---
name: prime-radiant
description: Mathematical AI interpretability with sheaf cohomology, spectral analysis, causal inference, and hallucination prevention
---

# Prime Radiant -- Mathematical AI Interpretability and Coherence

Mathematical AI plugin that catches contradictions, verifies consensus, and prevents hallucinations using six mathematical engines: sheaf cohomology, spectral analysis, causal inference, quantum topology, category theory, and homotopy type theory. Provides automatic hooks for memory gating, consensus validation, swarm stability, and RAG filtering.

## Purpose

Add a mathematical sanity-check layer that catches logical inconsistencies traditional validation misses. Detect contradictory information before storage, mathematically verify multi-agent consensus, filter inconsistent RAG results, monitor swarm health via spectral graph theory, and understand cause-and-effect via do-calculus.

## MCP Tools (6)

### 1. pr_coherence_check

Measure contradiction in a set of vectors using Sheaf Laplacian energy. Energy levels: 0.0-0.1 (consistent), 0.1-0.3 (minor inconsistencies), 0.3-0.7 (significant contradictions), 0.7-1.0 (major contradictions).

```typescript
mcp.call('pr_coherence_check', {
  vectors: [embedding("deadline is Friday"), embedding("two more weeks"), embedding("moved to next month")],
  threshold: 0.3
});
// Returns: { coherent: false, energy: 0.72, violations: [...], confidence: 0.28 }
```

### 2. pr_consensus_verify

Verify that multiple agents genuinely agree using coherence energy and spectral stability analysis.

```typescript
mcp.call('pr_consensus_verify', {
  agentStates: [
    { agentId: 'researcher', embedding: [...], vote: true },
    { agentId: 'analyst', embedding: [...], vote: true },
    { agentId: 'reviewer', embedding: [...], vote: false }
  ],
  consensusThreshold: 0.8
});
// Returns: { consensusAchieved: true, agreementRatio: 0.87, coherenceEnergy: 0.12, spectralStability: true }
```

### 3. pr_spectral_analyze

Analyze swarm stability using eigenvalues of the adjacency matrix. Watch spectralGap (higher = more stable) and stabilityIndex (below 0.5 = warning).

```typescript
mcp.call('pr_spectral_analyze', {
  adjacencyMatrix: [[0,1,1,0],[1,0,1,1],[1,1,0,1],[0,1,1,0]],
  analyzeType: 'stability'
});
// Returns: { stable: true, spectralGap: 0.25, stabilityIndex: 0.78, eigenvalues: [...], clustering: 0.6 }
```

### 4. pr_causal_infer

Understand cause-and-effect using do-calculus. Identifies confounders, validates interventions, and traces backdoor paths.

```typescript
mcp.call('pr_causal_infer', {
  treatment: 'agent_count',
  outcome: 'task_completion_time',
  graph: {
    nodes: ['agent_count', 'coordination_overhead', 'task_completion_time', 'task_complexity'],
    edges: [['agent_count', 'task_completion_time'], ['agent_count', 'coordination_overhead'],
            ['coordination_overhead', 'task_completion_time'], ['task_complexity', 'agent_count']]
  }
});
// Returns: { causalEffect: -0.35, confounders: ['task_complexity'], interventionValid: true }
```

### 5. pr_memory_gate

Automatically block contradictory information from being stored. Uses coherence check against existing context embeddings with configurable warn/reject thresholds.

```typescript
mcp.call('pr_memory_gate', {
  entry: { key: 'project-status', content: 'On track for Friday', embedding: [...] },
  contextEmbeddings: [embedding("Deadline extended to next month")],
  thresholds: { warn: 0.3, reject: 0.7 }
});
// Returns: { action: 'reject', energy: 0.82, reason: 'Contradicts existing information' }
```

### 6. pr_quantum_topology

Analyze vector space structure using persistent homology. Betti numbers reveal clusters (b0), cyclical relationships (b1), and voids (b2).

```typescript
mcp.call('pr_quantum_topology', {
  points: embeddings,
  maxDimension: 2
});
// Returns: { bettiNumbers: { b0: 3, b1: 1, b2: 0 }, persistenceDiagram: [...], significantFeatures: [...] }
```

## 6 Mathematical Engines

| Engine | Technique | Use Case |
|--------|-----------|----------|
| Cohomology | Sheaf Laplacian | Memory validation, fact-checking |
| Spectral | Eigenvalue analysis | Swarm health, network topology |
| Causal | Do-calculus | Root cause analysis, optimization |
| Quantum | Persistent homology | Clustering, pattern discovery |
| Category | Morphism and functor operations | Schema transformations |
| HoTT | Homotopy Type Theory proofs | Formal verification |

## Hooks (Automatic Integration)

| Hook | Trigger | Effect |
|------|---------|--------|
| pr/pre-memory-store | Before memory storage | Blocks contradictory entries |
| pr/pre-consensus | Before consensus voting | Validates proposal consistency |
| pr/post-swarm-task | After swarm tasks | Analyzes stability metrics |
| pr/pre-rag-retrieval | Before RAG results | Filters inconsistent documents |

## Configuration

```yaml
plugins:
  prime-radiant:
    config:
      coherence:
        warnThreshold: 0.3
        rejectThreshold: 0.7
        cacheEnabled: true
      spectral:
        stabilityThreshold: 0.1
        maxMatrixSize: 1000
      causal:
        maxBackdoorPaths: 10
```

## Performance

| Operation | Latency |
|-----------|---------|
| Coherence check | <5ms |
| Spectral analysis | <20ms (up to 100x100 matrix) |
| Causal inference | <10ms |
| Quantum topology | <50ms |
| Memory overhead | <10MB including WASM |