Skip to main content

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