@k2b/nessi 0.11.0 → 0.12.0

package/README.md

@@ -265,11 +265,62 @@ for await (const event of provider.stream({ messages })) {
 }
 ```
 
+## Audio transcription
+
+Use `openAICompatibleTranscription()` to upload an audio file to a service that
+implements the OpenAI-compatible `/audio/transcriptions` endpoint. Configure
+the service URL, API key and transcription model explicitly:
+
+```ts
+import { openAICompatibleTranscription } from "@k2b/nessi/ai";
+
+const speech = openAICompatibleTranscription("whisper-large-v3", {
+  baseURL: "https://api.scaleway.ai/v1",
+  apiKey: process.env.SCW_SECRET_KEY,
+});
+
+const result = await speech.transcribe({
+  file: Bun.file("./aufnahme.mp3"),
+  filename: "aufnahme.mp3",
+  language: "de",
+  signal: AbortSignal.timeout(120_000),
+});
+
+console.log(result.text);
+```
+
+For OpenAI, set `baseURL: "https://api.openai.com/v1"`, use your OpenAI key and
+a supported transcription model such as `whisper-1`. Local compatible services
+can omit `apiKey`. No environment variable is read automatically. Optional
+`headers` support gateways; `apiKey` overrides their Authorization header.
+
+`file` accepts a `Blob`, `File` or `Bun.file()`. Use `filename` to supply an
+extension for an unnamed Blob or override the filename. Automatically derived
+filenames omit local directories. Omit `language`
+for automatic detection. Optional `prompt` supplies vocabulary or context
+when supported by the model. File formats, size limits and optional parameter
+support depend on the service; Nessi does not convert or split audio.
+
+The result is `{ text: string }`, including an empty string for an empty
+transcript. HTTP, connection and malformed-response errors reject the promise.
+Pass `signal` for cancellation or a timeout; cancellation preserves the signal's
+reason. There are no automatic retries or default timeout.
+
+Transcription uses its own `TranscriptionProvider` contract with `name`, `model`
+and `transcribe(request)`. Custom adapters can implement that interface for other
+protocols. It is separate from the chat provider passed to `nessi()`; pass the
+resulting text into the agent when needed. Streaming transcription, timestamps
+and speaker identification are not exposed.
+
+The example follows [Scaleway's audio API documentation](https://www.scaleway.com/en/docs/generative-apis/how-to/query-audio-models/).
+Keep API keys on the server when integrating a browser application.
+
 ## Focused provider imports
 
 ```ts
 import { anthropic } from "@k2b/nessi/ai/providers/anthropic";
 import { openai } from "@k2b/nessi/ai/providers/openai";
