@delofarag/ai-utils 1.4.3 → 1.5.0

package/dist/modalities/speech/stt/stt.d.ts

@@ -0,0 +1,113 @@
+import { OpenRouterSTTModel } from "../../../helpers/llms";
+import { LLMInstance } from "../../openrouter";
+import { STTAudioInput } from "./helpers";
+type STTOptions = {
+    llm?: LLMInstance;
+    audio: STTAudioInput;
+    prompt?: string;
+    audioFormat?: "wav" | "mp3" | "aiff" | "aac" | "ogg" | "flac" | "m4a" | "pcm16" | "pcm24";
+    model?: OpenRouterSTTModel;
+};
+type PhoneSocketChunk = string | Buffer | Uint8Array;
+type STTPhoneSocketSessionOptions = {
+    llm?: LLMInstance;
+    prompt?: string;
+    audioFormat?: "wav" | "mp3" | "aiff" | "aac" | "ogg" | "flac" | "m4a" | "pcm16" | "pcm24";
+    model?: OpenRouterSTTModel;
+    flushIntervalMs?: number;
+    minBufferBytes?: number;
+    onTranscription?: (result: {
+        text: string;
+        raw: unknown;
+    }) => Promise<void> | void;
+};
+/**
+ * Transcribes audio to text using an OpenRouter speech-capable model.
+ *
+ * Internally this function sends an `input_audio` payload through the OpenRouter
+ * chat-completions-compatible flow. If no `llm` is provided, it builds one with
+ * `getLLM({ provider: "openrouter", type: "stt" })` and reads
+ * `process.env.OPENROUTER_API_KEY`.
+ *
+ * Make sure `OPENROUTER_API_KEY` is set in your `.env`.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.audio Audio source as file path, base64 string, `Buffer`, or `Uint8Array`.
+ * @param params.prompt Optional instruction text for the transcription model.
+ * @param params.audioFormat Audio format sent to the model (for example `wav`, `mp3`, `ogg`).
+ * @param params.model Optional model override for this call.
+ * @returns Promise with normalized `text` and full provider response in `raw`.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * stt({
+ *     llm = getLLM({ provider: "openrouter", type: "stt" }),
+ *     prompt = "Please transcribe this audio file.",
+ *     audioFormat = "wav",
+ *     model,
+ *     audio
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const result = await stt({
+ *     audio: "./audio/meeting.wav",
+ *     prompt: "Transcribe this in German."
+ * });
+ *
+ * console.log(result.text);
+ * ```
+ */
+export declare function stt({ llm, prompt, audioFormat, model, audio }: STTOptions): Promise<{
+    text: string;
+    raw: unknown;
+}>;
+/**
+ * Creates a lightweight live STT session for phone sockets (for example Twilio/Telnyx media chunks).
+ *
+ * Internally this helper buffers incoming live audio frames and repeatedly calls `stt()`
+ * to emit near-real-time transcriptions through `onTranscription`.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.prompt Optional transcription instruction prompt.
+ * @param params.audioFormat Audio format for incoming phone media chunks.
+ * @param params.model Optional model override for this session.
+ * @param params.flushIntervalMs Interval in milliseconds for automatic transcription flushes.
+ * @param params.minBufferBytes Minimum buffered bytes required before transcribing.
+ * @param params.onTranscription Optional callback that receives each partial transcription.
+ * @returns Session controller with `pushChunk`, `flush`, and `stop`.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * createSTTPhoneSocketSession({
+ *     llm = getLLM({ provider: "openrouter", type: "stt" }),
+       flushIntervalMs = 2000,
+       minBufferBytes = 1024,
+       prompt = "Please transcribe",
+       audioFormat = "wav",
+       model,
+       onTranscription
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const session = createSTTPhoneSocketSession({
+ *     audioFormat: "pcm16",
+ *     onTranscription: ({ text }) => console.log(text)
+ * });
+ *
+ * session.pushChunk(mediaPayloadBase64);
+ * await session.stop();
+ * ```
+ */
+export declare function createSTTPhoneSocketSession({ llm, flushIntervalMs, minBufferBytes, prompt, audioFormat, model, onTranscription }: STTPhoneSocketSessionOptions): {
+    pushChunk(chunk: PhoneSocketChunk): void;
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+};
+export {};
+//# sourceMappingURL=stt.d.ts.map

