@aigne/anthropic 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.8.0](https://github.com/AIGNE-io/aigne-framework/compare/anthropic-v0.7.2...anthropic-v0.8.0) (2025-07-10)
+
+
+### Features
+
+* **model:** reduce unnecessary LLM requests for structured output ([#241](https://github.com/AIGNE-io/aigne-framework/issues/241)) ([e28813c](https://github.com/AIGNE-io/aigne-framework/commit/e28813c021ed35c0251e198e2e007e2d746ab3d8))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.33.0
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.5
+
 ## [0.7.2](https://github.com/AIGNE-io/aigne-framework/compare/anthropic-v0.7.1...anthropic-v0.7.2) (2025-07-09)
 
 

package/README.md

@@ -6,8 +6,6 @@
 [![NPM Version](https://img.shields.io/npm/v/@aigne/anthropic)](https://www.npmjs.com/package/@aigne/anthropic)
 [![Elastic-2.0 licensed](https://img.shields.io/npm/l/@aigne/anthropic)](https://github.com/AIGNE-io/aigne-framework/blob/main/LICENSE.md)
 
-**English** | [中文](README.zh.md)
-
 AIGNE Anthropic SDK for integrating with Claude AI models within the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework).
 
 ## Introduction

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

@@ -105,12 +105,14 @@ export declare class AnthropicChatModel extends ChatModel {
     protected _client?: Anthropic;
     get client(): Anthropic;
     get modelOptions(): ChatModelOptions | undefined;
+    private getMaxTokens;
     /**
      * Process the input using Claude's chat model
      * @param input - The input to process
      * @returns The processed output from the model
      */
     process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private ajv;
     private _process;
     private extractResultFromAnthropicStream;
     private requestStructuredOutput;

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

@@ -6,10 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnthropicChatModel = exports.claudeChatModelOptionsSchema = void 0;
 const core_1 = require("@aigne/core");
 const json_schema_js_1 = require("@aigne/core/utils/json-schema.js");
+const logger_js_1 = require("@aigne/core/utils/logger.js");
 const model_utils_js_1 = require("@aigne/core/utils/model-utils.js");
 const stream_utils_js_1 = require("@aigne/core/utils/stream-utils.js");
 const type_utils_js_1 = require("@aigne/core/utils/type-utils.js");
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const ajv_1 = require("ajv");
+const jaison_1 = __importDefault(require("jaison"));
 const zod_1 = require("zod");
 const CHAT_MODEL_CLAUDE_DEFAULT_MODEL = "claude-3-7-sonnet-latest";
 /**
@@ -66,12 +69,28 @@ class AnthropicChatModel extends core_1.ChatModel {
         this._client ??= new sdk_1.default({
             apiKey,
             ...this.options?.clientOptions,
+            timeout: this.options?.clientOptions?.timeout ?? 600e3,
         });
         return this._client;
     }
     get modelOptions() {
         return this.options?.modelOptions;
     }
+    getMaxTokens(model) {
+        const matchers = [
+            [/claude-opus-4-/, 32000],
+            [/claude-sonnet-4-/, 64000],
+            [/claude-3-7-sonnet-/, 64000],
+            [/claude-3-5-sonnet-/, 8192],
+            [/claude-3-5-haiku-/, 8192],
+        ];
+        for (const [regex, maxTokens] of matchers) {
+            if (regex.test(model)) {
+                return maxTokens;
+            }
+        }
+        return 4096;
+    }
     /**
      * Process the input using Claude's chat model
      * @param input - The input to process
@@ -80,6 +99,7 @@ class AnthropicChatModel extends core_1.ChatModel {
     process(input) {
         return this._process(input);
     }
+    ajv = new ajv_1.Ajv();
     async _process(input) {
         const model = this.options?.model || CHAT_MODEL_CLAUDE_DEFAULT_MODEL;
         const disableParallelToolUse = input.modelOptions?.parallelToolCalls === false ||
@@ -89,10 +109,15 @@ class AnthropicChatModel extends core_1.ChatModel {
             temperature: input.modelOptions?.temperature ?? this.modelOptions?.temperature,
             top_p: input.modelOptions?.topP ?? this.modelOptions?.topP,
             // TODO: make dynamic based on model https://docs.anthropic.com/en/docs/about-claude/models/all-models
-            max_tokens: /claude-3-[5|7]/.test(model) ? 8192 : 4096,
+            max_tokens: this.getMaxTokens(model),
             ...convertMessages(input),
             ...convertTools({ ...input, disableParallelToolUse }),
         };
+        // Claude does not support json_schema response and tool calls in the same request,
+        // so we need to handle the case where tools are not used and responseFormat is json
+        if (!input.tools?.length && input.responseFormat?.type === "json_schema") {
+            return this.requestStructuredOutput(body, input.responseFormat);
+        }
         const stream = this.client.messages.stream({
             ...body,
             stream: true,
@@ -101,20 +126,26 @@ class AnthropicChatModel extends core_1.ChatModel {
             return this.extractResultFromAnthropicStream(stream, true);
         }
         const result = await this.extractResultFromAnthropicStream(stream);
+        // Just return the result if it has tool calls
+        if (result.toolCalls?.length)
+            return result;
+        // Try to parse the text response as JSON
+        // If it matches the json_schema, return it as json
+        const json = safeParseJSON(result.text || "");
+        if (this.ajv.validate(input.responseFormat.jsonSchema.schema, json)) {
+            return { ...result, json, text: undefined };
+        }
+        logger_js_1.logger.warn(`AnthropicChatModel: Text response does not match JSON schema, trying to use tool to extract json `, { text: result.text });
         // Claude doesn't support json_schema response and tool calls in the same request,
         // so we need to make a separate request for json_schema response when the tool calls is empty
-        if (!result.toolCalls?.length && input.responseFormat?.type === "json_schema") {
-            const output = await this.requestStructuredOutput(body, input.responseFormat);
-            return {
-                ...output,
-                // merge usage from both requests
-                usage: (0, model_utils_js_1.mergeUsage)(result.usage, output.usage),
-            };
-        }
-        return result;
+        const output = await this.requestStructuredOutput(body, input.responseFormat);
+        return {
+            ...output,
+            // merge usage from both requests
+            usage: (0, model_utils_js_1.mergeUsage)(result.usage, output.usage),
+        };
     }
     async extractResultFromAnthropicStream(stream, streaming) {
-        const logs = [];
         const result = new ReadableStream({
             async start(controller) {
                 try {
@@ -136,7 +167,6 @@ class AnthropicChatModel extends core_1.ChatModel {
                         if (chunk.type === "message_delta" && usage) {
                             usage.outputTokens = chunk.usage.output_tokens;
                         }
-                        logs.push(JSON.stringify(chunk));
                         // handle streaming text
                         if (chunk.type === "content_block_delta" && chunk.delta.type === "text_delta") {
                             controller.enqueue({
@@ -223,7 +253,7 @@ class AnthropicChatModel extends core_1.ChatModel {
     }
 }
 exports.AnthropicChatModel = AnthropicChatModel;
-function convertMessages({ messages, responseFormat }) {
+function convertMessages({ messages, responseFormat, tools }) {
     const systemMessages = [];
     const msgs = [];
     for (const msg of messages) {
@@ -273,7 +303,9 @@ function convertMessages({ messages, responseFormat }) {
             }
         }
     }
-    if (responseFormat?.type === "json_schema") {
+    // 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)}`);
     }
     const system = systemMessages.join("\n").trim() || undefined;
@@ -329,3 +361,13 @@ function convertTools({ tools, toolChoice, disableParallelToolUse, }) {
         tool_choice: choice,
     };
 }
+function safeParseJSON(text) {
+    if (!text)
+        return null;
+    try {
+        return (0, jaison_1.default)(text);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -105,12 +105,14 @@ export declare class AnthropicChatModel extends ChatModel {
     protected _client?: Anthropic;
     get client(): Anthropic;
     get modelOptions(): ChatModelOptions | undefined;
+    private getMaxTokens;
     /**
      * Process the input using Claude's chat model
      * @param input - The input to process
      * @returns The processed output from the model
      */
     process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private ajv;
     private _process;
     private extractResultFromAnthropicStream;
     private requestStructuredOutput;

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

@@ -105,12 +105,14 @@ export declare class AnthropicChatModel extends ChatModel {
     protected _client?: Anthropic;
     get client(): Anthropic;
     get modelOptions(): ChatModelOptions | undefined;
+    private getMaxTokens;
     /**
      * Process the input using Claude's chat model
      * @param input - The input to process
      * @returns The processed output from the model
      */
     process(input: ChatModelInput): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    private ajv;
     private _process;
     private extractResultFromAnthropicStream;
     private requestStructuredOutput;

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

@@ -1,9 +1,12 @@
 import { ChatModel, } from "@aigne/core";
 import { parseJSON } from "@aigne/core/utils/json-schema.js";
+import { logger } from "@aigne/core/utils/logger.js";
 import { mergeUsage } from "@aigne/core/utils/model-utils.js";
 import { agentResponseStreamToObject } from "@aigne/core/utils/stream-utils.js";
 import { checkArguments, isEmpty, isNonNullable, } from "@aigne/core/utils/type-utils.js";
 import Anthropic from "@anthropic-ai/sdk";
+import { Ajv } from "ajv";
+import jaison from "jaison";
 import { z } from "zod";
 const CHAT_MODEL_CLAUDE_DEFAULT_MODEL = "claude-3-7-sonnet-latest";
 /**
@@ -60,12 +63,28 @@ export class AnthropicChatModel extends ChatModel {
         this._client ??= new Anthropic({
             apiKey,
             ...this.options?.clientOptions,
+            timeout: this.options?.clientOptions?.timeout ?? 600e3,
         });
         return this._client;
     }
     get modelOptions() {
         return this.options?.modelOptions;
     }
+    getMaxTokens(model) {
+        const matchers = [
+            [/claude-opus-4-/, 32000],
+            [/claude-sonnet-4-/, 64000],
+            [/claude-3-7-sonnet-/, 64000],
+            [/claude-3-5-sonnet-/, 8192],
+            [/claude-3-5-haiku-/, 8192],
+        ];
+        for (const [regex, maxTokens] of matchers) {
+            if (regex.test(model)) {
+                return maxTokens;
+            }
+        }
+        return 4096;
+    }
     /**
      * Process the input using Claude's chat model
      * @param input - The input to process
@@ -74,6 +93,7 @@ export class AnthropicChatModel extends ChatModel {
     process(input) {
         return this._process(input);
     }
+    ajv = new Ajv();
     async _process(input) {
         const model = this.options?.model || CHAT_MODEL_CLAUDE_DEFAULT_MODEL;
         const disableParallelToolUse = input.modelOptions?.parallelToolCalls === false ||
@@ -83,10 +103,15 @@ export class AnthropicChatModel extends ChatModel {
             temperature: input.modelOptions?.temperature ?? this.modelOptions?.temperature,
             top_p: input.modelOptions?.topP ?? this.modelOptions?.topP,
             // TODO: make dynamic based on model https://docs.anthropic.com/en/docs/about-claude/models/all-models
-            max_tokens: /claude-3-[5|7]/.test(model) ? 8192 : 4096,
+            max_tokens: this.getMaxTokens(model),
             ...convertMessages(input),
             ...convertTools({ ...input, disableParallelToolUse }),
         };
+        // Claude does not support json_schema response and tool calls in the same request,
+        // so we need to handle the case where tools are not used and responseFormat is json
+        if (!input.tools?.length && input.responseFormat?.type === "json_schema") {
+            return this.requestStructuredOutput(body, input.responseFormat);
+        }
         const stream = this.client.messages.stream({
             ...body,
             stream: true,
@@ -95,20 +120,26 @@ export class AnthropicChatModel extends ChatModel {
             return this.extractResultFromAnthropicStream(stream, true);
         }
         const result = await this.extractResultFromAnthropicStream(stream);
+        // Just return the result if it has tool calls
+        if (result.toolCalls?.length)
+            return result;
+        // Try to parse the text response as JSON
+        // If it matches the json_schema, return it as json
+        const json = safeParseJSON(result.text || "");
+        if (this.ajv.validate(input.responseFormat.jsonSchema.schema, json)) {
+            return { ...result, json, text: undefined };
+        }
+        logger.warn(`AnthropicChatModel: Text response does not match JSON schema, trying to use tool to extract json `, { text: result.text });
         // Claude doesn't support json_schema response and tool calls in the same request,
         // so we need to make a separate request for json_schema response when the tool calls is empty
-        if (!result.toolCalls?.length && input.responseFormat?.type === "json_schema") {
-            const output = await this.requestStructuredOutput(body, input.responseFormat);
-            return {
-                ...output,
-                // merge usage from both requests
-                usage: mergeUsage(result.usage, output.usage),
-            };
-        }
-        return result;
+        const output = await this.requestStructuredOutput(body, input.responseFormat);
+        return {
+            ...output,
+            // merge usage from both requests
+            usage: mergeUsage(result.usage, output.usage),
+        };
     }
     async extractResultFromAnthropicStream(stream, streaming) {
-        const logs = [];
         const result = new ReadableStream({
             async start(controller) {
                 try {
@@ -130,7 +161,6 @@ export class AnthropicChatModel extends ChatModel {
                         if (chunk.type === "message_delta" && usage) {
                             usage.outputTokens = chunk.usage.output_tokens;
                         }
-                        logs.push(JSON.stringify(chunk));
                         // handle streaming text
                         if (chunk.type === "content_block_delta" && chunk.delta.type === "text_delta") {
                             controller.enqueue({
@@ -216,7 +246,7 @@ export class AnthropicChatModel extends ChatModel {
         };
     }
 }
-function convertMessages({ messages, responseFormat }) {
+function convertMessages({ messages, responseFormat, tools }) {
     const systemMessages = [];
     const msgs = [];
     for (const msg of messages) {
@@ -266,7 +296,9 @@ function convertMessages({ messages, responseFormat }) {
             }
         }
     }
-    if (responseFormat?.type === "json_schema") {
+    // 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)}`);
     }
     const system = systemMessages.join("\n").trim() || undefined;
@@ -322,3 +354,13 @@ function convertTools({ tools, toolChoice, disableParallelToolUse, }) {
         tool_choice: choice,
     };
 }
+function safeParseJSON(text) {
+    if (!text)
+        return null;
+    try {
+        return jaison(text);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/anthropic",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "AIGNE Anthropic SDK for integrating with Claude AI models",
   "publishConfig": {
     "access": "public"
@@ -33,8 +33,10 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.55.1",
+    "ajv": "^8.17.1",
+    "jaison": "^2.0.2",
     "zod": "^3.25.67",
-    "@aigne/core": "^1.32.2"
+    "@aigne/core": "^1.33.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.17",
@@ -42,7 +44,7 @@
     "npm-run-all": "^4.1.5",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
-    "@aigne/test-utils": "^0.5.4"
+    "@aigne/test-utils": "^0.5.5"
   },
   "scripts": {
     "lint": "tsc --noEmit",

package/README.zh.md

@@ -1,116 +0,0 @@
-# @aigne/anthropic
-
-[![GitHub star chart](https://img.shields.io/github/stars/AIGNE-io/aigne-framework?style=flat-square)](https://star-history.com/#AIGNE-io/aigne-framework)
-[![Open Issues](https://img.shields.io/github/issues-raw/AIGNE-io/aigne-framework?style=flat-square)](https://github.com/AIGNE-io/aigne-framework/issues)
-[![codecov](https://codecov.io/gh/AIGNE-io/aigne-framework/graph/badge.svg?token=DO07834RQL)](https://codecov.io/gh/AIGNE-io/aigne-framework)
-[![NPM Version](https://img.shields.io/npm/v/@aigne/anthropic)](https://www.npmjs.com/package/@aigne/anthropic)
-[![Elastic-2.0 licensed](https://img.shields.io/npm/l/@aigne/anthropic)](https://github.com/AIGNE-io/aigne-framework/blob/main/LICENSE.md)
-
-[English](README.md) | **中文**
-
-AIGNE Anthropic SDK，用于在 [AIGNE 框架](https://github.com/AIGNE-io/aigne-framework) 中集成 Anthropic 的 Claude AI 模型。
-
-## 简介
-
-`@aigne/anthropic` 提供了 AIGNE 框架与 Anthropic 的 Claude 语言模型和 API 之间的无缝集成。该包使开发者能够在 AIGNE 应用程序中轻松利用 Anthropic 的 Claude 模型，同时提供框架内一致的接口，充分发挥 Claude 先进的 AI 能力。
-
-## 特性
-
-* **Anthropic API 集成**：使用官方 SDK 直接连接到 Anthropic 的 API 服务
-* **聊天完成**：支持 Claude 的聊天完成 API 和所有可用模型
-* **工具调用**：内置支持 Claude 的工具调用功能
-* **流式响应**：支持流式响应，提供更高响应性的应用程序体验
-* **类型安全**：为所有 API 和模型提供全面的 TypeScript 类型定义
-* **一致接口**：兼容 AIGNE 框架的模型接口
-* **错误处理**：健壮的错误处理和重试机制
-* **完整配置**：丰富的配置选项用于微调行为
-
-## 安装
-
-### 使用 npm
-
-```bash
-npm install @aigne/anthropic @aigne/core
-```
-
-### 使用 yarn
-
-```bash
-yarn add @aigne/anthropic @aigne/core
-```
-
-### 使用 pnpm
-
-```bash
-pnpm add @aigne/anthropic @aigne/core
-```
-
-## 基本用法
-
-```typescript file="test/anthropic-chat-model.test.ts" region="example-anthropic-chat-model"
-import { AnthropicChatModel } from "@aigne/anthropic";
-
-const model = new AnthropicChatModel({
-  // Provide API key directly or use environment variable ANTHROPIC_API_KEY or CLAUDE_API_KEY
-  apiKey: "your-api-key", // Optional if set in env variables
-  // Specify Claude model version (defaults to 'claude-3-7-sonnet-latest')
-  model: "claude-3-haiku-20240307",
-  // Configure model behavior
-  modelOptions: {
-    temperature: 0.7,
-  },
-});
-
-const result = await model.invoke({
-  messages: [{ role: "user", content: "Tell me about yourself" }],
-});
-
-console.log(result);
-/* Output:
-  {
-    text: "I'm Claude, an AI assistant created by Anthropic. How can I help you today?",
-    model: "claude-3-haiku-20240307",
-    usage: {
-      inputTokens: 8,
-      outputTokens: 15
-    }
-  }
-  */
-```
-
-## 流式响应
-
-```typescript file="test/anthropic-chat-model.test.ts" region="example-anthropic-chat-model-streaming-async-generator"
-import { AnthropicChatModel } from "@aigne/anthropic";
-import { isAgentResponseDelta } from "@aigne/core";
-
-const model = new AnthropicChatModel({
-  apiKey: "your-api-key",
-  model: "claude-3-haiku-20240307",
-});
-
-const stream = await model.invoke(
-  {
-    messages: [{ role: "user", content: "Tell me about yourself" }],
-  },
-  { streaming: true },
-);
-
-let fullText = "";
-const json = {};
-
-for await (const chunk of stream) {
-  if (isAgentResponseDelta(chunk)) {
-    const text = chunk.delta.text?.text;
-    if (text) fullText += text;
-    if (chunk.delta.json) Object.assign(json, chunk.delta.json);
-  }
-}
-
-console.log(fullText); // Output: "I'm Claude, an AI assistant created by Anthropic. How can I help you today?"
-console.log(json); // { model: "claude-3-haiku-20240307", usage: { inputTokens: 8, outputTokens: 15 } }
-```
-
-## 许可证
-
-Elastic-2.0