theorum 0.1.15 → 1.1.3

package/esm/src/presets/google/speech-voices.js

@@ -0,0 +1,41 @@
+/**
+ * Google Gemini TTS voice names for `speech.voice`.
+ *
+ * Standalone preset vocabulary — no kernel registry imports so docs UIs can
+ * import this file without pulling provider wiring.
+ *
+ * @module
+ */
+/** Common Gemini TTS voice names. */
+export 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',
+];

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

@@ -1,50 +1,62 @@
 /**
  * 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 type { ProfileImageSpec, ProfileSpeechSpec, ToolCatalogEntry } from '../kernel/types.js';
-/** Google Interactions / Gemini grounding builtins. */
-declare const GOOGLE_BUILTIN_TOOLS: Record<string, ToolCatalogEntry>;
+import type { ProfileImageSpec, ProfileLiveSpec, ProfileSpeechSpec } from '../kernel/types.js';
+import { GOOGLE_SPEECH_VOICES, type GoogleSpeechVoice } from './google/speech-voices.js';
 /** Common Gemini image input MIME allowlist. */
 declare const GOOGLE_IMAGE_INPUT_MIMES: readonly ["image/png", "image/jpeg", "image/webp", "image/heic", "image/heif"];
 /** Common voice/audio input MIME allowlist for Gemini multimodal. */
 declare const GOOGLE_VOICE_INPUT_MIMES: readonly ["audio/webm", "audio/wav", "audio/mpeg", "audio/mp4"];
-/** Common Gemini TTS voice names for `outputs.speech.voice`. */
-declare const GOOGLE_SPEECH_VOICES: readonly ["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"];
-type GoogleSpeechVoice = (typeof GOOGLE_SPEECH_VOICES)[number];
-/**
- * `outputs.speech` pins narrowed to Google TTS vocabulary.
- * Assignable to kernel `ProfileSpeechSpec`.
- */
 type GoogleSpeechPins = Omit<ProfileSpeechSpec, 'voice'> & {
     voice?: GoogleSpeechVoice;
 };
-/** Aspect ratios commonly accepted by Gemini image models. */
+type GoogleLivePins = Omit<ProfileLiveSpec, 'voice'> & {
+    voice?: GoogleSpeechVoice;
+};
 declare const GOOGLE_IMAGE_ASPECT_RATIOS: readonly ["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. */
 declare const GOOGLE_IMAGE_SIZES: readonly ["1K"];
 type GoogleImageInputMime = (typeof GOOGLE_IMAGE_INPUT_MIMES)[number];
 type GoogleVoiceInputMime = (typeof GOOGLE_VOICE_INPUT_MIMES)[number];
 type GoogleImageAspectRatio = (typeof GOOGLE_IMAGE_ASPECT_RATIOS)[number];
 type GoogleImageSize = (typeof GOOGLE_IMAGE_SIZES)[number];
-/**
- * `outputs.image` pins narrowed to Google image vocabulary.
- * Assignable to kernel `ProfileImageSpec`.
- */
 type GoogleImagePins = Omit<ProfileImageSpec, 'aspectRatio' | 'size' | 'mimeType'> & {
     aspectRatio?: GoogleImageAspectRatio;
     size?: GoogleImageSize;
     mimeType?: GoogleImageInputMime | 'image/jpeg';
 };
-/** Register Google provider builtins into the process-local tool catalog. */
+declare const GOOGLE_BUILTIN_TOOLS: ({
+    type: "builtin";
+    name: string;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+    forcePaidKey: boolean;
+    wire: {
+        interactions: string;
+        openRouter: string;
+    };
+} | {
+    type: "builtin";
+    name: string;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+    wire: {
+        interactions: string;
+        openRouter?: undefined;
+    };
+    forcePaidKey?: undefined;
+})[];
+/** Register Google provider builtins into the process-local tool registry. */
 declare function registerGooglePreset(): void;
-export type { GoogleImageAspectRatio, GoogleImageInputMime, GoogleImagePins, GoogleImageSize, GoogleSpeechPins, GoogleSpeechVoice, GoogleVoiceInputMime, };
+export type { GoogleImageAspectRatio, GoogleImageInputMime, GoogleImagePins, GoogleImageSize, GoogleLivePins, GoogleSpeechPins, GoogleSpeechVoice, GoogleVoiceInputMime, };
 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/google.js

@@ -1,36 +1,11 @@
 /**
  * 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',
-    },
-};
+import { registerTools } from '../kernel/tools/mod.js';
+import { GOOGLE_SPEECH_VOICES } from './google/speech-voices.js';
 /** Common Gemini image input MIME allowlist. */
 const GOOGLE_IMAGE_INPUT_MIMES = [
     'image/png',
@@ -41,40 +16,6 @@ const GOOGLE_IMAGE_INPUT_MIMES = [
 ];
 /** 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',
@@ -87,9 +28,55 @@ const GOOGLE_IMAGE_ASPECT_RATIOS = [
     '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. */
+const GOOGLE_BUILTIN_TOOLS = [
+    {
+        type: 'builtin',
+        name: 'googleSearch',
+        description: 'Google Search grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        forcePaidKey: true,
+        wire: { interactions: 'google_search', openRouter: 'web' },
+    },
+    {
+        type: 'builtin',
+        name: 'googleMaps',
+        description: 'Google Maps grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'google_maps' },
+    },
+    {
+        type: 'builtin',
+        name: 'urlContext',
+        description: 'Fetch URL context',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'url_context' },
+    },
+    {
+        type: 'builtin',
+        name: 'codeExecution',
+        description: 'Google code execution',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'code_execution' },
+    },
+];
+/** Register Google provider builtins into the process-local tool registry. */
 function registerGooglePreset() {
     registerTools(GOOGLE_BUILTIN_TOOLS);
 }

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

