@neuroverseos/nv-sim 0.1.2 → 0.1.6

package/dist/lib/simulationAdapter.js

@@ -0,0 +1,686 @@
+"use strict";
+/**
+ * Universal Simulation Adapter
+ *
+ * Converts output from ANY simulation engine into a normalized schema
+ * that Echelon can reason about. Supported formats:
+ *
+ *   - MiroFish (JSON with agents + emergent_behaviors)
+ *   - NetLogo (tick-based key:value output)
+ *   - Mesa (Python agent action logs)
+ *   - AnyLogic / CSV (time-series tabular data)
+ *   - Generic JSON (any structured simulation output)
+ *   - Freeform text (natural language simulation descriptions)
+ *
+ * Architecture:
+ *   Raw simulation output → detectFormat() → parse*() → NormalizedSwarm
+ *   NormalizedSwarm → Echelon reasoning → strategic insights
+ *
+ * Key insight: every simulation engine produces the same types of signals:
+ *   agents, states, interactions, events, outcomes, timelines
+ * The adapter normalizes these into a universal internal schema.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORMAT_LABELS = void 0;
+exports.detectFormat = detectFormat;
+exports.parseSimulation = parseSimulation;
+// ============================================
+// FORMAT DETECTION
+// ============================================
+/**
+ * Detect the simulation format from raw input.
+ * Uses heuristics — no false positives needed, just best guess.
+ */
+function detectFormat(input) {
+    const trimmed = input.trim();
+    // Try JSON first
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            const data = JSON.parse(trimmed);
+            if (looksLikeMiroFish(data))
+                return "mirofish";
+            return "generic_json";
+        }
+        catch {
+            // Not valid JSON, fall through
+        }
+    }
+    // CSV: lines with commas and a header row
+    if (looksLikeCsv(trimmed))
+        return "anylogic_csv";
+    // NetLogo: tick-based key:value or key-value pairs
+    if (looksLikeNetLogo(trimmed))
+        return "netlogo";
+    // Mesa: agent action logs
+    if (looksLikeMesa(trimmed))
+        return "mesa";
+    return "freeform_text";
+}
+function looksLikeMiroFish(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const d = data;
+    return ((Array.isArray(d.agents) || Array.isArray(d.fish) || Array.isArray(d.swarm)) &&
+        (d.emergent_behaviors !== undefined ||
+            d.emergent_dynamics !== undefined ||
+            d.timeline !== undefined ||
+            d.simulation !== undefined));
+}
+function looksLikeCsv(text) {
+    const lines = text.split("\n").filter((l) => l.trim());
+    if (lines.length < 2)
+        return false;
+    const header = lines[0];
+    // Must have commas and look like a header
+    if (!header.includes(","))
+        return false;
+    const headerParts = header.split(",").map((h) => h.trim());
+    const dataLine = lines[1].split(",");
+    // Header should have words, data should have numbers
+    const headerHasWords = headerParts.some((h) => /^[a-zA-Z_]/.test(h));
+    const dataHasNumbers = dataLine.some((d) => !isNaN(Number(d.trim())));
+    return headerHasWords && dataHasNumbers && headerParts.length >= 2;
+}
+function looksLikeNetLogo(text) {
+    const lines = text.split("\n").filter((l) => l.trim());
+    // NetLogo: "key: value" or "key value" format with ticks
+    const kvPattern = /^[\w-]+\s*:\s*.+$/;
+    const tickPattern = /tick|step|round|iteration/i;
+    const kvMatches = lines.filter((l) => kvPattern.test(l.trim())).length;
+    const hasTick = lines.some((l) => tickPattern.test(l));
+    return (kvMatches >= 3 && kvMatches >= lines.length * 0.5) || (kvMatches >= 2 && hasTick);
+}
+function looksLikeMesa(text) {
+    const lines = text.split("\n").filter((l) => l.trim());
+    // Mesa: "Agent N: action" format
+    const agentPattern = /^(?:agent|player|entity)\s+\d+\s*:\s*.+$/i;
+    const agentMatches = lines.filter((l) => agentPattern.test(l.trim())).length;
+    return agentMatches >= 2 && agentMatches >= lines.length * 0.3;
+}
+// ============================================
+// PARSERS
+// ============================================
+/**
+ * Parse any simulation output into NormalizedSwarm.
+ * Auto-detects format and dispatches to the appropriate parser.
+ */
+function parseSimulation(input) {
+    const format = detectFormat(input);
+    switch (format) {
+        case "mirofish":
+            return parseMiroFish(input);
+        case "netlogo":
+            return parseNetLogo(input);
+        case "mesa":
+            return parseMesa(input);
+        case "anylogic_csv":
+            return parseCsv(input);
+        case "generic_json":
+            return parseGenericJson(input);
+        case "freeform_text":
+            return parseFreeformText(input);
+    }
+}
+// ── MiroFish Parser ──────────────────────────────────
+function parseMiroFish(input) {
+    const data = JSON.parse(input.trim());
+    const agents = [];
+    const events = [];
+    const stateChanges = [];
+    const metrics = [];
+    const timeline = [];
+    const coalitions = [];
+    // Parse agents
+    const rawAgents = data.agents || data.fish || data.swarm || [];
+    for (const a of rawAgents) {
+        agents.push({
+            id: a.id || a.name || a.type || `agent_${agents.length}`,
+            type: a.type || a.role || "agent",
+            state: a.state || a.status,
+            action: a.reaction || a.action || a.behavior,
+            attributes: extractAttributes(a, ["id", "name", "type", "role", "state", "status", "reaction", "action", "behavior"]),
+        });
+        if (a.reaction || a.action) {
+            events.push({
+                agents: [a.id || a.name || a.type],
+                action: a.reaction || a.action,
+                category: "reaction",
+            });
+        }
+    }
+    // Parse emergent behaviors
+    const emergentBehaviors = [];
+    if (data.emergent_behaviors) {
+        for (const b of Array.isArray(data.emergent_behaviors) ? data.emergent_behaviors : [data.emergent_behaviors]) {
+            emergentBehaviors.push(typeof b === "string" ? b : JSON.stringify(b));
+        }
+    }
+    if (data.emergent_dynamics) {
+        for (const d of Array.isArray(data.emergent_dynamics) ? data.emergent_dynamics : [data.emergent_dynamics]) {
+            emergentBehaviors.push(typeof d === "string" ? d : JSON.stringify(d));
+        }
+    }
+    // Parse timeline
+    if (data.timeline && Array.isArray(data.timeline)) {
+        for (const entry of data.timeline) {
+            if (typeof entry === "object") {
+                const { time, step, round, tick, ...rest } = entry;
+                timeline.push({
+                    time: time ?? step ?? round ?? tick ?? timeline.length,
+                    state: rest,
+                });
+            }
+        }
+    }
+    // Parse steps (MiroFish simulation output)
+    if (data.steps && Array.isArray(data.steps)) {
+        for (const step of data.steps) {
+            const t = step.step ?? step.round ?? timeline.length;
+            if (step.actions && Array.isArray(step.actions)) {
+                for (const action of step.actions) {
+                    events.push({
+                        time: t,
+                        agents: action.agent ? [action.agent] : undefined,
+                        action: action.action || action.type || JSON.stringify(action),
+                        effect: action.result || action.effect,
+                        category: "action",
+                    });
+                }
+            }
+        }
+    }
+    // Extract metrics from any numeric top-level fields
+    for (const [key, value] of Object.entries(data)) {
+        if (typeof value === "number" && !["version", "seed", "id"].includes(key)) {
+            metrics.push({ name: humanize(key), value });
+        }
+    }
+    return {
+        sourceFormat: "mirofish",
+        agents,
+        events,
+        stateChanges,
+        coalitions,
+        metrics,
+        timeline,
+        emergentBehaviors: emergentBehaviors.length > 0 ? emergentBehaviors : undefined,
+        summary: data.summary || data.description,
+    };
+}
+// ── NetLogo Parser ───────────────────────────────────
+function parseNetLogo(input) {
+    const lines = input.split("\n").filter((l) => l.trim());
+    const metrics = [];
+    const stateChanges = [];
+    const agents = [];
+    let currentTick;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Check for tick/step indicator
+        const tickMatch = trimmed.match(/(?:tick|step|round|iteration)\s*[:#=]?\s*(\d+)/i);
+        if (tickMatch) {
+            currentTick = parseInt(tickMatch[1]);
+            continue;
+        }
+        // Parse key: value pairs
+        const kvMatch = trimmed.match(/^([\w-]+)\s*:\s*(.+)$/);
+        if (kvMatch) {
+            const key = kvMatch[1].trim();
+            const rawValue = kvMatch[2].trim();
+            // Try to parse as number
+            const numValue = parseFloat(rawValue.replace("%", ""));
+            if (!isNaN(numValue)) {
+                const isPercent = rawValue.includes("%");
+                metrics.push({
+                    name: humanize(key),
+                    value: isPercent ? numValue / 100 : numValue,
+                    unit: isPercent ? "%" : undefined,
+                });
+                stateChanges.push({
+                    variable: key,
+                    to: isPercent ? numValue / 100 : numValue,
+                    time: currentTick,
+                });
+            }
+            else {
+                // Treat as agent or categorical state
+                agents.push({
+                    id: key,
+                    type: "entity",
+                    state: rawValue,
+                });
+            }
+            continue;
+        }
+        // Parse "key value" format (space-separated)
+        const spaceKv = trimmed.match(/^([\w-]+)\s+([-\d.]+%?)$/);
+        if (spaceKv) {
+            const numVal = parseFloat(spaceKv[2].replace("%", ""));
+            if (!isNaN(numVal)) {
+                metrics.push({
+                    name: humanize(spaceKv[1]),
+                    value: spaceKv[2].includes("%") ? numVal / 100 : numVal,
+                    unit: spaceKv[2].includes("%") ? "%" : undefined,
+                });
+            }
+        }
+    }
+    // Infer agents from metric names that suggest agent types
+    const agentPatterns = /consumer|producer|trader|voter|citizen|firm|bank|government|regulator/i;
+    for (const m of metrics) {
+        const match = m.name.match(agentPatterns);
+        if (match && !agents.some((a) => a.type === match[0].toLowerCase())) {
+            agents.push({
+                id: match[0].toLowerCase(),
+                type: match[0].toLowerCase(),
+                attributes: { [m.name]: m.value },
+            });
+        }
+    }
+    return {
+        sourceFormat: "netlogo",
+        agents,
+        events: [],
+        stateChanges,
+        coalitions: [],
+        metrics,
+        timeline: currentTick !== undefined
+            ? [{ time: currentTick, state: Object.fromEntries(metrics.map((m) => [m.name, m.value])) }]
+            : [],
+    };
+}
+// ── Mesa Parser ──────────────────────────────────────
+function parseMesa(input) {
+    const lines = input.split("\n").filter((l) => l.trim());
+    const agents = [];
+    const events = [];
+    const agentMap = new Map();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // "Agent N: action" format
+        const agentMatch = trimmed.match(/^(?:agent|player|entity)\s+(\w+)\s*:\s*(.+)$/i);
+        if (agentMatch) {
+            const agentId = agentMatch[1];
+            const action = agentMatch[2].trim();
+            if (!agentMap.has(agentId)) {
+                const agent = {
+                    id: `agent_${agentId}`,
+                    type: "agent",
+                    action,
+                };
+                agentMap.set(agentId, agent);
+                agents.push(agent);
+            }
+            else {
+                agentMap.get(agentId).action = action;
+            }
+            events.push({
+                agents: [`agent_${agentId}`],
+                action,
+                category: "action",
+            });
+            continue;
+        }
+        // "Name: action" format (capitalized names)
+        const namedMatch = trimmed.match(/^([A-Z][\w\s]+?)\s*:\s*(.+)$/);
+        if (namedMatch) {
+            const agentId = namedMatch[1].trim();
+            const action = namedMatch[2].trim();
+            if (!agentMap.has(agentId)) {
+                const agent = {
+                    id: agentId,
+                    type: inferAgentType(agentId),
+                    action,
+                };
+                agentMap.set(agentId, agent);
+                agents.push(agent);
+            }
+            events.push({
+                agents: [agentId],
+                action,
+                category: "action",
+            });
+        }
+    }
+    return {
+        sourceFormat: "mesa",
+        agents,
+        events,
+        stateChanges: [],
+        coalitions: [],
+        metrics: [],
+        timeline: [],
+    };
+}
+// ── CSV / AnyLogic Parser ────────────────────────────
+function parseCsv(input) {
+    const lines = input.split("\n").filter((l) => l.trim());
+    if (lines.length < 2) {
+        return emptySwarm("anylogic_csv");
+    }
+    const headers = lines[0].split(",").map((h) => h.trim().replace(/^["']|["']$/g, ""));
+    const timeline = [];
+    const metrics = [];
+    const metricSeries = new Map();
+    // Find time column
+    const timeIdx = headers.findIndex((h) => /^(time|tick|step|round|t|timestamp|period|year|month|day|date)$/i.test(h));
+    for (let i = 1; i < lines.length; i++) {
+        const cols = lines[i].split(",").map((c) => c.trim().replace(/^["']|["']$/g, ""));
+        if (cols.length < headers.length)
+            continue;
+        const time = timeIdx >= 0 ? (isNaN(Number(cols[timeIdx])) ? cols[timeIdx] : Number(cols[timeIdx])) : i;
+        const state = {};
+        for (let j = 0; j < headers.length; j++) {
+            if (j === timeIdx)
+                continue;
+            const val = cols[j];
+            const numVal = Number(val);
+            state[headers[j]] = isNaN(numVal) ? val : numVal;
+            // Build time series for each numeric column
+            if (!isNaN(numVal)) {
+                if (!metricSeries.has(headers[j]))
+                    metricSeries.set(headers[j], []);
+                metricSeries.get(headers[j]).push({ time, value: numVal });
+            }
+        }
+        timeline.push({ time, state });
+    }
+    // Build metrics from the last row + full series
+    for (const [name, series] of metricSeries) {
+        const lastValue = series[series.length - 1].value;
+        const firstValue = series[0].value;
+        const trend = series.length < 2 ? "stable" :
+            lastValue > firstValue * 1.05 ? "rising" :
+                lastValue < firstValue * 0.95 ? "falling" :
+                    "stable";
+        metrics.push({
+            name: humanize(name),
+            value: lastValue,
+            trend,
+            series,
+        });
+    }
+    // Infer agents from column names
+    const agents = [];
+    const agentPatterns = /consumer|producer|trader|voter|citizen|firm|bank|government|regulator|price|supply|demand/i;
+    for (const header of headers) {
+        const match = header.match(agentPatterns);
+        if (match) {
+            const lastState = timeline[timeline.length - 1]?.state;
+            agents.push({
+                id: header,
+                type: inferAgentType(header),
+                attributes: lastState ? { value: lastState[header] } : undefined,
+            });
+        }
+    }
+    return {
+        sourceFormat: "anylogic_csv",
+        agents,
+        events: [],
+        stateChanges: [],
+        coalitions: [],
+        metrics,
+        timeline,
+    };
+}
+// ── Generic JSON Parser ──────────────────────────────
+function parseGenericJson(input) {
+    const data = JSON.parse(input.trim());
+    const agents = [];
+    const events = [];
+    const metrics = [];
+    const stateChanges = [];
+    const timeline = [];
+    const coalitions = [];
+    // Recursively extract known structures
+    function walk(obj, path = "") {
+        if (Array.isArray(obj)) {
+            // Array of agent-like objects
+            if (obj.length > 0 && typeof obj[0] === "object" && obj[0] !== null) {
+                const first = obj[0];
+                if (first.id || first.name || first.agent || first.type) {
+                    for (const item of obj) {
+                        const o = item;
+                        agents.push({
+                            id: String(o.id || o.name || o.agent || `${path}_${agents.length}`),
+                            type: String(o.type || o.role || o.class || "agent"),
+                            state: o.state ? String(o.state) : undefined,
+                            action: o.action ? String(o.action) : o.reaction ? String(o.reaction) : undefined,
+                            attributes: extractAttributes(o, ["id", "name", "agent", "type", "role", "class", "state", "action", "reaction"]),
+                        });
+                    }
+                    return;
+                }
+                if (first.time || first.step || first.tick) {
+                    for (const item of obj) {
+                        const o = item;
+                        const t = o.time ?? o.step ?? o.tick ?? timeline.length;
+                        const state = {};
+                        for (const [k, v] of Object.entries(o)) {
+                            if (["time", "step", "tick"].includes(k))
+                                continue;
+                            if (typeof v === "number" || typeof v === "string" || typeof v === "boolean") {
+                                state[k] = v;
+                            }
+                        }
+                        timeline.push({ time: t, state });
+                    }
+                    return;
+                }
+                if (first.action || first.event) {
+                    for (const item of obj) {
+                        const o = item;
+                        events.push({
+                            agents: o.agent ? [String(o.agent)] : o.agents ? o.agents : undefined,
+                            action: String(o.action || o.event || o.type || "unknown"),
+                            effect: o.effect ? String(o.effect) : o.result ? String(o.result) : undefined,
+                            time: (o.time ?? o.step),
+                            category: "action",
+                        });
+                    }
+                    return;
+                }
+            }
+        }
+        else if (typeof obj === "object" && obj !== null) {
+            for (const [key, value] of Object.entries(obj)) {
+                if (typeof value === "number") {
+                    metrics.push({ name: humanize(key), value });
+                }
+                else if (typeof value === "object") {
+                    walk(value, path ? `${path}.${key}` : key);
+                }
+            }
+        }
+    }
+    if (typeof data === "object" && data !== null) {
+        // Handle top-level known arrays
+        const d = data;
+        if (d.agents)
+            walk(d.agents, "agents");
+        if (d.events)
+            walk(d.events, "events");
+        if (d.timeline)
+            walk(d.timeline, "timeline");
+        if (d.coalitions && Array.isArray(d.coalitions)) {
+            for (const c of d.coalitions) {
+                const co = c;
+                coalitions.push({
+                    name: String(co.name || `coalition_${coalitions.length}`),
+                    members: Array.isArray(co.members) ? co.members.map(String) : [],
+                    objective: co.objective ? String(co.objective) : undefined,
+                    strength: typeof co.strength === "number" ? co.strength : undefined,
+                });
+            }
+        }
+        // Walk remaining fields
+        for (const [key, value] of Object.entries(d)) {
+            if (["agents", "events", "timeline", "coalitions"].includes(key))
+                continue;
+            if (typeof value === "number") {
+                metrics.push({ name: humanize(key), value });
+            }
+            else if (typeof value === "object" && value !== null) {
+                walk(value, key);
+            }
+        }
+    }
+    return {
+        sourceFormat: "generic_json",
+        agents,
+        events,
+        stateChanges,
+        coalitions,
+        metrics,
+        timeline,
+        summary: typeof data.summary === "string"
+            ? data.summary
+            : undefined,
+    };
+}
+// ── Freeform Text Parser ─────────────────────────────
+function parseFreeformText(input) {
+    const text = input.trim();
+    const agents = [];
+    const events = [];
+    const metrics = [];
+    // Extract agent-like names
+    const agentPatterns = [
+        /(?:agent|player|actor|entity|stakeholder)\s*[:#]?\s*["']?(\w[\w\s]{1,25}?)["']?(?:\n|,|;|\.|$)/gi,
+        /^[-•*]\s*(\w[\w\s]{1,20}?)(?:\s*[-:—])/gm,
+    ];
+    const seenAgents = new Set();
+    for (const pattern of agentPatterns) {
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const name = match[1].trim();
+            if (name.length > 1 && name.length < 25 && !isStopWord(name) && !seenAgents.has(name.toLowerCase())) {
+                seenAgents.add(name.toLowerCase());
+                agents.push({
+                    id: name,
+                    type: inferAgentType(name),
+                });
+            }
+        }
+    }
+    // Extract actions from "Name: action" or "Name does X" patterns
+    const actionPattern = /(\w[\w\s]{1,20}?)\s*(?::|—)\s*(.+?)(?:\n|$)/g;
+    let actionMatch;
+    while ((actionMatch = actionPattern.exec(text)) !== null) {
+        const agentName = actionMatch[1].trim();
+        const action = actionMatch[2].trim();
+        if (!isStopWord(agentName) && action.length > 2) {
+            events.push({
+                agents: [agentName],
+                action,
+                category: "action",
+            });
+            if (!seenAgents.has(agentName.toLowerCase())) {
+                seenAgents.add(agentName.toLowerCase());
+                agents.push({ id: agentName, type: inferAgentType(agentName), action });
+            }
+        }
+    }
+    // Extract numbers as metrics
+    const numberPattern = /(\w[\w\s]{1,30}?)\s*(?:=|:)\s*([-\d.]+%?)/g;
+    let numMatch;
+    while ((numMatch = numberPattern.exec(text)) !== null) {
+        const name = numMatch[1].trim();
+        const rawVal = numMatch[2];
+        const val = parseFloat(rawVal.replace("%", ""));
+        if (!isNaN(val) && name.length > 1) {
+            metrics.push({
+                name: humanize(name),
+                value: rawVal.includes("%") ? val / 100 : val,
+                unit: rawVal.includes("%") ? "%" : undefined,
+            });
+        }
+    }
+    return {
+        sourceFormat: "freeform_text",
+        agents,
+        events,
+        stateChanges: [],
+        coalitions: [],
+        metrics,
+        timeline: [],
+        summary: text.length > 200 ? text.slice(0, 200) + "..." : text,
+    };
+}
+// ============================================
+// HELPERS
+// ============================================
+function emptySwarm(format) {
+    return {
+        sourceFormat: format,
+        agents: [],
+        events: [],
+        stateChanges: [],
+        coalitions: [],
+        metrics: [],
+        timeline: [],
+    };
+}
+function humanize(key) {
+    return key
+        .replace(/[-_]/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/\b\w/g, (c) => c.toUpperCase())
+        .trim();
+}
+function inferAgentType(name) {
+    const lower = name.toLowerCase();
+    if (/consumer|buyer|customer|shopper/.test(lower))
+        return "consumer";
+    if (/producer|supplier|manufacturer|seller/.test(lower))
+        return "producer";
+    if (/government|regulator|fed|agency|authority/.test(lower))
+        return "regulator";
+    if (/firm|company|corp|bank|enterprise/.test(lower))
+        return "firm";
+    if (/trader|investor|speculator|market/.test(lower))
+        return "trader";
+    if (/citizen|voter|public|population/.test(lower))
+        return "citizen";
+    if (/politician|senator|president|leader/.test(lower))
+        return "politician";
+    if (/media|press|journalist/.test(lower))
+        return "media";
+    if (/military|army|defense|navy/.test(lower))
+        return "military";
+    return "agent";
+}
+function isStopWord(word) {
+    const stops = new Set([
+        "the", "and", "for", "with", "from", "that", "this", "then",
+        "but", "not", "are", "was", "were", "has", "have", "had",
+        "will", "would", "could", "should", "may", "might",
+        "step", "round", "tick", "time", "result", "output", "data",
+    ]);
+    return stops.has(word.toLowerCase());
+}
+function extractAttributes(obj, exclude) {
+    const attrs = {};
+    let count = 0;
+    for (const [key, value] of Object.entries(obj)) {
+        if (exclude.includes(key))
+            continue;
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            attrs[key] = value;
+            count++;
+        }
+    }
+    return count > 0 ? attrs : undefined;
+}
+// ============================================
+// FORMAT LABELS (for UI)
+// ============================================
+exports.FORMAT_LABELS = {
+    mirofish: "MiroFish",
+    netlogo: "NetLogo",
+    mesa: "Mesa (Python)",
+    anylogic_csv: "AnyLogic / CSV",
+    generic_json: "JSON",
+    freeform_text: "Text",
+};