dearsky/wifi-densepose

Fork 0

Files

ruv cd5943df23 Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

2026-02-28 14:39:40 -05:00

20 KiB

Raw Blame History

EXO-AI 2025 Cognitive Substrate - API Documentation

Version: 0.1.0 License: MIT OR Apache-2.0 Repository: https://github.com/ruvnet/ruvector

Overview
Architecture
Core Crates
API Reference
Type System
Error Handling
Migration from RuVector

Overview

EXO-AI 2025 is a next-generation cognitive substrate designed for advanced AI systems. Unlike traditional vector databases that use discrete storage, EXO implements:

Continuous Manifold Storage via implicit neural representations (SIREN networks)
Higher-Order Reasoning through hypergraphs with topological data analysis
Temporal Causality with short-term/long-term memory coordination
Distributed Cognition using post-quantum federated mesh networking

Key Features

Feature	Description
Manifold Engine	No discrete inserts—continuous deformation of learned space
Hypergraph Substrate	Relations spanning >2 entities, persistent homology, Betti numbers
Temporal Memory	Causal tracking, consolidation, anticipatory pre-fetching
Federation	Post-quantum crypto, onion routing, CRDT reconciliation, Byzantine consensus
Multi-Platform	Native Rust, WASM (browser), Node.js bindings

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    EXO-AI 2025 Stack                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  exo-wasm    │  │  exo-node    │  │  exo-cli     │      │
│  │  (Browser)   │  │  (Node.js)   │  │  (Native)    │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         └─────────────────┴─────────────────┘              │
│                           │                                 │
│  ┌────────────────────────┴────────────────────────┐        │
│  │              exo-core (Core Traits)             │        │
│  │  • SubstrateBackend                             │        │
│  │  • TemporalContext                              │        │
│  │  • Pattern, Query, SearchResult                 │        │
│  └────────────────────────────────────────────────┘        │
│         │              │              │              │      │
│  ┌──────▼──────┐┌─────▼─────┐┌──────▼──────┐┌─────▼─────┐ │
│  │ exo-manifold││exo-hyper-  ││exo-temporal ││exo-feder- │ │
│  │             ││  graph     ││             ││  ation    │ │
│  │ SIREN nets  ││ TDA/sheaf  ││ Causal mem  ││ P2P mesh  │ │
│  └─────────────┘└────────────┘└─────────────┘└───────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Core Crates

1. exo-core - Foundation

Core trait definitions and types for the cognitive substrate.

Key Exports:

Pattern - Vector embedding with metadata, causal antecedents, and salience
SubstrateBackend - Hardware-agnostic backend trait
TemporalContext - Temporal memory operations trait
Error / Result - Unified error handling

Example:

use exo_core::{Pattern, PatternId, Metadata, SubstrateTime};

let pattern = Pattern {
    id: PatternId::new(),
    embedding: vec![1.0, 2.0, 3.0],
    metadata: Metadata::default(),
    timestamp: SubstrateTime::now(),
    antecedents: vec![],
    salience: 0.95,
};

2. exo-manifold - Learned Continuous Storage

Implements continuous manifold storage using SIREN networks (implicit neural representations).

Key Exports:

ManifoldEngine<B: Backend> - Main engine for manifold operations
LearnedManifold<B> - SIREN network implementation
GradientDescentRetriever - Query via gradient descent
ManifoldDeformer - Continuous deformation (replaces insert)
StrategicForgetting - Manifold smoothing for low-salience regions

Core Concept: Instead of discrete vector insertion, patterns deform the learned manifold:

use exo_manifold::{ManifoldEngine, ManifoldConfig};
use burn::backend::NdArray;

let config = ManifoldConfig {
    dimension: 768,
    max_descent_steps: 100,
    learning_rate: 0.01,
    convergence_threshold: 1e-4,
    hidden_layers: 3,
    hidden_dim: 256,
    omega_0: 30.0,
};

