@neuroverseos/nv-sim 0.1.2 → 0.1.5

package/dist/engine/aiProvider.js

@@ -0,0 +1,681 @@
+"use strict";
+/**
+ * AI Provider — Bring Your Own Model (BYOM)
+ *
+ * AI is NOT the engine. AI is an actor inside the governed system.
+ * Every AI call goes through /world evaluate — same as any other agent.
+ *
+ * Design principles:
+ *   - AI is optional: system works without it
+ *   - AI is governed: subject to world rules like any actor
+ *   - AI is pluggable: users bring their own model + key
+ *   - AI is auditable: every call appears in the trace
+ *
+ * Two governed AI roles:
+ *   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.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;
+exports.evaluateAIAction = evaluateAIAction;
+/** Default AI roles for world definitions */
+exports.AI_ROLES = [
+    {
+        id: "ai_translator",
+        type: "ai",
+        permissions: ["translate_input"],
+        constraints: [
+            "must_output_valid_schema",
+            "no_invention_of_events",
+            "confidence_must_be_provided",
+        ],
+    },
+    {
+        id: "ai_analyst",
+        type: "ai",
+        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",
+        ],
+    },
+];
+// ============================================
+// BUILT-IN PROVIDER: DETERMINISTIC (NO AI)
+// ============================================
+/**
+ * Default provider when no AI is configured.
+ * Generates structured reports purely from trace data.
+ * No LLM. No API key. No network.
+ */
+class DeterministicProvider {
+    name = "deterministic";
+    async translate(input) {
+        // Without AI, parse basic structured hints from input
+        const events = [];
+        const lower = input.toLowerCase();
+        if (lower.includes("sell") || lower.includes("panic") || lower.includes("crash")) {
+            events.push({
+                type: "market_shock",
+                action: "sell_pressure",
+                impact: -0.7,
+                confidence: 0.6,
+                severity: 0.8,
+            });
+        }
+        if (lower.includes("buy") || lower.includes("rally") || lower.includes("recover")) {
+            events.push({
+                type: "market_recovery",
+                action: "buy_pressure",
+                impact: 0.5,
+                confidence: 0.5,
+                severity: 0.3,
+            });
+        }
+        if (events.length === 0) {
+            events.push({
+                type: "unstructured_input",
+                action: "needs_ai_translation",
+                impact: 0,
+                confidence: 0.3,
+                metadata: { raw: input },
+            });
+        }
+        return events;
+    }
+    async summarize(trace) {
+        return generateDeterministicReport(trace);
+    }
+}
+exports.DeterministicProvider = DeterministicProvider;
+/**
+ * Generate a report purely from trace data — no AI needed.
+ * This is the fallback and also proves governance doesn't need AI.
+ */
+function generateDeterministicReport(trace) {
+    const { metrics, interventions, governanceStats, rounds } = trace;
+    // Extract key events from rounds with highest intervention counts
+    const keyEvents = rounds
+        .filter(r => r.interventions.length > 0)
+        .slice(0, 5)
+        .map(r => {
+        const agents = [...new Set(r.reactions.map(rx => rx.agent))];
+        const hasBlock = r.interventions.some(i => i.includes("[BLOCK]"));
+        return {
+            round: r.round,
+            description: r.interventions[0].replace(/^\[.*?\]\s*/, ""),
+            agents,
+            severity: (hasBlock ? "high" : "moderate"),
+        };
+    });
+    // Extract governance actions
+    const governanceActions = interventions
+        .slice(0, 10)
+        .map(intervention => {
+        const blockMatch = intervention.match(/^\[(BLOCK|PAUSE|GATE-\d+)\]\s*(.*?):\s*(.*)/);
+        if (blockMatch) {
+            const typeRaw = blockMatch[1];
+            const type = typeRaw === "BLOCK"
+                ? "BLOCK"
+                : typeRaw === "PAUSE"
+                    ? "PAUSE"
+                    : typeRaw.startsWith("GATE")
+                        ? "CIRCUIT_BREAKER"
+                        : "REBALANCE";
+            return {
+                type,
+                agent: blockMatch[2].trim(),
+                description: blockMatch[3].trim(),
+            };
+        }
+        return {
+            type: "REBALANCE",
+            agent: "system",
+            description: intervention,
+        };
+    });
+    // Build executive summary from metrics
+    const blockCount = governanceStats.blocks;
+    const totalInterventions = interventions.length;
+    const stabilityPct = (metrics.stabilityScore * 100).toFixed(0);
+    const collapsePct = (metrics.collapseProbability * 100).toFixed(0);
+    const executiveSummary = blockCount > 0
+        ? `Governance engine blocked ${blockCount} high-risk actions and applied ${totalInterventions} interventions. System stability: ${stabilityPct}%. Collapse probability held at ${collapsePct}%.`
+        : `Governance constraints applied ${totalInterventions} interventions, maintaining ${stabilityPct}% system stability with ${collapsePct}% collapse risk.`;
+    // Observations derived from trace
+    const observations = [];
+    if (blockCount > 2) {
+        observations.push("Multiple block events indicate aggressive agent behavior was successfully contained by invariant enforcement.");
+    }
+    if (metrics.stabilityScore > 0.6) {
+        observations.push("Governance rules maintained system stability above critical thresholds throughout the simulation.");
+    }
+    if (metrics.maxVolatility > 0.5) {
+        observations.push(`Peak volatility of ${(metrics.maxVolatility * 100).toFixed(0)}% was dampened by circuit breaker gates.`);
+    }
+    if (governanceStats.rulesFired > 3) {
+        observations.push(`${governanceStats.rulesFired} world rules fired during deterministic simulation, shaping agent behavior across rounds.`);
+    }
+    if (observations.length === 0) {
+        observations.push("Governance constraints maintained equilibrium with minimal intervention required.");
+    }
+    return {
+        executiveSummary,
+        keyEvents,
+        governanceActions,
+        metrics: {
+            volatilityReduction: `${(metrics.maxVolatility * 100).toFixed(0)}% peak`,
+            collapseRisk: `${collapsePct}%`,
+            stabilityScore: `${stabilityPct}%`,
+            interventionCount: totalInterventions,
+            blockedActions: blockCount,
+        },
+        counterfactual: totalInterventions > 3
+            ? `Without governance constraints, ${blockCount} blocked actions would have proceeded unchecked, likely increasing volatility beyond recovery thresholds.`
+            : undefined,
+        observations,
+        generatedBy: "deterministic",
+        governedBy: "NeuroverseOS",
+    };
+}
+// ============================================
+// 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);
+}
+/** Get the active AI provider */
+function getAIProvider(name) {
+    const providerName = name ?? "deterministic";
+    const factory = providerRegistry.get(providerName);
+    if (!factory) {
+        console.warn(`AI provider "${providerName}" not found, falling back to deterministic`);
+        return new DeterministicProvider();
+    }
+    return factory();
+}
+/** List available provider names */
+function listAIProviders() {
+    return [...providerRegistry.keys()];
+}
+/**
+ * Evaluate an AI action through governance.
+ *
+ * This is the critical function: ALL AI calls go through here.
+ * The AI actor is subject to the same rules as any other agent.
+ */
+async function evaluateAIAction(actor, action, execute) {
+    const violations = [];
+    // Pre-execution: verify actor has permission
+    if (!actor.permissions.includes(action)) {
+        violations.push(`Actor ${actor.id} lacks permission for action: ${action}`);
+    }
+    // Execute the AI action
+    const result = await execute();
+    // Post-execution: validate constraints
+    if (action === "generate_report" && result && typeof result === "object") {
+        const report = result;
+        for (const constraint of actor.constraints) {
+            if (constraint === "must_include_blocked_actions") {
+                if (!report.governanceActions || report.governanceActions.length === 0) {
+                    if (report.metrics?.blockedActions && report.metrics.blockedActions > 0) {
+                        violations.push("Report missing governance action details despite blocks occurring");
+                    }
+                }
+            }
+            if (constraint === "must_include_metrics") {
+                if (!report.metrics) {
+                    violations.push("Report missing required metrics section");
+                }
+            }
+        }
+    }
+    return {
+        result,
+        actor: actor.id,
+        action,
+        governed: true,
+        trace: {
+            constraints: actor.constraints,
+            passed: violations.length === 0,
+            violations,
+        },
+    };
+}