@neuroverseos/nv-sim 0.1.2 → 0.1.5

package/dist/engine/index.js

@@ -21,7 +21,8 @@
  * Mirotir helps you decide WHAT TO DO → the brain
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseReasonRequestBody = exports.handleRunPreset = exports.handleGetPreset = exports.handleListPresets = exports.handleHealthCheck = exports.handleCreateCapsule = exports.handleReasonFromCapsule = exports.handleReasonRequest = exports.TRADING_DEMO = exports.runGovernedComparison = exports.analyzeMiroFishSimulation = exports.DEFAULT_MIROFISH_CONFIG = exports.buildMiroFishRequest = exports.miroFishResultToSwarmResult = exports.stakeholdersToMiroFishAgents = exports.runUnifiedSimulation = exports.getMiroFishClient = exports.configureMiroFish = exports.MiroFishError = exports.MiroFishClient = exports.runSwarmSimulation = exports.initNeuroverseModule = exports.validationToEnforcedConstraints = exports.simulationToGovernanceSignals = exports.verdictToConstitutionalChecks = exports.validateScenarioWorld = exports.runWorldSimulation = exports.evaluateScenarioGuard = exports.buildWorldFromScenario = exports.runFullGovernanceChecks = exports.runGovernanceChecks = exports.processReasonRequest = exports.SCENARIO_TEMPLATES = exports.getPresetCapsule = exports.extractCapsuleFromUrl = exports.buildShareableUrl = exports.decodeCapsule = exports.encodeCapsule = exports.capsuleToReasonRequest = exports.createCapsule = exports.runGoalReasoning = void 0;
+exports.policyToWorld = exports.validatePolicy = exports.parseRulesFromText = exports.suggestExperiments = exports.formatPolicyDiagnostics = exports.formatGuidedNextSteps = exports.exportEnforcementReportJSON = exports.formatEnforcementReport = exports.createEnforcementSession = exports.formatCrossRunComparison = exports.formatBehavioralAnalysis = exports.compareBehaviorAcrossRuns = exports.detectBehavioralShifts = exports.computeActionDistributions = exports.buildAgentTrajectories = exports.classifyBehavior = exports.analyzeBehavior = exports.TRADING_DEMO = exports.runGovernedComparison = exports.analyzeMiroFishSimulation = exports.DEFAULT_MIROFISH_CONFIG = exports.buildMiroFishRequest = exports.miroFishResultToSwarmResult = exports.stakeholdersToMiroFishAgents = exports.runUnifiedSimulation = exports.getMiroFishClient = exports.configureMiroFish = exports.MiroFishError = exports.MiroFishClient = exports.runSwarmSimulation = exports.initNeuroverseModule = exports.validationToEnforcedConstraints = exports.simulationToGovernanceSignals = exports.verdictToConstitutionalChecks = exports.validateScenarioWorld = exports.runWorldSimulation = exports.evaluateScenarioGuard = exports.buildWorldFromScenario = exports.runFullGovernanceChecks = exports.runGovernanceChecks = exports.processReasonRequest = exports.SCENARIO_TEMPLATES = exports.getPresetCapsule = exports.extractCapsuleFromUrl = exports.buildShareableUrl = exports.decodeCapsule = exports.encodeCapsule = exports.capsuleToReasonRequest = exports.createCapsule = exports.runGoalReasoning = void 0;
+exports.EXAMPLE_WORLD_STATES = exports.EXAMPLE_ACTIONS = exports.createGovernor = exports.govern = exports.extractTrace = exports.generateGovernedReport = exports.formatAuditTrail = exports.searchAuditTrails = exports.loadAuditSession = exports.listAuditSessions = exports.AuditTrail = exports.evaluateAIAction = exports.listAIProviders = exports.getDefaultProviderName = exports.getAIProvider = exports.registerAIProvider = exports.generateAIReaction = exports.generateDeterministicReport = exports.OpenAICompatibleProvider = exports.AnthropicProvider = exports.DeterministicProvider = exports.AI_ROLES = exports.parseReasonRequestBody = exports.handleRunPreset = exports.handleGetPreset = exports.handleListPresets = exports.handleHealthCheck = exports.handleCreateCapsule = exports.handleReasonFromCapsule = exports.handleReasonRequest = exports.applyQuickFix = exports.runPolicyPipeline = void 0;
 // Goal-Directed Strategy Engine
 var goalEngine_1 = require("./goalEngine");
 Object.defineProperty(exports, "runGoalReasoning", { enumerable: true, get: function () { return goalEngine_1.runGoalReasoning; } });
