@delofarag/ai-utils 1.4.3 → 1.6.0

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"}

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

@@ -0,0 +1,55 @@
+import { OpenRouterVisionModel } from "../../helpers/llms";
+import { LLMInstance } from "../openrouter";
+import { VisionImageInput } from "./helpers";
+type VisionOptions = {
+    llm?: LLMInstance;
+    prompt: string;
+    images: VisionImageInput[];
+    detail?: "auto" | "low" | "high";
+    model?: OpenRouterVisionModel;
+};
+/**
+ * Analyzes one or more images with a vision-capable OpenRouter model.
+ *
+ * Internally this function sends `image_url` content parts through OpenRouter's
+ * chat-completions-compatible interface. If no `llm` is provided, it builds one
+ * with `getLLM({ provider: "openrouter", type: "vision" })` 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.prompt Instruction/question for the model about the provided images.
+ * @param params.images Array of image URLs, data URLs, or base64 strings.
+ * @param params.detail Vision detail level (`auto`, `low`, `high`).
+ * @param params.model Optional model override for this call.
+ * @returns Promise with normalized `text` and full provider response in `raw`.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * vision({
+ *     llm = getLLM({ provider: "openrouter", type: "vision" }),
+ *     prompt = "Describe the image in detail.",
+ *     detail = "auto",
+ *     images,
+ *     model
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const result = await vision({
+ *     prompt: "What objects do you see?",
+ *     images: ["https://example.com/cat.jpg"]
+ * });
+ *
+ * console.log(result.text);
+ * ```
+ */
+export declare function vision({ llm, prompt, detail, images, model }: VisionOptions): Promise<{
+    text: string;
+    raw: unknown;
+}>;
+export {};
+//# sourceMappingURL=vision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../../src/modalities/vision/vision.ts"],"names":[],"mappings":"AACA,OAAO,EAAU,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,EAAE,WAAW,EAAwB,MAAM,eAAe,CAAA;AACjE,OAAO,EAAwB,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAElE,KAAK,aAAa,GAAG;IACjB,GAAG,CAAC,EAAE,WAAW,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,gBAAgB,EAAE,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;IAChC,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,MAAM,CAAC,EACzB,GAAwD,EACxD,MAAwC,EACxC,MAAe,EACf,MAAM,EACN,KAAK,EACR,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC,CA+BzD"}

package/dist/modalities/vision/vision.js

@@ -0,0 +1,71 @@
+import { HumanMessage } from "../../imports";
+import { getLLM } from "../../helpers/llms";
+import { getOpenRouterRuntime } from "../openrouter";
+import { normalizeVisionImage } from "./helpers";
+/**
+ * Analyzes one or more images with a vision-capable OpenRouter model.
+ *
+ * Internally this function sends `image_url` content parts through OpenRouter's
+ * chat-completions-compatible interface. If no `llm` is provided, it builds one
+ * with `getLLM({ provider: "openrouter", type: "vision" })` 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.prompt Instruction/question for the model about the provided images.
+ * @param params.images Array of image URLs, data URLs, or base64 strings.
+ * @param params.detail Vision detail level (`auto`, `low`, `high`).
+ * @param params.model Optional model override for this call.
+ * @returns Promise with normalized `text` and full provider response in `raw`.
+ *
+ * @example
+ * CONFIG:
+ * ```ts
+ * vision({
+ *     llm = getLLM({ provider: "openrouter", type: "vision" }),
+ *     prompt = "Describe the image in detail.",
+ *     detail = "auto",
+ *     images,
+ *     model
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const result = await vision({
+ *     prompt: "What objects do you see?",
+ *     images: ["https://example.com/cat.jpg"]
+ * });
+ *
+ * console.log(result.text);
+ * ```
+ */
+export async function vision({ llm = getLLM({ provider: "openrouter", type: "vision" }), prompt = "Describe the image in detail.", detail = "auto", images, model }) {
+    const runtime = getOpenRouterRuntime(llm);
+    const content = [
+        { type: "text", text: prompt },
+        ...images.map((image) => ({
+            type: "image_url",
+            image_url: {
+                url: normalizeVisionImage(image),
+                detail
+            }
+        }))
+    ];
+    const runtimeLLM = model && model !== runtime.model
+        ? getLLM({
+            provider: "openrouter",
+            type: "vision",
+            model,
+            apikey: runtime.apiKey
+        })
+        : llm;
+    const response = await runtimeLLM.invoke([new HumanMessage({ content })]);
+    const text = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+    return {
+        text,
+        raw: response
+    };
+}
+//# sourceMappingURL=vision.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vision.js","sourceRoot":"","sources":["../../../src/modalities/vision/vision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAyB,MAAM,oBAAoB,CAAA;AAClE,OAAO,EAAe,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACjE,OAAO,EAAE,oBAAoB,EAAoB,MAAM,WAAW,CAAA;AAUlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,EACzB,GAAG,GAAG,MAAM,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EACxD,MAAM,GAAG,+BAA+B,EACxC,MAAM,GAAG,MAAM,EACf,MAAM,EACN,KAAK,EACO;IACZ,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAA;IAEzC,MAAM,OAAO,GAAG;QACZ,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,EAAE;QACvC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACtB,IAAI,EAAE,WAAoB;YAC1B,SAAS,EAAE;gBACP,GAAG,EAAE,oBAAoB,CAAC,KAAK,CAAC;gBAChC,MAAM;aACT;SACJ,CAAC,CAAC;KACN,CAAA;IAED,MAAM,UAAU,GACZ,KAAK,IAAI,KAAK,KAAK,OAAO,CAAC,KAAK;QAC5B,CAAC,CAAC,MAAM,CAAC;YACH,QAAQ,EAAE,YAAY;YACtB,IAAI,EAAE,QAAQ;YACd,KAAK;YACL,MAAM,EAAE,OAAO,CAAC,MAAM;SACzB,CAAC;QACJ,CAAC,CAAC,GAAG,CAAA;IAEb,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;IACzE,MAAM,IAAI,GAAG,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IAEvG,OAAO;QACH,IAAI;QACJ,GAAG,EAAE,QAAQ;KAChB,CAAA;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delofarag/ai-utils",
-  "version": "1.4.3",
+  "version": "1.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,7 +34,7 @@
     "zodios": "^5.1.0"
   },
   "peerDependencies": {
-    "@delofarag/supabase-utils": "^1.0.1"
+    "@delofarag/supabase-utils": "^1.3.10"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",