theorum 0.1.14 → 1.0.0

package/esm/src/providers/{local.js → local/local.js}

@@ -5,14 +5,19 @@
  * Streams SSE from `/v1/chat/completions`, accumulates tool calls, and yields
  * normalized `TurnEvent` objects. No external SDK dependency — raw fetch + SSE.
  *
+ * Wire-format message building delegates to the shared `openai/compat` module.
+ * SSE parsing delegates to the shared `parseSseStream` from `sse.ts`.
+ *
  * Hosts pass `baseUrl` explicitly. THEORUM does not read `OLLAMA_HOST` or other
- * environment variables (see src/providers/CONTRACT.md).
+ * environment variables (see docs/contracts/providers.md).
  *
  * @module
  */
-import { isAbortError, toErrorEvent } from '../guardrails/error.js';
-import { turnStopFromOpenRouter } from '../kernel/stop.js';
-import { exposeForTests } from './expose-for-tests.js';
+import { isAbortError, toErrorEvent } from '../../guardrails/error.js';
+import { turnStopFromOpenAiFinishReason } from '../../kernel/stop.js';
+import { buildChatMessages, wireTools } from '../openrouter/openai/compat.js';
+import { parseSseStream } from '../shared/sse.js';
+import { parseToolArgumentsObject } from '../shared/tool-args.js';
 /** Default OpenAI-compat base when the host omits `baseUrl` (Ollama's default port). */
 export const DEFAULT_LOCAL_BASE_URL = 'http://127.0.0.1:11434';
 // ── request mapping ─────────────────────────────────
@@ -22,132 +27,48 @@ function normalizeBaseUrl(baseUrl) {
         end -= 1;
     return baseUrl.slice(0, end);
 }
-function resolveBaseUrl(config) {
+export function resolveBaseUrl(config) {
     return normalizeBaseUrl(config?.baseUrl?.trim() || DEFAULT_LOCAL_BASE_URL);
 }
-function inputToContent(parts) {
-    if (parts.every((p) => p.type === 'text')) {
-        return parts.map((p) => ('text' in p ? p.text : '')).join('\n');
-    }
-    return parts.map((p) => {
-        if (p.type === 'text')
-            return { type: 'text', text: p.text };
-        return {
-            type: 'image_url',
-            image_url: { url: `data:${p.mimeType};base64,${p.data}` },
-        };
-    });
-}
-function historyMessageContent(msg) {
-    if (msg.parts && msg.parts.length > 0) {
-        return inputToContent(msg.parts);
-    }
-    if (msg.content != null)
-        return msg.content;
-    return undefined;
-}
-function historyToWire(req) {
-    const msgs = [];
-    if (req.system)
-        msgs.push({ role: 'system', content: req.system });
-    for (const msg of req.history ?? []) {
-        msgs.push(historyMessageToWire(msg));
-    }
-    if (req.input.length > 0) {
-        msgs.push({ role: 'user', content: inputToContent(req.input) });
-    }
-    return msgs;
-}
-function historyMessageToWire(msg) {
-    if (msg.role === 'tool') {
-        return {
-            role: 'tool',
-            tool_call_id: msg.tool_call_id ?? `call_${msg.name ?? 'tool'}`,
-            name: msg.name,
-            content: msg.content ?? '',
-        };
-    }
-    if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
-        return {
-            role: 'assistant',
-            content: historyMessageContent(msg) ?? undefined,
-            tool_calls: msg.tool_calls.map((tc) => ({
-                id: tc.id,
-                type: 'function',
-                function: { name: tc.function.name, arguments: tc.function.arguments },
-            })),
-        };
-    }
-    return { role: msg.role, content: historyMessageContent(msg) ?? '' };
-}
-function toolsToWire(dynamicTools) {
-    if (!dynamicTools || dynamicTools.length === 0)
-        return undefined;
-    return dynamicTools.map((t) => ({
-        type: 'function',
-        function: {
-            name: t.name,
-            description: t.description ?? '',
-            parameters: t.parameters ?? { type: 'object', properties: {} },
-        },
-    }));
-}
 function buildBody(req) {
     const body = {
         model: req.apiId,
-        messages: historyToWire(req),
+        messages: buildChatMessages(req),
         stream: true,
         stream_options: { include_usage: true },
         temperature: req.temperature,
         max_tokens: req.maxOutputTokens,
     };
-    const tools = toolsToWire(req.dynamicTools);
+    const tools = wireTools(req.wireTools);
     if (tools)
         body.tools = tools;
     return body;
 }
-// ── SSE parsing ─────────────────────────────────────
-async function* parseSse(body) {
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = '';
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split('\n');
-        buffer = lines.pop() ?? '';
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed.startsWith('data: '))
-                continue;
-            const data = trimmed.slice(6);
-            if (data === '[DONE]')
-                return;
-            try {
-                yield JSON.parse(data);
-            }
-            catch {
-                // skip malformed
-            }
-        }
-    }
-}
 // ── stream → TurnEvent ──────────────────────────────
