theorum 0.1.2

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

@@ -0,0 +1,46 @@
+import { OMIT_CANARY } from '../kernel/engine/boundary.js';
+import { sha256 } from '../kernel/engine/hash.js';
+import { mapStrings } from '../kernel/engine/tree.js';
+function isImageBlob(rec) {
+    if (rec.type === 'image' || rec.type === 'media') {
+        return true;
+    }
+    if (typeof rec.mimeType === 'string' || typeof rec.mime_type === 'string') {
+        return true;
+    }
+    return false;
+}
+async function scrubEntry(rec, key, nested) {
+    if (key === 'data' && typeof nested === 'string' && isImageBlob(rec)) {
+        return [key, await sha256(nested)];
+    }
+    return [key, await scrubGemini(nested)];
+}
+function scrubRecord(rec) {
+    return Promise.all(Object.entries(rec).map(([key, nested]) => scrubEntry(rec, key, nested))).then((pairs) => {
+        const out = Object.fromEntries(pairs);
+        if (typeof rec.data === 'string' && isImageBlob(rec)) {
+            out.dataKind = 'sha256';
+        }
+        return out;
+    });
+}
+function scrubGemini(value) {
+    if (Array.isArray(value)) {
+        return Promise.all(value.map((item) => scrubGemini(item)));
+    }
+    if (value && typeof value === 'object') {
+        return scrubRecord(value);
+    }
+    return Promise.resolve(value);
+}
+function redactCanaryInTree(value, canary) {
+    if (!canary) {
+        return value;
+    }
+    return mapStrings(value, (text) => text.replaceAll(canary, OMIT_CANARY));
+}
+async function tapeGemini(value, canary) {
+    return redactCanaryInTree(await scrubGemini(value), canary);
+}
+export { sha256, tapeGemini };

package/esm/src/providers/google-tap.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderCompleteRequest } from '../kernel/types.js';
+declare function tapFetch(tap: ProviderCompleteRequest['tapGemini'], send?: typeof fetch): typeof fetch;
+export { tapFetch };

package/esm/src/providers/google-tap.js

@@ -0,0 +1,48 @@
+const SECRET_HEADER = /key|auth|cookie|secret|token/i;
+function tapeHeaderValue(key, value) {
+    if (SECRET_HEADER.test(key)) {
+        return '[redacted]';
+    }
+    return value;
+}
+function tapeHeaders(headers) {
+    const out = {};
+    for (const [key, value] of new Headers(headers).entries()) {
+        out[key] = tapeHeaderValue(key, value);
+    }
+    return out;
+}
+function throwRow(err) {
+    if (err instanceof Error) {
+        return { eventType: 'http_throw', name: err.name, message: err.message };
+    }
+    return { eventType: 'http_throw', name: 'Error', message: String(err) };
+}
+function tapFetch(tap, send = fetch) {
+    return async (url, init) => {
+        const method = init?.method ?? 'GET';
+        tap?.({
+            eventType: 'http_request',
+            method,
+            url: String(url),
+            headers: tapeHeaders(init?.headers),
+        });
+        try {
+            const res = await send(url, init);
+            tap?.({
+                eventType: 'http_response',
+                status: res.status,
+                headers: tapeHeaders(res.headers),
+            });
+            if (!res.ok) {
+                tap?.({ eventType: 'http_error_body', body: await res.clone().text() });
+            }
+            return res;
+        }
+        catch (err) {
+            tap?.(throwRow(err));
+            throw err;
+        }
+    };
+}
+export { tapFetch };

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

@@ -0,0 +1,5 @@
+import type { ProviderCompleteRequest } from '../kernel/types.js';
+declare function camelToSnake(key: string): string;
+/** Interactions REST body for one complete() call (Google snake_case keys). */
+declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
+export { camelToSnake, toInteractionsBody };

package/esm/src/providers/interactions.js