package/dist/modalities/speech/stt/stt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stt.d.ts","sourceRoot":"","sources":["../../../../src/modalities/speech/stt/stt.ts"],"names":[],"mappings":"AACA,OAAO,EAAU,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAA;AACpE,OAAO,EAAE,aAAa,EAAiB,MAAM,WAAW,CAAA;AAExD,KAAK,UAAU,GAAG;IACd,GAAG,CAAC,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,aAAa,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAA;IACzF,KAAK,CAAC,EAAE,kBAAkB,CAAA;CAC7B,CAAA;AAED,KAAK,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;AAEpD,KAAK,4BAA4B,GAAG;IAChC,GAAG,CAAC,EAAE,WAAW,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAA;IACzF,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACrF,CAAA;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,GAAG,CAAC,EACtB,GAAqD,EACrD,MAA6C,EAC7C,WAAmB,EACnB,KAAK,EACL,KAAK,EACR,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC,CAqCtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,2BAA2B,CAAC,EACxC,GAAqD,EACrD,eAAsB,EACtB,cAAqB,EACrB,MAA4B,EAC5B,WAAmB,EACnB,KAAK,EACL,eAAe,EAClB,EAAE,4BAA4B;qBAyCN,gBAAgB;;;EAexC"}

package/dist/modalities/speech/stt/stt.js