@@ -70,6 +71,28 @@ Object.defineProperty(exports, "analyzeMiroFishSimulation", { enumerable: true,
 var governedSimulation_1 = require("./governedSimulation");
 Object.defineProperty(exports, "runGovernedComparison", { enumerable: true, get: function () { return governedSimulation_1.runGovernedComparison; } });
 Object.defineProperty(exports, "TRADING_DEMO", { enumerable: true, get: function () { return governedSimulation_1.TRADING_DEMO; } });
+var behavioralAnalysis_1 = require("./behavioralAnalysis");
+Object.defineProperty(exports, "analyzeBehavior", { enumerable: true, get: function () { return behavioralAnalysis_1.analyzeBehavior; } });
+Object.defineProperty(exports, "classifyBehavior", { enumerable: true, get: function () { return behavioralAnalysis_1.classifyBehavior; } });
+Object.defineProperty(exports, "buildAgentTrajectories", { enumerable: true, get: function () { return behavioralAnalysis_1.buildAgentTrajectories; } });
+Object.defineProperty(exports, "computeActionDistributions", { enumerable: true, get: function () { return behavioralAnalysis_1.computeActionDistributions; } });
+Object.defineProperty(exports, "detectBehavioralShifts", { enumerable: true, get: function () { return behavioralAnalysis_1.detectBehavioralShifts; } });
+Object.defineProperty(exports, "compareBehaviorAcrossRuns", { enumerable: true, get: function () { return behavioralAnalysis_1.compareBehaviorAcrossRuns; } });
+Object.defineProperty(exports, "formatBehavioralAnalysis", { enumerable: true, get: function () { return behavioralAnalysis_1.formatBehavioralAnalysis; } });
+Object.defineProperty(exports, "formatCrossRunComparison", { enumerable: true, get: function () { return behavioralAnalysis_1.formatCrossRunComparison; } });
+var policyEnforcement_1 = require("./policyEnforcement");
+Object.defineProperty(exports, "createEnforcementSession", { enumerable: true, get: function () { return policyEnforcement_1.createEnforcementSession; } });
+Object.defineProperty(exports, "formatEnforcementReport", { enumerable: true, get: function () { return policyEnforcement_1.formatEnforcementReport; } });
+Object.defineProperty(exports, "exportEnforcementReportJSON", { enumerable: true, get: function () { return policyEnforcement_1.exportEnforcementReportJSON; } });
+Object.defineProperty(exports, "formatGuidedNextSteps", { enumerable: true, get: function () { return policyEnforcement_1.formatGuidedNextSteps; } });
+Object.defineProperty(exports, "formatPolicyDiagnostics", { enumerable: true, get: function () { return policyEnforcement_1.formatPolicyDiagnostics; } });
+Object.defineProperty(exports, "suggestExperiments", { enumerable: true, get: function () { return policyEnforcement_1.suggestExperiments; } });
+var policyEngine_1 = require("./policyEngine");
+Object.defineProperty(exports, "parseRulesFromText", { enumerable: true, get: function () { return policyEngine_1.parseRulesFromText; } });
+Object.defineProperty(exports, "validatePolicy", { enumerable: true, get: function () { return policyEngine_1.validatePolicy; } });
+Object.defineProperty(exports, "policyToWorld", { enumerable: true, get: function () { return policyEngine_1.policyToWorld; } });
+Object.defineProperty(exports, "runPolicyPipeline", { enumerable: true, get: function () { return policyEngine_1.runPolicyPipeline; } });
+Object.defineProperty(exports, "applyQuickFix", { enumerable: true, get: function () { return policyEngine_1.applyQuickFix; } });
 // API Route Handlers
 var api_1 = require("./api");
 Object.defineProperty(exports, "handleReasonRequest", { enumerable: true, get: function () { return api_1.handleReasonRequest; } });
@@ -80,3 +103,35 @@ Object.defineProperty(exports, "handleListPresets", { enumerable: true, get: fun
 Object.defineProperty(exports, "handleGetPreset", { enumerable: true, get: function () { return api_1.handleGetPreset; } });
 Object.defineProperty(exports, "handleRunPreset", { enumerable: true, get: function () { return api_1.handleRunPreset; } });
 Object.defineProperty(exports, "parseReasonRequestBody", { enumerable: true, get: function () { return api_1.parseReasonRequestBody; } });
+var aiProvider_1 = require("./aiProvider");
+Object.defineProperty(exports, "AI_ROLES", { enumerable: true, get: function () { return aiProvider_1.AI_ROLES; } });
+Object.defineProperty(exports, "DeterministicProvider", { enumerable: true, get: function () { return aiProvider_1.DeterministicProvider; } });
+Object.defineProperty(exports, "AnthropicProvider", { enumerable: true, get: function () { return aiProvider_1.AnthropicProvider; } });
+Object.defineProperty(exports, "OpenAICompatibleProvider", { enumerable: true, get: function () { return aiProvider_1.OpenAICompatibleProvider; } });
+Object.defineProperty(exports, "generateDeterministicReport", { enumerable: true, get: function () { return aiProvider_1.generateDeterministicReport; } });
+Object.defineProperty(exports, "generateAIReaction", { enumerable: true, get: function () { return aiProvider_1.generateAIReaction; } });
+Object.defineProperty(exports, "registerAIProvider", { enumerable: true, get: function () { return aiProvider_1.registerAIProvider; } });
+Object.defineProperty(exports, "getAIProvider", { enumerable: true, get: function () { return aiProvider_1.getAIProvider; } });
+Object.defineProperty(exports, "getDefaultProviderName", { enumerable: true, get: function () { return aiProvider_1.getDefaultProviderName; } });
+Object.defineProperty(exports, "listAIProviders", { enumerable: true, get: function () { return aiProvider_1.listAIProviders; } });
+Object.defineProperty(exports, "evaluateAIAction", { enumerable: true, get: function () { return aiProvider_1.evaluateAIAction; } });
+var auditTrace_1 = require("./auditTrace");
+Object.defineProperty(exports, "AuditTrail", { enumerable: true, get: function () { return auditTrace_1.AuditTrail; } });
+Object.defineProperty(exports, "listAuditSessions", { enumerable: true, get: function () { return auditTrace_1.listAuditSessions; } });
+Object.defineProperty(exports, "loadAuditSession", { enumerable: true, get: function () { return auditTrace_1.loadAuditSession; } });
+Object.defineProperty(exports, "searchAuditTrails", { enumerable: true, get: function () { return auditTrace_1.searchAuditTrails; } });
+Object.defineProperty(exports, "formatAuditTrail", { enumerable: true, get: function () { return auditTrace_1.formatAuditTrail; } });
+var reportEngine_1 = require("./reportEngine");
+Object.defineProperty(exports, "generateGovernedReport", { enumerable: true, get: function () { return reportEngine_1.generateGovernedReport; } });
+Object.defineProperty(exports, "extractTrace", { enumerable: true, get: function () { return reportEngine_1.extractTrace; } });
+// NeuroVerse Governance Runtime — the wrapper that makes governance real
+// Drop into ANY agent system: govern(action, worldState, policyText)
+var govern_1 = require("../runtime/govern");
+Object.defineProperty(exports, "govern", { enumerable: true, get: function () { return govern_1.govern; } });
+Object.defineProperty(exports, "createGovernor", { enumerable: true, get: function () { return govern_1.createGovernor; } });
+Object.defineProperty(exports, "EXAMPLE_ACTIONS", { enumerable: true, get: function () { return govern_1.EXAMPLE_ACTIONS; } });
+Object.defineProperty(exports, "EXAMPLE_WORLD_STATES", { enumerable: true, get: function () { return govern_1.EXAMPLE_WORLD_STATES; } });
+// Live Simulation Adapters — plug ANY running simulator into governance + trace
+// NOTE: liveAdapter.ts uses Node.js APIs (child_process, events) and is NOT
+// exported here to avoid Vite browser bundle errors. Import directly from
+// "./liveAdapter" in CLI/server code only.

package/dist/engine/liveAdapter.js

@@ -0,0 +1,342 @@
+"use strict";
+/**
+ * Live Simulation Adapter
+ *
+ * Connects ANY running simulator into the NV-SIM governance + trace pipeline.
+ * Instead of running our own swarm simulation, we ingest live events from an
+ * external simulator process, normalize them, and feed them through governance.
+ *
+ * Architecture:
+ *   External Simulator (running process / stream)
+ *       ↓ stdout / WebSocket / SSE
+ *   LiveSimulationAdapter (parse + normalize)
+ *       ↓ LiveSimulationRound
+ *   Governance Engine (evaluate guards)
+ *       ↓ verdicts
+ *   Trace UI (causality visualization)
+ *
+ * Supported adapter types:
+ *   - ProcessAdapter: spawn a child process, parse stdout
+ *   - StreamAdapter: connect to WebSocket/SSE endpoint (future)
+ *
+ * Every adapter emits the same LiveSimulationRound events, regardless of source.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_REGISTRY = void 0;
+exports.createProcessAdapter = createProcessAdapter;
+exports.parseMiroFishLine = parseMiroFishLine;
+exports.parseGenericJsonLine = parseGenericJsonLine;
+exports.createAdapter = createAdapter;
+const child_process_1 = require("child_process");
+const events_1 = require("events");
+function createParserState() {
+    return {
+        currentRound: 0,
+        pendingActions: [],
+        pendingEvents: [],
+        pendingDynamics: [],
+        buffer: {},
+    };
+}
+/**
+ * Process adapter — spawns a child process and parses its stdout.
+ *
+ * Usage:
+ *   const adapter = createProcessAdapter({
+ *     type: "process",
+ *     label: "MiroFish (Live)",
+ *     command: "node",
+ *     args: ["mirofish.js"],
+ *     parser: parseMiroFishLine,
+ *   });
+ *   adapter.on("round", (round) => { ... });
+ *   await adapter.start();
+ */
+function createProcessAdapter(config) {
+    const emitter = new events_1.EventEmitter();
+    let proc = null;
+    let _status = "idle";
+    const state = createParserState();
+    function setStatus(s) {
+        _status = s;
+        emitter.emit("status", s);
+    }
+    Object.defineProperties(emitter, {
+        status: { get: () => _status },
+        source: { get: () => config.type },
+        label: { get: () => config.label },
+    });
+    emitter.start = async function start() {
+        setStatus("connecting");
+        proc = (0, child_process_1.spawn)(config.command, config.args, {
+            cwd: config.cwd,
+            env: { ...process.env, ...config.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let lineBuffer = "";
+        proc.stdout?.on("data", (chunk) => {
+            lineBuffer += chunk.toString();
+            const lines = lineBuffer.split("\n");
+            // Keep incomplete last line in buffer
+            lineBuffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const round = config.parser(trimmed, state);
+                    if (round) {
+                        emitter.emit("round", round);
+                    }
+                }
+                catch (err) {
+                    // Parser error — log but don't crash
+                    emitter.emit("error", new Error(`Parser error: ${err}`));
+                }
+            }
+            if (_status === "connecting") {
+                setStatus("streaming");
+            }
+        });
+        proc.stderr?.on("data", (chunk) => {
+            // stderr is informational — don't treat as error
+            const msg = chunk.toString().trim();
+            if (msg) {
+                emitter.emit("log", msg);
+            }
+        });
+        proc.on("close", (code) => {
+            // Flush any remaining buffer
+            if (lineBuffer.trim()) {
+                try {
+                    const round = config.parser(lineBuffer.trim(), state);
+                    if (round)
+                        emitter.emit("round", round);
+                }
+                catch { /* ignore */ }
+            }
+            if (code === 0) {
+                setStatus("completed");
+                emitter.emit("complete");
+            }
+            else {
+                setStatus("error");
+                emitter.emit("error", new Error(`Process exited with code ${code}`));
+            }
+            proc = null;
+        });
+        proc.on("error", (err) => {
+            setStatus("error");
+            emitter.emit("error", err);
+            proc = null;
+        });
+    };
+    emitter.stop = async function stop() {
+        if (proc) {
+            proc.kill("SIGTERM");
+            // Give it 3s to exit gracefully, then force
+            setTimeout(() => {
+                if (proc)
+                    proc.kill("SIGKILL");
+            }, 3000);
+        }
+        setStatus("idle");
+    };
+    return emitter;
+}
+// ============================================
+// MIROFISH STDOUT PARSER
+// ============================================
+/**
+ * Parses MiroFish stdout line-by-line.
+ *
+ * Expected MiroFish output formats:
+ *
+ * JSON-per-line (preferred):
+ *   {"step":1,"agent_actions":[{"agent_id":"a1","action":"buy","sentiment":0.5,"confidence":0.8}]}
+ *
+ * Key-value (fallback):
+ *   [step 1] agent=swarm_1 action=panic_sell sentiment=-0.7 confidence=0.6
+ *   [step 1] event=market_crash severity=major
+ *   [step 1] emergent=herd_behavior
+ *   [step 2] ...
+ *
+ * We emit a LiveSimulationRound when we detect a new step number
+ * (meaning the previous step is complete).
+ */
+function parseMiroFishLine(line, state) {
+    // Try JSON first
+    if (line.startsWith("{")) {
+        try {
+            const data = JSON.parse(line);
+            if (data.step != null && Array.isArray(data.agent_actions)) {
+                // Parse adaptation data if present
+                let adaptation;
+                if (data.adaptation) {
+                    const a = data.adaptation;
+                    adaptation = {
+                        count: a.count ?? 0,
+                        rate: a.rate ?? 0,
+                        deltas: (a.deltas ?? []).map((d) => ({
+                            agent: d.agent ?? "unknown",
+                            intended: d.intended ?? "",
+                            actual: d.actual ?? "",
+                            decision: d.decision ?? "BLOCK",
+                            rule: d.rule,
+                            reason: d.reason,
+                            shift: d.shift ?? "unknown",
+                        })),
+                        intendedDistribution: a.intended_distribution ?? {},
+                        actualDistribution: a.actual_distribution ?? {},
+                        clusterPatterns: (a.cluster_patterns ?? []).map((c) => ({
+                            type: c.type ?? "unknown",
+                            strength: c.strength ?? 0,
+                            agents: c.agents ?? 0,
+                        })),
+                        narrative: a.narrative ?? "",
+                    };
+                }
+                // Complete step as JSON — emit immediately
+                return {
+                    round: data.step,
+                    source: "mirofish",
+                    agentActions: data.agent_actions.map((a) => ({
+                        agent: a.agent_id ?? a.agent ?? "unknown",
+                        action: a.action ?? "",
+                        impact: a.sentiment ?? a.impact ?? 0,
+                        confidence: a.confidence ?? 0.5,
+                        ...(a.verdict ? { verdict: { status: a.verdict.status, rule: a.verdict.rule, reason: a.verdict.reason } } : {}),
+                    })),
+                    systemEvents: (data.system_events ?? []).map((e) => typeof e === "string"
+                        ? { id: e, label: e }
+                        : { id: e.id ?? e.event ?? "unknown", label: e.label ?? e.event ?? e.id ?? "", severity: e.severity }),
+                    emergentDynamics: data.emergent_patterns ?? data.emergent ?? [],
+                    adaptation,
+                };
+            }
+        }
+        catch { /* not JSON, fall through to key-value parsing */ }
+    }
+    // Key-value format: [step N] key=value ...
+    const stepMatch = line.match(/\[step\s+(\d+)\]/i);
+    if (!stepMatch)
+        return null;
+    const stepNum = parseInt(stepMatch[1], 10);
+    let result = null;
+    // If new step, flush previous
+    if (stepNum > state.currentRound && state.currentRound > 0) {
+        result = {
+            round: state.currentRound,
+            source: "mirofish",
+            agentActions: [...state.pendingActions],
+            systemEvents: state.pendingEvents.length > 0 ? [...state.pendingEvents] : undefined,
+            emergentDynamics: state.pendingDynamics.length > 0 ? [...state.pendingDynamics] : undefined,
+        };
+        state.pendingActions = [];
+        state.pendingEvents = [];
+        state.pendingDynamics = [];
+    }
+    state.currentRound = stepNum;
+    const rest = line.slice(stepMatch.index + stepMatch[0].length).trim();
+    // Parse agent action
+    const agentMatch = rest.match(/agent=(\S+)\s+action=(\S+)(?:\s+sentiment=([-\d.]+))?(?:\s+confidence=([-\d.]+))?/);
+    if (agentMatch) {
+        state.pendingActions.push({
+            agent: agentMatch[1],
+            action: agentMatch[2],
+            impact: agentMatch[3] ? parseFloat(agentMatch[3]) : 0,
+            confidence: agentMatch[4] ? parseFloat(agentMatch[4]) : 0.5,
+        });
+        return result;
+    }
+    // Parse system event
+    const eventMatch = rest.match(/event=(\S+)(?:\s+severity=(\S+))?/);
+    if (eventMatch) {
+        state.pendingEvents.push({
+            id: eventMatch[1],
+            label: eventMatch[1].replace(/_/g, " "),
+            severity: eventMatch[2],
+        });
+        return result;
+    }
+    // Parse emergent behavior
+    const emergentMatch = rest.match(/emergent=(.+)/);
+    if (emergentMatch) {
+        state.pendingDynamics.push(emergentMatch[1].trim());
+        return result;
+    }
+    return result;
+}
+// ============================================
+// GENERIC JSON PARSER (works for any JSON-per-line simulator)
+// ============================================
+/**
+ * Generic JSON-per-line parser.
+ * Expects each line to be a JSON object with at minimum:
+ *   { "step": N, "agents": [{ "id": "...", "action": "...", "impact": 0.5 }] }
+ */
+function parseGenericJsonLine(line, _state) {
+    if (!line.startsWith("{"))
+        return null;
+    try {
+        const data = JSON.parse(line);
+        const step = data.step ?? data.tick ?? data.round ?? data.time;
+        if (step == null)
+            return null;
+        const agents = (data.agents ?? data.agent_actions ?? []).map((a) => ({
+            agent: a.id ?? a.agent ?? a.agent_id ?? "unknown",
+            action: a.action ?? a.behavior ?? "",
+            impact: a.impact ?? a.sentiment ?? a.value ?? 0,
+            confidence: a.confidence ?? 0.5,
+        }));
+        return {
+            round: typeof step === "number" ? step : parseInt(step, 10),
+            source: "generic",
+            agentActions: agents,
+            systemEvents: (data.events ?? []).map((e) => typeof e === "string"
+                ? { id: e, label: e }
+                : { id: e.id ?? "unknown", label: e.label ?? e.id ?? "", severity: e.severity }),
+            emergentDynamics: data.dynamics ?? data.emergent ?? [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+exports.ADAPTER_REGISTRY = {
+    mirofish: {
+        id: "mirofish",
+        label: "MiroFish (Live)",
+        description: "Spawn MiroFish swarm simulation and stream agent behavior",
+        createConfig: (opts = {}) => ({
+            type: "process",
+            label: "MiroFish (Live)",
+            command: opts.command ?? "node",
+            args: (opts.args ?? "mirofish.js").split(" "),
+            cwd: opts.cwd,
+            parser: parseMiroFishLine,
+        }),
+    },
+    generic: {
+        id: "generic",
+        label: "Generic JSON Process",
+        description: "Spawn any process that outputs JSON-per-line simulation data",
+        createConfig: (opts = {}) => ({
+            type: "process",
+            label: opts.label ?? "External Simulator",
+            command: opts.command ?? "python",
+            args: (opts.args ?? "sim.py").split(" "),
+            cwd: opts.cwd,
+            parser: parseGenericJsonLine,
+        }),
+    },
+};
+/**
+ * Create an adapter from the registry.
+ */
+function createAdapter(adapterId, options) {
+    const entry = exports.ADAPTER_REGISTRY[adapterId];
+    if (!entry)
+        return null;
+    return createProcessAdapter(entry.createConfig(options));
+}