Skip to content

Latest commit

 

History

History
342 lines (243 loc) · 11.3 KB

README.md

File metadata and controls

342 lines (243 loc) · 11.3 KB

Prime-Radiant: Universal Coherence Engine

Advanced Mathematical Framework for AI Safety, Hallucination Detection, and Structural Consistency Verification

Prime-Radiant implements a universal coherence engine using sheaf Laplacian mathematics to provide structural consistency guarantees across domains. Rather than trying to make better predictions, Prime-Radiant proves when the world still fits together and when it does not.

Table of Contents

  1. Overview
  2. Six Mathematical Directions
  3. Installation
  4. Quick Start
  5. API Reference
  6. Performance Characteristics
  7. Use Cases
  8. Architecture

Overview

Prime-Radiant provides a single underlying coherence object that can be interpreted across multiple domains:

Domain Nodes Are Edges Are Residual Becomes Gate Becomes
AI Agents Facts, hypotheses, beliefs Citations, logical implication Contradiction energy Hallucination refusal
Finance Trades, positions, signals Market dependencies, arbitrage Regime mismatch Trading throttle
Medical Vitals, diagnoses, treatments Physiological causality Clinical disagreement Escalation trigger
Robotics Sensor readings, goals, plans Physics, kinematics Motion impossibility Safety stop
Security Identities, permissions, actions Policy rules, trust chains Authorization violation Access denial
Science Hypotheses, observations, models Experimental evidence Theory inconsistency Pruning signal

Core Mathematical Formula

The coherence energy is computed as:

E(S) = sum(w_e * ||r_e||^2)

where r_e = rho_u(x_u) - rho_v(x_v)
  • rho: Restriction map (linear transform defining how states constrain each other)
  • r_e: Residual at edge (measures local inconsistency)
  • w_e: Edge weight
  • E(S): Global incoherence measure

Six Mathematical Directions

Prime-Radiant implements six advanced mathematical frameworks for coherence analysis:

1. Sheaf Cohomology for AI Coherence

Sheaf theory provides the mathematical foundation for understanding local-to-global consistency:

  • Stalks: Fixed-dimensional state vectors at each node
  • Restriction Maps: Constraints defining how states relate
  • Global Sections: Coherent assignments across the entire graph
  • Cohomology Groups: Obstruction measures for global consistency

ADR-001: Sheaf Cohomology

2. Category Theory and Topos-Theoretic Belief Models

Functorial retrieval and higher category structures enable:

  • Functorial Retrieval: Structure-preserving knowledge access
  • Topos Models: Intuitionistic logic for belief systems
  • Higher Categories: Multi-level coherence laws
  • Natural Transformations: Systematic relationship mapping

ADR-002: Category and Topos Theory

3. Homotopy Type Theory for Verified Reasoning

HoTT provides verified reasoning with proof transport:

  • Univalence Axiom: Equivalent structures are identical
  • Path Induction: Proofs follow identity paths
  • Higher Inductive Types: Complex data structures with equalities
  • Proof Transport: Transfer proofs across equivalent structures

ADR-003: Homotopy Type Theory

4. Spectral Invariants for Cut Prediction

Spectral analysis of the sheaf Laplacian enables:

  • Cheeger Bounds: Relationship between spectral gap and graph cuts
  • Algebraic Connectivity: Second eigenvalue measures graph cohesion
  • Early Warning Systems: Detect structural weakening before failure
  • Drift Detection: Identify fundamental structural shifts

ADR-004: Spectral Invariants

5. Causal Abstraction for Consistency

Causal reasoning distinguishes correlation from causation:

  • Do-Calculus: Intervention-based causal reasoning
  • Structural Causal Models: Explicit causal relationships
  • Abstraction Verification: Ensure high-level models match low-level
  • Counterfactual Analysis: "What if" reasoning support

ADR-005: Causal Abstraction

6. Quantum Topology for Coherence Invariants

Topological methods provide robust coherence measures:

  • Persistent Homology: Multi-scale topological features
  • Betti Numbers: Counts of topological holes
  • Quantum-Inspired Encodings: Superposition-based representations
  • Stability Theorems: Robustness guarantees for features

ADR-006: Quantum Topology

Installation

Rust (Native)

Add to your Cargo.toml:

[dependencies]
prime-radiant = "0.1.0"

# Full feature set
prime-radiant = { version = "0.1.0", features = ["full"] }

Feature Flags

Feature Default Description
tiles No cognitum-gate-kernel 256-tile WASM fabric
sona No Self-optimizing threshold tuning (SONA)
learned-rho No GNN-learned restriction maps
hyperbolic No Hierarchy-aware Poincare energy
mincut No Subpolynomial n^o(1) graph partitioning
neural-gate No Biologically-inspired gating
attention No Topology-gated attention, MoE, PDE diffusion
distributed No Raft-based multi-node coherence
spectral No nalgebra-based eigenvalue computation
simd No SIMD-optimized residual calculation
gpu No wgpu-based parallel computation
ruvllm No LLM serving integration
full No All features enabled

