ruvector_temporal_tensor/
lib.rs

1//! Temporal Tensor Compression with Tiered Quantization
2//!
3//! Implements ADR-017: groupwise symmetric quantization with temporal segment
4//! reuse and access-pattern-driven tier selection (8/7/5/3 bit).
5//!
6//! # Architecture
7//!
8//! ```text
9//! f32 frame → tier_policy → quantizer → bitpack → segment
10//! segment → bitpack → quantizer → f32 output
11//! ```
12//!
13//! # Compression Ratios
14//!
15//! | Tier | Bits | Ratio vs f32 | Use Case |
16//! |------|------|-------------|----------|
17//! | Hot  | 8    | ~4.0x       | Frequently accessed tensors |
18//! | Warm | 7    | ~4.57x      | Moderately accessed |
19//! | Warm | 5    | ~6.4x       | Aggressively compressed warm |
20//! | Cold | 3    | ~10.67x     | Rarely accessed |
21//!
22//! # Zero Dependencies
23//!
24//! This crate has no external dependencies, making it fully WASM-compatible.
25//!
26//! # Quick Start
27//!
28//! ```rust
29//! use ruvector_temporal_tensor::{TemporalTensorCompressor, TierPolicy};
30//!
31//! // Create a compressor for 128-element tensors
32//! let mut comp = TemporalTensorCompressor::new(TierPolicy::default(), 128, 0);
33//! comp.set_access(100, 0); // hot tensor -> 8-bit quantization
34//!
35//! let frame = vec![1.0f32; 128];
36//! let mut segment = Vec::new();
37//!
38//! // Push frames; segment is populated when a boundary is crossed
39//! comp.push_frame(&frame, 1, &mut segment);
40//! comp.flush(&mut segment); // force-emit the current segment
41//!
42//! // Decode the segment back to f32
43//! let mut decoded = Vec::new();
44//! ruvector_temporal_tensor::segment::decode(&segment, &mut decoded);
45//! assert_eq!(decoded.len(), 128);
46//! ```
47//!
48//! # Random-Access Decode
49//!
50//! ```rust
51//! # use ruvector_temporal_tensor::{TemporalTensorCompressor, TierPolicy};
52//! # let mut comp = TemporalTensorCompressor::new(TierPolicy::default(), 64, 0);
53//! # let frame = vec![1.0f32; 64];
54//! # let mut seg = Vec::new();
55//! # comp.push_frame(&frame, 0, &mut seg);
56//! # comp.flush(&mut seg);
57//! // Decode only frame 0 without decoding the entire segment
58//! let single = ruvector_temporal_tensor::segment::decode_single_frame(&seg, 0);
59//! assert!(single.is_some());
60//! ```
61//!
62//! # Compression Ratio Inspection
63//!
64//! ```rust
65//! # use ruvector_temporal_tensor::{TemporalTensorCompressor, TierPolicy};
66//! # let mut comp = TemporalTensorCompressor::new(TierPolicy::default(), 64, 0);
67//! # let frame = vec![1.0f32; 64];
68//! # let mut seg = Vec::new();
69//! # comp.push_frame(&frame, 0, &mut seg);
70//! # comp.flush(&mut seg);
71//! let ratio = ruvector_temporal_tensor::segment::compression_ratio(&seg);
72//! assert!(ratio > 1.0);
73//! ```
74
75pub mod bitpack;
76pub mod compressor;
77pub mod delta;
78pub mod f16;
79pub mod metrics;
80pub mod quantizer;
81pub mod segment;
82pub mod store;
83pub mod tier_policy;
84pub mod tiering;
85
86pub mod agentdb;
87pub mod coherence;
88pub mod core_trait;
89#[cfg(feature = "persistence")]
90pub mod persistence;
91
92#[cfg(feature = "ffi")]
93pub mod ffi;
94
95#[cfg(feature = "ffi")]
96pub mod store_ffi;
97
98pub use compressor::TemporalTensorCompressor;
99pub use tier_policy::TierPolicy;
ruvector_temporal_tensor/lib.rs

ruvector_temporal_tensor/
lib.rs
