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; point location uses a
6//! fixed-resolution power-diagram grid whose cost is independent of tree depth.
7//!
8//! ## Core Principles
9//!
10//! 1. **Hyperbolic Geometry**: Maps hierarchical data into hyperbolic space using the Poincaré disk model
11//! 2. **Spatial Indexing**: ~61 fixed buckets with per-bucket VP-trees for range and nearest-neighbor queries
12//! 3. **Geometric Hashing**: Locality-sensitive signatures give hash-map path access
13//!
14//! ## Key Features
15//!
16//! - **Depth-independent lookups**: `get`/`exists` are hash-map access; grid point
17//!   location cost depends on grid resolution, not tree size. Per-method docs state
18//!   each operation's honest cost (VP-tree KNN is logarithmic per bucket; semantic
19//!   queries use lazy per-slice VP-trees above a node floor, a linear scan below —
20//!   see `Store::nearest_semantic` and `docs/SEMANTIC_INDEX.md`).
21//! - **Spatial Queries**: Find nearest neighbors and range queries in hyperbolic space
22//! - **Mathematically Grounded**: Sarkar embedding + Nielsen power diagram (see PROOF.md).
23//!   PROOF.md's Delaunay guarantee is conditional on `tau >= -log(tan(pi/(2*d_max)))`;
24//!   the default `tau = 1.0` satisfies it up to `d_max ~= 4.5` (see `StoreConfig::tau`).
25//! - **Deterministic Results**: Q64.64 fixed-point arithmetic for bit-identical results across platforms
26//! - **Extensible**: Modular architecture with pluggable components and extension system
27//!
28//! ## Basic Usage
29//!
30//! ```
31//! use horon_engine::{HTTStorage, HTTStorageConfig};
32//!
33//! // Create storage configuration
34//! let config = HTTStorageConfig::default();
35//!
36//! // Create HTT storage
37//! let storage = HTTStorage::new(config);
38//!
39//! // Store and retrieve data
40//! storage.store("/example/path", b"Hello, HTT!", None).unwrap();
41//! let data = storage.retrieve("/example/path").unwrap();
42//! assert_eq!(data, b"Hello, HTT!");
43//! ```
44
45#![warn(missing_docs)]
46
47// Core modules
48pub mod error;
49pub mod registry;
50pub mod metrics;
51pub mod config;
52pub mod hash_table;
53pub mod hyperbolic_geometry;
54pub mod metric_tree;
55pub mod semantic_disk;
56pub mod semantic_index;
57pub mod tensor_network;
58pub mod tree_tensor;
59pub mod storage;
60pub mod extension;
61pub mod utils;
62pub mod constants;
63pub mod concurrency;
64pub mod klein;
65pub mod store;
66pub mod init;
67
68// Re-export key types
69pub use error::{HTTError, HTTResult};
70pub use registry::{ComponentRegistry, HTTComponentRegistry, RegistryError};
71pub use metrics::{MetricsProvider, SimpleMetrics};
72pub use config::HTTStorageConfig;
73pub use tree_tensor::HTTConfig;
74pub use hash_table::HyperbolicHashTable;
75pub use hyperbolic_geometry::{PoincareDisk, HyperbolicPoint, distance_to_ratio};
76pub use tensor_network::{HyperbolicTensorNetwork, CompressedNode, NodeMetadata};
77pub use tree_tensor::HyperbolicTreeTensor;
78pub use storage::HTTStorage;
79pub use extension::{HTTExtension, HTTStorageProvider, ExtensionRegistry};
80pub use klein::{KleinPoint, PowerCell, PointLocationGrid, poincare_to_klein, klein_to_poincare, power_distance};
81pub use store::{Store, StoreConfig, StoreError, QueryAdapter, QueryResult, SemanticOutlier};
82pub use semantic_disk::SemanticDisk;
83
84
85/// Version information
86pub const VERSION: &str = env!("CARGO_PKG_VERSION");
87/// Crate authors (from Cargo.toml)
88pub const AUTHORS: &str = env!("CARGO_PKG_AUTHORS");
89/// Crate description (from Cargo.toml)
90pub const DESCRIPTION: &str = env!("CARGO_PKG_DESCRIPTION");
horon_engine/lib.rs

horon_engine/
lib.rs