@@ -0,0 +1,177 @@
+import { HumanMessage } from "../../../imports";
+import { getLLM } from "../../../helpers/llms";
+import { getOpenRouterRuntime } from "../../openrouter";
+import { toBase64Audio } from "./helpers";
+function normalizePhoneSocketChunk(chunk) {
+    if (typeof chunk === "string") {
+        return Buffer.from(chunk, "base64");
+    }
+    if (Buffer.isBuffer(chunk)) {
+        return chunk;
+    }
+    return Buffer.from(chunk);
+}
+/**
+ * Transcribes audio to text using an OpenRouter speech-capable model.
+ *
+ * Internally this function sends an `input_audio` payload through the OpenRouter
+ * chat-completions-compatible flow. If no `llm` is provided, it builds one with
+ * `getLLM({ provider: "openrouter", type: "stt" })` and reads
+ * `process.env.OPENROUTER_API_KEY`.
+ *
+ * Make sure `OPENROUTER_API_KEY` is set in your `.env`.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.audio Audio source as file path, base64 string, `Buffer`, or `Uint8Array`.
+ * @param params.prompt Optional instruction text for the transcription model.
+ * @param params.audioFormat Audio format sent to the model (for example `wav`, `mp3`, `ogg`).
+ * @param params.model Optional model override for this call.
+ * @returns Promise with normalized `text` and full provider response in `raw`.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * stt({
+ *     llm = getLLM({ provider: "openrouter", type: "stt" }),
+ *     prompt = "Please transcribe this audio file.",
+ *     audioFormat = "wav",
+ *     model,
+ *     audio
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const result = await stt({
+ *     audio: "./audio/meeting.wav",
+ *     prompt: "Transcribe this in German."
+ * });
+ *
+ * console.log(result.text);
+ * ```
+ */
+export async function stt({ llm = getLLM({ provider: "openrouter", type: "stt" }), prompt = "Please transcribe this audio file.", audioFormat = "wav", model, audio }) {
+    const runtime = getOpenRouterRuntime(llm);
+    const audioBase64 = await toBase64Audio(audio);
+    const message = new HumanMessage({
+        content: [
+            {
+                type: "text",
+                text: prompt
+            },
+            {
+                type: "input_audio",
+                input_audio: {
+                    data: audioBase64,
+                    format: audioFormat
+                }
+            }
+        ]
+    });
+    const runtimeLLM = model && model !== runtime.model
+        ? getLLM({
+            provider: "openrouter",
+            type: "stt",
+            model,
+            apikey: runtime.apiKey
+        })
+        : llm;
+    const response = await runtimeLLM.invoke([message]);
+    const text = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+    return {
+        text,
+        raw: response
+    };
+}
+/**
+ * Creates a lightweight live STT session for phone sockets (for example Twilio/Telnyx media chunks).
+ *
+ * Internally this helper buffers incoming live audio frames and repeatedly calls `stt()`
+ * to emit near-real-time transcriptions through `onTranscription`.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.prompt Optional transcription instruction prompt.
+ * @param params.audioFormat Audio format for incoming phone media chunks.
+ * @param params.model Optional model override for this session.
+ * @param params.flushIntervalMs Interval in milliseconds for automatic transcription flushes.
+ * @param params.minBufferBytes Minimum buffered bytes required before transcribing.
+ * @param params.onTranscription Optional callback that receives each partial transcription.
+ * @returns Session controller with `pushChunk`, `flush`, and `stop`.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * createSTTPhoneSocketSession({
+ *     llm = getLLM({ provider: "openrouter", type: "stt" }),
+       flushIntervalMs = 2000,
+       minBufferBytes = 1024,
+       prompt = "Please transcribe",
+       audioFormat = "wav",
+       model,
+       onTranscription
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const session = createSTTPhoneSocketSession({
+ *     audioFormat: "pcm16",
+ *     onTranscription: ({ text }) => console.log(text)
+ * });
+ *
+ * session.pushChunk(mediaPayloadBase64);
+ * await session.stop();
+ * ```
+ */
+export function createSTTPhoneSocketSession({ llm = getLLM({ provider: "openrouter", type: "stt" }), flushIntervalMs = 2000, minBufferBytes = 1024, prompt = "Please transcribe", audioFormat = "wav", model, onTranscription }) {
+    const chunks = [];
+    let isFlushing = false;
+    let isStopped = false;
+    const flush = async () => {
+        if (isFlushing || isStopped) {
+            return;
+        }
+        const totalBytes = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+        if (totalBytes < minBufferBytes) {
+            return;
+        }
+        isFlushing = true;
+        const merged = Buffer.concat(chunks);
+        chunks.length = 0;
+        try {
+            const result = await stt({
+                llm,
+                prompt,
+                audioFormat,
+                model,
+                audio: merged
+            });
+            if (onTranscription) {
+                await onTranscription(result);
+            }
+        }
+        finally {
+            isFlushing = false;
+        }
+    };
+    const timer = setInterval(() => {
+        void flush();
+    }, flushIntervalMs);
+    return {
+        pushChunk(chunk) {
+            if (isStopped) {
+                return;
+            }
+            chunks.push(normalizePhoneSocketChunk(chunk));
+        },
+        async flush() {
+            await flush();
+        },
+        async stop() {
+            isStopped = true;
+            clearInterval(timer);
+            await flush();
+        }
+    };
+}
+//# sourceMappingURL=stt.js.map

package/dist/modalities/speech/stt/stt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stt.js","sourceRoot":"","sources":["../../../../src/modalities/speech/stt/stt.ts"],"names":[],"mappings":"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"}

package/dist/modalities/speech/tts/helpers.d.ts

@@ -0,0 +1,12 @@
+import { AutoComplete } from "../../../helpers/llms";
+export type TTSResponseFormat = "mp3" | "pcm";
+export type OpenRouterTTSVoice = AutoComplete<"alloy" | "ash" | "ballad" | "cedar" | "coral" | "echo" | "fable" | "marin" | "nova" | "onyx" | "sage" | "shimmer" | "verse">;
+export type TTSPayload = {
+    model: string;
+    input: string;
+    voice: OpenRouterTTSVoice;
+    response_format?: TTSResponseFormat;
+    speed?: number;
+};
+export declare function createTTSPayload(payload: TTSPayload): TTSPayload;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/modalities/speech/tts/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/modalities/speech/tts/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEpD,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,KAAK,CAAA;AAC7C,MAAM,MAAM,kBAAkB,GAAG,YAAY,CACvC,OAAO,GACP,KAAK,GACL,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,OAAO,CACZ,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,kBAAkB,CAAA;IACzB,eAAe,CAAC,EAAE,iBAAiB,CAAA;IACnC,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAQhE"}

