theorum 0.1.2 → 0.1.4

package/src/providers/create-provider.ts

@@ -0,0 +1,64 @@
+/**
+ * Host provider factory — the single public door for binding a profile to a transport.
+ *
+ * Routes from `profile.model.protocol` / `provider` (and whether the profile is
+ * a speech role). Adapters under this folder are internal implementation.
+ *
+ * @module
+ */
+
+import { TheorumError } from '../guardrails/error.ts';
+import type { ModelProvider, Profile } from '../kernel/types.ts';
+import type { GeminiTransport } from './keys.ts';
+import { createOpenRouterProvider } from './openrouter.ts';
+import type { OpenRouterConfig } from './openrouter-payload.ts';
+import { createInteractionsProvider } from './provider.ts';
+import { createSpeechProvider } from './speech.ts';
+
+/** Credentials supplied by the host when creating a provider. */
+export interface CreateProviderOptions {
+  /** Google Interactions (chat, image, and speech when protocol is geminiInteractions). */
+  gemini?: GeminiTransport;
+  /**
+   * OpenRouter-compatible credentials for `openAi` profiles.
+   * Used for chat completions or `/audio/speech` when the profile is a speech role.
+   * Optional `voice` is a fallback when `outputs.speech.voice` is omitted.
+   */
+  openRouter?: OpenRouterConfig & { voice?: string };
+}
+
+function isSpeechRole(profile: Profile): boolean {
+  return profile.outputs.speech !== undefined;
+}
+
+/**
+ * Create a `ModelProvider` for a profile.
+ * One call: protocol/provider (and speech role) pick the transport.
+ */
+export function createProvider(
+  profile: Profile,
+  options: CreateProviderOptions = {},
+): ModelProvider {
+  const { protocol, provider } = profile.model;
+
+  if (protocol === 'geminiInteractions' && provider === 'google') {
+    if (!options.gemini) {
+      throw new TheorumError('createProvider requires gemini transport for google Interactions');
+    }
+    return createInteractionsProvider(options.gemini);
+  }
+
+  if (protocol === 'openAi' && provider === 'openrouter') {
+    if (!options.openRouter) {
+      throw new TheorumError('createProvider requires openRouter config for openAi/openrouter');
+    }
+    if (isSpeechRole(profile)) {
+      return createSpeechProvider(options.openRouter);
+    }
+    return createOpenRouterProvider(options.openRouter);
+  }
+
+  throw new TheorumError(
+    `createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`,
+  );
+}

package/src/providers/gemini-tape.ts

@@ -0,0 +1,59 @@
+import { OMIT_CANARY } from '../kernel/engine/boundary.ts';
+import { sha256 } from '../kernel/engine/hash.ts';
+import { mapStrings } from '../kernel/engine/tree.ts';
+
+function isImageBlob(rec: Record<string, unknown>): boolean {
+  if (rec.type === 'image' || rec.type === 'media') {
+    return true;
+  }
+  if (typeof rec.mimeType === 'string' || typeof rec.mime_type === 'string') {
+    return true;
+  }
+  return false;
+}
+
+async function scrubEntry(
+  rec: Record<string, unknown>,
+  key: string,
+  nested: unknown,
+): Promise<[string, unknown]> {
+  if (key === 'data' && typeof nested === 'string' && isImageBlob(rec)) {
+    return [key, await sha256(nested)];
+  }
+  return [key, await scrubGemini(nested)];
+}
+
+function scrubRecord(rec: Record<string, unknown>): Promise<Record<string, unknown>> {
+  return Promise.all(Object.entries(rec).map(([key, nested]) => scrubEntry(rec, key, nested))).then(
+    (pairs) => {
+      const out = Object.fromEntries(pairs);
+      if (typeof rec.data === 'string' && isImageBlob(rec)) {
+        out.dataKind = 'sha256';
+      }
+      return out;
+    },
+  );
+}
+
+function scrubGemini(value: unknown): Promise<unknown> {
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((item) => scrubGemini(item)));
+  }
+  if (value && typeof value === 'object') {
+    return scrubRecord(value as Record<string, unknown>);
+  }
+  return Promise.resolve(value);
+}
+
+function redactCanaryInTree(value: unknown, canary: string): unknown {
+  if (!canary) {
+    return value;
+  }
+  return mapStrings(value, (text) => text.replaceAll(canary, OMIT_CANARY));
+}
+
+async function tapeGemini(value: unknown, canary: string): Promise<unknown> {
+  return redactCanaryInTree(await scrubGemini(value), canary);
+}
+
+export { tapeGemini };

package/src/providers/google-tap.ts

