theorum 0.1.15 → 1.1.3

package/esm/src/providers/openrouter/image.js

@@ -0,0 +1,275 @@
+/**
+ * OpenAI-compatible image generation transport (internal).
+ *
+ * Hosts use `createProvider(profile, { openAiGateway })` — this module is selected
+ * when the profile is an openAi image role on OpenRouter.
+ *
+ * Image-only turns POST `/images`. When `image.includeText` is set, chat
+ * completions carry an OpenRouter image-generation server tool so the model may
+ * return interleaved assistant text and images.
+ *
+ * @module
+ */
+import { toErrorEvent } from '../../guardrails/error.js';
+import { extractUsageTokens } from '../../kernel/engine/delta.js';
+import { bytesToBase64 } from '../shared/pcm.js';
+import { buildChatMessages, openAiGatewayHeaders } from './openai/compat.js';
+import { buildImagesPayload, extractPromptText, imageToolParameters, } from './openai/image-payload.js';
+import { resolveOpenAiGatewayApiKey } from './resolve-api-key.js';
+const HTTP_OK = 200;
+/** OpenRouter chat server tool for inline image generation. */
+export const OPENROUTER_IMAGE_TOOL = 'openrouter:image_generation';
+export function buildImageHeaders(apiKey, config) {
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+    };
+    const gateway = openAiGatewayHeaders(config);
+    if (gateway) {
+        Object.assign(headers, gateway);
+    }
+    return headers;
+}
+function baseUrl(config) {
+    return config.baseUrl?.replace(/\/+$/, '') ?? 'https://openrouter.ai/api/v1';
+}
+function* yieldUsage(raw) {
+    const tokens = extractUsageTokens(raw);
+    if (!tokens) {
+        return;
+    }
+    yield { type: 'tokens', tokens };
+}
+export function mediaFromImagesResponse(body, fallbackMime) {
+    const data = body.data;
+    if (!Array.isArray(data) || data.length === 0) {
+        return null;
+    }
+    const first = data[0];
+    if (!first || typeof first !== 'object') {
+        return null;
+    }
+    const entry = first;
+    const b64 = typeof entry.b64_json === 'string' ? entry.b64_json : '';
+    if (!b64) {
+        return null;
+    }
+    const mimeType = typeof entry.media_type === 'string' && entry.media_type.length > 0
+        ? entry.media_type
+        : fallbackMime;
+    if (!mimeType) {
+        return null;
+    }
+    return { mimeType, data: b64 };
+}
+export async function fetchImageAsBase64(url, fetchFn, signal) {
+    const res = await fetchFn(url, { signal });
+    if (res.status !== HTTP_OK) {
+        return null;
+    }
+    const mimeType = res.headers.get('content-type')?.split(';')[0]?.trim() || 'image/png';
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.length === 0) {
+        return null;
+    }
+    return { mimeType, data: bytesToBase64(bytes) };
+}
+export function markdownImageUrls(content) {
+    const urls = [];
+    const pattern = /!\[[^\]]*]\((https?:\/\/[^)\s]+)\)/g;
+    for (const match of content.matchAll(pattern)) {
+        const url = match[1];
+        if (url) {
+            urls.push(url);
+        }
+    }
+    return urls;
+}
+export function plainTextFromContent(content) {
+    if (typeof content === 'string') {
+        return content.replace(/!\[[^\]]*]\([^)]+\)/g, '').trim();
+    }
+    if (!Array.isArray(content)) {
+        return '';
+    }
+    return content
+        .map((part) => {
+        if (!part || typeof part !== 'object') {
+            return '';
+        }
+        const entry = part;
+        if (entry.type === 'text' && typeof entry.text === 'string') {
+            return entry.text;
+        }
+        return '';
+    })
+        .join('\n')
+        .replace(/!\[[^\]]*]\([^)]+\)/g, '')
+        .trim();
+}
+function httpImageUrlFromPart(entry) {
+    if (entry.type !== 'image_url') {
+        return undefined;
+    }
+    const imageUrl = entry.image_url;
+    if (!imageUrl || typeof imageUrl !== 'object') {
+        return undefined;
+    }
+    const url = imageUrl.url;
+    if (typeof url === 'string' && /^https?:\/\//.test(url)) {
+        return url;
+    }
+    return undefined;
+}
+function inlineImageUrls(content) {
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const urls = [];
+    for (const part of content) {
+        if (!part || typeof part !== 'object') {
+            continue;
+        }
+        const url = httpImageUrlFromPart(part);
+        if (url) {
+            urls.push(url);
+        }
+    }
+    return urls;
+}
+async function postJson(config, apiKey, path, body, signal) {
+    const fetchFn = config.fetch ?? fetch;
+    return await fetchFn(`${baseUrl(config)}${path}`, {
+        method: 'POST',
+        headers: buildImageHeaders(apiKey, config),
+        body: JSON.stringify(body),
+        signal,
+    });
+}
+function imageHttpError(res, label) {
+    if (res.status !== HTTP_OK) {
+        return toErrorEvent(`${label} HTTP ${String(res.status)}`);
+    }
+    return undefined;
+}
+async function requestImages(req, config, apiKey) {
+    return await postJson(config, apiKey, '/images', buildImagesPayload(req), req.signal);
+}
+export function buildInterleavedChatPayload(req) {
+    if (!req.image) {
+        throw new Error('buildInterleavedChatPayload requires req.image');
+    }
+    return {
+        model: req.apiId,
+        stream: false,
+        messages: buildChatMessages(req),
+        temperature: req.temperature,
+        max_tokens: req.maxOutputTokens,
+        ...(req.thinking && req.thinking !== 'none' ? { reasoning: { effort: req.thinking } } : {}),
+        tools: [
+            {
+                type: OPENROUTER_IMAGE_TOOL,
+                parameters: imageToolParameters(req.image),
+            },
+        ],
+    };
+}
+async function requestInterleavedChat(req, config, apiKey) {
+    return await postJson(config, apiKey, '/chat/completions', buildInterleavedChatPayload(req), req.signal);
+}
+export async function* yieldInterleavedChat(req, config, apiKey) {
+    const res = await requestInterleavedChat(req, config, apiKey);
+    const httpErr = imageHttpError(res, 'Image chat');
+    if (httpErr) {
+        yield httpErr;
+        return;
+    }
+    const body = (await res.json());
+    const choices = body.choices;
+    if (!Array.isArray(choices) || choices.length === 0) {
+        yield toErrorEvent('no chat choices returned for image generation');
+        return;
+    }
+    const first = choices[0];
+    if (!first || typeof first !== 'object') {
+        yield toErrorEvent('invalid chat choice for image generation');
+        return;
+    }
+    const message = first.message;
+    if (!message || typeof message !== 'object') {
+        yield toErrorEvent('no assistant message returned for image generation');
+        return;
+    }
+    const content = message.content;
+    const text = plainTextFromContent(content);
+    if (text) {
+        yield { type: 'text', text };
+    }
+    const fetchFn = config.fetch ?? fetch;
+    const urls = [
+        ...inlineImageUrls(content),
+        ...(typeof content === 'string' ? markdownImageUrls(content) : []),
+    ];
+    let emittedMedia = false;
+    for (const url of urls) {
+        const media = await fetchImageAsBase64(url, fetchFn, req.signal);
+        if (!media) {
+            continue;
+        }
+        emittedMedia = true;
+        yield { type: 'media', media };
+    }
+    if (!emittedMedia) {
+        yield toErrorEvent('no image returned from chat image generation');
+        return;
+    }
+    yield* yieldUsage(body.usage);
+    yield { type: 'done' };
+}
+export async function* yieldImagesEndpoint(req, config, apiKey) {
+    const res = await requestImages(req, config, apiKey);
+    const httpErr = imageHttpError(res, 'Image');
+    if (httpErr) {
+        yield httpErr;
+        return;
+    }
+    const body = (await res.json());
+    const media = mediaFromImagesResponse(body, req.image?.mimeType);
+    if (!media) {
+        yield toErrorEvent('no image returned from image generation');
+        return;
+    }
+    yield { type: 'media', media };
+    yield* yieldUsage(body.usage);
+    yield { type: 'done' };
+}
+export async function* streamImage(req, config = {}) {
+    let apiKey;
+    try {
+        apiKey = resolveOpenAiGatewayApiKey(config, req.keySlot);
+    }
+    catch (err) {
+        yield toErrorEvent(err);
+        return;
+    }
+    if (!req.image) {
+        yield toErrorEvent('missing image response format');
+        return;
+    }
+    const prompt = extractPromptText(req.input);
+    if (!prompt) {
+        yield toErrorEvent('empty text for image generation');
+        return;
+    }
+    if (req.image.includeText) {
+        yield* yieldInterleavedChat(req, config, apiKey);
+        return;
+    }
+    yield* yieldImagesEndpoint(req, config, apiKey);
+}
+/** Internal ModelProvider for openAi image roles on OpenRouter. */
+export function createImageProvider(config = {}) {
+    return {
+        complete: (req) => streamImage(req, config),
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * OpenAI-compatible chat payload builder.
+ *
+ * Converts THEORUM provider requests into OpenAI-compatible chat completion
+ * payloads for OpenRouter and compatible gateways.
+ *
+ * Wire-format helpers (messages, tools, response format) are delegated to the
+ * shared `openai/compat` module. This file owns OpenRouter-specific concerns:
+ * plugins, web search, and the top-level payload shape.
+ *
+ * @module
+ */
+import type { ProviderCompleteRequest } from '../../../kernel/types.js';
+/** Convert a provider-neutral request into an OpenAI chat completion payload. */
+declare function toOpenAiChatPayload(req: ProviderCompleteRequest): Record<string, unknown>;
+interface ResolvedPlugins {
+    plugins: Array<{
+        id: string;
+    }>;
+    webSearch: boolean;
+}
+declare function resolveOpenRouterPlugins(builtins: readonly string[]): ResolvedPlugins;
+export type { ResolvedPlugins };
+export { resolveOpenRouterPlugins, toOpenAiChatPayload };

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

@@ -0,0 +1,82 @@
+/**
+ * OpenAI-compatible chat payload builder.
+ *
+ * Converts THEORUM provider requests into OpenAI-compatible chat completion
+ * payloads for OpenRouter and compatible gateways.
+ *
+ * Wire-format helpers (messages, tools, response format) are delegated to the
+ * shared `openai/compat` module. This file owns OpenRouter-specific concerns:
+ * plugins, web search, and the top-level payload shape.
+ *
+ * @module
+ */
+import { getTool } from '../../../kernel/tools/registry.js';
+import { cacheControlFromSpec } from '../cache-control.js';
+import { buildChatMessages, resolveResponseFormat, wireTools } from './compat.js';
+/** Convert a provider-neutral request into an OpenAI chat completion payload. */
+function toOpenAiChatPayload(req) {
+    const messages = buildChatMessages(req);
+    if (req.cache?.mode === 'system' && req.system) {
+        const directive = cacheControlFromSpec(req.cache);
+        const systemIdx = messages.findIndex((m) => m.role === 'system');
+        if (systemIdx >= 0) {
+            const text = typeof messages[systemIdx].content === 'string'
+                ? messages[systemIdx].content
+                : '';
+            messages[systemIdx] = {
+                role: 'system',
+                content: [{ type: 'text', text, cache_control: directive }],
+            };
+        }
+    }
+    const payload = {
+        model: req.apiId,
+        stream: true,
+        messages,
+        temperature: req.temperature,
+        max_tokens: req.maxOutputTokens,
+    };
+    if (req.thinking && req.thinking !== 'none') {
+        payload.reasoning = { effort: req.thinking };
+    }
+    if (req.cache?.mode === 'automatic') {
+        payload.cache_control = cacheControlFromSpec(req.cache);
+    }
+    if (req.sessionId) {
+        payload.session_id = req.sessionId;
+    }
+    const responseFormat = resolveResponseFormat(req.structured);
+    if (responseFormat) {
+        payload.response_format = responseFormat;
+    }
+    const tools = wireTools(req.wireTools);
+    if (tools) {
+        payload.tools = tools;
+    }
+    const resolved = resolveOpenRouterPlugins(req.builtins);
+    if (resolved.webSearch) {
+        payload.web_search_options = {};
+    }
+    if (resolved.plugins.length > 0) {
+        payload.plugins = resolved.plugins;
+    }
+    return payload;
+}
+function resolveOpenRouterPlugins(builtins) {
+    let webSearch = false;
+    const plugins = [];
+    for (const id of builtins) {
+        const entry = getTool(id);
+        const pluginId = entry?.type === 'builtin' ? entry.wire.openRouter : undefined;
+        if (!pluginId)
+            continue;
+        if (pluginId === 'web') {
+            webSearch = true;
+        }
+        else {
+            plugins.push({ id: pluginId });
+        }
+    }
+    return { plugins, webSearch };
+}
+export { resolveOpenRouterPlugins, toOpenAiChatPayload };

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

@@ -0,0 +1,53 @@
+/**
+ * Shared helpers for building OpenAI-compatible chat completion payloads.
+ *
+ * Used by local.ts (raw fetch), openai/chat-payload.ts (REST payload), and
+ * Used by openrouter/chat.ts (headers + response format). Message bodies for the AI SDK
+ * path are built by `openai/sdk-messages.ts`, which shares tool helpers here.
+ * Single source of truth for message wire format, tool declarations,
+ * structured response format, and gateway headers.
+ *
+ * @module
+ */
+import type { InteractionPart, ProviderCompleteRequest, StructuredSchemaId, WireFunctionTool } from '../../../kernel/types.js';
+/** Subset of provider config used for OpenAI-gateway HTTP headers. */
+interface GatewayHeaderConfig {
+    siteUrl?: string;
+    siteName?: string;
+}
+declare function stringDefault(value: string | undefined, fallback: string): string;
+declare function fallbackToolCallId(name?: string): string;
+declare function parseToolInput(raw: string): Record<string, unknown>;
+/**
+ * Map InteractionPart[] to OpenAI-compat message content.
+ * Text-only inputs are joined as a plain string; mixed inputs produce a
+ * content-part array (text, image_url, input_audio, file).
+ */
+export declare function wireMessageContent(parts: InteractionPart[]): unknown;
+/**
+ * Build the complete `messages` array for an OpenAI chat completion request.
+ * Assembles: system → history → user input.
+ *
+ * Set `includeSystem: false` when the caller passes system text separately
+ * (e.g. AI SDK `instructions`).
+ */
+declare function buildChatMessages(req: ProviderCompleteRequest, options?: {
+    includeSystem?: boolean;
+}): Record<string, unknown>[];
+/**
+ * Map wire function tools to OpenAI-compat function tool format.
+ * Returns undefined when there are no tools.
+ */
+declare function wireTools(wireTools?: WireFunctionTool[]): Record<string, unknown>[] | undefined;
+/**
+ * Resolve a StructuredSchemaId to an OpenAI `response_format` object.
+ * Returns undefined when the schema has no JSON schema.
+ */
+declare function resolveResponseFormat(structured: StructuredSchemaId | null): Record<string, unknown> | undefined;
+/**
+ * Build optional HTTP-Referer / X-Title headers for OpenAI-compat gateways.
+ * Used by OpenRouter (chat + speech) and local providers.
+ */
+declare function openAiGatewayHeaders(config: GatewayHeaderConfig): Record<string, string> | undefined;
+export type { GatewayHeaderConfig };
+export { buildChatMessages, fallbackToolCallId, openAiGatewayHeaders, parseToolInput, resolveResponseFormat, stringDefault, wireTools, };

package/esm/src/providers/openrouter/openai/compat.js

@@ -0,0 +1,213 @@
+/**
+ * Shared helpers for building OpenAI-compatible chat completion payloads.
+ *
+ * Used by local.ts (raw fetch), openai/chat-payload.ts (REST payload), and
+ * Used by openrouter/chat.ts (headers + response format). Message bodies for the AI SDK
+ * path are built by `openai/sdk-messages.ts`, which shares tool helpers here.
+ * Single source of truth for message wire format, tool declarations,
+ * structured response format, and gateway headers.
+ *
+ * @module
+ */
+import { TheorumError } from '../../../guardrails/error.js';
+import { isMediaRefPart } from '../../../kernel/interaction-parts.js';
+import { getStructured } from '../../../kernel/registry/schemas.js';
+import { parseToolArgumentsObject } from '../../shared/tool-args.js';
+// ── shared tool helpers ─────────────────────────────
+function stringDefault(value, fallback) {
+    return value === undefined ? fallback : value;
+}
+function fallbackToolCallId(name) {
+    return `call_${stringDefault(name, 'tool')}`;
+}
+function parseToolInput(raw) {
+    const parsed = parseToolArgumentsObject(raw);
+    if (!parsed.ok) {
+        throw new TheorumError(parsed.error);
+    }
+    return parsed.value;
+}
+// ── content wire format ─────────────────────────────
+function rejectMediaRef(part) {
+    if (isMediaRefPart(part)) {
+        throw new TheorumError('media references are not supported on openAi');
+    }
+}
+function wireAudioPart(part) {
+    let format = 'mp3';
+    if (part.mimeType.includes('wav')) {
+        format = 'wav';
+    }
+    return {
+        type: 'input_audio',
+        input_audio: {
+            data: part.data,
+            format,
+        },
+    };
+}
+/**
+ * Map InteractionPart[] to OpenAI-compat message content.
+ * Text-only inputs are joined as a plain string; mixed inputs produce a
+ * content-part array (text, image_url, input_audio, file).
+ */
+export 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 '';
+        })
+            .filter(Boolean)
+            .join('\n');
+    }
+    return parts.map((part) => {
+        if (part.type === 'text') {
+            return { type: 'text', text: part.text };
+        }
+        rejectMediaRef(part);
+        if (part.type === 'image') {
+            return {
+                type: 'image_url',
+                image_url: { url: `data:${part.mimeType};base64,${part.data}` },
+            };
+        }
+        if (part.type === 'audio') {
+            return wireAudioPart(part);
+        }
+        // video + document — file part (OpenAI-compat / OpenRouter)
+        return {
+            type: 'file',
+            file: {
+                filename: part.type === 'video' ? 'clip.bin' : 'document.bin',
+                file_data: `data:${part.mimeType};base64,${part.data}`,
+            },
+        };
+    });
+}
+// ── history message wire format ─────────────────────
+/**
+ * Map a single TurnHistoryMessage to an OpenAI-compat wire message.
+ * Tool messages receive a fallback tool_call_id when the source omits one.
+ * Assistant tool_calls are mapped to strip non-standard fields.
+ */
+function wireHistoryMessage(msg) {
+    if (msg.role === 'tool') {
+        let content = msg.content ?? '';
+        if (msg.parts && msg.parts.length > 0) {
+            // Prefer multimodal parts; if only text parts, wireMessageContent collapses to string.
+            content = wireMessageContent(msg.parts);
+        }
+        return {
+            role: 'tool',
+            tool_call_id: msg.tool_call_id ?? fallbackToolCallId(msg.name),
+            name: msg.name,
+            content,
+        };
+    }
+    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.map((tc) => ({
+            id: tc.id,
+            type: 'function',
+            function: { name: tc.function.name, arguments: tc.function.arguments },
+        }));
+    }
+    if (msg.name) {
+        wired.name = msg.name;
+    }
+    return wired;
+}
+// ── full message array builder ──────────────────────
+/**
+ * Build the complete `messages` array for an OpenAI chat completion request.
+ * Assembles: system → history → user input.
+ *
+ * Set `includeSystem: false` when the caller passes system text separately
+ * (e.g. AI SDK `instructions`).
+ */
+function buildChatMessages(req, options) {
+    const includeSystem = options?.includeSystem !== false;
+    const messages = [];
+    if (includeSystem && 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;
+}
+// ── tool declarations ───────────────────────────────
+/**
+ * Map wire function tools to OpenAI-compat function tool format.
+ * Returns undefined when there are no tools.
+ */
+function wireTools(wireTools) {
+    if (!wireTools || wireTools.length === 0) {
+        return undefined;
+    }
+    return wireTools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+        },
+    }));
+}
+// ── structured response format ──────────────────────
+/**
+ * Resolve a StructuredSchemaId to an OpenAI `response_format` object.
+ * Returns undefined when the schema has no JSON schema.
+ */
+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,
+        },
+    };
+}
+// ── gateway headers ─────────────────────────────────
+/**
+ * Build optional HTTP-Referer / X-Title headers for OpenAI-compat gateways.
+ * Used by OpenRouter (chat + speech) and local providers.
+ */
+function openAiGatewayHeaders(config) {
+    const headers = {};
+    if (config.siteUrl) {
+        headers['HTTP-Referer'] = config.siteUrl;
+    }
+    if (config.siteName) {
+        headers['X-Title'] = config.siteName;
+    }
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
+export { buildChatMessages, fallbackToolCallId, openAiGatewayHeaders, parseToolInput, resolveResponseFormat, stringDefault, wireTools, };

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

@@ -0,0 +1,18 @@
+/**
+ * OpenAI-compatible image generation payloads.
+ *
+ * Maps kernel `ImageResponseFormat` pins to the `/images` REST body shared by
+ * OpenRouter and other OpenAI-compat gateways.
+ *
+ * @module
+ */
+import type { ImageResponseFormat, InteractionMediaPart, InteractionPart, ProviderCompleteRequest } from '../../../kernel/types.js';
+export declare function extractPromptText(input: InteractionPart[]): string;
+export declare function outputFormatFromMime(mimeType: string): string;
+export declare function wireInputReference(part: InteractionMediaPart): Record<string, unknown>;
+export declare function wireInputReferences(input: InteractionPart[]): Record<string, unknown>[];
+export declare function attachImagePins(payload: Record<string, unknown>, image: ImageResponseFormat): void;
+/** Build a POST `/images` body for native image-generation models. */
+export declare function buildImagesPayload(req: ProviderCompleteRequest): Record<string, unknown>;
+/** Tool parameters for gateways that generate images inside chat completions. */
+export declare function imageToolParameters(image: ImageResponseFormat): Record<string, unknown>;