theorum 0.1.15 → 1.1.3

package/esm/src/providers/google/interactions/framing.js

@@ -0,0 +1,269 @@
+import { TheorumError } from '../../../guardrails/error.js';
+import { wireInteractionPart } from '../../../kernel/interaction-parts.js';
+import { getStructured } from '../../../kernel/registry/schemas.js';
+import { getTool } from '../../../kernel/tools/registry.js';
+export function camelToSnake(key) {
+    return key.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+export 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' || key === 'parameters') {
+                out[camelToSnake(key)] = nested;
+                continue;
+            }
+            out[camelToSnake(key)] = toGoogleValue(nested);
+        }
+        return out;
+    }
+    return value;
+}
+export function wirePart(part) {
+    return wireInteractionPart(part);
+}
+const USER_INPUT = 'user_input';
+export function userInputStep(parts) {
+    return { type: USER_INPUT, content: parts.map(wirePart) };
+}
+function functionResultStep(msg) {
+    const result = msg.parts && msg.parts.length > 0
+        ? msg.parts.map(wirePart)
+        : [{ type: 'text', text: msg.content ?? '' }];
+    return {
+        type: 'function_result',
+        name: msg.name ?? '',
+        call_id: msg.tool_call_id ?? '',
+        result,
+    };
+}
+/** Parse OpenAI-style tool-call `arguments` JSON into an Interactions object. */
+function functionCallArguments(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return { value: parsed };
+    }
+    catch {
+        return { value: raw };
+    }
+}
+function functionCallStep(call) {
+    const step = {
+        type: 'function_call',
+        id: call.id,
+        name: call.function.name,
+        arguments: functionCallArguments(call.function.arguments),
+    };
+    if (call.thoughtSignature) {
+        step.thoughtSignature = call.thoughtSignature;
+    }
+    return step;
+}
+function textOrPartsStep(role, msg) {
+    // Google Interactions input steps: assistant history is `model_output` (not `model_turn`).
+    const type = role === 'assistant' ? 'model_output' : 'user_input';
+    if (msg.parts && msg.parts.length > 0) {
+        return { type, content: msg.parts.map(wirePart) };
+    }
+    return { type, content: [{ type: 'text', text: msg.content ?? '' }] };
+}
+/**
+ * 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 function historySteps(msg) {
+    if (msg.role === 'tool') {
+        return [functionResultStep(msg)];
+    }
+    if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
+        const steps = [];
+        const hasParts = Boolean(msg.parts && msg.parts.length > 0);
+        const hasText = Boolean(msg.content?.trim());
+        if (hasParts || hasText) {
+            steps.push(textOrPartsStep('assistant', msg));
+        }
+        for (const call of msg.tool_calls) {
+            steps.push(functionCallStep(call));
+        }
+        return steps;
+    }
+    if (msg.role === 'assistant') {
+        return [textOrPartsStep('assistant', msg)];
+    }
+    return [textOrPartsStep('user', msg)];
+}
+/** Single-step helper for simple messages (first of {@link historySteps}). */
+export function historyStep(msg) {
+    const steps = historySteps(msg);
+    return steps[0] ?? { type: 'user_input', content: [{ type: 'text', text: '' }] };
+}
+export function systemHoldsUserInput(system, parts) {
+    for (const part of parts) {
+        if (part.type === 'text' && part.text && system.includes(part.text)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function jsonResponseFormat(schema) {
+    return [{ type: 'text', mimeType: 'application/json', schema }];
+}
+export 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' };
+        camel.responseModalities = ['audio'];
+        return;
+    }
+    if (req.image) {
+        const imageEntry = {
+            type: 'image',
+            mimeType: req.image.mimeType,
+        };
+        if (req.image.aspectRatio) {
+            imageEntry.aspectRatio = req.image.aspectRatio;
+        }
+        if (req.image.size) {
+            imageEntry.imageSize = req.image.size;
+        }
+        // Post–May 2026 Interactions API: object = image-only; array = text + image.
+        camel.responseFormat = req.image.includeText ? [{ type: 'text' }, imageEntry] : imageEntry;
+        return;
+    }
+    if (!req.structured) {
+        return;
+    }
+    const spec = getStructured(req.structured);
+    if (spec.enforced !== 'responseFormat' || !spec.jsonSchema) {
+        return;
+    }
+    camel.responseFormat = jsonResponseFormat(spec.jsonSchema);
+}
+export function attachSpeechConfig(req, generationConfig) {
+    if (!req.speech) {
+        return;
+    }
+    const voice = req.speech.voice;
+    if (!voice) {
+        return;
+    }
+    generationConfig.speechConfig = [{ voice }];
+}
+function wireInteractionsFunctionTool(decl) {
+    return {
+        type: 'function',
+        name: decl.name,
+        description: decl.description,
+        parameters: decl.parameters,
+    };
+}
+function wireGoogleMapsTool(req) {
+    const loc = req.googleMapsLocation;
+    if (loc && Number.isFinite(loc.latitude) && Number.isFinite(loc.longitude)) {
+        return {
+            type: 'google_maps',
+            latitude: loc.latitude,
+            longitude: loc.longitude,
+        };
+    }
+    return { type: 'google_maps' };
+}
+function wireInteractionsTools(req) {
+    const tools = [];
+    for (const id of req.builtins) {
+        const entry = getTool(id);
+        const type = entry?.type === 'builtin' ? entry.wire.interactions : undefined;
+        if (!type) {
+            throw new TheorumError(`Builtin '${id}' has no Interactions wire type`);
+        }
+        if (type === 'google_maps') {
+            tools.push(wireGoogleMapsTool(req));
+            continue;
+        }
+        tools.push({ type });
+    }
+    for (const decl of req.wireTools ?? []) {
+        tools.push(wireInteractionsFunctionTool(decl));
+    }
+    return tools;
+}
+export function inputStepsFromRequest(req) {
+    if (req.interactionOnlyInput && req.interactionOnlyInput.length > 0) {
+        return req.interactionOnlyInput;
+    }
+    const inputSteps = [];
+    for (const h of req.history ?? []) {
+        inputSteps.push(...historySteps(h));
+    }
+    if (req.input.length > 0 || inputSteps.length === 0) {
+        inputSteps.push(userInputStep(req.input));
+    }
+    return inputSteps;
+}
+export function applyOptionalRequestFields(req, camel) {
+    if (req.store !== undefined) {
+        camel.store = req.store;
+    }
+    if (req.previousInteractionId) {
+        camel.previousInteractionId = req.previousInteractionId;
+    }
+    if (req.system) {
+        if (systemHoldsUserInput(req.system, req.input)) {
+            throw new TheorumError('User payload must not be copied into system instructions');
+        }
+        camel.systemInstruction = req.system;
+    }
+    const tools = wireInteractionsTools(req);
+    if (tools.length > 0) {
+        camel.tools = tools;
+    }
+}
+export function baseInteractionsBody(req) {
+    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 {
+        if (req.thinking) {
+            generationConfig.thinkingLevel = req.thinking;
+        }
+        if (req.summaries) {
+            generationConfig.thinkingSummaries = req.summaries;
+        }
+    }
+    return {
+        model: req.apiId,
+        stream: req.stream ?? true,
+        input: inputStepsFromRequest(req),
+        generationConfig,
+    };
+}
+/** Compatibility wrapper for callers that need the complete wire body. */
+export function toInteractionsBody(req) {
+    const body = baseInteractionsBody(req);
+    attachResponseFormat(req, body);
+    applyOptionalRequestFields(req, body);
+    return toGoogleValue(body);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Google Interactions provider module.
+ *
+ * @module
+ */
+export { camelToSnake, toInteractionsBody } from './framing.js';
+export { createInteractionsProvider } from './stream.js';

package/esm/src/providers/google/interactions/mod.js

@@ -0,0 +1,7 @@
+/**
+ * Google Interactions provider module.
+ *
+ * @module
+ */
+export { camelToSnake, toInteractionsBody } from './framing.js';
+export { createInteractionsProvider } from './stream.js';

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

@@ -0,0 +1,83 @@
+/**
+ * Google Interactions provider adapter.
+ *
+ * This adapter converts THEORUM's provider-neutral request into the Google
+ * Interactions wire format and streams normalized `TurnEvent` objects.
+ * Speech-role turns use `response_format: audio` + `speech_config` (same
+ * transport as chat/image).
+ *
+ * @module
+ */
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../../../kernel/types.js';
+import { type ParsedToolArguments } from '../../shared/tool-args.js';
+import { type GeminiTransport } from '../keys.js';
+export interface PendingFunctionCall {
+    id?: string;
+    name?: string;
+    arguments: string;
+}
+export interface StreamFold {
+    text: string;
+    functionCalls: Map<number, PendingFunctionCall>;
+    emittedToolKeys: Set<string>;
+    emittedEvidenceKeys: Set<string>;
+    codeSteps: Map<number, Record<string, unknown>>;
+    sawStreamedMedia: boolean;
+}
+export declare function isRawPcmMime(mime: string): boolean;
+export declare function normalizeSpeechMedia(event: TurnEvent, speech: boolean): TurnEvent;
+export declare function newStreamFold(): StreamFold;
+export declare function eventType(payload: Record<string, unknown>): string;
+export declare function isDeltaEvent(type: string): boolean;
+export declare function isCompleteEvent(type: string): boolean;
+export declare function yieldGrounding(event: Record<string, unknown>): Generator<TurnEvent>;
+export declare function yieldTokens(event: Record<string, unknown>): Generator<TurnEvent>;
+export declare function functionCallKey(tool: {
+    name?: string;
+    id?: string;
+    arguments?: Record<string, unknown>;
+}): string;
+export declare function yieldEvidenceStep(step: Record<string, unknown>, emittedKeys: Set<string>): Generator<TurnEvent>;
+export declare function isCompleteCodeStep(step: Record<string, unknown>): boolean;
+export declare function foldStepStart(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export type { ParsedToolArguments };
+export declare function parseArgumentsObject(raw: unknown): ParsedToolArguments;
+export declare function emitUniqueToolEvent(tool: {
+    id?: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    phase?: 'error';
+    failure?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}, fold: StreamFold): TurnEvent[];
+/** Emit a tool call, or a structured tool failure when arguments cannot be parsed. */
+export declare function emitToolCallFromRawArguments(tool: {
+    id?: string;
+    name: string;
+}, rawArguments: unknown, fold: StreamFold): TurnEvent[];
+export declare function foldArgumentsDelta(delta: Record<string, unknown>, index: number, fold: StreamFold): void;
+export declare function foldFunctionCallDelta(delta: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldDeltaPayload(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function readData(part: Record<string, unknown>): string | undefined;
+export declare function readMime(part: Record<string, unknown>): string | undefined;
+export declare function yieldMediaChunk(part: Record<string, unknown>): Generator<TurnEvent>;
+export declare function scanMediaParts(content: unknown): Generator<TurnEvent>;
+export declare function emitPendingFunctionCall(index: number, fold: StreamFold): TurnEvent[];
+export declare function foldStepStop(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldInteractionSteps(interaction: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldCompleteEvents(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldPayload(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function finalizeStructured(req: ProviderCompleteRequest, fold: StreamFold): Generator<TurnEvent>;
+export declare function scanInteractionsMedia(json: Record<string, unknown>): Generator<TurnEvent>;
+export declare function isVoiceProfile(req: ProviderCompleteRequest): boolean;
+export declare function shouldReportMissingSpeechAudio(req: ProviderCompleteRequest, fold: StreamFold): boolean;
+/** Speech-role turns must receive real audio; never invent PCM from text bytes. */
+export declare function missingSpeechAudioError(): Generator<TurnEvent>;
+export declare function readApiErrorMessage(record: Record<string, unknown>): string | null;
+export declare function readNonOkErrorMessage(response: Response): Promise<string>;
+export declare function withTap(req: ProviderCompleteRequest, transport: GeminiTransport): GeminiTransport;
+/** Create a `ModelProvider` backed by Google Interactions HTTP / SSE. */
+export declare function createInteractionsProvider(transport: GeminiTransport): ModelProvider;