@@ -0,0 +1,57 @@
+import type { ProviderCompleteRequest } from '../kernel/types.ts';
+
+const SECRET_HEADER = /key|auth|cookie|secret|token/i;
+
+function tapeHeaderValue(key: string, value: string): string {
+  if (SECRET_HEADER.test(key)) {
+    return '[redacted]';
+  }
+  return value;
+}
+
+function tapeHeaders(headers?: HeadersInit): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of new Headers(headers).entries()) {
+    out[key] = tapeHeaderValue(key, value);
+  }
+  return out;
+}
+
+function throwRow(err: unknown): Record<string, unknown> {
+  if (err instanceof Error) {
+    return { eventType: 'http_throw', name: err.name, message: err.message };
+  }
+  return { eventType: 'http_throw', name: 'Error', message: String(err) };
+}
+
+function tapFetch(
+  tap: ProviderCompleteRequest['tapGemini'],
+  send: typeof fetch = fetch,
+): typeof fetch {
+  return async (url, init) => {
+    const method = init?.method ?? 'GET';
+    tap?.({
+      eventType: 'http_request',
+      method,
+      url: String(url),
+      headers: tapeHeaders(init?.headers),
+    });
+    try {
+      const res = await send(url, init);
+      tap?.({
+        eventType: 'http_response',
+        status: res.status,
+        headers: tapeHeaders(res.headers),
+      });
+      if (!res.ok) {
+        tap?.({ eventType: 'http_error_body', body: await res.clone().text() });
+      }
+      return res;
+    } catch (err) {
+      tap?.(throwRow(err));
+      throw err;
+    }
+  };
+}
+
+export { tapFetch };

package/src/providers/interactions.ts

