@jambonz/llm 0.5.7 → 0.6.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as ServiceAccountJson, A as AuthSpec, a as AuthKindSchema, P as PromptRequest, b as AdapterFactory, c as AdapterManifest, C as CreateLlmArgs, L as LlmAdapter } from './types-rZZBXYhB.cjs';
-export { d as ApiKeyAuth, e as AuthKind, f as AzureOpenAIApiKeyAuth, B as BedrockApiKeyAuth, g as BedrockIamAuth, h as ClientOptions, i as ContentBlock, F as FinishReason, j as FormField, k as FormFieldType, G as GoogleApiKeyAuth, l as GoogleServiceAccountAuth, J as JsonSchema, m as LlmEvent, M as Message, n as ModelCapabilities, o as ModelInfo, R as Role, T as Tool, p as ToolCallEvent, U as Usage, V as VertexServiceAccountAuth } from './types-rZZBXYhB.cjs';
+import { S as ServiceAccountJson, A as AuthSpec, a as AuthKindSchema, P as PromptRequest, b as AdapterFactory, c as AdapterManifest, C as CreateLlmArgs, L as LlmAdapter } from './types-Y0o6rN3B.cjs';
+export { d as ApiKeyAuth, e as AuthKind, f as AzureOpenAIApiKeyAuth, B as BedrockApiKeyAuth, g as BedrockIamAuth, h as ClientOptions, i as ContentBlock, F as FinishReason, j as FormField, k as FormFieldType, G as GoogleApiKeyAuth, l as GoogleServiceAccountAuth, J as JsonSchema, m as LlmEvent, M as Message, n as ModelCapabilities, o as ModelInfo, R as Role, T as Tool, p as ToolCallEvent, U as Usage, V as VertexServiceAccountAuth } from './types-Y0o6rN3B.cjs';
 
 /**
  * The loose "DB-shape" input accepted by `normalizeAuth`.
@@ -73,6 +73,7 @@ declare function pickAuthKind(vendor: string, raw: RawCredentialLoose): AuthKind
  *   - `model` is a non-empty string.
  *   - `messages` is a non-empty array.
  *   - `messages` does not contain `role: 'system'` turns (use `system` top-level).
+ *   - `cacheKey`, when present, is a non-empty string.
  */
 declare function assertValidRequest(req: PromptRequest): void;
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as ServiceAccountJson, A as AuthSpec, a as AuthKindSchema, P as PromptRequest, b as AdapterFactory, c as AdapterManifest, C as CreateLlmArgs, L as LlmAdapter } from './types-rZZBXYhB.js';
-export { d as ApiKeyAuth, e as AuthKind, f as AzureOpenAIApiKeyAuth, B as BedrockApiKeyAuth, g as BedrockIamAuth, h as ClientOptions, i as ContentBlock, F as FinishReason, j as FormField, k as FormFieldType, G as GoogleApiKeyAuth, l as GoogleServiceAccountAuth, J as JsonSchema, m as LlmEvent, M as Message, n as ModelCapabilities, o as ModelInfo, R as Role, T as Tool, p as ToolCallEvent, U as Usage, V as VertexServiceAccountAuth } from './types-rZZBXYhB.js';
+import { S as ServiceAccountJson, A as AuthSpec, a as AuthKindSchema, P as PromptRequest, b as AdapterFactory, c as AdapterManifest, C as CreateLlmArgs, L as LlmAdapter } from './types-Y0o6rN3B.js';
+export { d as ApiKeyAuth, e as AuthKind, f as AzureOpenAIApiKeyAuth, B as BedrockApiKeyAuth, g as BedrockIamAuth, h as ClientOptions, i as ContentBlock, F as FinishReason, j as FormField, k as FormFieldType, G as GoogleApiKeyAuth, l as GoogleServiceAccountAuth, J as JsonSchema, m as LlmEvent, M as Message, n as ModelCapabilities, o as ModelInfo, R as Role, T as Tool, p as ToolCallEvent, U as Usage, V as VertexServiceAccountAuth } from './types-Y0o6rN3B.js';
 
 /**
  * The loose "DB-shape" input accepted by `normalizeAuth`.
@@ -73,6 +73,7 @@ declare function pickAuthKind(vendor: string, raw: RawCredentialLoose): AuthKind
  *   - `model` is a non-empty string.
  *   - `messages` is a non-empty array.
  *   - `messages` does not contain `role: 'system'` turns (use `system` top-level).
+ *   - `cacheKey`, when present, is a non-empty string.
  */
 declare function assertValidRequest(req: PromptRequest): void;
 

