@neuroverseos/nv-sim 0.1.4 → 0.1.5

package/dist/engine/aiProvider.js

@@ -15,9 +15,44 @@
  *   ai_translator — converts unstructured input → normalized events
  *   ai_analyst    — generates governed reports from traces
  */
+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.DeterministicProvider = exports.AI_ROLES = void 0;
+exports.OpenAICompatibleProvider = exports.AnthropicProvider = exports.DeterministicProvider = exports.AI_ROLES = void 0;
 exports.generateDeterministicReport = generateDeterministicReport;
+exports.generateAIReaction = generateAIReaction;
+exports.getDefaultProviderName = getDefaultProviderName;
 exports.registerAIProvider = registerAIProvider;
 exports.getAIProvider = getAIProvider;
 exports.listAIProviders = listAIProviders;
@@ -37,13 +72,21 @@ exports.AI_ROLES = [
     {
         id: "ai_analyst",
         type: "ai",
-        permissions: ["generate_report", "summarize_trace"],
+        permissions: [
+            "generate_report",
+            "summarize_trace",
+            "suggest_experiments",
+            "detect_archetype",
+            "synthesize_strategy",
+            "compare_experiments",
+        ],
         constraints: [
             "must_reference_trace",
             "must_include_blocked_actions",
             "must_include_metrics",
             "no_unverifiable_claims",
             "no_speculation_without_flag",
+            "must_include_confidence",
         ],
     },
 ];
@@ -186,12 +229,394 @@ function generateDeterministicReport(trace) {
     };
 }
 // ============================================
