@broberg/ai-sdk 0.24.0 → 0.25.1

package/README.md

@@ -30,7 +30,7 @@ const emb = await ai.embedding({ text: ["a", "b"] });
 
 ## Capabilities
 
-`chat` · `vision` · `translate` · `image` (fal.ai) · `embedding` · `transcribe`
+`chat` · `vision` · `translate` · `image` (fal.ai default / OpenRouter) · `embedding` · `transcribe`
 (Whisper), plus **prompt contracts** with structured output:
 
 ```ts
@@ -56,6 +56,14 @@ await ai.chat({ prompt: "…", tier: "powerful" });
 await ai.chat({ prompt: "…", override: { provider: "openrouter", model: "minimax/minimax-m2.7" } });
 ```
 
+> **Images — raster vs. vector.** `ai.image()` defaults to fal.ai (raster PNG). For
+> **vector/SVG** output (logos), override to OpenRouter Recraft — the slug is an
+> **OpenRouter** model, not a fal app-id:
+> ```ts
+> await ai.image({ prompt: "…", override: { provider: "openrouter", model: "recraft/recraft-v4.1-vector" } });
+> // → data:image/svg+xml;base64,… with ground-truth cost
+> ```
+
 `cheap` defaults to the cheapest-that's-good-enough cloud model — **Mistral Small**
 (EU/Paris-hosted, GDPR-safe, ~$0.10/$0.30) — so a cost-tier call is safe for
 personal data by default; override per call for an even cheaper non-personal route.

package/dist/index.d.ts

@@ -239,6 +239,20 @@ interface EmbeddingResult {
     vectors: number[][];
     usage: Usage;
 }
