@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,186 @@
+import { isAbortError, kindOfHttpStatus, TheoremError, toErrorEvent, } from '../../guardrails/error.js';
+import { asRecord } from '../../kernel/engine/record.js';
+import { turnStopFromOpenAiFinishReason } from '../../kernel/stop.js';
+import { buildChatMessages, wireTools } from '../openrouter/openai/compat.js';
+import { openAiResponse, openAiUsageTokens } from '../openrouter/openai/usage.js';
+import { foldResponse } from '../shared/response-identity.js';
+import { parseSseStream } from '../shared/sse.js';
+import { toolCallEvents } from '../shared/tool-args.js';
+import { networkFetch, tapFetch } from '../shared/upstream-tap.js';
+import { bearerFetch, requireKey } from '../shared/vault.js';
+function normalizeBaseUrl(baseUrl) {
+    let end = baseUrl.length;
+    while (end > 0 && baseUrl.charCodeAt(end - 1) === 47)
+        end -= 1;
+    return baseUrl.slice(0, end);
+}
+export function resolveBaseUrl(config) {
+    const baseUrl = config.baseUrl.trim();
+    if (!baseUrl) {
+        throw new TheoremError('config', 'Local provider requires baseUrl'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return normalizeBaseUrl(baseUrl);
+}
+function buildBody(req) {
+    const body = {
+        model: req.apiId,
+        messages: buildChatMessages(req),
+        stream: req.stream !== false,
+        temperature: req.temperature,
+        max_tokens: req.maxOutputTokens,
+    };
+    if (body.stream)
+        body.stream_options = { include_usage: true };
+    const tools = wireTools(req.wireTools);
+    if (tools)
+        body.tools = tools;
+    return body;
+}
+export function flushPending(pending) {
+    const events = [...pending.values()].flatMap((tc) => toolCallEvents(tc, tc.args));
+    pending.clear();
+    return events;
+}
+/** A local server takes no key unless the model names a slot; then the key goes as a bearer token. */
+function localFetch(req, config) {
+    const fetchFn = networkFetch(config.fetch ?? globalThis.fetch);
+    if (!req.keySlot)
+        return { send: tapFetch(req.tapUpstream, fetchFn), headers: {} };
+    const key = requireKey(config.vault, req.keySlot);
+    return {
+        send: bearerFetch(req, fetchFn, config.vault, key),
+        headers: { Authorization: `Bearer ${key}` },
+    };
+}
+async function* streamComplete(baseUrl, req, config) {
+    const { send, headers } = localFetch(req, config);
+    const res = await send(`${baseUrl}/v1/chat/completions`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...headers },
+        body: JSON.stringify(buildBody(req)),
+        signal: req.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        yield toErrorEvent(new TheoremError(kindOfHttpStatus(res.status), `LLM HTTP ${res.status}: ${text}`));
+        return;
+    }
+    if (req.stream === false) {
+        yield* bufferedOpenAiBody(await res.json(), req.tapUpstream);
+        return;
+    }
+    if (!res.body) {
+        yield toErrorEvent(new TheoremError('bad_response', 'empty response body'));
+        return;
+    }
+    yield* streamOpenAiBody(res.body, req.tapUpstream);
+}
+function* bufferedOpenAiBody(raw, tap) {
+    tap?.(raw);
+    const identity = foldResponse(undefined, openAiResponse(raw));
+    if (identity.event)
+        yield identity.event;
+    const tokens = openAiUsageTokens(raw.usage);
+    if (tokens)
+        yield { type: 'tokens', tokens };
+    const choice = Array.isArray(raw.choices) ? asRecord(raw.choices[0]) : undefined;
+    const message = asRecord(choice?.message);
+    if (message?.content)
+        yield { type: 'text', text: message.content };
+    for (const [index, call] of (message?.tool_calls ?? []).entries()) {
+        yield* toolCallEvents({ id: call.id ?? `call_${index}`, name: call.function?.name ?? '' }, call.function?.arguments ?? '');
+    }
+    const finish = choice?.finish_reason;
+    yield {
+        type: 'done',
+        stop: turnStopFromOpenAiFinishReason(typeof finish === 'string' ? finish : null),
+    };
+}
+async function* streamOpenAiBody(body, tap) {
+    const pending = new Map();
+    let finishReason;
+    let response;
+    for await (const raw of parseSseStream(body)) {
+        tap?.(raw);
+        const identity = foldResponse(response, openAiResponse(raw));
+        response = identity.known;
+        if (identity.event)
+            yield identity.event;
+        const tokens = openAiUsageTokens(raw.usage);
+        if (tokens)
+            yield { type: 'tokens', tokens };
+        const choice = firstOpenAiChoice(raw);
+        if (!choice)
+            continue;
+        yield* eventsFromChoiceDelta(choice.delta, pending);
+        if (choice.finish_reason != null) {
+            finishReason = choice.finish_reason;
+            for (const event of flushPending(pending))
+                yield event;
+        }
+    }
+    for (const event of flushPending(pending))
+        yield event;
+    yield {
+        type: 'done',
+        stop: turnStopFromOpenAiFinishReason(finishReason),
+    };
+}
+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* eventsFromChoiceDelta(delta, pending) {
+    if (!delta)
+        return;
+    if (delta.content)
+        yield { type: 'text', text: delta.content };
+    accumulateToolCalls(delta.tool_calls, pending);
+}
+function accumulateToolCalls(toolCalls, pending) {
+    if (!toolCalls)
+        return;
+    for (const tc of toolCalls) {
+        const existing = pending.get(tc.index);
+        if (existing) {
+            existing.args += tc.function?.arguments ?? '';
+            continue;
+        }
+        pending.set(tc.index, {
+            id: tc.id ?? `call_${tc.index}`,
+            name: tc.function?.name ?? '',
+            args: tc.function?.arguments ?? '',
+        });
+    }
+}
+function createLocalProvider(config) {
+    const baseUrl = resolveBaseUrl(config);
+    return {
+        async *complete(req) {
+            try {
+                yield* streamComplete(baseUrl, req, config);
+            }
+            catch (err) {
+                if (isAbortError(err))
+                    throw err;
+                yield toErrorEvent(err);
+            }
+        },
+    };
+}
+export { buildChatMessages as historyToWire, createLocalProvider, wireTools as toolsToWire };

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

@@ -0,0 +1,8 @@
+/**
+ * Direct entry for local OpenAI-compatible servers, bypassing `createProvider`.
+ * Importing it loads the local adapter eagerly.
+ *
+ * @module
+ */
+import "../../../_dnt.polyfills.js";
+export { createLocalProvider } from './local.js';

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

@@ -0,0 +1,8 @@
+/**
+ * Direct entry for local OpenAI-compatible servers, bypassing `createProvider`.
+ * Importing it loads the local adapter eagerly.
+ *
+ * @module
+ */
+import "../../../_dnt.polyfills.js";
+export { createLocalProvider } from './local.js';

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

@@ -0,0 +1,11 @@
+/**
+ * `createProvider(profile, options)` binds a profile to a transport with host-supplied credentials.
+ *
+ * @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 { GeminiOptions } from './google/keys.js';
+export type { LocalProviderConfig, OpenAiGatewayConfig } from './types.js';

package/esm/src/providers/mod.js

@@ -0,0 +1,7 @@
+/**
+ * `createProvider(profile, options)` binds a profile to a transport with host-supplied credentials.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { createProvider } from './create-provider.js';

package/esm/src/providers/openrouter/cache-control.d.ts

@@ -0,0 +1,5 @@
+import type { CacheSpec } from '../../kernel/types.js';
+/** Index-signature return type: AI SDK `providerOptions` takes only plain JSON objects. */
+export declare function cacheControlJson(spec: CacheSpec): {
+    [key: string]: string;
+};

package/esm/src/providers/openrouter/cache-control.js

@@ -0,0 +1,4 @@
+/** Index-signature return type: AI SDK `providerOptions` takes only plain JSON objects. */
+export function cacheControlJson(spec) {
+    return spec.ttl ? { type: 'ephemeral', ttl: spec.ttl } : { type: 'ephemeral' };
+}

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

@@ -0,0 +1,64 @@
+import { type LanguageModelUsage, type ModelMessage, type TextStreamPart, type ToolSet } from 'ai';
+import type { ModelProvider, ProviderCompleteRequest, ProviderEvent, TurnResponse, TurnTokens, WireFunctionTool } from '../../kernel/types.js';
+import type { OpenAiGatewayTransport } from '../types.js';
+export interface StreamAccumulator {
+    text: string;
+    /** URIs this call has cited: a source cites once, whichever channel names it first. */
+    citedUris: Set<string>;
+    /** Other annotations reported, by their JSON: raw rows and the SDK's metadata repeat them. */
+    reportedAnnotations: Set<string>;
+    emittedTokens: boolean;
+    errored: boolean;
+    finishReason?: string | null;
+    nativeFinishReason?: string | null;
+    response?: TurnResponse;
+}
+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 type SourcePart = Extract<TextStreamPart<ToolSet>, {
+    type: 'source';
+}>;
+export declare function sourceEvent(part: SourcePart, acc: StreamAccumulator): ProviderEvent | undefined;
+export declare function schemaForTool(decl: WireFunctionTool): Record<string, unknown>;
+export declare function buildTools(wireTools?: WireFunctionTool[]): ToolSet | undefined;
+/** Only when the raw stream carried no `usage` row; `rawEvents` reads that one first, with cost. */
+export declare function tokensFromUsage(usage: LanguageModelUsage): TurnTokens | 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;
+/** Each citation or annotation reports once per call, however many rows repeat it. */
+export declare function eventsFromMetadata(metadata: unknown, acc: StreamAccumulator): ProviderEvent[];
+export declare function rawThoughtEvent(raw: Record<string, unknown>): ProviderEvent | undefined;
+export declare function rawChoiceMessageEvents(raw: Record<string, unknown>, acc: StreamAccumulator): ProviderEvent[];
+export declare function rawEvents(raw: unknown, acc: StreamAccumulator): ProviderEvent[];
+export type ToolCallPart = Extract<TextStreamPart<ToolSet>, {
+    type: 'tool-call';
+}>;
+/** A call the SDK could not parse or match is the call with no arguments, then its failure. */
+export declare function toolCallPartEvents(part: ToolCallPart): ProviderEvent[];
+export declare function tokenEvent(part: {
+    totalUsage: LanguageModelUsage;
+}): ProviderEvent | undefined;
+export declare function providerMetadataEvents(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): ProviderEvent[];
+export declare function eventFromPart(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): ProviderEvent[];
+export declare function primaryEventsFromPart(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): ProviderEvent[];
+export declare function finishEvent(part: {
+    finishReason?: string | null;
+    totalUsage?: LanguageModelUsage;
+}, acc: StreamAccumulator): ProviderEvent | undefined;
+export declare function finalEvents(req: ProviderCompleteRequest, acc: StreamAccumulator): Generator<ProviderEvent>;
+/** System via instructions XOR a cache-marked system message — never both. */
+export declare function systemDelivery(req: ProviderCompleteRequest): {
+    instructions?: string;
+    systemMessage?: ModelMessage;
+};
+export declare function providerOptionsFor(req: ProviderCompleteRequest): ProviderOptions | undefined;
+export declare function createOpenRouterProvider(config?: OpenAiGatewayTransport): ModelProvider;