package/dist/modalities/speech/tts/helpers.js

@@ -0,0 +1,10 @@
+export function createTTSPayload(payload) {
+    return {
+        model: payload.model,
+        input: payload.input,
+        voice: payload.voice,
+        response_format: payload.response_format ?? "mp3",
+        speed: payload.speed
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/modalities/speech/tts/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/modalities/speech/tts/helpers.ts"],"names":[],"mappings":"AA2BA,MAAM,UAAU,gBAAgB,CAAC,OAAmB;IAChD,OAAO;QACH,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,KAAK;QACjD,KAAK,EAAE,OAAO,CAAC,KAAK;KACvB,CAAA;AACL,CAAC"}

package/dist/modalities/speech/tts/tts.d.ts

@@ -0,0 +1,115 @@
+import { LLMInstance } from "../../openrouter";
+import { OpenRouterTTSVoice, TTSResponseFormat } from "./helpers";
+type TTSOptions = {
+    llm?: LLMInstance;
+    text: string;
+    model: OpenRouterTTSVoice;
+    responseFormat?: TTSResponseFormat;
+    speed?: number;
+};
+type TTSPhoneSocketStreamOptions = TTSOptions & {
+    chunkSizeBytes?: number;
+    emitBase64?: boolean;
+    onChunk: (chunk: Uint8Array | string, index: number) => Promise<void> | void;
+};
+/**
+ * Converts text to speech via OpenRouter's dedicated `/audio/speech` endpoint.
+ *
+ * Internally this function calls OpenRouter directly and returns raw audio bytes.
+ * If no `llm` is provided, it creates one with
+ * `getLLM({ provider: "openrouter", type: "tts" })` and reads
+ * `process.env.OPENROUTER_API_KEY`.
+ *
+ * Make sure `OPENROUTER_API_KEY` is set in your `.env`.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.text Text that should be synthesized to audio.
+ * @param params.model Voice identifier to use for speech generation.
+ * @param params.responseFormat Audio response format (`mp3` or `pcm`).
+ * @param params.speed Playback speed multiplier (default `1.0`).
+ * @returns Promise with `audioBytes` and optional response metadata headers.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * tts({
+ *     llm = getLLM({ provider: "openrouter", type: "tts" }),
+ *     responseFormat = "mp3",
+ *     speed = 1.0,
+ *     text,
+ *     model
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const speech = await tts({
+ *     text: "Hallo! Das ist ein Test.",
+ *     model: "nova",
+ *     responseFormat: "mp3"
+ * });
+ *
+ * console.log(speech.audioBytes.length);
+ * ```
+ */
+export declare function tts({ llm, responseFormat, speed, text, model }: TTSOptions): Promise<{
+    audioBytes: Uint8Array;
+    contentType?: string;
+    generationId?: string;
+}>;
+/**
+ * Streams synthesized TTS audio as sequential chunks for phone socket pipelines
+ * (for example Twilio/Telnyx websocket media send loops).
+ *
+ * Internally this helper calls `tts()` once and splits the returned audio into
+ * chunked payloads that can be forwarded to a live call socket.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.text Text that should be synthesized to audio.
+ * @param params.model Voice identifier for speech generation.
+ * @param params.responseFormat Audio response format (`mp3` or `pcm`).
+ * @param params.speed Playback speed multiplier.
+ * @param params.chunkSizeBytes Size of each emitted audio chunk.
+ * @param params.emitBase64 If true, emits base64 chunks; otherwise emits `Uint8Array`.
+ * @param params.onChunk Callback that receives each emitted chunk in order.
+ * @returns Promise with total emitted chunks and response metadata.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * streamTTSOverPhoneSocket({
+ *     llm = getLLM({ provider: "openrouter", type: "tts" }),
+       speed = 1.0,
+       chunkSizeBytes = 3200,
+       emitBase64 = true,
+       responseFormat = "mp3",
+       text,
+       model,
+       onChunk
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * await streamTTSOverPhoneSocket({
+    model,
+    onChunk
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * await streamTTSOverPhoneSocket({
+ *     text: "Willkommen beim Support.",
+ *     model: "nova",
+ *     onChunk: async (chunk) => socket.send(String(chunk))
+ * });
+ * ```
+ */
+export declare function streamTTSOverPhoneSocket({ llm, speed, chunkSizeBytes, emitBase64, responseFormat, text, model, onChunk }: TTSPhoneSocketStreamOptions): Promise<{
+    totalChunks: number;
+    contentType?: string;
+    generationId?: string;
+}>;
+export {};
+//# sourceMappingURL=tts.d.ts.map

package/dist/modalities/speech/tts/tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.d.ts","sourceRoot":"","sources":["../../../../src/modalities/speech/tts/tts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAA;AACpE,OAAO,EAAoB,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAEnF,KAAK,UAAU,GAAG;IACd,GAAG,CAAC,EAAE,WAAW,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,kBAAkB,CAAA;IACzB,cAAc,CAAC,EAAE,iBAAiB,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,KAAK,2BAA2B,GAAG,UAAU,GAAG;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC/E,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAsB,GAAG,CAAC,EACtB,GAAqD,EACrD,cAAsB,EACtB,KAAW,EACX,IAAI,EACJ,KAAK,EACR,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+B/F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,wBAAwB,CAAC,EAC3C,GAAqD,EACrD,KAAW,EACX,cAAqB,EACrB,UAAiB,EACjB,cAAsB,EACtB,IAAI,EACJ,KAAK,EACL,OAAO,EACV,EAAE,2BAA2B,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB7G"}

package/dist/modalities/speech/tts/tts.js

@@ -0,0 +1,142 @@
+import { getLLM } from "../../../helpers/llms";
+import { getOpenRouterRuntime } from "../../openrouter";
+import { createTTSPayload } from "./helpers";
+/**
+ * Converts text to speech via OpenRouter's dedicated `/audio/speech` endpoint.
+ *
+ * Internally this function calls OpenRouter directly and returns raw audio bytes.
+ * If no `llm` is provided, it creates one with
+ * `getLLM({ provider: "openrouter", type: "tts" })` and reads
+ * `process.env.OPENROUTER_API_KEY`.
+ *
+ * Make sure `OPENROUTER_API_KEY` is set in your `.env`.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.text Text that should be synthesized to audio.
+ * @param params.model Voice identifier to use for speech generation.
+ * @param params.responseFormat Audio response format (`mp3` or `pcm`).
+ * @param params.speed Playback speed multiplier (default `1.0`).
+ * @returns Promise with `audioBytes` and optional response metadata headers.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * tts({
+ *     llm = getLLM({ provider: "openrouter", type: "tts" }),
+ *     responseFormat = "mp3",
+ *     speed = 1.0,
+ *     text,
+ *     model
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const speech = await tts({
+ *     text: "Hallo! Das ist ein Test.",
+ *     model: "nova",
+ *     responseFormat: "mp3"
+ * });
+ *
+ * console.log(speech.audioBytes.length);
+ * ```
+ */
+export async function tts({ llm = getLLM({ provider: "openrouter", type: "tts" }), responseFormat = "mp3", speed = 1.0, text, model }) {
+    const runtime = getOpenRouterRuntime(llm);
+    const payload = createTTSPayload({
+        model: runtime.model,
+        input: text,
+        voice: model,
+        response_format: responseFormat,
+        speed
+    });
+    const response = await fetch(`${runtime.baseURL}/audio/speech`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${runtime.apiKey}`,
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`OpenRouter TTS failed (${response.status}): ${errorText}`);
+    }
+    const audioBuffer = await response.arrayBuffer();
+    return {
+        audioBytes: new Uint8Array(audioBuffer),
+        contentType: response.headers.get("content-type") ?? undefined,
+        generationId: response.headers.get("x-generation-id") ?? undefined
+    };
+}
+/**
+ * Streams synthesized TTS audio as sequential chunks for phone socket pipelines
+ * (for example Twilio/Telnyx websocket media send loops).
+ *
+ * Internally this helper calls `tts()` once and splits the returned audio into
+ * chunked payloads that can be forwarded to a live call socket.
+ *
+ * @param params.llm Optional LLM instance from `getLLM(...)`.
+ * @param params.text Text that should be synthesized to audio.
+ * @param params.model Voice identifier for speech generation.
+ * @param params.responseFormat Audio response format (`mp3` or `pcm`).
+ * @param params.speed Playback speed multiplier.
+ * @param params.chunkSizeBytes Size of each emitted audio chunk.
+ * @param params.emitBase64 If true, emits base64 chunks; otherwise emits `Uint8Array`.
+ * @param params.onChunk Callback that receives each emitted chunk in order.
+ * @returns Promise with total emitted chunks and response metadata.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * streamTTSOverPhoneSocket({
+ *     llm = getLLM({ provider: "openrouter", type: "tts" }),
+       speed = 1.0,
+       chunkSizeBytes = 3200,
+       emitBase64 = true,
+       responseFormat = "mp3",
+       text,
+       model,
+       onChunk
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * await streamTTSOverPhoneSocket({
+    model,
+    onChunk
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * await streamTTSOverPhoneSocket({
+ *     text: "Willkommen beim Support.",
+ *     model: "nova",
+ *     onChunk: async (chunk) => socket.send(String(chunk))
+ * });
+ * ```
+ */
+export async function streamTTSOverPhoneSocket({ llm = getLLM({ provider: "openrouter", type: "tts" }), speed = 1.0, chunkSizeBytes = 3200, emitBase64 = true, responseFormat = "mp3", text, model, onChunk }) {
+    const result = await tts({
+        llm,
+        text,
+        model,
+        responseFormat,
+        speed
+    });
+    let index = 0;
+    for (let offset = 0; offset < result.audioBytes.length; offset += chunkSizeBytes) {
+        const chunk = result.audioBytes.slice(offset, offset + chunkSizeBytes);
+        const outgoing = emitBase64 ? Buffer.from(chunk).toString("base64") : chunk;
+        await onChunk(outgoing, index);
+        index += 1;
+    }
+    return {
+        totalChunks: index,
+        contentType: result.contentType,
+        generationId: result.generationId
+    };
+}
+//# sourceMappingURL=tts.js.map

package/dist/modalities/speech/tts/tts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.js","sourceRoot":"","sources":["../../../../src/modalities/speech/tts/tts.ts"],"names":[],"mappings":"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"}

package/dist/modalities/vision/helpers.d.ts

@@ -0,0 +1,3 @@
+export type VisionImageInput = string;
+export declare function normalizeVisionImage(input: VisionImageInput): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/modalities/vision/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/modalities/vision/helpers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAErC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAMpE"}

package/dist/modalities/vision/helpers.js

@@ -0,0 +1,7 @@
+export function normalizeVisionImage(input) {
+    if (input.startsWith("http://") || input.startsWith("https://") || input.startsWith("data:image/")) {
+        return input;
+    }
+    return `data:image/jpeg;base64,${input}`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/modalities/vision/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/modalities/vision/helpers.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,oBAAoB,CAAC,KAAuB;IACxD,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACjG,OAAO,KAAK,CAAA;IAChB,CAAC;IAED,OAAO,0BAA0B,KAAK,EAAE,CAAA;AAC5C,CAAC"}