@@ -7,5 +7,5 @@
  * @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';
+export type { GoogleImageAspectRatio, GoogleImageInputMime, GoogleImagePins, GoogleImageSize, GoogleSpeechVoice, GoogleVoiceInputMime, } from './google.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_SPEECH_VOICES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';

package/esm/src/presets/mod.js

@@ -7,4 +7,4 @@
  * @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';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_SPEECH_VOICES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';

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

@@ -1,36 +1,39 @@
 /**
  * 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.
+ * Routes from the selected model binding's `protocol` / `provider` (and whether the
+ * profile is a speech or image role). Adapters under this folder are internal implementation.
  *
- * The OpenRouter / Vercel AI SDK stack is loaded only when an `openAi` +
- * `openrouter` chat provider actually runs `complete` — not when this module
- * is imported, and not for Google or local paths.
+ * Every adapter graph is loaded only when that transport's first `complete` runs —
+ * not when this module is imported.
  *
  * @module
  */
-import type { ModelProvider, Profile } from '../kernel/types.js';
-import type { GeminiTransport } from './keys.js';
-import { type LocalProviderConfig } from './local.js';
-import type { OpenRouterConfig } from './openrouter-payload.js';
+import type { ModelId, ModelProvider, Profile } from '../kernel/types.js';
+import type { GeminiTransport } from './google/keys.js';
+import type { LocalProviderConfig, OpenAiGatewayConfig } from './types.js';
 /** Credentials supplied by the host when creating a provider. */
 export interface CreateProviderOptions {
-    /** Google Interactions (chat, image, and speech when protocol is geminiInteractions). */
+    /** Google Interactions (text, 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.
+     * OpenAI-gateway credentials for `openAi` profiles (OpenRouter or compatible).
+     * Used for chat completions, `/images`, or `/audio/speech` depending on output role.
+     * Optional `voice` is a fallback when `speech.voice` is omitted.
      */
-    openRouter?: OpenRouterConfig & {
+    openAiGateway?: OpenAiGatewayConfig & {
         voice?: string;
     };
     /** Local OpenAI-compatible server (Ollama, llama.cpp, vLLM, LM Studio). */
     local?: LocalProviderConfig;
 }
+export declare function isSpeechRole(profile: Profile): boolean;
+export declare function isImageRole(profile: Profile): boolean;
 /**
- * Create a `ModelProvider` for a profile.
- * One call: protocol/provider (and speech role) pick the transport.
+ * Create a `ModelProvider` for a turn-based profile (text / image / speech).
+ * Live profiles use `runSession` — `createProvider` rejects geminiLive.
+ *
+ * When a profile declares multiple models, pass `modelId` to pick the binding used
+ * for adapter selection (defaults to `defaultModel` or the sole model key).
  */
-export declare function createProvider(profile: Profile, options?: CreateProviderOptions): ModelProvider;
+export declare function createProvider(profile: Profile, options?: CreateProviderOptions, modelId?: ModelId): ModelProvider;

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

@@ -1,60 +1,106 @@
 /**
  * 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.
+ * Routes from the selected model binding's `protocol` / `provider` (and whether the
+ * profile is a speech or image role). Adapters under this folder are internal implementation.
  *
- * The OpenRouter / Vercel AI SDK stack is loaded only when an `openAi` +
- * `openrouter` chat provider actually runs `complete` — not when this module
- * is imported, and not for Google or local paths.
+ * Every adapter graph is loaded only when that transport's first `complete` runs —
+ * not when this module is imported.
  *
  * @module
  */
 import { TheorumError } from '../guardrails/error.js';
-import { exposeForTests } from './expose-for-tests.js';
-import { createLocalProvider } from './local.js';
-import { createInteractionsProvider } from './provider.js';
-import { createSpeechProvider } from './speech.js';
-function isSpeechRole(profile) {
-    return profile.outputs.speech !== undefined;
+import { requireModelProfile } from '../kernel/registry/resolve.js';
+import { soleModelId } from '../kernel/registry/sole-model.js';
+import { isValidPair } from '../kernel/schema.js';
+import { markModuleLoad } from './probe.js';
+export function isSpeechRole(profile) {
+    return profile.type === 'speech';
+}
+export function isImageRole(profile) {
+    return profile.type === 'image';
+}
+function bindingForProvider(input, modelId) {
+    const profile = requireModelProfile(input, 'createProvider');
+    const id = modelId ?? profile.defaultModel ?? soleModelId(profile.models);
+    if (!id) {
+        throw new TheorumError(`createProvider: profile '${profile.id}' must set defaultModel when multiple models are declared`);
+    }
+    const binding = profile.models[id];
+    if (!binding) {
+        throw new TheorumError(`createProvider: profile '${profile.id}' has no model '${id}'`);
+    }
+    return binding;
 }
 /**
- * Defer loading `@openrouter/ai-sdk-provider` / `ai` until the first `complete`.
- * Keeps Google and local hosts free of the Vercel SDK graph.
+ * Lazy-load an adapter on first `complete`. When `THEORUM_IMPORT_PROBE=1`,
+ * emits `LOADED:<label>` exactly once at load time (import-isolation tests).
  */
-function lazyOpenRouterChat(config) {
+function lazyAdapter(label, load) {
     let pending;
     return {
         async *complete(req) {
-            pending ??= import('./openrouter.js').then((m) => m.createOpenRouterProvider(config));
+            pending ??= (async () => {
+                markModuleLoad(label);
+                return await load();
+            })();
             yield* (await pending).complete(req);
         },
     };
 }
+function lazyOpenRouterChat(config) {
+    return lazyAdapter('openrouter-chat', () => import('./openrouter/chat.js').then((m) => m.createOpenRouterProvider(config)));
+}
+function lazyGoogleInteractions(config) {
+    return lazyAdapter('google-interactions-adapter', () => import('./google/interactions/mod.js').then((m) => m.createInteractionsProvider(config)));
+}
+function lazySpeech(config) {
+    return lazyAdapter('openrouter-speech', () => import('./openrouter/speech.js').then((m) => m.createSpeechProvider(config)));
+}
+function lazyImage(config) {
+    return lazyAdapter('openrouter-image', () => import('./openrouter/image.js').then((m) => m.createImageProvider(config)));
+}
+function lazyLocal(config) {
+    return lazyAdapter('local-adapter', () => import('./local/local.js').then((m) => m.createLocalProvider(config)));
+}
 /**
- * Create a `ModelProvider` for a profile.
- * One call: protocol/provider (and speech role) pick the transport.
+ * Create a `ModelProvider` for a turn-based profile (text / image / speech).
+ * Live profiles use `runSession` — `createProvider` rejects geminiLive.
+ *
+ * When a profile declares multiple models, pass `modelId` to pick the binding used
+ * for adapter selection (defaults to `defaultModel` or the sole model key).
  */
-export function createProvider(profile, options = {}) {
-    const { protocol, provider } = profile.model;
+export function createProvider(profile, options = {}, modelId) {
+    const { protocol, provider } = bindingForProvider(profile, modelId);
+    if (!isValidPair(protocol, provider)) {
+        throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
+    }
     if (protocol === 'geminiInteractions' && provider === 'google') {
         if (!options.gemini) {
             throw new TheorumError('createProvider requires gemini transport for google Interactions');
         }
-        return createInteractionsProvider(options.gemini);
+        return lazyGoogleInteractions(options.gemini);
+    }
+    if (protocol === 'geminiLive' && provider === 'google') {
+        throw new TheorumError("createProvider does not support type 'live' / geminiLive — use runSession(req, { gemini })");
     }
     if (protocol === 'openAi' && provider === 'openrouter') {
-        if (!options.openRouter) {
-            throw new TheorumError('createProvider requires openRouter config for openAi/openrouter');
+        if (!options.openAiGateway) {
+            throw new TheorumError('createProvider requires openAiGateway config for openAi/openrouter');
         }
         if (isSpeechRole(profile)) {
-            return createSpeechProvider(options.openRouter);
+            return lazySpeech(options.openAiGateway);
         }
-        return lazyOpenRouterChat(options.openRouter);
+        if (isImageRole(profile)) {
+            return lazyImage(options.openAiGateway);
+        }
+        return lazyOpenRouterChat(options.openAiGateway);
     }
     if (protocol === 'openAi' && provider === 'local') {
-        return createLocalProvider(options.local);
+        if (isImageRole(profile)) {
+            throw new TheorumError('createProvider: type image requires openrouter provider for openAi protocol');
+        }
+        return lazyLocal(options.local);
     }
     throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
 }
-exposeForTests('create-provider', { isSpeechRole, createProvider, lazyOpenRouterChat });

package/esm/src/providers/google/interactions/framing.d.ts

@@ -0,0 +1,23 @@
+import type { InteractionPart, ProviderCompleteRequest, TurnHistoryMessage } from '../../../kernel/types.js';
+export declare function camelToSnake(key: string): string;
+export declare function toGoogleValue(value: unknown): unknown;
+export declare function wirePart(part: InteractionPart): Record<string, string>;
+export declare function userInputStep(parts: InteractionPart[]): Record<string, unknown>;
+/**
+ * Map one host history message to Interactions input step(s).
+ *
+ * OpenAI-shaped assistant `tool_calls` (often with no `content`) become
+ * `function_call` steps — never empty `model_output` text.
+ */
+export declare function historySteps(msg: TurnHistoryMessage): Record<string, unknown>[];
+/** Single-step helper for simple messages (first of {@link historySteps}). */
+export declare function historyStep(msg: TurnHistoryMessage): Record<string, unknown>;
+export declare function systemHoldsUserInput(system: string, parts: InteractionPart[]): boolean;
+export declare function jsonResponseFormat(schema: Record<string, unknown>): unknown[];
+export declare function attachResponseFormat(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+export declare function attachSpeechConfig(req: ProviderCompleteRequest, generationConfig: Record<string, unknown>): void;
+export declare function inputStepsFromRequest(req: ProviderCompleteRequest): Record<string, unknown>[];
+export declare function applyOptionalRequestFields(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+export declare function baseInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
+/** Compatibility wrapper for callers that need the complete wire body. */
+export declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;