horon_engine/
lib.rs

1//! # horon-engine
2//!
3//! horon-engine is a Rust implementation of the Hyperbolic Tree Tensor data structure:
4//! hierarchical data embedded in the Poincaré disk so that tree structure becomes
5//! spatial proximity. Path lookups are hash-map access; spatial queries are
6//! answered exactly by a computed cell index.
7//!
8//! ## Core Principles
9//!
10//! 1. **Hyperbolic Geometry**: Maps hierarchical data into hyperbolic space using the Poincaré disk model
11//! 2. **Spatial Indexing**: a computed cell index — radial bands × angular sectors —
12//!    walked outward until a proven lower bound rules out every unvisited cell
13//! 3. **Exact by default**: no candidate cap, no window, no count-based stopping
14//!    rule. Degradation is toward slow, never toward wrong.
15//!
16//! ## Key Features
17//!
18//! - **Honest costs**: `get`/`exists` are hash-map access. Spatial queries are not
19//!   O(1) — they cost as many cells as the bound needs to rule out, which depends on
20//!   tree shape; see BENCHMARKS.md for measured figures. Semantic queries use lazy
21//!   per-slice VP-trees above a node floor and a linear scan below — see
22//!   `Store::nearest_semantic` and `docs/SEMANTIC_INDEX.md`.
23//! - **Spatial Queries**: Find nearest neighbors and range queries in hyperbolic space
24//! - **Architecture**: `docs/ARCHITECTURE.md` — the three coordinate systems and
25//!   which query serves each. Read it first; the distinction is easy to get backwards.
26//! - **Mathematically Grounded**: Sarkar embedding (see PROOF.md). PROOF.md's Delaunay
27//!   guarantee is conditional on `tau >= -log(tan(pi/(2*d_max)))` and the default
28//!   `tau = 1.0` satisfies it only up to `d_max ~= 4.5` (see `StoreConfig::tau`) — but
29//!   since 0.6.0 no query path depends on it. A violated bound costs spacing quality,
30//!   not correctness. See `docs/GEOMETRY_TRACK.md`.
31//! - **Deterministic Results**: Q64.64 fixed-point arithmetic for bit-identical results across platforms
32//! - **Extensible**: Modular architecture with pluggable components and extension system
33//!
34//! ## Basic Usage
35//!
36//! ```
37//! use horon_engine::{HTTStorage, HTTStorageConfig};
38//!
39//! // Create storage configuration
40//! let config = HTTStorageConfig::default();
41//!
42//! // Create HTT storage
43//! let storage = HTTStorage::new(config);
44//!
45//! // Store and retrieve data
46//! storage.store("/example/path", b"Hello, HTT!", None).unwrap();
47//! let data = storage.retrieve("/example/path").unwrap();
48//! assert_eq!(data, b"Hello, HTT!");
49//! ```
50
51#![warn(missing_docs)]
52
53// Core modules
54pub mod error;
55pub mod registry;
56pub mod metrics;
57pub mod config;
58pub mod hash_table;
59pub mod hyperbolic_geometry;
60pub mod metric_tree;
61pub mod cell_index;
62// A `spatial_index` module (a MetricVpTree wrapper) was held in reserve while
63// the cell index was being proven. It is nothing's dependency and never
64// shipped, so it is not published; it sits in the untracked `archive/` after a
65// full per-item inspection (248 lines, 5 tests, zero references).
66pub mod semantic_disk;
67pub mod semantic_index;
68pub mod tensor_network;
69pub mod tree_tensor;
70pub mod storage;
71pub mod extension;
72pub mod utils;
73pub mod constants;
74pub mod concurrency;
75pub mod klein;
76pub mod store;
77pub mod init;
78
79// Re-export key types
80pub use error::{HTTError, HTTResult};
81pub use registry::{ComponentRegistry, HTTComponentRegistry, RegistryError};
82pub use metrics::{MetricsProvider, SimpleMetrics};
83pub use config::HTTStorageConfig;
84pub use tree_tensor::HTTConfig;
85pub use hash_table::GeometricSignature;
86pub use hyperbolic_geometry::{PoincareDisk, HyperbolicPoint, distance_to_ratio};
87pub use tensor_network::{HyperbolicTensorNetwork, CompressedNode, NodeMetadata};
88pub use tree_tensor::HyperbolicTreeTensor;
89pub use storage::HTTStorage;
90pub use extension::{HTTExtension, HTTStorageProvider, ExtensionRegistry};
91pub use klein::{KleinPoint, poincare_to_klein, klein_to_poincare, power_distance};
92pub use store::{Store, StoreConfig, StoreError, QueryAdapter, QueryResult, SemanticOutlier};
93pub use semantic_disk::SemanticDisk;
94
95
96/// Version information
97pub const VERSION: &str = env!("CARGO_PKG_VERSION");
98/// Crate authors (from Cargo.toml)
99pub const AUTHORS: &str = env!("CARGO_PKG_AUTHORS");
100/// Crate description (from Cargo.toml)
101pub const DESCRIPTION: &str = env!("CARGO_PKG_DESCRIPTION");
horon_engine/lib.rs

horon_engine/
lib.rs
