theorum 0.1.3 → 0.1.4

package/src/providers/pcm.ts

@@ -0,0 +1,37 @@
+/**
+ * PCM → WAV helpers shared by speech transports.
+ *
+ * @module
+ */
+
+const SAMPLE_RATE = 24000;
+
+function writeAscii(view: DataView, offset: number, str: string): void {
+  for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i));
+}
+
+/** Wrap raw PCM bytes in a RIFF/WAVE container. */
+export function wrapPcmAsWav(pcm: Uint8Array, sampleRate = SAMPLE_RATE): Uint8Array {
+  const numChannels = 1;
+  const bitsPerSample = 16;
+  const byteRate = (sampleRate * numChannels * bitsPerSample) / 8;
+  const blockAlign = (numChannels * bitsPerSample) / 8;
+  const dataSize = pcm.length;
+  const buf = new ArrayBuffer(44 + dataSize);
+  const view = new DataView(buf);
+  writeAscii(view, 0, 'RIFF');
+  view.setUint32(4, 36 + dataSize, true);
+  writeAscii(view, 8, 'WAVE');
+  writeAscii(view, 12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true); // PCM
+  view.setUint16(22, numChannels, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, byteRate, true);
+  view.setUint16(32, blockAlign, true);
+  view.setUint16(34, bitsPerSample, true);
+  writeAscii(view, 36, 'data');
+  view.setUint32(40, dataSize, true);
+  new Uint8Array(buf, 44).set(pcm);
+  return new Uint8Array(buf);
+}

package/src/providers/provider.ts