+import { openAICompatibleTranscription } from "@k2b/nessi/ai/providers/openai-compatible-transcription";
 ```
 
 ## Features
@@ -290,6 +341,7 @@ import { openai } from "@k2b/nessi/ai/providers/openai";
 - Standalone `compact()` loop with `loop_start`, `compaction_start`, `compaction_end`, `issue`, and `loop_end` events
 - Optional token-credit budgeting
 - Provider adapters with shared `complete()` and `stream()` APIs
+- Audio transcription through configurable OpenAI-compatible services
 - Native adapters for OpenAI, OpenRouter, vLLM, Ollama, Anthropic, Mistral, and Gemini
 
 ## Package layout
@@ -299,7 +351,7 @@ import { openai } from "@k2b/nessi/ai/providers/openai";
   Agent loop, structured task helper, tools, stores, compaction, shared types
 
 @k2b/nessi/ai
-  Provider factories, provider types, complete(), stream(), responseFormat
+  Provider factories, provider types, complete(), stream(), responseFormat, transcribe()
 
 @k2b/nessi/ai/providers/*
   Focused provider entrypoints

package/ai/index.d.ts

@@ -1,4 +1,7 @@
 export { completeFromStream } from "./complete-from-stream.js";
+export { openAICompatibleTranscription } from "./providers/openai-compatible-transcription.js";
+export type { OpenAICompatibleTranscriptionOptions } from "./providers/openai-compatible-transcription.js";
+export type { TranscriptionProvider, TranscriptionRequest, TranscriptionResult } from "./transcription.js";
 export { openAICompatible } from "./providers/openai-compatible.js";
 export { openai } from "./providers/openai.js";
 export { openrouter } from "./providers/openrouter.js";

package/ai/index.js

@@ -1,4 +1,5 @@
 export { completeFromStream } from "./complete-from-stream.js";
+export { openAICompatibleTranscription } from "./providers/openai-compatible-transcription.js";
 export { openAICompatible } from "./providers/openai-compatible.js";
 export { openai } from "./providers/openai.js";
 export { openrouter } from "./providers/openrouter.js";

package/ai/providers/openai-compatible-transcription.d.ts

@@ -0,0 +1,8 @@
+import type { TranscriptionProvider } from "../transcription.js";
+export type OpenAICompatibleTranscriptionOptions = {
+    baseURL: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    name?: string;
+};
+export declare const openAICompatibleTranscription: (model: string, options: OpenAICompatibleTranscriptionOptions) => TranscriptionProvider;

package/ai/providers/openai-compatible-transcription.js

@@ -0,0 +1,60 @@
+import { formatConnectionError, normalizeHttpError } from "../shared/errors.js";
+export const openAICompatibleTranscription = (model, options) => {
+    const baseURL = options.baseURL.replace(/\/+$/, "");
+    const name = options.name ?? "openai-compatible";
+    const headers = new Headers(options.headers);
+    // Fetch must supply the multipart boundary, including with custom headers.
+    headers.delete("Content-Type");
+    if (options.apiKey)
+        headers.set("Authorization", `Bearer ${options.apiKey}`);
+    return {
+        name,
+        model,
+        async transcribe(request) {
+            request.signal?.throwIfAborted();
+            const body = new FormData();
+            // Bun.file().name can contain a local path; only upload the basename.
+            const fileName = "name" in request.file && typeof request.file.name === "string"
+                ? request.file.name.split(/[\\/]/).at(-1)
+                : undefined;
+            const filename = request.filename ?? fileName;
+            if (filename !== undefined)
+                body.append("file", request.file, filename);
+            else
+                body.append("file", request.file);
+            body.append("model", model);
+            body.append("response_format", "json");
+            if (request.language !== undefined)
+                body.append("language", request.language);
+            if (request.prompt !== undefined)
+                body.append("prompt", request.prompt);
+            const response = await fetch(`${baseURL}/audio/transcriptions`, {
+                method: "POST",
+                headers,
+                body,
+                signal: request.signal,
+            }).catch((error) => {
+                request.signal?.throwIfAborted();
+                throw new Error(formatConnectionError(name, error));
+            });
+            if (!response.ok) {
+                const normalized = await normalizeHttpError(name, response);
+                request.signal?.throwIfAborted();
+                throw new Error(normalized.error);
+            }
+            const raw = await response.text();
+            let payload;
+            try {
+                payload = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`${name} returned invalid transcription JSON.`);
+            }
+            if (typeof payload !== "object" || payload === null
+                || !("text" in payload) || typeof payload.text !== "string") {
+                throw new Error(`${name} returned a transcription without a string text field.`);
+            }
+            return { text: payload.text };
+        },
+    };
+};

package/ai/transcription.d.ts

@@ -0,0 +1,18 @@
+export type TranscriptionRequest = {
+    file: Blob;
+    /** Override the file name, or supply one for an unnamed Blob. */
+    filename?: string;
+    /** ISO-639-1 language code, for example "de". Omit for automatic detection. */
+    language?: string;
+    /** Optional vocabulary or context hint, subject to model support. */
+    prompt?: string;
+    signal?: AbortSignal;
+};
+export type TranscriptionResult = {
+    text: string;
+};
+export type TranscriptionProvider = {
+    name: string;
+    model: string;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/nessi",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Minimal agent loop and provider adapters for nessi.",
   "main": "index.js",
   "module": "index.js",
@@ -16,6 +16,10 @@
       "import": "./ai/index.js",
       "types": "./ai/index.d.ts"
     },
+    "./ai/providers/openai-compatible-transcription": {
+      "import": "./ai/providers/openai-compatible-transcription.js",
+      "types": "./ai/providers/openai-compatible-transcription.d.ts"
+    },
     "./ai/providers/openai-compatible": {
       "import": "./ai/providers/openai-compatible.js",
       "types": "./ai/providers/openai-compatible.d.ts"