katgpt_types/lib.rs
1//! katgpt-types — Shared configuration, RNG, math utilities, SIMD kernels,
2//! and inference types for the katgpt-rs / riir-engine superset.
3//!
4//! Pure substrate leaf crate. No katgpt-* dependencies — only `fastrand`,
5//! `blake3`, `serde`, `half`. This is the foundational layer (types + SIMD
6//! kernels) that every other katgpt-* crate (and riir-engine) builds on.
7//! The `types` and `simd` modules are co-located because `types::math`
8//! calls `simd` kernels (softmax / rmsnorm / matmul) and `simd::ternary`
9//! uses `types::TernaryWeights` — they form a tight bidirectional leaf that
10//! cannot be split further without breaking the cycle.
11//!
12//! Originally a single 5,148-line `types.rs` inside katgpt-core (2.5× the
13//! 2048-line ceiling), split into topic-specific submodules. The full public
14//! surface is re-exported here so consumers can use `katgpt_types::*` paths
15//! directly.
16//!
17//! Spun out of `katgpt-core::types` (Issue 007 Phase E Tier 1 #2) as a
18//! standalone publishable crate mirroring the `katgpt-dec` / `katgpt-transformer`
19//! template.
20//!
21//! # Module layout
22//!
23//! - `enums` — small config enums (DepthTier, HlaMode, AttentionMode, …)
24//! plus WallConfig / ThinkingBudget
25//! - `config` — the `Config` struct (~1.5k lines), `InferenceOverrides`,
26//! and `kv_dim`
27//! - `rng` — XorShift64 PRNG
28//! - `math` — SIMD-accelerated softmax / rmsnorm / matmul / sample_token
29//! (legacy home; candidates for relocation to `katgpt-simd::`)
30//! - `lora` — CPU-side LoRA adapter
31//! - `gpart` — GPart Isometric Partition adapter (Research 227)
32//! - `domain` — DomainLatent embedding (Plan 038)
33//! - `inference` — InferenceResult, TaskType, ProposerTask, DataGate
34//! - `looping` — Training-Free Loop types (Plan 136)
35//! - `ternary` — Bit-plane ternary weights (`plasma_path`)
36//! - `hydra` — Hydra Adaptive Layer Budget types
37//! - `sense` — ShardEmbedding (DEPRECATED, Issue 139) + sense composition types
38//!
39//! Test modules live alongside their topic (e.g. `rng::tests_rng`) or in
40//! `tests_types.rs` for cross-cutting tests.
41
42mod config;
43/// Depth-Invariance Diagnostic & Magnitude-Regularized Residual (Plan 306).
44/// Pure math, depends only on simd. Co-located here (the leaf) so both
45/// katgpt-core (depth_invariance feature) and katgpt-micro-belief
46/// (audit_depth_invariance methods) can consume it without a cycle.
47#[cfg(feature = "depth_invariance")]
48pub mod depth_invariance;
49mod domain;
50#[cfg(feature = "depth_invariance")]
51pub use depth_invariance::{
52 DepthInvarianceConfig, DepthInvarianceDiagnostic, DepthInvarianceKind, MagnitudeRegularization,
53 Scratch, apply_magnitude_regularization, classify_chain, classify_chain_batched,
54};
55/// Binary `{-1,+1}` bit-plane packed weights (Issue 145, `binary_plasma` feature).
56#[cfg(feature = "binary_plasma")]
57pub mod binary;
58mod enums;
59mod gpart;
60mod hydra;
61mod inference;
62/// QuantizedKVCache trait — shared extension point for all KV backends.
63/// Promoted from `katgpt-rs/src/types.rs` (Issue 015 Phase 1) so backend
64/// crates can depend on the trait without pulling the whole root crate.
65pub mod kv_cache;
66/// Shared leaky-integrator / delta-rule step primitive (Plan 276 Phase 2 T2.1).
67/// Pure inline math, zero deps. Consumed by both katgpt-micro-belief
68/// (`LeakyIntegrator::step`) and katgpt-core's sense reconstruction
69/// (`ReconstructionState::evolve_belief`). Co-located here (the leaf) so both
70/// consumers can share the single source of truth without a cycle.
71pub mod leaky_core;
72mod looping;
73mod lora;
74pub mod math;
75pub mod merkle;
76mod rng;
77mod sense;
78/// SIMD-accelerated linear algebra kernels (NEON / AVX2 / WASM-SIMD128 /
79/// scalar fallback). Co-located with `types` because `types::math` calls
80/// these kernels and `simd::ternary` uses `types::TernaryWeights`.
81pub mod simd;
82pub mod slod;
83pub mod temporal;
84mod ternary;
85
86#[cfg(test)]
87mod tests_types;
88
89// Re-export the entire public surface so `katgpt_types::*` paths are
90// available at the crate root. Feature gates mirror the gates on the
91// underlying items.
92#[cfg(feature = "binary_plasma")]
93pub use binary::{BinaryWeights, GROUP_SIZE};
94pub use config::{Config, InferenceOverrides, kv_dim};
95#[cfg(feature = "domain_latent")]
96pub use domain::DomainLatent;
97#[cfg(feature = "deltanet_inference")]
98pub use enums::DeltaNetLayerType;
99#[cfg(feature = "collapse_aware_thinking")]
100pub use enums::ThinkingBudget;
101#[cfg(feature = "wall_attention")]
102pub use enums::WallConfig;
103pub use enums::{
104 AttentionMode, AttentionProjection, CacheLayout, CalibrationMode, ConvergenceSelector,
105 DashAttnConfig, DepthTier, HlaMode, HybridPattern, LoopMode, LoopStabilityMode,
106 ModelArchitecture, ResidualGate, RetrievalHeadRole, RtTurboConfig, SdpaOutputGate, WeightDtype,
107};
108#[cfg(feature = "sr2am_configurator")]
109pub use enums::{ConfiguratorContext, PlanningDecision};
110#[cfg(feature = "gpart_adapter")]
111pub use gpart::{GPART_MAGIC, GPART_VERSION, GpartAdapter, GpartPair, GpartPrepared};
112#[cfg(feature = "hydra_budget")]
113pub use hydra::{HydraBudgetConfig, HydraLayerProfile};
114pub use inference::InferenceResult;
115#[cfg(feature = "data_gate")]
116pub use inference::{DataGate, GateDecision, ProposerTask, TaskType};
117pub use kv_cache::QuantizedKVCache;
118pub use leaky_core::leaky_step;
119pub use looping::{CacheStrategy, IterationMode, SubStepStrategy, TrainingFreeLoopConfig};
120pub use lora::{LoraAdapter, LoraPair, lora_apply};
121#[allow(deprecated)]
122pub use math::sample_token;
123#[cfg(feature = "sparse_mlp")]
124pub use math::sparse_matmul;
125pub use math::{
126 gegelu, gegelu_tanh, matmul, matmul_f16, matmul_f16_f16, matmul_f16_f16_parallel,
127 matmul_f16_parallel, matmul_parallel, matmul_relu, rmsnorm, rmsnorm_with_gamma,
128 rmsnorm_with_gamma_eps, sample_token_into, silu, softmax, softmax_scaled, swiglu,
129 swiglu_inplace,
130};
131pub use merkle::{
132 HASH_SIZE, MERKLE_OCTREE_BRANCHING, MERKLE_OCTREE_DEPTH, MERKLE_OCTREE_INTERNAL,
133 MERKLE_OCTREE_LEAVES, MERKLE_OCTREE_NODES, MerkleOctree, MerkleProof,
134};
135pub use rng::Rng;
136#[allow(deprecated)]
137pub use sense::ShardEmbedding;
138pub use sense::{DilationConfig, SenseKind, SenseModule, TernaryDir};
139pub use slod::ScaleBoundary;
140pub use temporal::{TemporalDerivativeKernel, sigmoid_surprise_gate};
141#[cfg(feature = "plasma_path")]
142pub use ternary::TernaryWeights;
143
144// Internal helpers (read_u32_le / read_f32_le / read_u16_le) live in
145// `domain.rs` and are crate-private — not re-exported here. If other modules
146// need them, import via `crate::domain::read_u32_le`.