trustformers_debug/
lib.rs

1//! # TrustformeRS Debug
2//!
3//! Advanced debugging tools for TrustformeRS models including tensor inspection,
4//! gradient debugging, and model diagnostics.
5
6// Allow ambiguous glob re-exports - documented below with clear guidance on which version to use
7#![allow(ambiguous_glob_reexports)]
8// Allow large error types in Result (TrustformersError is large by design)
9#![allow(clippy::result_large_err)]
10// Allow large enum variants (debug reports contain comprehensive data)
11#![allow(clippy::large_enum_variant)]
12// Allow common patterns in debugging/profiling code
13#![allow(clippy::too_many_arguments)]
14#![allow(clippy::type_complexity)]
15#![allow(clippy::excessive_nesting)]
16// Allow manual clamp pattern (.max().min()) - more explicit and doesn't panic on NaN
17#![allow(clippy::manual_clamp)]
18// Allow range loops for better readability in array indexing
19#![allow(clippy::needless_range_loop)]
20// Not all types need Default implementations
21#![allow(clippy::new_without_default)]
22// Style preferences for vec initialization
23#![allow(clippy::vec_init_then_push)]
24// Allow format! in format args for clarity
25#![allow(clippy::format_in_format_args)]
26// Empty lines after attributes are intentional for readability
27#![allow(clippy::empty_line_after_outer_attr)]
28#![allow(clippy::empty_line_after_doc_comments)]
29// Allow await holding lock in debug code where it's safe
30#![allow(clippy::await_holding_lock)]
31// Allow if-else with same body in debug code for clarity
32#![allow(clippy::if_same_then_else)]
33// Allow double-ended iterator last when it's clearer
34#![allow(clippy::double_ended_iterator_last)]
35// Allow manual strip for explicit string handling
36#![allow(clippy::manual_strip)]
37// Allow derivable impls when Default has complex semantics
38#![allow(clippy::derivable_impls)]
39// Allow needless question mark in debug code for clarity
40#![allow(clippy::needless_question_mark)]
41// Allow let_and_return for clarity in complex expressions
42#![allow(clippy::let_and_return)]
43// Allow field reassign with default in test code
44#![allow(clippy::field_reassign_with_default)]
45// Allow filter_map when pattern matching different variants
46#![allow(clippy::unnecessary_filter_map)]
47// Allow uppercase acronyms like LSTM, GPU, etc.
48#![allow(clippy::upper_case_acronyms)]
49// Allow never_loop in streaming code (intentional drain patterns)
50#![allow(clippy::never_loop)]
51
52// New visualization and analysis modules
53pub mod activation_visualizer;
54pub mod attention_visualizer;
55pub mod graph_visualizer;
56pub mod mlflow_integration;
57pub mod netron_export;
58pub mod performance_tuning;
59pub mod stability_checker;
60pub mod tensorboard_integration;
61pub mod unified_debug_session;
62pub mod visualization_plugins;
63pub mod weight_analyzer;
64
65pub mod advanced_gpu_profiler;
66pub mod advanced_ml_debugging;
67pub mod ai_code_analyzer;
68pub mod anomaly_detector;
69pub mod architecture_analysis;
70pub mod auto_debugger;
71pub mod behavior_analysis;
72pub mod cicd_integration;
73pub mod collaboration;
74pub mod computation_graph;
75pub mod dashboard;
76pub mod data_export;
77pub mod differential_debugging;
78pub mod distributed_debugger;
79pub mod distributed_profiling;
80pub mod environmental_monitor;
81pub mod error_recovery;
82pub mod flame_graph_profiler;
83pub mod gradient_debugger;
84pub mod health_checker;
85pub mod hooks;
86pub mod ide_integration;
87pub mod interactive_debugger;
88pub(crate) mod interpretability;
89pub mod interpretability_tools;
90pub mod kernel_optimizer;
91pub mod large_model_viz;
92pub mod llm_debugging;
93pub mod memory_profiler;
94pub mod model_diagnostics;
95pub mod model_diagnostics_main;
96pub use model_diagnostics_main::{ModelDiagnostics, ModelDiagnosticsReport};
97
98// Import specific types from model_diagnostics to avoid conflicts
99pub use model_diagnostics::{
100    ActivationHeatmap,
101    ActiveAlert,
102    // Advanced analytics
103    AdvancedAnalytics,
104    AlertConfig,
105    // Alert system
106    AlertManager,
107    AlertSeverity,
108    AlertStatistics,
109
110    AlertStatus,
111    AlertThresholds,
112    AnalyticsConfig,
113    AnalyticsReport,
114    AnomalyDetectionResults,
115    ArchitecturalAnalysis,
116    AttentionVisualization,
117    AutoDebugConfig,
118    // Auto-debugging system
119    AutoDebugger,
120    ConvergenceStatus,
121    DebuggingRecommendation,
122    DebuggingReport,
123    HiddenStateAnalysis,
124
125    IdentifiedIssue,
126    IssueCategory,
127    IssueSeverity,
128
129    LayerActivationStats,
130    LayerAnalysis,
131    LayerAnalysisConfig,
132
133    // Layer analysis (prefixed to avoid conflicts)
134    LayerAnalyzer,
135    ModelArchitectureInfo,
136    ModelDiagnosticAlert,
137    // Core types that don't conflict
138    ModelPerformanceMetrics,
139    OverfittingIndicator,
140    // Performance analysis (prefixed to avoid conflicts)
141    PerformanceAnalyzer,
142    PerformanceAnomaly,
143
144    PerformanceSummary,
145    PlateauInfo,
146    StatisticalAnalysis,
147    TrainingDynamics,
148    // Training analysis (prefixed to avoid conflicts)
149    TrainingDynamicsAnalyzer,
150
151    TrainingStability,
152    UnderfittingIndicator,
153    WeightDistribution,
154};
155pub mod neural_network_debugging;
156pub mod profiler;
157pub mod quantum_debugging;
158pub mod realtime_dashboard;
159pub mod regression_detector;
160pub mod report_generation;
161pub mod simulation_tools;
162pub mod streaming_debugger;
163pub mod team_dashboard;
164pub mod tensor_inspector;
165pub mod training_dynamics;
166pub mod utilities;
167pub mod visualization;
168#[cfg(feature = "wasm")]
169pub mod wasm_interface;
170
171/// Lock-free single-producer/multi-consumer ring buffer used by
172/// [`dashboard_ws`] to fan out live training events without an unbounded
173/// backlog. Was previously compiled (`mod ring_buffer;` was missing from
174/// this file) but never reachable from outside the crate, so its tests
175/// never ran; declared here rather than deleted since [`dashboard_ws`]
176/// depends on it and both are real, working implementations.
177pub mod ring_buffer;
178
179/// Trace-export formats for profiling data: Chrome/Perfetto JSON, Tracy
180/// CSV, and a unified CSV/JSON exporter. Re-exported under the `export`
181/// namespace (not glob-imported at the crate root) because its
182/// [`export::ExportFormat`] name collides with unrelated `ExportFormat`
183/// types already defined in [`data_export`] and [`netron_export`].
184pub mod export;
185
186/// Real-time training-event streaming over Server-Sent Events (SSE), with
187/// no third-party web-framework dependency. Re-exported under the
188/// `dashboard_ws` namespace (not glob-imported) because its
189/// [`dashboard_ws::DashboardConfig`] name collides with the crate's several
190/// other `DashboardConfig` types (see [`realtime_dashboard`],
191/// [`team_dashboard`]).
192pub mod dashboard_ws;
193
194/// Performance-regression detectors: baseline comparison
195/// ([`regression::RegressionDetector`]) plus streaming z-score/CUSUM
196/// change-point detection. Re-exported under the `regression` namespace
197/// (not glob-imported) because [`regression::RegressionDetector`] and
198/// [`regression::RegressionSeverity`] collide with the unrelated types of
199/// the same name in [`regression_detector`] (the crate's original,
200/// still-primary regression-detection module).
201pub mod regression;
202
203// GPU profiling imports (specific to avoid conflicts)
204pub use advanced_gpu_profiler::{
205    AdvancedGpuMemoryProfiler, AdvancedGpuProfilingConfig, CrossDeviceTransfer,
206    GpuMemoryAllocation, GpuMemoryType, HighImpactOptimization, KernelOptimizationSummaryReport,
207    MemoryAnalysisReport, MemoryFragmentationSnapshot,
208};
209
210// Kernel optimization imports (specific)
211pub use kernel_optimizer::{
212    KernelOptimizationAnalyzer, KernelOptimizationConfig, KernelOptimizationReport,
213    KernelProfileData,
214};
215
216// ============================================================================
217// New Visualization and Analysis Tools (TODO.md implementations)
218// ============================================================================
219
220// TensorBoard Integration
221pub use tensorboard_integration::{
222    create_graph_node, tensor_to_histogram_values, GraphDef, GraphNode as TensorBoardGraphNode,
223    HistogramEvent, ScalarEvent, TensorBoardWriter, TextEvent,
224};
225
226// Netron/ONNX Export
227pub use netron_export::{
228    AttributeValue, ExportFormat, GraphNode as NetronGraphNode, ModelGraph, ModelMetadata,
229    NetronExporter, NetronModel, TensorData, TensorInfo,
230};
231
232// Activation Visualizer
233pub use activation_visualizer::{
234    ActivationConfig, ActivationData, ActivationHeatmap as ActivationVisualizerHeatmap,
235    ActivationHistogram, ActivationStatistics, ActivationVisualizer,
236};
237
238// Attention Visualizer
239pub use attention_visualizer::{
240    AttentionAnalysis, AttentionFlow, AttentionHeatmap as AttentionVisualizerHeatmap,
241    AttentionType, AttentionVisualizer, AttentionVisualizerConfig, AttentionWeights, ColorScheme,
242};
243
244// Stability Checker
245pub use stability_checker::{
246    IssueKind, StabilityChecker, StabilityConfig, StabilityIssue, StabilitySummary,
247};
248
249// Graph Visualizer
250pub use graph_visualizer::{
251    ComputationGraph, GraphColorScheme, GraphEdge, GraphNode as GraphVisualizerNode,
252    GraphStatistics, GraphVisualizer, GraphVisualizerConfig, LayoutDirection,
253};
254
255// Unified Debug Session Manager
256pub use unified_debug_session::{SessionSummary, UnifiedDebugSession, UnifiedDebugSessionConfig};
257
258// Weight Analyzer
259pub use weight_analyzer::{
260    InitializationScheme, WeightAnalysis, WeightAnalyzer, WeightAnalyzerConfig, WeightHistogram,
261    WeightStatistics,
262};
263
264// MLflow Integration
265pub use mlflow_integration::{
266    ArtifactType, MLflowClient, MLflowConfig, MLflowDebugSession, MetricPoint, RunInfo, RunStatus,
267    TrackingMode,
268};
269
270// Visualization Plugin System
271pub use visualization_plugins::{
272    OutputFormat as PluginOutputFormat, PluginConfig, PluginManager, PluginMetadata, PluginResult,
273    VisualizationData, VisualizationPlugin,
274};
275
276// Performance Tuning
277pub use performance_tuning::{
278    Difficulty, HardwareType, ImpactEstimate, PerformanceSnapshot,
279    PerformanceSummary as TuningPerformanceSummary, PerformanceTuner, Priority, Recommendation,
280    RecommendationCategory, TunerConfig, TuningReport,
281};
282
283// ============================================================================
284// Module Re-exports
285// ============================================================================
286//
287// ⚠️  TYPE NAME CONFLICTS (Documented for clarity):
288// The following types are defined in multiple modules. The LAST import wins in Rust.
289// If you need a specific version, import directly from the module:
290//
291// - `LRScheduleType`: defined in `training_dynamics` (PRIMARY) and `advanced_ml_debugging`
292//   → Use `training_dynamics::LRScheduleType` for training schedules
293//   → Use `advanced_ml_debugging::LRScheduleType` for ML debugging contexts
294//
295// - `RiskLevel`: defined in `llm_debugging` (PRIMARY) and `advanced_ml_debugging`
296//   → Use `llm_debugging::RiskLevel` for LLM safety analysis
297//   → Use `advanced_ml_debugging::RiskLevel` for general ML risk assessment
298//
299// - `InteractionType`: defined in `simulation_tools` (PRIMARY) and `advanced_ml_debugging`
300//   → Use `simulation_tools::InteractionType` for simulation interactions
301//   → Use `advanced_ml_debugging::InteractionType` for ML component interactions
302//
303// - `BottleneckType`: defined in `profiler` (PRIMARY) and `advanced_ml_debugging`
304//   → Use `profiler::BottleneckType` for performance bottlenecks
305//   → Use `advanced_ml_debugging::BottleneckType` for ML-specific bottlenecks
306//
307// - `FeatureSensitivityAnalysis`: defined in `simulation_tools` (PRIMARY) and `advanced_ml_debugging`
308//   → Use `simulation_tools::FeatureSensitivityAnalysis` for simulation feature analysis
309//   → Use `advanced_ml_debugging::FeatureSensitivityAnalysis` for ML feature analysis
310//
311// - `RobustnessAssessment`: defined in `simulation_tools` (PRIMARY) and `advanced_ml_debugging`
312//   → Use `simulation_tools::RobustnessAssessment` for simulation robustness
313//   → Use `advanced_ml_debugging::RobustnessAssessment` for ML robustness
314//
315// - `PatternType`: defined in `memory_profiler` (PRIMARY) and `ai_code_analyzer`
316//   → Use `memory_profiler::PatternType` for memory allocation patterns
317//   → Use `ai_code_analyzer::PatternType` for code patterns
318//
319// - `IssueType`: defined in `auto_debugger` (PRIMARY) and `ai_code_analyzer`
320//   → Use `auto_debugger::IssueType` for debugging issues
321//   → Use `ai_code_analyzer::IssueType` for code analysis issues
322//
323// ============================================================================
324
325// Primary exports (order determines which type wins for ambiguous names)
326// Note: New visualization modules are explicitly imported above to avoid conflicts
327pub use advanced_ml_debugging::*;
328pub use ai_code_analyzer::*;
329pub use anomaly_detector::*;
330pub use architecture_analysis::*;
331pub use auto_debugger::*;
332pub use behavior_analysis::*;
333pub use cicd_integration::*;
334pub use collaboration::*;
335pub use computation_graph::*;
336pub use dashboard::*;
337pub use data_export::*;
338pub use differential_debugging::*;
339pub use distributed_debugger::*;
340pub use distributed_profiling::*;
341pub use environmental_monitor::*;
342pub use error_recovery::*;
343pub use flame_graph_profiler::*;
344pub use gradient_debugger::*;
345pub use health_checker::*;
346pub use hooks::*;
347pub use ide_integration::*;
348pub use interactive_debugger::*;
349pub use large_model_viz::*;
350pub use llm_debugging::*;
351pub use memory_profiler::*;
352pub use model_diagnostics::*;
353pub use neural_network_debugging::*;
354pub use profiler::*;
355pub use quantum_debugging::*;
356pub use realtime_dashboard::{AlertSeverity as DashboardAlertSeverity, *};
357pub use regression_detector::*;
358pub use report_generation::*;
359pub use simulation_tools::*;
360pub use streaming_debugger::*;
361pub use team_dashboard::*;
362pub use tensor_inspector::*;
363pub use training_dynamics::*; // LRScheduleType from here is PRIMARY
364pub use utilities::*;
365pub use visualization::*;
366#[cfg(feature = "wasm")]
367pub use wasm_interface::*;
368
369use scirs2_core::ndarray::ArrayD; // SciRS2 Integration Policy
370
371// ============================================================================
372// NEW MODULAR ARCHITECTURE
373// ============================================================================
374
375/// Core debugging session and configuration management
376pub mod core;
377
378/// Simplified debugging interface with one-line functions
379pub mod interface;
380
381/// Guided debugging system with step-by-step workflows
382pub mod guided;
383
384/// Interactive tutorial and learning system
385pub mod tutorial;
386
387/// Context-aware help system
388pub mod help;
389
390/// Performance optimization system for production debugging
391pub mod performance;
392
393// Re-export all public items from modules for backward compatibility
394pub use core::*;
395pub use guided::*;
396pub use help::*;
397pub use interface::*;
398pub use performance::*;
399pub use tutorial::*;
400
401// Interpretability types (real implementations from interpretability_tools module)
402pub use interpretability_tools::{
403    InterpretabilityAnalyzer, InterpretabilityConfig, InterpretabilityReport,
404};
trustformers_debug/lib.rs

trustformers_debug/
lib.rs
