Advanced mathematical AI interpretability: Category Theory, Homotopy Type Theory, Spectral Analysis, Causal Inference, Quantum Topology, and Sheaf Cohomology for WebAssembly. Implements functorial retrieval, univalence axioms, Cheeger bounds, do-calculus,
npm install prime-radiant-advanced-wasm
Prime-Radiant is infrastructure for AI safety — a mathematical gate that proves whether a system's beliefs, facts, and claims are internally consistent before allowing action.
Instead of asking "How confident am I?" (which can be wrong), Prime-Radiant asks "Are there any contradictions?" — and provides mathematical proof of the answer.
``
┌─────────────────────────────────────────────────────────────────┐
│ "The meeting is at 3pm" ←──────→ "The meeting is at 4pm" │
│ (Memory A) ✗ (Memory B) │
│ │
│ Energy = 0.92 → HIGH INCOHERENCE → Block / Escalate │
└─────────────────────────────────────────────────────────────────┘
| Traditional AI | Prime-Radiant |
|----------------|---------------|
| "I'm 95% confident" (but wrong) | "These facts contradict each other" (provably) |
| Hallucinations pass through | Contradictions get caught |
| Trust the model's self-assessment | Trust mathematical invariants |
| Fails silently | Fails loudly with proof |
The core insight: Confidence scores lie. Coherence scores don't.
An LLM can be 99% confident while citing contradictory sources. Prime-Radiant catches this by measuring the mathematical structure of the information, not the model's opinion about it.
`
┌─────────────────────────────────────────────────────────────────┐
│ PRIME-RADIANT PIPELINE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Input Coherence Decision Output │
│ ───── ───────── ──────── ────── │
│ │
│ Memories → Sheaf → Energy → ✓ Proceed │
│ Facts Laplacian < 0.3 (coherent) │
│ Claims │
│ Energy → ✗ Block │
│ > 0.7 (contradicts) │
│ │
│ Energy → ⚠ Escalate │
│ 0.3-0.7 (uncertain) │
│ │
└─────────────────────────────────────────────────────────────────┘
The Sheaf Laplacian measures how well local information "glues together" globally. High energy = information doesn't fit together = contradiction detected.
`bash`
npm install prime-radiant-advanced-wasm
`javascript
import init, { CohomologyEngine } from 'prime-radiant-advanced-wasm';
await init();
// Create a coherence gate for 768-dimensional embeddings
const gate = new CohomologyEngine(768);
// Add facts/memories as nodes with their embeddings
gate.add_node('fact1', embed("The meeting is scheduled for 3pm"));
gate.add_node('fact2', embed("John confirmed 3pm works for him"));
gate.add_node('fact3', embed("The meeting was moved to 4pm")); // Contradiction!
// Connect related facts
gate.add_edge('fact1', 'fact2', 0.9); // High similarity
gate.add_edge('fact2', 'fact3', 0.7); // Related but conflicting
gate.add_edge('fact1', 'fact3', 0.3); // Low similarity (contradiction signal)
// Compute coherence energy
const energy = gate.sheaf_laplacian_energy();
// Make gated decision
if (energy < 0.3) {
console.log('✓ COHERENT - Safe to proceed');
executeAction();
} else if (energy > 0.7) {
console.log('✗ INCOHERENT - Blocking action');
console.log(' Contradiction detected. Escalating to human review.');
escalateToHuman();
} else {
console.log('⚠ UNCERTAIN - Requesting clarification');
requestMoreContext();
}
`
Problem: Your RAG system retrieves contradictory documents and the LLM confidently synthesizes nonsense.
`javascript
const gate = new CohomologyEngine(768);
// After retrieval, before generation
retrievedDocs.forEach((doc, i) => {
gate.add_node(doc${i}, doc.embedding);
});
// Build coherence graph
for (let i = 0; i < retrievedDocs.length; i++) {
for (let j = i + 1; j < retrievedDocs.length; j++) {
gate.add_edge(doc${i}, doc${j}, cosineSim(docs[i], docs[j]));
}
}
const energy = gate.sheaf_laplacian_energy();
if (energy > 0.5) {
// Don't generate from contradictory sources!
return "I found conflicting information. Let me clarify: [show conflicts]";
}
`
Problem: Your agent swarm reached "consensus" but agents actually disagree.
`javascript
const gate = new CohomologyEngine(768);
// Each agent's conclusion as a node
agents.forEach(agent => {
gate.add_node(agent.id, embed(agent.conclusion));
});
// Connect agents that communicated
communications.forEach(comm => {
gate.add_edge(comm.from, comm.to, comm.agreementScore);
});
const energy = gate.sheaf_laplacian_energy();
if (energy > 0.4) {
console.log('⚠ FALSE CONSENSUS - Agents have hidden disagreements');
// Force explicit reconciliation before proceeding
}
`
Problem: Your agent's memories drift and contradict over time.
`javascript
const gate = new CohomologyEngine(768);
// Periodically audit agent memory
agent.memories.forEach((memory, i) => {
gate.add_node(mem${i}, memory.embedding);
});
// Connect temporally adjacent memories
for (let i = 0; i < memories.length - 1; i++) {
gate.add_edge(mem${i}, mem${i+1}, temporalSimilarity(i, i+1));
}
const energy = gate.sheaf_laplacian_energy();
if (energy > 0.6) {
console.log('⚠ MEMORY DRIFT - Agent beliefs have become inconsistent');
// Trigger memory consolidation or reset
}
`
Problem: Sensor fusion produces conflicting interpretations.
`javascript
const gate = new CohomologyEngine(128);
// Each sensor's interpretation
gate.add_node('lidar', embed(lidarInterpretation));
gate.add_node('camera', embed(cameraInterpretation));
gate.add_node('radar', embed(radarInterpretation));
// Sensor agreement edges
gate.add_edge('lidar', 'camera', lidarCameraAgreement);
gate.add_edge('camera', 'radar', cameraRadarAgreement);
gate.add_edge('lidar', 'radar', lidarRadarAgreement);
const energy = gate.sheaf_laplacian_energy();
if (energy > 0.5) {
// STOP - sensors disagree about the environment
emergencyBrake();
}
`
Prime-Radiant provides 6 mathematical engines for AI safety:
| Engine | What It Detects | Safety Application |
|--------|-----------------|-------------------|
| CohomologyEngine | Contradictions in beliefs/facts | Gate actions on consistency |
| SpectralEngine | System instability | Predict failures before they happen |
| CausalEngine | Spurious correlations | Ensure decisions are causally grounded |
| QuantumEngine | Structural anomalies | Detect out-of-distribution inputs |
| CategoryEngine | Type mismatches | Verify pipeline correctness |
| HottEngine | Logical inconsistencies | Formal verification of reasoning |
| Approach | Method | Limitation | Prime-Radiant Advantage |
|----------|--------|------------|------------------------|
| Confidence Thresholds | Reject if P < 0.8 | Confident errors pass | Catches contradictions regardless of confidence |
| Output Filtering | Block bad outputs | Reactive, not preventive | Prevents bad reasoning upstream |
| RLHF | Train away bad behavior | Can be fooled/jailbroken | Mathematical invariants can't be talked around |
| Constitutional AI | Self-critique | Model critiques itself | External mathematical proof |
| Ensemble Voting | Majority wins | Correlated failures | Detects hidden disagreement structure |
| Feature | prime-radiant | LangChain | LlamaIndex | Custom |
|---------|--------------|-----------|------------|--------|
| Coherence detection | Native (Sheaf theory) | None | None | Manual |
| Contradiction proofs | Mathematical | Heuristic | Heuristic | Varies |
| Collapse prediction | Spectral analysis | None | None | Manual |
| Bundle size | 92 KB | 2MB+ | 1.5MB+ | Varies |
| Zero dependencies | Yes | No | No | Varies |
| Runs in browser | WASM | Node only | Node only | Varies |
`javascript
const gate = new CohomologyEngine(embeddingDim);
// Build the coherence graph
gate.add_node(id, embedding); // Add a fact/belief/memory
gate.add_edge(from, to, similarity); // Connect related items
// Measure coherence
gate.sheaf_laplacian_energy(); // 0 = perfect coherence, 1 = total contradiction
gate.compute_cohomology_dimension(1); // Count of "holes" (unresolvable conflicts)
`
`javascript
const monitor = new SpectralEngine();
monitor.add_node(id);
monitor.add_edge(from, to, strength);
monitor.predict_collapse_risk(); // 0-1 risk score
monitor.compute_fiedler_value(); // Connectivity strength
monitor.compute_cheeger_constant(); // Partition resistance
`
`javascript
const causal = new CausalEngine();
causal.add_variable(name, isObserved);
causal.add_causal_edge(cause, effect);
causal.is_identifiable(treatment, outcome); // Can we measure this effect?
causal.get_adjustment_set(treatment, outcome); // What to control for
causal.compute_ate(treatment, outcome); // Actual causal effect
`
`javascript
const topology = new QuantumEngine();
topology.add_point(coordinates);
topology.get_betti_numbers(scale); // [components, holes, voids]
topology.compute_persistence(maxDim); // Feature lifetimes
`
Full Tutorial: Building a Coherence-Gated Agent
`javascript
import init, { CohomologyEngine, SpectralEngine } from 'prime-radiant-advanced-wasm';
await init();
class CoherenceGatedAgent {
constructor(embeddingDim = 768) {
this.coherenceGate = new CohomologyEngine(embeddingDim);
this.stabilityMonitor = new SpectralEngine();
this.memories = [];
this.thresholds = {
coherence: 0.4, // Block if energy > this
stability: 0.6, // Alert if risk > this
};
}
// Add a new memory/belief
remember(content, embedding) {
const id = mem_${this.memories.length};
this.memories.push({ id, content, embedding, timestamp: Date.now() });
// Rebuild coherence graph
this.rebuildCoherenceGraph();
// Check if this memory creates contradictions
const energy = this.coherenceGate.sheaf_laplacian_energy();
if (energy > this.thresholds.coherence) {
console.warn(⚠ New memory creates contradiction (energy: ${energy.toFixed(3)}));
return { accepted: false, reason: 'contradiction', energy };
}
return { accepted: true, energy };
}
rebuildCoherenceGraph() {
this.coherenceGate = new CohomologyEngine(768);
// Add all memories as nodes
this.memories.forEach(mem => {
this.coherenceGate.add_node(mem.id, mem.embedding);
});
// Connect memories by similarity
for (let i = 0; i < this.memories.length; i++) {
for (let j = i + 1; j < this.memories.length; j++) {
const sim = this.cosineSim(
this.memories[i].embedding,
this.memories[j].embedding
);
if (sim > 0.2) {
this.coherenceGate.add_edge(
this.memories[i].id,
this.memories[j].id,
sim
);
}
}
}
}
// Gate an action on coherence
async act(action, context) {
// Build context graph
const contextGate = new CohomologyEngine(768);
context.facts.forEach((fact, i) => {
contextGate.add_node(fact_${i}, fact.embedding);
});
for (let i = 0; i < context.facts.length; i++) {
for (let j = i + 1; j < context.facts.length; j++) {
const sim = this.cosineSim(
context.facts[i].embedding,
context.facts[j].embedding
);
contextGate.add_edge(fact_${i}, fact_${j}, sim);
}
}
const energy = contextGate.sheaf_laplacian_energy();
// GATE DECISION
if (energy > this.thresholds.coherence) {
return {
executed: false,
reason: 'Context contains contradictions',
energy,
recommendation: 'Resolve conflicts before proceeding'
};
}
// Safe to proceed
const result = await action();
return {
executed: true,
result,
energy,
coherenceVerified: true
};
}
// Periodic health check
healthCheck() {
const energy = this.coherenceGate.sheaf_laplacian_energy();
const holes = this.coherenceGate.compute_cohomology_dimension(1);
return {
status: energy < 0.3 ? 'healthy' : energy < 0.6 ? 'warning' : 'critical',
coherenceEnergy: energy,
contradictionCount: holes,
memoryCount: this.memories.length,
recommendation: this.getRecommendation(energy, holes)
};
}
getRecommendation(energy, holes) {
if (energy > 0.7) {
return 'CRITICAL: Multiple contradictions detected. Memory consolidation required.';
}
if (holes > 0) {
return WARNING: ${holes} unresolvable conflict(s) in memory. Review flagged memories.;
}
if (energy > 0.4) {
return 'CAUTION: Some tension in beliefs. Monitor for drift.';
}
return 'All systems nominal.';
}
cosineSim(a, b) {
let dot = 0, normA = 0, normB = 0;
for (let i = 0; i < a.length; i++) {
dot += a[i] * b[i];
normA += a[i] * a[i];
normB += b[i] * b[i];
}
return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}
}
// Usage
const agent = new CoherenceGatedAgent();
// Add memories
agent.remember("The project deadline is Friday", embedFriday);
agent.remember("John is leading the project", embedJohn);
// This will be flagged as contradictory:
const result = agent.remember("The project deadline is next Monday", embedMonday);
// result.accepted = false, result.reason = 'contradiction'
// Gate an action
const actionResult = await agent.act(
() => sendEmail("Reminder: deadline Friday"),
{ facts: [fridayDeadline, johnLeading] }
);
// actionResult.executed = true (coherent context)
// Health check
const health = agent.healthCheck();
// health.status = 'warning', health.recommendation = '...'
`
Mathematical Foundation
A sheaf assigns vector spaces to nodes and linear maps to edges. For AI:
- Nodes = facts, memories, beliefs (as embeddings)
- Edges = relationships between them
- Sheaf maps = how information should transform across relationships
The Sheaf Laplacian L_F generalizes the graph Laplacian:
`
L_F = δδ + δδ
where δ is the coboundary operator
`
Key insight: The quadratic form x^T L_F x measures how much the data fails to be globally consistent.
- Energy = 0: Perfect coherence. All local data glues together.
- Energy > 0: Incoherence. Some information doesn't match up.
- High energy: Major contradictions. Information fundamentally conflicts.
Traditional approaches check pairwise similarity:
`
"Is A similar to B?" → Yes
"Is B similar to C?" → Yes
Therefore coherent? → NOT NECESSARILY
The sheaf approach checks global consistency:
`
"Does A→B→C→A form a consistent cycle?" → No! (A→C might conflict)
This catches transitive contradictions that pairwise methods miss.
The cohomology groups H^n detect "holes" in coherence:
- H^0: Connected components (fragmented beliefs)
- H^1: Cycles that don't close (circular contradictions)
- H^2: Higher-order inconsistencies
A non-zero H^1 dimension means there's a fundamental contradiction that can't be resolved by local adjustments.
| Operation | 10 items | 100 items | 1,000 items |
|-----------|----------|-----------|-------------|
| Coherence gate | <1ms | ~2ms | ~15ms |
| Full analysis | ~1ms | ~5ms | ~40ms |
Fast enough for real-time gating of every LLM call.
| Environment | Support |
|-------------|---------|
| Chrome 57+ | Full |
| Firefox 52+ | Full |
| Safari 11+ | Full |
| Edge 16+ | Full |
| Node.js 12+ | Full |
| Deno | Full |
| Cloudflare Workers | Full |
- ruvector — High-performance vector operations
- ruvector-attention-wasm — Attention mechanisms
MIT OR Apache-2.0
Issues and PRs welcome at github.com/ruvnet/ruvector
---
"Don't trust confidence. Trust coherence."