+// BUILT-IN PROVIDER: ANTHROPIC (CLAUDE)
+// ============================================
+/**
+ * Anthropic Claude provider — real AI reasoning for NeuroverseOS.
+ *
+ * Requires ANTHROPIC_API_KEY environment variable.
+ * Uses Claude to translate unstructured input into normalized events
+ * and generate governed reports from simulation traces.
+ */
+class AnthropicProvider {
+    name = "anthropic";
+    client = null;
+    model;
+    _apiKey;
+    constructor(options) {
+        this.model = options?.model ?? "claude-sonnet-4-20250514";
+        const key = options?.apiKey ?? process.env.ANTHROPIC_API_KEY;
+        if (!key) {
+            throw new Error("AnthropicProvider requires ANTHROPIC_API_KEY environment variable or apiKey option");
+        }
+        this._apiKey = key;
+    }
+    async getClient() {
+        if (!this.client) {
+            try {
+                const sdk = await Promise.resolve().then(() => __importStar(require("@anthropic-ai/sdk")));
+                const Anthropic = sdk.default ?? sdk.Anthropic;
+                this.client = new Anthropic({ apiKey: this._apiKey });
+            }
+            catch {
+                throw new Error("Failed to load @anthropic-ai/sdk. Install it: npm install @anthropic-ai/sdk");
+            }
+        }
+        return this.client;
+    }
+    async translate(input) {
+        const client = await this.getClient();
+        const response = await client.messages.create({
+            model: this.model,
+            max_tokens: 1024,
+            system: TRANSLATE_SYSTEM_PROMPT,
+            messages: [{ role: "user", content: input }],
+        });
+        const text = response.content[0]?.type === "text" ? response.content[0].text : "[]";
+        return safeParseEventArray(text);
+    }
+    async summarize(trace) {
+        const client = await this.getClient();
+        const traceJson = buildTraceSummaryInput(trace);
+        const response = await client.messages.create({
+            model: this.model,
+            max_tokens: 2048,
+            system: SUMMARIZE_SYSTEM_PROMPT,
+            messages: [{ role: "user", content: `Analyze this simulation trace:\n${traceJson}` }],
+        });
+        const text = response.content[0]?.type === "text" ? response.content[0].text : "{}";
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return generateDeterministicReport(trace);
+        }
+    }
+}
+exports.AnthropicProvider = AnthropicProvider;
+// ============================================
+// BUILT-IN PROVIDER: OPENAI-COMPATIBLE
+// ============================================
+/**
+ * OpenAI-compatible provider — works with ANY API that speaks the
+ * OpenAI chat completions format:
+ *
+ *   - OpenAI (GPT-4, GPT-4o, o1, etc.)
+ *   - Local LLMs: Ollama, LM Studio, vLLM, llama.cpp, LocalAI
+ *   - Cloud APIs: Groq, Together, Fireworks, Mistral, Deepseek, Perplexity
+ *   - Any custom endpoint that implements POST /v1/chat/completions
+ *
+ * Configuration via env vars:
+ *   OPENAI_API_KEY     — API key (set to "none" or "local" for local models)
+ *   OPENAI_BASE_URL    — Custom base URL (default: https://api.openai.com/v1)
+ *   OPENAI_MODEL       — Model name (default: gpt-4o)
+ *
+ * Or via constructor options for full control.
+ */
+class OpenAICompatibleProvider {
+    name;
+    model;
+    baseUrl;
+    apiKey;
+    headers;
+    constructor(options) {
+        this.name = options?.name ?? "openai";
+        this.model = options?.model ?? process.env.OPENAI_MODEL ?? "gpt-4o";
+        this.apiKey = options?.apiKey ?? process.env.OPENAI_API_KEY ?? "";
+        this.baseUrl = (options?.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1")
+            .replace(/\/+$/, ""); // strip trailing slashes
+        this.headers = options?.headers ?? {};
+    }
+    async chatCompletion(systemPrompt, userMessage, maxTokens) {
+        const url = `${this.baseUrl}/chat/completions`;
+        const headers = {
+            "Content-Type": "application/json",
+            ...this.headers,
+        };
+        // Only add Authorization if we have a real key (not "none"/"local"/"")
+        if (this.apiKey && this.apiKey !== "none" && this.apiKey !== "local") {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const body = JSON.stringify({
+            model: this.model,
+            max_tokens: maxTokens,
+            temperature: 0.7,
+            messages: [
+                { role: "system", content: systemPrompt },
+                { role: "user", content: userMessage },
+            ],
+        });
+        const response = await fetch(url, { method: "POST", headers, body });
+        if (!response.ok) {
+            const errText = await response.text().catch(() => "");
+            throw new Error(`${this.name} API error ${response.status}: ${errText.slice(0, 200)}`);
+        }
+        const json = await response.json();
+        return json.choices?.[0]?.message?.content ?? "";
+    }
+    async translate(input) {
+        const text = await this.chatCompletion(TRANSLATE_SYSTEM_PROMPT, input, 1024);
+        return safeParseEventArray(text);
+    }
+    async summarize(trace) {
+        const traceJson = buildTraceSummaryInput(trace);
+        const text = await this.chatCompletion(SUMMARIZE_SYSTEM_PROMPT, `Analyze this simulation trace:\n${traceJson}`, 2048);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return generateDeterministicReport(trace);
+        }
+    }
+}
+exports.OpenAICompatibleProvider = OpenAICompatibleProvider;
+// ============================================
+// SHARED PROMPTS & HELPERS
+// ============================================
+const TRANSLATE_SYSTEM_PROMPT = `You are an event normalizer for NeuroverseOS, a governance simulation platform.
+Given unstructured input, extract structured events. Return ONLY valid JSON — an array of objects with these fields:
+- type (string): event category (market_shock, policy_change, agent_action, etc.)
+- agent (string, optional): who caused it
+- action (string): what happened
+- impact (number, -1 to 1): negative to positive impact
+- confidence (number, 0 to 1): how confident you are
+- severity (number, 0 to 1): how severe
+- sector (string, optional): affected domain
+No markdown, no explanation — just the JSON array.`;
+const SUMMARIZE_SYSTEM_PROMPT = `You are a governance analyst for NeuroverseOS. Analyze simulation trace data and produce a structured report.
+Return ONLY valid JSON matching this schema:
+{
+  "executiveSummary": "string — 2-3 sentence overview",
+  "keyEvents": [{"round": number, "description": "string", "agents": ["string"], "severity": "low|moderate|high|critical"}],
+  "governanceActions": [{"type": "BLOCK|PAUSE|CIRCUIT_BREAKER|REBALANCE", "agent": "string", "description": "string"}],
+  "metrics": {"volatilityReduction": "string", "collapseRisk": "string", "stabilityScore": "string", "interventionCount": number, "blockedActions": number},
+  "counterfactual": "string — what would have happened without governance",
+  "observations": ["string — insight about agent behavior under governance"],
+  "generatedBy": "ai",
+  "governedBy": "NeuroverseOS"
+}
+Focus on WHAT AGENTS DID DIFFERENTLY under governance — behavioral shifts matter more than raw block counts.`;
+const AGENT_REACTION_SYSTEM_PROMPT = `You are a stakeholder in a NeuroverseOS governance simulation.
+You will be given your identity, the scenario, and the current state.
+React in character. Return ONLY valid JSON:
+{
+  "reaction": "1-2 sentence description of your reaction and reasoning",
+  "impact": <number from -1 (strongly negative) to 1 (strongly positive)>,
+  "confidence": <number from 0 to 1 — how sure you are>,
+  "trigger": "brief label for what drove this reaction"
+}`;
+function safeParseEventArray(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch {
+        return [{
+                type: "ai_translation",
+                action: "parsed_input",
+                impact: 0,
+                confidence: 0.5,
+                metadata: { raw: text, source: "ai" },
+            }];
+    }
+}
+function buildTraceSummaryInput(trace) {
+    return JSON.stringify({
+        scenario: trace.scenario,
+        roundCount: trace.rounds.length,
+        totalReactions: trace.rounds.reduce((s, r) => s + r.reactions.length, 0),
+        metrics: trace.metrics,
+        governanceStats: trace.governanceStats,
+        interventions: trace.interventions.slice(0, 20),
+        sampleRounds: trace.rounds.slice(0, 3),
+    });
+}
+/**
+ * Generate an AI-powered stakeholder reaction.
+ *
+ * Works with ANY provider — Anthropic, OpenAI, local LLM, etc.
+ * Each agent gets an LLM call to decide how they'd actually react.
+ */
+async function generateAIReaction(options) {
+    const provider = options.provider ?? getAIProvider(getDefaultProviderName());
+    if (provider.name === "deterministic") {
+        return {
+            reaction: `${options.stakeholderId} evaluates the situation (no AI provider configured)`,
+            impact: 0,
+            confidence: 0.3,
+            trigger: "No AI provider — deterministic fallback",
+        };
+    }
+    const userPrompt = `You are ${options.stakeholderId}${options.stakeholderDescription ? ` (${options.stakeholderDescription})` : ""}.
+Disposition: ${options.stakeholderDisposition ?? "unknown"}
+Priorities: ${options.stakeholderPriorities?.join(", ") ?? "not specified"}
+
+SCENARIO: ${options.scenario}
+CURRENT PATH: ${options.pathDescription}
+RISK LEVEL: ${options.pathRisk}
+ROUND: ${options.round + 1}
+${options.previousReactions?.length ? `\nPREVIOUS REACTIONS THIS ROUND:\n${options.previousReactions.join("\n")}` : ""}
+
+How do you react?`;
+    try {
+        // Route through the appropriate provider
+        if (provider instanceof AnthropicProvider) {
+            const client = await provider.getClient();
+            const response = await client.messages.create({
+                model: provider.model,
+                max_tokens: 256,
+                system: AGENT_REACTION_SYSTEM_PROMPT,
+                messages: [{ role: "user", content: userPrompt }],
+            });
+            const text = response.content[0]?.type === "text" ? response.content[0].text : "{}";
+            return parseReactionResponse(text, options.stakeholderId);
+        }
+        else if (provider instanceof OpenAICompatibleProvider) {
+            // Use the OpenAI-compatible chat completions directly
+            const text = await provider.chatCompletion(AGENT_REACTION_SYSTEM_PROMPT, userPrompt, 256);
+            return parseReactionResponse(text, options.stakeholderId);
+        }
+        else {
+            // Generic provider — use translate as a proxy
+            const events = await provider.translate(`Stakeholder ${options.stakeholderId} reacts to: ${options.pathDescription} (risk: ${options.pathRisk})`);
+            const event = events[0];
+            return {
+                reaction: `${options.stakeholderId}: ${event?.action ?? "no reaction"}`,
+                impact: event?.impact ?? 0,
+                confidence: event?.confidence ?? 0.5,
+                trigger: event?.type ?? "provider-generated",
+            };
+        }
+    }
+    catch {
+        return {
+            reaction: `${options.stakeholderId} considers the situation (AI call failed, using fallback)`,
+            impact: 0,
+            confidence: 0.3,
+            trigger: "AI fallback — API error",
+        };
+    }
+}
+function parseReactionResponse(text, stakeholderId) {
+    try {
+        const parsed = JSON.parse(text);
+        return {
+            reaction: String(parsed.reaction ?? `${stakeholderId} reacts`),
+            impact: Math.max(-1, Math.min(1, Number(parsed.impact) || 0)),
+            confidence: Math.max(0, Math.min(1, Number(parsed.confidence) || 0.5)),
+            trigger: String(parsed.trigger ?? "AI-generated reaction"),
+        };
+    }
+    catch {
+        return {
+            reaction: text?.slice(0, 200) || `${stakeholderId} reacts`,
+            impact: 0,
+            confidence: 0.3,
+            trigger: "AI response (unparsed)",
+        };
+    }
+}
+// ============================================
 // PROVIDER REGISTRY
 // ============================================
 /** Registry of available AI providers */
 const providerRegistry = new Map();
 /** Register the deterministic (no-AI) provider by default */
 providerRegistry.set("deterministic", () => new DeterministicProvider());
+/** Register the Anthropic (Claude) provider — activates when ANTHROPIC_API_KEY is set */
+providerRegistry.set("anthropic", () => new AnthropicProvider());
+/**
+ * Register the OpenAI-compatible provider.
+ * Covers: OpenAI, Groq, Together, Fireworks, Mistral, Deepseek, etc.
+ */
+providerRegistry.set("openai", () => new OpenAICompatibleProvider());
+/**
+ * Register local LLM provider — Ollama, LM Studio, vLLM, llama.cpp, LocalAI.
+ * These use the OpenAI-compatible API on localhost.
+ *
+ * Env vars:
+ *   LOCAL_LLM_URL     — e.g. http://localhost:11434/v1 (Ollama)
+ *   LOCAL_LLM_MODEL   — e.g. llama3, mistral, codellama
+ */
+providerRegistry.set("local", () => new OpenAICompatibleProvider({
+    name: "local",
+    baseUrl: process.env.LOCAL_LLM_URL ?? "http://localhost:11434/v1",
+    model: process.env.LOCAL_LLM_MODEL ?? "llama3",
+    apiKey: "local",
+}));
+// Convenience aliases for popular providers
+providerRegistry.set("ollama", () => new OpenAICompatibleProvider({
+    name: "ollama",
+    baseUrl: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1",
+    model: process.env.OLLAMA_MODEL ?? "llama3",
+    apiKey: "local",
+}));
+providerRegistry.set("groq", () => new OpenAICompatibleProvider({
+    name: "groq",
+    baseUrl: "https://api.groq.com/openai/v1",
+    model: process.env.GROQ_MODEL ?? "llama-3.3-70b-versatile",
+    apiKey: process.env.GROQ_API_KEY ?? "",
+}));
+providerRegistry.set("together", () => new OpenAICompatibleProvider({
+    name: "together",
+    baseUrl: "https://api.together.xyz/v1",
+    model: process.env.TOGETHER_MODEL ?? "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
+    apiKey: process.env.TOGETHER_API_KEY ?? "",
+}));
+providerRegistry.set("mistral", () => new OpenAICompatibleProvider({
+    name: "mistral",
+    baseUrl: "https://api.mistral.ai/v1",
+    model: process.env.MISTRAL_MODEL ?? "mistral-large-latest",
+    apiKey: process.env.MISTRAL_API_KEY ?? "",
+}));
+providerRegistry.set("deepseek", () => new OpenAICompatibleProvider({
+    name: "deepseek",
+    baseUrl: "https://api.deepseek.com/v1",
+    model: process.env.DEEPSEEK_MODEL ?? "deepseek-chat",
+    apiKey: process.env.DEEPSEEK_API_KEY ?? "",
+}));
+providerRegistry.set("fireworks", () => new OpenAICompatibleProvider({
+    name: "fireworks",
+    baseUrl: "https://api.fireworks.ai/inference/v1",
+    model: process.env.FIREWORKS_MODEL ?? "accounts/fireworks/models/llama-v3p1-70b-instruct",
+    apiKey: process.env.FIREWORKS_API_KEY ?? "",
+}));
+/**
+ * Auto-detect the best available provider based on environment variables.
+ *
+ * Priority:
+ *   1. ANTHROPIC_API_KEY → anthropic (Claude)
+ *   2. OPENAI_API_KEY    → openai (GPT-4, etc.)
+ *   3. GROQ_API_KEY      → groq
+ *   4. TOGETHER_API_KEY  → together
+ *   5. MISTRAL_API_KEY   → mistral
+ *   6. DEEPSEEK_API_KEY  → deepseek
+ *   7. FIREWORKS_API_KEY → fireworks
+ *   8. LOCAL_LLM_URL     → local (Ollama, LM Studio, vLLM, etc.)
+ *   9. OLLAMA_BASE_URL   → ollama
+ *  10. (none)            → deterministic (Math.random(), no AI)
+ */
+function getDefaultProviderName() {
+    if (process.env.ANTHROPIC_API_KEY)
+        return "anthropic";
+    if (process.env.OPENAI_API_KEY)
+        return "openai";
+    if (process.env.GROQ_API_KEY)
+        return "groq";
+    if (process.env.TOGETHER_API_KEY)
+        return "together";
+    if (process.env.MISTRAL_API_KEY)
+        return "mistral";
+    if (process.env.DEEPSEEK_API_KEY)
+        return "deepseek";
+    if (process.env.FIREWORKS_API_KEY)
+        return "fireworks";
+    if (process.env.LOCAL_LLM_URL)
+        return "local";
+    if (process.env.OLLAMA_BASE_URL)
+        return "ollama";
+    return "deterministic";
+}
 /** Register a custom AI provider */
 function registerAIProvider(name, factory) {
     providerRegistry.set(name, factory);