fib_quant/lib.rs
1#![warn(rustdoc::broken_intra_doc_links)]
2
3//! Experimental paper-core FibQuant math crate.
4//!
5//! This crate implements the normalize, deterministic rotation,
6//! spherical-Beta block source, radial-angular codebook, Lloyd-Max refinement,
7//! and fixed-rate codec path described in `FibQuant: Universal Vector
8//! Quantization for Random-Access KV-Cache Compression`.
9//!
10//! The `0.1.0-alpha.1` surface is deliberately narrow. It is not a production
11//! KV-cache compressor, not a benchmark reproduction package, and not
12//! integrated with any parent workspace memory crate. Profiles are validated
13//! against explicit alpha resource limits before allocation-heavy paths run.
14//!
15//! ```
16//! use fib_quant::{FibQuantProfileV1, FibQuantizer};
17//!
18//! # fn main() -> fib_quant::Result<()> {
19//! let mut profile = FibQuantProfileV1::paper_default(8, 2, 8, 7)?;
20//! profile.training_samples = 128;
21//! profile.lloyd_restarts = 1;
22//! profile.lloyd_iterations = 2;
23//! let quantizer = FibQuantizer::new(profile)?;
24//! let input = vec![0.25, -0.5, 0.75, 1.0, -1.25, 0.5, 0.125, -0.875];
25//! let code = quantizer.encode(&input)?;
26//! let decoded = quantizer.decode(&code)?;
27//! assert_eq!(decoded.len(), input.len());
28//! # Ok(())
29//! # }
30//! ```
31
32pub mod beta_inv;
33pub mod bitpack;
34pub mod codebook;
35pub mod codec;
36pub mod digest;
37pub mod directions;
38pub mod error;
39#[cfg(feature = "kv")]
40pub mod kv;
41pub mod lloyd;
42pub mod metrics;
43pub mod profile;
44pub mod receipt;
45pub mod rotation;
46pub mod spherical_beta;
47
48pub use codebook::{build_initial_codebook, FibCodebookV1};
49pub use codec::{FibCodeV1, FibQuantizer};
50pub use directions::{fibonacci_sphere_3d, fibonacci_spiral_2d, roberts_kronecker};
51pub use error::{FibQuantError, Result};
52pub use lloyd::{LloydRepairEventV1, LloydReportV1};
53pub use profile::{
54 DirectionMethod, EmptyCellPolicy, FibQuantProfileV1, NormFormat, RadiusMethod, SourceMode,
55 MAX_AMBIENT_DIM, MAX_BLOCK_DIM, MAX_CODEBOOK_SIZE, MAX_CODEBOOK_VALUES, MAX_PACKED_INDEX_BITS,
56 MAX_ROTATION_MATRIX_VALUES, MAX_TRAINING_SAMPLES,
57};
58pub use receipt::FibQuantCompressionReceiptV1;
59pub use rotation::{StoredRotation, ROTATION_ALGORITHM_VERSION, ROTATION_SCHEMA};
60pub use spherical_beta::{
61 beta_d_k, radius_quantile, radius_quantile_k2_closed_form, sample_reference_projection,
62 sample_spherical_beta,
63};