ruvnet--ruflo/v3/plugins/prime-radiant

@claude-flow/plugin-prime-radiant

Mathematical AI that catches contradictions, verifies consensus, and prevents hallucinations before they cause problems.

What is this?

This plugin brings advanced mathematical techniques to Claude Flow for ensuring AI reliability:

• Coherence Checking - Detect when information contradicts itself before storing it
• Consensus Verification - Mathematically verify that multiple agents actually agree
• Hallucination Prevention - Catch inconsistent RAG results before they reach users
• Stability Analysis - Monitor swarm health using spectral graph theory
• Causal Inference - Understand cause-and-effect, not just correlations

Think of it as a mathematical "sanity check" layer that catches logical inconsistencies that traditional validation misses.

Installation

npm install @claude-flow/plugin-prime-radiant

---

Practical Examples

🟢 Basic: Check if Information is Consistent

Before storing facts, check if they contradict each other:

const result = await mcp.call('pr_coherence_check', {
  vectors: [
    embedding("The project deadline is Friday"),
    embedding("We have two more weeks"),
    embedding("The deadline was moved to next month")
  ],
  threshold: 0.3
});

// Result
{
  coherent: false,
  energy: 0.72,  // High energy = contradiction
  violations: ["Statement 3 contradicts statements 1-2"],
  confidence: 0.28
}

Energy levels explained:

• 0.0-0.1 = Fully consistent, safe to store
• 0.1-0.3 = Minor inconsistencies, warning zone
• 0.3-0.7 = Significant contradictions, needs review
• 0.7-1.0 = Major contradictions, reject

🟢 Basic: Verify Multi-Agent Consensus

Check if agents actually agree or just appear to:

const consensus = await mcp.call('pr_consensus_verify', {
  agentStates: [
    { agentId: 'researcher', embedding: [...], vote: true },
    { agentId: 'analyst', embedding: [...], vote: true },
    { agentId: 'reviewer', embedding: [...], vote: false }
  ],
  consensusThreshold: 0.8
});

// Result
{
  consensusAchieved: true,
  agreementRatio: 0.87,
  coherenceEnergy: 0.12,  // Low = they genuinely agree
  spectralStability: true
}

🟡 Intermediate: Analyze Swarm Stability

Monitor if your agent swarm is working together effectively:

const stability = await mcp.call('pr_spectral_analyze', {
  adjacencyMatrix: [
    [0, 1, 1, 0, 0],
    [1, 0, 1, 1, 0],
    [1, 1, 0, 1, 1],
    [0, 1, 1, 0, 1],
    [0, 0, 1, 1, 0]
  ],
  analyzeType: 'stability'
});

// Result
{
  stable: true,
  spectralGap: 0.25,      // Higher = more stable
  stabilityIndex: 0.78,
  eigenvalues: [2.73, 0.73, -0.73, -2.73, 0],
  clustering: 0.6         // How well agents cluster
}

What to watch for:

• spectralGap < 0.1 = Unstable, agents may desynchronize
• stabilityIndex < 0.5 = Warning, coordination issues likely

🟡 Intermediate: Causal Inference

Understand cause-and-effect relationships in your system:

const causal = await 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'],
      ['task_complexity', 'task_completion_time']
    ]
  }
});

// Result
{
  causalEffect: -0.35,  // Adding agents REDUCES completion time
  confounders: ['task_complexity'],  // This affects both
  interventionValid: true,
  backdoorPaths: [['agent_count', 'task_complexity', 'task_completion_time']]
}

🟠 Advanced: Memory Gate (Auto-Reject Contradictions)

Automatically block contradictory information from being stored:

const result = await mcp.call('pr_memory_gate', {
  entry: {
    key: 'project-status',
    content: 'Project is on track for Friday deadline',
    embedding: embedding("Project is on track for Friday deadline")
  },
  contextEmbeddings: [
    embedding("Deadline extended to next month"),  // Already stored
    embedding("Team requested more time")          // Already stored
  ],
  thresholds: {
    warn: 0.3,
    reject: 0.7
  }
});

// Result
{
  action: 'reject',  // Blocked from storage
  energy: 0.82,
  reason: 'Contradicts existing information about deadline',
  existingConflicts: ['Deadline extended to next month']
}

🟠 Advanced: Prevent RAG Hallucinations

Filter contradictory documents before they confuse the AI:

// Hook automatically runs before RAG retrieval
// If retrieved docs contradict each other, it filters to the most coherent subset

const context = await rag.retrieve('What is the project deadline?');

