Expand description
Experimental paper-core FibQuant math crate.
This crate implements the normalize, deterministic rotation,
spherical-Beta block source, radial-angular codebook, Lloyd-Max refinement,
and fixed-rate codec path described in FibQuant: Universal Vector Quantization for Random-Access KV-Cache Compression.
The 0.1.0-alpha.1 surface is deliberately narrow. It is not a production
KV-cache compressor, not a benchmark reproduction package, and not
integrated with any parent workspace memory crate. Profiles are validated
against explicit alpha resource limits before allocation-heavy paths run.
use fib_quant::{FibQuantProfileV1, FibQuantizer};
let mut profile = FibQuantProfileV1::paper_default(8, 2, 8, 7)?;
profile.training_samples = 128;
profile.lloyd_restarts = 1;
profile.lloyd_iterations = 2;
let quantizer = FibQuantizer::new(profile)?;
let input = vec![0.25, -0.5, 0.75, 1.0, -1.25, 0.5, 0.125, -0.875];
let code = quantizer.encode(&input)?;
let decoded = quantizer.decode(&code)?;
assert_eq!(decoded.len(), input.len());Re-exports§
pub use batch_ingest::BatchIngestPipeline;pub use batch_ingest::IngestReceipt;pub use codebook::build_initial_codebook;pub use codebook::FibCodebookV1;pub use codec::CompactFeatureFlags;pub use codec::FibCodeV1;pub use codec::FibQuantizer;pub use codec::GpuStepReport;pub use codec::CODEC_ID;pub use codec::COMPACT_MAGIC;pub use codec::COMPACT_V2_MAGIC;pub use codec::COMPACT_V2_VERSION;pub use codec::COMPACT_VERSION;pub use directions::fibonacci_sphere_3d;pub use directions::fibonacci_spiral_2d;pub use directions::roberts_kronecker;pub use error::FibQuantError;pub use error::Result;pub use eval::ndcg_at_k;pub use eval::recall_at_k;pub use eval::run_benchmark;pub use eval::FibBenchmarkCorpus;pub use eval::FibBenchmarkReceiptV1;pub use lattice::quantize_a2_pairs;pub use lattice::quantize_z1;pub use lattice::LatticeKind;pub use lattice::LatticeQuantizationResult;pub use lloyd::LloydRepairEventV1;pub use lloyd::LloydReportV1;pub use persistence::load_from_file;pub use persistence::save_to_file;pub use persistence::FibSidecarFileV1;pub use persistence::FILE_MAGIC;pub use persistence::FILE_VERSION;pub use persistence::load_mmap;pub use persistence::MmapSidecarIndex;pub use profile::DirectionMethod;pub use profile::EmptyCellPolicy;pub use profile::FibQuantProfileV1;pub use profile::LloydMode;pub use profile::NormFormat;pub use profile::RadiusMethod;pub use profile::SourceMode;pub use profile::MAX_AMBIENT_DIM;pub use profile::MAX_BLOCK_DIM;pub use profile::MAX_CODEBOOK_SIZE;pub use profile::MAX_CODEBOOK_VALUES;pub use profile::MAX_PACKED_INDEX_BITS;pub use profile::MAX_ROTATION_MATRIX_VALUES;pub use profile::MAX_TRAINING_SAMPLES;pub use receipt::FibQuantCompressionReceiptV1;pub use residual::FibMultiLevelQuantizer;pub use residual::FibResidualCodeV1;pub use residual::FibResidualQuantizer;pub use residual::MultiLevelCode;pub use residual::MultiLevelResidualCodebookV1;pub use residual::ResidualCodebookV1;pub use rope::allocate_rope_bits;pub use rope::rope_block_energies;pub use rope::rope_blocks;pub use rope::RopeBitAllocation;pub use rope::RopeBlock;pub use rope::RopeBlockEnergy;pub use rotation::StoredRotation;pub use rotation::ROTATION_ALGORITHM_VERSION;pub use rotation::ROTATION_SCHEMA;pub use scoring::FibPreparedQuery;pub use scoring::FibScorer;pub use scoring::GramTable;pub use scoring::ScoredItem;pub use sidecar::FibSidecarIndex;pub use sidecar::IvfCoarseQuantizer;pub use sidecar::ScoredCandidate;pub use sidecar::SearchReceiptIvfV1;pub use sidecar::SearchReceiptV1;pub use spherical_beta::beta_d_k;pub use spherical_beta::radius_quantile;pub use spherical_beta::radius_quantile_k2_closed_form;pub use spherical_beta::sample_reference_projection;pub use spherical_beta::sample_spherical_beta;pub use wire::FibCodeWireV1;pub use wire::WireHeader;pub use wire::WIRE_HEADER_SIZE;pub use wire::WIRE_MAGIC;pub use wire::WIRE_VERSION;
Modules§
- batch_
ingest - High-throughput batch ingest pipeline for encoding and inserting
large vector corpora (100K+) into a
FibSidecarIndex. - beta_
inv - bitpack
- codebook
- codec
- compat
- quant-codec-core trait implementations for fib-quant.
- digest
- directions
- error
- eval
- Benchmark and evaluation harness for FibQuant.
- ffi
- FFI bindings to the C kernels in
c-kernels/. - kv
- KV-cache compression contracts and CPU reference paths.
- lattice
- lloyd
- metrics
- persistence
- Disk persistence and zero-copy mmap access for
FibSidecarIndex. - profile
- receipt
- residual
- Residual (second-level) quantization for improved reconstruction quality.
- rope
- RoPE-aware bit allocation for KV-cache quantization.
- rotation
- scoring
- Approximate inner product scoring without full decode.
- sidecar
- Generic sidecar search index wrapping
FibScorer. - spherical_
beta - wire
- Self-describing wire format for FibQuant codes.