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//! - **Deterministic Results**: Q64.64 fixed-point arithmetic for bit-identical results across platforms
24//! - **Extensible**: Modular architecture with pluggable components and extension system
25//!
26//! ## Basic Usage
27//!
28//! ```
29//! use horon_engine::{HTTStorage, HTTStorageConfig};
30//!
31//! // Create storage configuration
32//! let config = HTTStorageConfig::default();
33//!
34//! // Create HTT storage
35//! let storage = HTTStorage::new(config);
36//!
37//! // Store and retrieve data
38//! storage.store("/example/path", b"Hello, HTT!", None).unwrap();
39//! let data = storage.retrieve("/example/path").unwrap();
40//! assert_eq!(data, b"Hello, HTT!");
41//! ```
42
43#![warn(missing_docs)]
44
45// Core modules
46pub mod error;
47pub mod registry;
48pub mod metrics;
49pub mod config;
50pub mod hash_table;
51pub mod hyperbolic_geometry;
52pub mod metric_tree;
53pub mod semantic_disk;
54pub mod semantic_index;
55pub mod tensor_network;
56pub mod tree_tensor;
57pub mod storage;
58pub mod extension;
59pub mod utils;
60pub mod constants;
61pub mod concurrency;
62pub mod klein;
63pub mod store;
64pub mod init;
65
66// Re-export key types
67pub use error::{HTTError, HTTResult};
68pub use registry::{ComponentRegistry, HTTComponentRegistry, RegistryError};
69pub use metrics::{MetricsProvider, SimpleMetrics};
70pub use config::HTTStorageConfig;
71pub use tree_tensor::HTTConfig;
72pub use hash_table::HyperbolicHashTable;
73pub use hyperbolic_geometry::{PoincareDisk, HyperbolicPoint, distance_to_ratio};
74pub use tensor_network::{HyperbolicTensorNetwork, CompressedNode, NodeMetadata};
75pub use tree_tensor::HyperbolicTreeTensor;
76pub use storage::HTTStorage;
77pub use extension::{HTTExtension, HTTStorageProvider, ExtensionRegistry};
78pub use klein::{KleinPoint, PowerCell, PointLocationGrid, poincare_to_klein, klein_to_poincare, power_distance};
79pub use store::{Store, StoreConfig, StoreError, QueryAdapter, QueryResult, SemanticOutlier};
80pub use semantic_disk::SemanticDisk;
81
82
83/// Version information
84pub const VERSION: &str = env!("CARGO_PKG_VERSION");
85/// Crate authors (from Cargo.toml)
86pub const AUTHORS: &str = env!("CARGO_PKG_AUTHORS");
87/// Crate description (from Cargo.toml)
88pub const DESCRIPTION: &str = env!("CARGO_PKG_DESCRIPTION");
horon_engine/lib.rs

horon_engine/
lib.rs