// If docs were contradictory:
{
  documents: [...],  // Filtered to consistent subset
  coherenceFiltered: true,
  originalCount: 5,
  filteredCount: 3,
  removedForCoherence: ['doc-4', 'doc-5'],
  originalCoherenceEnergy: 0.68
}

🔴 Expert: Quantum Topology Analysis

Analyze the structure of your vector space using persistent homology:

const topology = await mcp.call('pr_quantum_topology', {
  points: embeddings,  // Array of embedding vectors
  maxDimension: 2
});

// Result
{
  bettiNumbers: {
    b0: 3,   // 3 connected components (clusters)
    b1: 1,   // 1 loop (circular relationship)
    b2: 0    // No voids
  },
  persistenceDiagram: [...],  // Birth-death pairs
  significantFeatures: [
    { dimension: 0, persistence: 0.8, interpretation: 'Strong cluster' },
    { dimension: 1, persistence: 0.3, interpretation: 'Weak cyclical pattern' }
  ]
}

What this tells you:

• b0 = Number of distinct concept clusters
• b1 = Cyclical relationships (A→B→C→A)
• b2 = Higher-dimensional voids (rare in practice)

🟣 Exotic: Real-Time Swarm Health Dashboard

Monitor your multi-agent swarm in real-time:

// Run periodically to track swarm health
async function monitorSwarmHealth() {
  const adjacency = await getSwarmAdjacencyMatrix();

  const health = await mcp.call('pr_spectral_analyze', {
    adjacencyMatrix: adjacency,
    analyzeType: 'stability'
  });

  if (!health.stable) {
    console.warn('⚠️ Swarm instability detected!');
    console.log('Spectral gap:', health.spectralGap);
    console.log('Stability index:', health.stabilityIndex);

    // Trigger rebalancing
    await swarm.rebalance();
  }

  if (health.spectralGap < 0.1) {
    console.warn('⚠️ Communication breakdown risk');
    // Add redundant connections
    await swarm.addRedundancy();
  }
}

// Monitor every 30 seconds
setInterval(monitorSwarmHealth, 30000);

🟣 Exotic: Coherent Knowledge Base

Build a knowledge base that mathematically cannot contain contradictions:

class CoherentKnowledgeBase {
  async store(fact: string, embedding: number[]) {
    // Check against all existing knowledge
    const existing = await this.getAllEmbeddings();

    const check = await mcp.call('pr_coherence_check', {
      vectors: [...existing, embedding],
      threshold: 0.3
    });

    if (check.energy > 0.7) {
      throw new Error(`Fact contradicts existing knowledge: ${check.violations[0]}`);
    }

    if (check.energy > 0.3) {
      console.warn(`Warning: Minor inconsistency detected (energy: ${check.energy})`);
    }

    // Safe to store
    await this.db.store(fact, embedding, { coherenceEnergy: check.energy });
  }

  async query(question: string) {
    const results = await this.db.search(question);

    // Verify retrieved results are consistent with each other
    const embeddings = results.map(r => r.embedding);
    const coherence = await mcp.call('pr_coherence_check', {
      vectors: embeddings,
      threshold: 0.3
    });

    if (coherence.energy > 0.5) {
      // Filter to most coherent subset
      return this.filterToCoherent(results, coherence);
    }

    return results;
  }
}

---

6 Mathematical Engines

Engine	What It Does	Use Case
Cohomology	Measures contradiction using Sheaf Laplacian	Memory validation, fact-checking
Spectral	Analyzes stability via eigenvalues	Swarm health, network topology
Causal	Do-calculus for cause-effect reasoning	Root cause analysis, optimization
Quantum	Persistent homology for structure	Clustering, pattern discovery
Category	Morphism and functor operations	Schema transformations
HoTT	Homotopy Type Theory proofs	Formal verification

---

Hooks (Automatic Integration)

Hook	When It Runs	What It Does
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

# claude-flow.config.yaml
plugins:
  prime-radiant:
    enabled: true
    config:
      coherence:
        warnThreshold: 0.3    # Warn above this energy
        rejectThreshold: 0.7  # Block above this energy
        cacheEnabled: true
      spectral:
        stabilityThreshold: 0.1
        maxMatrixSize: 1000
      causal:
        maxBackdoorPaths: 10

---

Performance

Operation	Latency	Notes
Coherence check	<5ms	Per validation
Spectral analysis	<20ms	Up to 100x100 matrix
Causal inference	<10ms	Per query
Quantum topology	<50ms	Per computation
Memory overhead	<10MB	Including WASM

---

License

MIT