@@ -0,0 +1,206 @@
+/**
+ * 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 { publicError, TheorumError } from '../guardrails/error.ts';
+import {
+  eventsFromComplete,
+  eventsFromDelta,
+  extractTokenEvent,
+  groundingFromEvent,
+  tryStructured,
+} from '../kernel/engine/delta.ts';
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../kernel/types.ts';
+import { tapFetch } from './google-tap.ts';
+import { toInteractionsBody } from './interactions.ts';
+import { fetchGemini, type GeminiTransport } from './keys.ts';
+import { wrapPcmAsWav } from './pcm.ts';
+import { INTERACTIONS_URL, takeSsePayloads } from './sse.ts';
+
+const HTTP_OK = 200;
+
+function base64ToBytes(data: string): Uint8Array {
+  const bin = atob(data);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+
+function isRawPcmMime(mime: string): boolean {
+  const lower = mime.toLowerCase();
+  return lower === 'audio/pcm' || lower === 'audio/l16' || lower === 'audio/raw';
+}
+
+/** Google TTS returns raw PCM; wrap as WAV for hosts (matches OpenRouter pcm path). */
+function normalizeSpeechMedia(event: TurnEvent, speech: boolean): TurnEvent {
+  if (!(speech && event.type === 'media' && event.media)) {
+    return event;
+  }
+  const { mimeType, data } = event.media;
+  if (!isRawPcmMime(mimeType)) {
+    return event;
+  }
+  const wav = wrapPcmAsWav(base64ToBytes(data));
+  return {
+    type: 'media',
+    media: { mimeType: 'audio/wav', data: bytesToBase64(wav) },
+  };
+}
+
+async function* readSseRecords(res: Response): AsyncGenerator<Record<string, unknown>> {
+  if (!res.body) {
+    throw new TheorumError('empty Gemini stream');
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  yield* pumpSse(reader, decoder, '', '');
+}
+
+async function* pumpSse(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  decoder: TextDecoder,
+  buffer: string,
+  pendingEvent: string,
+): AsyncGenerator<Record<string, unknown>> {
+  const { done, value } = await reader.read();
+  if (done) {
+    return;
+  }
+  const next = buffer + decoder.decode(value, { stream: true });
+  const taken = takeSsePayloads(next, pendingEvent);
+  for (const payload of taken.payloads) {
+    yield payload;
+  }
+  yield* pumpSse(reader, decoder, taken.rest, taken.pendingEvent);
+}
+
+function eventType(event: Record<string, unknown>): string {
+  return String(event.event_type ?? event.type ?? '');
+}
+
+function isDeltaEvent(kind: string): boolean {
+  return kind === 'content.delta' || kind === 'step.delta';
+}
+
+function isCompleteEvent(kind: string): boolean {
+  return (
+    kind === 'interaction.complete' ||
+    kind === 'interaction.completed' ||
+    kind.startsWith('interaction.')
+  );
+}
+
+function foldDeltaPayload(event: Record<string, unknown>, acc: { text: string }): TurnEvent[] {
+  const deltaEvents = eventsFromDelta(event.delta);
+  for (const item of deltaEvents) {
+    if (item.type === 'text' && item.text) {
+      acc.text += item.text;
+    }
+  }
+  return deltaEvents;
+}
+
+function foldPayload(event: Record<string, unknown>, acc: { text: string }): TurnEvent[] {
+  const kind = eventType(event);
+  const events: TurnEvent[] = [];
+  if (isDeltaEvent(kind)) {
+    events.push(...foldDeltaPayload(event, acc));
+  } else if (isCompleteEvent(kind)) {
+    events.push(...eventsFromComplete(event, acc.text.length > 0));
+  }
+
+  // Also check if usage was included on the event directly
+  if (!events.some((e) => e.type === 'tokens')) {
+    const tokenEvent = extractTokenEvent(event);
+    if (tokenEvent) {
+      events.push(tokenEvent);
+    }
+  }
+  const groundingEvent = groundingFromEvent(event);
+  if (groundingEvent && !events.some((e) => e.type === 'grounding')) {
+    events.push(groundingEvent);
+  }
+  return events;
+}
+
+function withTap(req: ProviderCompleteRequest, transport: GeminiTransport): GeminiTransport {
+  return {
+    ...transport,
+    fetch: tapFetch(req.tapGemini, transport.fetch),
+  };
+}
+
+async function* streamComplete(
+  req: ProviderCompleteRequest,
+  transport: GeminiTransport,
+): AsyncGenerator<TurnEvent> {
+  if (!req.geminiBucket) {
+    yield {
+      type: 'error',
+      error: publicError('missing Gemini vault bucket for Interactions'),
+    };
+    return;
+  }
+  const res = await fetchGemini(
+    INTERACTIONS_URL,
+    { method: 'POST', body: JSON.stringify(toInteractionsBody(req)) },
+    req.geminiBucket,
+    withTap(req, transport),
+  );
+  if (res.status !== HTTP_OK) {
+    const errorBody = await res.text().catch(() => '');
+    yield {
+      type: 'error',
+      error: publicError(`Gemini HTTP ${String(res.status)}: ${errorBody}`),
+    };
+    return;
+  }
+  const acc = { text: '' };
+  const speech = Boolean(req.speech);
+  for await (const payload of readSseRecords(res)) {
+    req.tapGemini?.(payload);
+    const events = foldPayload(payload, acc);
+    for (const event of events) {
+      yield normalizeSpeechMedia(event, speech);
+    }
+  }
+  if (req.structured && acc.text) {
+    const structured = tryStructured(acc.text);
+    if (structured) {
+      yield structured;
+    }
+  }
+}
+
+async function* streamGuarded(
+  req: ProviderCompleteRequest,
+  transport: GeminiTransport,
+): AsyncGenerator<TurnEvent> {
+  try {
+    yield* streamComplete(req, transport);
+  } catch (err) {
+    yield { type: 'error', error: publicError(err) };
+  }
+}
+
+/** Create a `ModelProvider` backed by Google Interactions streaming. */
+function createInteractionsProvider(transport: GeminiTransport): ModelProvider {
+  return {
+    complete: (req) => streamGuarded(req, transport),
+  };
+}
+
+export { createInteractionsProvider };

package/src/providers/speech.ts

@@ -0,0 +1,180 @@
+/**
+ * OpenAI-compatible `/audio/speech` transport (internal).
+ *
+ * Hosts use `createProvider(profile, { openRouter })` — this module is selected
+ * when the profile is an openAi speech role. Not a separate public door.
+ *
+ * @module
+ */
+
+import { publicError } from '../guardrails/error.ts';
+import type {
+  InteractionPart,
+  ModelProvider,
+  ProfileSpeechSpec,
+  ProviderCompleteRequest,
+  SpeechAudioFormat,
+  TurnEvent,
+} from '../kernel/types.ts';
+import { wrapPcmAsWav } from './pcm.ts';
+
+const HTTP_OK = 200;
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+
+/** Credentials for the openAi speech path (same shape as OpenRouter chat config + voice). */
+export interface SpeechProviderConfig {
+  apiKey?: string;
+  /** Fallback TTS voice when the profile does not pin `outputs.speech.voice`. */
+  voice?: string;
+  baseUrl?: string;
+  siteUrl?: string;
+  siteName?: string;
+  fetch?: typeof fetch;
+}
+
+function extractInputText(input: InteractionPart[]): string {
+  return input
+    .filter((p) => p.type === 'text')
+    .map((p) => (p.type === 'text' ? p.text : ''))
+    .join(' ')
+    .trim();
+}
+
+function resolveSpeechWireModel(req: ProviderCompleteRequest): string {
+  if (req.openRouterId) {
+    return req.openRouterId;
+  }
+  if (req.apiId.includes('/')) {
+    return req.apiId;
+  }
+  if (req.apiId) {
+    return `google/${req.apiId}`;
+  }
+  return String(req.model);
+}
+
+function buildHeaders(apiKey: string, config: SpeechProviderConfig): Record<string, string> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  };
+  if (config.siteUrl) {
+    headers['HTTP-Referer'] = config.siteUrl;
+  }
+  if (config.siteName) {
+    headers['X-Title'] = config.siteName;
+  }
+  return headers;
+}
+
+function buildPayload(
+  req: ProviderCompleteRequest,
+  text: string,
+  speech: ProfileSpeechSpec | undefined,
+  configVoice?: string,
+): Record<string, unknown> {
+  const voice = speech?.voice ?? configVoice;
+  const format: SpeechAudioFormat = speech?.format ?? 'pcm';
+  const payload: Record<string, unknown> = {
+    model: resolveSpeechWireModel(req),
+    input: text,
+    response_format: format,
+  };
+  if (voice) {
+    payload.voice = voice;
+  }
+  return payload;
+}
+
+async function requestSpeech(
+  apiKey: string,
+  text: string,
+  req: ProviderCompleteRequest,
+  config: SpeechProviderConfig,
+): Promise<Response> {
+  const fetchFn = config.fetch ?? fetch;
+  const baseUrl = config.baseUrl?.replace(/\/+$/, '') ?? 'https://openrouter.ai/api/v1';
+  const url = `${baseUrl}/audio/speech`;
+  return await fetchFn(url, {
+    method: 'POST',
+    headers: buildHeaders(apiKey, config),
+    body: JSON.stringify(buildPayload(req, text, req.speech, config.voice)),
+  });
+}
+
+function* yieldSpeechSuccess(
+  rawBytes: Uint8Array,
+  text: string,
+  format: SpeechAudioFormat,
+): Generator<TurnEvent> {
+  let mediaMime = 'audio/mpeg';
+  let mediaBytes = rawBytes;
+
+  if (format === 'pcm') {
+    mediaMime = 'audio/wav';
+    mediaBytes = wrapPcmAsWav(rawBytes);
+  }
+
+  yield {
+    type: 'media',
+    media: { mimeType: mediaMime, data: bytesToBase64(mediaBytes) },
+  };
+
+  const inputTokens = Math.max(1, Math.round(text.length / 4));
+  const outputTokens = Math.max(1, Math.round(rawBytes.length / 100));
+  yield {
+    type: 'tokens',
+    tokens: { input: inputTokens, output: outputTokens, total: inputTokens + outputTokens },
+  };
+
+  yield { type: 'done' };
+}
+
+async function* streamSpeech(
+  req: ProviderCompleteRequest,
+  config: SpeechProviderConfig = {},
+): AsyncGenerator<TurnEvent> {
+  const apiKey = config.apiKey?.trim() || undefined;
+  if (!apiKey) {
+    yield { type: 'error', error: publicError('missing API key for speech') };
+    return;
+  }
+
+  const text = extractInputText(req.input);
+  if (!text) {
+    yield { type: 'error', error: publicError('empty text for speech') };
+    return;
+  }
+
+  const res = await requestSpeech(apiKey, text, req, config);
+  if (res.status !== HTTP_OK) {
+    yield { type: 'error', error: publicError(`Speech HTTP ${String(res.status)}`) };
+    return;
+  }
+
+  const arrayBuffer = await res.arrayBuffer();
+  const rawBytes = new Uint8Array(arrayBuffer);
+  if (rawBytes.length === 0) {
+    yield { type: 'error', error: publicError('no audio returned from speech') };
+    return;
+  }
+
+  const format = req.speech?.format ?? 'pcm';
+  for (const ev of yieldSpeechSuccess(rawBytes, text, format)) {
+    yield ev;
+  }
+}
+
+/** Internal ModelProvider for openAi speech roles. */
+function createSpeechProvider(config: SpeechProviderConfig = {}): ModelProvider {
+  return {
+    complete: (req: ProviderCompleteRequest) => streamSpeech(req, config),
+  };
+}
+
+export { createSpeechProvider, streamSpeech };