@@ -0,0 +1,127 @@
+import { TheorumError } from '../guardrails/error.js';
+import { modelEntry } 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()}`);
+}
+function toGoogleValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(toGoogleValue);
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            // JSON Schema property names must stay as authored (e.g. correctAnswer in
+            // both properties and required). Snake-casing breaks Gemini validation.
+            if (key === 'schema') {
+                out[camelToSnake(key)] = nested;
+                continue;
+            }
+            out[camelToSnake(key)] = toGoogleValue(nested);
+        }
+        return out;
+    }
+    return value;
+}
+function wirePart(part) {
+    if (part.type === 'text') {
+        return { type: 'text', text: part.text };
+    }
+    return { type: part.type, mimeType: part.mimeType, data: part.data };
+}
+const USER_INPUT = 'user_input';
+function userInputStep(parts) {
+    return { type: USER_INPUT, content: parts.map(wirePart) };
+}
+function historyStep(msg) {
+    const isAssistant = msg.role === 'assistant';
+    const type = isAssistant ? 'model_turn' : 'user_input';
+    if (msg.parts && msg.parts.length > 0) {
+        return { type, content: msg.parts.map(wirePart) };
+    }
+    return { type, content: [{ type: 'text', text: msg.content ?? '' }] };
+}
+function systemHoldsUserInput(system, parts) {
+    for (const part of parts) {
+        if (part.type === 'text' && part.text && system.includes(part.text)) {
+            return true;
+        }
+    }
+    return false;
+}
+function jsonResponseFormat(schema) {
+    return [{ type: 'text', mimeType: 'application/json', schema }];
+}
+function attachResponseFormat(req, camel) {
+    if (req.image) {
+        camel.responseFormat = {
+            type: 'image',
+            mimeType: req.image.mimeType,
+            aspectRatio: req.image.aspectRatio,
+            imageSize: req.image.imageSize,
+        };
+        return;
+    }
+    if (!req.structured) {
+        return;
+    }
+    const spec = getStructured(req.structured);
+    if (spec.enforced !== 'responseFormat' || !spec.jsonSchema) {
+        return;
+    }
+    camel.responseFormat = jsonResponseFormat(spec.jsonSchema);
+}
+function inputStepsFromRequest(req) {
+    const inputSteps = [];
+    for (const h of req.history ?? []) {
+        inputSteps.push(historyStep(h));
+    }
+    if (req.input.length > 0 || inputSteps.length === 0) {
+        inputSteps.push(userInputStep(req.input));
+    }
+    return inputSteps;
+}
+function applyOptionalRequestFields(req, camel) {
+    if (req.store !== undefined) {
+        camel.store = req.store;
+    }
+    if (req.previousInteractionId) {
+        camel.previousInteractionId = req.previousInteractionId;
+    }
+    if (req.system) {
+        camel.systemInstruction = req.system;
+    }
+    if (req.builtins.length > 0) {
+        camel.tools = req.builtins.map((id) => ({ type: BUILTIN_API[id] }));
+    }
+}
+function baseInteractionsBody(req) {
+    const catalog = modelEntry(req.model);
+    return {
+        model: catalog.apiId,
+        stream: true,
+        input: inputStepsFromRequest(req),
+        generationConfig: {
+            temperature: req.temperature,
+            maxOutputTokens: req.maxOutputTokens,
+            thinkingLevel: req.thinking,
+            thinkingSummaries: req.summaries,
+        },
+    };
+}
+/** Interactions REST body for one complete() call (Google snake_case keys). */
+function toInteractionsBody(req) {
+    if (systemHoldsUserInput(req.system, req.input)) {
+        throw new TheorumError('user input cannot be placed in the system block');
+    }
+    const camel = baseInteractionsBody(req);
+    applyOptionalRequestFields(req, camel);
+    attachResponseFormat(req, camel);
+    return toGoogleValue(camel);
+}
+export { camelToSnake, toInteractionsBody };

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

@@ -0,0 +1,5 @@
+import type { BuiltinToolId, ImageResponseFormat, InteractionPart, ModelId, Profile, TurnRequest } from '../kernel/types.js';
+declare function resolveImageFormat(profile: Profile, model: ModelId, slots?: Record<string, string>): ImageResponseFormat | null;
+declare function resolveInputParts(profile: Profile, model: ModelId, req: TurnRequest): InteractionPart[];
+declare function assertImageGrounding(model: ModelId, builtins: BuiltinToolId[]): void;
+export { assertImageGrounding, resolveImageFormat, resolveInputParts };

package/esm/src/providers/media.js

@@ -0,0 +1,125 @@
+import { TheorumError } from '../guardrails/error.js';
+import { wrapUserData } from '../kernel/engine/boundary.js';
+import { synthesizeRepairPrompt } from '../kernel/engine/repair.js';
+import { geminiKindForMime, mimeAllowed, mimeEssence, modelEntry, } from '../kernel/registry/catalog.js';
+import { assertAttachmentLimits, requireMediaLimits } from './attachments.js';
+function listedValue(allowed, requested) {
+    if (!requested) {
+        return allowed[0];
+    }
+    for (const item of allowed) {
+        if (item === requested) {
+            return item;
+        }
+    }
+    return undefined;
+}
+function requireImageSpec(profile, model) {
+    const spec = modelEntry(model).image;
+    if (!spec) {
+        throw new TheorumError(`Profile ${profile.id} requests media but ${model} is not an image model`);
+    }
+    if (profile.outputs.structured !== null) {
+        throw new TheorumError(`Profile ${profile.id} cannot mix structured JSON with native image output`);
+    }
+    return spec;
+}
+function resolveImageFormat(profile, model, slots) {
+    if (!profile.outputs.media) {
+        return null;
+    }
+    const spec = requireImageSpec(profile, model);
+    const aspectRatio = listedValue(spec.aspectRatios, slots?.aspectRatio);
+    const imageSize = listedValue(spec.sizes, slots?.imageSize);
+    if (!(aspectRatio && imageSize)) {
+        throw new TheorumError(`Unknown image aspect or size for ${profile.id}`);
+    }
+    return {
+        type: 'image',
+        mimeType: spec.outputMime,
+        aspectRatio,
+        imageSize,
+    };
+}
+function assertGeminiMime(mime) {
+    const kind = geminiKindForMime(mime);
+    if (!kind) {
+        throw new TheorumError(`MIME '${mime}' is not a Gemini input type`);
+    }
+    return kind;
+}
+function mediaParts(profile, model, blobs, channel) {
+    const accept = channel === 'voice' ? profile.inputs.voice?.accept : profile.inputs.attachments?.accept;
+    if (!accept) {
+        throw new TheorumError(`Profile ${profile.id} does not accept ${channel}`);
+    }
+    const spec = modelEntry(model).image;
+    const imageCount = blobs.filter((blob) => geminiKindForMime(blob.mimeType) === 'image').length;
+    if (spec && imageCount > spec.maxInputImages) {
+        throw new TheorumError(`At most ${spec.maxInputImages} reference images on ${model}`);
+    }
+    return blobs.map((blob) => {
+        const kind = assertGeminiMime(blob.mimeType);
+        if (!mimeAllowed(accept, blob.mimeType)) {
+            throw new TheorumError(`MIME '${blob.mimeType}' is not accepted on ${profile.id}`);
+        }
+        const essence = mimeEssence(blob.mimeType);
+        if (kind === 'image' && spec && !spec.inputMimes.includes(essence) && essence !== 'image/jpg') {
+            throw new TheorumError(`MIME '${blob.mimeType}' is not valid on ${model}`);
+        }
+        return {
+            type: kind,
+            mimeType: essence === 'image/jpg' ? 'image/jpeg' : essence,
+            data: blob.data,
+        };
+    });
+}
+function extractTextPart(profile, req) {
+    const { text, repair, history } = req.input ?? {};
+    if (profile.inputs.text === false) {
+        if (text) {
+            throw new TheorumError(`Profile ${profile.id} does not accept text input`);
+        }
+        return null;
+    }
+    let promptText = text;
+    if (repair) {
+        promptText = synthesizeRepairPrompt({ profile, repair, history });
+    }
+    if (!promptText) {
+        return null;
+    }
+    return { type: 'text', text: wrapUserData(promptText) };
+}
+function extractMediaParts(profile, model, req) {
+    const { attachments, voice } = req.input ?? {};
+    const files = attachments ?? [];
+    const clips = voice ?? [];
+    if (files.length + clips.length > 0) {
+        assertAttachmentLimits([...files, ...clips], requireMediaLimits(profile));
+    }
+    const parts = [];
+    if (files.length > 0) {
+        parts.push(...mediaParts(profile, model, files, 'attachments'));
+    }
+    if (clips.length > 0) {
+        parts.push(...mediaParts(profile, model, clips, 'voice'));
+    }
+    return parts;
+}
+function resolveInputParts(profile, model, req) {
+    const parts = [];
+    const textPart = extractTextPart(profile, req);
+    if (textPart) {
+        parts.push(textPart);
+    }
+    parts.push(...extractMediaParts(profile, model, req));
+    return parts;
+}
+function assertImageGrounding(model, builtins) {
+    const spec = modelEntry(model).image;
+    if (spec && !spec.allowsGrounding && builtins.length > 0) {
+        throw new TheorumError(`Grounding tools are not valid on ${model}`);
+    }
+}
+export { assertImageGrounding, resolveImageFormat, resolveInputParts };

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

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ * 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';

package/esm/src/providers/mod.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ * 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';

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

@@ -0,0 +1,24 @@
+/**
+ * OpenRouter payload builder.
+ *
+ * Converts THEORUM provider requests into OpenAI-compatible chat completion
+ * payloads for OpenRouter and compatible gateways.
+ *
+ * @module
+ */
+import type { ModelId, ProviderCompleteRequest } from '../kernel/types.js';
+/** Configuration supplied by the host app when creating OpenRouter providers. */
+interface OpenRouterConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    siteUrl?: string;
+    siteName?: string;
+    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;
+/** 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 { resolveOpenRouterModel, toOpenRouterPayload };

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

@@ -0,0 +1,177 @@
+/**
+ * OpenRouter payload builder.
+ *
+ * Converts THEORUM provider requests into OpenAI-compatible chat completion
+ * payloads for OpenRouter and compatible gateways.
+ *
+ * @module
+ */
+import { CATALOG } 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) {
+    if (customMap?.[modelId]) {
+        return customMap[modelId];
+    }
+    const catalogEntry = CATALOG.models[modelId];
+    if (catalogEntry?.openRouterId) {
+        return catalogEntry.openRouterId;
+    }
+    if (catalogEntry?.apiId.includes('/')) {
+        return catalogEntry.apiId;
+    }
+    if (catalogEntry?.apiId) {
+        return `google/${catalogEntry.apiId}`;
+    }
+    return String(modelId);
+}
+function mapThinkingEffort(thinking) {
+    if (thinking === 'low') {
+        return 'low';
+    }
+    if (thinking === 'medium') {
+        return 'medium';
+    }
+    if (thinking === 'high') {
+        return 'high';
+    }
+    return null;
+}
+function wireAudioPart(part) {
+    let format = 'mp3';
+    if (part.mimeType.includes('wav')) {
+        format = 'wav';
+    }
+    return {
+        type: 'input_audio',
+        input_audio: {
+            data: part.data,
+            format,
+        },
+    };
+}
+function wireMessageContent(parts) {
+    const isAllText = parts.every((p) => p.type === 'text');
+    if (isAllText) {
+        return parts
+            .map((p) => {
+            if (p.type === 'text') {
+                return p.text;
+            }
+            return '';
+        })
+            .join('\n');
+    }
+    return parts.map((part) => {
+        if (part.type === 'text') {
+            return { type: 'text', text: part.text };
+        }
+        if (part.type === 'image') {
+            return {
+                type: 'image_url',
+                image_url: { url: `data:${part.mimeType};base64,${part.data}` },
+            };
+        }
+        if (part.type === 'audio') {
+            return wireAudioPart(part);
+        }
+        return { type: 'text', text: '' };
+    });
+}
+function wireHistoryMessage(msg) {
+    let content = msg.content ?? '';
+    if (msg.parts && msg.parts.length > 0) {
+        content = wireMessageContent(msg.parts);
+    }
+    const wired = {
+        role: msg.role,
+        content,
+    };
+    if (msg.tool_calls && msg.tool_calls.length > 0) {
+        wired.tool_calls = msg.tool_calls;
+    }
+    if (msg.tool_call_id) {
+        wired.tool_call_id = msg.tool_call_id;
+    }
+    if (msg.name) {
+        wired.name = msg.name;
+    }
+    return wired;
+}
+function wireTools(dynamicTools) {
+    if (!dynamicTools || dynamicTools.length === 0) {
+        return [];
+    }
+    return dynamicTools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description ?? '',
+            parameters: t.parameters ?? { type: 'object', properties: {} },
+        },
+    }));
+}
+function buildMessages(req) {
+    const messages = [];
+    if (req.system) {
+        messages.push({ role: 'system', content: req.system });
+    }
+    if (req.history && req.history.length > 0) {
+        for (const h of req.history) {
+            messages.push(wireHistoryMessage(h));
+        }
+    }
+    if (req.input.length > 0) {
+        messages.push({
+            role: 'user',
+            content: wireMessageContent(req.input),
+        });
+    }
+    return messages;
+}
+function resolveResponseFormat(structured) {
+    if (!structured) {
+        return undefined;
+    }
+    const spec = getStructured(structured);
+    if (!spec.jsonSchema) {
+        return undefined;
+    }
+    return {
+        type: 'json_schema',
+        json_schema: {
+            name: String(structured),
+            strict: true,
+            schema: spec.jsonSchema,
+        },
+    };
+}
+/** Convert a provider-neutral request into an OpenRouter chat completion payload. */
+function toOpenRouterPayload(req, config) {
+    const model = resolveOpenRouterModel(req.model, config.modelMap);
+    const messages = buildMessages(req);
+    const payload = {
+        model,
+        stream: true,
+        messages,
+        temperature: req.temperature,
+        max_tokens: req.maxOutputTokens,
+    };
+    const effort = mapThinkingEffort(req.thinking);
+    if (effort) {
+        payload.reasoning = { effort };
+    }
+    const responseFormat = resolveResponseFormat(req.structured);
+    if (responseFormat) {
+        payload.response_format = responseFormat;
+    }
+    const tools = wireTools(req.dynamicTools);
+    if (tools.length > 0) {
+        payload.tools = tools;
+    }
+    if (req.builtins.includes('googleSearch')) {
+        payload.plugins = [{ id: 'web' }];
+    }
+    return payload;
+}
+export { resolveOpenRouterModel, toOpenRouterPayload };

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

@@ -0,0 +1,17 @@
+/**
+ * OpenRouter-compatible streaming provider adapter.
+ *
+ * This module maps THEORUM requests to OpenAI-style chat completions, including
+ * reasoning deltas, tool calls, citations, structured output, and token usage.
+ *
+ * @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. */
+declare function createOpenRouterProvider(config?: OpenRouterConfig): ModelProvider;
+export type { OpenRouterConfig };
+export { createOpenRouterProvider, resolveOpenRouterModel, toOpenRouterPayload };