theorum 0.1.2

package/esm/src/providers/openrouter.js

@@ -0,0 +1,332 @@
+/**
+ * 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 { publicError, TheorumError } from '../guardrails/error.js';
+import { tryStructured } from '../kernel/engine/delta.js';
+import { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';
+import { takeSsePayloads } from './sse.js';
+const HTTP_OK = 200;
+const DEFAULT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+async function* readSseLines(res) {
+    if (!res.body) {
+        throw new TheorumError('empty OpenRouter stream');
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let pendingEvent = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const taken = takeSsePayloads(buffer, pendingEvent);
+        buffer = taken.rest;
+        pendingEvent = taken.pendingEvent;
+        for (const payload of taken.payloads) {
+            yield payload;
+        }
+    }
+}
+function extractReasoning(delta) {
+    if (typeof delta.reasoning === 'string') {
+        return delta.reasoning;
+    }
+    if (typeof delta.thinking === 'string') {
+        return delta.thinking;
+    }
+    return undefined;
+}
+function applyToolCallObject(callObj, toolMap) {
+    let index = 0;
+    if (typeof callObj.index === 'number') {
+        index = callObj.index;
+    }
+    const current = toolMap.get(index) ?? { index, arguments: '' };
+    if (typeof callObj.id === 'string') {
+        current.id = callObj.id;
+    }
+    const fn = callObj.function;
+    if (fn) {
+        if (typeof fn.name === 'string') {
+            current.name = (current.name ?? '') + fn.name;
+        }
+        if (typeof fn.arguments === 'string') {
+            current.arguments += fn.arguments;
+        }
+    }
+    toolMap.set(index, current);
+}
+function processToolCalls(rawCalls, toolMap) {
+    for (const rawCall of rawCalls) {
+        if (rawCall && typeof rawCall === 'object') {
+            applyToolCallObject(rawCall, toolMap);
+        }
+    }
+}
+function processDelta(delta, acc) {
+    const events = [];
+    const reasoning = extractReasoning(delta);
+    if (reasoning) {
+        events.push({ type: 'thought', text: reasoning });
+    }
+    if (typeof delta.content === 'string') {
+        acc.text += delta.content;
+        events.push({ type: 'text', text: delta.content });
+    }
+    if (Array.isArray(delta.tool_calls)) {
+        processToolCalls(delta.tool_calls, acc.toolCalls);
+    }
+    const evidence = evidenceFromRecord(delta);
+    if (evidence && !acc.evidenceSeen) {
+        acc.evidenceSeen = true;
+        events.push(evidence);
+    }
+    return events;
+}
+function stringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const out = value.filter((item) => typeof item === 'string');
+    return out.length > 0 ? out : undefined;
+}
+function recordField(record, key) {
+    const value = record[key];
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function firstEvidenceRaw(record) {
+    for (const key of [
+        'annotations',
+        'citations',
+        'search_results',
+        'searchResults',
+        'provider_metadata',
+        'providerMetadata',
+    ]) {
+        const value = record[key];
+        if (value !== undefined) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function evidenceCitations(record) {
+    return (stringArray(record.citations) ??
+        stringArray(recordField(record, 'provider_metadata')?.citations) ??
+        stringArray(recordField(record, 'providerMetadata')?.citations));
+}
+function evidenceAnnotations(record) {
+    return Array.isArray(record.annotations) ? record.annotations : undefined;
+}
+function evidenceFromRecord(record) {
+    if (firstEvidenceRaw(record) === undefined) {
+        return undefined;
+    }
+    return {
+        type: 'evidence',
+        evidence: {
+            provider: 'openrouter',
+            raw: record,
+            citations: evidenceCitations(record),
+            annotations: evidenceAnnotations(record),
+        },
+    };
+}
+function parseUsage(usageRaw) {
+    if (!usageRaw || typeof usageRaw !== 'object') {
+        return undefined;
+    }
+    const u = usageRaw;
+    let input = 0;
+    if (typeof u.prompt_tokens === 'number') {
+        input = u.prompt_tokens;
+    }
+    let output = 0;
+    if (typeof u.completion_tokens === 'number') {
+        output = u.completion_tokens;
+    }
+    let total = input + output;
+    if (typeof u.total_tokens === 'number') {
+        total = u.total_tokens;
+    }
+    return { input, output, total };
+}
+function parseToolArgs(rawArgs) {
+    try {
+        return JSON.parse(rawArgs);
+    }
+    catch {
+        return { _raw: rawArgs };
+    }
+}
+function emitRemainingTools(acc) {
+    const events = [];
+    for (const tool of acc.toolCalls.values()) {
+        if (tool.name) {
+            let args;
+            if (tool.arguments) {
+                args = parseToolArgs(tool.arguments);
+            }
+            events.push({
+                type: 'tool',
+                tool: {
+                    name: tool.name,
+                    arguments: args,
+                    ...(tool.id ? { id: tool.id } : {}),
+                },
+            });
+        }
+    }
+    return events;
+}
+function buildHeaders(apiKey, config) {
+    const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (config.siteUrl) {
+        headers['HTTP-Referer'] = config.siteUrl;
+    }
+    if (config.siteName) {
+        headers['X-Title'] = config.siteName;
+    }
+    return headers;
+}
+async function postOpenRouter(req, config, apiKey) {
+    const baseUrl = config.baseUrl ?? DEFAULT_OPENROUTER_BASE_URL;
+    const url = `${baseUrl.replace(/\/+$/, '')}/chat/completions`;
+    const fetchFn = config.fetch ?? fetch;
+    const headers = buildHeaders(apiKey, config);
+    const body = JSON.stringify(toOpenRouterPayload(req, config));
+    return await fetchFn(url, { method: 'POST', headers, body });
+}
+function processChoiceDeltas(choices, acc) {
+    if (!Array.isArray(choices)) {
+        return [];
+    }
+    const events = [];
+    for (const choice of choices) {
+        events.push(...processChoiceDelta(choice, acc));
+    }
+    return events;
+}
+function processChoiceDelta(choice, acc) {
+    if (!choice || typeof choice !== 'object') {
+        return [];
+    }
+    const c = choice;
+    const events = processChoiceDeltaPayload(c.delta, acc);
+    const evidence = evidenceFromChoiceMessage(c.message, acc);
+    if (evidence) {
+        events.push(evidence);
+    }
+    return events;
+}
+function processChoiceDeltaPayload(delta, acc) {
+    if (!delta || typeof delta !== 'object') {
+        return [];
+    }
+    return processDelta(delta, acc);
+}
+function evidenceFromChoiceMessage(message, acc) {
+    if (!message || typeof message !== 'object') {
+        return undefined;
+    }
+    const evidence = evidenceFromRecord(message);
+    if (!evidence || acc.evidenceSeen) {
+        return undefined;
+    }
+    acc.evidenceSeen = true;
+    return evidence;
+}
+function* yieldRemainingStreamEvents(req, acc) {
+    for (const ev of emitRemainingTools(acc)) {
+        yield ev;
+    }
+    if (req.structured && acc.text) {
+        const structured = tryStructured(acc.text);
+        if (structured) {
+            yield structured;
+        }
+    }
+    yield { type: 'done' };
+}
+function evidenceFromPayload(payload, acc) {
+    const evidence = evidenceFromRecord(payload);
+    if (!evidence || acc.evidenceSeen) {
+        return undefined;
+    }
+    acc.evidenceSeen = true;
+    return evidence;
+}
+function* eventsFromPayload(payload, acc) {
+    const evidence = evidenceFromPayload(payload, acc);
+    if (evidence) {
+        yield evidence;
+    }
+    for (const ev of processChoiceDeltas(payload.choices, acc)) {
+        yield ev;
+    }
+}
+async function* streamOpenRouter(req, config) {
+    const apiKey = resolveOpenRouterApiKey(config.apiKey);
+    if (!apiKey) {
+        yield { type: 'error', error: publicError('missing OpenRouter API key') };
+        return;
+    }
+    try {
+        const res = await postOpenRouter(req, config, apiKey);
+        if (res.status !== HTTP_OK) {
+            yield { type: 'error', error: publicError(`OpenRouter HTTP ${String(res.status)}`) };
+            return;
+        }
+        const acc = { text: '', toolCalls: new Map(), evidenceSeen: false };
+        let emittedTokens = false;
+        let sawPayload = false;
+        for await (const payload of readSseLines(res)) {
+            sawPayload = true;
+            req.tapGemini?.(payload);
+            for (const ev of eventsFromPayload(payload, acc)) {
+                yield ev;
+            }
+            const usage = parseUsage(payload.usage);
+            if (usage && !emittedTokens) {
+                emittedTokens = true;
+                yield { type: 'tokens', tokens: usage };
+            }
+        }
+        if (!sawPayload) {
+            yield { type: 'error', error: publicError('empty OpenRouter stream') };
+            return;
+        }
+        yield* yieldRemainingStreamEvents(req, acc);
+    }
+    catch (err) {
+        yield { type: 'error', error: publicError(err) };
+    }
+}
+/** Resolve an OpenRouter API key supplied explicitly by the host application. */
+export function resolveOpenRouterApiKey(explicitKey) {
+    if (explicitKey?.trim()) {
+        return explicitKey.trim();
+    }
+    return undefined;
+}
+/** Create a `ModelProvider` backed by OpenRouter-compatible chat completions. */
+function createOpenRouterProvider(config = {}) {
+    return {
+        complete: (req) => streamOpenRouter(req, config),
+    };
+}
+export { createOpenRouterProvider, resolveOpenRouterModel, toOpenRouterPayload };

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

