@broberg/ai-sdk 0.23.0 → 0.25.0

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,9 @@ 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. */
+    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 +1373,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 +1392,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 +2043,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.23.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.23.0";
+declare const VERSION: "0.25.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.25.0";
 
 /** 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 };
 }
@@ -2526,6 +2537,9 @@ 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. */
+  timestamps: z.union([z.enum(["word", "segment"]), z.array(z.enum(["word", "segment"]))]).optional(),
   ...callOptions
 });
 var ocrInputSchema = z.object({
@@ -2571,6 +2585,78 @@ var aiConfigSchema = z.object({
   availability: availabilitySchema.optional()
 });
 
+// src/version.ts
+var VERSION = "0.25.0";
+var SDK_TAG = "@broberg/ai-sdk@0.25.0";
+
+// src/cost/sinks/upmetrics.ts
+function upmetricsSink(config) {
+  const doFetch = config.fetch ?? fetch;
+  const url = `${config.baseUrl.replace(/\/$/, "")}/api/agent`;
+  return {
+    async record(usage) {
+      try {
+        const startedAt = usage.ts || (/* @__PURE__ */ new Date()).toISOString();
+        const endedAt = new Date(
+          new Date(startedAt).getTime() + (usage.latencyMs || 0)
+        ).toISOString();
+        const agentKind = config.agentKind ?? (usage.capability === "embedding" ? "embedding" : "chatbot");
+        const body = {
+          mode: "record",
+          agent_kind: agentKind,
+          agent_name: config.agentName,
+          provider: usage.provider,
+          model: usage.model,
+          status: "success",
+          input_tokens: usage.inputTokens,
+          output_tokens: usage.outputTokens,
+          cache_read_tokens: usage.cacheReadTokens,
+          cache_creation_tokens: usage.cacheCreationTokens,
+          cost_usd: usage.costUsd,
+          duration_ms: usage.latencyMs,
+          started_at: startedAt,
+          ended_at: endedAt,
+          tags: {
+            // Consumer attribution labels (e.g. tenantId) ride in tags so no new
+            // top-level field risks the strict-shape ingest schema (F011). The
+            // SDK-owned keys win — a label can never clobber capability/transport/sdk.
+            ...usage.labels,
+            capability: usage.capability,
+            transport: usage.transport,
+            sdk: SDK_TAG
+          }
+        };
+        if (usage.tier !== void 0) body.tier = usage.tier;
+        if (usage.purpose !== void 0) body.purpose = usage.purpose;
+        if (usage.toolCalls) {
+          body.tool_calls = usage.toolCalls.map((t) => ({
+            name: t.name,
+            count: t.count,
+            error_count: t.errorCount ?? 0
+          }));
+        }
+        void config.complianceMode;
+        const res = await doFetch(url, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "X-Upmetrics-Key": config.apiKey
+          },
+          body: JSON.stringify(body)
+        });
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          config.onError?.(
+            new Error(`upmetricsSink: ingest returned ${res.status}: ${text.slice(0, 200)}`)
+          );
+        }
+      } catch (err) {
+        config.onError?.(err);
+      }
+    }
+  };
+}
+
 // src/client.ts
 var DEFAULT_IMAGE_SPEC = {
   provider: "fal",
@@ -2608,9 +2694,20 @@ var DEFAULT_MODERATION_SPEC = { provider: "mistral", model: "mistral-moderation-
 var DEFAULT_PODCAST_SPEC = { provider: "elevenlabs", model: "eleven_v3", transport: "http" };
 var DEFAULT_TTS_SPEC = { provider: "elevenlabs", model: "eleven_multilingual_v2", transport: "http" };
 var DEFAULT_BATCH_SPEC = { provider: "mistral", model: "mistral-small-latest", transport: "http" };
+function defaultCostSink() {
+  const apiKey = process.env.UPMETRICS_API_KEY;
+  if (!apiKey) return void 0;
+  return upmetricsSink({
+    baseUrl: process.env.UPMETRICS_BASE_URL ?? "https://upmetrics.org",
+    apiKey,
+    agentName: process.env.UPMETRICS_AGENT_NAME ?? process.env.npm_package_name ?? "unknown",
+    complianceMode: process.env.UPMETRICS_COMPLIANCE === "1"
+  });
+}
 function createAI(config = {}) {
   const cfg = aiConfigSchema.parse(config);
   const providers = cfg.providers ?? defaultProviders;
+  const costSink = cfg.costSink ?? defaultCostSink();
   const budget = cfg.budget ? new BudgetGuard(cfg.budget) : void 0;
   const estTokens = (s) => Math.ceil(s.length / 4);
   async function preflight(spec, estInTokens, estOutTokens) {
@@ -2639,9 +2736,9 @@ function createAI(config = {}) {
     return usage;
   }
   async function report(usage) {
-    if (!cfg.costSink) return;
+    if (!costSink) return;
     try {
-      await cfg.costSink.record(usage);
+      await costSink.record(usage);
     } catch {
     }
   }
@@ -3043,7 +3140,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 });
         }
       });
     },
