poly_kv/
lib.rs

1//! Poly-KV: Shared compressed KV-cache pool for multi-agent context.
2//!
3//! ## Architecture
4//!
5//! A two-tier compression strategy derived from empirical benchmarks:
6//! - **Shared pool (cold tier):** fib-quant at k=4, N=32, 50× compression, 100% recall
7//! - **Agent shells (hot tier):** turbo-quant at 8-bit, 8× compression, 99.9% score retention
8//!
9//! ## Quick Start
10//!
11//! ```rust,ignore
12//! use poly_kv::{SharedKVPool, KvTensorShape, AttentionType};
13//!
14//! let shape = KvTensorShape {
15//!     attention_type: AttentionType::MHA,
16//!     num_layers: 32,
17//!     num_heads: 32,
18//!     num_kv_heads: 32,
19//!     head_dim: 128,
20//!     hidden_size: 4096,
21//! };
22//!
23//! let corpus: Vec<(String, Vec<f32>)> = vec![
24//!     ("tok_0".into(), vec![0.1; shape.num_layers as usize * 32 * 128 * 2]),
25//! ];
26//!
27//! let (pool, receipt) = SharedKVPool::build(&corpus, &shape, 42).unwrap();
28//! let (shell, mat_receipt) = pool.materialize_shell("agent_1", &[], 42).unwrap();
29//! ```
30
31pub mod codec;
32pub mod digest_compat;
33pub mod error;
34pub mod fallback;
35pub mod ids_compat;
36pub mod manifest;
37pub mod policy;
38pub mod pool;
39pub mod receipt;
40pub mod replay;
41pub mod shape;
42pub mod shell;
43
44#[cfg(feature = "temporal-truth")]
45pub mod temporal;
46
47// Re-export core types
48pub use codec::{create_codec, CompressedBlock, KVecCodec};
49pub use digest_compat::Digest;
50pub use error::{PolyKvError, Result};
51pub use ids_compat::AgentId;
52pub use manifest::{PoolManifest, ShellManifest, POOL_MANIFEST_SCHEMA, SHELL_MANIFEST_SCHEMA};
53pub use policy::{
54    CodecId, CompressionPolicy, FibConfig, TurboConfig, CODEC_EXACT_FALLBACK, CODEC_FIB_K4_N32,
55    CODEC_TURBO_8BIT,
56};
57pub use pool::{
58    CacheTarget, CompressedAttentionHit, CompressedAttentionSelection, DecompressedLayer,
59    FullyPreparedCompressedIndex, PoolLayer, PrefetchedGramRows, PreparedCompressedIndex,
60    SharedKVPool,
61};
62pub use receipt::{
63    BlockInjectionTrace, CompressedAttentionSelectionReceipt, InjectionReceipt, PoolBuildReceipt,
64    ShellMaterializeReceipt, COMPRESSED_ATTENTION_SELECTION_RECEIPT_SCHEMA,
65    INJECTION_RECEIPT_SCHEMA, POOL_BUILD_RECEIPT_SCHEMA, RECEIPT_SCHEMA,
66    SHELL_MATERIALIZE_RECEIPT_SCHEMA,
67};
68pub use replay::{
69    run_captured_model_replay, run_model_replay, CandidateReplayMetrics, CapturedReplayConfig,
70    CapturedReplayFixture, CapturedReplayQuery, CapturedReplayReceipt, ModelReplayConfig,
71    ModelReplayMetrics, ModelReplayQuery, ModelReplayReceipt, CAPTURED_MODEL_REPLAY_RECEIPT_SCHEMA,
72    MODEL_REPLAY_RECEIPT_SCHEMA,
73};
74pub use shape::{AttentionType, KvTensorShape};
75pub use shell::{
76    AgentShell, AttentionHit, CompressedShellAttentionHit, CompressedShellAttentionSelection,
77    ShellLayer,
78};
poly_kv/lib.rs

poly_kv/
lib.rs
