cbtop/
lib.rs

1//! cbtop - Compute Block Top
2//!
3//! Real-time load testing and hardware monitoring TUI built on the Brick Architecture.
4//!
5// Allow new_without_default - explicit new() is clearer for these types
6#![cfg_attr(test, allow(clippy::disallowed_methods, clippy::float_cmp))]
7#![allow(clippy::new_without_default)]
8// Allow derivable_impls - explicit Default is clearer
9#![allow(clippy::derivable_impls)]
10// Allow missing_panics_doc - not critical for internal methods
11#![allow(clippy::missing_panics_doc)]
12// Allow missing_errors_doc - errors are self-explanatory
13#![allow(clippy::missing_errors_doc)]
14// Allow unnecessary_map_or - map_or is clearer
15#![allow(clippy::unnecessary_map_or)]
16// Allow collapsible_if - clarity over conciseness
17#![allow(clippy::collapsible_if)]
18// Allow needless_range_loop - clearer in some cases
19#![allow(clippy::needless_range_loop)]
20// Allow cast_precision_loss - acceptable for display values
21#![allow(clippy::cast_precision_loss)]
22// Allow cast_possible_truncation - handled appropriately
23#![allow(clippy::cast_possible_truncation)]
24// Allow dead_code - development in progress
25#![allow(dead_code)]
26// Allow field_reassign_with_default - clearer initialization
27#![allow(clippy::field_reassign_with_default)]
28// Allow manual_flatten - clearer error handling
29#![allow(clippy::manual_flatten)]
30//!
31//! # Design Philosophy
32//!
33//! - **Test-as-Interface**: Every component is a falsifiable Brick (PROBAR-SPEC-009)
34//! - **presentar-terminal**: All widgets and canvas from presentar-terminal (no custom reimplementation)
35//! - **Toyota Way**: Jidoka, Poka-Yoke, Genchi Genbutsu principles throughout
36//!
37//! # Architecture
38//!
39//! ```text
40//! Layer 4: Load Generators  → SimdLoadBrick, CudaLoadBrick, WgpuLoadBrick
41//! Layer 3: Panels           → Overview, CPU, GPU, PCIe, Memory, Thermal
42//! Layer 2: Analyzers        → Throughput, Bottleneck, Thermal
43//! Layer 1: Collectors       → CPU, GPU, PCIe, Memory, Thermal
44//! ```
45//!
46//! # Widget Source Policy
47//!
48//! All widgets and canvas implementations come from `presentar-terminal`.
49//! cbtop does NOT implement its own widgets. If a widget is missing, it MUST
50//! be added to presentar-terminal FIRST, then used here.
51
52pub mod adaptive_ml;
53pub mod adaptive_threshold;
54pub mod adversarial;
55pub mod alerting;
56pub mod anomaly_detection;
57pub mod app;
58pub mod backend_regression;
59pub mod baseline;
60pub mod brick;
61pub mod bricks;
62pub mod cache_analysis;
63pub mod config;
64pub mod context_regression;
65pub mod continuous_batcher;
66pub mod correlation_analysis;
67pub mod cost_tracker;
68pub mod double_blind;
69pub mod error;
70pub mod event_streaming;
71pub mod export_reporting;
72pub mod federated_metrics;
73pub mod frequency_control;
74pub mod fuzz;
75pub mod golden_trace;
76pub mod grammar;
77pub mod headless;
78pub mod incremental_snapshot;
79pub mod ironman;
80pub mod latency_distribution;
81pub mod observability_backend;
82pub mod optimize;
83pub mod paged_kv;
84pub mod performance_prediction;
85pub mod predictive_scheduler;
86pub mod profile_compare;
87pub mod profile_persistence;
88pub mod prometheus;
89pub mod quantize;
90pub mod regression_pipeline;
91pub mod remote_agent;
92pub mod ring_buffer;
93pub mod roofline;
94pub mod statistics;
95pub mod thermal_prediction;
96pub mod tracing_escalation;
97pub mod variance_analysis;
98pub mod workload_characterization;
99
100// Core brick traits (cbtop-specific)
101pub use brick::{Brick, BrickAssertion, BrickBudget, BrickVerification};
102// ComputeBrick Scoring Framework (§29)
103pub use brick::{BrickGrade, BrickScore, Scorable};
104// CORRECTNESS-011: Per-kernel divergence detection
105pub use brick::{fnv1a_f32, BrickProfiler, DivergenceReport, KernelTrace};
106
107// Application
108pub use app::CbtopApp;
109pub use config::Config;
110pub use error::CbtopError;
111
112// Headless benchmarking API (HL-007)
113pub use headless::{
114    Benchmark, BenchmarkBuilder, BenchmarkConfig, BenchmarkResult, BenchmarkResults,
115    ComparisonResult, LatencyStats, OutputFormat, RegressionResult, ScoreInfo, SystemInfo,
116};
117// Re-export config types for benchmark builder
118pub use config::{ComputeBackend, WorkloadType};
119
120// Optimization tooling (OPT-001 to OPT-004)
121pub use optimize::{
122    AnalysisSummary, BaselineEntry, BaselineReport, BottleneckAnalysis, BottleneckEntry,
123    BottleneckSeverity, CpuCapabilities, OptimizationSuite, OptimizationValidator,
124    RegressionDetector, RegressionEntry, RegressionReport, ValidationResult, WorkloadConfig,
125};
126
127// Industry Baseline Validation (PMAT-016)
128pub use baseline::{
129    BaselineComparison, BaselineValidator, GpuClass, ServerBaseline, SingleComparison, SmHealth,
130    ThroughputGrade, ValidationSummary, INDUSTRY_BASELINES, TGI_BASELINE, TRITON_BASELINE,
131    VLLM_BASELINE,
132};
133
134// Quantized Weight Support (PMAT-013)
135pub use quantize::{
136    ggml_type_to_format, DequantStrategy, GgufError, GgufHeader, GgufLoader, GgufResult,
137    GgufTensorInfo, GgufValue, LayerQuantStats, QuantFormat, QuantStats, QuantizedBrick,
138    QuantizedWeights,
139};
140
141// Paged KV Cache (PMAT-014)
142pub use paged_kv::{
143    BlockId, CacheStats, EvictionStrategy, KvBlock, PagedKvCache, PagedKvError, PagedKvResult,
144    SeqId, SequenceInfo,
145};
146
147// Continuous Batcher (PMAT-015)
148pub use continuous_batcher::{
149    BatchSchedule, BatcherStats, ContinuousBatcher, ExponentialMovingAverage, InferenceRequest,
150    Priority, SchedulingPolicy, SequenceGroup, SpeculativeDecoder, SpeculativeOutput, Token,
151    TokenOutput,
152};
153
154// Ironman Falsification Suite (PMAT-017)
155pub use ironman::{
156    full_validate, quick_validate, GateCategory, GateResult, IronmanScorecard, IronmanValidator,
157    QualityGate, IRONMAN_GATES,
158};
159
160// Grammar of ComputeBlock (PMAT-018)
161pub use grammar::{
162    BuiltComputeBlock, ByteSize, CompositionMode, ComputeBlock, ComputeBlockBuilder, CpuAffinity,
163    DataTransform, DataType, Dimensions, ExecutionContext, ExecutionPolicy, ExecutionResult,
164    ExecutionStrategy, GpuDevice, GrammarError, GrammarResult, KernelSpec, LinearResourceScale,
165    LogResourceScale, ObservabilityConfig, Operation, QosLevel, QuantScheme, ResourceLimits,
166    ResourceMapping, ResourceScale, RetryPolicy, ScaleBinding, SimdWidth, StrategyLayer,
167    TensorSpec, WorkloadSpec,
168};
169
170// Adversarial Falsification Testing (PMAT-019)
171pub use adversarial::{
172    AdversarialError, AdversarialResult, AdversarialTactic, AdversarialTestSummary,
173    BitFlipInjector, CancellationToken, CheckedArithmetic, ConfigValidator, InputValidator,
174    MonotonicClock, RecoveryHandler, ResourceLimiter, ResourceUsage,
175};
176
177// Double-Blind Verification Framework (PMAT-020)
178pub use double_blind::{
179    AuditEntry, BlackBoxArtifact, FalsificationClaim, FalsificationCriterion, ReleaseDecision,
180    Role, ScorecardComponent, ScorecardV2, SessionState, VerificationAttempt, VerificationReport,
181    VerificationResult, VerificationSession,
182};
183
184// Tracing Escalation Framework (PMAT-021)
185pub use tracing_escalation::{
186    EscalationReason, EscalationThresholds, OtlpSpanAttributes, SyscallBreakdown, TraceResult,
187    TracingEscalation,
188};
189
190// Roofline Model Analyzer (PMAT-022)
191pub use roofline::{
192    BatchRooflineAnalysis, BatchSummary, BottleneckType, HardwareProfile, RooflineAnalysis,
193    RooflinePlot, RooflinePlotPoint, WorkloadMetrics,
194};
195
196// Fuzz Testing Integration (PMAT-023)
197pub use fuzz::{
198    bound_value, checked_add_u64, checked_mul_u64, safe_div, sanitize_float, test_float_edge_cases,
199    test_u64_edge_cases, FuzzFailure, FuzzInputValidator, FuzzResult, FuzzSuite, FuzzSummary,
200    FuzzTargetConfig, FuzzValidationError,
201};
202
203// Statistical Analysis (PMAT-024)
204pub use statistics::{
205    bootstrap_ci, percentile, trimmed_mean, ComparisonResult as StatisticalComparison,
206    EffectCategory, EffectSize, MannWhitneyResult, OutlierFilter, StatisticalAnalysis,
207};
208
209// Cache Efficiency Analysis (PMAT-025)
210pub use cache_analysis::{
211    elementwise_working_set, matrix_working_set, optimal_matmul_tile, AccessPattern,
212    BandwidthPrediction, CacheConfig, CacheLevel, WorkingSetAnalysis,
213};
214
215// Latency Distribution Analysis (PMAT-026)
216pub use latency_distribution::{
217    DistributionShape, HistogramBucket, LatencyDistribution, LatencyHistogram, TailSeverity,
218};
219
220// Variance Source Analysis (PMAT-027)
221pub use variance_analysis::{VarianceAnalysis, VarianceInput, VarianceSource};
222
223// Profile Persistence and Rotation (PMAT-028)
224pub use profile_persistence::{
225    BackendConfig as ProfileBackend, ProfileConfig, ProfileError, ProfileManager, ProfileOverlay,
226    ProfileResult, WorkloadConfig as ProfileWorkload,
227};
228
229// Golden Trace Comparison (PMAT-029)
230pub use golden_trace::{
231    GoldenComparator, GoldenTrace, GoldenTraceError, GoldenTraceManager, GoldenTraceResult,
232    SyscallBreakdown as TraceSyscallBreakdown, SyscallBreakdownDelta, TraceComparison,
233    TraceMetrics,
234};
235
236// Thermal Trend Prediction (PMAT-030)
237pub use thermal_prediction::{
238    analyze_thermal, assess_throttle_risk, CooldownRecommendation, RiskCategory, ThermalAnalyzer,
239    ThermalCorrelation, ThermalPrediction, ThermalSample, ThermalVariance, ThrottleRisk,
240    DEFAULT_THROTTLE_THRESHOLD_C, MIN_SAMPLES_FOR_ANALYSIS,
241};
242
243// Cross-Backend Regression Detector (PMAT-031)
244pub use backend_regression::{
245    Backend, BackendComparison, BackendMeasurement, BackendRecommendation,
246    BackendRegressionDetector, BackendSummary, SizeCliff, TransferAnalysis,
247    WorkloadType as BackendWorkload,
248};
249
250// Multi-Metric Correlation Analysis (PMAT-032)
251pub use correlation_analysis::{
252    CorrelationAnalyzer, CorrelationResult, EventSample, EventType, InterferenceCategory,
253    InterferenceResult, IsolationAction, IsolationRecommendation, PerformanceSample,
254    SystemSnapshot,
255};
256
257// Performance Prediction Model (PMAT-033)
258pub use performance_prediction::{
259    DataPoint, FittedModel, ModelType, PerformancePredictor, Prediction, MIN_SAMPLES_FOR_FIT,
260};
261
262// Anomaly Detection Engine (PMAT-034)
263pub use anomaly_detection::{
264    Anomaly, AnomalyDetector, AnomalyReport, AnomalySeverity, AnomalyType, ChangePoint,
265    DEFAULT_IQR_MULTIPLIER, DEFAULT_ZSCORE_THRESHOLD, MIN_SAMPLES_FOR_DETECTION,
266};
267
268// Workload Characterization System (PMAT-035)
269pub use workload_characterization::{
270    ClassificationResult, RecommendedBackend, WorkloadCategory, WorkloadCharacterizer,
271    WorkloadFeatures,
272};
273
274// Multi-Format Export System (PMAT-036)
275pub use export_reporting::{
276    BenchmarkMetric, BenchmarkReport, ComparisonEntry, ComparisonReport, ExportFormat,
277    ReportBuilder, ReportExporter, ReportType,
278};
279
280// Adaptive Threshold Learning System (PMAT-037)
281pub use adaptive_threshold::{
282    LearnedThreshold, ThresholdCheck, ThresholdDirection, ThresholdLearner,
283    DEFAULT_CONFIDENCE_LEVEL, DEFAULT_OUTLIER_THRESHOLD, MIN_SAMPLES_FOR_LEARNING,
284};
285
286// CPU Frequency Control Backend (PMAT-038)
287pub use frequency_control::{
288    CpuFrequencyInfo, CpuGovernor, FrequencyController, FrequencyLock, FrequencyReading,
289    FrequencyVariance,
290};
291
292// Context-Aware Regression Predictor (PMAT-039)
293pub use context_regression::{
294    BaselineEntry as ContextBaselineEntry, ContextRegressionPredictor, RegressionCheck,
295    RegressionThreshold, SystemContext, Trend, DEFAULT_COLD_START_MARGIN, DEFAULT_STALENESS_SEC,
296    MIN_SAMPLES_FOR_CONTEXT,
297};
298
299// Real-Time Alert Integration System (PMAT-040)
300pub use alerting::{
301    alert_from_anomaly, Alert, AlertChannel, AlertRouter, AlertRouterConfig, AlertSeverity,
302    DeliveryResult, MessageTemplate,
303};
304
305// Prometheus Metrics Exporter (PMAT-041)
306pub use prometheus::{
307    validate_metric_name, CounterValue, GaugeValue, HistogramBuckets, HistogramValue, Labels,
308    MetricDef, MetricType, MetricsRegistry, DEFAULT_BUCKETS, DEFAULT_MAX_LABELS,
309};
310
311// Cost and Energy Efficiency Tracker (PMAT-042)
312pub use cost_tracker::{
313    default_gpu_pricing, BudgetAlert, CloudProvider, CostComparison, CostResult, CostTracker,
314    EnergyMeasurement, GpuPricing, DEFAULT_CARBON_INTENSITY, JOULES_PER_KWH,
315};
316
317// Structured Event Streaming (PMAT-043)
318pub use event_streaming::{
319    compress_data, event_from_sample, EventBatch, EventStreamer, MetricEvent, RetryConfig,
320    SinkHealth, SinkType, DEFAULT_BATCH_SIZE, SCHEMA_VERSION,
321};
322
323// Remote SSH/Headless Agent Integration (PMAT-044)
324pub use remote_agent::{
325    AggregatedResult, AggregationStrategy, AuthMethod, CommandResult, HostBenchmark, HostConfig,
326    HostHealth, HostState, RemoteAgent, RemoteAgentConfig, RemoteError, RemoteResult,
327    DEFAULT_HEALTH_CHECK_INTERVAL_SEC, DEFAULT_MAX_CONCURRENT, DEFAULT_RETRY_DELAY_MS,
328};
329
330// Profile Diffing and A/B Comparison (PMAT-045)
331pub use profile_compare::{
332    BenchmarkProfile, ChangeDirection, CompareConfig, CompareError, CompareResult,
333    ComparisonVerdict, EffectMagnitude, EffectSizeResult, MetricComparison, MetricSamples,
334    ProfileComparator, ProfileComparison, WelchTestResult,
335    DEFAULT_CONFIDENCE_LEVEL as COMPARE_DEFAULT_CONFIDENCE_LEVEL,
336    DEFAULT_REGRESSION_THRESHOLD as COMPARE_DEFAULT_REGRESSION_THRESHOLD, MIN_COMPARISON_SAMPLES,
337};
338
339// Observability Backend Integrations (PMAT-046)
340pub use observability_backend::{
341    format_dogstatsd, BackendHealth, DatadogConfig, ExportMetric, ExportResult, HoneycombConfig,
342    MetricExportType, NewRelicConfig, ObservabilityBackend,
343    ObservabilityConfig as ObsBackendConfig, ObservabilityError, ObservabilityExporter,
344    ObservabilityResult, OtlpConfig, WebhookConfig, DEFAULT_BATCH_SIZE as OBS_DEFAULT_BATCH_SIZE,
345    DEFAULT_FLUSH_INTERVAL_MS,
346};
347
348// CI/CD Regression Detection Pipeline (PMAT-047)
349pub use regression_pipeline::{
350    BenchmarkMetric as PipelineBenchmarkMetric, BenchmarkResults as PipelineBenchmarkResults,
351    GitRef, MetricRegression, PipelineConfig, PipelineError, PipelineResult, PipelineStatus,
352    RegressionAnalysis, RegressionPipeline, StatusCheck,
353    DEFAULT_REGRESSION_THRESHOLD as PIPELINE_REGRESSION_THRESHOLD, DEFAULT_TIMEOUT_SEC,
354    DEFAULT_WARNING_THRESHOLD,
355};
356
357// Federated Metrics Aggregation (PMAT-048)
358pub use federated_metrics::{
359    AggregatedMetrics, FederatedHost, FederationConfig, GCounter, LwwRegister, MetricsFederation,
360    OrSet,
361};
362
363// Dynamic Adaptive Thresholds with ML (PMAT-049)
364pub use adaptive_ml::{
365    AdaptiveThresholdMl, AnomalyResult as MlAnomalyResult,
366    ClassificationMetrics as MlClassificationMetrics, LearnedWorkloadThreshold, MlThresholdConfig,
367    MlThresholdError, TimeSeriesFeatures, WorkloadClass,
368};
369
370// Incremental Profile Snapshots (PMAT-050)
371pub use incremental_snapshot::{
372    DeltaMetric, DeltaSnapshot, IncrementalSnapshotStore, MetricData, ProfileSnapshot,
373    RetentionTier, SnapshotConfig, SnapshotError, SnapshotIndex, SnapshotQuery,
374};
375
376// Predictive Scheduling Optimizer (PMAT-051)
377pub use predictive_scheduler::{
378    HostProfile, InstanceType, PredictiveScheduler, PredictiveSchedulerConfig, SchedulerMetrics,
379    SchedulingDecision, WorkloadSpec as SchedulerWorkloadSpec,
380};
381
382// Re-export presentar-terminal widgets and canvas for convenience
383// All widgets MUST come from presentar-terminal - DO NOT reimplement
384pub use presentar_terminal::direct::{CellBuffer, DiffRenderer, DirectTerminalCanvas};
385pub use presentar_terminal::{BrailleGraph, ColorMode, GraphMode, Meter, Table};
386
387// Re-export presentar-core traits
388pub use presentar_core::{Canvas, Color, Constraints, Point, Rect, Size, TextStyle};
cbtop/lib.rs

cbtop/
lib.rs
