@revealui/ai 0.8.0 → 0.8.1

package/dist/llm/providers/inference-snaps.d.ts

@@ -4,35 +4,45 @@
  * Local inference via Canonical's inference-snaps OpenAI-compatible API.
  * No API key required. Zero cost, fully offline, hardware-optimized.
  *
- * Supported models (snaps), per Canonical's official catalog at
- * https://documentation.ubuntu.com/inference-snaps/reference/snaps/ :
- *   gemma3                 -  general LLM + vision (text/image in, text out)
- *   deepseek-r1            -  reasoning LLM (chat completions)
- *   qwen-vl                -  vision-language model (image + text)
- *   nemotron-3-nano        -  general LLM (reasoning + non-reasoning, text only)
- *   nemotron-3-nano-omni   -  multimodal (text/image/video/audio in, text out)
+ * Product hardline: US-origin snap models only (see us-origin-snaps.ts).
+ * Allowlisted snaps (install these):
+ *   nemotron-3-nano        -  NVIDIA general + tools (default)
+ *   nemotron-3-nano-omni   -  NVIDIA multimodal
+ *   gemma3 / gemma4        -  Google general + vision + tools
+ *
+ * Canonical also publishes non-US snaps (deepseek-r1, qwen-*, glm-*). Those
+ * are rejected at construction unless REVEALUI_ALLOW_NON_US_MODELS=1.
  *
  * Install a model:
- *   sudo snap install gemma3
- *   gemma3 set http.port=9090   # optional: change port (default varies)
- *   gemma3 status               # shows base URL and available models
+ *   sudo snap install nemotron-3-nano
+ *   nemotron-3-nano set http.port=9090   # optional: change port
+ *   nemotron-3-nano status              # shows base URL and available models
  *
  * Set env vars:
  *   INFERENCE_SNAPS_BASE_URL=http://localhost:9090/v1
- *   LLM_MODEL=gemma3            # must match the snap name / model ID
- *   LLM_EMBED_MODEL=gemma3      # optional: model for embeddings
+ *   LLM_MODEL=nemotron-3-nano   # must match an allowlisted snap model ID
+ *   LLM_EMBED_MODEL=nemotron-3-nano
  *
  * Docs: https://documentation.ubuntu.com/inference-snaps
  */
 import type { Embedding, LLMChatOptions, LLMChunk, LLMEmbedOptions, LLMProvider, LLMProviderConfig, LLMResponse, LLMStreamOptions, Message, ReasonerCapabilities } from './base.js';