package/src/providers/sse.ts

@@ -0,0 +1,59 @@
+const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse';
+
+const DATA_PREFIX = 'data: ';
+const EVENT_PREFIX = 'event: ';
+const DONE = '[DONE]';
+
+function asObject(parsed: unknown): Record<string, unknown> | undefined {
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    return parsed as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function dataRecord(raw: string, sseEvent: string): Record<string, unknown> {
+  const data = raw.slice(DATA_PREFIX.length).trim();
+  const row: Record<string, unknown> = {};
+  if (sseEvent) {
+    row.sseEvent = sseEvent;
+  }
+  if (!data || data === DONE) {
+    row.eventType = 'sse_done';
+    return row;
+  }
+  try {
+    const parsed: unknown = JSON.parse(data);
+    const obj = asObject(parsed);
+    if (obj) {
+      return { ...obj, ...row };
+    }
+    row.eventType = 'sse_unparsed';
+    row.data = parsed;
+    return row;
+  } catch {
+    row.eventType = 'sse_unparsed';
+    row.data = data;
+    return row;
+  }
+}
+
+function takeSsePayloads(
+  buffer: string,
+  pendingEvent = '',
+): { rest: string; payloads: Record<string, unknown>[]; pendingEvent: string } {
+  const payloads: Record<string, unknown>[] = [];
+  const chunks = buffer.split('\n');
+  const rest = chunks.pop() ?? '';
+  let sseEvent = pendingEvent;
+  for (const line of chunks) {
+    if (line.startsWith(EVENT_PREFIX)) {
+      sseEvent = line.slice(EVENT_PREFIX.length).trim();
+    } else if (line.startsWith(DATA_PREFIX)) {
+      payloads.push(dataRecord(line, sseEvent));
+      sseEvent = '';
+    }
+  }
+  return { rest, payloads, pendingEvent: sseEvent };
+}
+
+export { INTERACTIONS_URL, takeSsePayloads };

package/esm/_dnt.polyfills.d.ts

@@ -1,110 +0,0 @@
-declare global {
-    interface Object {
-        /**
-         * Determines whether an object has a property with the specified name.
-         * @param o An object.
-         * @param v A property name.
-         */
-        hasOwn(o: object, v: PropertyKey): boolean;
-    }
-}
-export {};
-/**
- * Based on [import-meta-ponyfill](https://github.com/gaubee/import-meta-ponyfill),
- * but instead of using npm to install additional dependencies,
- * this approach manually consolidates cjs/mjs/d.ts into a single file.
- *
- * Note that this code might be imported multiple times
- * (for example, both dnt.test.polyfills.ts and dnt.polyfills.ts contain this code;
- *  or Node.js might dynamically clear the cache and then force a require).
- * Therefore, it's important to avoid redundant writes to global objects.
- * Additionally, consider that commonjs is used alongside esm,
- * so the two ponyfill functions are stored independently in two separate global objects.
- */
-import { createRequire } from "node:module";
-import { type URL } from "node:url";
-declare global {
-    interface ImportMeta {
-        /** A string representation of the fully qualified module URL. When the
-         * module is loaded locally, the value will be a file URL (e.g.
-         * `file:///path/module.ts`).
-         *
-         * You can also parse the string as a URL to determine more information about
-         * how the current module was loaded. For example to determine if a module was
-         * local or not:
-         *
-         * ```ts
-         * const url = new URL(import.meta.url);
-         * if (url.protocol === "file:") {
-         *   console.log("this module was loaded locally");
-         * }
-         * ```
-         */
-        url: string;
-        /**
-         * A function that returns resolved specifier as if it would be imported
-         * using `import(specifier)`.
-         *
-         * ```ts
-         * console.log(import.meta.resolve("./foo.js"));
-         * // file:///dev/foo.js
-         * ```
-         *
-         * @param specifier The module specifier to resolve relative to `parent`.
-         * @param parent The absolute parent module URL to resolve from.
-         * @returns The absolute (`file:`) URL string for the resolved module.
-         */
-        resolve(specifier: string, parent?: string | URL | undefined): string;
-        /** A flag that indicates if the current module is the main module that was
-         * called when starting the program under Deno.
-         *
-         * ```ts
-         * if (import.meta.main) {
-         *   // this was loaded as the main module, maybe do some bootstrapping
-         * }
-         * ```
-         */
-        main: boolean;
-        /** The absolute path of the current module.
-         *
-         * This property is only provided for local modules (ie. using `file://` URLs).
-         *
-         * Example:
-         * ```
-         * // Unix
-         * console.log(import.meta.filename); // /home/alice/my_module.ts
-         *
-         * // Windows
-         * console.log(import.meta.filename); // C:\alice\my_module.ts
-         * ```
-         */
-        filename: string;
-        /** The absolute path of the directory containing the current module.
-         *
-         * This property is only provided for local modules (ie. using `file://` URLs).
-         *
-         * * Example:
-         * ```
-         * // Unix
-         * console.log(import.meta.dirname); // /home/alice
-         *
-         * // Windows
-         * console.log(import.meta.dirname); // C:\alice
-         * ```
-         */
-        dirname: string;
-    }
-}
-type NodeRequest = ReturnType<typeof createRequire>;
-type NodeModule = NonNullable<NodeRequest["main"]>;
-interface ImportMetaPonyfillCommonjs {
-    (require: NodeRequest, module: NodeModule): ImportMeta;
-}
-interface ImportMetaPonyfillEsmodule {
-    (importMeta: ImportMeta): ImportMeta;
-}
-interface ImportMetaPonyfill extends ImportMetaPonyfillCommonjs, ImportMetaPonyfillEsmodule {
-}
-export declare let import_meta_ponyfill_commonjs: ImportMetaPonyfillCommonjs;
-export declare let import_meta_ponyfill_esmodule: ImportMetaPonyfillEsmodule;
-export declare let import_meta_ponyfill: ImportMetaPonyfill;