JSPM

prime-radiant-advanced-wasm

0.1.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 575
  • Score
    100M100P100Q108903F
  • License MIT OR Apache-2.0

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, persistent homology, and coboundary operators.

Package Exports

  • prime-radiant-advanced-wasm
  • prime-radiant-advanced-wasm/prime_radiant_advanced_wasm.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (prime-radiant-advanced-wasm) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

prime-radiant-advanced-wasm

npm version License WebAssembly TypeScript

Fix hallucinations, detect system failures before they happen, and answer "why" questions in your AI applications.

The Problem

Building production AI systems is hard. You face:

Problem What Happens Business Impact
RAG returns irrelevant docs ChatBot answers with unrelated information Users lose trust, support tickets increase
LLM hallucinations Model confidently states false information Legal liability, reputation damage
Multi-agent chaos Agents contradict each other, system spirals Complete system failure, data corruption
"Why did it do that?" No way to explain AI decisions Compliance failures, debugging nightmares
Silent degradation System slowly gets worse, no alerts Gradual user churn, missed SLAs

The Solution

Prime-Radiant uses battle-tested mathematics (not heuristics) to solve these problems:

┌─────────────────────────────────────────────────────────────────┐
│  Your AI Application                                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   [RAG Pipeline] ──→ CohomologyEngine ──→ "These 3 docs don't  │
│                                            belong together"     │
│                                                                 │
│   [Agent Swarm] ──→ SpectralEngine ──→ "System will fail in    │
│                                         ~2 minutes, add node"   │
│                                                                 │
│   [Decision Made] ──→ CausalEngine ──→ "Output caused by X,    │
│                                         not Y as suspected"     │
│                                                                 │
│   [Embeddings] ──→ QuantumEngine ──→ "Data has 3 clusters      │
│                                       with 1 outlier group"     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Comparison: Before vs After