@@ -3170,10 +3268,6 @@ var stubProviders = {
   fal: falStubAdapter
 };
 
-// src/version.ts
-var VERSION = "0.23.0";
-var SDK_TAG = "@broberg/ai-sdk@0.23.0";
-
 // src/availability/refresh.ts
 var NOT_REFRESHED = { refreshed: false, checked: 0, markedUnavailable: [] };
 var DEFAULT_TTL_MS = 60 * 60 * 1e3;
@@ -3263,74 +3357,6 @@ function multiSink(sinks) {
   };
 }
 
-// src/cost/sinks/upmetrics.ts
-function upmetricsSink(config) {
-  const doFetch = config.fetch ?? fetch;
-  const url = `${config.baseUrl.replace(/\/$/, "")}/api/agent`;
-  return {
-    async record(usage) {
-      try {
-        const startedAt = usage.ts || (/* @__PURE__ */ new Date()).toISOString();
-        const endedAt = new Date(
-          new Date(startedAt).getTime() + (usage.latencyMs || 0)
-        ).toISOString();
-        const agentKind = config.agentKind ?? (usage.capability === "embedding" ? "embedding" : "chatbot");
-        const body = {
-          mode: "record",
-          agent_kind: agentKind,
-          agent_name: config.agentName,
-          provider: usage.provider,
-          model: usage.model,
-          status: "success",
-          input_tokens: usage.inputTokens,
-          output_tokens: usage.outputTokens,
-          cache_read_tokens: usage.cacheReadTokens,
-          cache_creation_tokens: usage.cacheCreationTokens,
-          cost_usd: usage.costUsd,
-          duration_ms: usage.latencyMs,
-          started_at: startedAt,
-          ended_at: endedAt,
-          tags: {
-            // Consumer attribution labels (e.g. tenantId) ride in tags so no new
-            // top-level field risks the strict-shape ingest schema (F011). The
-            // SDK-owned keys win — a label can never clobber capability/transport/sdk.
-            ...usage.labels,
-            capability: usage.capability,
-            transport: usage.transport,
-            sdk: SDK_TAG
-          }
-        };
-        if (usage.tier !== void 0) body.tier = usage.tier;
-        if (usage.purpose !== void 0) body.purpose = usage.purpose;
-        if (usage.toolCalls) {
-          body.tool_calls = usage.toolCalls.map((t) => ({
-            name: t.name,
-            count: t.count,
-            error_count: t.errorCount ?? 0
-          }));
-        }
-        void config.complianceMode;
-        const res = await doFetch(url, {
-          method: "POST",
-          headers: {
-            "content-type": "application/json",
-            "X-Upmetrics-Key": config.apiKey
-          },
-          body: JSON.stringify(body)
-        });
-        if (!res.ok) {
-          const text = await res.text().catch(() => "");
-          config.onError?.(
-            new Error(`upmetricsSink: ingest returned ${res.status}: ${text.slice(0, 200)}`)
-          );
-        }
-      } catch (err) {
-        config.onError?.(err);
-      }
-    }
-  };
-}
-
 // src/cost/sinks/discord.ts
 function discordSink(config) {
   const doFetch = config.fetch ?? fetch;