theorum 0.1.2 → 0.1.3

package/esm/src/presets/google.js

@@ -0,0 +1,96 @@
+/**
+ * Google / Gemini convenience preset.
+ *
+ * Kernel stays open (`string` pins). This pack owns Google vocabularies as
+ * real unions so host profiles stay typed when they opt into the preset.
+ *
+ * Call `registerGooglePreset()` at host startup for tools; use the exported
+ * types/constants when authoring image/speech-adjacent profile fields.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { registerTools } from '../kernel/registry/catalog.js';
+/** Google Interactions / Gemini grounding builtins. */
+const GOOGLE_BUILTIN_TOOLS = {
+    googleSearch: {
+        kind: 'builtin',
+        ui: true,
+        interactionsType: 'google_search',
+        openRouterPlugin: 'web',
+    },
+    googleMaps: {
+        kind: 'builtin',
+        ui: true,
+        interactionsType: 'google_maps',
+        conflictsWith: ['googleSearch', 'urlContext'],
+    },
+    urlContext: {
+        kind: 'builtin',
+        ui: true,
+        interactionsType: 'url_context',
+    },
+};
+/** Common Gemini image input MIME allowlist. */
+const GOOGLE_IMAGE_INPUT_MIMES = [
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/heic',
+    'image/heif',
+];
+/** Common voice/audio input MIME allowlist for Gemini multimodal. */
+const GOOGLE_VOICE_INPUT_MIMES = ['audio/webm', 'audio/wav', 'audio/mpeg', 'audio/mp4'];
+/** Common Gemini TTS voice names for `outputs.speech.voice`. */
+const GOOGLE_SPEECH_VOICES = [
+    'Zephyr',
+    'Puck',
+    'Charon',
+    'Kore',
+    'Fenrir',
+    'Leda',
+    'Orus',
+    'Aoede',
+    'Callirrhoe',
+    'Autonoe',
+    'Enceladus',
+    'Iapetus',
+    'Umbriel',
+    'Algieba',
+    'Despina',
+    'Erinome',
+    'Algenib',
+    'Rasalgethi',
+    'Laomedeia',
+    'Achernar',
+    'Alnilam',
+    'Schedar',
+    'Gacrux',
+    'Pulcherrima',
+    'Achird',
+    'Zubenelgenubi',
+    'Vindemiatrix',
+    'Sadachbia',
+    'Sadaltager',
+    'Sulafat',
+];
+/** Aspect ratios commonly accepted by Gemini image models. */
+const GOOGLE_IMAGE_ASPECT_RATIOS = [
+    '1:1',
+    '3:2',
+    '2:3',
+    '3:4',
+    '4:3',
+    '4:5',
+    '5:4',
+    '9:16',
+    '16:9',
+    '21:9',
+];
+/** Image sizes commonly accepted by Gemini Flash Lite image. */
+const GOOGLE_IMAGE_SIZES = ['1K'];
+/** Register Google provider builtins into the process-local tool catalog. */
+function registerGooglePreset() {
+    registerTools(GOOGLE_BUILTIN_TOOLS);
+}
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_SPEECH_VOICES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, };

package/esm/src/presets/mod.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Optional THEORUM presets.
+ *
+ * Presets register host-convenience catalogs (provider builtins, media
+ * vocabularies, later model packs) without baking product opinions into the kernel.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { GoogleImageAspectRatio, GoogleImageInputMime, GoogleImagePins, GoogleImageSize, GoogleVoiceInputMime, } from './google.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';

package/esm/src/presets/mod.js

@@ -0,0 +1,10 @@
+/**
+ * Optional THEORUM presets.
+ *
+ * Presets register host-convenience catalogs (provider builtins, media
+ * vocabularies, later model packs) without baking product opinions into the kernel.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';

package/esm/src/providers/create-provider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Host provider factory — the single public door for binding a profile to a transport.
+ *
+ * Routes from `profile.model.protocol` / `provider` (and whether the profile is
+ * a speech role). Adapters under this folder are internal implementation.
+ *
+ * @module
+ */
+import type { ModelProvider, Profile } from '../kernel/types.js';
+import type { GeminiTransport } from './keys.js';
+import type { OpenRouterConfig } from './openrouter-payload.js';
+/** Credentials supplied by the host when creating a provider. */
+export interface CreateProviderOptions {
+    /** Google Interactions (chat, image, and speech when protocol is geminiInteractions). */
+    gemini?: GeminiTransport;
+    /**
+     * OpenRouter-compatible credentials for `openAi` profiles.
+     * Used for chat completions or `/audio/speech` when the profile is a speech role.
+     * Optional `voice` is a fallback when `outputs.speech.voice` is omitted.
+     */
+    openRouter?: OpenRouterConfig & {
+        voice?: string;
+    };
+}
+/**
+ * Create a `ModelProvider` for a profile.
+ * One call: protocol/provider (and speech role) pick the transport.
+ */
+export declare function createProvider(profile: Profile, options?: CreateProviderOptions): ModelProvider;