WASM

# Install wasm-pack
cargo install wasm-pack

# Build for web
wasm-pack build --target web

# Build for Node.js
wasm-pack build --target nodejs

Quick Start

Basic Coherence Computation

use prime_radiant::prelude::*;

fn main() -> Result<(), CoherenceError> {
    // Create a sheaf graph
    let mut graph = SheafGraph::new();

    // Add nodes with state vectors
    let fact1 = SheafNode::new(vec![1.0, 0.0, 0.0, 0.5]);
    let fact2 = SheafNode::new(vec![0.9, 0.1, 0.0, 0.4]);

    let id1 = graph.add_node(fact1);
    let id2 = graph.add_node(fact2);

    // Add edge with restriction map
    let rho = RestrictionMap::identity(4);
    graph.add_edge(SheafEdge::new(id1, id2, rho.clone(), rho, 1.0))?;

    // Compute coherence energy
    let energy = graph.compute_energy();
    println!("Total coherence energy: {}", energy.total);

    Ok(())
}

Coherence Gate with Compute Ladder

use prime_radiant::{CoherenceGate, ComputeLane, EnergySnapshot};

fn main() {
    let policy = PolicyBundleRef::placeholder();
    let mut gate = CoherenceGate::with_defaults(policy);

    let energy = EnergySnapshot::new(0.15, 0.12, ScopeId::new("test"));
    let (decision, witness) = gate.evaluate_with_witness(&action, &energy);

    match decision.lane {
        ComputeLane::Reflex => println!("Approved (<1ms)"),
        ComputeLane::Retrieval => println!("Evidence needed (~10ms)"),
        ComputeLane::Heavy => println!("Heavy processing (~100ms)"),
        ComputeLane::Human => println!("Human review required"),
    }
}

Spectral Drift Detection

use prime_radiant::coherence::{SpectralAnalyzer, SpectralConfig};

let mut analyzer = SpectralAnalyzer::new(SpectralConfig::default());

analyzer.record_eigenvalues(vec![0.0, 0.5, 1.2, 2.1]);
analyzer.record_eigenvalues(vec![0.0, 0.3, 0.9, 1.8]); // Drift!

if let Some(drift) = analyzer.detect_drift() {
    println!("Drift: {:?}, severity: {:?}", drift.description, drift.severity);
}

API Reference

Core Types

Type Description
SheafGraph Graph with nodes, edges, and restriction maps
SheafNode Vertex with state vector (stalk)
SheafEdge Edge with restriction maps and weight
RestrictionMap Linear transform for state constraints
CoherenceEnergy Global incoherence measure
CoherenceGate Threshold-based action gating
GateDecision Allow/deny with compute lane
WitnessRecord Immutable audit record

Compute Ladder

Lane Latency Use Case
Reflex <1ms Low-energy automatic approval
Retrieval ~10ms Evidence fetching
Heavy ~100ms Multi-step planning
Human Unbounded Sustained incoherence review

Performance Characteristics

Operation Target
Single residual < 1us
Full energy (10K nodes) < 10ms
Incremental update < 100us
Gate evaluation < 500us
SONA adaptation < 0.05ms
MinCut update n^o(1) subpolynomial
Hyperbolic distance < 500ns

Use Cases

  • AI Safety: Detect hallucinations via structural inconsistency
  • Finance: Regime change detection and arbitrage validation
  • Medical: Clinical decision consistency verification
  • Robotics: Kinematic constraint enforcement
  • Security: Policy rule coherence checking

Architecture

+-----------------------------------------------------------------------------+
|                           APPLICATION LAYER                                  |
|  LLM Guards | Fraud Detection | Compliance Proofs | Robotics Safety         |
+-----------------------------------------------------------------------------+
                                    |
+-----------------------------------------------------------------------------+
|                           COHERENCE GATE                                     |
|  Lane 0 (Reflex) | Lane 1 (Retrieval) | Lane 2 (Heavy) | Lane 3 (Human)     |
+-----------------------------------------------------------------------------+
                                    |
+-----------------------------------------------------------------------------+
|                           COHERENCE COMPUTATION                              |
|  Residual Calculator | Energy Aggregator | Spectral Analyzer                |
+-----------------------------------------------------------------------------+
                                    |
+-----------------------------------------------------------------------------+
|                           KNOWLEDGE SUBSTRATE                                |
|  Sheaf Graph | Node States | Edge Constraints | Restriction Maps           |
+-----------------------------------------------------------------------------+

Documentation

References

  1. Hansen, J., & Ghrist, R. (2019). "Toward a spectral theory of cellular sheaves."
  2. Robinson, M. (2014). "Topological Signal Processing."
  3. Curry, J. (2014). "Sheaves, Cosheaves and Applications."
  4. Univalent Foundations Program. "Homotopy Type Theory."

License

MIT OR Apache-2.0

Prime-Radiant: Where mathematics meets machine safety.