@neuroverseos/nv-sim 0.1.4 → 0.1.7

package/dist/engine/scenarioComparison.js

@@ -0,0 +1,463 @@
+"use strict";
+/**
+ * Multi-Scenario Comparison Runner — N Scenarios × M Policies
+ *
+ * The decision intelligence engine. This is MODE 3 of the Prime Radiant.
+ *
+ * Instead of:
+ *   "Here's what happened"
+ * We produce:
+ *   "Here's what you should do"
+ *
+ * Usage:
+ *   const result = await runScenarioMatrix({
+ *     scenario: "University disciplinary crisis",
+ *     stakeholders: [...],
+ *     paths: [...],
+ *     policyOptions: [
+ *       { id: "revoke", label: "Revoke Decision", policyText: "..." },
+ *       { id: "partial", label: "Partial Apology", policyText: "..." },
+ *       { id: "maintain", label: "Maintain Decision", policyText: "..." },
+ *     ],
+ *     evaluationMetrics: [
+ *       { id: "trust", label: "Public Trust", weight: 0.3 },
+ *       { id: "polarization", label: "Polarization Index", weight: 0.25, lowerIsBetter: true },
+ *       ...
+ *     ],
+ *   })
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_METRICS = void 0;
+exports.runScenarioMatrix = runScenarioMatrix;
+const fullGovernedLoop_1 = require("./fullGovernedLoop");
+// ============================================
+// DEFAULT METRICS
+// ============================================
+exports.DEFAULT_METRICS = [
+    {
+        id: "trust",
+        label: "Public Trust",
+        weight: 0.25,
+        extractor: (r) => r.finalState.trust,
+    },
+    {
+        id: "polarization",
+        label: "Polarization Index",
+        weight: 0.20,
+        lowerIsBetter: true,
+        extractor: (r) => r.finalState.polarization,
+    },
+    {
+        id: "outrage",
+        label: "Outrage Level",
+        weight: 0.15,
+        lowerIsBetter: true,
+        extractor: (r) => r.finalState.outrage,
+    },
+    {
+        id: "cascade_risk",
+        label: "Cascade Risk",
+        weight: 0.15,
+        lowerIsBetter: true,
+        extractor: (r) => r.finalState.cascadeRisk,
+    },
+    {
+        id: "system_health",
+        label: "System Health",
+        weight: 0.15,
+        extractor: (r) => r.systemHealthScore / 100,
+    },
+    {
+        id: "governance_effectiveness",
+        label: "Governance Effectiveness",
+        weight: 0.10,
+        extractor: (r) => {
+            const blocked = r.actionGovernance.blocked;
+            const total = r.actionGovernance.totalEvaluations;
+            const blockRate = total > 0 ? blocked / total : 0;
+            // Sweet spot: some blocking is good, too much is bad
+            if (blockRate < 0.1)
+                return 0.3; // too lenient
+            if (blockRate > 0.7)
+                return 0.2; // over-constrained
+            return 0.7 + (1 - Math.abs(blockRate - 0.3) * 3) * 0.3;
+        },
+    },
+];
+// ============================================
+// METRIC EXTRACTION
+// ============================================
+function extractMetric(metric, result) {
+    if (metric.extractor) {
+        return metric.extractor(result);
+    }
+    // Default extractors based on metric ID
+    switch (metric.id) {
+        case "trust": return result.finalState.trust;
+        case "polarization": return result.finalState.polarization;
+        case "outrage": return result.finalState.outrage;
+        case "cascade_risk": return result.finalState.cascadeRisk;
+        case "system_health": return result.systemHealthScore / 100;
+        case "amplification": return result.finalState.amplification;
+        default: return 0.5;
+    }
+}
+function normalizeScore(value, lowerIsBetter) {
+    if (lowerIsBetter) {
+        return Math.max(0, Math.min(1, 1 - value));
+    }
+    return Math.max(0, Math.min(1, value));
+}
+function rateScore(normalized) {
+    if (normalized >= 0.8)
+        return "excellent";
+    if (normalized >= 0.6)
+        return "good";
+    if (normalized >= 0.4)
+        return "moderate";
+    if (normalized >= 0.2)
+        return "poor";
+    return "critical";
+}
+function formatMetricValue(value, metricId) {
+    if (metricId === "system_health")
+        return `${(value * 100).toFixed(0)}/100`;
+    if (metricId.includes("risk") || metricId.includes("probability"))
+        return `${(value * 100).toFixed(0)}%`;
+    return value.toFixed(2);
+}
+// ============================================
+// MAIN: runScenarioMatrix()
+// ============================================
+async function runScenarioMatrix(config) {
+    const metrics = config.evaluationMetrics.length > 0
+        ? config.evaluationMetrics
+        : exports.DEFAULT_METRICS;
+    const optionResults = [];
+    // --- Run simulation for each policy option ---
+    for (const option of config.policyOptions) {
+        config.onProgress?.(option.id, "simulating");
+        const worldDef = option.worldDef ?? config.defaultWorldDef;
+        const simulation = await (0, fullGovernedLoop_1.runFullGovernedSimulation)({
+            scenario: config.scenario,
+            stakeholders: config.stakeholders,
+            paths: config.paths,
+            swarmConfig: config.swarmConfig,
+            policyText: option.policyText,
+            worldDef,
+            narrativeEvents: config.narrativeEvents,
+            agentTypes: config.agentTypes,
+        });
+        config.onProgress?.(option.id, "evaluating");
+        // Score each metric
+        const metricScores = metrics.map((metric) => {
+            const value = extractMetric(metric, simulation);
+            const normalized = normalizeScore(value, metric.lowerIsBetter ?? false);
+            const weighted = normalized * metric.weight;
+            return {
+                metricId: metric.id,
+                metricLabel: metric.label,
+                value: Number(value.toFixed(3)),
+                normalizedScore: Number(normalized.toFixed(3)),
+                weightedScore: Number(weighted.toFixed(3)),
+                display: formatMetricValue(value, metric.id),
+                rating: rateScore(normalized),
+            };
+        });
+        const overallScore = metricScores.reduce((s, m) => s + m.weightedScore, 0);
+        // Extract outcomes
+        const outcomes = {
+            finalTrust: Number(simulation.finalState.trust.toFixed(3)),
+            finalPolarization: Number(simulation.finalState.polarization.toFixed(3)),
+            finalOutrage: Number(simulation.finalState.outrage.toFixed(3)),
+            finalCascadeRisk: Number(simulation.finalState.cascadeRisk.toFixed(3)),
+            peakOutrage: simulation.dynamicsGovernance.peakOutrage,
+            totalInterventions: simulation.dynamicsGovernance.totalInterventions,
+            actionsBlocked: simulation.actionGovernance.blocked,
+            systemHealth: simulation.systemHealthScore,
+            trajectory: simulation.trajectory,
+            cascadeBreakerFired: simulation.dynamicsGovernance.cascadeBreakers > 0,
+            coolingActivated: simulation.dynamicsGovernance.coolingPeriods > 0,
+        };
+        optionResults.push({
+            optionId: option.id,
+            optionLabel: option.label,
+            simulation,
+            metricScores,
+            overallScore: Number(overallScore.toFixed(3)),
+            outcomes,
+        });
+    }
+    // --- Build comparison matrix ---
+    const sortedResults = [...optionResults].sort((a, b) => b.overallScore - a.overallScore);
+    const comparison = buildComparisonMatrix(optionResults, metrics);
+    const rankings = buildRankings(sortedResults);
+    const riskAssessment = buildRiskAssessment(optionResults);
+    const recommendation = buildRecommendation(sortedResults, riskAssessment, config.policyOptions);
+    const decisionBrief = buildDecisionBrief(sortedResults, recommendation, riskAssessment);
+    return {
+        scenario: config.scenario,
+        optionResults,
+        comparison,
+        recommendation,
+        rankings,
+        riskAssessment,
+        decisionBrief,
+    };
+}
+// ============================================
+// COMPARISON MATRIX BUILDER
+// ============================================
+function buildComparisonMatrix(results, metrics) {
+    const metricIds = metrics.map((m) => m.id);
+    // Find best/worst per metric
+    const bestPerMetric = {};
+    const worstPerMetric = {};
+    for (const metric of metrics) {
+        const values = results.map((r) => {
+            const score = r.metricScores.find((s) => s.metricId === metric.id);
+            return score?.normalizedScore ?? 0;
+        });
+        bestPerMetric[metric.id] = Math.max(...values);
+        worstPerMetric[metric.id] = Math.min(...values);
+    }
+    const sorted = [...results].sort((a, b) => b.overallScore - a.overallScore);
+    const rows = sorted.map((result, idx) => ({
+        optionId: result.optionId,
+        optionLabel: result.optionLabel,
+        values: metrics.map((metric) => {
+            const score = result.metricScores.find((s) => s.metricId === metric.id);
+            return {
+                metricId: metric.id,
+                value: score.value,
+                display: score.display,
+                isBest: score.normalizedScore === bestPerMetric[metric.id],
+                isWorst: score.normalizedScore === worstPerMetric[metric.id],
+            };
+        }),
+        overallScore: result.overallScore,
+        rank: idx + 1,
+    }));
+    return {
+        metrics: metricIds,
+        rows,
+    };
+}
+// ============================================
+// RANKINGS
+// ============================================
+function buildRankings(sorted) {
+    return sorted.map((result, idx) => {
+        let verdict;
+        if (idx === 0)
+            verdict = "BEST";
+        else if (result.overallScore > 0.5)
+            verdict = "VIABLE";
+        else if (result.overallScore > 0.3)
+            verdict = "RISKY";
+        else
+            verdict = "AVOID";
+        const oneLiner = buildOneLiner(result, idx);
+        return {
+            rank: idx + 1,
+            optionId: result.optionId,
+            optionLabel: result.optionLabel,
+            overallScore: result.overallScore,
+            verdict,
+            oneLiner,
+        };
+    });
+}
+function buildOneLiner(result, rank) {
+    const outcomes = result.outcomes;
+    if (outcomes.cascadeBreakerFired) {
+        return "Required emergency circuit breaker — high risk scenario.";
+    }
+    if (outcomes.finalTrust > 0.6 && outcomes.finalPolarization < 0.3) {
+        return "Maintains trust and minimizes polarization.";
+    }
+    if (outcomes.finalOutrage > 0.6) {
+        return "Outrage remains elevated — risk of sustained negative dynamics.";
+    }
+    if (outcomes.finalCascadeRisk > 0.5) {
+        return "Cascade risk remains dangerous — structural instability.";
+    }
+    if (outcomes.systemHealth > 70) {
+        return "System stabilizes with good overall health.";
+    }
+    if (outcomes.totalInterventions > 10) {
+        return "Requires heavy governance intervention to maintain stability.";
+    }
+    return `Overall score: ${result.overallScore.toFixed(2)} — ${outcomes.trajectory} trajectory.`;
+}
+// ============================================
+// RISK ASSESSMENT
+// ============================================
+function buildRiskAssessment(results) {
+    return results.map((result) => {
+        const risks = [];
+        const outcomes = result.outcomes;
+        if (outcomes.finalCascadeRisk > 0.5) {
+            risks.push({
+                risk: "Cascading failure — actions compound into system-wide instability",
+                probability: outcomes.finalCascadeRisk,
+                severity: outcomes.finalCascadeRisk > 0.7 ? "critical" : "high",
+            });
+        }
+        if (outcomes.finalPolarization > 0.5) {
+            risks.push({
+                risk: "Entrenched polarization — stakeholder base splits into opposing camps",
+                probability: outcomes.finalPolarization,
+                severity: outcomes.finalPolarization > 0.7 ? "high" : "moderate",
+            });
+        }
+        if (outcomes.finalTrust < 0.3) {
+            risks.push({
+                risk: "Institutional trust collapse — credibility cannot be recovered",
+                probability: 1 - outcomes.finalTrust,
+                severity: outcomes.finalTrust < 0.15 ? "critical" : "high",
+            });
+        }
+        if (outcomes.peakOutrage > 0.7) {
+            risks.push({
+                risk: "Outrage spike — may trigger media cascade or coordinated backlash",
+                probability: outcomes.peakOutrage,
+                severity: outcomes.peakOutrage > 0.85 ? "critical" : "high",
+            });
+        }
+        if (outcomes.actionsBlocked > outcomes.systemHealth * 0.3) {
+            risks.push({
+                risk: "Over-governance — too many blocked actions may freeze legitimate response",
+                probability: 0.5,
+                severity: "moderate",
+            });
+        }
+        let overallRisk;
+        const criticalRisks = risks.filter((r) => r.severity === "critical").length;
+        const highRisks = risks.filter((r) => r.severity === "high").length;
+        if (criticalRisks > 0)
+            overallRisk = "CRITICAL";
+        else if (highRisks > 1)
+            overallRisk = "HIGH";
+        else if (highRisks > 0 || risks.length > 2)
+            overallRisk = "MEDIUM";
+        else
+            overallRisk = "LOW";
+        return {
+            optionId: result.optionId,
+            optionLabel: result.optionLabel,
+            overallRisk,
+            risks,
+        };
+    });
+}
+// ============================================
+// RECOMMENDATION ENGINE
+// ============================================
+function buildRecommendation(sorted, risks, options) {
+    const best = sorted[0];
+    const bestRisk = risks.find((r) => r.optionId === best.optionId);
+    const secondBest = sorted.length > 1 ? sorted[1] : null;
+    // Confidence: based on score gap and risk level
+    let confidence = 0.5;
+    if (secondBest) {
+        const gap = best.overallScore - secondBest.overallScore;
+        confidence += gap * 2; // bigger gap = more confidence
+    }
+    if (bestRisk?.overallRisk === "LOW")
+        confidence += 0.15;
+    else if (bestRisk?.overallRisk === "CRITICAL")
+        confidence -= 0.2;
+    confidence = Math.max(0.2, Math.min(0.95, confidence));
+    // Rationale
+    const parts = [];
+    parts.push(`"${best.optionLabel}" scores highest across the evaluation metrics (${best.overallScore.toFixed(2)}).`);
+    if (best.outcomes.finalTrust > 0.5) {
+        parts.push(`Preserves institutional trust at ${(best.outcomes.finalTrust * 100).toFixed(0)}%.`);
+    }
+    if (best.outcomes.finalPolarization < 0.3) {
+        parts.push(`Keeps polarization contained at ${(best.outcomes.finalPolarization * 100).toFixed(0)}%.`);
+    }
+    if (secondBest) {
+        parts.push(`Outperforms "${secondBest.optionLabel}" by ${((best.overallScore - secondBest.overallScore) * 100).toFixed(0)} points.`);
+    }
+    // Caveats
+    const caveats = [];
+    if (bestRisk?.overallRisk === "HIGH" || bestRisk?.overallRisk === "CRITICAL") {
+        caveats.push(`This option still carries ${bestRisk.overallRisk} risk — ${bestRisk.risks[0]?.risk}`);
+    }
+    if (best.outcomes.coolingActivated) {
+        caveats.push("Required a cooling period — expect delayed response dynamics.");
+    }
+    if (best.outcomes.cascadeBreakerFired) {
+        caveats.push("Circuit breaker was triggered — the system reached critical thresholds before stabilizing.");
+    }
+    if (confidence < 0.5) {
+        caveats.push("Score differences between options are small — the choice is not clear-cut.");
+    }
+    // Next steps
+    const nextSteps = [
+        `Implement the "${best.optionLabel}" policy as the primary approach.`,
+    ];
+    if (best.outcomes.totalInterventions > 5) {
+        nextSteps.push("Prepare governance mechanisms for active intervention — this option requires ongoing management.");
+    }
+    if (secondBest && secondBest.overallScore > best.overallScore - 0.1) {
+        nextSteps.push(`Keep "${secondBest.optionLabel}" as a fallback — score difference is marginal.`);
+    }
+    nextSteps.push("Monitor the system state metrics (trust, polarization, outrage) in real-time.");
+    return {
+        optionId: best.optionId,
+        optionLabel: best.optionLabel,
+        confidence: Number(confidence.toFixed(2)),
+        rationale: parts.join(" "),
+        caveats,
+        nextSteps,
+    };
+}
+// ============================================
+// DECISION BRIEF
+// ============================================
+function buildDecisionBrief(sorted, recommendation, risks) {
+    const lines = [];
+    lines.push("DECISION INTELLIGENCE BRIEF");
+    lines.push("=".repeat(50));
+    lines.push("");
+    // Rankings table
+    lines.push("SCENARIO COMPARISON:");
+    lines.push("-".repeat(50));
+    const headers = ["Option", "Score", "Trust", "Polar.", "Risk", "Verdict"];
+    lines.push(`  ${headers.map((h) => h.padEnd(12)).join("")}`);
+    lines.push(`  ${"-".repeat(72)}`);
+    for (const result of sorted) {
+        const risk = risks.find((r) => r.optionId === result.optionId);
+        const rank = sorted.indexOf(result);
+        const verdict = rank === 0 ? "BEST" : result.overallScore > 0.5 ? "VIABLE" : result.overallScore > 0.3 ? "RISKY" : "AVOID";
+        const prefix = rank === 0 ? ">>> " : "    ";
+        const row = [
+            result.optionLabel.slice(0, 11),
+            result.overallScore.toFixed(2),
+            `${(result.outcomes.finalTrust * 100).toFixed(0)}%`,
+            `${(result.outcomes.finalPolarization * 100).toFixed(0)}%`,
+            risk?.overallRisk ?? "?",
+            verdict,
+        ];
+        lines.push(`${prefix}${row.map((v) => v.padEnd(12)).join("")}`);
+    }
+    lines.push("");
+    lines.push("RECOMMENDATION:");
+    lines.push(`  ${recommendation.rationale}`);
+    if (recommendation.caveats.length > 0) {
+        lines.push("");
+        lines.push("CAVEATS:");
+        for (const caveat of recommendation.caveats) {
+            lines.push(`  - ${caveat}`);
+        }
+    }
+    lines.push("");
+    lines.push("NEXT STEPS:");
+    for (const step of recommendation.nextSteps) {
+        lines.push(`  ${sorted.indexOf(sorted[0]) + 1}. ${step}`);
+    }
+    return lines.join("\n");
+}

package/dist/engine/swarmSimulation.js

@@ -19,6 +19,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSwarmSimulation = runSwarmSimulation;
+const aiProvider_1 = require("./aiProvider");
 // ============================================
 // REACTION MODELS
 // ============================================
@@ -205,10 +206,16 @@ function findInflectionPoints(rounds) {
  * This is Echelon's native reaction model — NOT MiroFish.
  * It simulates how stakeholders react to different reasoning paths
  * over multiple rounds, detecting emergent dynamics.
+ *
+ * When ANTHROPIC_API_KEY is set, agents use Claude for real reasoning.
+ * Otherwise, falls back to the deterministic Math.random() model.
  */
 async function runSwarmSimulation(scenario, stakeholders, paths, config) {
     const roundCount = config.rounds ?? 3;
     const model = config.reaction_model ?? "mixed";
+    // Detect if AI reasoning is available and requested
+    const defaultProvider = (0, aiProvider_1.getDefaultProviderName)();
+    const useAI = config.ai_reasoning !== false && defaultProvider !== "deterministic";
     // Filter stakeholders if specific ones requested
     const activeStakeholders = config.simulate_stakeholders
         ? stakeholders.filter((s) => config.simulate_stakeholders.includes(s.id))
@@ -224,8 +231,54 @@ async function runSwarmSimulation(scenario, stakeholders, paths, config) {
     }
     // Run simulation rounds
     const rounds = [];
+    let aiProvider;
+    if (useAI) {
+        try {
+            aiProvider = (0, aiProvider_1.getAIProvider)(defaultProvider);
+        }
+        catch {
+            // No API key or provider unavailable — fall back silently
+        }
+    }
     for (let round = 0; round < roundCount; round++) {
-        const reactions = activeStakeholders.map((stakeholder) => modelReaction(stakeholder, primaryPath, model, round));
+        let reactions;
+        if (aiProvider) {
+            // AI-POWERED REASONING: Each agent gets a Claude call
+            const previousReactions = round > 0
+                ? rounds[round - 1].reactions.map(r => `${r.stakeholder_id}: ${r.reaction}`)
+                : [];
+            reactions = await Promise.all(activeStakeholders.map(async (stakeholder) => {
+                try {
+                    const aiResult = await (0, aiProvider_1.generateAIReaction)({
+                        stakeholderId: stakeholder.id,
+                        stakeholderDescription: stakeholder.description,
+                        stakeholderDisposition: stakeholder.disposition,
+                        stakeholderPriorities: stakeholder.priorities,
+                        scenario,
+                        pathDescription: primaryPath.description,
+                        pathRisk: primaryPath.risk,
+                        round,
+                        previousReactions,
+                        provider: aiProvider,
+                    });
+                    return {
+                        stakeholder_id: stakeholder.id,
+                        reaction: aiResult.reaction,
+                        confidence: aiResult.confidence,
+                        impact: aiResult.impact,
+                        trigger: aiResult.trigger,
+                    };
+                }
+                catch {
+                    // Individual agent fallback to deterministic
+                    return modelReaction(stakeholder, primaryPath, model, round);
+                }
+            }));
+        }
+        else {
+            // DETERMINISTIC: Original Math.random() model
+            reactions = activeStakeholders.map((stakeholder) => modelReaction(stakeholder, primaryPath, model, round));
+        }
         const emergentDynamics = detectEmergentDynamics(reactions);
         rounds.push({
             round,