+import { DEFAULT_US_ORIGIN_INFERENCE_SNAP } from './us-origin-snaps.js';
 export interface InferenceSnapsProviderConfig extends Omit<LLMProviderConfig, 'apiKey'> {
     apiKey?: string;
     /** Base URL of the inference-snaps service, e.g. http://localhost:9090/v1 */
     baseURL: string;
-    /** Chat/vision model name  -  must match the snap's model ID (e.g. 'gemma3', 'deepseek-r1') */
+    /**
+     * Chat/vision model name — must match an allowlisted snap model ID
+     * (e.g. 'nemotron-3-nano', 'gemma4'). See US_ORIGIN_INFERENCE_SNAP_IDS.
+     */
     model?: string;
     /** Embedding model name. Defaults to the chat model when omitted. */
     embedModel?: string;
+    /**
+     * Bypass US-origin allowlist for this instance (operator/tests only).
+     * Prefer the process env REVEALUI_ALLOW_NON_US_MODELS=1 when needed.
+     */
+    allowNonUsModels?: boolean;
 }
 export declare class InferenceSnapsProvider implements LLMProvider {
     private inner;
@@ -44,4 +54,5 @@ export declare class InferenceSnapsProvider implements LLMProvider {
     stream(messages: Message[], options?: LLMStreamOptions): AsyncIterable<LLMChunk>;
     embed(text: string | string[], _options?: LLMEmbedOptions): Promise<Embedding | Embedding[]>;
 }
+export { DEFAULT_US_ORIGIN_INFERENCE_SNAP };
 //# sourceMappingURL=inference-snaps.d.ts.map

package/dist/llm/providers/inference-snaps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inference-snaps.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/inference-snaps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,OAAO,EACP,oBAAoB,EACrB,MAAM,WAAW,CAAC;AAGnB,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,sBAAuB,YAAW,WAAW;IACxD,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,4BAA4B;IAahD,YAAY,IAAI,oBAAoB;IAgBpC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAIzE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC;IAI1E,KAAK,CACT,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,SAAS,GAAG,SAAS,EAAE,CAAC;CAsBpC"}
+{"version":3,"file":"inference-snaps.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/inference-snaps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,OAAO,EACP,oBAAoB,EACrB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAEL,gCAAgC,EACjC,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,qBAAa,sBAAuB,YAAW,WAAW;IACxD,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,4BAA4B;IAchD,YAAY,IAAI,oBAAoB;IAgBpC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAIzE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC;IAI1E,KAAK,CACT,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,SAAS,GAAG,SAAS,EAAE,CAAC;CAsBpC;AAED,OAAO,EAAE,gCAAgC,EAAE,CAAC"}

package/dist/llm/providers/inference-snaps.js

@@ -4,46 +4,49 @@
  * Local inference via Canonical's inference-snaps OpenAI-compatible API.
  * No API key required. Zero cost, fully offline, hardware-optimized.
  *
- * Supported models (snaps), per Canonical's official catalog at
- * https://documentation.ubuntu.com/inference-snaps/reference/snaps/ :
- *   gemma3                 -  general LLM + vision (text/image in, text out)
- *   deepseek-r1            -  reasoning LLM (chat completions)
- *   qwen-vl                -  vision-language model (image + text)
- *   nemotron-3-nano        -  general LLM (reasoning + non-reasoning, text only)
- *   nemotron-3-nano-omni   -  multimodal (text/image/video/audio in, text out)
+ * Product hardline: US-origin snap models only (see us-origin-snaps.ts).
+ * Allowlisted snaps (install these):
+ *   nemotron-3-nano        -  NVIDIA general + tools (default)
+ *   nemotron-3-nano-omni   -  NVIDIA multimodal
+ *   gemma3 / gemma4        -  Google general + vision + tools
+ *
+ * Canonical also publishes non-US snaps (deepseek-r1, qwen-*, glm-*). Those
+ * are rejected at construction unless REVEALUI_ALLOW_NON_US_MODELS=1.
  *
  * Install a model:
- *   sudo snap install gemma3
- *   gemma3 set http.port=9090   # optional: change port (default varies)
- *   gemma3 status               # shows base URL and available models
+ *   sudo snap install nemotron-3-nano
+ *   nemotron-3-nano set http.port=9090   # optional: change port
+ *   nemotron-3-nano status              # shows base URL and available models
  *
  * Set env vars:
  *   INFERENCE_SNAPS_BASE_URL=http://localhost:9090/v1
- *   LLM_MODEL=gemma3            # must match the snap name / model ID
- *   LLM_EMBED_MODEL=gemma3      # optional: model for embeddings
+ *   LLM_MODEL=nemotron-3-nano   # must match an allowlisted snap model ID
+ *   LLM_EMBED_MODEL=nemotron-3-nano
  *
  * Docs: https://documentation.ubuntu.com/inference-snaps
  */
 import { OpenAICompatProvider } from './openai-compat.js';
+import { assertUsOriginInferenceSnap, DEFAULT_US_ORIGIN_INFERENCE_SNAP, } from './us-origin-snaps.js';
 export class InferenceSnapsProvider {
     inner;
     embedModel;
     baseURL;
     constructor(config) {
         this.baseURL = config.baseURL;
-        // Use the same model for embeddings unless explicitly overridden
-        this.embedModel = config.embedModel ?? config.model ?? 'gemma3';
+        const assertOpts = { allowNonUs: config.allowNonUsModels === true };
+        const model = assertUsOriginInferenceSnap(config.model, assertOpts);
+        this.embedModel = assertUsOriginInferenceSnap(config.embedModel ?? model, assertOpts);
         this.inner = new OpenAICompatProvider({
             ...config,
             // inference-snaps ignores the API key; OpenAI client requires a non-empty value
             apiKey: config.apiKey ?? 'inference-snaps',
             baseURL: config.baseURL,
-            model: config.model ?? 'gemma3',
+            model,
         });
     }
     capabilities() {
-        // Profile for the default model (gemma3, text-only). Per-model capability
-        // negotiation (e.g. qwen-vl vision, deepseek-r1 reasoningEffort) is a follow-up.
+        // Profile for the default US-origin model (text + tools). Per-model capability
+        // negotiation (e.g. nemotron-3-nano-omni vision) is a follow-up.
         return {
             providerTag: 'inference-snaps',
             tools: true,
@@ -80,3 +83,4 @@ export class InferenceSnapsProvider {
         return Array.isArray(text) ? embeddings : embeddings[0];
     }
 }
+export { DEFAULT_US_ORIGIN_INFERENCE_SNAP };

package/dist/llm/providers/us-origin-snaps.d.ts

@@ -0,0 +1,79 @@
+/**
+ * US-origin Inference Snap allowlist (product hardline).
+ *
+ * Canonical's snap catalog includes PRC-origin models (DeepSeek, Qwen, GLM).
+ * RevealUI product local inference is **US-origin weights only**, fail-closed.
+ *
+ * Definition: open weights published by an organization whose ultimate parent
+ * is incorporated in the United States. Packaging (Canonical snaps) is not origin.
+ *
+ * Allowlist today (Canonical catalog, 2026-07):
+ *   - nemotron-3-nano / nemotron-3-nano-omni — NVIDIA
+ *   - gemma3 / gemma4 — Google (Alphabet)
+ *
+ * Escape (operator-only, never seed, always loud in the error path):
+ *   REVEALUI_ALLOW_NON_US_MODELS=1
+ *
+ * Companion ADR: .jv docs/decisions/2026-07-24-us-origin-inference-snaps.md
+ */
+/**
+ * Product install/list catalog (snap name + operator-facing description).
+ * SSOT for harnesses InferenceService + Studio install UIs.
+ * Order: product default first (nemotron for capable hosts; gemma preferred on low-RAM via profile daily).
+ */
+export declare const PRODUCT_INFERENCE_SNAP_CATALOG: readonly [{
+    readonly id: "nemotron-3-nano";
+    readonly description: "NVIDIA (US) — general + tools; product default on capable hosts";
+}, {
+    readonly id: "nemotron-3-nano-omni";
+    readonly description: "NVIDIA (US) — multimodal (text/image/video/audio in)";
+}, {
+    readonly id: "gemma4";
+    readonly description: "Google (US) — general + vision + tools";
+}, {
+    readonly id: "gemma3";
+    readonly description: "Google (US) — general + vision; prefer 270m on low-RAM hosts";
+}];
+export type UsOriginInferenceSnapId = (typeof PRODUCT_INFERENCE_SNAP_CATALOG)[number]['id'];
+/** Snap model IDs permitted for product Inference Snaps usage. */
+export declare const US_ORIGIN_INFERENCE_SNAP_IDS: readonly UsOriginInferenceSnapId[];
+/** Default chat/embed model when none is specified (env factory / provider). */
+export declare const DEFAULT_US_ORIGIN_INFERENCE_SNAP: UsOriginInferenceSnapId;
+/** Preferred snap on constrained hosts (profile `snaps` tier). */
+export declare const DEFAULT_LOW_RAM_INFERENCE_SNAP: UsOriginInferenceSnapId;
+/** Preferred Ollama model for profile `daily` tier (fits ~4GB WSL). */
+export declare const DEFAULT_DAILY_OLLAMA_MODEL = "gemma3:1b";
+/** Operator escape env var. Never set in customer seed or CI green paths. */
+export declare const NON_US_MODELS_ESCAPE_ENV = "REVEALUI_ALLOW_NON_US_MODELS";
+export declare class NonUsOriginInferenceSnapError extends Error {
+    readonly code: "NON_US_ORIGIN_INFERENCE_SNAP";
+    readonly modelId: string;
+    constructor(modelId: string);
+}
+/** Normalize a snap model id for allowlist comparison. */
+export declare function normalizeInferenceSnapModelId(modelId: string): string;
+/**
+ * True when the model id is on the US-origin product allowlist.
+ *
+ * Accepts exact snap ids (`nemotron-3-nano`) and engine-served variants that
+ * Canonical publishes under the same snap (e.g.
+ * `nemotron-3-nano-30b-a3b-q4-k-m`, `gemma4:e2b` style suffixes with `-` or `:`).
+ * Match longest snap id first so `nemotron-3-nano-omni` wins over `nemotron-3-nano`.
+ */
+export declare function isUsOriginInferenceSnap(modelId: string): boolean;
+/** True when the operator escape hatch is enabled. */
+export declare function isNonUsModelsEscapeEnabled(env?: NodeJS.ProcessEnv): boolean;
+export interface AssertUsOriginInferenceSnapOptions {
+    /** Force-allow non-US models (tests / explicit callers). Overrides env when true. */
+    allowNonUs?: boolean;
+    /** Env source for the escape hatch (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve and enforce the US-origin allowlist.
+ *
+ * @returns the model id to use (default when empty/undefined)
+ * @throws {NonUsOriginInferenceSnapError} when model is off-allowlist and escape is off
+ */
+export declare function assertUsOriginInferenceSnap(modelId: string | undefined, options?: AssertUsOriginInferenceSnapOptions): string;
+//# sourceMappingURL=us-origin-snaps.d.ts.map

package/dist/llm/providers/us-origin-snaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"us-origin-snaps.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/us-origin-snaps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;EAiBjC,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAE5F,kEAAkE;AAClE,eAAO,MAAM,4BAA4B,EAAE,SAAS,uBAAuB,EAClB,CAAC;AAE1D,gFAAgF;AAChF,eAAO,MAAM,gCAAgC,EAAE,uBAA2C,CAAC;AAE3F,kEAAkE;AAClE,eAAO,MAAM,8BAA8B,EAAE,uBAAkC,CAAC;AAEhF,uEAAuE;AACvE,eAAO,MAAM,0BAA0B,cAAc,CAAC;AAEtD,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,iCAAiC,CAAC;AAEvE,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EAAG,8BAA8B,CAAU;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAW5B;AAED,0DAA0D;AAC1D,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQhE;AAED,sDAAsD;AACtD,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGxF;AAED,MAAM,WAAW,kCAAkC;IACjD,qFAAqF;IACrF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,CAAC,EAAE,kCAAkC,GAC3C,MAAM,CAcR"}

package/dist/llm/providers/us-origin-snaps.js

@@ -0,0 +1,108 @@
+/**
+ * US-origin Inference Snap allowlist (product hardline).
+ *
+ * Canonical's snap catalog includes PRC-origin models (DeepSeek, Qwen, GLM).
+ * RevealUI product local inference is **US-origin weights only**, fail-closed.
+ *
+ * Definition: open weights published by an organization whose ultimate parent
+ * is incorporated in the United States. Packaging (Canonical snaps) is not origin.
+ *
+ * Allowlist today (Canonical catalog, 2026-07):
+ *   - nemotron-3-nano / nemotron-3-nano-omni — NVIDIA
+ *   - gemma3 / gemma4 — Google (Alphabet)
+ *
+ * Escape (operator-only, never seed, always loud in the error path):
+ *   REVEALUI_ALLOW_NON_US_MODELS=1
+ *
+ * Companion ADR: .jv docs/decisions/2026-07-24-us-origin-inference-snaps.md
+ */
+/**
+ * Product install/list catalog (snap name + operator-facing description).
+ * SSOT for harnesses InferenceService + Studio install UIs.
+ * Order: product default first (nemotron for capable hosts; gemma preferred on low-RAM via profile daily).
+ */
+export const PRODUCT_INFERENCE_SNAP_CATALOG = [
+    {
+        id: 'nemotron-3-nano',
+        description: 'NVIDIA (US) — general + tools; product default on capable hosts',
+    },
+    {
+        id: 'nemotron-3-nano-omni',
+        description: 'NVIDIA (US) — multimodal (text/image/video/audio in)',
+    },
+    {
+        id: 'gemma4',
+        description: 'Google (US) — general + vision + tools',
+    },
+    {
+        id: 'gemma3',
+        description: 'Google (US) — general + vision; prefer 270m on low-RAM hosts',
+    },
+];
+/** Snap model IDs permitted for product Inference Snaps usage. */
+export const US_ORIGIN_INFERENCE_SNAP_IDS = PRODUCT_INFERENCE_SNAP_CATALOG.map((entry) => entry.id);
+/** Default chat/embed model when none is specified (env factory / provider). */
+export const DEFAULT_US_ORIGIN_INFERENCE_SNAP = 'nemotron-3-nano';
+/** Preferred snap on constrained hosts (profile `snaps` tier). */
+export const DEFAULT_LOW_RAM_INFERENCE_SNAP = 'gemma3';
+/** Preferred Ollama model for profile `daily` tier (fits ~4GB WSL). */
+export const DEFAULT_DAILY_OLLAMA_MODEL = 'gemma3:1b';
+/** Operator escape env var. Never set in customer seed or CI green paths. */
+export const NON_US_MODELS_ESCAPE_ENV = 'REVEALUI_ALLOW_NON_US_MODELS';
+export class NonUsOriginInferenceSnapError extends Error {
+    code = 'NON_US_ORIGIN_INFERENCE_SNAP';
+    modelId;
+    constructor(modelId) {
+        super(`Inference Snap model "${modelId}" is not on the US-origin allowlist ` +
+            `(${US_ORIGIN_INFERENCE_SNAP_IDS.join(', ')}). ` +
+            'Product local inference is US-origin snaps only. ' +
+            `Install: sudo snap install ${DEFAULT_US_ORIGIN_INFERENCE_SNAP}. ` +
+            `Operator escape (audited, never seed): ${NON_US_MODELS_ESCAPE_ENV}=1`);
+        this.name = 'NonUsOriginInferenceSnapError';
+        this.modelId = modelId;
+    }
+}
+/** Normalize a snap model id for allowlist comparison. */
+export function normalizeInferenceSnapModelId(modelId) {
+    return modelId.trim().toLowerCase();
+}
+/**
+ * True when the model id is on the US-origin product allowlist.
+ *
+ * Accepts exact snap ids (`nemotron-3-nano`) and engine-served variants that
+ * Canonical publishes under the same snap (e.g.
+ * `nemotron-3-nano-30b-a3b-q4-k-m`, `gemma4:e2b` style suffixes with `-` or `:`).
+ * Match longest snap id first so `nemotron-3-nano-omni` wins over `nemotron-3-nano`.
+ */
+export function isUsOriginInferenceSnap(modelId) {
+    const id = normalizeInferenceSnapModelId(modelId);
+    const snaps = [...US_ORIGIN_INFERENCE_SNAP_IDS].sort((a, b) => b.length - a.length);
+    for (const snap of snaps) {
+        if (id === snap)
+            return true;
+        if (id.startsWith(`${snap}-`) || id.startsWith(`${snap}:`))
+            return true;
+    }
+    return false;
+}
+/** True when the operator escape hatch is enabled. */
+export function isNonUsModelsEscapeEnabled(env = process.env) {
+    const value = env[NON_US_MODELS_ESCAPE_ENV];
+    return value === '1' || value === 'true';
+}
+/**
+ * Resolve and enforce the US-origin allowlist.
+ *
+ * @returns the model id to use (default when empty/undefined)
+ * @throws {NonUsOriginInferenceSnapError} when model is off-allowlist and escape is off
+ */
+export function assertUsOriginInferenceSnap(modelId, options) {
+    const resolved = modelId !== undefined && modelId.trim() !== ''
+        ? modelId.trim()
+        : DEFAULT_US_ORIGIN_INFERENCE_SNAP;
+    const allowNonUs = options?.allowNonUs === true || isNonUsModelsEscapeEnabled(options?.env ?? process.env);
+    if (!(allowNonUs || isUsOriginInferenceSnap(resolved))) {
+        throw new NonUsOriginInferenceSnapError(resolved);
+    }
+    return resolved;
+}

package/dist/observability/export.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @revealui/ai - Export Utilities
+ *
+ * Export agent events to various formats (JSON, CSV, NDJSON).
+ */
+import type { AgentEventLogger } from './logger.js';
+import type { AnyAgentEvent, EventFilter } from './types.js';
+/**
+ * Export events to JSON format
+ */
+export declare function exportToJSON(events: AnyAgentEvent[], options?: {
+    pretty?: boolean;
+    metadata?: Record<string, unknown>;
+}): string;
+/**
+ * Export events to CSV format
+ */
+export declare function exportToCSV(events: AnyAgentEvent[]): string;
+/**
+ * Export events to NDJSON format (newline-delimited JSON)
+ */
+export declare function exportToNDJSON(events: AnyAgentEvent[]): string;
+/**
+ * Export events to a file (Node.js)
+ */
+export declare function exportToFile(events: AnyAgentEvent[], filePath: string, format?: 'json' | 'csv' | 'ndjson'): Promise<void>;
+/**
+ * Create a downloadable file blob (Browser)
+ */
+export declare function createDownloadableBlob(events: AnyAgentEvent[], format?: 'json' | 'csv' | 'ndjson'): Blob;
+/**
+ * Trigger download in browser
+ */
+export declare function downloadEvents(events: AnyAgentEvent[], filename: string, format?: 'json' | 'csv' | 'ndjson'): void;
+/**
+ * Export helper class with logger integration
+ */
+export declare class EventExporter {
+    private logger;
+    constructor(logger: AgentEventLogger);
+    /**
+     * Export all events
+     */
+    exportAll(format?: 'json' | 'csv' | 'ndjson'): string;
+    /**
+     * Export filtered events
+     */
+    exportFiltered(filter: EventFilter, format?: 'json' | 'csv' | 'ndjson'): string;
+    /**
+     * Export to file (Node.js)
+     */
+    exportToFile(filePath: string, format?: 'json' | 'csv' | 'ndjson', filter?: EventFilter): Promise<void>;
+    /**
+     * Download in browser
+     */
+    download(filename: string, format?: 'json' | 'csv' | 'ndjson', filter?: EventFilter): void;
+    /**
+     * Export by time range
+     */
+    exportTimeRange(start: Date, end: Date, format?: 'json' | 'csv' | 'ndjson'): string;
+    /**
+     * Export by agent
+     */
+    exportByAgent(agentId: string, format?: 'json' | 'csv' | 'ndjson'): string;
+    /**
+     * Export by session
+     */
+    exportBySession(sessionId: string, format?: 'json' | 'csv' | 'ndjson'): string;
+    /**
+     * Export errors only
+     */
+    exportErrors(format?: 'json' | 'csv' | 'ndjson'): string;
+    /**
+     * Export LLM calls only
+     */
+    exportLLMCalls(format?: 'json' | 'csv' | 'ndjson'): string;
+}
+//# sourceMappingURL=export.d.ts.map

package/dist/observability/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/observability/export.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EAAE,EACvB,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GACA,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAyD3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GACzC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EAAE,EACvB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GACzC,IAAI,CAoBN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GACzC,IAAI,CAgBN;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,gBAAgB;IAIpC;;OAEG;IACH,SAAS,CAAC,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAa7D;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAgBvF;;OAEG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,EAC1C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;IAKhB;;OAEG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,EAC1C,MAAM,CAAC,EAAE,WAAW,GACnB,IAAI;IAKP;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAU3F;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAIlF;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAItF;;OAEG;IACH,YAAY,CAAC,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;IAIhE;;OAEG;IACH,cAAc,CAAC,MAAM,GAAE,MAAM,GAAG,KAAK,GAAG,QAAiB,GAAG,MAAM;CAGnE"}

package/dist/observability/export.js

@@ -0,0 +1,229 @@
+/**
+ * @revealui/ai - Export Utilities
+ *
+ * Export agent events to various formats (JSON, CSV, NDJSON).
+ */
+/**
+ * Export events to JSON format
+ */
+export function exportToJSON(events, options) {
+    const data = options?.metadata
+        ? {
+            metadata: {
+                exportedAt: new Date().toISOString(),
+                eventCount: events.length,
+                ...options.metadata,
+            },
+            events,
+        }
+        : events;
+    return options?.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+}
+/**
+ * Export events to CSV format
+ */
+export function exportToCSV(events) {
+    if (events.length === 0) {
+        return '';
+    }
+    // Define common columns
+    const columns = [
+        'timestamp',
+        'eventType',
+        'agentId',
+        'sessionId',
+        'taskId',
+        // Decision-specific
+        'reasoning',
+        'chosenTool',
+        'confidence',
+        // Tool call-specific
+        'toolName',
+        'success',
+        'durationMs',
+        'errorMessage',
+        // LLM call-specific
+        'provider',
+        'model',
+        'promptTokens',
+        'completionTokens',
+        'cost',
+        'cacheHit',
+        // Error-specific
+        'message',
+        'recoverable',
+        'errorCode',
+    ];
+    // Create CSV header
+    const header = columns.join(',');
+    // Create CSV rows
+    const rows = events.map((event) => {
+        const row = [];
+        for (const column of columns) {
+            const value = event[column];
+            if (value === undefined || value === null) {
+                row.push('');
+            }
+            else if (typeof value === 'string' && (value.includes(',') || value.includes('"'))) {
+                // Escape strings with commas or quotes
+                row.push(`"${value.replace(/"/g, '""')}"`);
+            }
+            else {
+                row.push(String(value));
+            }
+        }
+        return row.join(',');
+    });
+    return [header, ...rows].join('\n');
+}
+/**
+ * Export events to NDJSON format (newline-delimited JSON)
+ */
+export function exportToNDJSON(events) {
+    return events.map((event) => JSON.stringify(event)).join('\n');
+}
+/**
+ * Export events to a file (Node.js)
+ */
+export async function exportToFile(events, filePath, format = 'json') {
+    const fs = await import('node:fs/promises');
+    let content;
+    switch (format) {
+        case 'json':
+            content = exportToJSON(events, { pretty: true });
+            break;
+        case 'csv':
+            content = exportToCSV(events);
+            break;
+        case 'ndjson':
+            content = exportToNDJSON(events);
+            break;
+    }
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Create a downloadable file blob (Browser)
+ */
+export function createDownloadableBlob(events, format = 'json') {
+    let content;
+    let mimeType;
+    switch (format) {
+        case 'json':
+            content = exportToJSON(events, { pretty: true });
+            mimeType = 'application/json';
+            break;
+        case 'csv':
+            content = exportToCSV(events);
+            mimeType = 'text/csv';
+            break;
+        case 'ndjson':
+            content = exportToNDJSON(events);
+            mimeType = 'application/x-ndjson';
+            break;
+    }
+    return new Blob([content], { type: mimeType });
+}
+/**
+ * Trigger download in browser
+ */
+export function downloadEvents(events, filename, format = 'json') {
+    if (typeof window === 'undefined') {
+        throw new Error('downloadEvents can only be used in browser environments');
+    }
+    const blob = createDownloadableBlob(events, format);
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+/**
+ * Export helper class with logger integration
+ */
+export class EventExporter {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Export all events
+     */
+    exportAll(format = 'json') {
+        const events = this.logger.getEvents();
+        switch (format) {
+            case 'json':
+                return exportToJSON(events, { pretty: true });
+            case 'csv':
+                return exportToCSV(events);
+            case 'ndjson':
+                return exportToNDJSON(events);
+        }
+    }
+    /**
+     * Export filtered events
+     */
+    exportFiltered(filter, format = 'json') {
+        const events = this.logger.getEvents(filter);
+        switch (format) {
+            case 'json':
+                return exportToJSON(events, {
+                    pretty: true,
+                    metadata: { filter },
+                });
+            case 'csv':
+                return exportToCSV(events);
+            case 'ndjson':
+                return exportToNDJSON(events);
+        }
+    }
+    /**
+     * Export to file (Node.js)
+     */
+    async exportToFile(filePath, format = 'json', filter) {
+        const events = filter ? this.logger.getEvents(filter) : this.logger.getEvents();
+        await exportToFile(events, filePath, format);
+    }
+    /**
+     * Download in browser
+     */
+    download(filename, format = 'json', filter) {
+        const events = filter ? this.logger.getEvents(filter) : this.logger.getEvents();
+        downloadEvents(events, filename, format);
+    }
+    /**
+     * Export by time range
+     */
+    exportTimeRange(start, end, format = 'json') {
+        return this.exportFiltered({
+            startTime: start.getTime(),
+            endTime: end.getTime(),
+        }, format);
+    }
+    /**
+     * Export by agent
+     */
+    exportByAgent(agentId, format = 'json') {
+        return this.exportFiltered({ agentId }, format);
+    }
+    /**
+     * Export by session
+     */
+    exportBySession(sessionId, format = 'json') {
+        return this.exportFiltered({ sessionId }, format);
+    }
+    /**
+     * Export errors only
+     */
+    exportErrors(format = 'json') {
+        return this.exportFiltered({ eventType: 'error' }, format);
+    }
+    /**
+     * Export LLM calls only
+     */
+    exportLLMCalls(format = 'json') {
+        return this.exportFiltered({ eventType: 'llm_call' }, format);
+    }
+}