@broberg/ai-sdk 0.30.1 → 0.31.0

package/dist/index.d.ts

@@ -130,6 +130,11 @@ interface ChatRequest {
      *  (components' requirement while building @broberg/chat, 2026-08-27, where two
      *  knowledge bases are written for readers with different permissions.) */
     promptCacheKey?: string;
+    /** F039.2 — prompt caching is ON by default where the provider supports it.
+     *  Set false to opt out (e.g. a one-shot call whose prefix will never repeat).
+     *  Off has no cost benefit and no penalty; a cache MISS was measured to cost
+     *  exactly the same as a call with no key at all. */
+    promptCache?: boolean;
     temperature?: number;
     /** "json" → request JSON-object output where the provider supports it (F009). */
     responseFormat?: "json" | "text";
@@ -546,7 +551,6 @@ declare const messageSchema: z.ZodObject<{
     }>, "many">>;
     toolCallId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    role: "system" | "user" | "assistant" | "tool";
     content: string | ({
         text: string;
         type: "text";
@@ -555,6 +559,7 @@ declare const messageSchema: z.ZodObject<{
         type: "image";
         mimeType?: string | undefined;
     })[];
+    role: "system" | "user" | "assistant" | "tool";
     toolCalls?: {
         id: string;
         name: string;
@@ -562,7 +567,6 @@ declare const messageSchema: z.ZodObject<{
     }[] | undefined;
     toolCallId?: string | undefined;
 }, {
-    role: "system" | "user" | "assistant" | "tool";
     content: string | ({
         text: string;
         type: "text";
@@ -571,6 +575,7 @@ declare const messageSchema: z.ZodObject<{
         type: "image";
         mimeType?: string | undefined;
     })[];
+    role: "system" | "user" | "assistant" | "tool";
     toolCalls?: {
         id: string;
         name: string;
@@ -613,6 +618,9 @@ declare const chatInputSchema: z.ZodObject<{
      *  Derive it from (tenant, conversation): the key is a shared-prefix identity,
      *  so two tenants with identical transcripts must get different keys. */
     promptCacheKey: z.ZodOptional<z.ZodString>;
+    /** F039.2 — prompt caching is ON by default on providers that support it.
+     *  false opts out; an explicit promptCacheKey always wins. */
+    promptCache: z.ZodOptional<z.ZodBoolean>;
     prompt: z.ZodOptional<z.ZodString>;
     messages: z.ZodOptional<z.ZodArray<z.ZodObject<{
         role: z.ZodEnum<["system", "user", "assistant", "tool"]>;
@@ -653,7 +661,6 @@ declare const chatInputSchema: z.ZodObject<{
         }>, "many">>;
         toolCallId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        role: "system" | "user" | "assistant" | "tool";
         content: string | ({
             text: string;
             type: "text";
@@ -662,6 +669,7 @@ declare const chatInputSchema: z.ZodObject<{
             type: "image";
             mimeType?: string | undefined;
         })[];
+        role: "system" | "user" | "assistant" | "tool";
         toolCalls?: {
             id: string;
             name: string;
@@ -669,7 +677,6 @@ declare const chatInputSchema: z.ZodObject<{
         }[] | undefined;
         toolCallId?: string | undefined;
     }, {
-        role: "system" | "user" | "assistant" | "tool";
         content: string | ({
             text: string;
             type: "text";
@@ -678,6 +685,7 @@ declare const chatInputSchema: z.ZodObject<{
             type: "image";
             mimeType?: string | undefined;
         })[];
+        role: "system" | "user" | "assistant" | "tool";
         toolCalls?: {
             id: string;
             name: string;
@@ -708,7 +716,6 @@ declare const chatInputSchema: z.ZodObject<{
     tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "video" | "embedding" | undefined;
     prompt?: string | undefined;
     messages?: {
-        role: "system" | "user" | "assistant" | "tool";
         content: string | ({
             text: string;
             type: "text";
@@ -717,6 +724,7 @@ declare const chatInputSchema: z.ZodObject<{
             type: "image";
             mimeType?: string | undefined;
         })[];
+        role: "system" | "user" | "assistant" | "tool";
         toolCalls?: {
             id: string;
             name: string;
@@ -732,6 +740,7 @@ declare const chatInputSchema: z.ZodObject<{
     temperature?: number | undefined;
     purpose?: string | undefined;
     promptCacheKey?: string | undefined;
+    promptCache?: boolean | undefined;
     maxTokens?: number | undefined;
     responseFormat?: "text" | "json" | undefined;
     override?: {
@@ -750,7 +759,6 @@ declare const chatInputSchema: z.ZodObject<{
     tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "video" | "embedding" | undefined;
     prompt?: string | undefined;
     messages?: {
-        role: "system" | "user" | "assistant" | "tool";
         content: string | ({
             text: string;
             type: "text";
@@ -759,6 +767,7 @@ declare const chatInputSchema: z.ZodObject<{
             type: "image";
             mimeType?: string | undefined;
         })[];
+        role: "system" | "user" | "assistant" | "tool";
         toolCalls?: {
             id: string;
             name: string;
@@ -774,6 +783,7 @@ declare const chatInputSchema: z.ZodObject<{
     temperature?: number | undefined;
     purpose?: string | undefined;
     promptCacheKey?: string | undefined;
+    promptCache?: boolean | undefined;
     maxTokens?: number | undefined;
     responseFormat?: "text" | "json" | undefined;
     override?: {
@@ -1716,6 +1726,9 @@ declare const ttsInputSchema: z.ZodObject<{
     rate?: number | undefined;
 }>;
 declare const aiConfigSchema: z.ZodObject<{
+    /** F039.2 — client-wide opt-out from prompt caching (default: on where the
+     *  provider supports it). A per-call `promptCache` wins over this. */
+    promptCache: z.ZodOptional<z.ZodBoolean>;
     defaults: z.ZodOptional<z.ZodRecord<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "video", "embedding"]>, z.ZodObject<{
         provider: z.ZodString;
         model: z.ZodString;
@@ -1755,6 +1768,7 @@ declare const aiConfigSchema: z.ZodObject<{
         autoResolve?: boolean | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    promptCache?: boolean | undefined;
     defaults?: Partial<Record<"fast" | "smart" | "powerful" | "cheap" | "vision" | "video" | "embedding", {
         provider: string;
         model: string;
@@ -1771,6 +1785,7 @@ declare const aiConfigSchema: z.ZodObject<{
         autoResolve?: boolean | undefined;
     } | undefined;
 }, {
+    promptCache?: boolean | undefined;
     defaults?: Partial<Record<"fast" | "smart" | "powerful" | "cheap" | "vision" | "video" | "embedding", {
         provider: string;
         model: string;
@@ -2060,6 +2075,13 @@ interface OpenAICompatibleConfig {
      *  response's `usage.cost` (USD) as costUsd, falling back to the pricing table.
      *  Only OpenRouter returns this field — openai/deepinfra leave it false. */
     costFromResponseField?: boolean;
+    /** F039.2 — this provider accepts `prompt_cache_key` and caches a shared prefix
+     *  on it. Mistral only, deliberately: an unknown field is ignored by some
+     *  OpenAI-compatible servers and rejected with a 400 by others, so sending it
+     *  everywhere would trade a saving for an outage. Providers that cache
+     *  AUTOMATICALLY (openai, deepseek, gemini) need no key — they only need their
+     *  cached counts read back, which happens for every provider below. */
+    supportsPromptCacheKey?: boolean;
 }
 declare function makeOpenAICompatibleAdapter(config: OpenAICompatibleConfig): ProviderAdapter;
 
@@ -2081,8 +2103,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.30.1";
-declare const SDK_TAG: "@broberg/ai-sdk@0.30.1";
+declare const VERSION: "0.31.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.31.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.

package/dist/index.js

@@ -485,6 +485,16 @@ function mapAnthropicStop(reason) {
 }
 
 // src/providers/openai-compatible.ts
+function autoCacheKey(messages) {
+  const system = messages.find((m) => m.role === "system");
+  if (!system || typeof system.content !== "string" || system.content.length < 200) return void 0;
+  let h = 2166136261;
+  for (let i = 0; i < system.content.length; i++) {
+    h ^= system.content.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return `ai-sdk-auto-${h.toString(16)}-${system.content.length}`;
+}
 function toOpenAIMessage(m) {
   if (typeof m.content === "string") {
     const base = { role: m.role, content: m.content };
@@ -523,7 +533,10 @@ function makeOpenAICompatibleAdapter(config) {
     if (req.maxTokens !== void 0) body.max_tokens = req.maxTokens;
     if (req.temperature !== void 0) body.temperature = req.temperature;
     if (req.responseFormat === "json") body.response_format = { type: "json_object" };
-    if (req.promptCacheKey !== void 0) body.prompt_cache_key = req.promptCacheKey;
+    if (config.supportsPromptCacheKey && req.promptCache !== false) {
+      const k = req.promptCacheKey ?? autoCacheKey(req.messages);
+      if (k !== void 0) body.prompt_cache_key = k;
+    }
     if (config.costFromResponseField) body.usage = { include: true };
     const res = await httpTransport({
       spec: req.spec,
@@ -1150,7 +1163,7 @@ var VOXTRAL_PRICE_PER_MIN = {
 };
 function mistralAdapter(config = {}) {
   const baseUrl = config.baseUrl ?? "https://api.mistral.ai/v1";
-  const base = makeOpenAICompatibleAdapter({ name: "mistral", baseUrl, apiKey: config.apiKey });
+  const base = makeOpenAICompatibleAdapter({ name: "mistral", baseUrl, apiKey: config.apiKey, supportsPromptCacheKey: true });
   function key() {
     const k = config.apiKey ?? process.env.MISTRAL_API_KEY;
     if (!k) throw new Error("mistral adapter: API key not set (env MISTRAL_API_KEY)");
@@ -2631,6 +2644,9 @@ var chatInputSchema = z.object({
    *  Derive it from (tenant, conversation): the key is a shared-prefix identity,
    *  so two tenants with identical transcripts must get different keys. */
   promptCacheKey: z.string().optional(),
+  /** F039.2 — prompt caching is ON by default on providers that support it.
+   *  false opts out; an explicit promptCacheKey always wins. */
+  promptCache: z.boolean().optional(),
   prompt: z.string().optional(),
   messages: z.array(messageSchema).optional(),
   system: z.string().optional(),
@@ -2779,6 +2795,9 @@ var availabilitySchema = z.object({
   fallback: z.union([z.string(), z.array(z.string())]).optional()
 });
 var aiConfigSchema = z.object({
+  /** F039.2 — client-wide opt-out from prompt caching (default: on where the
+   *  provider supports it). A per-call `promptCache` wins over this. */
+  promptCache: z.boolean().optional(),
   defaults: z.record(tierSchema, tierSpecSchema).optional(),
   // Functions can't be deeply validated — z.custom asserts the TS type and
   // passes the value through untouched.
@@ -2792,8 +2811,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.30.1";
-var SDK_TAG = "@broberg/ai-sdk@0.30.1";
+var VERSION = "0.31.0";
+var SDK_TAG = "@broberg/ai-sdk@0.31.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {
@@ -3077,7 +3096,7 @@ function createAI(config = {}) {
         invoke: async (spec) => {
           const adapter = pickProvider(spec.provider);
           if (!adapter.chat) throw new Error(`createAI: provider "${spec.provider}" does not support chat`);
-          return adapter.chat({ messages, spec, tools: input.tools, maxTokens: input.maxTokens, temperature: input.temperature, responseFormat: input.responseFormat, promptCacheKey: input.promptCacheKey });
+          return adapter.chat({ messages, spec, tools: input.tools, maxTokens: input.maxTokens, temperature: input.temperature, responseFormat: input.responseFormat, promptCacheKey: input.promptCacheKey, promptCache: input.promptCache ?? cfg.promptCache });
         }
       });
     },