package/esm/src/providers/create-provider.js

@@ -0,0 +1,38 @@
+/**
+ * Host provider factory — the single public door for binding a profile to a transport.
+ *
+ * Routes from `profile.model.protocol` / `provider` (and whether the profile is
+ * a speech role). Adapters under this folder are internal implementation.
+ *
+ * @module
+ */
+import { TheorumError } from '../guardrails/error.js';
+import { createOpenRouterProvider } from './openrouter.js';
+import { createInteractionsProvider } from './provider.js';
+import { createSpeechProvider } from './speech.js';
+function isSpeechRole(profile) {
+    return profile.outputs.speech !== undefined;
+}
+/**
+ * Create a `ModelProvider` for a profile.
+ * One call: protocol/provider (and speech role) pick the transport.
+ */
+export function createProvider(profile, options = {}) {
+    const { protocol, provider } = profile.model;
+    if (protocol === 'geminiInteractions' && provider === 'google') {
+        if (!options.gemini) {
+            throw new TheorumError('createProvider requires gemini transport for google Interactions');
+        }
+        return createInteractionsProvider(options.gemini);
+    }
+    if (protocol === 'openAi' && provider === 'openrouter') {
+        if (!options.openRouter) {
+            throw new TheorumError('createProvider requires openRouter config for openAi/openrouter');
+        }
+        if (isSpeechRole(profile)) {
+            return createSpeechProvider(options.openRouter);
+        }
+        return createOpenRouterProvider(options.openRouter);
+    }
+    throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
+}

package/esm/src/providers/gemini-tape.d.ts

@@ -1,3 +1,2 @@
-import { sha256 } from '../kernel/engine/hash.js';
 declare function tapeGemini(value: unknown, canary: string): Promise<unknown>;
-export { sha256, tapeGemini };
+export { tapeGemini };

package/esm/src/providers/gemini-tape.js