Scenario Traditional Approach With Prime-Radiant
RAG coherence check Cosine similarity > 0.7 (misses context drift) Sheaf Laplacian detects semantic inconsistency even when embeddings are similar
System health monitoring CPU/memory metrics (reactive) Spectral analysis predicts collapse 2-5 min before it happens
Explainability "Top 3 features were X, Y, Z" (correlations) Causal graph shows actual cause-effect chains
Anomaly detection Statistical outliers (misses structural issues) Topological analysis finds "holes" in your data coverage
Pipeline validation Unit tests (doesn't catch composition bugs) Category theory proves transformations compose correctly

Comparison: This Package vs Alternatives

Feature prime-radiant-wasm TensorFlow.js Brain.js ml5.js
Coherence detection Native sheaf theory Manual implementation No No
Collapse prediction Spectral + Cheeger No No No
Causal inference Full do-calculus No No No
Topological analysis Persistent homology Limited No No
WASM performance Native Rust Partial No No
Bundle size 92 KB 1.2 MB+ 200 KB 500 KB+
Zero dependencies Yes No No No
TypeScript types Full Full Partial Partial

Real-World Use Cases

1. RAG Quality Gate

Problem: Your RAG returns 5 documents, but 2 are about completely different topics.

import init, { CohomologyEngine } from 'prime-radiant-advanced-wasm';
await init();

const checker = new CohomologyEngine(768);

// Add your retrieved documents
retrievedDocs.forEach((doc, i) => {
  checker.add_node(`doc${i}`, doc.embedding);
});

// Connect sequential docs
for (let i = 0; i < retrievedDocs.length - 1; i++) {
  checker.add_edge(`doc${i}`, `doc${i+1}`, cosineSim(docs[i], docs[i+1]));
}

// Check coherence
const energy = checker.sheaf_laplacian_energy();

if (energy > 0.5) {
  console.warn('Retrieved docs are incoherent - triggering re-retrieval');
  // Re-retrieve with stricter filters
}

2. Multi-Agent Health Monitor

Problem: Your 10-agent swarm occasionally deadlocks or produces garbage.

import init, { SpectralEngine } from 'prime-radiant-advanced-wasm';
await init();

const monitor = new SpectralEngine();

// Build communication graph
agents.forEach(a => monitor.add_node(a.id));
communications.forEach(c => monitor.add_edge(c.from, c.to, c.messageCount));

// Check every 30 seconds
setInterval(() => {
  const risk = monitor.predict_collapse_risk();

  if (risk > 0.7) {
    alert(`CRITICAL: ${(risk * 100).toFixed(0)}% collapse risk`);
    // Auto-remediation: spawn backup agent, redistribute load
  } else if (risk > 0.4) {
    console.warn(`Warning: System stress at ${(risk * 100).toFixed(0)}%`);
  }
}, 30000);

3. Explainable AI Decisions

Problem: User asks "Why did the model recommend Product X?"

import init, { CausalEngine } from 'prime-radiant-advanced-wasm';
await init();

const explainer = new CausalEngine();

// Define your recommendation factors
explainer.add_variable('BrowsingHistory', true);
explainer.add_variable('Demographics', true);
explainer.add_variable('PastPurchases', true);
explainer.add_variable('Recommendation', true);

// Define causal relationships (from your domain knowledge)
explainer.add_causal_edge('BrowsingHistory', 'Recommendation');
explainer.add_causal_edge('Demographics', 'BrowsingHistory');
explainer.add_causal_edge('PastPurchases', 'Recommendation');

// Get explanation
const adjustSet = explainer.get_adjustment_set('BrowsingHistory', 'Recommendation');
// Returns: ["Demographics"] - control for this to isolate browsing effect

const effect = explainer.compute_ate('BrowsingHistory', 'Recommendation');
// Returns: 0.73 - browsing history accounts for 73% of recommendation

4. Embedding Space Quality Check

Problem: Your fine-tuned embeddings might have "dead zones" where nothing maps.

import init, { QuantumEngine } from 'prime-radiant-advanced-wasm';
await init();

const analyzer = new QuantumEngine();

// Sample your embedding space
sampleEmbeddings.forEach(emb => analyzer.add_point(emb));

// Compute topological features
const betti = analyzer.get_betti_numbers(0.3);

console.log(`Connected components: ${betti[0]}`);  // Should be 1 for good embeddings
console.log(`Holes/gaps: ${betti[1]}`);            // Should be 0 for dense coverage

if (betti[0] > 1) {
  console.warn('Embedding space is fragmented - consider more training data');
}
if (betti[1] > 0) {
  console.warn('Embedding space has gaps - some concepts may not be represented');
}

Installation

npm install prime-radiant-advanced-wasm

Quick Start

import init, {
  CohomologyEngine,
  SpectralEngine,
  CausalEngine,
  QuantumEngine,
  CategoryEngine,
  HottEngine
} from 'prime-radiant-advanced-wasm';

// Initialize WASM module (required once)
await init();

// Create engines as needed
const coherence = new CohomologyEngine(768);  // For 768-dim embeddings
const stability = new SpectralEngine();
const causality = new CausalEngine();
const topology = new QuantumEngine();

Engine Overview

Engine What It Does When To Use
CohomologyEngine Measures if data "fits together" semantically RAG quality gates, context window validation
SpectralEngine Predicts system stability/collapse Multi-agent monitoring, distributed system health
CausalEngine Traces cause-effect relationships Explainability, debugging, A/B test analysis
QuantumEngine Finds structural patterns in high-dim data Embedding QA, clustering validation, anomaly detection
CategoryEngine Validates transformation pipelines Pipeline correctness, type-safe data flow
HottEngine Formal verification of equivalences Proof-carrying code, migration validation

API Reference

CohomologyEngine

const engine = new CohomologyEngine(embeddingDim);

engine.add_node(id, embedding);           // Add a data point
engine.add_edge(from, to, similarity);    // Connect related points
engine.sheaf_laplacian_energy();          // Get coherence score (lower = more coherent)
engine.compute_cohomology_dimension(1);   // Get "hole count" at dimension

SpectralEngine

const engine = new SpectralEngine();

engine.add_node(id);                      // Add a system component
engine.add_edge(from, to, strength);      // Add connection
engine.predict_collapse_risk();           // Get risk score 0-1
engine.compute_fiedler_value();           // Get connectivity strength
engine.compute_cheeger_constant();        // Get partition resistance

CausalEngine

const engine = new CausalEngine();

engine.add_variable(name, isObserved);    // Add a variable
engine.add_causal_edge(cause, effect);    // Define causal link
engine.is_identifiable(treatment, outcome); // Can we measure this effect?
engine.get_adjustment_set(treatment, outcome); // What to control for
engine.compute_ate(treatment, outcome);   // Get causal effect size

QuantumEngine

const engine = new QuantumEngine();

engine.add_point(coordinates);            // Add a point (any dimension)
engine.get_betti_numbers(scale);          // Get topological features
engine.compute_persistence(maxDim);       // Get birth/death of features

Full Tutorials

Tutorial 1: Complete RAG Pipeline with Coherence Checking

import init, { CohomologyEngine } from 'prime-radiant-advanced-wasm';

await init();

class CoherentRAG {
  constructor(embeddingDim = 768) {
    this.checker = new CohomologyEngine(embeddingDim);
    this.threshold = 0.5;
  }

  async retrieve(query, vectorDB, k = 5) {
    // Get candidates from vector DB
    const candidates = await vectorDB.search(query, k * 2);

    // Build coherence graph
    this.checker = new CohomologyEngine(768); // Reset
    candidates.forEach((doc, i) => {
      this.checker.add_node(`doc${i}`, doc.embedding);
    });

    // Connect by similarity
    for (let i = 0; i < candidates.length; i++) {
      for (let j = i + 1; j < candidates.length; j++) {
        const sim = this.cosineSim(candidates[i].embedding, candidates[j].embedding);
        if (sim > 0.3) {
          this.checker.add_edge(`doc${i}`, `doc${j}`, sim);
        }
      }
    }

    // Check coherence
    const energy = this.checker.sheaf_laplacian_energy();

    if (energy > this.threshold) {
      // Incoherent - find the most connected subset
      return this.findCoherentSubset(candidates, k);
    }

    return candidates.slice(0, k);
  }

  findCoherentSubset(candidates, k) {
    // Greedy: start with best match, add only coherent docs
    const result = [candidates[0]];

    for (let i = 1; i < candidates.length && result.length < k; i++) {
      const testSet = [...result, candidates[i]];

      // Check if adding this doc maintains coherence
      this.checker = new CohomologyEngine(768);
      testSet.forEach((doc, j) => this.checker.add_node(`doc${j}`, doc.embedding));

      for (let a = 0; a < testSet.length; a++) {
        for (let b = a + 1; b < testSet.length; b++) {
          const sim = this.cosineSim(testSet[a].embedding, testSet[b].embedding);
          this.checker.add_edge(`doc${a}`, `doc${b}`, sim);
        }
      }

      if (this.checker.sheaf_laplacian_energy() <= this.threshold) {
        result.push(candidates[i]);
      }
    }

    return result;
  }

  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 rag = new CoherentRAG();
const docs = await rag.retrieve("What is machine learning?", myVectorDB);

Tutorial 2: Multi-Agent System Monitor

import init, { SpectralEngine } from 'prime-radiant-advanced-wasm';

await init();

class SwarmMonitor {
  constructor() {
    this.engine = new SpectralEngine();
    this.agents = new Map();
    this.history = [];
  }

  registerAgent(agentId) {
    this.agents.set(agentId, { messages: 0, lastSeen: Date.now() });
    this.rebuildGraph();
  }

  recordCommunication(fromAgent, toAgent) {
    this.agents.get(fromAgent).messages++;
    this.agents.get(toAgent).lastSeen = Date.now();
    this.rebuildGraph();
  }

  rebuildGraph() {
    this.engine = new SpectralEngine();

    for (const [id, data] of this.agents) {
      this.engine.add_node(id);
    }

    // Add edges based on communication patterns
    // (In real app, track actual message flows)
    for (const [id1] of this.agents) {
      for (const [id2] of this.agents) {
        if (id1 < id2) {
          this.engine.add_edge(id1, id2, 1.0);
        }
      }
    }
  }

  getHealthReport() {
    const risk = this.engine.predict_collapse_risk();
    const fiedler = this.engine.compute_fiedler_value();
    const cheeger = this.engine.compute_cheeger_constant();

    this.history.push({ time: Date.now(), risk, fiedler, cheeger });

    // Keep last hour
    const oneHourAgo = Date.now() - 3600000;
    this.history = this.history.filter(h => h.time > oneHourAgo);

    // Detect trend
    const trend = this.history.length > 10
      ? (this.history[this.history.length - 1].risk - this.history[0].risk) / this.history.length
      : 0;

    return {
      status: risk < 0.3 ? 'healthy' : risk < 0.6 ? 'warning' : 'critical',
      collapseRisk: risk,
      connectivity: fiedler,
      partitionResistance: cheeger,
      trend: trend > 0.01 ? 'degrading' : trend < -0.01 ? 'improving' : 'stable',
      recommendation: this.getRecommendation(risk, fiedler)
    };
  }

  getRecommendation(risk, fiedler) {
    if (risk > 0.7) {
      return 'CRITICAL: Add redundant connections or spawn backup agents immediately';
    }
    if (fiedler < 0.1) {
      return 'WARNING: System is loosely connected. Consider adding coordinator agent.';
    }
    if (risk > 0.4) {
      return 'CAUTION: Monitor closely. Prepare failover procedures.';
    }
    return 'System healthy. No action needed.';
  }
}

// Usage
const monitor = new SwarmMonitor();
monitor.registerAgent('coordinator');
monitor.registerAgent('worker-1');
monitor.registerAgent('worker-2');
monitor.registerAgent('worker-3');

setInterval(() => {
  const report = monitor.getHealthReport();
  console.log(`[${report.status.toUpperCase()}] Risk: ${(report.collapseRisk * 100).toFixed(1)}%`);
  if (report.status !== 'healthy') {
    console.log(`${report.recommendation}`);
  }
}, 30000);

Tutorial 3: Causal Explainability for ML Models

import init, { CausalEngine } from 'prime-radiant-advanced-wasm';

await init();

class ModelExplainer {
  constructor() {
    this.engine = new CausalEngine();
    this.variables = [];
  }

  // Define your model's causal structure
  defineStructure(features, confounders, target) {
    this.engine = new CausalEngine();

    // Add all variables
    features.forEach(f => {
      this.engine.add_variable(f, true);
      this.variables.push(f);
    });

    confounders.forEach(c => {
      this.engine.add_variable(c, true);
      this.variables.push(c);
    });

    this.engine.add_variable(target, true);
    this.variables.push(target);

    // Define causal edges (from domain knowledge)
    // Confounders affect both features and target
    confounders.forEach(c => {
      features.forEach(f => this.engine.add_causal_edge(c, f));
      this.engine.add_causal_edge(c, target);
    });

    // Features affect target
    features.forEach(f => this.engine.add_causal_edge(f, target));

    this.target = target;
  }

  explain(feature) {
    // Check if effect is identifiable
    const identifiable = this.engine.is_identifiable(feature, this.target);

    if (!identifiable) {
      return {
        feature,
        identifiable: false,
        message: `Cannot isolate effect of ${feature} - unmeasured confounders present`
      };
    }

    // Get adjustment set
    const adjustFor = this.engine.get_adjustment_set(feature, this.target);

    // Compute effect
    const effect = this.engine.compute_ate(feature, this.target);

    return {
      feature,
      identifiable: true,
      causalEffect: effect,
      adjustFor,
      interpretation: this.interpret(feature, effect, adjustFor)
    };
  }

  interpret(feature, effect, adjustFor) {
    const direction = effect > 0 ? 'increases' : 'decreases';
    const magnitude = Math.abs(effect) > 0.5 ? 'strongly' : Math.abs(effect) > 0.2 ? 'moderately' : 'slightly';

    let explanation = `${feature} ${magnitude} ${direction} the outcome (effect size: ${effect.toFixed(3)}).`;

    if (adjustFor.length > 0) {
      explanation += ` This accounts for confounding from: ${adjustFor.join(', ')}.`;
    }

    return explanation;
  }

  explainAll() {
    return this.variables
      .filter(v => v !== this.target)
      .map(v => this.explain(v))
      .sort((a, b) => Math.abs(b.causalEffect || 0) - Math.abs(a.causalEffect || 0));
  }
}

// Usage
const explainer = new ModelExplainer();

explainer.defineStructure(
  ['click_history', 'search_terms', 'time_on_page'],  // Features
  ['user_segment', 'device_type'],                      // Confounders
  'conversion'                                          // Target
);

const explanations = explainer.explainAll();
console.log('Feature importance by causal effect:');
explanations.forEach((exp, i) => {
  console.log(`${i + 1}. ${exp.interpretation}`);
});

Tutorial 4: Embedding Quality Assurance

import init, { QuantumEngine } from 'prime-radiant-advanced-wasm';

await init();

class EmbeddingQA {
  constructor() {
    this.engine = new QuantumEngine();
  }

  analyze(embeddings, sampleSize = 500) {
    this.engine = new QuantumEngine();

    // Sample if too large
    const sample = embeddings.length > sampleSize
      ? this.randomSample(embeddings, sampleSize)
      : embeddings;

    // Add points
    sample.forEach(emb => this.engine.add_point(new Float64Array(emb)));

    // Analyze at multiple scales
    const scales = [0.1, 0.3, 0.5, 0.7, 1.0];
    const analysis = scales.map(scale => ({
      scale,
      betti: this.engine.get_betti_numbers(scale)
    }));

    return {
      sampleSize: sample.length,
      dimensions: sample[0].length,
      scaleAnalysis: analysis,
      issues: this.detectIssues(analysis),
      recommendations: this.getRecommendations(analysis)
    };
  }

  detectIssues(analysis) {
    const issues = [];

    // Check for fragmentation at low scales
    const lowScale = analysis.find(a => a.scale === 0.3);
    if (lowScale && lowScale.betti[0] > 5) {
      issues.push({
        type: 'fragmentation',
        severity: 'high',
        detail: `${lowScale.betti[0]} disconnected clusters at scale 0.3`
      });
    }

    // Check for holes (gaps in coverage)
    const midScale = analysis.find(a => a.scale === 0.5);
    if (midScale && midScale.betti[1] > 0) {
      issues.push({
        type: 'coverage_gaps',
        severity: 'medium',
        detail: `${midScale.betti[1]} topological holes detected`
      });
    }

    // Check connectivity at high scales
    const highScale = analysis.find(a => a.scale === 1.0);
    if (highScale && highScale.betti[0] > 1) {
      issues.push({
        type: 'disconnected_regions',
        severity: 'high',
        detail: 'Embedding space remains disconnected even at large scales'
      });
    }

    return issues;
  }

  getRecommendations(analysis) {
    const recs = [];
    const issues = this.detectIssues(analysis);

    if (issues.some(i => i.type === 'fragmentation')) {
      recs.push('Add more training data to connect isolated clusters');
      recs.push('Consider using contrastive learning to improve embedding density');
    }

    if (issues.some(i => i.type === 'coverage_gaps')) {
      recs.push('Identify concepts in the gaps and add targeted training examples');
      recs.push('Review data preprocessing - some categories may be underrepresented');
    }

    if (issues.some(i => i.type === 'disconnected_regions')) {
      recs.push('Severe fragmentation detected - consider retraining with different hyperparameters');
      recs.push('Check for data quality issues or labeling errors');
    }

    if (recs.length === 0) {
      recs.push('Embedding space looks healthy!');
    }

    return recs;
  }

  randomSample(arr, n) {
    const shuffled = [...arr].sort(() => 0.5 - Math.random());
    return shuffled.slice(0, n);
  }
}

// Usage
const qa = new EmbeddingQA();

// Assume you have embeddings from your model
const report = qa.analyze(myEmbeddings);

console.log(`Analyzed ${report.sampleSize} embeddings (${report.dimensions}D)`);
console.log('\nIssues found:');
report.issues.forEach(issue => {
  console.log(`  [${issue.severity.toUpperCase()}] ${issue.type}: ${issue.detail}`);
});
console.log('\nRecommendations:');
report.recommendations.forEach((rec, i) => {
  console.log(`  ${i + 1}. ${rec}`);
});

Mathematical Background

Sheaf Cohomology (CohomologyEngine)

Intuition: Measures if local data "glues together" consistently.

  • Sheaf: Assigns data to each node with compatibility rules on edges
  • Coboundary operator: δ measures how much data fails to match across edges
  • Cohomology H¹: Non-zero means there are "global inconsistencies"
  • Sheaf Laplacian energy: E = x^T L x, lower = more coherent

Spectral Graph Theory (SpectralEngine)

Intuition: Eigenvalues reveal structural properties of networks.

  • Fiedler value (λ₂): Second-smallest eigenvalue = algebraic connectivity
  • Cheeger constant h(G): How hard is it to split the graph?
  • Cheeger inequality: λ₂/2 ≤ h(G) ≤ √(2λ₂)
  • Collapse prediction: Low λ₂ or h(G) = system about to partition

Do-Calculus (CausalEngine)

Intuition: Distinguish correlation from causation.

  • SCM: Structural Causal Model = DAG + equations
  • do(X=x): Intervention, not observation
  • Three rules: Transform P(Y|do(X)) into observable quantities
  • Adjustment sets: What to control for to isolate effects

Persistent Homology (QuantumEngine)

Intuition: Find shapes/patterns that persist across scales.

  • Filtration: Grow balls around points, track when things connect
  • Betti numbers: β₀ = components, β₁ = loops, β₂ = voids
  • Persistence diagram: (birth, death) of each feature
  • Long-lived features: Real signal. Short-lived: noise.

Performance

Operation 100 items 1,000 items 10,000 items
Coherence check ~1ms ~8ms ~120ms
Collapse prediction ~2ms ~15ms ~200ms
Causal effect <1ms ~3ms ~25ms
Betti numbers ~2ms ~12ms ~180ms

Browser Support

Browser Version Status
Chrome 57+ Full support
Firefox 52+ Full support
Safari 11+ Full support
Edge 16+ Full support
Node.js 12+ Full support
Package Description
ruvector High-performance vector operations in Rust/WASM
ruvector-attention-wasm Attention mechanisms for transformers

License

MIT OR Apache-2.0

Contributing

Issues and PRs welcome at github.com/ruvnet/ruvector