@@ -0,0 +1,182 @@
+import { TheorumError } from '../guardrails/error.ts';
+import { getTool } from '../kernel/registry/catalog.ts';
+import { getStructured } from '../kernel/registry/schemas.ts';
+import type { InteractionPart, ProviderCompleteRequest } from '../kernel/types.ts';
+
+function camelToSnake(key: string): string {
+  return key.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+
+function toGoogleValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(toGoogleValue);
+  }
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    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') {
+        out[camelToSnake(key)] = nested;
+        continue;
+      }
+      out[camelToSnake(key)] = toGoogleValue(nested);
+    }
+    return out;
+  }
+  return value;
+}
+
+function wirePart(part: InteractionPart): Record<string, string> {
+  if (part.type === 'text') {
+    return { type: 'text', text: part.text };
+  }
+  return { type: part.type, mimeType: part.mimeType, data: part.data };
+}
+
+const USER_INPUT = 'user_input';
+
+function userInputStep(parts: InteractionPart[]): {
+  type: string;
+  content: Record<string, string>[];
+} {
+  return { type: USER_INPUT, content: parts.map(wirePart) };
+}
+
+function historyStep(msg: import('../kernel/types.ts').TurnHistoryMessage): {
+  type: string;
+  content: Record<string, string>[];
+} {
+  const isAssistant = msg.role === 'assistant';
+  const type = isAssistant ? 'model_turn' : 'user_input';
+  if (msg.parts && msg.parts.length > 0) {
+    return { type, content: msg.parts.map(wirePart) };
+  }
+  return { type, content: [{ type: 'text', text: msg.content ?? '' }] };
+}
+
+function systemHoldsUserInput(system: string, parts: InteractionPart[]): boolean {
+  for (const part of parts) {
+    if (part.type === 'text' && part.text && system.includes(part.text)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function jsonResponseFormat(schema: Record<string, unknown>): unknown[] {
+  return [{ type: 'text', mimeType: 'application/json', schema }];
+}
+
+function attachResponseFormat(req: ProviderCompleteRequest, camel: Record<string, unknown>): void {
+  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' };
+    return;
+  }
+  if (req.image) {
+    camel.responseFormat = {
+      type: 'image',
+      mimeType: req.image.mimeType,
+      aspectRatio: req.image.aspectRatio,
+      imageSize: req.image.size,
+    };
+    return;
+  }
+  if (!req.structured) {
+    return;
+  }
+  const spec = getStructured(req.structured);
+  if (spec.enforced !== 'responseFormat' || !spec.jsonSchema) {
+    return;
+  }
+  camel.responseFormat = jsonResponseFormat(spec.jsonSchema);
+}
+
+function attachSpeechConfig(
+  req: ProviderCompleteRequest,
+  generationConfig: Record<string, unknown>,
+): void {
+  if (!req.speech) {
+    return;
+  }
+  if (req.speech.voice) {
+    generationConfig.speechConfig = [{ voice: req.speech.voice }];
+  }
+}
+
+function inputStepsFromRequest(req: ProviderCompleteRequest): {
+  type: string;
+  content: Record<string, string>[];
+}[] {
+  const inputSteps: { type: string; content: Record<string, string>[] }[] = [];
+  for (const h of req.history ?? []) {
+    inputSteps.push(historyStep(h));
+  }
+  if (req.input.length > 0 || inputSteps.length === 0) {
+    inputSteps.push(userInputStep(req.input));
+  }
+  return inputSteps;
+}
+
+function applyOptionalRequestFields(
+  req: ProviderCompleteRequest,
+  camel: Record<string, unknown>,
+): void {
+  if (req.store !== undefined) {
+    camel.store = req.store;
+  }
+  if (req.previousInteractionId) {
+    camel.previousInteractionId = req.previousInteractionId;
+  }
+  if (req.system) {
+    camel.systemInstruction = req.system;
+  }
+  if (req.builtins.length > 0) {
+    camel.tools = req.builtins.map((id) => {
+      const type = getTool(id)?.interactionsType;
+      if (!type) {
+        throw new TheorumError(`Builtin '${id}' has no Interactions wire type`);
+      }
+      return { type };
+    });
+  }
+}
+
+function baseInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown> {
+  const generationConfig: Record<string, unknown> = {
+    temperature: req.temperature,
+    maxOutputTokens: req.maxOutputTokens,
+  };
+  if (req.speech) {
+    // TTS models reject chat thinking knobs; voice lives under speech_config.
+    attachSpeechConfig(req, generationConfig);
+  } else {
+    generationConfig.thinkingLevel = req.thinking;
+    generationConfig.thinkingSummaries = req.summaries;
+  }
+  return {
+    model: req.apiId,
+    stream: true,
+    input: inputStepsFromRequest(req),
+    generationConfig,
+  };
+}
+
+/** Interactions REST body for one complete() call (Google snake_case keys). */
+function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown> {
+  if (systemHoldsUserInput(req.system, req.input)) {
+    throw new TheorumError('user input cannot be placed in the system block');
+  }
+  const camel = baseInteractionsBody(req);
+  applyOptionalRequestFields(req, camel);
+  attachResponseFormat(req, camel);
+  return toGoogleValue(camel) as Record<string, unknown>;
+}
+
+export { camelToSnake, toInteractionsBody };

package/src/providers/keys.ts

@@ -0,0 +1,182 @@
+/**
+ * Gemini key vault selection, quota overflow, and fetch retries.
+ *
+ * Host applications supply vault credentials through `GeminiTransport`.
+ * THEORUM does not read environment variables for these keys.
+ *
+ * @module
+ */
+
+import { TheorumError, UPSTREAM_FAILED } from '../guardrails/error.ts';
+import type { GeminiBucket } from '../kernel/types.ts';
+
+type GeminiVault = Record<GeminiBucket, string | undefined>;
+
+interface GeminiTransport {
+  vault: GeminiVault;
+  wait?: (ms: number) => Promise<void>;
+  fetch?: typeof fetch;
+}
+
+const ATTEMPTS = 3;
+const LAST_ATTEMPT = ATTEMPTS - 1;
+const BACKOFF_FIRST_MS = 1000;
+const BACKOFF_SECOND_MS = 2000;
+const BACKOFF_THIRD_MS = 4000;
+const BACKOFF_MS = [BACKOFF_FIRST_MS, BACKOFF_SECOND_MS, BACKOFF_THIRD_MS];
+
+const HTTP_TIMEOUT = 408;
+const HTTP_QUOTA = 429;
+const HTTP_SERVER = 500;
+const HTTP_BAD_GATEWAY = 502;
+const HTTP_UNAVAILABLE = 503;
+const HTTP_GATEWAY_TIMEOUT = 504;
+
+const QUOTA_RE = /quota/i;
+const TRANSIENT_THROWN_RE =
+  /name resolution|dns|econnreset|econnrefused|etimedout|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
+
+function waitDefault(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function isQuota(err: unknown): boolean {
+  const s = String(err);
+  return s.includes(String(HTTP_QUOTA)) || s.includes('RESOURCE_EXHAUSTED') || QUOTA_RE.test(s);
+}
+
+function isTransientHttp(status: number): boolean {
+  return (
+    status === HTTP_TIMEOUT ||
+    status === HTTP_QUOTA ||
+    status === HTTP_SERVER ||
+    status === HTTP_BAD_GATEWAY ||
+    status === HTTP_UNAVAILABLE ||
+    status === HTTP_GATEWAY_TIMEOUT
+  );
+}
+
+function isTransientThrown(err: unknown): boolean {
+  return TRANSIENT_THROWN_RE.test(String(err));
+}
+
+function requireKey(vault: GeminiVault, bucket: GeminiBucket): string {
+  const key = vault[bucket];
+  if (!key) {
+    throw new TheorumError(UPSTREAM_FAILED);
+  }
+  return key;
+}
+
+function backoffMs(attempt: number): number {
+  return BACKOFF_MS[attempt] ?? BACKOFF_SECOND_MS;
+}
+
+async function runWithBackoff<T>(
+  apiKey: string,
+  run: (apiKey: string) => Promise<T>,
+  wait: (ms: number) => Promise<void>,
+  attempt: number,
+): Promise<T> {
+  try {
+    return await run(apiKey);
+  } catch (err) {
+    if (!(isQuota(err) || isTransientThrown(err)) || attempt === LAST_ATTEMPT) {
+      throw err;
+    }
+    await wait(backoffMs(attempt));
+    return runWithBackoff(apiKey, run, wait, attempt + 1);
+  }
+}
+
+function canOverflow(
+  bucket: GeminiBucket,
+  vault: GeminiVault,
+  primary: string,
+): string | undefined {
+  if (bucket === 'paid') {
+    return undefined;
+  }
+  const { paid } = vault;
+  if (!paid || paid === primary) {
+    return undefined;
+  }
+  return paid;
+}
+
+async function withGeminiKey<T>(
+  bucket: GeminiBucket,
+  run: (apiKey: string) => Promise<T>,
+  transport: GeminiTransport,
+): Promise<T> {
+  const wait = transport.wait ?? waitDefault;
+  const primary = requireKey(transport.vault, bucket);
+  try {
+    return await runWithBackoff(primary, run, wait, 0);
+  } catch (err) {
+    const paid = canOverflow(bucket, transport.vault, primary);
+    if (!(isQuota(err) && paid)) {
+      throw err;
+    }
+    return await runWithBackoff(paid, run, wait, 0);
+  }
+}
+
+function withApiKey(init: RequestInit, apiKey: string): RequestInit {
+  const headers = new Headers(init.headers);
+  headers.set('x-goog-api-key', apiKey);
+  if (!headers.has('Content-Type') && (init.method || 'GET').toUpperCase() !== 'GET') {
+    headers.set('Content-Type', 'application/json');
+  }
+  return { ...init, headers };
+}
+
+interface FetchAttempt {
+  href: string;
+  init: RequestInit;
+  apiKey: string;
+  transport: GeminiTransport;
+  attempt: number;
+}
+
+async function fetchWithBackoff(args: FetchAttempt): Promise<Response> {
+  const wait = args.transport.wait ?? waitDefault;
+  const send = args.transport.fetch ?? fetch;
+  try {
+    const last = await send(args.href, withApiKey(args.init, args.apiKey));
+    if (!isTransientHttp(last.status) || args.attempt === LAST_ATTEMPT) {
+      return last;
+    }
+    await wait(backoffMs(args.attempt));
+    return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
+  } catch (err) {
+    if (!isTransientThrown(err) || args.attempt === LAST_ATTEMPT) {
+      throw err;
+    }
+    await wait(backoffMs(args.attempt));
+    return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
+  }
+}
+
+async function fetchGemini(
+  url: string,
+  init: RequestInit,
+  bucket: GeminiBucket,
+  transport: GeminiTransport,
+): Promise<Response> {
+  const parsed = new URL(url);
+  parsed.searchParams.delete('key');
+  const href = parsed.toString();
+  const primary = requireKey(transport.vault, bucket);
+  let last = await fetchWithBackoff({ href, init, apiKey: primary, transport, attempt: 0 });
+  const paid = canOverflow(bucket, transport.vault, primary);
+  if (last.status === HTTP_QUOTA && paid) {
+    last = await fetchWithBackoff({ href, init, apiKey: paid, transport, attempt: 0 });
+  }
+  return last;
+}
+
+export type { GeminiTransport, GeminiVault };
+export { fetchGemini, withGeminiKey };

package/src/providers/mod.ts

@@ -0,0 +1,12 @@
+/**
+ * Provider adapters for THEORUM's `ModelProvider` contract.
+ *
+ * Host apps should use `createProvider(profile, options)` — the single door.
+ * Credentials are always supplied by the host application.
+ *
+ * @module
+ */
+
+export type { CreateProviderOptions } from './create-provider.ts';
+export { createProvider } from './create-provider.ts';
+export type { GeminiTransport, GeminiVault } from './keys.ts';

package/src/providers/openrouter-mod.ts

@@ -0,0 +1,16 @@
+/**
+ * OpenRouter provider adapter and payload helpers.
+ *
+ * Prefer `createProvider(profile, { openRouter })` from `theorum` / `theorum/providers`
+ * for turn execution. This entrypoint is for hosts that build OpenRouter payloads
+ * outside the runner.
+ *
+ * @module
+ */
+
+export { createOpenRouterProvider } from './openrouter.ts';
+export type { OpenRouterConfig } from './openrouter-payload.ts';
+export {
+  resolveOpenRouterModel,
+  toOpenRouterPayload,
+} from './openrouter-payload.ts';