let device = Default::default();
let mut engine = ManifoldEngine::<NdArray>::new(config, device);

// Continuous deformation (no discrete insert)
let delta = engine.deform(pattern, salience)?;

// Retrieval via gradient descent
let results = engine.retrieve(&query_embedding, k)?;

// Strategic forgetting
let pruned_count = engine.forget(0.1, 0.95)?;

3. exo-hypergraph - Higher-Order Relations

Supports hyperedges (relations spanning >2 entities) with topological data analysis.

Key Exports:

HypergraphSubstrate - Main hypergraph structure
Hyperedge - N-way relation
SimplicialComplex - For persistent homology
SheafStructure - Consistency checking

Topological Queries:

Persistent Homology - Find topological features across scales
Betti Numbers - Count connected components, loops, voids
Sheaf Consistency - Local-to-global coherence checks

Example:

use exo_hypergraph::{HypergraphSubstrate, HypergraphConfig};
use exo_core::{EntityId, Relation, RelationType};

let config = HypergraphConfig {
    enable_sheaf: true,
    max_dimension: 3,
    epsilon: 1e-6,
};

let mut hypergraph = HypergraphSubstrate::new(config);

// Create 3-way hyperedge
let entities = [EntityId::new(), EntityId::new(), EntityId::new()];
for &e in &entities {
    hypergraph.add_entity(e, serde_json::json!({}));
}

let relation = Relation {
    relation_type: RelationType::new("collaboration"),
    properties: serde_json::json!({"weight": 0.9}),
};

let hyperedge_id = hypergraph.create_hyperedge(&entities, &relation)?;

// Topological queries
let betti = hypergraph.betti_numbers(3); // [β₀, β₁, β₂, β₃]
let diagram = hypergraph.persistent_homology(1, (0.0, 1.0));

4. exo-temporal - Temporal Memory

Implements temporal memory with causal tracking and consolidation.

Key Exports:

TemporalMemory - Main coordinator
ShortTermBuffer - Volatile recent memory
LongTermStore - Consolidated persistent memory
CausalGraph - DAG of causal relationships
AnticipationHint / PrefetchCache - Predictive retrieval

Memory Layers:

Short-Term: Volatile buffer (recent patterns)
Long-Term: Consolidated store (high-salience patterns)
Causal Graph: Tracks antecedent relationships

Example:

use exo_temporal::{TemporalMemory, TemporalConfig, CausalConeType};

let memory = TemporalMemory::new(TemporalConfig::default());

// Store with causal context
let p1 = Pattern::new(vec![1.0, 0.0, 0.0], Metadata::new());
let id1 = memory.store(p1, &[])?;

let p2 = Pattern::new(vec![0.9, 0.1, 0.0], Metadata::new());
let id2 = memory.store(p2, &[id1])?; // p2 caused by p1

// Causal query (within past light-cone)
let query = Query::from_embedding(vec![1.0, 0.0, 0.0]).with_origin(id1);
let results = memory.causal_query(
    &query,
    SubstrateTime::now(),
    CausalConeType::Past,
);

// Consolidation: short-term → long-term
let consolidation_result = memory.consolidate();

5. exo-federation - Distributed Mesh

Federated substrate networking with post-quantum cryptography and Byzantine consensus.

Key Exports:

FederatedMesh - Main coordinator
PostQuantumKeypair - Dilithium/Kyber keys
join_federation() - Handshake protocol
onion_query() - Privacy-preserving routing
byzantine_commit() - BFT consensus (f = ⌊(N-1)/3⌋)

Features:

Post-Quantum Crypto: CRYSTALS-Dilithium + Kyber
Onion Routing: Multi-hop privacy (Tor-like)
CRDT Reconciliation: Eventual consistency
Byzantine Consensus: 3f+1 fault tolerance

Example:

use exo_federation::{FederatedMesh, PeerAddress, FederationScope};