@@ -0,0 +1,13 @@
+/**
+ * Google Interactions provider adapter.
+ *
+ * This adapter converts THEORUM's provider-neutral request into the Google
+ * Interactions wire format and streams normalized `TurnEvent` objects.
+ *
+ * @module
+ */
+import { type GeminiTransport } from '../guardrails/keys.js';
+import type { ModelProvider } from '../kernel/types.js';
+/** Create a `ModelProvider` backed by Google Interactions streaming. */
+declare function createInteractionsProvider(transport: GeminiTransport): ModelProvider;
+export { createInteractionsProvider };

package/esm/src/providers/provider.js

@@ -0,0 +1,123 @@
+/**
+ * Google Interactions provider adapter.
+ *
+ * This adapter converts THEORUM's provider-neutral request into the Google
+ * Interactions wire format and streams normalized `TurnEvent` objects.
+ *
+ * @module
+ */
+import { publicError, TheorumError } from '../guardrails/error.js';
+import { fetchGemini } from '../guardrails/keys.js';
+import { eventsFromComplete, eventsFromDelta, extractTokenEvent, groundingFromEvent, tryStructured, } from '../kernel/engine/delta.js';
+import { tapFetch } from './google-tap.js';
+import { toInteractionsBody } from './interactions.js';
+import { INTERACTIONS_URL, takeSsePayloads } from './sse.js';
+const HTTP_OK = 200;
+async function* readSseRecords(res) {
+    if (!res.body) {
+        throw new TheorumError('empty Gemini stream');
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    yield* pumpSse(reader, decoder, '', '');
+}
+async function* pumpSse(reader, decoder, buffer, pendingEvent) {
+    const { done, value } = await reader.read();
+    if (done) {
+        return;
+    }
+    const next = buffer + decoder.decode(value, { stream: true });
+    const taken = takeSsePayloads(next, pendingEvent);
+    for (const payload of taken.payloads) {
+        yield payload;
+    }
+    yield* pumpSse(reader, decoder, taken.rest, taken.pendingEvent);
+}
+function eventType(event) {
+    return String(event.event_type ?? event.type ?? '');
+}
+function isDeltaEvent(kind) {
+    return kind === 'content.delta' || kind === 'step.delta';
+}
+function isCompleteEvent(kind) {
+    return (kind === 'interaction.complete' ||
+        kind === 'interaction.completed' ||
+        kind.startsWith('interaction.'));
+}
+function foldDeltaPayload(event, acc) {
+    const deltaEvents = eventsFromDelta(event.delta);
+    for (const item of deltaEvents) {
+        if (item.type === 'text' && item.text) {
+            acc.text += item.text;
+        }
+    }
+    return deltaEvents;
+}
+function foldPayload(event, acc) {
+    const kind = eventType(event);
+    const events = [];
+    if (isDeltaEvent(kind)) {
+        events.push(...foldDeltaPayload(event, acc));
+    }
+    else if (isCompleteEvent(kind)) {
+        events.push(...eventsFromComplete(event, acc.text.length > 0));
+    }
+    // Also check if usage was included on the event directly
+    if (!events.some((e) => e.type === 'tokens')) {
+        const tokenEvent = extractTokenEvent(event);
+        if (tokenEvent) {
+            events.push(tokenEvent);
+        }
+    }
+    const groundingEvent = groundingFromEvent(event);
+    if (groundingEvent && !events.some((e) => e.type === 'grounding')) {
+        events.push(groundingEvent);
+    }
+    return events;
+}
+function withTap(req, transport) {
+    return {
+        ...transport,
+        fetch: tapFetch(req.tapGemini, transport.fetch),
+    };
+}
+async function* streamComplete(req, transport) {
+    const res = await fetchGemini(INTERACTIONS_URL, { method: 'POST', body: JSON.stringify(toInteractionsBody(req)) }, req.geminiBucket, withTap(req, transport));
+    if (res.status !== HTTP_OK) {
+        const errorBody = await res.text().catch(() => '');
+        yield {
+            type: 'error',
+            error: publicError(`Gemini HTTP ${String(res.status)}: ${errorBody}`),
+        };
+        return;
+    }
+    const acc = { text: '' };
+    for await (const payload of readSseRecords(res)) {
+        req.tapGemini?.(payload);
+        const events = foldPayload(payload, acc);
+        for (const event of events) {
+            yield event;
+        }
+    }
+    if (req.structured && acc.text) {
+        const structured = tryStructured(acc.text);
+        if (structured) {
+            yield structured;
+        }
+    }
+}
+async function* streamGuarded(req, transport) {
+    try {
+        yield* streamComplete(req, transport);
+    }
+    catch (err) {
+        yield { type: 'error', error: publicError(err) };
+    }
+}
+/** Create a `ModelProvider` backed by Google Interactions streaming. */
+function createInteractionsProvider(transport) {
+    return {
+        complete: (req) => streamGuarded(req, transport),
+    };
+}
+export { createInteractionsProvider };

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

@@ -0,0 +1,7 @@
+declare const INTERACTIONS_URL = "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse";
+declare function takeSsePayloads(buffer: string, pendingEvent?: string): {
+    rest: string;
+    payloads: Record<string, unknown>[];
+    pendingEvent: string;
+};
+export { INTERACTIONS_URL, takeSsePayloads };

package/esm/src/providers/sse.js

@@ -0,0 +1,53 @@
+const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse';
+const DATA_PREFIX = 'data: ';
+const EVENT_PREFIX = 'event: ';
+const DONE = '[DONE]';
+function asObject(parsed) {
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return undefined;
+}
+function dataRecord(raw, sseEvent) {
+    const data = raw.slice(DATA_PREFIX.length).trim();
+    const row = {};
+    if (sseEvent) {
+        row.sseEvent = sseEvent;
+    }
+    if (!data || data === DONE) {
+        row.eventType = 'sse_done';
+        return row;
+    }
+    try {
+        const parsed = JSON.parse(data);
+        const obj = asObject(parsed);
+        if (obj) {
+            return { ...obj, ...row };
+        }
+        row.eventType = 'sse_unparsed';
+        row.data = parsed;
+        return row;
+    }
+    catch {
+        row.eventType = 'sse_unparsed';
+        row.data = data;
+        return row;
+    }
+}
+function takeSsePayloads(buffer, pendingEvent = '') {
+    const payloads = [];
+    const chunks = buffer.split('\n');
+    const rest = chunks.pop() ?? '';
+    let sseEvent = pendingEvent;
+    for (const line of chunks) {
+        if (line.startsWith(EVENT_PREFIX)) {
+            sseEvent = line.slice(EVENT_PREFIX.length).trim();
+        }
+        else if (line.startsWith(DATA_PREFIX)) {
+            payloads.push(dataRecord(line, sseEvent));
+            sseEvent = '';
+        }
+    }
+    return { rest, payloads, pendingEvent: sseEvent };
+}
+export { INTERACTIONS_URL, takeSsePayloads };

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

@@ -0,0 +1,24 @@
+/**
+ * OpenRouter TTS provider utilities.
+ *
+ * Provides direct text-to-speech streaming and a `ModelProvider` wrapper for
+ * voice output profiles.
+ *
+ * @module
+ */
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../kernel/types.js';
+/** Wrap raw PCM bytes in a RIFF/WAVE container. */
+export declare function wrapPcmAsWav(pcm: Uint8Array, sampleRate?: number): Uint8Array;
+/** Host-supplied OpenRouter TTS configuration. */
+export interface OpenRouterTtsConfig {
+    apiKey?: string;
+    voiceName?: string;
+    baseUrl?: string;
+    siteUrl?: string;
+    siteName?: string;
+    fetch?: typeof fetch;
+}
+/** Stream one OpenRouter TTS synthesis request as THEORUM events. */
+export declare function streamOpenRouterTts(req: ProviderCompleteRequest, config?: OpenRouterTtsConfig): AsyncGenerator<TurnEvent>;
+/** Create a `ModelProvider` that emits TTS media events. */
+export declare function createOpenRouterTtsProvider(config?: OpenRouterTtsConfig): ModelProvider;

package/esm/src/providers/tts.js

@@ -0,0 +1,144 @@
+/**
+ * OpenRouter TTS provider utilities.
+ *
+ * Provides direct text-to-speech streaming and a `ModelProvider` wrapper for
+ * voice output profiles.
+ *
+ * @module
+ */
+import { publicError } from '../guardrails/error.js';
+import { resolveOpenRouterApiKey } from './openrouter.js';
+const SAMPLE_RATE = 24000;
+const TTS_MODEL = 'google/gemini-3.1-flash-tts-preview';
+const HTTP_OK = 200;
+function bytesToBase64(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function writeAscii(view, offset, str) {
+    for (let i = 0; i < str.length; i++)
+        view.setUint8(offset + i, str.charCodeAt(i));
+}
+/** Wrap raw PCM bytes in a RIFF/WAVE container. */
+export function wrapPcmAsWav(pcm, sampleRate = SAMPLE_RATE) {
+    const numChannels = 1;
+    const bitsPerSample = 16;
+    const byteRate = (sampleRate * numChannels * bitsPerSample) / 8;
+    const blockAlign = (numChannels * bitsPerSample) / 8;
+    const dataSize = pcm.length;
+    const buf = new ArrayBuffer(44 + dataSize);
+    const view = new DataView(buf);
+    writeAscii(view, 0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true);
+    writeAscii(view, 8, 'WAVE');
+    writeAscii(view, 12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true); // PCM
+    view.setUint16(22, numChannels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, byteRate, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, bitsPerSample, true);
+    writeAscii(view, 36, 'data');
+    view.setUint32(40, dataSize, true);
+    new Uint8Array(buf, 44).set(pcm);
+    return new Uint8Array(buf);
+}
+function extractInputText(input) {
+    return input
+        .filter((p) => p.type === 'text')
+        .map((p) => (p.type === 'text' ? p.text : ''))
+        .join(' ')
+        .trim();
+}
+function buildHeaders(apiKey, config) {
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+    };
+    if (config.siteUrl) {
+        headers['HTTP-Referer'] = config.siteUrl;
+    }
+    if (config.siteName) {
+        headers['X-Title'] = config.siteName;
+    }
+    return headers;
+}
+function buildPayload(text, voiceSpec, configVoiceName) {
+    const voice = voiceSpec?.voice ?? configVoiceName;
+    const responseFormat = voiceSpec?.responseFormat ?? 'pcm';
+    const payload = {
+        model: TTS_MODEL,
+        input: text,
+        response_format: responseFormat,
+    };
+    if (voice) {
+        payload.voice = voice;
+    }
+    return payload;
+}
+async function requestTts(apiKey, text, req, config) {
+    const fetchFn = config.fetch ?? fetch;
+    const baseUrl = config.baseUrl?.replace(/\/+$/, '') ?? 'https://openrouter.ai/api/v1';
+    const url = `${baseUrl}/audio/speech`;
+    return await fetchFn(url, {
+        method: 'POST',
+        headers: buildHeaders(apiKey, config),
+        body: JSON.stringify(buildPayload(text, req.voice, config.voiceName)),
+    });
+}
+function* yieldTtsSuccess(rawBytes, text, responseFormat) {
+    let mediaMime = 'audio/mpeg';
+    let mediaBytes = rawBytes;
+    if (responseFormat === 'pcm') {
+        mediaMime = 'audio/wav';
+        mediaBytes = wrapPcmAsWav(rawBytes);
+    }
+    yield {
+        type: 'media',
+        media: { mimeType: mediaMime, data: bytesToBase64(mediaBytes) },
+    };
+    const inputTokens = Math.max(1, Math.round(text.length / 4));
+    const outputTokens = Math.max(1, Math.round(rawBytes.length / 100));
+    yield {
+        type: 'tokens',
+        tokens: { input: inputTokens, output: outputTokens, total: inputTokens + outputTokens },
+    };
+    yield { type: 'done' };
+}
+/** Stream one OpenRouter TTS synthesis request as THEORUM events. */
+export async function* streamOpenRouterTts(req, config = {}) {
+    const apiKey = resolveOpenRouterApiKey(config.apiKey);
+    if (!apiKey) {
+        yield { type: 'error', error: publicError('missing OpenRouter API key for TTS') };
+        return;
+    }
+    const text = extractInputText(req.input);
+    if (!text) {
+        yield { type: 'error', error: publicError('empty text for TTS') };
+        return;
+    }
+    const res = await requestTts(apiKey, text, req, config);
+    if (res.status !== HTTP_OK) {
+        yield { type: 'error', error: publicError(`OpenRouter TTS HTTP ${String(res.status)}`) };
+        return;
+    }
+    const arrayBuffer = await res.arrayBuffer();
+    const rawBytes = new Uint8Array(arrayBuffer);
+    if (rawBytes.length === 0) {
+        yield { type: 'error', error: publicError('no audio returned from TTS') };
+        return;
+    }
+    const responseFormat = req.voice?.responseFormat ?? 'pcm';
+    for (const ev of yieldTtsSuccess(rawBytes, text, responseFormat)) {
+        yield ev;
+    }
+}
+/** Create a `ModelProvider` that emits TTS media events. */
+export function createOpenRouterTtsProvider(config = {}) {
+    return {
+        complete: (req) => streamOpenRouterTts(req, config),
+    };
+}