@aigne/anthropic 0.14.16-beta.2 → 0.14.16-beta.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.14.16-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/anthropic-v0.14.16-beta.2...anthropic-v0.14.16-beta.3) (2025-12-19)
+
+
+### Features
+
+* add prompt caching for OpenAI/Gemini/Anthropic and cache token display ([#838](https://github.com/AIGNE-io/aigne-framework/issues/838)) ([46c628f](https://github.com/AIGNE-io/aigne-framework/commit/46c628f180572ea1b955d1a9888aad6145204842))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.72.0-beta.3
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.69-beta.3
+
 ## [0.14.16-beta.2](https://github.com/AIGNE-io/aigne-framework/compare/anthropic-v0.14.16-beta.1...anthropic-v0.14.16-beta.2) (2025-12-19)
 
 

package/lib/cjs/anthropic-chat-model.d.ts

@@ -124,6 +124,9 @@ export declare class AnthropicChatModel extends ChatModel {
         reasoningEffort?: number | "minimal" | "low" | "medium" | "high" | {
             $get: string;
         } | undefined;
+        cacheConfig?: import("@aigne/core").CacheConfig | {
+            $get: string;
+        } | undefined;
     }> | undefined;
     get credential(): {
         apiKey: string | undefined;

package/lib/cjs/anthropic-chat-model.js

@@ -166,10 +166,12 @@ class AnthropicChatModel extends core_1.ChatModel {
                                 model = chunk.message.model;
                                 controller.enqueue({ delta: { json: { model } } });
                             }
-                            const { input_tokens, output_tokens } = chunk.message.usage;
+                            const { input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, } = chunk.message.usage;
                             usage = {
                                 inputTokens: input_tokens,
                                 outputTokens: output_tokens,
+                                cacheCreationInputTokens: cache_creation_input_tokens ?? undefined,
+                                cacheReadInputTokens: cache_read_input_tokens ?? undefined,
                             };
                         }
                         if (chunk.type === "message_delta" && usage) {
@@ -261,14 +263,40 @@ class AnthropicChatModel extends core_1.ChatModel {
     }
 }
 exports.AnthropicChatModel = AnthropicChatModel;
-async function convertMessages({ messages, responseFormat, tools }) {
-    const systemMessages = [];
+/**
+ * Parse cache configuration from model options
+ */
+function parseCacheConfig(modelOptions) {
+    const cacheConfig = modelOptions?.cacheConfig || {};
+    const shouldCache = cacheConfig.enabled !== false; // Default: enabled
+    const ttl = cacheConfig.ttl === "1h" ? "1h" : "5m"; // Default: 5m
+    const strategy = cacheConfig.strategy || "auto"; // Default: auto
+    const autoBreakpoints = {
+        tools: cacheConfig.autoBreakpoints?.tools !== false, // Default: true
+        system: cacheConfig.autoBreakpoints?.system !== false, // Default: true
+        lastMessage: cacheConfig.autoBreakpoints?.lastMessage === true, // Default: false
+    };
+    return {
+        shouldCache,
+        ttl,
+        strategy,
+        autoBreakpoints,
+    };
+}
+async function convertMessages({ messages, responseFormat, tools, modelOptions, }) {
+    const systemBlocks = [];
     const msgs = [];
+    // Extract cache configuration with defaults
+    const { shouldCache, ttl, strategy, autoBreakpoints } = parseCacheConfig(modelOptions);
     for (const msg of messages) {
         if (msg.role === "system") {
             if (typeof msg.content !== "string")
                 throw new Error("System message must have content");
-            systemMessages.push(msg.content);
+            const block = {
+                type: "text",
+                text: msg.content,
+            };
+            systemBlocks.push(block);
         }
         else if (msg.role === "tool") {
             if (!msg.toolCallId)
@@ -314,16 +342,48 @@ async function convertMessages({ messages, responseFormat, tools }) {
     // If there are tools and responseFormat is json_schema, we need to add a system message
     // to inform the model about the expected json schema, then trying to parse the response as json
     if (tools?.length && responseFormat?.type === "json_schema") {
-        systemMessages.push(`You should provide a json response with schema: ${JSON.stringify(responseFormat.jsonSchema.schema)}`);
+        systemBlocks.push({
+            type: "text",
+            text: `You should provide a json response with schema: ${JSON.stringify(responseFormat.jsonSchema.schema)}`,
+        });
+    }
+    // Apply cache_control to the last system block if auto strategy is enabled
+    if (shouldCache && strategy === "auto" && autoBreakpoints.system && systemBlocks.length > 0) {
+        const lastBlock = systemBlocks[systemBlocks.length - 1];
+        if (lastBlock) {
+            lastBlock.cache_control = { type: "ephemeral" };
+            if (ttl === "1h") {
+                lastBlock.cache_control = { type: "ephemeral", ttl: "1h" };
+            }
+        }
+    }
+    // Manual cache control: apply user-specified cacheControl from system messages
+    if (shouldCache && strategy === "manual") {
+        for (const [index, msg] of messages.entries()) {
+            const msgWithCache = msg;
+            if (msg.role === "system" && msgWithCache.cacheControl) {
+                const block = systemBlocks[index];
+                if (block) {
+                    block.cache_control = {
+                        type: msgWithCache.cacheControl.type,
+                        ...(msgWithCache.cacheControl.ttl && { ttl: msgWithCache.cacheControl.ttl }),
+                    };
+                }
+            }
+        }
     }
-    const system = systemMessages.join("\n").trim() || undefined;
     // Claude requires at least one message, so we add a system message if there are no messages
     if (msgs.length === 0) {
-        if (!system)
+        if (systemBlocks.length === 0)
             throw new Error("No messages provided");
-        return { messages: [{ role: "user", content: system }] };
+        // Convert system blocks to a single user message
+        const systemText = systemBlocks.map((b) => b.text).join("\n");
+        return { messages: [{ role: "user", content: systemText }] };
     }
-    return { messages: msgs, system };
+    return {
+        messages: msgs,
+        system: systemBlocks.length > 0 ? systemBlocks : undefined,
+    };
 }
 async function convertContent(content) {
     if (typeof content === "string")
@@ -348,7 +408,7 @@ async function convertContent(content) {
     }
     throw new Error("Invalid chat message content");
 }
-function convertTools({ tools, toolChoice, disableParallelToolUse, }) {
+function convertTools({ tools, toolChoice, disableParallelToolUse, modelOptions, }) {
     let choice;
     if (typeof toolChoice === "object" && "type" in toolChoice && toolChoice.type === "function") {
         choice = {
@@ -369,15 +429,38 @@ function convertTools({ tools, toolChoice, disableParallelToolUse, }) {
     else if (toolChoice === "none") {
         choice = { type: "none" };
     }
+    // Extract cache configuration with defaults
+    const { shouldCache, ttl, strategy, autoBreakpoints } = parseCacheConfig(modelOptions);
+    const shouldCacheTools = shouldCache && strategy === "auto" && autoBreakpoints.tools;
     return {
         tools: tools?.length
-            ? tools.map((i) => ({
-                name: i.function.name,
-                description: i.function.description,
-                input_schema: (0, type_utils_js_1.isEmpty)(i.function.parameters)
-                    ? { type: "object" }
-                    : i.function.parameters,
-            }))
+            ? tools.map((i, index, arr) => {
+                const tool = {
+                    name: i.function.name,
+                    description: i.function.description,
+                    input_schema: (0, type_utils_js_1.isEmpty)(i.function.parameters)
+                        ? { type: "object" }
+                        : i.function.parameters,
+                };
+                // Auto mode: add cache_control to the last tool
+                if (shouldCacheTools && index === arr.length - 1) {
+                    tool.cache_control = { type: "ephemeral" };
+                    if (ttl === "1h") {
+                        tool.cache_control = { type: "ephemeral", ttl: "1h" };
+                    }
+                }
+                // Manual mode: use tool-specific cacheControl if provided
+                else if (shouldCache && strategy === "manual") {
+                    const toolWithCache = i;
+                    if (toolWithCache.cacheControl) {
+                        tool.cache_control = {
+                            type: toolWithCache.cacheControl.type,
+                            ...(toolWithCache.cacheControl.ttl && { ttl: toolWithCache.cacheControl.ttl }),
+                        };
+                    }
+                }
+                return tool;
+            })
             : undefined,
         tool_choice: choice,
     };

package/lib/dts/anthropic-chat-model.d.ts

@@ -124,6 +124,9 @@ export declare class AnthropicChatModel extends ChatModel {
         reasoningEffort?: number | "minimal" | "low" | "medium" | "high" | {
             $get: string;
         } | undefined;
+        cacheConfig?: import("@aigne/core").CacheConfig | {
+            $get: string;
+        } | undefined;
     }> | undefined;
     get credential(): {
         apiKey: string | undefined;

package/lib/esm/anthropic-chat-model.d.ts

@@ -124,6 +124,9 @@ export declare class AnthropicChatModel extends ChatModel {
         reasoningEffort?: number | "minimal" | "low" | "medium" | "high" | {
             $get: string;
         } | undefined;
+        cacheConfig?: import("@aigne/core").CacheConfig | {
+            $get: string;
+        } | undefined;
     }> | undefined;
     get credential(): {
         apiKey: string | undefined;

package/lib/esm/anthropic-chat-model.js

@@ -160,10 +160,12 @@ export class AnthropicChatModel extends ChatModel {
                                 model = chunk.message.model;
                                 controller.enqueue({ delta: { json: { model } } });
                             }
-                            const { input_tokens, output_tokens } = chunk.message.usage;
+                            const { input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, } = chunk.message.usage;
                             usage = {
                                 inputTokens: input_tokens,
                                 outputTokens: output_tokens,
+                                cacheCreationInputTokens: cache_creation_input_tokens ?? undefined,
+                                cacheReadInputTokens: cache_read_input_tokens ?? undefined,
                             };
                         }
                         if (chunk.type === "message_delta" && usage) {
@@ -254,14 +256,40 @@ export class AnthropicChatModel extends ChatModel {
         };
     }
 }
-async function convertMessages({ messages, responseFormat, tools }) {
-    const systemMessages = [];
+/**
+ * Parse cache configuration from model options
+ */
+function parseCacheConfig(modelOptions) {
+    const cacheConfig = modelOptions?.cacheConfig || {};
+    const shouldCache = cacheConfig.enabled !== false; // Default: enabled
+    const ttl = cacheConfig.ttl === "1h" ? "1h" : "5m"; // Default: 5m
+    const strategy = cacheConfig.strategy || "auto"; // Default: auto
+    const autoBreakpoints = {
+        tools: cacheConfig.autoBreakpoints?.tools !== false, // Default: true
+        system: cacheConfig.autoBreakpoints?.system !== false, // Default: true
+        lastMessage: cacheConfig.autoBreakpoints?.lastMessage === true, // Default: false
+    };
+    return {
+        shouldCache,
+        ttl,
+        strategy,
+        autoBreakpoints,
+    };
+}
+async function convertMessages({ messages, responseFormat, tools, modelOptions, }) {
+    const systemBlocks = [];
     const msgs = [];
+    // Extract cache configuration with defaults
+    const { shouldCache, ttl, strategy, autoBreakpoints } = parseCacheConfig(modelOptions);
     for (const msg of messages) {
         if (msg.role === "system") {
             if (typeof msg.content !== "string")
                 throw new Error("System message must have content");
-            systemMessages.push(msg.content);
+            const block = {
+                type: "text",
+                text: msg.content,
+            };
+            systemBlocks.push(block);
         }
         else if (msg.role === "tool") {
             if (!msg.toolCallId)
@@ -307,16 +335,48 @@ async function convertMessages({ messages, responseFormat, tools }) {
     // If there are tools and responseFormat is json_schema, we need to add a system message
     // to inform the model about the expected json schema, then trying to parse the response as json
     if (tools?.length && responseFormat?.type === "json_schema") {
-        systemMessages.push(`You should provide a json response with schema: ${JSON.stringify(responseFormat.jsonSchema.schema)}`);
+        systemBlocks.push({
+            type: "text",
+            text: `You should provide a json response with schema: ${JSON.stringify(responseFormat.jsonSchema.schema)}`,
+        });
+    }
+    // Apply cache_control to the last system block if auto strategy is enabled
+    if (shouldCache && strategy === "auto" && autoBreakpoints.system && systemBlocks.length > 0) {
+        const lastBlock = systemBlocks[systemBlocks.length - 1];
+        if (lastBlock) {
+            lastBlock.cache_control = { type: "ephemeral" };
+            if (ttl === "1h") {
+                lastBlock.cache_control = { type: "ephemeral", ttl: "1h" };
+            }
+        }
+    }
+    // Manual cache control: apply user-specified cacheControl from system messages
+    if (shouldCache && strategy === "manual") {
+        for (const [index, msg] of messages.entries()) {
+            const msgWithCache = msg;
+            if (msg.role === "system" && msgWithCache.cacheControl) {
+                const block = systemBlocks[index];
+                if (block) {
+                    block.cache_control = {
+                        type: msgWithCache.cacheControl.type,
+                        ...(msgWithCache.cacheControl.ttl && { ttl: msgWithCache.cacheControl.ttl }),
+                    };
+                }
+            }
+        }
     }
-    const system = systemMessages.join("\n").trim() || undefined;
     // Claude requires at least one message, so we add a system message if there are no messages
     if (msgs.length === 0) {
-        if (!system)
+        if (systemBlocks.length === 0)
             throw new Error("No messages provided");
-        return { messages: [{ role: "user", content: system }] };
+        // Convert system blocks to a single user message
+        const systemText = systemBlocks.map((b) => b.text).join("\n");
+        return { messages: [{ role: "user", content: systemText }] };
     }
-    return { messages: msgs, system };
+    return {
+        messages: msgs,
+        system: systemBlocks.length > 0 ? systemBlocks : undefined,
+    };
 }
 async function convertContent(content) {
     if (typeof content === "string")
@@ -341,7 +401,7 @@ async function convertContent(content) {
     }
     throw new Error("Invalid chat message content");
 }
-function convertTools({ tools, toolChoice, disableParallelToolUse, }) {
+function convertTools({ tools, toolChoice, disableParallelToolUse, modelOptions, }) {
     let choice;
     if (typeof toolChoice === "object" && "type" in toolChoice && toolChoice.type === "function") {
         choice = {
@@ -362,15 +422,38 @@ function convertTools({ tools, toolChoice, disableParallelToolUse, }) {
     else if (toolChoice === "none") {
         choice = { type: "none" };
     }
+    // Extract cache configuration with defaults
+    const { shouldCache, ttl, strategy, autoBreakpoints } = parseCacheConfig(modelOptions);
+    const shouldCacheTools = shouldCache && strategy === "auto" && autoBreakpoints.tools;
     return {
         tools: tools?.length
-            ? tools.map((i) => ({
-                name: i.function.name,
-                description: i.function.description,
-                input_schema: isEmpty(i.function.parameters)
-                    ? { type: "object" }
-                    : i.function.parameters,
-            }))
+            ? tools.map((i, index, arr) => {
+                const tool = {
+                    name: i.function.name,
+                    description: i.function.description,
+                    input_schema: isEmpty(i.function.parameters)
+                        ? { type: "object" }
+                        : i.function.parameters,
+                };
+                // Auto mode: add cache_control to the last tool
+                if (shouldCacheTools && index === arr.length - 1) {
+                    tool.cache_control = { type: "ephemeral" };
+                    if (ttl === "1h") {
+                        tool.cache_control = { type: "ephemeral", ttl: "1h" };
+                    }
+                }
+                // Manual mode: use tool-specific cacheControl if provided
+                else if (shouldCache && strategy === "manual") {
+                    const toolWithCache = i;
+                    if (toolWithCache.cacheControl) {
+                        tool.cache_control = {
+                            type: toolWithCache.cacheControl.type,
+                            ...(toolWithCache.cacheControl.ttl && { ttl: toolWithCache.cacheControl.ttl }),
+                        };
+                    }
+                }
+                return tool;
+            })
             : undefined,
         tool_choice: choice,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/anthropic",
-  "version": "0.14.16-beta.2",
+  "version": "0.14.16-beta.3",
   "description": "AIGNE Anthropic SDK for integrating with Claude AI models",
   "publishConfig": {
     "access": "public"
@@ -37,7 +37,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.63.0",
     "zod": "^3.25.67",
-    "@aigne/core": "^1.72.0-beta.2",
+    "@aigne/core": "^1.72.0-beta.3",
     "@aigne/platform-helpers": "^0.6.7-beta"
   },
   "devDependencies": {
@@ -46,7 +46,7 @@
     "npm-run-all": "^4.1.5",
     "rimraf": "^6.0.1",
     "typescript": "^5.9.2",
-    "@aigne/test-utils": "^0.5.69-beta.2"
+    "@aigne/test-utils": "^0.5.69-beta.3"
   },
   "scripts": {
     "lint": "tsc --noEmit",