let local_substrate = SubstrateInstance::new(config)?;
let mut mesh = FederatedMesh::new(local_substrate)?;

// Join federation
let peer = PeerAddress::new(
    "peer.example.com".to_string(),
    9000,
    peer_public_key,
);
let token = mesh.join_federation(&peer).await?;

// Federated query
let results = mesh.federated_query(
    query_data,
    FederationScope::Global { max_hops: 3 },
).await?;

// Byzantine consensus for state update
let update = StateUpdate { /* ... */ };
let proof = mesh.byzantine_commit(update).await?;

6. exo-wasm - Browser Bindings

WASM bindings for browser-based cognitive substrate.

Key Exports:

ExoSubstrate - Main WASM interface
Pattern - WASM-compatible pattern type
SearchResult - WASM search result

Example (JavaScript):

import init, { ExoSubstrate } from 'exo-wasm';

await init();

const substrate = new ExoSubstrate({
  dimensions: 384,
  distance_metric: "cosine",
  use_hnsw: true,
  enable_temporal: true,
  enable_causal: true
});

// Store pattern
const pattern = new Pattern(
  new Float32Array([1.0, 2.0, 3.0, ...]),
  { text: "example", category: "demo" },
  [] // antecedents
);
const id = substrate.store(pattern);

// Query
const results = await substrate.query(
  new Float32Array([1.0, 2.0, 3.0, ...]),
  10
);

// Stats
const stats = substrate.stats();
console.log(`Patterns: ${stats.pattern_count}`);

7. exo-node - Node.js Bindings

High-performance Node.js bindings via NAPI-RS.

Key Exports:

ExoSubstrateNode - Main Node.js interface
version() - Get library version

Example (Node.js/TypeScript):

import { ExoSubstrateNode } from 'exo-node';

const substrate = new ExoSubstrateNode({
  dimensions: 384,
  storagePath: './substrate.db',
  enableHypergraph: true,
  enableTemporal: true
});

// Store pattern
const id = await substrate.store({
  embedding: new Float32Array([1.0, 2.0, 3.0]),
  metadata: { text: 'example' },
  antecedents: []
});

// Search
const results = await substrate.search(
  new Float32Array([1.0, 2.0, 3.0]),
  10
);

// Hypergraph query
const hypergraphResult = await substrate.hypergraphQuery(
  JSON.stringify({
    type: 'BettiNumbers',
    maxDimension: 3
  })
);

// Stats
const stats = await substrate.stats();

Type System

Core Types

`Pattern`

Vector embedding with causal and temporal context.

pub struct Pattern {
    pub id: PatternId,
    pub embedding: Vec<f32>,
    pub metadata: Metadata,
    pub timestamp: SubstrateTime,
    pub antecedents: Vec<PatternId>,  // Causal dependencies
    pub salience: f32,                 // Importance score [0, 1]
}

`PatternId`

Unique identifier for patterns (UUID).

pub struct PatternId(pub Uuid);

impl PatternId {
    pub fn new() -> Self;
}

`SubstrateTime`

Nanosecond-precision timestamp.

pub struct SubstrateTime(pub i64);

impl SubstrateTime {
    pub const MIN: Self;
    pub const MAX: Self;
    pub fn now() -> Self;
    pub fn abs(&self) -> Self;
}

`SearchResult`

Result from similarity search.

pub struct SearchResult {
    pub pattern: Pattern,
    pub score: f32,      // Similarity score
    pub distance: f32,   // Distance metric
}

`Filter`

Metadata filtering for queries.

pub struct Filter {
    pub conditions: Vec<FilterCondition>,
}

pub struct FilterCondition {
    pub field: String,
    pub operator: FilterOperator,  // Equal, NotEqual, GreaterThan, LessThan, Contains
    pub value: MetadataValue,
}

Hypergraph Types

`Hyperedge`

N-way relation spanning multiple entities.