-function flushPending(pending) {
+export function flushPending(pending) {
     const events = [];
     for (const [, tc] of pending) {
-        let parsed = {};
-        try {
-            parsed = JSON.parse(tc.args);
-        }
-        catch {
-            // empty
+        const parsed = parseToolArgumentsObject(tc.args);
+        if (!parsed.ok) {
+            events.push({
+                type: 'tool',
+                tool: {
+                    name: tc.name,
+                    arguments: {},
+                    id: tc.id,
+                    phase: 'error',
+                    failure: {
+                        code: 'malformed_arguments',
+                        message: parsed.error,
+                        details: { raw: parsed.raw },
+                    },
+                },
+            });
+            continue;
         }
         events.push({
             type: 'tool',
-            tool: { name: tc.name, arguments: parsed, id: tc.id },
+            tool: { name: tc.name, arguments: parsed.value, id: tc.id },
         });
     }
     pending.clear();
@@ -174,11 +95,11 @@ async function* streamComplete(baseUrl, req, fetchFn) {
 async function* streamOpenAiBody(body) {
     const pending = new Map();
     let finishReason;
-    for await (const chunk of parseSse(body)) {
-        const usageEvent = tokensFromUsage(chunk.usage);
+    for await (const raw of parseSseStream(body)) {
+        const usageEvent = tokensFromUsage(readOpenAiUsage(raw));
         if (usageEvent)
             yield usageEvent;
-        const choice = chunk.choices?.[0];
+        const choice = firstOpenAiChoice(raw);
         if (!choice)
             continue;
         yield* eventsFromChoiceDelta(choice.delta, pending);
@@ -190,7 +111,37 @@ async function* streamOpenAiBody(body) {
     }
     for (const event of flushPending(pending))
         yield event;
-    yield { type: 'done', stop: turnStopFromOpenRouter(finishReason) };
+    yield { type: 'done', stop: turnStopFromOpenAiFinishReason(finishReason) };
+}
+function readOpenAiUsage(raw) {
+    const usage = raw.usage;
+    if (!usage || typeof usage !== 'object' || Array.isArray(usage))
+        return undefined;
+    const row = usage;
+    return {
+        prompt_tokens: typeof row.prompt_tokens === 'number' ? row.prompt_tokens : undefined,
+        completion_tokens: typeof row.completion_tokens === 'number' ? row.completion_tokens : undefined,
+        total_tokens: typeof row.total_tokens === 'number' ? row.total_tokens : undefined,
+    };
+}
+function firstOpenAiChoice(raw) {
+    if (!Array.isArray(raw.choices) || raw.choices.length === 0)
+        return undefined;
+    const choice = raw.choices[0];
+    if (!choice || typeof choice !== 'object' || Array.isArray(choice))
+        return undefined;
+    const row = choice;
+    const deltaRaw = row.delta;
+    const delta = deltaRaw && typeof deltaRaw === 'object' && !Array.isArray(deltaRaw)
+        ? deltaRaw
+        : undefined;
+    return {
+        index: typeof row.index === 'number' ? row.index : 0,
+        delta,
+        finish_reason: typeof row.finish_reason === 'string' || row.finish_reason === null
+            ? row.finish_reason
+            : undefined,
+    };
 }
 function tokensFromUsage(usage) {
     if (!usage)
@@ -245,15 +196,4 @@ function createLocalProvider(config) {
         },
     };
 }
-export { createLocalProvider };
-exposeForTests('local', {
-    inputToContent,
-    historyMessageContent,
-    historyToWire,
-    toolsToWire,
-    buildBody,
-    parseSse,
-    flushPending,
-    resolveBaseUrl,
-    DEFAULT_LOCAL_BASE_URL,
-});
+export { buildChatMessages as historyToWire, createLocalProvider, wireTools as toolsToWire };

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

@@ -0,0 +1,9 @@
+/**
+ * Direct entry for local OpenAI-compat providers (Ollama, vLLM, etc.).
+ * Importing this module loads the local adapter graph — prefer `createProvider`
+ * when routing from a profile unless you intentionally bypass the factory.
+ *
+ * @module
+ */
+import "../../../_dnt.polyfills.js";
+export { createLocalProvider, DEFAULT_LOCAL_BASE_URL } from './local.js';

package/esm/src/providers/local/mod.js

@@ -0,0 +1,9 @@
+/**
+ * Direct entry for local OpenAI-compat providers (Ollama, vLLM, etc.).
+ * Importing this module loads the local adapter graph — prefer `createProvider`
+ * when routing from a profile unless you intentionally bypass the factory.
+ *
+ * @module
+ */
+import "../../../_dnt.polyfills.js";
+export { createLocalProvider, DEFAULT_LOCAL_BASE_URL } from './local.js';

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

@@ -4,11 +4,14 @@
  * Host apps should use `createProvider(profile, options)` — the single door.
  * Credentials are always supplied by the host application.
  *
+ * For direct local adapter access (bypassing the factory), import
+ * `@theorum/core/providers/local`.
+ *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export type { KeyVault } from '../kernel/types.js';
 export type { CreateProviderOptions } from './create-provider.js';
 export { createProvider } from './create-provider.js';
-export type { GeminiTransport, GeminiVault } from './keys.js';
-export type { LocalProviderConfig } from './local.js';
-export { createLocalProvider, DEFAULT_LOCAL_BASE_URL } from './local.js';
+export type { GeminiTransport } from './google/keys.js';
+export type { LocalProviderConfig, OpenAiGatewayConfig } from './types.js';

package/esm/src/providers/mod.js

@@ -4,8 +4,10 @@
  * Host apps should use `createProvider(profile, options)` — the single door.
  * Credentials are always supplied by the host application.
  *
+ * For direct local adapter access (bypassing the factory), import
+ * `@theorum/core/providers/local`.
+ *
  * @module
  */
 import "../../_dnt.polyfills.js";
 export { createProvider } from './create-provider.js';
-export { createLocalProvider, DEFAULT_LOCAL_BASE_URL } from './local.js';

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

@@ -0,0 +1,87 @@
+/**
+ * OpenRouter provider adapter powered by Vercel AI SDK Core.
+ *
+ * THEORUM keeps the public `ModelProvider` and `TurnEvent` contract; AI SDK
+ * owns the OpenRouter call, stream parsing, provider compatibility, and tool
+ * call normalization. Message assembly delegates to `openai/sdk-messages.ts`.
+ *
+ * @module
+ */
+import { type TextStreamPart, type ToolSet } from 'ai';
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent, TurnTokens, WireFunctionTool } from '../../kernel/types.js';
+import type { OpenAiGatewayConfig } from '../types.js';
+export interface StreamAccumulator {
+    text: string;
+    evidenceSeen: boolean;
+    emittedTokens: boolean;
+    errored: boolean;
+    finishReason?: string | null;
+    nativeFinishReason?: string | null;
+}
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type ProviderOptions = Record<string, {
+    [key: string]: JsonValue;
+}>;
+export declare function trimApiKey(explicitKey?: string): string | undefined;
+export declare function createAccumulator(): StreamAccumulator;
+export declare function sourceEvent(part: {
+    sourceType?: string;
+    title?: string | null;
+    url?: string;
+}): TurnEvent;
+export declare function schemaForTool(decl: WireFunctionTool): Record<string, unknown>;
+export declare function buildTools(wireTools?: WireFunctionTool[]): ToolSet | undefined;
+export declare function tokensFromUsage(usage: {
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    totalTokens?: number | null;
+}): TurnTokens | undefined;
+export declare function rawRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function stringArray(value: unknown): string[] | undefined;
+export declare function metadataRecord(raw: Record<string, unknown>, key: string): Record<string, unknown> | undefined;
+export declare function citationCandidates(raw: Record<string, unknown>): unknown[];
+export declare function nestedCitations(raw: Record<string, unknown>): string[] | undefined;
+export declare function metadataAnnotations(raw: Record<string, unknown>): unknown[] | undefined;
+export declare function evidenceFromMetadata(metadata: unknown, acc: StreamAccumulator): TurnEvent | undefined;
+export declare function toolArguments(input: unknown): Record<string, unknown> | undefined;
+export declare function toolResultData(output: unknown): Record<string, unknown> | undefined;
+export declare function rawThoughtEvent(raw: Record<string, unknown>): TurnEvent | undefined;
+export declare function rawChoiceMessageEvidence(raw: Record<string, unknown>, acc: StreamAccumulator): TurnEvent | undefined;
+export declare function rawEvents(raw: unknown, acc: StreamAccumulator): TurnEvent[];
+export declare function toolCallEvent(part: {
+    toolName: string;
+    toolCallId: string;
+    input?: unknown;
+}): TurnEvent;
+export declare function toolResultEvent(part: {
+    toolName: string;
+    toolCallId: string;
+    input?: unknown;
+    output?: unknown;
+}): TurnEvent;
+export declare function tokenEvent(part: {
+    totalUsage: {
+        inputTokens?: number | null;
+        outputTokens?: number | null;
+        totalTokens?: number | null;
+    };
+}): TurnEvent | undefined;
+export declare function providerMetadataEvent(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): TurnEvent | undefined;
+export declare function eventFromPart(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): TurnEvent[];
+export declare function primaryEventFromPart(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): TurnEvent | undefined;
+export declare function finishEvent(part: {
+    finishReason?: string | null;
+    totalUsage?: {
+        inputTokens?: number | null;
+        outputTokens?: number | null;
+        totalTokens?: number | null;
+    };
+}, acc: StreamAccumulator): TurnEvent | undefined;
+export declare function finalEvents(req: ProviderCompleteRequest, acc: StreamAccumulator): Generator<TurnEvent>;
+export declare function missingOpenRouterKey(): TurnEvent;
+export declare function providerOptionsFor(req: ProviderCompleteRequest): ProviderOptions | undefined;
+/** Create a `ModelProvider` backed by OpenRouter through AI SDK Core. */
+export declare function createOpenRouterProvider(config?: OpenAiGatewayConfig): ModelProvider;
+export type { OpenAiGatewayConfig };