## Coverage Report

#### Created: 2026-01-25 15:05

next uncovered line (L), next uncovered region (R), next uncovered branch (B)

    /home/noah/src/realizar/src/lib.rs

    Line
    Count
    Source
    1
    //! # Realizar
    2
    //!
    3
    //! Pure Rust, portable, high-performance ML library with unified CPU/GPU/WASM support.
    4
    //!
    5
    //! Realizar (Spanish: "to accomplish, to achieve") provides a unified API for machine learning
    6
    //! operations that automatically dispatches to the optimal backend based on data size,
    7
    //! operation complexity, and available hardware.
    8
    //!
    9
    //! ## Features
    10
    //!
    11
    //! - **Unified API**: Single interface for CPU SIMD, GPU, and WASM execution
    12
    //! - **Native Integration**: First-class support for `trueno` and `aprender`
    13
    //! - **Memory Safe**: Zero unsafe code in public API, leveraging Rust's type system
    14
    //! - **Production Ready**: EXTREME TDD, 85%+ coverage, zero tolerance for defects
    15
    //!
    16
    //! ## Example
    17
    //!
    18
    //! ```rust
    19
    //! use realizar::Tensor;
    20
    //!
    21
    //! // Create tensors
    22
    //! let a = Tensor::from_vec(vec![3, 3], vec![
    23
    //!     1.0, 2.0, 3.0,
    24
    //!     4.0, 5.0, 6.0,
    25
    //!     7.0, 8.0, 9.0,
    26
    //! ]).expect("test");
    27
    //!
    28
    //! // Check tensor properties
    29
    //! assert_eq!(a.shape(), &[3, 3]);
    30
    //! assert_eq!(a.ndim(), 2);
    31
    //! assert_eq!(a.size(), 9);
    32
    //! ```
    33
    //!
    34
    //! ## Future Operations (Phase 1+)
    35
    //!
    36
    //! ```rust,ignore
    37
    //! // Element-wise operations (SIMD-accelerated) - Coming in Phase 1
    38
    //! let sum = a.add(&b).expect("test");
    39
    //!
    40
    //! // Matrix multiplication (GPU-accelerated for large matrices) - Coming in Phase 2
    41
    //! let product = a.matmul(&b).expect("test");
    42
    //! ```
    43
    //!
    44
    //! ## Architecture
    45
    //!
    46
    //! Realizar is built on top of:
    47
    //! - **Trueno**: Low-level compute primitives with SIMD/GPU/WASM backends
    48
    //! - **Aprender**: High-level ML algorithms (will be refactored to use Realizar)
    49
    //!
    50
    //! ## Quality Standards
    51
    //!
    52
    //! Following EXTREME TDD methodology:
    53
    //! - Test Coverage: ≥85%
    54
    //! - Mutation Score: ≥80%
    55
    //! - TDG Score: ≥90/100
    56
    //! - Clippy Warnings: 0 (enforced)
    57
    //! - Cyclomatic Complexity: ≤10 per function
    58
    59
    #![deny(missing_docs)]
    60
    #![deny(clippy::all)]
    61
    #![warn(clippy::pedantic)]
    62
    // Multiple crate versions are acceptable for dependencies
    63
    // #![warn(clippy::cargo)]
    64
    65
    // Clippy allows (MUST come after deny/warn to override them)
    66
    #![allow(clippy::module_name_repetitions)]
    67
    #![allow(clippy::large_stack_arrays)] // Test data
    68
    #![allow(clippy::cast_possible_wrap)] // u64 -> i64 for timestamps is safe
    69
    #![allow(clippy::cast_precision_loss)] // usize -> f32 precision loss is acceptable
    70
    #![allow(clippy::cast_possible_truncation)] // u128 -> u64 etc for metrics is safe
    71
    #![allow(clippy::cast_sign_loss)] // Metrics conversions are safe
    72
    #![allow(clippy::too_many_lines)] // Some handlers are naturally long
    73
    #![allow(clippy::must_use_candidate)] // Not all methods need #[must_use]
    74
    #![allow(clippy::doc_markdown)] // Allow technical terms without backticks
    75
    #![allow(clippy::redundant_clone)] // Sometimes clarity > performance
    76
    #![allow(clippy::uninlined_format_args)] // Prefer explicit format args
    77
    #![allow(clippy::single_match_else)] // Sometimes clearer than if-let
    78
    #![allow(clippy::unnecessary_to_owned)] // Allow explicit .to_string()
    79
    #![allow(clippy::single_char_pattern)] // Allow "x" instead of 'x' in contains()
    80
    #![allow(clippy::missing_panics_doc)] // Allow missing Panics doc sections
    81
    #![allow(clippy::missing_errors_doc)] // Allow missing Errors doc sections (common in math code)
    82
    #![allow(clippy::items_after_statements)] // Allow const/type definitions after statements
    83
    #![allow(clippy::unused_self)] // Allow unused self in methods for API consistency
    84
    #![allow(clippy::cloned_instead_of_copied)] // Allow cloned() even for Copy types
    85
    #![allow(clippy::needless_pass_by_value)] // Allow pass-by-value where it's clearer
    86
    #![allow(clippy::unnecessary_wraps)] // Allow wrapping in Result/Option for API consistency
    87
    #![allow(clippy::if_not_else)] // Allow if !condition { } else { }
    88
    #![allow(clippy::manual_let_else)] // Allow manual let-else patterns
    89
    #![allow(clippy::float_cmp)] // Allow float comparisons in tests
    90
    #![allow(clippy::cast_lossless)] // Allow i32 to f64 casts
    91
    #![allow(clippy::approx_constant)] // Allow approximate PI
    92
    #![allow(clippy::manual_range_contains)] // Allow manual range checks
    93
    #![allow(clippy::same_item_push)] // Allow pushing same items in tests
    94
    #![allow(clippy::similar_names)] // Allow similar variable names in test code
    95
    #![allow(clippy::unreadable_literal)] // Allow literals without separators in test code
    96
    #![allow(clippy::useless_vec)] // Allow vec![] where slice would work in tests
    97
    #![allow(clippy::ignore_without_reason)] // Allow #[ignore] without explicit reason
    98
    #![allow(clippy::cast_ptr_alignment)] // Allow unaligned SIMD pointer casts (loadu/storeu are safe)
    99
    #![allow(clippy::ptr_as_ptr)] // Allow pointer cast style in SIMD code
    100
    #![allow(clippy::struct_excessive_bools)] // Allow structs with multiple bool fields
    101
    #![allow(clippy::match_same_arms)] // Allow match arms with same bodies for clarity
    102
    #![allow(clippy::assertions_on_constants)] // Allow assert!(true) in tests
    103
    #![allow(clippy::format_push_string)] // Allow format! with push_str for clarity
    104
    #![allow(clippy::upper_case_acronyms)] // Allow VLLM, APR, GGUF, ONNX etc.
    105
    #![allow(clippy::struct_field_names)] // Allow field names with common suffix (_ms, _hash)
    106
    #![allow(clippy::if_same_then_else)] // Allow if/else with same block for clarity
    107
    #![allow(clippy::format_collect)] // Allow map().collect() with format! inside
    108
    #![allow(clippy::no_effect_underscore_binding)] // Allow underscore-prefixed bindings
    109
    #![allow(clippy::too_many_arguments)] // Allow functions with >7 args
    110
    #![allow(clippy::needless_range_loop)] // Allow for i in 0..len style loops
    111
    #![allow(clippy::trivially_copy_pass_by_ref)] // Allow &self on small Copy types
    112
    #![allow(clippy::used_underscore_items)] // Allow using _prefixed items
    113
    #![allow(clippy::field_reassign_with_default)] // Allow field reassign after default
    114
    #![allow(dead_code)] // Allow unused fields/variants in test structs
    115
    116
    #[cfg(feature = "server")]
    117
    pub mod api;
    118
    /// Aprender .apr format support (PRIMARY inference format)
    119
    ///
    120
    /// The .apr format is the native format for the sovereign AI stack.
    121
    /// GGUF and safetensors are supported as fallback formats.
    122
    pub mod apr;
    123
    /// APR Transformer format for WASM-compatible LLM inference
    124
    ///
    125
    /// Provides F32 transformer weights for fair APR vs GGUF comparison.
    126
    /// Designed for WASM compatibility - no SIMD requirements.
    127
    pub mod apr_transformer;
    128
    /// Audit trail and provenance logging
    129
    ///
    130
    /// Per spec §12: Comprehensive audit record for every inference request.
    131
    /// Implements GDPR Article 13/14 and SOC 2 compliance requirements.
    132
    /// - Full provenance tracking (model hash, distillation lineage)
    133
    /// - Latency breakdown (preprocessing, inference, postprocessing)
    134
    /// - Quality gates (Jidoka: NaN check, confidence check)
    135
    pub mod audit;
    136
    /// Benchmark harness for model runner comparison
    137
    ///
    138
    /// Implements the benchmark specification v1.1 with Toyota Way engineering principles:
    139
    /// - Dynamic CV-based stop-rule (Hoefler & Belli)
    140
    /// - Thermal throttling protocol
    141
    /// - ITL variance measurement
    142
    /// - KV-cache fragmentation detection
    143
    /// - KL-Divergence quality validation
    144
    pub mod bench;
    145
    /// Preflight validation protocol for deterministic benchmarking
    146
    ///
    147
    /// Per spec v1.0.1, implements Toyota Way principles:
    148
    /// - Jidoka: Fail-fast validation, stop on anomaly
    149
    /// - Poka-yoke: Error-proofing through type-safe configurations
    150
    /// - Genchi Genbutsu: Verify actual system state
    151
    ///
    152
    /// References:
    153
    /// - Hoefler & Belli SC'15: CV-based stopping
    154
    /// - Vitek & Kalibera EMSOFT'11: Reproducibility requirements
    155
    pub mod bench_preflight;
    156
    /// Benchmark visualization for inference comparison (PAR-040)
    157
    ///
    158
    /// Creates 2×3 grid visualizations comparing APR vs Ollama vs llama.cpp
    159
    /// and generates profiling logs suitable for chat paste debugging.
    160
    pub mod bench_viz;
    161
    /// ComputeBrick architecture for token-centric, self-verifying inference
    162
    ///
    163
    /// Per spec: Qwen2.5-Coder Showcase Demo v3.0.0
    164
    /// Implements 5-layer brick hierarchy with Toyota Way engineering:
    165
    /// - Jidoka: Every brick has stop-the-line assertions
    166
    /// - Poka-Yoke: Token budgets enforce performance contracts
    167
    /// - Genchi Genbutsu: Statistical benchmarking with CV < 5%
    168
    /// - Mieruka: Visual progress via TUI integration
    169
    pub mod brick;
    170
    pub mod cache;
    171
    /// Chat template engine for model-specific message formatting
    172
    ///
    173
    /// Supports ChatML (Qwen2, Yi), LLaMA2 (TinyLlama, Vicuna),
    174
    /// Mistral, Phi, Alpaca, and Raw formats.
    175
    /// Auto-detects format from model name.
    176
    pub mod chat_template;
    177
    /// CLI command implementations (extracted for testability)
    178
    pub mod cli;
    179
    /// GGUF to APR Transformer converter
    180
    ///
    181
    /// Converts GGUF models to APR format for fair comparison.
    182
    /// All weights are dequantized to F32 for WASM compatibility.
    183
    pub mod convert;
    184
    /// CUDA PTX generation for NVIDIA GPUs
    185
    ///
    186
    /// Provides native CUDA kernel generation and execution via trueno-gpu.
    187
    /// - Pure Rust PTX generation (no LLVM, no nvcc)
    188
    /// - Hand-optimized kernels: GEMM, Softmax, LayerNorm, Attention, Q4K
    189
    /// - FlashAttention-style tiled attention
    190
    /// - Full CUDA runtime via trueno-gpu driver (context, stream, memory)
    191
    #[cfg(feature = "cuda")]
    192
    #[allow(
    193
        clippy::borrow_as_ptr,
    194
        clippy::ptr_as_ptr,
    195
        clippy::many_single_char_names,
    196
        clippy::manual_div_ceil
    197
    )]
    198
    pub mod cuda;
    199
    pub mod error;
    200
    /// Model explainability (SHAP, Attention)
    201
    ///
    202
    /// Per spec §13: Model explainability for APR classical ML models.
    203
    /// Implements SHAP TreeExplainer for tree ensembles and KernelSHAP for any model.
    204
    /// - TreeSHAP: O(TLD) complexity for tree-based models
    205
    /// - KernelSHAP: Model-agnostic with weighted linear regression
    206
    /// - Feature importance: Top-k features by absolute SHAP value
    207
    pub mod explain;
    208
    /// Unified model format detection (APR, GGUF, SafeTensors)
    209
    ///
    210
    /// Per spec §3: Format Support Matrix - auto-detect from magic bytes.
    211
    /// APR is first-class, GGUF and SafeTensors are backwards-compatible.
    212
    pub mod format;
    213
    pub mod generate;
    214
    pub mod gguf;
    215
    /// GPU acceleration module (Phase 4: ≥100 tok/s target)
    216
    ///
    217
    /// Implements GPU-accelerated matrix operations via Trueno's wgpu backend.
    218
    /// - GPU matmul shader for large matrix multiplications
    219
    /// - Hybrid CPU/GPU scheduling based on workload size
    220
    /// - Automatic fallback to SIMD when GPU unavailable
    221
    #[cfg(feature = "gpu")]
    222
    #[allow(clippy::similar_names)] // GPU code has intentionally similar kv_head/k_head names
    223
    pub mod gpu;
    224
    /// Grammar-constrained generation for structured output
    225
    ///
    226
    /// Implements GBNF-style grammar constraints for LLM generation.
    227
    /// - JSON schema validation
    228
    /// - Custom grammar rules (GBNF format)
    229
    /// - Token masking for efficient constrained generation
    230
    /// - State machine for tracking grammar state
    231
    pub mod grammar;
    232
    /// HTTP client for real model server benchmarking
    233
    ///
    234
    /// Implements actual HTTP calls to external servers (vLLM, Ollama, llama.cpp).
    235
    /// **NO MOCK DATA** - measures real network latency and inference timing.
    236
    #[cfg(feature = "bench-http")]
    237
    pub mod http_client;
    238
    /// High-level inference API for CLI tools
    239
    ///
    240
    /// Per spec APR-CLI-DELEGATE-001: All inference in `apr run` and `apr chat`
    241
    /// delegates to this module. This eliminates ~1800 lines of duplicated code.
    242
    ///
    243
    /// # Example
    244
    ///
    245
    /// ```rust,ignore
    246
    /// use realizar::infer::{InferenceConfig, run_inference};
    247
    ///
    248
    /// let result = run_inference(&InferenceConfig::new("model.gguf")
    249
    ///     .with_prompt("Hello!"))?;
    250
    /// println!("{}", result.text);
    251
    /// ```
    252
    pub mod infer;
    253
    /// SIMD-accelerated inference engine using trueno
    254
    ///
    255
    /// Provides high-performance transformer inference competing with llama.cpp.
    256
    /// Uses trueno's SIMD primitives for matrix operations.
    257
    pub mod inference;
    258
    /// Inference tracing for debugging LLM pipelines
    259
    ///
    260
    /// Per spec APR-TRACE-001: Toyota Way Genchi Genbutsu (Go and See) + Jidoka.
    261
    /// Provides step-by-step visualization of the inference pipeline:
    262
    /// - ENCODE: Tokenization with OOV detection
    263
    /// - EMBED: Token embedding lookup
    264
    /// - TRANSFORMER: Layer-by-layer processing
    265
    /// - LM_HEAD: Final projection to logits
    266
    /// - SAMPLE: Token sampling
    267
    /// - DECODE: Token to text decoding with garbage detection (APR-TOK-001)
    268
    pub mod inference_trace;
    269
    pub mod layers;
    270
    pub mod memory;
    271
    #[cfg(feature = "server")]
    272
    pub mod metrics;
    273
    /// Unified model loader for APR, GGUF, and SafeTensors
    274
    ///
    275
    /// Per spec §3.2 and §5: Combines format detection with model loading.
    276
    /// Supports all 18 APR model types.
    277
    pub mod model_loader;
    278
    pub mod moe;
    279
    /// Observability: metrics, tracing, and A/B testing
    280
    ///
    281
    /// Safe numeric casts for observability metrics:
    282
    /// - Duration microseconds: u128 -> u64 (durations under 584,942 years won't overflow)
    283
    /// - Timestamps: u128 -> u64 (Unix epoch nanoseconds/microseconds fit in u64 until ~2554)
    284
    /// - Percentages: integer -> f64 (exact for values under 2^53)
    285
    #[cfg(feature = "server")]
    286
    #[allow(clippy::cast_possible_truncation)]
    287
    #[allow(clippy::cast_precision_loss)]
    288
    #[allow(clippy::cast_sign_loss)]
    289
    pub mod observability;
    290
    /// PagedAttention KV cache management
    291
    ///
    292
    /// Per spec §8.1: Efficient KV cache management based on vLLM's PagedAttention.
    293
    /// Reference: [4] Kwon et al. (2023) "Efficient Memory Management for LLM Serving"
    294
    /// - Physical pages: Fixed-size memory blocks for KV cache
    295
    /// - Page tables: Logical to physical mapping per sequence
    296
    /// - Copy-on-Write: Efficient prefix sharing between sequences
    297
    pub mod paged_kv;
    298
    /// Multi-GPU and Distributed Inference
    299
    ///
    300
    /// Per spec §10: Implements parallelism strategies for 70B+ model inference.
    301
    /// Reference: [11] Shoeybi et al. (2019) "Megatron-LM: Training Multi-Billion Parameter LMs"
    302
    /// - Tensor Parallelism (TP): Split tensors across GPUs within node (2-8 GPUs)
    303
    /// - Pipeline Parallelism (PP): Split layers across GPUs/nodes (2-64 GPUs)
    304
    /// - Data Parallelism (DP): Replicate model, split batches
    305
    /// - ZeRO-Inference: Memory offload to CPU
    306
    pub mod parallel;
    307
    pub mod quantize;
    308
    #[cfg(feature = "server")]
    309
    pub mod registry;
    310
    pub mod safetensors;
    311
    /// SafeTensors inference support (PAR-301)
    312
    ///
    313
    /// Converts HuggingFace SafeTensors models to AprTransformer for inference.
    314
    /// Requires config.json and tokenizer.json in the same directory.
    315
    pub mod safetensors_infer;
    316
    /// Continuous batching scheduler
    317
    ///
    318
    /// Per spec §8: Implements continuous batching for LLM serving based on vLLM/Orca.
    319
    /// Reference: [8] Yu et al. (2022) "Orca: A Distributed Serving System"
    320
    /// - Iteration-level scheduling: New requests join batch at any iteration
    321
    /// - Preemption: Low-priority requests can be preempted for high-priority
    322
    /// - Memory-aware: Respects KV cache limits when scheduling
    323
    pub mod scheduler;
    324
    #[cfg(feature = "aprender-serve")]
    325
    pub mod serve;
    326
    /// Speculative decoding for LLM inference acceleration
    327
    ///
    328
    /// Per spec §8.3: Implements speculative decoding based on SGLang/DeepMind research.
    329
    /// Reference: [9] Leviathan et al. (2023) "Fast Inference from Transformers via Speculative Decoding"
    330
    /// - Draft model: Small model generates K candidate tokens
    331
    /// - Target model: Verifies all K tokens in single forward pass
    332
    /// - Rejection sampling: Maintains exact target distribution
    333
    /// - Speedup: Up to 3x with well-matched draft/target pairs
    334
    pub mod speculative;
    335
    pub mod stats;
    336
    pub mod tensor;
    337
    /// TUI monitoring for inference performance
    338
    pub mod tui;
    339
    pub mod viz;
    340
    /// Model warm-up and pre-loading
    341
    pub mod warmup;
    342
    343
    /// AWS Lambda handler for aprender model serving
    344
    #[cfg(feature = "lambda")]
    345
    pub mod lambda;
    346
    /// Multi-target deployment support (Lambda, Docker, WASM)
    347
    pub mod target;
    348
    pub mod tokenizer;
    349
    /// Pacha URI scheme support for model loading
    350
    pub mod uri;
    351
    352
    // Re-exports for convenience
    353
    pub use error::{RealizarError, Result};
    354
    pub use infer::{run_inference, InferenceConfig, InferenceResult};
    355
    pub use inference_trace::{InferenceTracer, ModelInfo, TraceConfig, TraceStep};
    356
    #[cfg(not(target_arch = "wasm32"))]
    357
    pub use safetensors::MappedSafeTensorsModel;
    358
    pub use safetensors::SafetensorsConfig;
    359
    pub use tensor::Tensor;
    360
    361
    /// Library version
    362
    pub const VERSION: &str = env!("CARGO_PKG_VERSION");
    363
    364
    #[cfg(test)]
    365
    mod tests {
    366
        use super::*;
    367
    368
        #[test]
    369
    1
        fn test_version() {
    370
            // VERSION is a compile-time constant from CARGO_PKG_VERSION, so it's never empty
    371
    1
            assert!(VERSION.starts_with("0."));
    372
    1
            assert!(VERSION.len() >= 3); // At least "0.x"
    373
    1
            assert!(VERSION.contains('.'));
    374
    1
        }
    375
    }