pub struct Hyperedge {
    pub id: HyperedgeId,
    pub entities: Vec<EntityId>,
    pub relation: Relation,
}

`TopologicalQuery`

Query specification for TDA operations.

pub enum TopologicalQuery {
    PersistentHomology {
        dimension: usize,
        epsilon_range: (f32, f32),
    },
    BettiNumbers {
        max_dimension: usize,
    },
    SheafConsistency {
        local_sections: Vec<SectionId>,
    },
}

`HyperedgeResult`

Result from topological queries.

pub enum HyperedgeResult {
    PersistenceDiagram(Vec<(f32, f32)>),  // (birth, death) pairs
    BettiNumbers(Vec<usize>),              // [β₀, β₁, β₂, ...]
    SheafConsistency(SheafConsistencyResult),
}

Temporal Types

`CausalResult`

Search result with causal and temporal context.

pub struct CausalResult {
    pub pattern: Pattern,
    pub similarity: f32,
    pub causal_distance: Option<usize>,  // Hops in causal graph
    pub temporal_distance: Duration,
    pub combined_score: f32,
}

`CausalConeType`

Causal cone constraint for queries.

pub enum CausalConeType {
    Past,                    // Only past events
    Future,                  // Only future events
    LightCone { radius: f32 }, // Relativistic constraint
}

`AnticipationHint`

Hint for predictive pre-fetching.

pub enum AnticipationHint {
    Sequential {
        last_k_patterns: Vec<PatternId>,
    },
    Temporal {
        current_phase: TemporalPhase,
    },
    Contextual {
        active_context: Vec<PatternId>,
    },
}

Federation Types

`PeerId`

Unique identifier for federation peers.

pub struct PeerId(pub String);

impl PeerId {
    pub fn generate() -> Self;
}

`FederationScope`

Scope for federated queries.

pub enum FederationScope {
    Local,                    // Query only local instance
    Direct,                   // Query direct peers
    Global { max_hops: usize }, // Multi-hop query
}

`FederatedResult`

Result from federated query.

pub struct FederatedResult {
    pub source: PeerId,
    pub data: Vec<u8>,
    pub score: f32,
    pub timestamp: u64,
}

Error Handling

All crates use a unified error model with thiserror.

`exo_core::Error`

pub enum Error {
    PatternNotFound(PatternId),
    InvalidDimension { expected: usize, got: usize },
    Backend(String),
    ConvergenceFailed,
    InvalidConfig(String),
}

pub type Result<T> = std::result::Result<T, Error>;

`exo_temporal::TemporalError`

pub enum TemporalError {
    PatternNotFound(PatternId),
    InvalidQuery(String),
    StorageError(String),
}

`exo_federation::FederationError`

pub enum FederationError {
    CryptoError(String),
    NetworkError(String),
    ConsensusError(String),
    InvalidToken,
    InsufficientPeers { needed: usize, actual: usize },
    ReconciliationError(String),
    PeerNotFound(String),
}

Migration from RuVector

EXO-AI 2025 is the next evolution of RuVector. Here's how to migrate:

Key Differences

RuVector	EXO-AI 2025
Discrete inserts	Continuous deformation
`db.insert(vector)`	`engine.deform(pattern, salience)`
Simple vector DB	Cognitive substrate
No causal tracking	Full causal graph
No hypergraph support	Full TDA + sheaf theory
Single-node only	Distributed federation

Migration Example

Before (RuVector):

use ruvector_core::{VectorDB, VectorEntry};

let db = VectorDB::new(db_options)?;

let entry = VectorEntry {
    id: Some("doc1".to_string()),
    vector: vec![1.0, 2.0, 3.0],
    metadata: Some(metadata),
};

let id = db.insert(entry)?;
let results = db.search(search_query)?;

After (EXO-AI 2025):

use exo_manifold::{ManifoldEngine, ManifoldConfig};
use exo_core::Pattern;
use burn::backend::NdArray;

