@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/providers/create-provider.js

@@ -0,0 +1,90 @@
+import { TheoremError } from '../guardrails/error.js';
+import { requireModelProfile } from '../kernel/registry/resolve.js';
+import { isValidPair } from '../kernel/schema.js';
+import { markModuleLoad } from './probe.js';
+export function isSpeechRole(profile) {
+    return profile.type === 'speech';
+}
+export function isImageRole(profile) {
+    return profile.type === 'image';
+}
+function bindingForProvider(input, modelId) {
+    const profile = requireModelProfile(input, 'createProvider');
+    const id = modelId ?? profile.defaultModel;
+    const binding = profile.models[id];
+    if (!binding) {
+        throw new TheoremError('config', `createProvider: profile '${profile.id}' has no model '${id}'`);
+    }
+    return binding;
+}
+/**
+ * Lazy-load an adapter on first `complete`. When `THEOREM_IMPORT_PROBE=1`,
+ * emits `LOADED:<label>` exactly once at load time (import-isolation tests).
+ */
+function lazyAdapter(label, load) {
+    let pending;
+    return {
+        async *complete(req) {
+            pending ??= (async () => {
+                markModuleLoad(label);
+                return await load();
+            })();
+            yield* (await pending).complete(req);
+        },
+    };
+}
+function lazyOpenRouterChat(config) {
+    return lazyAdapter('openrouter-chat', () => import('./openrouter/chat.js').then((m) => m.createOpenRouterProvider(config)));
+}
+function lazyGoogleInteractions(config) {
+    return lazyAdapter('google-interactions-adapter', () => import('./google/interactions/mod.js').then((m) => m.createInteractionsProvider(config)));
+}
+function lazySpeech(config) {
+    return lazyAdapter('openrouter-speech', () => import('./openrouter/speech.js').then((m) => m.createSpeechProvider(config)));
+}
+function lazyImage(config) {
+    return lazyAdapter('openrouter-image', () => import('./openrouter/image.js').then((m) => m.createImageProvider(config)));
+}
+function lazyLocal(config) {
+    return lazyAdapter('local-adapter', () => import('./local/local.js').then((m) => m.createLocalProvider(config)));
+}
+/** Live profiles use `runSession`. `modelId` picks the binding; default `defaultModel`. */
+export function createProvider(profile, options = {}, modelId) {
+    const { protocol, provider } = bindingForProvider(profile, modelId);
+    if (!isValidPair(protocol, provider)) {
+        throw new TheoremError('config', `createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
+    }
+    if (protocol === 'geminiInteractions' && provider === 'google') {
+        if (!options.vault) {
+            throw new TheoremError('config', 'createProvider requires a vault for google models');
+        }
+        return lazyGoogleInteractions({ ...options.gemini, vault: options.vault });
+    }
+    if (protocol === 'geminiLive' && provider === 'google') {
+        throw new TheoremError('request', "createProvider does not support type 'live' / geminiLive — use runSession(req, { vault })");
+    }
+    if (protocol === 'openAi' && provider === 'openrouter') {
+        if (!options.vault) {
+            throw new TheoremError('config', 'createProvider requires a vault for openrouter models');
+        }
+        const gateway = { ...options.openAiGateway, vault: options.vault };
+        if (isSpeechRole(profile)) {
+            return lazySpeech(gateway);
+        }
+        if (isImageRole(profile)) {
+            return lazyImage(gateway);
+        }
+        return lazyOpenRouterChat(gateway);
+    }
+    if (protocol === 'openAi' && provider === 'local') {
+        if (isImageRole(profile)) {
+            throw new TheoremError('config', 'createProvider: type image requires openrouter provider for openAi protocol');
+        }
+        // A profile can name `local`; only the host can say a local server is there to reach.
+        if (!options.local) {
+            throw new TheoremError('config', 'createProvider requires local config for openAi/local');
+        }
+        return lazyLocal({ ...options.local, vault: options.vault });
+    }
+    throw new TheoremError('config', `createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
+}

package/esm/src/providers/decision/usage.d.ts

@@ -0,0 +1,3 @@
+import type { DecisionModelBinding, DecisionResult } from '../../kernel/types.js';
+/** Provider-reported usage, with Jev's published tariff only for a direct Jev response. */
+export declare function decisionUsage(usage: unknown, binding: Pick<DecisionModelBinding, 'provider' | 'apiId'>, responseModel: string): DecisionResult['usage'];

package/esm/src/providers/decision/usage.js

@@ -0,0 +1,25 @@
+import { isRecord } from '../../kernel/util/record.js';
+import { JEV_USD_PER_MILLION_INPUT_TOKENS } from '../../presets/typesafe.js';
+/** Provider-reported usage, with Jev's published tariff only for a direct Jev response. */
+export function decisionUsage(usage, binding, responseModel) {
+    if (!isRecord(usage) ||
+        !Number.isSafeInteger(usage.input_tokens) ||
+        !Number.isSafeInteger(usage.output_tokens) ||
+        usage.input_tokens < 0 ||
+        usage.output_tokens < 0)
+        return undefined;
+    const inputTokens = usage.input_tokens;
+    const reported = typeof usage.cost === 'number' && Number.isFinite(usage.cost) && usage.cost >= 0
+        ? usage.cost
+        : undefined;
+    const directJev = binding.provider === 'typesafe' &&
+        binding.apiId.startsWith('jev-') &&
+        responseModel.startsWith('jev-');
+    const costUsd = reported ??
+        (directJev ? (inputTokens * JEV_USD_PER_MILLION_INPUT_TOKENS) / 1_000_000 : undefined);
+    return {
+        inputTokens,
+        outputTokens: usage.output_tokens,
+        ...(costUsd === undefined ? {} : { costUsd }),
+    };
+}

package/esm/src/providers/google/api-error.d.ts

@@ -0,0 +1,8 @@
+import { TheoremError } from '../../guardrails/error.js';
+/**
+ * Interactions (SSE `error` rows, non-OK bodies) and Live (error frames) both send
+ * `{ error: { code, message, status } }`; `code` is an HTTP status or a named code.
+ */
+export declare function readGeminiApiError(record: Record<string, unknown>): TheoremError | null;
+/** The kind is the HTTP status's, unless the body names a refused key. */
+export declare function readNonOkError(response: Response): Promise<TheoremError>;

package/esm/src/providers/google/api-error.js

@@ -0,0 +1,123 @@
+import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
+import { asRecord } from '../../kernel/engine/record.js';
+const HTTP_STATUS_MIN = 100;
+const HTTP_STATUS_MAX = 599;
+/**
+ * Google refuses a bad key as a 400 `INVALID_ARGUMENT`, so the status reads as
+ * a request THEOREM cannot make; the `ErrorInfo` reason is what says it is the
+ * key. An expired key carries the same reason.
+ */
+const AUTH_REASONS = new Set(['API_KEY_INVALID']);
+/** Whether an error's `details` name a key Google refused. */
+function refusesKey(details) {
+    return (Array.isArray(details) &&
+        details.some((detail) => {
+            const reason = asRecord(detail)?.reason;
+            return typeof reason === 'string' && AUTH_REASONS.has(reason);
+        }));
+}
+/**
+ * The HTTP status behind each named code Google puts on an Interactions error
+ * (https://ai.google.dev/gemini-api/docs/api-errors). A code it does not list
+ * is the snake_case name of the HTTP status, so those names are here too.
+ */
+const NAMED_CODE_STATUS = {
+    invalid_request: 400,
+    failed_precondition: 400,
+    parameter_unknown: 400,
+    authentication: 401,
+    payment_required: 402,
+    permission_denied: 403,
+    not_found: 404,
+    model_not_found: 404,
+    already_exists: 409,
+    aborted: 409,
+    out_of_range: 416,
+    rate_limit_exceeded: 429,
+    quota_exceeded: 429,
+    too_many_requests: 429,
+    api_error: 500,
+    unimplemented: 501,
+    service_unavailable: 503,
+    deadline_exceeded: 504,
+    bad_request: 400,
+    unauthorized: 401,
+    forbidden: 403,
+    method_not_allowed: 405,
+    request_timeout: 408,
+    conflict: 409,
+    payload_too_large: 413,
+    unprocessable_entity: 422,
+    internal_server_error: 500,
+    not_implemented: 501,
+    bad_gateway: 502,
+    gateway_timeout: 504,
+};
+/** Codes for a generation Google's safety filters held back. */
+const BLOCKED_CODES = new Set([
+    'safety',
+    'recitation',
+    'language',
+    'prohibited_content',
+    'spii',
+    'blocklist',
+    'image_safety',
+    'image_prohibited_content',
+    'image_recitation',
+    'image_other',
+    'content_blocked',
+]);
+/**
+ * `cancelled` (499) is the request stopped on THEOREM's side. Generation error
+ * codes (`malformed_function_call`, `no_image`, …) and any code Google adds later
+ * are `bad_response`.
+ */
+function kindOfNamedCode(code) {
+    if (code === 'cancelled')
+        return 'cancelled';
+    if (BLOCKED_CODES.has(code))
+        return 'safety';
+    const status = NAMED_CODE_STATUS[code];
+    return status === undefined ? 'bad_response' : kindOfHttpStatus(status);
+}
+/**
+ * Interactions (SSE `error` rows, non-OK bodies) and Live (error frames) both send
+ * `{ error: { code, message, status } }`; `code` is an HTTP status or a named code.
+ */
+export function readGeminiApiError(record) {
+    const error = asRecord(record.error);
+    if (!error) {
+        return null;
+    }
+    const { code, message, status, details } = error;
+    const kind = refusesKey(details)
+        ? 'auth'
+        : typeof code === 'number' && code >= HTTP_STATUS_MIN && code <= HTTP_STATUS_MAX
+            ? kindOfHttpStatus(code)
+            : typeof code === 'string'
+                ? kindOfNamedCode(code)
+                : 'bad_response';
+    if (typeof message !== 'string' || message.length === 0) {
+        return new TheoremError(kind, 'Gemini returned an error.');
+    }
+    return new TheoremError(kind, typeof status === 'string' ? `${status}: ${message}` : message);
+}
+/** The kind is the HTTP status's, unless the body names a refused key. */
+export async function readNonOkError(response) {
+    const kind = kindOfHttpStatus(response.status);
+    const text = await response.text().catch(() => '');
+    if (!text.trim()) {
+        return new TheoremError(kind, `HTTP ${response.status}`);
+    }
+    const parsed = parseRecord(text);
+    const stated = parsed ? readGeminiApiError(parsed) : null;
+    return new TheoremError(stated?.kind === 'auth' ? 'auth' : kind, stated?.message ?? `Gemini HTTP ${response.status}: ${text}`);
+}
+function parseRecord(text) {
+    try {
+        return asRecord(JSON.parse(text));
+    }
+    catch {
+        return undefined;
+    }
+}

package/esm/src/providers/google/grounding.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderEvent } from '../../kernel/types.js';
+declare function groundingFromDelta(event: Record<string, unknown>): ProviderEvent[];
+declare function groundingFromSteps(steps: unknown[]): ProviderEvent[];
+declare function groundingFromLiveMetadata(value: unknown): ProviderEvent[];
+export { groundingFromDelta, groundingFromLiveMetadata, groundingFromSteps };

package/esm/src/providers/google/grounding.js

@@ -0,0 +1,226 @@
+import { asRecord, nonEmptyString } from '../../kernel/engine/record.js';
+function groundedEvents(grounded) {
+    if (!grounded)
+        return [];
+    const { grounding, sources } = grounded;
+    return [
+        { type: 'grounding', grounding },
+        ...(sources.length > 0 ? [{ type: 'citation', sources }] : []),
+    ];
+}
+function sourceFromPlace(place) {
+    const uri = nonEmptyString(place.url);
+    if (!uri) {
+        return undefined;
+    }
+    const placeId = nonEmptyString(place.place_id);
+    return {
+        type: 'maps',
+        uri,
+        title: nonEmptyString(place.name) ?? uri,
+        ...(placeId ? { placeId } : {}),
+    };
+}
+function chunkFromMapsSource(source) {
+    return {
+        maps: {
+            title: source.title,
+            uri: source.uri,
+            ...(source.placeId ? { placeId: source.placeId } : {}),
+        },
+    };
+}
+function sourceFromWeb(web) {
+    const uri = nonEmptyString(web.uri);
+    if (!uri) {
+        return undefined;
+    }
+    return { type: 'web', uri, title: nonEmptyString(web.title) ?? uri };
+}
+function pushUniqueSource(sources, source) {
+    if (!source) {
+        return;
+    }
+    if (sources.some((item) => {
+        if (item.type !== source.type) {
+            return false;
+        }
+        if (source.placeId && item.placeId && source.placeId === item.placeId) {
+            return true;
+        }
+        return item.uri === source.uri;
+    })) {
+        return;
+    }
+    sources.push(source);
+}
+function pushUniqueChunk(chunks, chunk) {
+    const maps = asRecord(asRecord(chunk)?.maps);
+    if (!maps) {
+        chunks.push(chunk);
+        return;
+    }
+    const placeId = nonEmptyString(maps.placeId);
+    const uri = nonEmptyString(maps.uri);
+    if (chunks.some((existing) => {
+        const existingMaps = asRecord(asRecord(existing)?.maps);
+        if (!existingMaps) {
+            return false;
+        }
+        const existingId = nonEmptyString(existingMaps.placeId);
+        if (placeId && existingId && placeId === existingId) {
+            return true;
+        }
+        return Boolean(uri && nonEmptyString(existingMaps.uri) === uri);
+    })) {
+        return;
+    }
+    chunks.push(chunk);
+}
+function searchSuggestionsHtml(result) {
+    if (!Array.isArray(result)) {
+        return undefined;
+    }
+    for (const entry of result) {
+        const html = nonEmptyString(asRecord(entry)?.search_suggestions);
+        if (html) {
+            return html;
+        }
+    }
+    return undefined;
+}
+function sourceFromAnnotation(ann) {
+    const record = asRecord(ann);
+    const uri = nonEmptyString(record?.url);
+    if (!record || !uri) {
+        return undefined;
+    }
+    if (record.type === 'place_citation') {
+        const title = nonEmptyString(record.name) ?? uri;
+        const placeId = nonEmptyString(record.place_id);
+        return { type: 'maps', uri, title, ...(placeId ? { placeId } : {}) };
+    }
+    if (record.type === 'url_citation') {
+        return { type: 'web', uri, title: nonEmptyString(record.title) ?? uri };
+    }
+    return undefined;
+}
+function appendAnnotationSources(into, annotations) {
+    if (!Array.isArray(annotations)) {
+        return;
+    }
+    for (const ann of annotations) {
+        pushUniqueSource(into, sourceFromAnnotation(ann));
+    }
+}
+function appendPlaceSources(into, result) {
+    if (!Array.isArray(result)) {
+        return;
+    }
+    for (const entry of result) {
+        const places = asRecord(entry)?.places;
+        if (!Array.isArray(places)) {
+            continue;
+        }
+        for (const placeValue of places) {
+            const place = asRecord(placeValue);
+            const source = place ? sourceFromPlace(place) : undefined;
+            if (source) {
+                pushUniqueSource(into, source);
+            }
+        }
+    }
+}
+/** Maps sources also emit normalized `chunks[].maps` so hosts share one parse shape with Live. */
+function groundingFromInteractionsStep(step) {
+    const sources = [];
+    appendAnnotationSources(sources, step.annotations);
+    if (Array.isArray(step.content)) {
+        for (const block of step.content) {
+            appendAnnotationSources(sources, asRecord(block)?.annotations);
+        }
+    }
+    appendPlaceSources(sources, step.result);
+    const chunks = [];
+    for (const source of sources) {
+        if (source.type === 'maps') {
+            pushUniqueChunk(chunks, chunkFromMapsSource(source));
+        }
+    }
+    const html = searchSuggestionsHtml(step.result);
+    if (!html && sources.length === 0) {
+        return undefined;
+    }
+    return {
+        grounding: {
+            metadata: step,
+            ...(chunks.length > 0 ? { chunks } : {}),
+            ...(html ? { searchHtml: html } : {}),
+        },
+        sources,
+    };
+}
+function mergeGrounding(a, b) {
+    if (!a) {
+        return b;
+    }
+    if (!b) {
+        return a;
+    }
+    const chunks = [];
+    for (const chunk of [...(a.grounding.chunks ?? []), ...(b.grounding.chunks ?? [])]) {
+        pushUniqueChunk(chunks, chunk);
+    }
+    const sources = [...a.sources];
+    for (const source of b.sources) {
+        pushUniqueSource(sources, source);
+    }
+    const searchHtml = b.grounding.searchHtml ?? a.grounding.searchHtml;
+    const metadata = b.grounding.metadata ?? a.grounding.metadata;
+    return {
+        grounding: {
+            ...(metadata ? { metadata } : {}),
+            ...(chunks.length > 0 ? { chunks } : {}),
+            ...(searchHtml ? { searchHtml } : {}),
+        },
+        sources,
+    };
+}
+function groundingFromDelta(event) {
+    const delta = asRecord(event.delta);
+    return groundedEvents(delta ? groundingFromInteractionsStep(delta) : undefined);
+}
+function groundingFromSteps(steps) {
+    let grounded;
+    for (const stepValue of steps) {
+        const step = asRecord(stepValue);
+        if (step) {
+            grounded = mergeGrounding(grounded, groundingFromInteractionsStep(step));
+        }
+    }
+    return groundedEvents(grounded);
+}
+function groundingFromLiveMetadata(value) {
+    const metadata = asRecord(value);
+    if (!metadata) {
+        return [];
+    }
+    const chunks = Array.isArray(metadata.groundingChunks) ? metadata.groundingChunks : [];
+    const sources = [];
+    for (const chunk of chunks) {
+        const web = asRecord(asRecord(chunk)?.web);
+        if (web) {
+            pushUniqueSource(sources, sourceFromWeb(web));
+        }
+    }
+    const html = nonEmptyString(asRecord(metadata.searchEntryPoint)?.renderedContent);
+    return groundedEvents({
+        grounding: {
+            metadata,
+            ...(chunks.length > 0 ? { chunks } : {}),
+            ...(html ? { searchHtml: html } : {}),
+        },
+        sources,
+    });
+}
+export { groundingFromDelta, groundingFromLiveMetadata, groundingFromSteps };

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

@@ -0,0 +1,15 @@
+import type { InteractionPart, ProviderCompleteRequest, TurnHistoryMessage } from '../../../kernel/types.js';
+export declare function camelToSnake(key: string): string;
+export declare function toGoogleValue(value: unknown): unknown;
+export declare function wirePart(part: InteractionPart): Record<string, string>;
+export declare function userInputStep(parts: InteractionPart[]): Record<string, unknown>;
+/** Assistant `tool_calls` (often with no `content`) become `function_call` steps, never empty `model_output`. */
+export declare function historySteps(msg: TurnHistoryMessage): Record<string, unknown>[];
+export declare function historyStep(msg: TurnHistoryMessage): Record<string, unknown>;
+export declare function jsonResponseFormat(schema: Record<string, unknown>): unknown[];
+export declare function attachResponseFormat(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+export declare function attachSpeechConfig(req: ProviderCompleteRequest, generationConfig: Record<string, unknown>): void;
+export declare function inputStepsFromRequest(req: ProviderCompleteRequest): Record<string, unknown>[];
+export declare function applyOptionalRequestFields(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+export declare function baseInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
+export declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;