+/** Timestamp granularity a caller can request from `ai.transcribe` (F036). */
+type TimestampGranularity = "word" | "segment";
+/** A single word with its start/end offset in seconds. */
+interface WordTimestamp {
+    word: string;
+    start: number;
+    end: number;
+}
+/** A phrase/sentence segment with its start/end offset in seconds. */
+interface SegmentTimestamp {
+    text: string;
+    start: number;
+    end: number;
+}
 interface TranscribeRequest {
     /** Raw audio bytes (the client resolves a URL to bytes before calling). */
     audio: Uint8Array;
@@ -248,10 +262,17 @@ interface TranscribeRequest {
     /** Bias recognition toward these brand/jargon terms (Azure phraseList, F029.3).
      *  Providers without biasing support (Voxtral/Whisper) ignore it. */
     phrases?: string[];
+    /** Request timestamps (F036). The client normalizes the input to this array.
+     *  Adapters without timestamp support ignore it (result omits words/segments). */
+    timestamps?: TimestampGranularity[];
     spec: TierSpec;
 }
 interface TranscribeResult {
     text: string;
+    /** Word-level timing — present only when "word" timestamps were requested. */
+    words?: WordTimestamp[];
+    /** Segment (phrase/sentence) timing — present when any timestamps were requested. */
+    segments?: SegmentTimestamp[];
     usage: Usage;
 }
 interface OcrRequest {
@@ -1331,6 +1352,11 @@ declare const transcribeInputSchema: z.ZodObject<{
     durationSec: z.ZodOptional<z.ZodNumber>;
     /** Bias toward brand/jargon terms (Azure phraseList, F029.3); others ignore it. */
     phrases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Opt-in timestamps (F036) — a single granularity or an array. Omit → the
+     *  current { text, usage } shape, unchanged. Pass ["word","segment"] for both.
+     *  Supported by Whisper (openai) + Azure fast-transcription (F036.1); other
+     *  adapters (Voxtral/mistral) ignore it and return text only. */
+    timestamps: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["word", "segment"]>, z.ZodArray<z.ZodEnum<["word", "segment"]>, "many">]>>;
 }, "strip", z.ZodTypeAny, {
     audio: string | Uint8Array<ArrayBuffer>;
     language?: string | undefined;
@@ -1349,6 +1375,7 @@ declare const transcribeInputSchema: z.ZodObject<{
     labels?: Record<string, string> | undefined;
     durationSec?: number | undefined;
     phrases?: string[] | undefined;
+    timestamps?: "word" | "segment" | ("word" | "segment")[] | undefined;
 }, {
     audio: string | Uint8Array<ArrayBuffer>;
     language?: string | undefined;
@@ -1367,6 +1394,7 @@ declare const transcribeInputSchema: z.ZodObject<{
     labels?: Record<string, string> | undefined;
     durationSec?: number | undefined;
     phrases?: string[] | undefined;
+    timestamps?: "word" | "segment" | ("word" | "segment")[] | undefined;
 }>;
 declare const ocrInputSchema: z.ZodObject<{
     tier: z.ZodOptional<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "video", "embedding"]>>;
@@ -2017,8 +2045,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.24.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.24.0";
+declare const VERSION: "0.25.1";
+declare const SDK_TAG: "@broberg/ai-sdk@0.25.1";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.

package/dist/index.js

@@ -730,6 +730,10 @@ function openaiAdapter(config = {}) {
     form.append("file", new Blob([req.audio]), "audio");
     form.append("model", req.spec.model);
     if (req.language) form.append("language", req.language);
+    if (req.timestamps && req.timestamps.length > 0) {
+      form.append("response_format", "verbose_json");
+      for (const g of req.timestamps) form.append("timestamp_granularities[]", g);
+    }
     const fetchImpl = config.fetch ?? fetch;
     const res = await fetchImpl(`${baseUrl}/audio/transcriptions`, {
       method: "POST",
@@ -753,7 +757,14 @@ function openaiAdapter(config = {}) {
       const perMinute = WHISPER_PRICE_PER_MIN[req.spec.model] ?? 0;
       usage.costUsd = req.durationSec / 60 * perMinute;
     }
-    return { text: data.text ?? "", usage };
+    const result = { text: data.text ?? "", usage };
+    if (req.timestamps?.includes("word") && data.words) {
+      result.words = data.words.map((w) => ({ word: w.word, start: w.start, end: w.end }));
+    }
+    if (req.timestamps && req.timestamps.length > 0 && data.segments) {
+      result.segments = data.segments.map((s) => ({ text: s.text, start: s.start, end: s.end }));
+    }
+    return result;
   }
   return { ...base, embedding, transcribe };
 }
@@ -1523,7 +1534,26 @@ function azureAdapter(config = {}) {
       outputTokens: 0
     });
     usage.costUsd = minutes * (config.sttPricePerMin ?? AZURE_STT_PRICE_PER_MIN);
-    return { text, usage };
+    const result = { text, usage };
+    if (req.timestamps && req.timestamps.length > 0 && data.phrases) {
+      const toSec = (ms) => (ms ?? 0) / 1e3;
+      if (req.timestamps.includes("word")) {
+        const words = data.phrases.flatMap((p) => p.words ?? []);
+        if (words.length > 0) {
+          result.words = words.map((w) => ({
+            word: w.text ?? "",
+            start: toSec(w.offsetMilliseconds),
+            end: toSec((w.offsetMilliseconds ?? 0) + (w.durationMilliseconds ?? 0))
+          }));
+        }
+      }
+      result.segments = data.phrases.map((p) => ({
+        text: p.text ?? "",
+        start: toSec(p.offsetMilliseconds),
+        end: toSec((p.offsetMilliseconds ?? 0) + (p.durationMilliseconds ?? 0))
+      }));
+    }
+    return result;
   }
   return { name: "azure", tts, transcribe };
 }
@@ -2526,6 +2556,11 @@ var transcribeInputSchema = z.object({
   durationSec: z.number().positive().optional(),
   /** Bias toward brand/jargon terms (Azure phraseList, F029.3); others ignore it. */
   phrases: z.array(z.string()).optional(),
+  /** Opt-in timestamps (F036) — a single granularity or an array. Omit → the
+   *  current { text, usage } shape, unchanged. Pass ["word","segment"] for both.
+   *  Supported by Whisper (openai) + Azure fast-transcription (F036.1); other
+   *  adapters (Voxtral/mistral) ignore it and return text only. */
+  timestamps: z.union([z.enum(["word", "segment"]), z.array(z.enum(["word", "segment"]))]).optional(),
   ...callOptions
 });
 var ocrInputSchema = z.object({
@@ -2572,8 +2607,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.24.0";
-var SDK_TAG = "@broberg/ai-sdk@0.24.0";
+var VERSION = "0.25.1";
+var SDK_TAG = "@broberg/ai-sdk@0.25.1";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {
@@ -3126,7 +3161,8 @@ function createAI(config = {}) {
         invoke: async (spec) => {
           const adapter = pickProvider(spec.provider);
           if (!adapter.transcribe) throw new Error(`createAI: provider "${spec.provider}" does not support transcribe`);
-          return adapter.transcribe({ audio, language: input.language, durationSec: input.durationSec, phrases: input.phrases, spec });
+          const timestamps = input.timestamps === void 0 ? void 0 : Array.isArray(input.timestamps) ? input.timestamps : [input.timestamps];
+          return adapter.transcribe({ audio, language: input.language, durationSec: input.durationSec, phrases: input.phrases, timestamps, spec });
         }
       });
     },