@neuroverseos/nv-sim 0.1.0

package/dist/engine/mirofish.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * MiroFish Integration Adapter
+ *
+ * Connects Mirotir to MiroFish swarm simulations as an EXTERNAL SERVICE.
+ *
+ * POSITIONING:
+ *   MiroFish shows what might happen → the spectacle
+ *   Mirotir helps you decide what to do → the brain
+ *
+ *   "MiroFish simulates the crowd. Mirotir reasons about the decision."
+ *
+ * LICENSE COMPLIANCE:
+ *   MiroFish is called as an external service via its REST API.
+ *   We do NOT embed, copy, or redistribute MiroFish code.
+ *   We do NOT use MiroFish internals, algorithms, or data structures.
+ *   The integration is purely through the public API contract.
+ *   This is the same relationship as using Stripe's API — we call it, we don't own it.
+ *
+ * ARCHITECTURE:
+ *   Scenario → Echelon reasoning → strategies generated
+ *                                        ↓
+ *                               MiroFish simulation runs
+ *                                        ↓
+ *                               Echelon evaluates outcomes
+ *
+ *   MiroFish = world engine (emergent behavior, swarms, crowds)
+ *   Echelon  = decision engine (structured reasoning, recommendations)
+ *
+ * FALLBACK:
+ *   When MiroFish is not available, we use Echelon's native
+ *   lightweight reaction model (swarmSimulation.ts).
+ *   The API contract is the same either way.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiroFishError = exports.MiroFishClient = exports.DEFAULT_MIROFISH_CONFIG = void 0;
+exports.stakeholdersToMiroFishAgents = stakeholdersToMiroFishAgents;
+exports.miroFishResultToSwarmResult = miroFishResultToSwarmResult;
+exports.buildMiroFishRequest = buildMiroFishRequest;
+exports.configureMiroFish = configureMiroFish;
+exports.getMiroFishClient = getMiroFishClient;
+exports.runUnifiedSimulation = runUnifiedSimulation;
+/**
+ * Default MiroFish configuration.
+ * Assumes local Docker container on default port.
+ */
+exports.DEFAULT_MIROFISH_CONFIG = {
+    endpoint: "http://localhost:8080",
+    timeout: 30000,
+    fallbackToNative: true,
+};
+// ============================================
+// MIROFISH CLIENT
+// ============================================
+/**
+ * MiroFish API client.
+ * Calls MiroFish as an external service via REST API.
+ */
+class MiroFishClient {
+    config;
+    constructor(config) {
+        this.config = { ...exports.DEFAULT_MIROFISH_CONFIG, ...config };
+    }
+    /**
+     * Check if the MiroFish service is available.
+     */
+    async isAvailable() {
+        try {
+            const response = await fetch(`${this.config.endpoint}/health`, {
+                method: "GET",
+                signal: AbortSignal.timeout(5000),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Run a simulation against the MiroFish service.
+     */
+    async simulate(request) {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.config.apiKey) {
+            headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+        }
+        const response = await fetch(`${this.config.endpoint}/simulate`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(this.config.timeout ?? 30000),
+        });
+        if (!response.ok) {
+            throw new MiroFishError(`MiroFish simulation failed: ${response.status} ${response.statusText}`, response.status);
+        }
+        return response.json();
+    }
+    /**
+     * Get the MiroFish service configuration.
+     */
+    getConfig() {
+        return this.config;
+    }
+}
+exports.MiroFishClient = MiroFishClient;
+/**
+ * MiroFish-specific error.
+ */
+class MiroFishError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "MiroFishError";
+        this.statusCode = statusCode;
+    }
+}
+exports.MiroFishError = MiroFishError;
+// ============================================
+// TRANSLATION LAYER
+// ============================================
+/**
+ * Convert Mirotir stakeholders to MiroFish agents.
+ */
+function stakeholdersToMiroFishAgents(stakeholders) {
+    return stakeholders.map((s) => ({
+        id: s.id,
+        role: s.description ?? s.id,
+        disposition: s.disposition,
+        priorities: s.priorities,
+    }));
+}
+/**
+ * Convert MiroFish simulation results to Mirotir's SwarmSimulationResult format.
+ *
+ * This is the key translation — MiroFish provides the raw emergent behavior,
+ * and we normalize it into the format that Echelon's reasoning engine consumes.
+ *
+ * MiroFish shows WHAT happens.
+ * Echelon reasons about WHAT IT MEANS.
+ */
+function miroFishResultToSwarmResult(mfResult) {
+    // Convert MiroFish steps to SwarmRounds
+    const rounds = mfResult.steps.map((step) => {
+        const reactions = step.agent_actions.map((action) => ({
+            stakeholder_id: action.agent_id,
+            reaction: action.action,
+            confidence: action.confidence,
+            impact: action.sentiment,
+            trigger: action.reasoning ?? "MiroFish emergent behavior",
+        }));
+        return {
+            round: step.step,
+            reactions,
+            emergent_dynamics: step.system_events,
+        };
+    });
+    // Determine trajectory from MiroFish final state
+    let trajectory;
+    if (mfResult.final_state.convergence && mfResult.final_state.stability > 0.7) {
+        trajectory = "converging";
+    }
+    else if (mfResult.final_state.convergence) {
+        trajectory = "stabilizing";
+    }
+    else if (mfResult.final_state.stability < 0.3) {
+        trajectory = "escalating";
+    }
+    else {
+        trajectory = "diverging";
+    }
+    // Extract inflection points from emergent patterns
+    const inflection_points = mfResult.emergent_patterns ?? [
+        "MiroFish simulation completed — see rounds for detailed agent behaviors",
+    ];
+    return {
+        rounds,
+        trajectory,
+        inflection_points,
+    };
+}
+/**
+ * Build a MiroFish simulation request from Mirotir inputs.
+ */
+function buildMiroFishRequest(scenario, stakeholders, config) {
+    return {
+        scenario,
+        agents: stakeholdersToMiroFishAgents(config.simulate_stakeholders
+            ? stakeholders.filter((s) => config.simulate_stakeholders.includes(s.id))
+            : stakeholders),
+        steps: config.rounds ?? 3,
+        parameters: {
+            model: config.reaction_model ?? "mixed",
+            pressure: 0.5,
+            allow_coalitions: true,
+        },
+    };
+}
+/**
+ * Singleton MiroFish client instance.
+ * Configured via setMiroFishConfig().
+ */
+let miroFishClient = null;
+/**
+ * Configure the MiroFish connection.
+ * Call this at startup if MiroFish is available.
+ */
+function configureMiroFish(config) {
+    miroFishClient = new MiroFishClient(config);
+}
+/**
+ * Get the current MiroFish client (if configured).
+ */
+function getMiroFishClient() {
+    return miroFishClient;
+}
+/**
+ * Run simulation through unified interface.
+ *
+ * Strategy:
+ * 1. If MiroFish is configured and available → use it
+ * 2. If MiroFish fails and fallback is enabled → use Echelon-native
+ * 3. If MiroFish is not configured → use Echelon-native
+ */
+async function runUnifiedSimulation(scenario, stakeholders, paths, swarmConfig, miroFishOverride) {
+    // Determine which client to use
+    const client = miroFishOverride
+        ? new MiroFishClient(miroFishOverride)
+        : miroFishClient;
+    // Try MiroFish first if configured
+    if (client) {
+        try {
+            const available = await client.isAvailable();
+            if (available) {
+                const request = buildMiroFishRequest(scenario, stakeholders, swarmConfig);
+                const mfResult = await client.simulate(request);
+                const result = miroFishResultToSwarmResult(mfResult);
+                return {
+                    result,
+                    source: "mirofish",
+                    mirofish_simulation_id: mfResult.simulation_id,
+                };
+            }
+        }
+        catch (error) {
+            const fallback = miroFishOverride?.fallbackToNative ?? client.getConfig().fallbackToNative ?? true;
+            if (!fallback) {
+                throw error;
+            }
+            // Log and fall through to native simulation
+            console.warn("[MiroFish] Simulation failed, falling back to Echelon-native:", error instanceof Error ? error.message : "Unknown error");
+        }
+    }
+    // Fall back to Echelon-native simulation
+    const { runSwarmSimulation } = await Promise.resolve().then(() => __importStar(require("./swarmSimulation")));
+    const result = await runSwarmSimulation(scenario, stakeholders, paths, swarmConfig);
+    return {
+        result,
+        source: "echelon-native",
+    };
+}