package/dist/index.js

@@ -56,6 +56,9 @@ function assertValidRequest(req) {
       "PromptRequest.messages must not contain role: 'system'. Pass the system prompt via PromptRequest.system instead."
     );
   }
+  if (req.cacheKey !== void 0 && (typeof req.cacheKey !== "string" || req.cacheKey.length === 0)) {
+    throw new Error("PromptRequest.cacheKey must be a non-empty string");
+  }
 }
 
 // src/adapters/openai/_streaming.ts
@@ -80,6 +83,9 @@ async function* streamFromOpenAI(client, req, options) {
     body.tool_choice = "auto";
   }
   if (req.temperature !== void 0) body.temperature = req.temperature;
+  if (req.cacheKey && options.includeCacheKey !== false) {
+    body.prompt_cache_key = req.cacheKey;
+  }
   const effectiveMaxTokens = req.maxTokens ?? options.defaultMaxTokens;
   if (effectiveMaxTokens !== void 0) {
     const param = options.tokensParam ?? (needsMaxCompletionTokens(req.model) ? "max_completion_tokens" : "max_tokens");
@@ -133,10 +139,12 @@ async function* streamFromOpenAI(client, req, options) {
         throw new Error(`OpenAI-compatible stream returned an error: ${message}`);
       }
       if (chunk.usage) {
+        const cachedTokens = chunk.usage.prompt_tokens_details?.cached_tokens;
         usage = {
-          ...chunk.usage.prompt_tokens !== void 0 ? { inputTokens: chunk.usage.prompt_tokens } : {},
+          ...chunk.usage.prompt_tokens !== void 0 ? { inputTokens: chunk.usage.prompt_tokens - (cachedTokens ?? 0) } : {},
           ...chunk.usage.completion_tokens !== void 0 ? { outputTokens: chunk.usage.completion_tokens } : {},
-          ...chunk.usage.total_tokens !== void 0 ? { totalTokens: chunk.usage.total_tokens } : {}
+          ...chunk.usage.total_tokens !== void 0 ? { totalTokens: chunk.usage.total_tokens } : {},
+          ...cachedTokens !== void 0 ? { cacheReadTokens: cachedTokens } : {}
         };
       }
       const choice = chunk.choices?.[0];
@@ -515,7 +523,8 @@ var OpenAIAdapter = class {
   stream(req) {
     return streamFromOpenAI(this.ensureClient(), req, {
       knownModels: this.knownModels(),
-      vendorMetadataExtractor: OPENAI_METADATA_EXTRACTOR
+      vendorMetadataExtractor: OPENAI_METADATA_EXTRACTOR,
+      includeCacheKey: this.forwardCacheKey()
     });
   }
   appendAssistantToolCall(history, toolCalls) {
@@ -536,6 +545,20 @@ var OpenAIAdapter = class {
   knownModels() {
     return openAIManifest.knownModels;
   }
+  /**
+   * Whether to forward `req.cacheKey` as OpenAI's `prompt_cache_key` request
+   * param. Default true — verified accepted by OpenAI, Azure OpenAI,
+   * Vertex-OpenAI, and Baseten. OpenAI-compatible vendors whose param
+   * handling is strict or unverified (DeepSeek, Moonshot, Zai, xAI — and
+   * Groq via its own stream override) override to false: a strict backend
+   * rejects the whole request on an unknown body param, which is far worse
+   * than forgoing a cache-routing hint. Flip a vendor to true only after
+   * verifying its endpoint (including any proxy in front of it, e.g.
+   * Bedrock Mantle) tolerates the param.
+   */
+  forwardCacheKey() {
+    return true;
+  }
   async testCredential() {
     await this.ensureClient().models.list();
   }
@@ -648,6 +671,11 @@ var DeepSeekAdapter = class extends OpenAIAdapter {
   knownModels() {
     return deepseekManifest.knownModels;
   }
+  // DeepSeek caches automatically server-side; prompt_cache_key is
+  // unverified against its param handling — do not forward.
+  forwardCacheKey() {
+    return false;
+  }
 };
 var deepseekFactory = {
   vendor: deepseekManifest.vendor,
@@ -871,6 +899,12 @@ var MoonshotAdapter = class extends OpenAIAdapter {
   knownModels() {
     return moonshotManifest.knownModels;
   }
+  // Moonshot's param handling is strict (e.g. it rejects unknown template
+  // kwargs) and prompt_cache_key is unverified against both the native
+  // endpoint and Bedrock Mantle deployments — do not forward.
+  forwardCacheKey() {
+    return false;
+  }
 };
 var moonshotFactory = {
   vendor: moonshotManifest.vendor,
@@ -944,6 +978,11 @@ var ZaiAdapter = class extends OpenAIAdapter {
   knownModels() {
     return zaiManifest.knownModels;
   }
+  // prompt_cache_key is unverified against Zai's OpenAI-compat endpoint —
+  // do not forward.
+  forwardCacheKey() {
+    return false;
+  }
 };
 var zaiFactory = {
   vendor: zaiManifest.vendor,
@@ -1039,6 +1078,11 @@ var XaiAdapter = class extends OpenAIAdapter {
   knownModels() {
     return xaiManifest.knownModels;
   }
+  // xAI caches automatically server-side; prompt_cache_key is unverified
+  // against its param handling — do not forward.
+  forwardCacheKey() {
+    return false;
+  }
 };
 var xaiFactory = {
   vendor: xaiManifest.vendor,
@@ -1189,6 +1233,16 @@ var AnthropicAdapter = class {
     if (req.system) body.system = req.system;
     if (tools) body.tools = tools;
     if (req.temperature !== void 0) body.temperature = req.temperature;
+    if (req.cacheKey) {
+      if (req.system) {
+        body.system = [{ type: "text", text: req.system, cache_control: { type: "ephemeral" } }];
+      }
+      if (tools) {
+        const lastTool = tools[tools.length - 1];
+        lastTool.cache_control = { type: "ephemeral" };
+      }
+      markLastMessageForCaching(messages);
+    }
     let stream;
     let responseHeaders;
     try {
@@ -1216,6 +1270,8 @@ var AnthropicAdapter = class {
     let stopReason;
     let inputTokens;
     let outputTokens;
+    let cacheReadTokens;
+    let cacheWriteTokens;
     try {
       for await (const event of stream) {
         if (req.signal?.aborted) {
@@ -1225,6 +1281,8 @@ var AnthropicAdapter = class {
         switch (event.type) {
           case "message_start":
             inputTokens = event.message?.usage?.input_tokens;
+            cacheReadTokens = event.message?.usage?.cache_read_input_tokens;
+            cacheWriteTokens = event.message?.usage?.cache_creation_input_tokens;
             break;
           case "content_block_start": {
             const block = event.content_block;
@@ -1306,7 +1364,11 @@ var AnthropicAdapter = class {
     const usage = inputTokens !== void 0 || outputTokens !== void 0 ? {
       ...inputTokens !== void 0 ? { inputTokens } : {},
       ...outputTokens !== void 0 ? { outputTokens } : {},
-      ...inputTokens !== void 0 && outputTokens !== void 0 ? { totalTokens: inputTokens + outputTokens } : {}
+      ...inputTokens !== void 0 && outputTokens !== void 0 ? {
+        totalTokens: inputTokens + outputTokens + (cacheReadTokens ?? 0) + (cacheWriteTokens ?? 0)
+      } : {},
+      ...cacheReadTokens !== void 0 ? { cacheReadTokens } : {},
+      ...cacheWriteTokens !== void 0 ? { cacheWriteTokens } : {}
     } : void 0;
     const endEvent = {
       type: "end",
@@ -1405,6 +1467,23 @@ function buildWireMessages2(req) {
   }
   return out;
 }
+function markLastMessageForCaching(messages) {
+  if (messages.length === 0) return;
+  const last = messages[messages.length - 1];
+  const cacheControl = { cache_control: { type: "ephemeral" } };
+  if (typeof last.content === "string" && last.content.length > 0) {
+    messages[messages.length - 1] = {
+      ...last,
+      content: [{ type: "text", text: last.content, ...cacheControl }]
+    };
+  } else if (Array.isArray(last.content) && last.content.length > 0) {
+    const blocks = last.content;
+    messages[messages.length - 1] = {
+      ...last,
+      content: [...blocks.slice(0, -1), { ...blocks[blocks.length - 1], ...cacheControl }]
+    };
+  }
+}
 function formatTools2(tools) {
   return tools.map((t) => ({
     name: t.name,
@@ -1467,6 +1546,11 @@ async function* streamFromGemini(client, req) {
   if (req.temperature !== void 0) config.temperature = req.temperature;
   if (req.maxTokens !== void 0) config.maxOutputTokens = req.maxTokens;
   if (req.signal) config.abortSignal = req.signal;
+  if (req.providerParams) {
+    for (const [key, value] of Object.entries(req.providerParams)) {
+      if (!(key in config)) config[key] = value;
+    }
+  }
   let stream;
   try {
     stream = await client.models.generateContentStream({
@@ -1487,6 +1571,7 @@ async function* streamFromGemini(client, req) {
   let inputTokens;
   let outputTokens;
   let totalTokens;
+  let cacheReadTokens;
   try {
     for await (const chunk of stream) {
       if (req.signal?.aborted) {
@@ -1495,7 +1580,12 @@ async function* streamFromGemini(client, req) {
       }
       const usage2 = chunk.usageMetadata;
       if (usage2) {
-        if (usage2.promptTokenCount !== void 0) inputTokens = usage2.promptTokenCount;
+        if (usage2.cachedContentTokenCount !== void 0) {
+          cacheReadTokens = usage2.cachedContentTokenCount;
+        }
+        if (usage2.promptTokenCount !== void 0) {
+          inputTokens = usage2.promptTokenCount - (usage2.cachedContentTokenCount ?? 0);
+        }
         if (usage2.candidatesTokenCount !== void 0) outputTokens = usage2.candidatesTokenCount;
         if (usage2.totalTokenCount !== void 0) totalTokens = usage2.totalTokenCount;
       }
@@ -1549,7 +1639,8 @@ async function* streamFromGemini(client, req) {
   const usage = inputTokens !== void 0 || outputTokens !== void 0 || totalTokens !== void 0 ? {
     ...inputTokens !== void 0 ? { inputTokens } : {},
     ...outputTokens !== void 0 ? { outputTokens } : {},
-    ...totalTokens !== void 0 ? { totalTokens } : {}
+    ...totalTokens !== void 0 ? { totalTokens } : {},
+    ...cacheReadTokens !== void 0 ? { cacheReadTokens } : {}
   } : void 0;
   const endEvent = {
     type: "end",
@@ -1691,6 +1782,39 @@ function isAbortError3(err) {
 
 // src/adapters/google/manifest.ts
 var GOOGLE_KNOWN_MODELS = [
+  {
+    id: "gemini-3.6-flash",
+    displayName: "Gemini 3.6 Flash",
+    capabilities: {
+      streaming: true,
+      tools: true,
+      vision: true,
+      systemPrompt: true,
+      maxContextTokens: 1e6
+    }
+  },
+  {
+    id: "gemini-3.5-flash",
+    displayName: "Gemini 3.5 Flash",
+    capabilities: {
+      streaming: true,
+      tools: true,
+      vision: true,
+      systemPrompt: true,
+      maxContextTokens: 1e6
+    }
+  },
+  {
+    id: "gemini-3.5-flash-lite",
+    displayName: "Gemini 3.5 Flash-Lite",
+    capabilities: {
+      streaming: true,
+      tools: true,
+      vision: true,
+      systemPrompt: true,
+      maxContextTokens: 1e6
+    }
+  },
   {
     id: "gemini-2.5-pro",
     displayName: "Gemini 2.5 Pro",
@@ -1834,6 +1958,39 @@ import { GoogleGenAI as GoogleGenAI2 } from "@google/genai";
 
 // src/adapters/vertex-gemini/manifest.ts
 var VERTEX_GEMINI_KNOWN_MODELS = [
+  {
+    id: "gemini-3.6-flash",
+    displayName: "Gemini 3.6 Flash",
+    capabilities: {
+      streaming: true,
+      tools: true,
+      vision: true,
+      systemPrompt: true,
+      maxContextTokens: 1e6
+    }
+  },
+  {
+    id: "gemini-3.5-flash",
+    displayName: "Gemini 3.5 Flash",
+    capabilities: {
+      streaming: true,
+      tools: true,
+      vision: true,
+      systemPrompt: true,
+      maxContextTokens: 1e6
+    }
+  },
+  {
+    id: "gemini-3.5-flash-lite",
+    displayName: "Gemini 3.5 Flash-Lite",
+    capabilities: {
+      streaming: true,
+      tools: true,
+      vision: true,
+      systemPrompt: true,
+      maxContextTokens: 1e6
+    }
+  },
   {
     id: "gemini-2.5-pro",
     displayName: "Gemini 2.5 Pro",
@@ -2523,6 +2680,15 @@ var BedrockAdapter = class {
     if (Object.keys(inferenceConfig).length > 0) {
       commandInput.inferenceConfig = inferenceConfig;
     }
+    if (req.cacheKey) {
+      if (commandInput.system) {
+        commandInput.system.push({ cachePoint: { type: "default" } });
+      }
+      if (tools) {
+        tools.tools.push({ cachePoint: { type: "default" } });
+      }
+      markLastMessageForCaching2(messages);
+    }
     const command = new ConverseStreamCommand(
       commandInput
     );
@@ -2546,6 +2712,8 @@ var BedrockAdapter = class {
     let inputTokens;
     let outputTokens;
     let totalTokens;
+    let cacheReadTokens;
+    let cacheWriteTokens;
     try {
       for await (const event of response.stream) {
         if (req.signal?.aborted) {
@@ -2598,6 +2766,8 @@ var BedrockAdapter = class {
             inputTokens = event.metadata.usage.inputTokens;
             outputTokens = event.metadata.usage.outputTokens;
             totalTokens = event.metadata.usage.totalTokens;
+            cacheReadTokens = event.metadata.usage.cacheReadInputTokens;
+            cacheWriteTokens = event.metadata.usage.cacheWriteInputTokens;
           }
         }
       }
@@ -2624,7 +2794,9 @@ var BedrockAdapter = class {
     const usage = inputTokens !== void 0 || outputTokens !== void 0 || totalTokens !== void 0 ? {
       ...inputTokens !== void 0 ? { inputTokens } : {},
       ...outputTokens !== void 0 ? { outputTokens } : {},
-      ...totalTokens !== void 0 ? { totalTokens } : {}
+      ...totalTokens !== void 0 ? { totalTokens } : {},
+      ...cacheReadTokens !== void 0 ? { cacheReadTokens } : {},
+      ...cacheWriteTokens !== void 0 ? { cacheWriteTokens } : {}
     } : void 0;
     const endEvent = {
       type: "end",
@@ -2732,6 +2904,16 @@ function buildWireMessages3(req) {
   }
   return out;
 }
+function markLastMessageForCaching2(messages) {
+  if (messages.length === 0) return;
+  const last = messages[messages.length - 1];
+  if (Array.isArray(last.content) && last.content.length > 0) {
+    messages[messages.length - 1] = {
+      ...last,
+      content: [...last.content, { cachePoint: { type: "default" } }]
+    };
+  }
+}
 function formatTools4(tools) {
   return tools.map((t) => ({
     toolSpec: {
@@ -3087,7 +3269,10 @@ var GroqAdapter = class extends OpenAIAdapter {
   stream(req) {
     return streamFromOpenAI(this.ensureClient(), req, {
       knownModels: groqManifest.knownModels,
-      vendorMetadataExtractor: GROQ_METADATA_EXTRACTOR
+      vendorMetadataExtractor: GROQ_METADATA_EXTRACTOR,
+      // Groq caches automatically server-side and rejects/ignores undocumented
+      // OpenAI params — do not forward prompt_cache_key.
+      includeCacheKey: false
     });
   }
 };
@@ -3208,7 +3393,10 @@ var HuggingfaceAdapter = class extends OpenAIAdapter {
   stream(req) {
     return streamFromOpenAI(this.ensureClient(), req, {
       knownModels: huggingfaceManifest.knownModels,
-      vendorMetadataExtractor: HUGGINGFACE_METADATA_EXTRACTOR
+      vendorMetadataExtractor: HUGGINGFACE_METADATA_EXTRACTOR,
+      // The HF router fronts many third-party inference providers;
+      // prompt_cache_key is unverified against them — do not forward.
+      includeCacheKey: false
     });
   }
 };