arms_hat/
lib.rs

1//! # ARMS - Attention Reasoning Memory Store
2//!
3//! > "The hippocampus of artificial minds"
4//!
5//! ARMS is a spatial memory fabric for AI models. It stores computed attention
6//! states at their native dimensional coordinates, enabling instant retrieval
7//! by proximity rather than traditional indexing.
8//!
9//! ## Philosophy
10//!
11//! - **Position IS relationship** - No foreign keys, proximity defines connection
12//! - **Configurable, not hardcoded** - Dimensionality, proximity functions, all flexible
13//! - **Generators over assets** - Algorithms, not rigid structures
14//! - **Pure core, swappable adapters** - Hexagonal architecture
15//!
16//! ## Architecture
17//!
18//! ```text
19//! ┌─────────────────────────────────────────────────────────────┐
20//! │                         ARMS                                 │
21//! ├─────────────────────────────────────────────────────────────┤
22//! │                                                              │
23//! │  CORE (pure math, no I/O)                                   │
24//! │    Point, Id, Blob, Proximity, Merge                        │
25//! │                                                              │
26//! │  PORTS (trait contracts)                                     │
27//! │    Place, Near, Latency                                     │
28//! │                                                              │
29//! │  ADAPTERS (swappable implementations)                       │
30//! │    Storage: Memory, NVMe                                    │
31//! │    Index: Flat, HNSW                                        │
32//! │    API: Python bindings                                      │
33//! │                                                              │
34//! │  ENGINE (orchestration)                                      │
35//! │    Arms - the main entry point                              │
36//! │                                                              │
37//! └─────────────────────────────────────────────────────────────┘
38//! ```
39//!
40//! ## Quick Start
41//!
42//! ```rust,ignore
43//! use arms::{Arms, ArmsConfig, Point};
44//!
45//! // Create ARMS with default config (768 dimensions)
46//! let mut arms = Arms::new(ArmsConfig::default());
47//!
48//! // Place a point in the space
49//! let point = Point::new(vec![0.1; 768]);
50//! let id = arms.place(point, b"my data".to_vec());
51//!
52//! // Find nearby points
53//! let query = Point::new(vec![0.1; 768]);
54//! let neighbors = arms.near(&query, 5);
55//! ```
56
57// ============================================================================
58// MODULES
59// ============================================================================
60
61/// Core domain - pure math, no I/O
62/// Contains: Point, Id, Blob, Proximity trait, Merge trait
63pub mod core;
64
65/// Port definitions - trait contracts for adapters
66/// Contains: Place trait, Near trait, Latency trait
67pub mod ports;
68
69/// Adapter implementations - swappable components
70/// Contains: storage, index, python submodules
71pub mod adapters;
72
73/// Engine - orchestration layer
74/// Contains: Arms main struct
75pub mod engine;
76
77// ============================================================================
78// PYTHON BINDINGS (when enabled)
79// ============================================================================
80
81#[cfg(feature = "python")]
82pub use adapters::python::*;
83
84// ============================================================================
85// RE-EXPORTS (public API)
86// ============================================================================
87
88// Core types
89pub use crate::core::{Point, Id, Blob, PlacedPoint};
90pub use crate::core::proximity::{Proximity, Cosine, Euclidean, DotProduct};
91pub use crate::core::merge::{Merge, Mean, WeightedMean, MaxPool};
92pub use crate::core::config::ArmsConfig;
93
94// Port traits
95pub use crate::ports::{Place, Near, Latency};
96
97// Engine
98pub use crate::engine::Arms;
99
100// ============================================================================
101// CRATE-LEVEL DOCUMENTATION
102// ============================================================================
103
104/// The five primitives of ARMS:
105///
106/// 1. **Point**: `Vec<f32>` - Any dimensionality
107/// 2. **Proximity**: `fn(a, b) -> f32` - How related?
108/// 3. **Merge**: `fn(points) -> point` - Compose together
109/// 4. **Place**: `fn(point, data) -> id` - Exist in space
110/// 5. **Near**: `fn(point, k) -> ids` - What's related?
111///
112/// Everything else is configuration or adapters.
113#[doc(hidden)]
114pub const _PRIMITIVES: () = ();
arms_hat/lib.rs

arms_hat/
lib.rs