@@ -43,4 +43,4 @@ function redactCanaryInTree(value, canary) {
 async function tapeGemini(value, canary) {
     return redactCanaryInTree(await scrubGemini(value), canary);
 }
-export { sha256, tapeGemini };
+export { tapeGemini };

package/esm/src/providers/interactions.js

@@ -1,11 +1,6 @@
 import { TheorumError } from '../guardrails/error.js';
-import { modelEntry } from '../kernel/registry/catalog.js';
+import { getTool } from '../kernel/registry/catalog.js';
 import { getStructured } from '../kernel/registry/schemas.js';
-const BUILTIN_API = {
-    googleSearch: 'google_search',
-    googleMaps: 'google_maps',
-    urlContext: 'url_context',
-};
 function camelToSnake(key) {
     return key.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
@@ -58,12 +53,22 @@ function jsonResponseFormat(schema) {
     return [{ type: 'text', mimeType: 'application/json', schema }];
 }
 function attachResponseFormat(req, camel) {
+    if (req.speech) {
+        if (req.image) {
+            throw new TheorumError('cannot mix speech and image response formats');
+        }
+        if (req.structured) {
+            throw new TheorumError('cannot mix speech and structured response formats');
+        }
+        camel.responseFormat = { type: 'audio' };
+        return;
+    }
     if (req.image) {
         camel.responseFormat = {
             type: 'image',
             mimeType: req.image.mimeType,
             aspectRatio: req.image.aspectRatio,
-            imageSize: req.image.imageSize,
+            imageSize: req.image.size,
         };
         return;
     }
@@ -76,6 +81,14 @@ function attachResponseFormat(req, camel) {
     }
     camel.responseFormat = jsonResponseFormat(spec.jsonSchema);
 }
+function attachSpeechConfig(req, generationConfig) {
+    if (!req.speech) {
+        return;
+    }
+    if (req.speech.voice) {
+        generationConfig.speechConfig = [{ voice: req.speech.voice }];
+    }
+}
 function inputStepsFromRequest(req) {
     const inputSteps = [];
     for (const h of req.history ?? []) {
@@ -97,21 +110,33 @@ function applyOptionalRequestFields(req, camel) {
         camel.systemInstruction = req.system;
     }
     if (req.builtins.length > 0) {
-        camel.tools = req.builtins.map((id) => ({ type: BUILTIN_API[id] }));
+        camel.tools = req.builtins.map((id) => {
+            const type = getTool(id)?.interactionsType;
+            if (!type) {
+                throw new TheorumError(`Builtin '${id}' has no Interactions wire type`);
+            }
+            return { type };
+        });
     }
 }
 function baseInteractionsBody(req) {
-    const catalog = modelEntry(req.model);
+    const generationConfig = {
+        temperature: req.temperature,
+        maxOutputTokens: req.maxOutputTokens,
+    };
+    if (req.speech) {
+        // TTS models reject chat thinking knobs; voice lives under speech_config.
+        attachSpeechConfig(req, generationConfig);
+    }
+    else {
+        generationConfig.thinkingLevel = req.thinking;
+        generationConfig.thinkingSummaries = req.summaries;
+    }
     return {
-        model: catalog.apiId,
+        model: req.apiId,
         stream: true,
         input: inputStepsFromRequest(req),
-        generationConfig: {
-            temperature: req.temperature,
-            maxOutputTokens: req.maxOutputTokens,
-            thinkingLevel: req.thinking,
-            thinkingSummaries: req.summaries,
-        },
+        generationConfig,
     };
 }
 /** Interactions REST body for one complete() call (Google snake_case keys). */

package/esm/src/{guardrails → providers}/keys.d.ts

@@ -1,12 +1,19 @@
-import type { BuiltinToolId, GeminiBucket, GeminiFreeBucket, ModelId } from '../kernel/types.js';
+/**
+ * Gemini key vault selection, quota overflow, and fetch retries.
+ *
+ * Host applications supply vault credentials through `GeminiTransport`.
+ * THEORUM does not read environment variables for these keys.
+ *
+ * @module
+ */
+import type { GeminiBucket } from '../kernel/types.js';
 type GeminiVault = Record<GeminiBucket, string | undefined>;
 interface GeminiTransport {
     vault: GeminiVault;
     wait?: (ms: number) => Promise<void>;
     fetch?: typeof fetch;
 }
-declare function resolveGeminiBucket(free: GeminiFreeBucket, model: ModelId, builtins: BuiltinToolId[]): GeminiBucket;
 declare function withGeminiKey<T>(bucket: GeminiBucket, run: (apiKey: string) => Promise<T>, transport: GeminiTransport): Promise<T>;
 declare function fetchGemini(url: string, init: RequestInit, bucket: GeminiBucket, transport: GeminiTransport): Promise<Response>;
 export type { GeminiTransport, GeminiVault };
-export { fetchGemini, resolveGeminiBucket, withGeminiKey };
+export { fetchGemini, withGeminiKey };

package/esm/src/{guardrails → providers}/keys.js

@@ -1,5 +1,12 @@
-import { modelEntry } from '../kernel/registry/catalog.js';
-import { TheorumError, UPSTREAM_FAILED } from './error.js';
+/**
+ * Gemini key vault selection, quota overflow, and fetch retries.
+ *
+ * Host applications supply vault credentials through `GeminiTransport`.
+ * THEORUM does not read environment variables for these keys.
+ *
+ * @module
+ */
+import { TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
 const ATTEMPTS = 3;
 const LAST_ATTEMPT = ATTEMPTS - 1;
 const BACKOFF_FIRST_MS = 1000;
@@ -14,16 +21,6 @@ const HTTP_UNAVAILABLE = 503;
 const HTTP_GATEWAY_TIMEOUT = 504;
 const QUOTA_RE = /quota/i;
 const TRANSIENT_THROWN_RE = /name resolution|dns|econnreset|econnrefused|etimedout|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
-function resolveGeminiBucket(free, model, builtins) {
-    const entry = modelEntry(model);
-    if (entry.image) {
-        return 'paid';
-    }
-    if (builtins.some((id) => !entry.freeBuiltins.includes(id))) {
-        return 'paid';
-    }
-    return free;
-}
 function waitDefault(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
@@ -129,4 +126,4 @@ async function fetchGemini(url, init, bucket, transport) {
     }
     return last;
 }
-export { fetchGemini, resolveGeminiBucket, withGeminiKey };
+export { fetchGemini, withGeminiKey };

package/esm/src/providers/mod.d.ts

@@ -1,15 +1,12 @@
 /**
  * Provider adapters for THEORUM's `ModelProvider` contract.
  *
- * Use this entrypoint when a host app wants to bind THEORUM to Google
- * Interactions, OpenRouter-compatible chat completions, or OpenRouter TTS.
+ * Host apps should use `createProvider(profile, options)` — the single door.
  * Credentials are always supplied by the host application.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
-export type { OpenRouterConfig } from './openrouter.js';
-export { createOpenRouterProvider, resolveOpenRouterApiKey, resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter.js';
-export { createInteractionsProvider } from './provider.js';
-export type { OpenRouterTtsConfig } from './tts.js';
-export { createOpenRouterTtsProvider, streamOpenRouterTts, wrapPcmAsWav, } from './tts.js';
+export type { CreateProviderOptions } from './create-provider.js';
+export { createProvider } from './create-provider.js';
+export type { GeminiTransport, GeminiVault } from './keys.js';

package/esm/src/providers/mod.js

@@ -1,13 +1,10 @@
 /**
  * Provider adapters for THEORUM's `ModelProvider` contract.
  *
- * Use this entrypoint when a host app wants to bind THEORUM to Google
- * Interactions, OpenRouter-compatible chat completions, or OpenRouter TTS.
+ * Host apps should use `createProvider(profile, options)` — the single door.
  * Credentials are always supplied by the host application.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { createOpenRouterProvider, resolveOpenRouterApiKey, resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter.js';
-export { createInteractionsProvider } from './provider.js';
-export { createOpenRouterTtsProvider, streamOpenRouterTts, wrapPcmAsWav, } from './tts.js';
+export { createProvider } from './create-provider.js';

package/esm/src/providers/openrouter-mod.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenRouter provider adapter and payload helpers.
+ *
+ * Prefer `createProvider(profile, { openRouter })` from `theorum` / `theorum/providers`
+ * for turn execution. This entrypoint is for hosts that build OpenRouter payloads
+ * outside the runner.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { createOpenRouterProvider } from './openrouter.js';
+export type { OpenRouterConfig } from './openrouter-payload.js';
+export { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';

package/esm/src/providers/openrouter-mod.js

@@ -0,0 +1,12 @@
+/**
+ * OpenRouter provider adapter and payload helpers.
+ *
+ * Prefer `createProvider(profile, { openRouter })` from `theorum` / `theorum/providers`
+ * for turn execution. This entrypoint is for hosts that build OpenRouter payloads
+ * outside the runner.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { createOpenRouterProvider } from './openrouter.js';
+export { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';

package/esm/src/providers/openrouter-payload.d.ts

@@ -16,9 +16,17 @@ interface OpenRouterConfig {
     fetch?: typeof fetch;
     modelMap?: Record<string, string>;
 }
-/** Resolve a THEORUM model id to an OpenRouter model string. */
-declare function resolveOpenRouterModel(modelId: ModelId | string, customMap?: Record<string, string>): string;
+/** Host-owned wire ids used when resolving an OpenRouter model string. */
+interface OpenRouterWireIds {
+    apiId?: string;
+    openRouterId?: string;
+}
+/**
+ * Resolve a THEORUM model id to an OpenRouter model string.
+ * Prefer `openRouterId` / `apiId` from the profile model spec on the request.
+ */
+declare function resolveOpenRouterModel(modelId: ModelId | string, customMap?: Record<string, string>, wire?: OpenRouterWireIds): string;
 /** Convert a provider-neutral request into an OpenRouter chat completion payload. */
 declare function toOpenRouterPayload(req: ProviderCompleteRequest, config: OpenRouterConfig): Record<string, unknown>;
-export type { OpenRouterConfig };
+export type { OpenRouterConfig, OpenRouterWireIds };
 export { resolveOpenRouterModel, toOpenRouterPayload };

package/esm/src/providers/openrouter-payload.js

@@ -6,36 +6,33 @@
  *
  * @module
  */
-import { CATALOG } from '../kernel/registry/catalog.js';
+import { getTool } from '../kernel/registry/catalog.js';
 import { getStructured } from '../kernel/registry/schemas.js';
-/** Resolve a THEORUM model id to an OpenRouter model string. */
-function resolveOpenRouterModel(modelId, customMap) {
+/**
+ * Resolve a THEORUM model id to an OpenRouter model string.
+ * Prefer `openRouterId` / `apiId` from the profile model spec on the request.
+ */
+function resolveOpenRouterModel(modelId, customMap, wire) {
     if (customMap?.[modelId]) {
         return customMap[modelId];
     }
-    const catalogEntry = CATALOG.models[modelId];
-    if (catalogEntry?.openRouterId) {
-        return catalogEntry.openRouterId;
+    if (wire?.openRouterId) {
+        return wire.openRouterId;
     }
-    if (catalogEntry?.apiId.includes('/')) {
-        return catalogEntry.apiId;
+    if (wire?.apiId?.includes('/')) {
+        return wire.apiId;
     }
-    if (catalogEntry?.apiId) {
-        return `google/${catalogEntry.apiId}`;
+    if (wire?.apiId) {
+        return `google/${wire.apiId}`;
+    }
+    if (String(modelId).includes('/')) {
+        return String(modelId);
     }
     return String(modelId);
 }
+/** Map THEORUM thinking level to OpenRouter/OpenAI `reasoning.effort`. */
 function mapThinkingEffort(thinking) {
-    if (thinking === 'low') {
-        return 'low';
-    }
-    if (thinking === 'medium') {
-        return 'medium';
-    }
-    if (thinking === 'high') {
-        return 'high';
-    }
-    return null;
+    return thinking;
 }
 function wireAudioPart(part) {
     let format = 'mp3';
@@ -148,7 +145,10 @@ function resolveResponseFormat(structured) {
 }
 /** Convert a provider-neutral request into an OpenRouter chat completion payload. */
 function toOpenRouterPayload(req, config) {
-    const model = resolveOpenRouterModel(req.model, config.modelMap);
+    const model = resolveOpenRouterModel(req.model, config.modelMap, {
+        apiId: req.apiId,
+        openRouterId: req.openRouterId,
+    });
     const messages = buildMessages(req);
     const payload = {
         model,
@@ -158,9 +158,7 @@ function toOpenRouterPayload(req, config) {
         max_tokens: req.maxOutputTokens,
     };
     const effort = mapThinkingEffort(req.thinking);
-    if (effort) {
-        payload.reasoning = { effort };
-    }
+    payload.reasoning = { effort };
     const responseFormat = resolveResponseFormat(req.structured);
     if (responseFormat) {
         payload.response_format = responseFormat;
@@ -169,8 +167,12 @@ function toOpenRouterPayload(req, config) {
     if (tools.length > 0) {
         payload.tools = tools;
     }
-    if (req.builtins.includes('googleSearch')) {
-        payload.plugins = [{ id: 'web' }];
+    const plugins = req.builtins
+        .map((id) => getTool(id)?.openRouterPlugin)
+        .filter((id) => Boolean(id))
+        .map((id) => ({ id }));
+    if (plugins.length > 0) {
+        payload.plugins = plugins;
     }
     return payload;
 }

package/esm/src/providers/openrouter.d.ts

@@ -1,17 +1,15 @@
 /**
- * OpenRouter-compatible streaming provider adapter.
+ * OpenRouter provider adapter powered by Vercel AI SDK Core.
  *
- * This module maps THEORUM requests to OpenAI-style chat completions, including
- * reasoning deltas, tool calls, citations, structured output, and token usage.
+ * THEORUM keeps the public `ModelProvider` and `TurnEvent` contract; AI SDK
+ * owns the OpenRouter call, stream parsing, provider compatibility, and tool
+ * call normalization.
  *
  * @module
  */
-import "../../_dnt.polyfills.js";
 import type { ModelProvider } from '../kernel/types.js';
 import { type OpenRouterConfig, resolveOpenRouterModel, toOpenRouterPayload } from './openrouter-payload.js';
-/** Resolve an OpenRouter API key supplied explicitly by the host application. */
-export declare function resolveOpenRouterApiKey(explicitKey?: string): string | undefined;
-/** Create a `ModelProvider` backed by OpenRouter-compatible chat completions. */
+/** Create a `ModelProvider` backed by OpenRouter through AI SDK Core. */
 declare function createOpenRouterProvider(config?: OpenRouterConfig): ModelProvider;
 export type { OpenRouterConfig };
 export { createOpenRouterProvider, resolveOpenRouterModel, toOpenRouterPayload };