let config = ManifoldConfig::default();
let mut engine = ManifoldEngine::<NdArray>::new(config, device);

let pattern = Pattern {
    id: PatternId::new(),
    embedding: vec![1.0, 2.0, 3.0],
    metadata: Metadata::default(),
    timestamp: SubstrateTime::now(),
    antecedents: vec![],
    salience: 0.9,
};

// Continuous deformation instead of discrete insert
let delta = engine.deform(pattern, 0.9)?;

// Gradient descent retrieval
let results = engine.retrieve(&query, k)?;

Backend Compatibility

For classical discrete backends (backward compatibility):

use exo_backend_classical::ClassicalBackend;
use exo_core::SubstrateBackend;

let backend = ClassicalBackend::new(config);

// Still uses discrete storage internally
backend.similarity_search(&query, k, filter)?;

// Deform becomes insert for classical backends
backend.manifold_deform(&pattern, learning_rate)?;

Performance Characteristics

Manifold Engine

Operation	Complexity	Notes
`deform()`	O(H·D)	H=hidden layers, D=dimension
`retrieve()`	O(S·H·D)	S=descent steps
`forget()`	O(P·D)	P=patterns to prune

Hypergraph

Operation	Complexity	Notes
`create_hyperedge()`	O(E)	E=entity count
`persistent_homology()`	O(N³)	N=simplex count
`betti_numbers()`	O(N²·d)	d=max dimension

Temporal Memory

Operation	Complexity	Notes
`store()`	O(1)	Short-term insert
`causal_query()`	O(log N + k)	N=total patterns
`consolidate()`	O(S·log L)	S=short-term, L=long-term

Thread Safety

All crates are thread-safe by design:

ManifoldEngine: Uses Arc<RwLock<...>>
HypergraphSubstrate: Uses DashMap (lock-free)
TemporalMemory: Uses Arc + concurrent data structures
FederatedMesh: Async-safe with tokio::sync::RwLock

Feature Flags

[features]
default = ["simd"]
simd = []           # SIMD optimizations
distributed = []    # Enable federation
gpu = []            # GPU backend support (future)
quantization = []   # Vector quantization (future)

Version History

v0.1.0 (2025-01-29): Initial release
- Manifold engine with SIREN networks
- Hypergraph substrate with TDA
- Temporal memory coordinator
- Federation with post-quantum crypto
- WASM and Node.js bindings

20 KiB Raw Blame History

EXO-AI 2025 Cognitive Substrate - API Documentation

Table of Contents

Overview

Key Features

Architecture

Core Crates

1. exo-core - Foundation

2. exo-manifold - Learned Continuous Storage

3. exo-hypergraph - Higher-Order Relations

4. exo-temporal - Temporal Memory

5. exo-federation - Distributed Mesh

6. exo-wasm - Browser Bindings

7. exo-node - Node.js Bindings

Type System

Core Types

Pattern

PatternId

SubstrateTime

SearchResult

Filter

Hypergraph Types

Hyperedge

TopologicalQuery

HyperedgeResult

Temporal Types

CausalResult

CausalConeType

AnticipationHint

Federation Types

PeerId

FederationScope

FederatedResult

Error Handling

exo_core::Error

exo_temporal::TemporalError

exo_federation::FederationError

Migration from RuVector

Key Differences

Migration Example

Backend Compatibility

Performance Characteristics

Manifold Engine

Hypergraph

Temporal Memory

Thread Safety

Feature Flags

Version History

See Also

20 KiB

Raw Blame History

`Pattern`

`PatternId`

`SubstrateTime`

`SearchResult`

`Filter`

`Hyperedge`

`TopologicalQuery`

`HyperedgeResult`

`CausalResult`

`CausalConeType`

`AnticipationHint`

`PeerId`

`FederationScope`

`FederatedResult`

`exo_core::Error`

`exo_temporal::TemporalError`

`exo_federation::FederationError`