Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
refactor(model): refactor the chat model implementation (#1564)
DavdGaoa063cdb8901e
diff --git a/pyproject.toml b/pyproject.tomlindex 6a684413a..f7a1a63bc 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -51,9 +51,11 @@ dependencies = [# ------------ Model APIs ------------gemini = ["google-genai"]ollama = ["ollama>=0.5.4"]+xai = ["xai-sdk"]models = ["agentscope[ollama]","agentscope[gemini]",+ "agentscope[xai]",]# ------------ Full ------------diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex b582f4d86..40ccd4e0d 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -220,7 +220,7 @@ class Agent:estimated_tokens = await self.model.count_tokens(**kwargs)# Skip if no compression is needed- threshold = cfg.trigger_ratio * self.model.context_length+ threshold = cfg.trigger_ratio * self.model.context_sizeif estimated_tokens < threshold:return@@ -251,7 +251,7 @@ class Agent:msgs_to_compress,msgs_to_reserve,) = await self._split_context_for_compression(- cfg.reserve_ratio * self.model.context_length,+ cfg.reserve_ratio * self.model.context_size,tools,)@@ -268,7 +268,7 @@ class Agent:msgs_to_compress,msgs_to_reserve,) = await self._split_context_for_compression(- 0 * self.model.context_length,+ 0 * self.model.context_size,tools,)@@ -313,12 +313,12 @@ class Agent:messages,compression_tool_schema,)- if estimated_compression_tokens > self.model.context_length:+ if estimated_compression_tokens > self.model.context_size:logger.warning("The current context length exceeds the model's context ""length (%d tokens), the compression maybe failed due to ""insufficient reserved context for compression.",- self.model.context_length,+ self.model.context_size,)context_overflow = True@@ -357,7 +357,7 @@ class Agent:# tokens for compression responseif (estimated_compression_tokens- < self.model.context_length * cfg.trigger_ratio+ < self.model.context_size * cfg.trigger_ratio):break@@ -636,7 +636,7 @@ class Agent:yield ModelCallStartEvent(reply_id=self.state.reply_id,- model_name=self.model.model_name,+ model_name=self.model.model,)# Get the input arguments for the chat model, including messages and@@ -1865,7 +1865,7 @@ class Agent:logger.warning("Model %s call failed for agent %s. ""Retrying (%d/%d)...",- model.model_name,+ model.model,self.name,_ + 1,self.model_config.max_retries,diff --git a/src/agentscope/credential/__init__.py b/src/agentscope/credential/__init__.pynew file mode 100644index 000000000..1084a4c3e--- /dev/null+++ b/src/agentscope/credential/__init__.py@@ -0,0 +1,40 @@+# -*- coding: utf-8 -*-+"""The credential module."""++from ._anthropic import AnthropicCredential+from ._dashscope import DashScopeCredential+from ._deepseek import DeepSeekCredential+from ._gemini import GeminiCredential+from ._kimi import KimiCredential+from ._ollama import OllamaCredential+from ._openai import OpenAICredential+from ._xai import XAICredential++__all__ = [+ "AnthropicCredential",+ "DashScopeCredential",+ "DeepSeekCredential",+ "GeminiCredential",+ "KimiCredential",+ "OllamaCredential",+ "OpenAICredential",+ "XAICredential",+]+++def list_credential() -> list[dict]:+ """List the available credential and their schemas, used for frontend to+ render the credential form."""++ credentials = [+ AnthropicCredential,+ DashScopeCredential,+ DeepSeekCredential,+ GeminiCredential,+ KimiCredential,+ OllamaCredential,+ OpenAICredential,+ XAICredential,+ ]++ return [_.model_json_schema() for _ in credentials]diff --git a/src/agentscope/credential/_anthropic.py b/src/agentscope/credential/_anthropic.pynew file mode 100644index 000000000..8a007a94d--- /dev/null+++ b/src/agentscope/credential/_anthropic.py@@ -0,0 +1,39 @@+# -*- coding: utf-8 -*-+"""The Anthropic credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field, SecretStr, ConfigDict++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase+++class AnthropicCredential(CredentialBase):+ """The Anthropic credential model."""++ model_config = ConfigDict(+ title="Anthropic Credential",+ )++ type: Literal["anthropic_credential"] = "anthropic_credential"+ """The credential type."""++ api_key: SecretStr = Field(+ description="The Anthropic API key",+ )+ """The API key."""++ base_url: str | None = Field(+ description="The base URL for the Anthropic API.",+ default=None,+ )+ """The base URL for the Anthropic API."""++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the AnthropicChatModel class."""+ from ..model import AnthropicChatModel++ return AnthropicChatModeldiff --git a/src/agentscope/credential/_base.py b/src/agentscope/credential/_base.pynew file mode 100644index 000000000..a4db8ccfb--- /dev/null+++ b/src/agentscope/credential/_base.py@@ -0,0 +1,44 @@+# -*- coding: utf-8 -*-+"""The credential base class."""+import uuid+from typing import TYPE_CHECKING, Type++from pydantic import BaseModel, Field++if TYPE_CHECKING:+ from ..model import ChatModelBase, ModelCard+++class CredentialBase(BaseModel):+ """The credential base class."""++ id: str = Field(+ default_factory=lambda: uuid.uuid4().hex,+ description="The credential id",+ )++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the :class:`ChatModelBase` subclass that consumes this+ credential. Subclasses must override this method to return the+ corresponding chat model class.++ Returns:+ `Type[ChatModelBase]`:+ The chat model class that uses this credential.+ """+ raise NotImplementedError(+ f"{cls.__name__} must implement ``get_chat_model_class``.",+ )++ def list_models(self) -> list["ModelCard"]:+ """List the candidate chat models that are available under this+ credential. The default implementation delegates to the+ :meth:`ChatModelBase.list_models` of the class returned by+ :meth:`get_chat_model_class`.++ Returns:+ `list[ModelCard]`:+ A list of candidate models described by their model cards.+ """+ return self.get_chat_model_class().list_models()diff --git a/src/agentscope/credential/_dashscope.py b/src/agentscope/credential/_dashscope.pynew file mode 100644index 000000000..bdcc62762--- /dev/null+++ b/src/agentscope/credential/_dashscope.py@@ -0,0 +1,35 @@+# -*- coding: utf-8 -*-+"""The DashScope credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field, SecretStr++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase+++class DashScopeCredential(CredentialBase):+ """The credential for DashScope API."""++ type: Literal["dashscope_credential"] = "dashscope_credential"+ """The type of the credential."""++ api_key: SecretStr = Field(+ description="The DashScope API key.",+ title="API Key",+ )++ base_http_api_url: str | None = Field(+ default=None,+ title="API Base URL",+ description="The base URL of the DashScope API.",+ )++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the DashScopeChatModel class."""+ from ..model import DashScopeChatModel++ return DashScopeChatModeldiff --git a/src/agentscope/credential/_deepseek.py b/src/agentscope/credential/_deepseek.pynew file mode 100644index 000000000..e337621a8--- /dev/null+++ b/src/agentscope/credential/_deepseek.py@@ -0,0 +1,37 @@+# -*- coding: utf-8 -*-+"""The DeepSeek credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field, SecretStr++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase++_DEEPSEEK_BASE_URL = "https://api.deepseek.com"+++class DeepSeekCredential(CredentialBase):+ """The DeepSeek credential model."""++ type: Literal["deepseek_credential"] = "deepseek_credential"+ """The credential type."""++ api_key: SecretStr = Field(+ description="The DeepSeek API key.",+ )+ """The API key."""++ base_url: str = Field(+ default=_DEEPSEEK_BASE_URL,+ description="The base URL for the DeepSeek API.",+ )+ """The base URL for the DeepSeek API."""++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the DeepSeekChatModel class."""+ from ..model import DeepSeekChatModel++ return DeepSeekChatModeldiff --git a/src/agentscope/credential/_gemini.py b/src/agentscope/credential/_gemini.pynew file mode 100644index 000000000..6b281e443--- /dev/null+++ b/src/agentscope/credential/_gemini.py@@ -0,0 +1,29 @@+# -*- coding: utf-8 -*-+"""The Google Gemini credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field, SecretStr++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase+++class GeminiCredential(CredentialBase):+ """The Google Gemini credential model."""++ type: Literal["gemini_credential"] = "gemini_credential"+ """The credential type."""++ api_key: SecretStr = Field(+ description="The Google Gemini API key.",+ )+ """The API key."""++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the GeminiChatModel class."""+ from ..model import GeminiChatModel++ return GeminiChatModeldiff --git a/src/agentscope/credential/_kimi.py b/src/agentscope/credential/_kimi.pynew file mode 100644index 000000000..3f8369053--- /dev/null+++ b/src/agentscope/credential/_kimi.py@@ -0,0 +1,37 @@+# -*- coding: utf-8 -*-+"""The Kimi (Moonshot AI) credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field, SecretStr++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase++_KIMI_BASE_URL = "https://api.moonshot.cn/v1"+++class KimiCredential(CredentialBase):+ """The Kimi (Moonshot AI) credential model."""++ type: Literal["kimi_credential"] = "kimi_credential"+ """The credential type."""++ api_key: SecretStr = Field(+ description="The Kimi (Moonshot AI) API key.",+ )+ """The API key."""++ base_url: str = Field(+ default=_KIMI_BASE_URL,+ description="The base URL for the Kimi API.",+ )+ """The base URL for the Kimi API."""++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the KimiChatModel class."""+ from ..model import KimiChatModel++ return KimiChatModeldiff --git a/src/agentscope/credential/_ollama.py b/src/agentscope/credential/_ollama.pynew file mode 100644index 000000000..43154095e--- /dev/null+++ b/src/agentscope/credential/_ollama.py@@ -0,0 +1,33 @@+# -*- coding: utf-8 -*-+"""The Ollama credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase+++class OllamaCredential(CredentialBase):+ """The Ollama credential model (connection settings)."""++ type: Literal["ollama_credential"] = "ollama_credential"+ """The credential type."""++ host: str | None = Field(+ default=None,+ description=(+ "The Ollama server host URL. "+ "Defaults to http://localhost:11434 if not specified."+ ),+ )+ """The Ollama server host URL."""++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the OllamaChatModel class."""+ from ..model import OllamaChatModel++ return OllamaChatModeldiff --git a/src/agentscope/credential/_openai.py b/src/agentscope/credential/_openai.pynew file mode 100644index 000000000..24dcc156c--- /dev/null+++ b/src/agentscope/credential/_openai.py@@ -0,0 +1,44 @@+# -*- coding: utf-8 -*-+"""The OpenAI credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field, SecretStr++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase+++class OpenAICredential(CredentialBase):+ """The OpenAI credential model."""++ type: Literal["openai_credential"] = "openai_credential"+ """The credential type."""++ api_key: SecretStr = Field(+ description="The OpenAI API key.",+ )+ """The API key."""++ organization: str | None = Field(+ default=None,+ description="The OpenAI organization ID.",+ )+ """The OpenAI organization ID."""++ base_url: str | None = Field(+ default=None,+ description=(+ "The base URL for the OpenAI API. "+ "Can be used for OpenAI-compatible endpoints."+ ),+ )+ """Custom base URL for OpenAI-compatible endpoints."""++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the OpenAIChatModel class."""+ from ..model import OpenAIChatModel++ return OpenAIChatModeldiff --git a/src/agentscope/credential/_xai.py b/src/agentscope/credential/_xai.pynew file mode 100644index 000000000..17dbb1d80--- /dev/null+++ b/src/agentscope/credential/_xai.py@@ -0,0 +1,29 @@+# -*- coding: utf-8 -*-+"""The xAI credential."""+from typing import Literal, Type, TYPE_CHECKING++from pydantic import Field, SecretStr++from ._base import CredentialBase++if TYPE_CHECKING:+ from ..model import ChatModelBase+++class XAICredential(CredentialBase):+ """The xAI credential model."""++ type: Literal["xai_credential"] = "xai_credential"+ """The credential type."""++ api_key: SecretStr = Field(+ description="The xAI API key.",+ )+ """The xAI API key."""++ @classmethod+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:+ """Return the XAIChatModel class."""+ from ..model import XAIChatModel++ return XAIChatModeldiff --git a/src/agentscope/formatter/__init__.py b/src/agentscope/formatter/__init__.pyindex 974880ce8..6ccf08be7 100644--- a/src/agentscope/formatter/__init__.py+++ b/src/agentscope/formatter/__init__.py@@ -26,6 +26,15 @@ from ._deepseek_formatter import (DeepSeekChatFormatter,DeepSeekMultiAgentFormatter,)+from ._openai_response_formatter import (+ OpenAIResponseFormatter,+ OpenAIResponseMultiAgentFormatter,+)+from ._kimi_formatter import KimiChatFormatter, KimiMultiAgentFormatter+from ._xai_formatter import (+ XAIChatFormatter,+ XAIMultiAgentFormatter,+)__all__ = ["FormatterBase",@@ -41,4 +50,10 @@ __all__ = ["OllamaMultiAgentFormatter","DeepSeekChatFormatter","DeepSeekMultiAgentFormatter",+ "OpenAIResponseFormatter",+ "OpenAIResponseMultiAgentFormatter",+ "KimiChatFormatter",+ "KimiMultiAgentFormatter",+ "XAIChatFormatter",+ "XAIMultiAgentFormatter",]diff --git a/src/agentscope/formatter/_anthropic_formatter.py b/src/agentscope/formatter/_anthropic_formatter.pyindex 0d2061d29..84a09fc6c 100644--- a/src/agentscope/formatter/_anthropic_formatter.py+++ b/src/agentscope/formatter/_anthropic_formatter.py@@ -2,10 +2,12 @@"""The Anthropic formatter module."""import base64import fnmatch+import jsonfrom abc import ABCfrom typing import Anyimport requests+from pydantic import Fieldfrom ._formatter_base import FormatterBasefrom .._logging import logger@@ -26,8 +28,6 @@ class _AnthropicFormatterBase(FormatterBase, ABC):"""Mixin for formatting Anthropic formatters to avoid duplication betweenAnthropicChatFormatter and AnthropicMultiAgentFormatter."""- supported_input_media_types: list[str]-async def _format_messages(self,msgs: list[Msg],@@ -53,6 +53,7 @@ class _AnthropicFormatterBase(FormatterBase, ABC):messages: list[dict] = []for msg in msgs:content_blocks: list = []+ has_tool_result = Falsefor block in msg.get_content_blocks():if isinstance(block, TextBlock):@@ -61,8 +62,16 @@ class _AnthropicFormatterBase(FormatterBase, ABC):)elif isinstance(block, ThinkingBlock):+ # Anthropic requires the signature to be passed back in+ # subsequent requests so the API can verify the thinking+ # block. signature is stored as an extra field and may be+ # absent on blocks from other providers.content_blocks.append(- {"type": "thinking", "thinking": block.thinking},+ {+ "type": "thinking",+ "thinking": block.thinking,+ "signature": getattr(block, "signature", "") or "",+ },)elif isinstance(block, HintBlock):@@ -79,7 +88,9 @@ class _AnthropicFormatterBase(FormatterBase, ABC):"type": "tool_use","id": block.id,"name": block.name,- "input": block.input,+ # Anthropic API expects input as a dict, not a+ # JSON string.+ "input": json.loads(block.input or "{}"),},)@@ -96,58 +107,23 @@ class _AnthropicFormatterBase(FormatterBase, ABC):)for data_block in multimodal_data:+ if not isinstance(data_block, DataBlock):+ continueformatted_block = self._format_anthropic_data_block(data_block,)if formatted_block:tool_result_content.append(formatted_block)- # If there's multimodal data, promote to UserMsg- if multimodal_data:- # Add tool result first- content_blocks.append(- {- "type": "tool_result",- "tool_use_id": block.id,- "content": tool_result_content,- },- )-- # Flush current message- if content_blocks:- messages.append(- {- "role": msg.role,- "content": content_blocks,- },- )- content_blocks = []-- # Insert UserMsg with multimodal data- user_content = []- for data_block in multimodal_data:- formatted_block = (- self._format_anthropic_data_block(data_block)- )- if formatted_block:- user_content.append(formatted_block)-- if user_content:- messages.append(- {- "role": "user",- "content": user_content,- },- )- else:- # No multimodal data, just add tool result- content_blocks.append(- {- "type": "tool_result",- "tool_use_id": block.id,- "content": tool_result_content,- },- )+ content_blocks.append(+ {+ "type": "tool_result",+ "tool_use_id": block.id,+ "content": tool_result_content,+ },+ )+ # Anthropic requires tool_result to be in a "user" message.+ has_tool_result = Trueelse:logger.warning(@@ -156,9 +132,12 @@ class _AnthropicFormatterBase(FormatterBase, ABC):)if content_blocks:+ # Anthropic requires `tool_result` blocks to be in a `user`+ # message regardless of the containing Msg's role.+ role = "user" if has_tool_result else msg.rolemessages.append({- "role": msg.role,+ "role": role,"content": content_blocks,},)@@ -228,7 +207,7 @@ class _AnthropicFormatterBase(FormatterBase, ABC):},}elif isinstance(source, URLSource):- url = source.url+ url = str(source.url)if url.startswith("file://"):# Local file - read and convert to base64file_path = url.removeprefix("file://")@@ -265,21 +244,13 @@ class AnthropicChatFormatter(_AnthropicFormatterBase):entities in the conversation."""- def __init__(- self,- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the Anthropic chat formatter.-- Args:- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types. Defaults to- ``["image/*"]``.- """- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*"],- )+ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*"]``.'+ ),+ )async def format(self,@@ -309,29 +280,22 @@ class AnthropicMultiAgentFormatter(_AnthropicFormatterBase):a user and an agent are involved."""- def __init__(- self,- conversation_history_prompt: str = (+ conversation_history_prompt: str = Field(+ default=("# Conversation History\n""The content between <history></history> tags contains ""your conversation history\n"),- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the Anthropic multi-agent formatter.-- Args:- conversation_history_prompt (`str`):- The prompt to use for the conversation history section.- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types. Defaults to- ``["image/*"]``.- """- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*"],- )- self.conversation_history_prompt = conversation_history_prompt+ description="The prompt to use for the conversation history section.",+ )++ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*"]``.'+ ),+ )async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:"""Format input messages into the structure required by the Anthropicdiff --git a/src/agentscope/formatter/_dashscope_formatter.py b/src/agentscope/formatter/_dashscope_formatter.pyindex 56913d23e..56c9fded0 100644--- a/src/agentscope/formatter/_dashscope_formatter.py+++ b/src/agentscope/formatter/_dashscope_formatter.py@@ -1,15 +1,19 @@# -*- coding: utf-8 -*-"""The dashscope formatter module."""+import base64from typing import Anyfrom fnmatch import fnmatchfrom abc import ABC-from . import FormatterBase+from pydantic import Field++from ._formatter_base import FormatterBasefrom .._logging import loggerfrom ..message import (Msg,TextBlock,+ ThinkingBlock,ToolResultBlock,URLSource,DataBlock,@@ -24,7 +28,38 @@ class _DashScopeFormatterBase(FormatterBase, ABC):"""Base class for DashScope formatters, providing shared data blockformatting logic."""- supported_input_media_types: list[str]+ input_types: list[str] = Field(+ default_factory=lambda: [+ "text/plain",+ "image/*",+ "audio/*",+ "video/*",+ ],+ description=(+ "The supported input types, aligned with the model card's "+ "``input_types`` field. Media types (non ``text/plain`` / "+ "``application/x-thinking`` entries) are used to filter "+ "``DataBlock``\\s; ``application/x-thinking`` enables passing "+ "``reasoning_content`` back to the API."+ ),+ )++ @property+ def supported_input_media_types(self) -> list[str]:+ """Derive supported media types from :attr:`input_types`, excluding+ ``text/plain`` and ``application/x-thinking``."""+ return [+ t+ for t in self.input_types+ if t not in ("text/plain", "application/x-thinking")+ ]++ @property+ def supports_thinking_input(self) -> bool:+ """Return ``True`` if ``application/x-thinking`` is listed in+ :attr:`input_types`, meaning the model accepts ``reasoning_content``+ in the conversation history."""+ return "application/x-thinking" in self.input_typesdef _format_dashscope_data_block(self,@@ -56,7 +91,17 @@ class _DashScopeFormatterBase(FormatterBase, ABC):main_type = block.source.media_type.split("/")[0]if isinstance(block.source, URLSource):- return {main_type: block.source.url}+ url_str = str(block.source.url)+ if url_str.startswith("file://"):+ # Local file — read and encode as base64 data URI+ local_path = url_str.removeprefix("file://")+ with open(local_path, "rb") as f:+ encoded = base64.b64encode(f.read()).decode("utf-8")+ return {+ main_type: f"data:{block.source.media_type};"+ f"base64,{encoded}",+ }+ return {main_type: url_str}if isinstance(block.source, Base64Source):return {@@ -90,22 +135,6 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):list ``[]`` for messages without valid content blocks."""- def __init__(- self,- supported_input_media_type: list[str] | None = None,- ) -> None:- """Initialize the DashScope chat formatter.-- Args:- supported_input_media_type (`list[str] | None`, optional):- The list of supported input media types. Defaults to- ["image/*", "audio/*", "video/*"].- """- super().__init__(- supported_input_media_types=supported_input_media_type- or ["image/*", "audio/*", "video/*"],- )-async def format(self,msgs: list[Msg],@@ -128,6 +157,7 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):msg = msgs[i]content_blocks: list[dict] = []tool_calls = []+ thinking_parts: list[str] = []for block in msg.get_content_blocks():if isinstance(block, TextBlock):@@ -169,6 +199,10 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):},)+ elif isinstance(block, ThinkingBlock):+ if self.supports_thinking_input:+ thinking_parts.append(block.thinking)+elif isinstance(block, ToolResultBlock):(textual_output,@@ -196,6 +230,12 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):),)+ else:+ logger.warning(+ "Unsupported block type %s in the message, skipped.",+ type(block),+ )+msg_dashscope = {"role": msg.role,"content": content_blocks,@@ -204,17 +244,25 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):if tool_calls:msg_dashscope["tool_calls"] = tool_calls+ if thinking_parts:+ msg_dashscope["reasoning_content"] = "\n".join(thinking_parts)+if msg_dashscope["content"] or msg_dashscope.get("tool_calls"):formatted_msgs.append(msg_dashscope)# Move to next messagei += 1- # Merge adjacent text block into one block to avoid API issues+ # Merge adjacent text blocks into one to avoid API issues.+ # Tool-result messages have content as a plain string (not a list),+ # so skip merging for those.cleaned_msgs: list = []- for msg in formatted_msgs:+ for formatted_msg in formatted_msgs:+ if not isinstance(formatted_msg.get("content"), list):+ cleaned_msgs.append(formatted_msg)+ continuenew_content = []- for block in msg["content"]:+ for block in formatted_msg["content"]:if (block.get("text")and new_content@@ -223,8 +271,8 @@ class DashScopeChatFormatter(_DashScopeFormatterBase):new_content[-1]["text"] += "\n" + block["text"]else:new_content.append(block)- msg["content"] = new_content- cleaned_msgs.append(msg)+ formatted_msg["content"] = new_content+ cleaned_msgs.append(formatted_msg)return cleaned_msgs@@ -248,29 +296,14 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):"""- def __init__(- self,- conversation_history_prompt: str = (+ conversation_history_prompt: str = Field(+ description="The conversation history prompt.",+ default=("# Conversation History\n""The content between <history></history> tags contains ""your conversation history\n"),- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the DashScope multi-agent formatter.-- Args:- conversation_history_prompt (`str`):- The prompt to use for the conversation history section.- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types. Defaults to- ["image/*", "audio/*", "video/*"].- """- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*", "audio/*", "video/*"],- )- self.conversation_history_prompt = conversation_history_prompt+ )async def format(self, msgs: list[Msg]) -> list[dict]:"""Format input messages into the structure required by the DashScope@@ -333,7 +366,7 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):A list of dictionaries formatted for the DashScope API."""return await DashScopeChatFormatter(- supported_input_media_type=self.supported_input_media_types,+ input_types=self.input_types,).format(msgs)async def _format_agent_message(@@ -370,7 +403,7 @@ class DashScopeMultiAgentFormatter(_DashScopeFormatterBase):for msg in msgs:for block in msg.get_content_blocks():if isinstance(block, TextBlock):- accumulated_text.append(f"{msg.name}: {block['text']}")+ accumulated_text.append(f"{msg.name}: {block.text}")elif isinstance(block, DataBlock):# Handle the accumulated text as a single blockdiff --git a/src/agentscope/formatter/_deepseek_formatter.py b/src/agentscope/formatter/_deepseek_formatter.pyindex 9328961ee..4302eef49 100644--- a/src/agentscope/formatter/_deepseek_formatter.py+++ b/src/agentscope/formatter/_deepseek_formatter.py@@ -2,6 +2,8 @@"""The DeepSeek formatter module."""from typing import Any+from pydantic import Field+from ._formatter_base import FormatterBasefrom .._logging import loggerfrom ..message import (@@ -20,13 +22,13 @@ class DeepSeekChatFormatter(FormatterBase):entities in the conversation."""- def __init__(- self,- supported_input_media_types: list[str] | None = None,- ) -> None:- super().__init__(- supported_input_media_types=supported_input_media_types or [],- )+ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain"],+ description=(+ 'The supported input types. Defaults to ``["text/plain"]`` '+ "(DeepSeek does not support multimodal input)."+ ),+ )async def format(self,@@ -95,12 +97,19 @@ class DeepSeekChatFormatter(FormatterBase):msg_deepseek: dict[str, Any] = {"role": msg.role,- "content": content_msg or None,+ "content": content_msg or (None if tool_calls else ""),}- if reasoning_content_blocks:- msg_deepseek["reasoning_content"] = "\n".join(- reasoning_content_blocks,+ # DeepSeek requires `reasoning_content` to be present on ALL+ # assistant messages in multi-turn conversations that use thinking+ # mode. When switching from a non-thinking model, historical+ # messages will have no ThinkingBlock, so we always include the+ # field (as None) for assistant messages to keep the context valid.+ if msg.role == "assistant":+ msg_deepseek["reasoning_content"] = (+ "\n".join(reasoning_content_blocks)+ if reasoning_content_blocks+ else "")if tool_calls:@@ -118,28 +127,22 @@ class DeepSeekMultiAgentFormatter(FormatterBase):a user and an agent are involved."""- def __init__(- self,- conversation_history_prompt: str = (+ conversation_history_prompt: str = Field(+ default=("# Conversation History\n""The content between <history></history> tags contains ""your conversation history\n"),- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the DeepSeek multi-agent formatter.-- Args:- conversation_history_prompt (`str`):- The prompt to use for the conversation history section.- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types. Defaults to ``[]``- (DeepSeek does not support multimodal input).- """- super().__init__(- supported_input_media_types=supported_input_media_types or [],- )- self.conversation_history_prompt = conversation_history_prompt+ description="The prompt to use for the conversation history section.",+ )++ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain"],+ description=(+ 'The supported input types. Defaults to ``["text/plain"]`` '+ "(DeepSeek does not support multimodal input)."+ ),+ )async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:"""Format input messages into the structure required by the DeepSeek@@ -179,7 +182,7 @@ class DeepSeekMultiAgentFormatter(FormatterBase):"""Given a sequence of tool call/result messages, format them intothe required format for the DeepSeek API."""return await DeepSeekChatFormatter(- supported_input_media_types=self.supported_input_media_types,+ input_types=self.input_types,).format(msgs)async def _format_agent_message(diff --git a/src/agentscope/formatter/_formatter_base.py b/src/agentscope/formatter/_formatter_base.pyindex 3ac02590e..102451c02 100644--- a/src/agentscope/formatter/_formatter_base.py+++ b/src/agentscope/formatter/_formatter_base.py@@ -8,6 +8,7 @@ from fnmatch import fnmatchfrom typing import Any, List, AsyncGeneratorimport shortuuid+from pydantic import BaseModel, Fieldfrom ..message import (Msg,@@ -18,24 +19,31 @@ from ..message import ()-class FormatterBase:+class FormatterBase(BaseModel):"""The base class for formatters."""- supported_input_media_types: list[str]- """The supported media types for multimodal data in the input messages,- supporting mime types like "image/*", "image/png", "audio/*", "video/*",- etc."""-- def __init__(self, supported_input_media_types: list[str]) -> None:- """Initialize the formatter base class.-- Args:- supported_input_media_types (`list[str]`):- The supported media types for multimodal data in the input- messages, supporting mime types like "image/*", "image/png",- "audio/*", "video/*", etc.- """- self.supported_input_media_types = supported_input_media_types+ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain"],+ description=(+ "The supported input types, aligned with the model card's "+ "``input_types`` field. Entries other than ``text/plain`` and "+ "``application/x-thinking`` are treated as media-type patterns "+ "(glob-style, e.g. ``image/*``, ``audio/mp3``) that control which "+ "``DataBlock``\\s are forwarded to the API."+ ),+ )+ """The supported input types for this formatter, aligned with the model+ card's ``input_types`` field."""++ @property+ def supported_input_media_types(self) -> list[str]:+ """Derive the accepted media-type patterns from :attr:`input_types` by+ excluding ``text/plain`` and ``application/x-thinking``."""+ return [+ t+ for t in self.input_types+ if t not in ("text/plain", "application/x-thinking")+ ]@abstractmethodasync def format(self, *args: Any, **kwargs: Any) -> list[dict[str, Any]]:@@ -118,7 +126,6 @@ class FormatterBase:block,],)- multimodal_data.append(block)# For unsupported media types, if it's a URL, include it in# the textual output; if it's base64 data, save it locallydiff --git a/src/agentscope/formatter/_gemini_formatter.py b/src/agentscope/formatter/_gemini_formatter.pyindex d31b2f17c..16a34d70d 100644--- a/src/agentscope/formatter/_gemini_formatter.py+++ b/src/agentscope/formatter/_gemini_formatter.py@@ -2,10 +2,12 @@"""Google Gemini API formatter in agentscope."""import base64import fnmatch+import jsonfrom abc import ABCfrom typing import Anyimport requests+from pydantic import Fieldfrom ._formatter_base import FormatterBasefrom .._logging import logger@@ -27,8 +29,6 @@ class _GeminiFormatterBase(FormatterBase, ABC):"""Base class for Gemini formatters, providing shared data blockformatting logic."""- supported_input_media_types: list[str]-def _format_gemini_data_block(self,block: DataBlock,@@ -82,7 +82,7 @@ class _GeminiFormatterBase(FormatterBase, ABC):},}elif isinstance(source, URLSource):- url = source.url+ url = str(source.url)if url.startswith("file://"):# Local file - read and convert to base64file_path = url.removeprefix("file://")@@ -115,14 +115,18 @@ class GeminiChatFormatter(_GeminiFormatterBase):entities in the conversation."""- def __init__(- self,- supported_input_media_types: list[str] | None = None,- ) -> None:- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*", "audio/*", "video/*"],- )+ input_types: list[str] = Field(+ default_factory=lambda: [+ "text/plain",+ "image/*",+ "audio/*",+ "video/*",+ ],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*", "audio/*", "video/*"]``.'+ ),+ )async def format(self,@@ -151,7 +155,10 @@ class GeminiChatFormatter(_GeminiFormatterBase):parts.append({"text": block.text})elif isinstance(block, ThinkingBlock):- parts.append({"text": block.thinking})+ # Gemini API requires `thought: true` to mark a part as a+ # thinking/reasoning block so the model can distinguish it+ # from normal text and maintain reasoning continuity.+ parts.append({"thought": True, "text": block.thinking})elif isinstance(block, HintBlock):pass # Gemini does not support hint blocks@@ -165,11 +172,10 @@ class GeminiChatFormatter(_GeminiFormatterBase):parts.append({"function_call": {- "id": None,+ "id": block.id,"name": block.name,- "args": block.input,+ "args": json.loads(block.input or "{}"),},- "thought_signature": block.id,},)@@ -246,29 +252,27 @@ class GeminiMultiAgentFormatter(_GeminiFormatterBase):"""- def __init__(- self,- conversation_history_prompt: str = (+ conversation_history_prompt: str = Field(+ default=("# Conversation History\n""The content between <history></history> tags contains ""your conversation history\n"),- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the Gemini multi-agent formatter.-- Args:- conversation_history_prompt (`str`):- The prompt to be used for the conversation history section.- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types. Defaults to- ``["image/*", "audio/*", "video/*"]``.- """- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*", "audio/*", "video/*"],- )- self.conversation_history_prompt = conversation_history_prompt+ description="The prompt to use for the conversation history section.",+ )++ input_types: list[str] = Field(+ default_factory=lambda: [+ "text/plain",+ "image/*",+ "audio/*",+ "video/*",+ ],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*", "audio/*", "video/*"]``.'+ ),+ )async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:"""Format input messages into the structure required by the Gemini@@ -308,7 +312,7 @@ class GeminiMultiAgentFormatter(_GeminiFormatterBase):"""Given a sequence of tool call/result messages, format them intothe required format for the Gemini API."""return await GeminiChatFormatter(- supported_input_media_types=self.supported_input_media_types,+ input_types=self.input_types,).format(msgs)async def _format_agent_message(diff --git a/src/agentscope/formatter/_kimi_formatter.py b/src/agentscope/formatter/_kimi_formatter.pynew file mode 100644index 000000000..fb6862cc2--- /dev/null+++ b/src/agentscope/formatter/_kimi_formatter.py@@ -0,0 +1,307 @@+# -*- coding: utf-8 -*-+"""The Kimi (Moonshot AI) formatter for agentscope."""+from typing import Any++from pydantic import Field++from ._openai_formatter import _OpenAIFormatterBase+from .._logging import logger+from ..message import (+ Msg,+ TextBlock,+ DataBlock,+ ThinkingBlock,+ HintBlock,+ ToolCallBlock,+ ToolResultBlock,+ UserMsg,+)+++class KimiChatFormatter(_OpenAIFormatterBase):+ """The Kimi formatter for chatbot scenario.++ Kimi's API is OpenAI-compatible, but thinking models (``kimi-k2.6``,+ ``kimi-k2-thinking``) return a ``reasoning_content`` field alongside+ ``content`` in assistant messages. This formatter preserves that field+ when re-sending assistant messages back to the API so that Kimi's+ *Preserved Thinking* feature works correctly in multi-turn conversations.+ """++ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'+ ),+ )++ async def format(+ self,+ msgs: list[Msg],+ ) -> list[dict[str, Any]]:+ """Format messages into the Kimi / OpenAI-compatible API format.++ Behaves identically to :class:`OpenAIChatFormatter` except that+ :class:`ThinkingBlock` content is placed into the ``reasoning_content``+ field of the assistant message dict (required for Preserved Thinking).++ Args:+ msgs (`list[Msg]`):+ The list of message objects to format.++ Returns:+ `list[dict[str, Any]]`:+ The formatted messages as a list of dictionaries.+ """+ self.assert_list_of_msgs(msgs)++ messages: list[dict] = []+ i = 0+ while i < len(msgs):+ msg = msgs[i]+ content_blocks: list[dict] = []+ reasoning_parts: list[str] = []+ tool_calls: list[dict] = []++ for block in msg.get_content_blocks():+ if isinstance(block, ThinkingBlock):+ # Preserve reasoning_content for Kimi's multi-turn+ # Preserved Thinking feature (kimi-k2.6 / kimi-k2-thinking)+ reasoning_parts.append(block.thinking)++ elif isinstance(block, TextBlock):+ content_blocks.append({"type": "text", "text": block.text})++ elif isinstance(block, DataBlock):+ formatted = self._format_openai_data_block(+ block,+ role=msg.role,+ )+ if formatted is not None:+ content_blocks.append(formatted)++ elif isinstance(block, HintBlock):+ if content_blocks or tool_calls:+ msg_kimi = {+ "role": msg.role,+ "name": msg.name,+ "content": content_blocks or None,+ }+ if reasoning_parts:+ msg_kimi["reasoning_content"] = "\n".join(+ reasoning_parts,+ )+ if tool_calls:+ msg_kimi["tool_calls"] = tool_calls+ messages.append(msg_kimi)+ content_blocks = []+ reasoning_parts = []+ tool_calls = []++ elif isinstance(block, ToolCallBlock):+ tool_calls.append(+ {+ "id": block.id,+ "type": "function",+ "function": {+ "name": block.name,+ "arguments": block.input,+ },+ },+ )++ elif isinstance(block, ToolResultBlock):+ (+ textual_output,+ multimodal_data,+ ) = self.convert_tool_result_to_string(block.output)++ messages.append(+ {+ "role": "tool",+ "tool_call_id": block.id,+ "content": textual_output,+ "name": block.name,+ },+ )++ if multimodal_data:+ msgs.insert(+ i + 1,+ UserMsg(+ name="system-reminder",+ content=multimodal_data,+ ),+ )++ else:+ logger.warning(+ "Unsupported block type %s in the message, skipped.",+ type(block),+ )++ msg_kimi = {+ "role": msg.role,+ "name": msg.name,+ "content": content_blocks or None,+ }++ # Kimi's Preserved Thinking requires `reasoning_content` on ALL+ # assistant messages in multi-turn conversations (None when no+ # thinking took place), so that the model can continue its chain+ # of thought correctly.+ if msg.role == "assistant":+ msg_kimi["reasoning_content"] = (+ "\n".join(reasoning_parts) if reasoning_parts else ""+ )++ if tool_calls:+ msg_kimi["tool_calls"] = tool_calls++ if msg_kimi["content"] or msg_kimi.get("tool_calls"):+ messages.append(msg_kimi)++ i += 1++ return messages+++class KimiMultiAgentFormatter(_OpenAIFormatterBase):+ """Formatter for the Kimi (Moonshot AI) API in multi-agent conversations.++ Kimi's API is OpenAI-compatible, so the multi-agent history collapsing+ strategy is the same as :class:`OpenAIMultiAgentFormatter`. Tool+ sequences are delegated to :class:`KimiChatFormatter` so that+ ``reasoning_content`` is preserved correctly for multi-turn+ *Preserved Thinking* conversations.++ .. note:: Telling the assistant's name in the system prompt is important+ in multi-agent conversations so that the model knows which role it+ is playing.+ """++ conversation_history_prompt: str = Field(+ default=(+ "# Conversation History\n"+ "The content between <history></history> tags contains "+ "your conversation history\n"+ ),+ description="The prompt to use for the conversation history section.",+ )++ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'+ ),+ )++ async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:+ """Format input messages into the Kimi API format for multi-agent+ conversations.++ Non-tool messages from all agents are collapsed into a single user+ message with ``<history></history>`` tags. Tool call / result+ sequences are delegated to :class:`KimiChatFormatter`.++ Args:+ msgs (`list[Msg]`):+ The list of message objects to format.++ Returns:+ `list[dict[str, Any]]`:+ The formatted messages as a list of dictionaries.+ """+ self.assert_list_of_msgs(msgs)++ formatted_msgs: list[dict] = []+ start_index = 0+ if msgs and msgs[0].role == "system":+ formatted_msgs.append(+ await self._format_system_message(msgs[0]),+ )+ start_index = 1++ is_first_agent_message = True+ async for typ, group in self._group_messages(msgs[start_index:]):+ if typ == "tool_sequence":+ formatted_msgs.extend(+ await KimiChatFormatter(+ input_types=self.input_types,+ ).format(group),+ )+ elif typ == "agent_message":+ formatted_msgs.extend(+ await self._format_agent_message(+ group,+ is_first_agent_message,+ ),+ )+ is_first_agent_message = False++ return formatted_msgs++ async def _format_tool_sequence(+ self,+ msgs: list[Msg],+ ) -> list[dict[str, Any]]:+ """Format a sequence of tool-related messages using+ KimiChatFormatter."""+ return await KimiChatFormatter(+ input_types=self.input_types,+ ).format(msgs)++ async def _format_agent_message(+ self,+ msgs: list[Msg],+ is_first: bool = True,+ ) -> list[dict[str, Any]]:+ """Collapse agent messages into a ``<history>`` user message."""+ if is_first:+ conversation_history_prompt = self.conversation_history_prompt+ else:+ conversation_history_prompt = ""++ accumulated_text: list[str] = []+ media_blocks: list[dict] = []++ for msg in msgs:+ for block in msg.get_content_blocks():+ if isinstance(block, TextBlock):+ accumulated_text.append(f"{msg.name}: {block.text}")+ elif isinstance(block, DataBlock):+ formatted = self._format_openai_data_block(+ block,+ role=msg.role,+ )+ if formatted is not None:+ media_blocks.append(formatted)++ if not accumulated_text and not media_blocks:+ return []++ history_text = "\n".join(accumulated_text)+ if history_text:+ history_text = (+ conversation_history_prompt+ + "<history>\n"+ + history_text+ + "\n</history>"+ )++ content_list: list[dict[str, Any]] = []+ if history_text:+ content_list.append({"type": "text", "text": history_text})+ content_list.extend(media_blocks)++ return [{"role": "user", "content": content_list}]++ @staticmethod+ async def _format_system_message(msg: Msg) -> dict[str, Any]:+ """Format a system message for the Kimi API."""+ return {+ "role": "system",+ "content": msg.get_text_content(),+ }diff --git a/src/agentscope/formatter/_ollama_formatter.py b/src/agentscope/formatter/_ollama_formatter.pyindex 43f51196d..c20196a3c 100644--- a/src/agentscope/formatter/_ollama_formatter.py+++ b/src/agentscope/formatter/_ollama_formatter.py@@ -2,10 +2,12 @@"""The Ollama formatter module."""import base64import fnmatch+import jsonfrom abc import ABCfrom typing import Anyimport requests+from pydantic import Fieldfrom ._formatter_base import FormatterBasefrom .._logging import logger@@ -16,6 +18,7 @@ from ..message import (DataBlock,ToolCallBlock,ToolResultBlock,+ ThinkingBlock,URLSource,Base64Source,)@@ -25,8 +28,6 @@ class _OllamaFormatterBase(FormatterBase, ABC):"""Base class for Ollama formatters, providing shared data blockformatting logic."""- supported_input_media_types: list[str]-def _format_ollama_data_block(self,block: DataBlock,@@ -81,7 +82,7 @@ class _OllamaFormatterBase(FormatterBase, ABC):if isinstance(source, Base64Source):return source.dataelif isinstance(source, URLSource):- url = source.url+ url = str(source.url)if url.startswith("file://"):# Local file - read and convert to base64file_path = url.removeprefix("file://")@@ -104,14 +105,13 @@ class OllamaChatFormatter(_OllamaFormatterBase):participants in the conversation."""- def __init__(- self,- supported_input_media_types: list[str] | None = None,- ) -> None:- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*"],- )+ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*"]``.'+ ),+ )async def format(self,@@ -146,6 +146,11 @@ class OllamaChatFormatter(_OllamaFormatterBase):if formatted_image:images.append(formatted_image)+ elif isinstance(block, ThinkingBlock):+ # Ollama does not use reasoning content in the context+ # — skip thinking blocks silently.+ pass+elif isinstance(block, ToolCallBlock):messages.append({@@ -157,7 +162,11 @@ class OllamaChatFormatter(_OllamaFormatterBase):{"function": {"name": block.name,- "arguments": block.input,+ # Ollama SDK expects a dict, not a+ # JSON string.+ "arguments": json.loads(+ block.input or "{}",+ ),},},],@@ -172,7 +181,16 @@ class OllamaChatFormatter(_OllamaFormatterBase):multimodal_data,) = self.convert_tool_result_to_string(block.output)- # If there's multimodal data, insert a user message+ # Ollama expects tool results as a separate "tool" role+ # message, regardless of the containing Msg's role.+ messages.append(+ {+ "role": "tool",+ "content": textual_output,+ },+ )++ # If there's multimodal data, append an extra user message.if multimodal_data:user_images = []user_content_parts = []@@ -197,9 +215,6 @@ class OllamaChatFormatter(_OllamaFormatterBase):if user_images:user_msg["images"] = user_imagesmessages.append(user_msg)- else:- # No multimodal data, just add text to content- content_parts.append(textual_output)else:logger.warning(@@ -228,29 +243,22 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):a user and an agent are involved."""- def __init__(- self,- conversation_history_prompt: str = (+ conversation_history_prompt: str = Field(+ default=("# Conversation History\n""The content between <history></history> tags contains ""your conversation history\n"),- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the Ollama multi-agent formatter.-- Args:- conversation_history_prompt (`str`):- The prompt to use for the conversation history section.- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types. Defaults to- ``["image/*"]``.- """- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*"],- )- self.conversation_history_prompt = conversation_history_prompt+ description="The prompt to use for the conversation history section.",+ )++ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*"]``.'+ ),+ )async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:"""Format input messages into the structure required by the Ollama@@ -289,7 +297,7 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):) -> list[dict[str, Any]]:"""Format a sequence of tool-related messages."""return await OllamaChatFormatter(- supported_input_media_types=self.supported_input_media_types,+ input_types=self.input_types,).format(msgs)async def _format_agent_message(@@ -314,8 +322,8 @@ class OllamaMultiAgentFormatter(_OllamaFormatterBase):formatted_image = self._format_ollama_data_block(block)if formatted_image:images.append(formatted_image)- elif isinstance(block, HintBlock):- pass # Ollama does not support hint blocks+ elif isinstance(block, (HintBlock, ThinkingBlock)):+ pass # Ollama does not use hint/thinking blockselse:logger.warning("Unsupported block type %s in agent message, skipped.",diff --git a/src/agentscope/formatter/_openai_formatter.py b/src/agentscope/formatter/_openai_formatter.pyindex 490023cab..1cdcb17ef 100644--- a/src/agentscope/formatter/_openai_formatter.py+++ b/src/agentscope/formatter/_openai_formatter.py@@ -7,8 +7,9 @@ from typing import Anyfrom urllib.parse import urlparseimport requests+from pydantic import Field-from . import FormatterBase+from ._formatter_base import FormatterBasefrom .._logging import loggerfrom ..message import (Msg,@@ -19,6 +20,7 @@ from ..message import (ToolCallBlock,ToolResultBlock,HintBlock,+ ThinkingBlock,UserMsg,)@@ -27,8 +29,6 @@ class _OpenAIFormatterBase(FormatterBase, ABC):"""Base class for OpenAI formatters, providing shared data blockformatting logic."""- supported_input_media_types: list[str]-def _format_openai_data_block(self,block: DataBlock,@@ -105,15 +105,16 @@ class _OpenAIFormatterBase(FormatterBase, ABC):url = f"data:{source.media_type};base64,{source.data}"elif isinstance(source, URLSource):- if source.url.startswith("file://"):+ url_str = str(source.url)+ if url_str.startswith("file://"):# Local file — read and encode as base64 data URI- local_path = source.url.removeprefix("file://")+ local_path = url_str.removeprefix("file://")with open(local_path, "rb") as f:encoded = base64.b64encode(f.read()).decode("utf-8")url = f"data:{source.media_type};base64,{encoded}"else:# Remote URL — pass through as-is- url = source.url+ url = url_strelse:raise ValueError(f"Unsupported image source type: {type(source)}")@@ -156,9 +157,10 @@ class _OpenAIFormatterBase(FormatterBase, ABC):}if isinstance(source, URLSource):- if source.url.startswith("file://"):+ url_str = str(source.url)+ if url_str.startswith("file://"):# Local file- local_path = source.url.removeprefix("file://")+ local_path = url_str.removeprefix("file://")extension = local_path.rsplit(".", 1)[-1].lower()if extension not in ["wav", "mp3"]:raise TypeError(@@ -169,14 +171,14 @@ class _OpenAIFormatterBase(FormatterBase, ABC):data = base64.b64encode(f.read()).decode("utf-8")else:# Remote URL — download and encode- parsed = urlparse(source.url)+ parsed = urlparse(url_str)extension = parsed.path.rsplit(".", 1)[-1].lower()if extension not in ["wav", "mp3"]:raise TypeError(f"Unsupported audio file extension: {extension}, ""wav and mp3 are supported.",)- response = requests.get(source.url)+ response = requests.get(url_str)response.raise_for_status()data = base64.b64encode(response.content).decode("utf-8")@@ -197,22 +199,13 @@ class OpenAIChatFormatter(_OpenAIFormatterBase):identify different entities in the conversation."""- def __init__(- self,- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the OpenAI chat formatter.-- Args:- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types, using glob-style- patterns (e.g. ``"image/*"``, ``"audio/mp3"``). Defaults to- ``["image/*", "audio/*"]``.- """- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*", "audio/*"],- )+ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'+ ),+ )async def format(self,@@ -302,6 +295,11 @@ class OpenAIChatFormatter(_OpenAIFormatterBase):),)+ elif isinstance(block, ThinkingBlock):+ # OpenAI API does not accept reasoning/thinking content+ # in conversation history — skip thinking blocks silently.+ pass+else:logger.warning("Unsupported block type %s in the message, skipped.",@@ -336,30 +334,22 @@ class OpenAIMultiAgentFormatter(_OpenAIFormatterBase):OpenAI-compatible services like vLLM, Azure OpenAI, and others."""- def __init__(- self,- conversation_history_prompt: str = (+ conversation_history_prompt: str = Field(+ default=("# Conversation History\n""The content between <history></history> tags contains ""your conversation history\n"),- supported_input_media_types: list[str] | None = None,- ) -> None:- """Initialize the OpenAI multi-agent formatter.-- Args:- conversation_history_prompt (`str`):- The prompt to use for the conversation history section.- supported_input_media_types (`list[str] | None`, optional):- The list of supported input media types, using glob-style- patterns (e.g. ``"image/*"``, ``"audio/mp3"``). Defaults to- ``["image/*", "audio/*"]``.- """- super().__init__(- supported_input_media_types=supported_input_media_types- or ["image/*", "audio/*"],- )- self.conversation_history_prompt = conversation_history_prompt+ description="The prompt to use for the conversation history section.",+ )++ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'+ ),+ )async def format(self, msgs: list[Msg]) -> list[dict[str, Any]]:"""Format input messages into the structure required by the OpenAI API@@ -399,7 +389,7 @@ class OpenAIMultiAgentFormatter(_OpenAIFormatterBase):"""Given a sequence of tool call/result messages, format them intothe required format for the OpenAI API."""return await OpenAIChatFormatter(- supported_input_media_types=self.supported_input_media_types,+ input_types=self.input_types,).format(msgs)async def _format_agent_message(diff --git a/src/agentscope/formatter/_openai_response_formatter.py b/src/agentscope/formatter/_openai_response_formatter.pynew file mode 100644index 000000000..71a19c405--- /dev/null+++ b/src/agentscope/formatter/_openai_response_formatter.py@@ -0,0 +1,391 @@+# -*- coding: utf-8 -*-+"""Formatters for the OpenAI Responses API."""+from abc import ABC+from typing import Any++from pydantic import Field++from ._openai_formatter import _OpenAIFormatterBase+from .._logging import logger+from ..message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ HintBlock,+ ThinkingBlock,+ UserMsg,+)+++class _OpenAIResponseFormatterBase(_OpenAIFormatterBase, ABC):+ """Base class for OpenAI Responses API formatters.++ Provides the shared ``_format_response_data_block`` helper used by both+ :class:`OpenAIResponseFormatter` (chat) and+ :class:`OpenAIResponseMultiAgentFormatter` (multi-agent).+ """++ input_types: list[str] = Field(+ default_factory=lambda: ["text/plain", "image/*", "audio/*"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/*", "audio/*"]``.'+ ),+ )++ def _format_response_data_block(+ self,+ block: DataBlock,+ role: str = "user",+ ) -> dict[str, Any] | None:+ """Format a DataBlock into the Response API format.++ Args:+ block (`DataBlock`):+ The DataBlock to format.+ role (`str`, defaults to ``"user"``):+ The role of the message that contains this block.++ Returns:+ `dict[str, Any] | None`:+ A dictionary in the Responses API format, or ``None`` when the+ block type is unsupported.+ """+ base_result = self._format_openai_data_block(block, role)+ if base_result is None:+ return None++ if base_result.get("type") == "image_url":+ return {+ "type": "input_image",+ "image_url": base_result["image_url"]["url"],+ }++ return base_result+++class OpenAIResponseFormatter(_OpenAIResponseFormatterBase):+ """Formatter for the OpenAI Responses API in chat (single-agent) mode.++ Produces input items compatible with ``client.responses.create(+ input=...)``.+ Compared with the Chat Completions format, the key differences are:++ * Text content blocks use ``input_text`` instead of ``text``.+ * Image content blocks use ``input_image`` instead of ``image_url``.+ * Assistant tool-call messages become top-level ``function_call`` items.+ * Tool result messages become ``function_call_output`` items.+ * Reasoning items (``ThinkingBlock`` with ``reasoning_item_id``) are+ echoed back verbatim as required by reasoning models (e.g. ``o1``).+ """++ async def format(+ self,+ msgs: list[Msg],+ ) -> list[dict[str, Any]]:+ """Format message objects into OpenAI Response API input items.++ Args:+ msgs (`list[Msg]`):+ The list of Msg objects to format.++ Returns:+ `list[dict[str, Any]]`:+ A list of input items for ``client.responses.create``.+ """+ self.assert_list_of_msgs(msgs)++ items: list[dict] = []+ i = 0+ while i < len(msgs):+ msg = msgs[i]+ content_parts: list[dict] = []+ function_calls: list[dict] = []++ for block in msg.get_content_blocks():+ if isinstance(block, TextBlock):+ content_parts.append(+ {"type": "input_text", "text": block.text},+ )++ elif isinstance(block, DataBlock):+ formatted = self._format_response_data_block(+ block,+ role=msg.role,+ )+ if formatted is not None:+ content_parts.append(formatted)++ elif isinstance(block, HintBlock):+ if content_parts:+ items.append(+ {+ "role": msg.role,+ "content": content_parts,+ },+ )+ content_parts = []++ elif isinstance(block, ThinkingBlock):+ # When reasoning_item_id is present the block originated+ # from a Responses API "reasoning" output item. The API+ # requires that such items are echoed back verbatim in+ # multi-turn history (especially when they precede a+ # function_call). Without the ID we skip silently.+ reasoning_item_id = getattr(+ block,+ "reasoning_item_id",+ None,+ )+ if reasoning_item_id:+ if content_parts:+ items.append(+ {+ "role": msg.role,+ "content": content_parts,+ },+ )+ content_parts = []+ # summary may be empty when the model did not produce+ # reasoning summary text (e.g. o4-mini with streaming)+ summary = (+ [{"type": "summary_text", "text": block.thinking}]+ if block.thinking+ else []+ )+ items.append(+ {+ "type": "reasoning",+ "id": reasoning_item_id,+ "summary": summary,+ "content": [],+ },+ )++ elif isinstance(block, ToolCallBlock):+ # The Responses API distinguishes two identifiers on a+ # function_call item:+ # id → fc_xxx: the item identifier used when+ # echoing the item in multi-turn history+ # call_id → call_xxx: the identifier that must be+ # echoed in the matching function_call_output+ # For other APIs (Chat Completions, DashScope …) only one+ # ID exists; call_id extra field is None and we fall back+ # to id for both fields.+ function_calls.append(+ {+ "type": "function_call",+ "id": block.id,+ "call_id": getattr(block, "call_id", None)+ or block.id,+ "name": block.name,+ "arguments": block.input,+ },+ )++ elif isinstance(block, ToolResultBlock):+ (+ textual_output,+ multimodal_data,+ ) = self.convert_tool_result_to_string(block.output)++ items.append(+ {+ "type": "function_call_output",+ "call_id": block.id,+ "output": textual_output,+ },+ )++ if multimodal_data:+ msgs.insert(+ i + 1,+ UserMsg(+ name="system-reminder",+ content=multimodal_data,+ ),+ )++ else:+ logger.warning(+ "Unsupported block type %s in the message, skipped.",+ type(block),+ )++ if function_calls:+ if content_parts:+ items.append(+ {+ "role": msg.role,+ "content": content_parts,+ },+ )+ items.extend(function_calls)+ elif content_parts:+ items.append(+ {+ "role": msg.role,+ "content": content_parts,+ },+ )++ i += 1++ return items+++class OpenAIResponseMultiAgentFormatter(_OpenAIResponseFormatterBase):+ """Formatter for the OpenAI Responses API in multi-agent mode.++ Handles conversations where more than a user and a single agent are+ involved. Tool call/result sequences are formatted with the Responses API+ ``function_call`` / ``function_call_output`` items (delegated to+ :class:`OpenAIResponseFormatter`). Agent conversation history messages+ are wrapped inside ``<history></history>`` tags and presented as a single+ ``user`` input item.+ """++ conversation_history_prompt: str = Field(+ default=(+ "# Conversation History\n"+ "The content between <history></history> tags contains "+ "your conversation history\n"+ ),+ description="The prompt to use for the conversation history section.",+ )++ async def format(+ self,+ msgs: list[Msg],+ ) -> list[dict[str, Any]]:+ """Format messages for multi-agent Responses API conversations.++ Args:+ msgs (`list[Msg]`):+ The list of Msg objects to format.++ Returns:+ `list[dict[str, Any]]`:+ A list of input items for ``client.responses.create``.+ """+ self.assert_list_of_msgs(msgs)++ formatted_msgs: list[dict] = []+ start_index = 0+ if len(msgs) > 0 and msgs[0].role == "system":+ formatted_msgs.append(+ await self._format_system_message(msgs[0]),+ )+ start_index = 1++ is_first_agent_message = True+ async for typ, group in self._group_messages(msgs[start_index:]):+ if typ == "tool_sequence":+ formatted_msgs.extend(+ await self._format_tool_sequence(group),+ )+ elif typ == "agent_message":+ formatted_msgs.extend(+ await self._format_agent_message(+ group,+ is_first_agent_message,+ ),+ )+ is_first_agent_message = False++ return formatted_msgs++ async def _format_tool_sequence(+ self,+ msgs: list[Msg],+ ) -> list[dict[str, Any]]:+ """Format a sequence of tool call/result messages using the Responses+ API format.++ Args:+ msgs (`list[Msg]`):+ The tool call/result messages to format.++ Returns:+ `list[dict[str, Any]]`:+ A list of Responses API input items.+ """+ return await OpenAIResponseFormatter(+ input_types=self.input_types,+ ).format(msgs)++ async def _format_agent_message(+ self,+ msgs: list[Msg],+ is_first: bool = True,+ ) -> list[dict[str, Any]]:+ """Format a sequence of agent messages as a history-wrapped user item.++ Args:+ msgs (`list[Msg]`):+ The agent messages to format.+ is_first (`bool`, defaults to ``True``):+ Whether this is the first agent message group, which triggers+ the conversation history prompt.++ Returns:+ `list[dict[str, Any]]`:+ A list containing at most one user input item.+ """+ conversation_history_prompt = (+ self.conversation_history_prompt if is_first else ""+ )++ accumulated_text: list[str] = []+ media_blocks: list[dict] = []++ for msg in msgs:+ for block in msg.get_content_blocks():+ if isinstance(block, TextBlock):+ accumulated_text.append(f"{msg.name}: {block.text}")+ elif isinstance(block, DataBlock):+ formatted = self._format_response_data_block(+ block,+ role=msg.role,+ )+ if formatted is not None:+ media_blocks.append(formatted)++ if not accumulated_text and not media_blocks:+ return []++ history_text = "\n".join(accumulated_text)+ wrapped = (+ conversation_history_prompt+ + "<history>\n"+ + history_text+ + "\n</history>"+ )++ content_list: list[dict[str, Any]] = [+ {"type": "input_text", "text": wrapped},+ ]+ content_list.extend(media_blocks)++ return [{"role": "user", "content": content_list}]++ @staticmethod+ async def _format_system_message(+ msg: Msg,+ ) -> dict[str, Any]:+ """Format a system message for the Responses API.++ Args:+ msg (`Msg`):+ The system message to format.++ Returns:+ `dict[str, Any]`:+ A dictionary with ``role`` and ``content`` keys.+ """+ return {+ "role": "system",+ "content": msg.get_text_content(),+ }diff --git a/src/agentscope/formatter/_xai_formatter.py b/src/agentscope/formatter/_xai_formatter.pynew file mode 100644index 000000000..bfb665951--- /dev/null+++ b/src/agentscope/formatter/_xai_formatter.py@@ -0,0 +1,335 @@+# -*- coding: utf-8 -*-+"""The xAI formatter module.++This formatter converts AgentScope ``Msg`` objects into the protobuf+``Message`` objects expected by the ``xai_sdk`` gRPC client. Unlike every+other formatter, the ``format()`` method returns a list of+``chat_pb2.Message`` proto objects rather than plain dicts, because the+``xai_sdk`` chat API accepts proto messages directly.+"""+import base64+from typing import Any, List++from pydantic import Field++from ._formatter_base import FormatterBase+from .._logging import logger+from ..message import (+ Msg,+ TextBlock,+ ThinkingBlock,+ ToolCallBlock,+ ToolResultBlock,+ DataBlock,+ URLSource,+ Base64Source,+ HintBlock,+)+++class XAIChatFormatter(FormatterBase):+ """Formatter for the xAI chat model.++ Converts ``Msg`` objects into ``xai_sdk`` protobuf ``Message`` objects+ that can be appended directly to a ``xai_sdk`` chat session.++ Unlike other formatters whose ``format()`` returns ``list[dict]``, this+ formatter returns ``list[chat_pb2.Message]``. The type annotation is+ intentionally widened to ``list[Any]`` to accommodate this difference.+ """++ input_types: list[str] = Field(+ default=["text/plain", "image/jpeg", "image/png"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/jpeg", "image/png"]``.'+ ),+ )++ async def format(+ self,+ msgs: list[Msg],+ **kwargs: Any,+ ) -> List[Any]:+ """Convert a list of ``Msg`` objects to ``xai_sdk`` proto messages.++ Args:+ msgs (`list[Msg]`):+ A list of ``Msg`` objects representing the conversation.+ **kwargs (`Any`):+ Unused; retained for interface compatibility.++ Returns:+ `list[Any]`:+ A list of ``chat_pb2.Message`` proto objects, ready to be+ appended to a ``xai_sdk`` chat session via+ ``chat.append()``.+ """+ from xai_sdk.chat import (+ assistant,+ image,+ system,+ tool_result,+ user,+ chat_pb2,+ )++ self.assert_list_of_msgs(msgs)++ xai_messages: List[Any] = []++ for msg in msgs:+ blocks = msg.get_content_blocks()++ text_blocks = [b for b in blocks if isinstance(b, TextBlock)]+ tool_call_blocks = [+ b for b in blocks if isinstance(b, ToolCallBlock)+ ]+ tool_result_blocks = [+ b for b in blocks if isinstance(b, ToolResultBlock)+ ]++ if msg.role == "system":+ text = "\n".join(b.text for b in text_blocks)+ xai_messages.append(system(text))++ elif msg.role == "user":+ content_args: list = []+ for block in blocks:+ if isinstance(block, (HintBlock, ThinkingBlock)):+ pass+ elif isinstance(block, TextBlock):+ content_args.append(block.text)+ elif isinstance(block, DataBlock):+ if block.source.media_type.startswith("image/"):+ if isinstance(block.source, URLSource):+ url_str = str(block.source.url)+ if url_str.startswith("file://"):+ # Local file — read and encode as data URI+ local_path = url_str.removeprefix(+ "file://",+ )+ with open(local_path, "rb") as f:+ encoded = base64.b64encode(+ f.read(),+ ).decode("utf-8")+ content_args.append(+ image(+ f"data:{block.source.media_type};"+ f"base64,{encoded}",+ ),+ )+ else:+ content_args.append(image(url_str))+ elif isinstance(block.source, Base64Source):+ content_args.append(+ image(+ f"data:{block.source.media_type};"+ f"base64,{block.source.data}",+ ),+ )+ else:+ logger.warning(+ "Unsupported media type %s for xAI API. "+ "Only image/jpeg and image/png are supported. "+ "This block will be skipped.",+ block.source.media_type,+ )+ else:+ logger.warning(+ "Unsupported block type %s in user message, "+ "skipped.",+ type(block).__name__,+ )++ if content_args:+ xai_messages.append(user(*content_args))++ elif msg.role == "assistant":+ if tool_result_blocks:+ # Convert each ToolResultBlock to a tool_result message.+ for tr_block in tool_result_blocks:+ output_text = self._extract_result_text(+ tr_block.output,+ )+ xai_messages.append(+ tool_result(+ output_text,+ tool_call_id=tr_block.id,+ ),+ )++ elif tool_call_blocks:+ # Assistant turn that triggered tool calls (history).+ msg_proto = chat_pb2.Message()+ msg_proto.role = chat_pb2.MessageRole.Value(+ "ROLE_ASSISTANT",+ )+ if text_blocks:+ c = msg_proto.content.add()+ c.text = "\n".join(b.text for b in text_blocks)+ for tc in tool_call_blocks:+ proto_tc = msg_proto.tool_calls.add()+ proto_tc.id = tc.id+ proto_tc.type = chat_pb2.ToolCallType.Value(+ "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL",+ )+ proto_tc.function.name = tc.name+ proto_tc.function.arguments = tc.input+ xai_messages.append(msg_proto)++ else:+ # Regular assistant text message.+ text = "\n".join(b.text for b in text_blocks)+ if text:+ xai_messages.append(assistant(text))++ else:+ logger.warning(+ "Unsupported message role '%s', skipped.",+ msg.role,+ )++ return xai_messages++ def _extract_result_text(self, output: Any) -> str:+ """Extract a plain-text string from a ``ToolResultBlock`` output.++ Args:+ output (`Any`):+ The raw output of a ``ToolResultBlock``, which may be a+ string, a list of blocks, or another type.++ Returns:+ `str`:+ A plain-text representation of the output.+ """+ if output is None:+ return ""+ if isinstance(output, str):+ return output+ if isinstance(output, list):+ parts = []+ for item in output:+ if isinstance(item, TextBlock):+ parts.append(item.text)+ elif isinstance(item, str):+ parts.append(item)+ else:+ parts.append(str(item))+ return "\n".join(parts)+ return str(output)+++class XAIMultiAgentFormatter(FormatterBase):+ """Formatter for the xAI chat model in multi-agent conversations.++ Produces ``xai_sdk`` protobuf ``Message`` objects (same as+ :class:`XAIChatFormatter`). Prior agent-to-agent messages are collapsed+ into a single ``user`` message with ``<history></history>`` tags; tool+ call / result sequences are delegated to :class:`XAIChatFormatter`.++ .. note:: ``format()`` returns ``list[Any]`` (protobuf messages), not+ ``list[dict]``.+ """++ conversation_history_prompt: str = Field(+ default=(+ "# Conversation History\n"+ "The content between <history></history> tags contains "+ "your conversation history\n"+ ),+ description="The prompt to use for the conversation history section.",+ )++ input_types: list[str] = Field(+ default=["text/plain", "image/jpeg", "image/png"],+ description=(+ "The supported input types. "+ 'Defaults to ``["text/plain", "image/jpeg", "image/png"]``.'+ ),+ )++ async def format(+ self,+ msgs: list[Msg],+ **kwargs: Any,+ ) -> List[Any]:+ """Convert a list of ``Msg`` objects to ``xai_sdk`` proto messages.++ Conversation history (non-tool messages) is collapsed into a single+ ``user`` protobuf message containing ``<history></history>`` tags.+ Tool sequences are formatted by :class:`XAIChatFormatter`.++ Args:+ msgs (`list[Msg]`):+ A list of ``Msg`` objects representing the conversation.+ **kwargs (`Any`):+ Unused; retained for interface compatibility.++ Returns:+ `list[Any]`:+ A list of ``chat_pb2.Message`` proto objects.+ """+ from xai_sdk.chat import system, user++ self.assert_list_of_msgs(msgs)++ xai_messages: List[Any] = []+ start_index = 0++ if msgs and msgs[0].role == "system":+ text = msgs[0].get_text_content()+ xai_messages.append(system(text))+ start_index = 1++ is_first_agent_message = True+ async for typ, group in self._group_messages(msgs[start_index:]):+ if typ == "tool_sequence":+ xai_messages.extend(+ await XAIChatFormatter(+ input_types=self.input_types,+ ).format(group),+ )+ elif typ == "agent_message":+ history_text = self._build_history_text(+ group,+ is_first=is_first_agent_message,+ )+ if history_text:+ xai_messages.append(user(history_text))+ is_first_agent_message = False++ return xai_messages++ def _build_history_text(self, msgs: list[Msg], *, is_first: bool) -> str:+ """Build a ``<history>…</history>`` text block from agent messages.++ Args:+ msgs (`list[Msg]`):+ Non-tool messages to collapse into history.+ is_first (`bool`):+ When ``True``, prepend+ :attr:`conversation_history_prompt` before the tag.++ Returns:+ `str`:+ The formatted history string, or an empty string when there+ is no text content.+ """+ lines: list[str] = []+ for msg in msgs:+ parts: list[str] = []+ if msg.name:+ parts.append(f"{msg.name}:")+ for block in msg.get_content_blocks():+ if isinstance(block, TextBlock):+ parts.append(block.text)+ if parts:+ lines.append(" ".join(parts))++ if not lines:+ return ""++ prefix = self.conversation_history_prompt if is_first else ""+ return prefix + "<history>\n" + "\n".join(lines) + "\n</history>"diff --git a/src/agentscope/message/_block.py b/src/agentscope/message/_block.pyindex 56fbd7d0b..2b557f0b9 100644--- a/src/agentscope/message/_block.py+++ b/src/agentscope/message/_block.py@@ -18,7 +18,14 @@ class TextBlock(BaseModel):class ThinkingBlock(BaseModel):- """The thinking block."""+ """The thinking block.++ Allows extra provider-specific fields (e.g. Anthropic's ``signature``)+ via ``extra="allow"`` so that model implementations can pass+ arbitrary metadata without subclassing.+ """++ model_config = ConfigDict(extra="allow")type: Literal["thinking"] = "thinking""""The type of the thinking block, which is always 'thinking'."""@@ -94,9 +101,13 @@ class ToolCallState(StrEnum):class ToolCallBlock(BaseModel):- """The tool call block."""+ """The tool call block.- model_config = ConfigDict(use_enum_values=True)+ Allows extra provider-specific fields (e.g. the OpenAI Responses API's+ ``call_id``) via ``extra="allow"`` without requiring subclassing.+ """++ model_config = ConfigDict(use_enum_values=True, extra="allow")type: Literal["tool_call"] = "tool_call""""The type of the tool call block, which is always 'tool_call'."""diff --git a/src/agentscope/model/__init__.py b/src/agentscope/model/__init__.pyindex f164a88ae..3394c037c 100644--- a/src/agentscope/model/__init__.py+++ b/src/agentscope/model/__init__.py@@ -1,74 +1,33 @@# -*- coding: utf-8 -*-"""The model module."""-from typing import Any, Type-from ._model_base import ChatModelBase+from ._base import ChatModelBase+from ._model_card import ModelCardfrom ._model_response import ChatResponse, StructuredResponse-from ._dashscope_model import DashScopeChatModel-from ._openai_model import OpenAIChatModel-from ._anthropic_model import AnthropicChatModel-from ._ollama_model import OllamaChatModel-from ._gemini_model import GeminiChatModelfrom ._model_usage import ChatUsage--# Built-in model classes (internal use only)-_BUILTIN_MODELS: list[Type[ChatModelBase]] = [- DashScopeChatModel,- OpenAIChatModel,- AnthropicChatModel,- OllamaChatModel,- GeminiChatModel,-]---def _deserialize_model(- data: dict[str, Any],- custom_classes: list[Type[ChatModelBase]] | None = None,- context: dict[str, Any] | None = None,-) -> ChatModelBase:- """Deserialize a chat model from a dictionary.-- Args:- data: Dictionary containing serialized model data with 'type' field.- custom_classes: Optional list of custom model classes to support.- context: Optional context dict to pass to nested validators.-- Returns:- Deserialized model instance.-- Raises:- ValueError: If 'type' field is missing or unknown.- """- if "type" not in data:- raise ValueError("Model data must contain 'type' field")-- type_value = data["type"]-- all_classes = _BUILTIN_MODELS + (custom_classes or [])- registry = {- cls.model_fields["type"].default: cls- for cls in all_classes- if "type" in cls.model_fields- and cls.model_fields["type"].default is not None- }-- if type_value not in registry:- raise ValueError(- f"Unknown model type '{type_value}'. "- f"Available types: {list(registry.keys())}",- )-- return registry[type_value].model_validate(data, context=context)-+from ._anthropic import AnthropicChatModel+from ._dashscope import DashScopeChatModel+from ._deepseek import DeepSeekChatModel+from ._gemini import GeminiChatModel+from ._ollama import OllamaChatModel+from ._openai_chat import OpenAIChatModel+from ._xai import XAIChatModel+from ._kimi import KimiChatModel+from ._openai_response import OpenAIResponseModel__all__ = ["ChatUsage","ChatModelBase","ChatResponse",+ "ModelCard","StructuredResponse",- "DashScopeChatModel",- "OpenAIChatModel","AnthropicChatModel",- "OllamaChatModel",+ "DashScopeChatModel",+ "DeepSeekChatModel","GeminiChatModel",+ "OllamaChatModel",+ "OpenAIChatModel",+ "XAIChatModel",+ "KimiChatModel",+ "OpenAIResponseModel",]diff --git a/src/agentscope/model/_anthropic/__init__.py b/src/agentscope/model/_anthropic/__init__.pynew file mode 100644index 000000000..fd62e62a5--- /dev/null+++ b/src/agentscope/model/_anthropic/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""The Anthropic LLM API modules."""++from ._model import AnthropicCredential, AnthropicChatModel++__all__ = [+ "AnthropicCredential",+ "AnthropicChatModel",+]diff --git a/src/agentscope/model/_anthropic_model.py b/src/agentscope/model/_anthropic/_model.pysimilarity index 64%rename from src/agentscope/model/_anthropic_model.pyrename to src/agentscope/model/_anthropic/_model.pyindex 39e826cce..830d8f0cf 100644--- a/src/agentscope/model/_anthropic_model.py+++ b/src/agentscope/model/_anthropic/_model.py@@ -1,119 +1,101 @@# -*- coding: utf-8 -*--"""The Anthropic API model classes."""-from datetime import datetime-from typing import (- Any,- AsyncGenerator,- TYPE_CHECKING,- List,- Literal,-)+"""The Anthropic chat model implementation."""from collections import OrderedDict+from datetime import datetime+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List-from pydantic import BaseModel+from pydantic import BaseModel, Field-from ._model_base import ChatModelBase-from ._model_response import ChatResponse-from ._model_usage import ChatUsage-from ..formatter import FormatterBase, AnthropicChatFormatter-from ..message import TextBlock, ToolCallBlock, ThinkingBlock-from ..tool import ToolChoice-from ..tracing import trace_llm-from ..types import JSONSerializableObject+from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import AnthropicCredential+from ...formatter import FormatterBase, AnthropicChatFormatter+from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...tool import ToolChoice+from ...tracing import trace_llmif TYPE_CHECKING:from anthropic.types.message import Messagefrom anthropic import AsyncStreamelse:- Message = "anthropic.types.message.Message"- AsyncStream = "anthropic.AsyncStream"+ Message = Any+ AsyncStream = Anyclass AnthropicChatModel(ChatModelBase):- """The Anthropic model wrapper for AgentScope."""+ """The Anthropic chat model."""++ type: Literal["anthropic_chat"] = "anthropic_chat"+ """The type of the chat model."""++ class Parameters(BaseModel):+ """The parameters for the Anthropic chat model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description=(+ "The maximum number of tokens to generate in the chat "+ "completion."+ ),+ gt=0,+ )- class ThinkingConfig(BaseModel):- """Configuration for Claude's internal reasoning process."""+ thinking_enable: bool = Field(+ default=False,+ title="Thinking",+ description="The thinking enable for the LLM output.",+ )- enable_thinking: bool- budget_tokens: int = 1024+ thinking_budget: int | None = Field(+ default=None,+ title="Thinking budget",+ description="The thinking budget for the LLM output.",+ gt=0,+ )def __init__(self,- model_name: str,- context_length: int,- api_key: str | None = None,- max_tokens: int = 2048,+ credential: AnthropicCredential,+ model: str,+ parameters: "AnthropicChatModel.Parameters | None" = None,stream: bool = True,- max_retries: int = 0,- fallback_model_name: str | None = None,+ max_retries: int = 3,+ context_size: int = 200000,formatter: FormatterBase | None = None,- thinking_config: ThinkingConfig | None = None,- stream_tool_parsing: bool = True,- client_kwargs: dict[str, JSONSerializableObject] | None = None,- generate_kwargs: dict[str, JSONSerializableObject] | None = None,) -> None:"""Initialize the Anthropic chat model.Args:- model_name (`str`):- The model names.- context_length (`int`):- The context length of the model, used in context compression.- api_key (`str`):- The anthropic API key.- max_tokens (`int`):- Limit the maximum token count the model can generate.- stream (`bool`):- The streaming output or not- max_retries (`int`, optional):- Maximum number of retries on failure. Defaults to 0.- fallback_model_name (`str | None`, optional):- Fallback model name to use after all retries fail.- formatter (`FormatterBase | None`, optional):- Formatter for message preprocessing.- thinking_config (`ThinkingConfig | None`, default `None`):- Configuration for Claude's internal reasoning process.- stream_tool_parsing (`bool`, default to `True`):- Whether to parse incomplete tool use JSON during streaming- with auto-repair. If True, partial JSON (e.g., `'{"a": "x'`)- is repaired to valid dicts ({"a": "x"}) in real-time for- immediate tool function input. Otherwise, the input field- remains {} until the final chunk arrives.- client_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments to initialize the Anthropic client.- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments used in Anthropic API generation,- e.g. `temperature`, `seed`.+ credential (`AnthropicCredential`):+ The Anthropic credential used to authenticate API calls.+ model (`str`):+ The Anthropic model name, e.g. ``claude-opus-4-7``.+ parameters (`AnthropicChatModel.Parameters | None`, defaults to \+ `None`):+ The Anthropic API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the Anthropic API.+ context_size (`int`, defaults to `200000`):+ The model context size used for context compression.+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the Anthropic API. When ``None``, an+ ``AnthropicChatFormatter`` instance will be used."""-- try:- import anthropic- except ImportError as e:- raise ImportError(- "Please install the `anthropic` package by running "- "`pip install anthropic`.",- ) from e-super().__init__(- model_name=model_name,+ model=model,stream=stream,- context_length=context_length,max_retries=max_retries,- fallback_model_name=fallback_model_name,- formatter=formatter or AnthropicChatFormatter(),- )-- self.client = anthropic.AsyncAnthropic(- api_key=api_key,- **(client_kwargs or {}),+ context_size=context_size,)- self.max_tokens = max_tokens- self.thinking_config = thinking_config- self.stream_tool_parsing = stream_tool_parsing- self.generate_kwargs = generate_kwargs or {}+ self.credential = credential+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or AnthropicChatFormatter()@trace_llmasync def _call_api(@@ -121,7 +103,7 @@ class AnthropicChatModel(ChatModelBase):model_name: str,messages: list[dict[str, Any]],tools: list[dict] | None = None,- tool_choice: Literal["auto", "none", "required"] | str | None = None,+ tool_choice: ToolChoice | None = None,**generate_kwargs: Any,) -> ChatResponse | AsyncGenerator[ChatResponse, None]:"""Get the response from Anthropic chat completions API by the given@@ -135,29 +117,47 @@ class AnthropicChatModel(ChatModelBase):required, and `name` field is optional.tools (`list[dict]`, default `None`):The tools JSON schemas.- tool_choice (`Literal["auto", "none", "required"] | str \- | None`, default `None`):+ tool_choice (`ToolChoice | None`, optional):Controls which (if any) tool is called by the model.**generate_kwargs (`Any`):The keyword arguments for Anthropic chat completions API.Returns:`ChatResponse | AsyncGenerator[ChatResponse, None]`:- The response from the Anthropic chat completions API."""+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """++ import anthropic++ client = anthropic.AsyncAnthropic(+ api_key=self.credential.api_key.get_secret_value(),+ base_url=self.credential.base_url,+ )++ # Anthropic requires max_tokens; fall back to a safe default when+ # the user hasn't configured one explicitly.+ max_tokens = self.parameters.max_tokens or 8192kwargs: dict[str, Any] = {"model": model_name,- "max_tokens": self.max_tokens,+ "max_tokens": max_tokens,"stream": self.stream,- **self.generate_kwargs,**generate_kwargs,}- if self.thinking_config and "thinking" not in kwargs:++ # Anthropic extended thinking — only set when explicitly enabled.+ # Anthropic requires max_tokens > budget_tokens strictly.+ if self.parameters.thinking_enable and "thinking" not in kwargs:+ budget = self.parameters.thinking_budget or (max_tokens // 2)+ if budget >= max_tokens:+ # Auto-expand max_tokens to satisfy the strict inequality.+ max_tokens = budget + 1024+ kwargs["max_tokens"] = max_tokenskwargs["thinking"] = {- "type": "enabled"- if self.thinking_config.enable_thinking- else "disabled",- "budget_tokens": self.thinking_config.budget_tokens,+ "type": "enabled",+ "budget_tokens": budget,}if tools:@@ -169,16 +169,18 @@ class AnthropicChatModel(ChatModelBase):tools,)+ formatted_messages = await self.formatter.format(messages)+# Extract the system message- if messages[0]["role"] == "system":- kwargs["system"] = messages[0]["content"]- messages = messages[1:]+ if formatted_messages and formatted_messages[0]["role"] == "system":+ kwargs["system"] = formatted_messages[0]["content"]+ formatted_messages = formatted_messages[1:]- kwargs["messages"] = messages+ kwargs["messages"] = formatted_messagesstart_datetime = datetime.now()- response = await self.client.messages.create(**kwargs)+ response = await client.messages.create(**kwargs)if self.stream:return self._parse_anthropic_stream_completion_response(@@ -209,8 +211,9 @@ class AnthropicChatModel(ChatModelBase):Anthropic Message object to parse.Returns:- ChatResponse (`ChatResponse`):- A ChatResponse object containing the content blocks and usage.+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True`` containing+ the extracted content blocks and usage."""content_blocks: List[ThinkingBlock | TextBlock | ToolCallBlock] = []@@ -222,8 +225,9 @@ class AnthropicChatModel(ChatModelBase):):thinking_block = ThinkingBlock(thinking=content_block.thinking,+ signature=getattr(content_block, "signature", "")+ or "",)- thinking_block["signature"] = content_block.signaturecontent_blocks.append(thinking_block)elif (@@ -281,22 +285,21 @@ class AnthropicChatModel(ChatModelBase):response (`AsyncStream`):Anthropic AsyncStream object to parse.- Returns:- `AsyncGenerator[ChatResponse, None]`:- An async generator that yields ChatResponse objects containing- the content blocks and usage information for each chunk in- the streaming response.+ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True`` containing the+ fully accumulated content blocks and usage."""usage = Noneresponse_id: str | None = None- # Accumulated state- acc_text = ""- acc_thinking = ""+ # All delta should have the same block identifier+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")thinking_signature = ""- acc_tool_calls: OrderedDict = (- OrderedDict()- ) # index -> {id, name, input}+ # index -> {id, name, input}+ acc_tool_calls: OrderedDict = OrderedDict()async for event in response:delta_content: list = []@@ -330,12 +333,17 @@ class AnthropicChatModel(ChatModelBase):block_index = event.indexdelta = event.deltaif delta.type == "text_delta":- acc_text += delta.text- delta_content.append(TextBlock(text=delta.text))+ acc_text.text += delta.text+ delta_content.append(+ TextBlock(id=acc_text.id, text=delta.text),+ )elif delta.type == "thinking_delta":- acc_thinking += delta.thinking+ acc_thinking.thinking += delta.thinkingdelta_content.append(- ThinkingBlock(thinking=delta.thinking),+ ThinkingBlock(+ id=acc_thinking.id,+ thinking=delta.thinking,+ ),)elif delta.type == "signature_delta":thinking_signature = delta.signature@@ -370,12 +378,11 @@ class AnthropicChatModel(ChatModelBase):# Build final accumulated contentfinal_content: list = []- if acc_thinking:- thinking_block = ThinkingBlock(thinking=acc_thinking)- thinking_block["signature"] = thinking_signature- final_content.append(thinking_block)- if acc_text:- final_content.append(TextBlock(text=acc_text))+ if acc_thinking.thinking:+ acc_thinking.signature = thinking_signature+ final_content.append(acc_thinking)+ if acc_text.text:+ final_content.append(acc_text)for tc in acc_tool_calls.values():input_str = tc["input"]final_content.append(diff --git a/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml b/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yamlnew file mode 100644index 000000000..feae8f167--- /dev/null+++ b/src/agentscope/model/_anthropic/_models/claude-haiku-4-5.yaml@@ -0,0 +1,21 @@+name: claude-haiku-4-5+label: Claude Haiku 4.5+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 200000+output_size: 65536++parameter_overrides:+ max_tokens: {"maximum": 65536}diff --git a/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml b/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yamlnew file mode 100644index 000000000..a3a9beee1--- /dev/null+++ b/src/agentscope/model/_anthropic/_models/claude-opus-4-7.yaml@@ -0,0 +1,21 @@+name: claude-opus-4-7+label: Claude Opus 4.7+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 128000++parameter_overrides:+ max_tokens: {"maximum": 128000}diff --git a/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yamlnew file mode 100644index 000000000..61d22d04c--- /dev/null+++ b/src/agentscope/model/_anthropic/_models/claude-sonnet-4-6.yaml@@ -0,0 +1,21 @@+name: claude-sonnet-4-6+label: Claude Sonnet 4.6+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 65536++parameter_overrides:+ max_tokens: {"maximum": 65536}diff --git a/src/agentscope/model/_model_base.py b/src/agentscope/model/_base.pysimilarity index 71%rename from src/agentscope/model/_model_base.pyrename to src/agentscope/model/_base.pyindex 54d1b4a2e..b0376260e 100644--- a/src/agentscope/model/_model_base.py+++ b/src/agentscope/model/_base.py@@ -1,92 +1,125 @@# -*- coding: utf-8 -*--"""The chat model base class."""+"""The base class for the chat models."""+import inspectimport jsonfrom abc import abstractmethodfrom copy import deepcopy-from typing import AsyncGenerator, Any, TYPE_CHECKING, Type+from pathlib import Path+from typing import Type, Any, AsyncGeneratorimport jsonschemafrom pydantic import BaseModel-from ._model_response import ChatResponse, StructuredResponse+from ._model_response import StructuredResponse, ChatResponse+from ._model_card import ModelCardfrom .._logging import loggerfrom .._utils._common import _json_loads_with_repair-from ..formatter import FormatterBasefrom ..message import (Msg,TextBlock,- ThinkingBlock,+ UserMsg,ToolCallBlock,+ ThinkingBlock,ToolResultBlock,DataBlock,URLSource,Base64Source,- UserMsg,)--if TYPE_CHECKING:- from ..tool import ToolChoice-else:- ToolChoice = Any+from ..tool import ToolChoice_TOOL_CHOICE_MODES = ["auto", "none", "required"]class ChatModelBase:- """Base class for chat models."""+ """The base class for chat models."""- model_name: str- """The model name"""+ class Parameters(BaseModel):+ """Each subclass should implement this inner class to define its+ parameters."""++ model: str+ """The model name."""stream: bool- """Is the model output streaming or not"""+ """The enable stream output for the LLM output."""max_retries: int- """Maximum number of retries on failure"""-- context_length: int- """The context length of the model, which will be used in context- compression."""+ """The maximum retries for the Anthropic API."""- fallback_model_name: str | None- """Fallback model name to use after all retries fail"""-- formatter: FormatterBase- """The API formatter that format the messages into the required format for- the underlying API."""+ context_size: int+ """The model context size that will be used in the context compression."""def __init__(self,- model_name: str,- stream: bool,- context_length: int,- formatter: FormatterBase,- max_retries: int = 0,- fallback_model_name: str | None = None,+ model: str,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 32768,) -> None:- """Initialize the chat model base class.+ """Initialize the chat model base.Args:- model_name (`str`):- The name of the model- stream (`bool`):- Whether the model output is streaming or not- context_length (`int`):- The context length of the model, which will be used- in context compression.- formatter (`FormatterBase`):- Formatter for message preprocessing.- max_retries (`int`, optional):- Maximum number of retries on failure. Defaults to 0.- fallback_model_name (`str | None`, optional):- Fallback model name to use after all retries fail.+ model (`str`):+ The model name.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output for the LLM.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for API calls.+ context_size (`int`, defaults to `32768`):+ The model context size used for context compression."""- self.model_name = model_name+ self.model = modelself.stream = stream- self.context_length = context_lengthself.max_retries = max_retries- self.fallback_model_name = fallback_model_name- self.formatter = formatter+ self.context_size = context_size++ @classmethod+ def list_models(+ cls,+ custom_yaml_dir: str | None = None,+ ) -> list[ModelCard]:+ """List candidate models of the API.++ Args:+ custom_yaml_dir (`str | None`):+ The custom YAML directory.++ Returns:+ `list[ModelCard]`:+ A list of candidate models.+ """++ # Determine YAML directory+ if custom_yaml_dir is None:+ # Use the ``_models`` directory that sits next to the concrete+ # subclass's source file (not this base file).+ subclass_file = Path(inspect.getfile(cls))+ yaml_dir = subclass_file.parent / "_models"+ else:+ yaml_dir = Path(custom_yaml_dir)++ # Find all .yaml files+ yaml_files = list(yaml_dir.glob("*.yaml"))++ # Load each YAML file and create ModelCard+ model_cards = []+ for yaml_file in yaml_files:+ try:+ card = ModelCard.from_yaml(+ yaml_path=str(yaml_file),+ parameter_class=cls.Parameters,+ )+ model_cards.append(card)+ except Exception as e:+ # Log error but continue with other files+ logger.warning(+ "Warning: Failed to load %s: %s",+ yaml_file,+ str(e),+ )+ continue++ return model_cardsasync def __call__(self,@@ -114,42 +147,38 @@ class ChatModelBase:last_error: Exception | None = None- for model_name in self._models_to_try():- for attempt in range(self.max_retries + 1):- try:- return await self._call_api(- model_name,- messages=messages,- tools=tools,- tool_choice=tool_choice,- **kwargs,+ for attempt in range(self.max_retries + 1):+ try:+ return await self._call_api(+ self.model,+ messages=messages,+ tools=tools,+ tool_choice=tool_choice,+ **kwargs,+ )+ except Exception as e:+ last_error = e+ if attempt < self.max_retries:+ logger.warning(+ "Attempt %d failed for model %s: %s. Retrying...",+ attempt + 1,+ self.model,+ str(e),+ )+ else:+ logger.warning(+ "All %d attempt(s) failed for model %s.",+ self.max_retries + 1,+ self.model,)- except Exception as e:- last_error = e- if attempt < self.max_retries:- logger.warning(- "Attempt %d failed for model %s: %s. Retrying...",- attempt + 1,- model_name,- str(e),- )- else:- logger.warning(- "All %d attempt(s) failed for model %s.",- self.max_retries + 1,- model_name,- )if last_error is not None:raise last_error- raise RuntimeError("No models to try")- def _models_to_try(self) -> list[str]:- """Return the ordered list of model names to try."""- models = [self.model_name]- if self.fallback_model_name:- models.append(self.fallback_model_name)- return models+ raise RuntimeError(+ f"Failed to call model {self.model} after "+ f"{self.max_retries + 1} retries.",+ )@abstractmethodasync def _call_api(@@ -318,34 +347,37 @@ class ChatModelBase:last_error: Exception | None = None- for model_name in self._models_to_try():- for attempt in range(self.max_retries + 1):- try:- return await self._call_api_with_structured_output(- model_name,- messages=messages,- structured_model=structured_model,- **kwargs,+ for attempt in range(self.max_retries + 1):+ try:+ return await self._call_api_with_structured_output(+ self.model,+ messages=messages,+ structured_model=structured_model,+ **kwargs,+ )+ except Exception as e:+ last_error = e+ if attempt < self.max_retries:+ logger.warning(+ "Attempt %d failed for model %s: %s. Retrying...",+ attempt + 1,+ self.model,+ str(e),+ )+ else:+ logger.warning(+ "All %d attempt(s) failed for model %s.",+ self.max_retries + 1,+ self.model,)- except Exception as e:- last_error = e- if attempt < self.max_retries:- logger.warning(- "Attempt %d failed for model %s: %s. Retrying...",- attempt + 1,- model_name,- str(e),- )- else:- logger.warning(- "All %d attempt(s) failed for model %s.",- self.max_retries + 1,- model_name,- )if last_error is not None:raise last_error- raise RuntimeError("No models to try")++ raise RuntimeError(+ f"Failed to generate structured output after "+ f"{self.max_retries + 1} retries.",+ )async def _call_api_with_structured_output(self,diff --git a/src/agentscope/model/_dashscope/__init__.py b/src/agentscope/model/_dashscope/__init__.pynew file mode 100644index 000000000..e22af4fa6--- /dev/null+++ b/src/agentscope/model/_dashscope/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""The DashScope API modules."""++from ._model import DashScopeChatModel, DashScopeCredential++__all__ = [+ "DashScopeChatModel",+ "DashScopeCredential",+]diff --git a/src/agentscope/model/_dashscope_model.py b/src/agentscope/model/_dashscope/_model.pysimilarity index 72%rename from src/agentscope/model/_dashscope_model.pyrename to src/agentscope/model/_dashscope/_model.pyindex 728d7e053..c2398ec51 100644--- a/src/agentscope/model/_dashscope_model.py+++ b/src/agentscope/model/_dashscope/_model.py@@ -1,30 +1,22 @@# -*- coding: utf-8 -*--"""The dashscope API model classes."""+"""The DashScope chat model class."""import uuidimport warningsfrom datetime import datetimefrom http import HTTPStatus-from typing import (- Any,- AsyncGenerator,- Generator,- Union,- TYPE_CHECKING,- List,-)--from pydantic import BaseModel+from typing import Any, AsyncGenerator, Generator, List, Literal, TYPE_CHECKING++from pydantic import BaseModel, Fieldfrom aioitertools import iter as giter-from ._model_base import ChatModelBase-from ._model_response import ChatResponse-from ._model_usage import ChatUsage-from ..formatter import FormatterBase, DashScopeChatFormatter-from ..message import TextBlock, ToolCallBlock, ThinkingBlock, Msg-from ..tool import ToolChoice-from ..tracing import trace_llm-from ..types import JSONSerializableObject-from .._logging import logger+from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import DashScopeCredential+from ...formatter import FormatterBase, DashScopeChatFormatter+from ...message import Msg, TextBlock, ThinkingBlock, ToolCallBlock+from ...tool import ToolChoice+from ...tracing import trace_llmif TYPE_CHECKING:@@ -33,131 +25,117 @@ if TYPE_CHECKING:MultiModalConversationResponse,)else:- GenerationResponse = (- "dashscope.api_entities.dashscope_response.GenerationResponse"- )- MultiModalConversationResponse = (- "dashscope.api_entities.dashscope_response."- "MultiModalConversationResponse"- )+ GenerationResponse = Any+ MultiModalConversationResponse = Anyclass DashScopeChatModel(ChatModelBase):- """The DashScope chat model class, which unifies the Generation and- MultimodalConversation APIs into one method.-- This class provides a unified interface for DashScope API by automatically- selecting between text-only (Generation API) and multimodal- (MultiModalConversation API) endpoints. The `multimodality` parameter- allows explicit control over API selection:-- - When `multimodality=True`: Forces use of MultiModalConversation API- for handling images, videos, and other multimodal inputs- - When `multimodality=False`: Forces use of Generation API for- text-only processing- - When `multimodality=None` (default): Automatically selects the API- based on model name (e.g., models with "-vl" suffix or starting- with "qvq" will use MultiModalConversation API)-- This design enables seamless switching between text and multimodal- models without changing code structure, making it easier to work with- DashScope's diverse model offerings.- """-- class ThinkingConfig(BaseModel):- """The configuration for the thinking process in DashScope API."""-- enable_thinking: bool- thinking_budget: int = 2000- preserve_thinking: bool = False+ """The DashScope chat model."""++ class Parameters(BaseModel):+ """The parameters for DashScope LLM API."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of tokens for the LLM output.",+ gt=0,+ )++ thinking_enable: bool = Field(+ default=False,+ title="Thinking",+ description="The thinking enable for the LLM output.",+ )++ thinking_budget: int | None = Field(+ default=None,+ title="Thinking budget",+ description="The thinking budget for the LLM output.",+ gt=0,+ )++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ lt=2,+ )++ top_p: float | None = Field(+ default=None,+ title="Top P",+ description="The top P value for the LLM output.",+ gt=0,+ le=1,+ )++ top_k: int | None = Field(+ default=None,+ title="Top K",+ description="The top K value for the LLM output.",+ gt=0,+ le=100,+ )++ parallel_tool_calls: bool = Field(+ default=True,+ title="Parallel Tool Calls",+ description="If enable parallel tool calls for the LLM output.",+ )++ type: Literal["dashscope_chat"] = "dashscope_chat"+ """The type of the chat model."""def __init__(self,- model_name: str,- api_key: str,- context_length: int,+ credential: DashScopeCredential,+ model: str,+ parameters: "DashScopeChatModel.Parameters | None" = None,stream: bool = True,- max_retries: int = 0,- fallback_model_name: str | None = None,+ max_retries: int = 3,+ context_size: int = 131072,+ multimodality: bool | None = None,formatter: FormatterBase | None = None,- thinking_config: ThinkingConfig | None = None,- multimodality: bool = False,- generate_kwargs: dict[str, JSONSerializableObject] | None = None,- base_http_api_url: str | None = None,- **_kwargs: Any,) -> None:"""Initialize the DashScope chat model.Args:- model_name (`str`):- The model names.- api_key (`str`):- The dashscope API key.- context_length (`int`):- The context length of the model.- stream (`bool`):- The streaming output or not- enable_thinking (`bool | None`, optional):- Enable thinking or not, only support Qwen3, QwQ, DeepSeek-R1.- Refer to `DashScope documentation- <https://help.aliyun.com/zh/model-studio/deep-thinking>`_- for more details.- multimodality (`bool | None`, optional):- Whether to use multimodal conversation API. If `True`,- it will use `dashscope.AioMultiModalConversation.call`- to process multimodal inputs such as images and text. If- `False`, it will use- `dashscope.aigc.generation.AioGeneration.call` to process- text inputs. If `None` (default), the choice is based on- the model name.- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments used in DashScope API generation,- e.g. `temperature`, `seed`.- base_http_api_url (`str | None`, optional):- The base URL for DashScope API requests. If not provided,- the default base URL from the DashScope SDK will be used.- stream_tool_parsing (`bool`, default to `True`):- Whether to parse incomplete tool use JSON in streaming mode- with auto-repair. If True, partial JSON (e.g., `'{"a": "x'`)- is repaired to valid dicts (`{"a": "x"}`) in real-time for- immediate tool function input. Otherwise, the input field- remains {} until the final chunk arrives.- **_kwargs (`Any`):- Additional keyword arguments.+ credential (`DashScopeCredential`):+ The DashScope credential used to authenticate API calls.+ model (`str`):+ The DashScope model name, e.g. ``qwen-plus``.+ parameters (`DashScopeChatModel.Parameters | None`, defaults to \+ `None`):+ The DashScope API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the DashScope API.+ context_size (`int`, defaults to `131072`):+ The model context size used for context compression.+ multimodality (`bool | None`, defaults to `None`):+ Whether to call the MultiModalConversation API. ``True``+ forces multimodal mode, ``False`` forces text-only mode,+ and ``None`` auto-detects from the model name+ (e.g. ``qvq`` or ``-vl`` suffix).+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the DashScope API. When ``None``, a+ ``DashScopeChatFormatter`` instance will be used."""-- self.thinking_config = (- thinking_config- or DashScopeChatModel.ThinkingConfig(- enable_thinking=False,- )- )-- if self.thinking_config.enable_thinking and not stream:- logger.info(- "In DashScope API, `stream` must be True when "- "`enable_thinking` is True. ",- )- stream = True-super().__init__(- model_name,- stream,- context_length,- formatter or DashScopeChatFormatter(),- max_retries,- fallback_model_name,+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,)-- self.api_key = api_key+ self.credential = credential+ self.parameters = parameters or self.Parameters()self.multimodality = multimodality- self.generate_kwargs = generate_kwargs or {}-- if base_http_api_url is not None:- import dashscope-- dashscope.base_http_api_url = base_http_api_url+ self.formatter = formatter or DashScopeChatFormatter()@trace_llmasync def _call_api(@@ -210,7 +188,6 @@ class DashScopeChatModel(ChatModelBase):# In agentscope, the `incremental_output` must be `True` when# `self.stream` is True"incremental_output": self.stream,- **self.generate_kwargs,**kwargs,}@@ -225,25 +202,32 @@ class DashScopeChatModel(ChatModelBase):tools,)- # thinking related options- kwargs = {**kwargs, **self.thinking_config.model_dump()}+ # thinking related options — map to DashScope API parameter names+ kwargs["enable_thinking"] = self.parameters.thinking_enable+ if self.parameters.thinking_budget is not None:+ kwargs["thinking_budget"] = self.parameters.thinking_budget# 3. Call the API and parse the responsestart_datetime = datetime.now()# Use MultiModalConversation API if multimodality is True, or if the# model is multimodal based on the model name.+ api_key = self.credential.api_key.get_secret_value()if self.multimodality or (self.multimodality is None- and ("qvq" in self.model_name or "-vl" in self.model_name)+ and (+ "qvq" in model_name+ or "-vl" in model_name+ or "-omni" in model_name+ )):response = await dashscope.AioMultiModalConversation.call(- api_key=self.api_key,+ api_key=api_key,**kwargs,)else:response = await dashscope.aigc.generation.AioGeneration.call(- api_key=self.api_key,+ api_key=api_key,**kwargs,)@@ -351,6 +335,9 @@ class DashScopeChatModel(ChatModelBase):# Use the index to identify different tool callsindex = tool_call.get("index", 0)+ # Initialize accumulator for a new tool call index+ acc_tool_calls.setdefault(index, {})+# Avoid appending duplicate idif "id" in tool_call and tool_call["id"] != acc_tool_calls[index@@ -402,16 +389,24 @@ class DashScopeChatModel(ChatModelBase):)# Yield a final complete response with the accumulated content and- # final usage+ # final usage. Thinking comes before text to preserve the natural+ # generation order (reasoning first, then answer).content = []- if acc_text.text:- content.append(acc_text)-if acc_thinking.thinking:content.append(acc_thinking)+ if acc_text.text:+ content.append(acc_text)+if acc_tool_calls:- content.extend(acc_tool_calls.values())+ content.extend(+ ToolCallBlock(+ id=tc.get("id", uuid.uuid4().hex),+ name=tc.get("name", ""),+ input=tc.get("arguments", "{}"),+ )+ for tc in acc_tool_calls.values()+ )yield ChatResponse(id=response_id or uuid.uuid4().hex,@@ -423,10 +418,7 @@ class DashScopeChatModel(ChatModelBase):async def _parse_dashscope_generation_response(self,start_datetime: datetime,- response: Union[- GenerationResponse,- MultiModalConversationResponse,- ],+ response: GenerationResponse | MultiModalConversationResponse,) -> ChatResponse:"""Given a DashScope GenerationResponse object, extract the contentblocks and usages from it.@@ -435,7 +427,7 @@ class DashScopeChatModel(ChatModelBase):start_datetime (`datetime`):The start datetime of the response generation.response (- `Union[GenerationResponse, MultiModalConversationResponse]`+ `GenerationResponse | MultiModalConversationResponse`):Dashscope GenerationResponse | MultiModalConversationResponseobject to parse.diff --git a/src/agentscope/model/_dashscope/_models/qwen-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen-plus.yamlnew file mode 100644index 000000000..f7f77d55e--- /dev/null+++ b/src/agentscope/model/_dashscope/_models/qwen-plus.yaml@@ -0,0 +1,16 @@+name: qwen-plus+label: Qwen Plus+status: active++input_types:+ - text/plain++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 16384++parameter_overrides:+ max_tokens: {"maximum": 16384}diff --git a/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yamlnew file mode 100644index 000000000..973e282dd--- /dev/null+++ b/src/agentscope/model/_dashscope/_models/qwen3.5-omni-plus.yaml@@ -0,0 +1,28 @@+name: qwen3.5-omni-plus+label: Qwen3.5-Omni-Plus+status: active++input_types:+ - text/plain+ - image/bmp+ - image/jpeg+ - image/png+ - image/tiff+ - image/webp+ - image/heic+ - audio/mp3+ - audio/wav+ - audio/flac+ - video/mp4++output_types:+ - text/plain+ - application/x-thinking+ - audio/wav++context_size: 262144+output_size: 65536++parameter_overrides:+ max_tokens: {"maximum": 65536}+diff --git a/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml b/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yamlnew file mode 100644index 000000000..3ae5e677d--- /dev/null+++ b/src/agentscope/model/_dashscope/_models/qwen3.6-plus.yaml@@ -0,0 +1,24 @@+name: qwen3.6-plus+label: Qwen3.6-Plus+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/bmp+ - image/jpeg+ - image/png+ - image/tiff+ - image/webp+ - image/heic+ - video/mp4++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 65536++parameter_overrides:+ max_tokens: {"maximum": 65536}diff --git a/src/agentscope/model/_deepseek/__init__.py b/src/agentscope/model/_deepseek/__init__.pynew file mode 100644index 000000000..580146f06--- /dev/null+++ b/src/agentscope/model/_deepseek/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""The DeepSeek LLM API modules."""++from ._model import DeepSeekCredential, DeepSeekChatModel++__all__ = [+ "DeepSeekCredential",+ "DeepSeekChatModel",+]diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.pynew file mode 100644index 000000000..52a247671--- /dev/null+++ b/src/agentscope/model/_deepseek/_model.py@@ -0,0 +1,384 @@+# -*- coding: utf-8 -*-+"""The DeepSeek chat model implementation."""+from collections import OrderedDict+from datetime import datetime+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List++from pydantic import BaseModel, Field++from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import DeepSeekCredential+from ...formatter import FormatterBase, DeepSeekChatFormatter+from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...tool import ToolChoice+from ...tracing import trace_llm++if TYPE_CHECKING:+ from openai.types.chat import ChatCompletion+ from openai import AsyncStream+else:+ ChatCompletion = Any+ AsyncStream = Any+++class DeepSeekChatModel(ChatModelBase):+ """The DeepSeek chat model."""++ class Parameters(BaseModel):+ """The parameters for the DeepSeek chat model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of tokens for the LLM output.",+ gt=0,+ )++ thinking_enable: bool = Field(+ default=False,+ title="Thinking",+ description=(+ "Whether to enable thinking. Note: for the DeepSeek API, "+ "thinking mode is selected by choosing the deepseek-reasoner "+ "model rather than an API parameter."+ ),+ )++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ le=2,+ )++ top_p: float | None = Field(+ default=None,+ title="Top P",+ description="The top P value for the LLM output.",+ gt=0,+ le=1,+ )++ type: Literal["deepseek_chat"] = "deepseek_chat"+ """The type of the chat model."""++ def __init__(+ self,+ credential: DeepSeekCredential,+ model: str,+ parameters: "DeepSeekChatModel.Parameters | None" = None,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 65536,+ formatter: FormatterBase | None = None,+ ) -> None:+ """Initialize the DeepSeek chat model.++ Args:+ credential (`DeepSeekCredential`):+ The DeepSeek credential used to authenticate API calls.+ model (`str`):+ The DeepSeek model name, e.g. ``deepseek-chat``.+ parameters (`DeepSeekChatModel.Parameters | None`, defaults to \+ `None`):+ The DeepSeek API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the DeepSeek API.+ context_size (`int`, defaults to `65536`):+ The model context size used for context compression.+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the DeepSeek API. When ``None``, a+ ``DeepSeekChatFormatter`` instance will be used.+ """+ super().__init__(+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,+ )+ self.credential = credential+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or DeepSeekChatFormatter()++ @trace_llm+ async def _call_api(+ self,+ model_name: str,+ messages: list[Any],+ tools: list[dict] | None = None,+ tool_choice: ToolChoice | None = None,+ **generate_kwargs: Any,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Call the DeepSeek chat completions API.++ Args:+ model_name (`str`):+ The model name to use for this call.+ messages (`list`):+ A list of message dicts with ``role`` and ``content`` keys.+ tools (`list[dict]`, default `None`):+ The tools JSON schemas.+ tool_choice (`ToolChoice | None`, optional):+ Controls which (if any) tool is called by the model.+ **generate_kwargs (`Any`):+ Extra keyword arguments forwarded to the API.++ Returns:+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """+ import openai++ client = openai.AsyncClient(+ api_key=self.credential.api_key.get_secret_value(),+ base_url=self.credential.base_url,+ )++ formatted_messages = await self.formatter.format(messages)++ kwargs: dict[str, Any] = {+ "model": model_name,+ "messages": formatted_messages,+ "stream": self.stream,+ }++ if self.parameters.max_tokens is not None:+ kwargs["max_tokens"] = self.parameters.max_tokens++ if self.parameters.temperature is not None:+ kwargs["temperature"] = self.parameters.temperature++ if self.parameters.top_p is not None:+ kwargs["top_p"] = self.parameters.top_p++ kwargs.update(generate_kwargs)++ if tools:+ kwargs["tools"] = tools++ if tool_choice:+ kwargs["tool_choice"] = self._format_tool_choice(+ tool_choice,+ tools,+ )++ if self.stream:+ kwargs["stream_options"] = {"include_usage": True}++ start_datetime = datetime.now()+ response = await client.chat.completions.create(**kwargs)++ if self.stream:+ return self._parse_stream_response(start_datetime, response)++ return self._parse_completion_response(start_datetime, response)++ async def _parse_stream_response(+ self,+ start_datetime: datetime,+ response: AsyncStream,+ ) -> AsyncGenerator[ChatResponse, None]:+ """Parse the DeepSeek streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`AsyncStream`):+ The OpenAI-compatible async stream object.++ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True``.+ """+ usage = None+ response_id: str | None = None+ # All delta should have the same block identifier+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")+ acc_tool_calls: OrderedDict = OrderedDict()++ async with response as stream:+ async for chunk in stream:+ if chunk.usage:+ usage = ChatUsage(+ input_tokens=chunk.usage.prompt_tokens,+ output_tokens=chunk.usage.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=chunk.usage,+ )++ # Capture response_id from the first chunk that carries it+ response_id = response_id or getattr(chunk, "id", None)++ if not chunk.choices:+ continue++ choice = chunk.choices[0]+ delta = choice.delta++ delta_thinking = (+ getattr(delta, "reasoning_content", None) or ""+ )+ delta_text = getattr(delta, "content", None) or ""++ acc_thinking.thinking += delta_thinking+ acc_text.text += delta_text++ for tool_call in getattr(delta, "tool_calls", None) or []:+ idx = tool_call.index+ if idx in acc_tool_calls:+ if tool_call.function.arguments is not None:+ acc_tool_calls[idx][+ "input"+ ] += tool_call.function.arguments+ else:+ acc_tool_calls[idx] = {+ "id": tool_call.id,+ "name": tool_call.function.name,+ "input": tool_call.function.arguments or "",+ }++ delta_contents: List[+ TextBlock | ToolCallBlock | ThinkingBlock+ ] = []+ if delta_thinking:+ delta_contents.append(+ ThinkingBlock(+ id=acc_thinking.id,+ thinking=delta_thinking,+ ),+ )+ if delta_text:+ delta_contents.append(+ TextBlock(id=acc_text.id, text=delta_text),+ )++ if delta_contents:+ _kwargs: dict[str, Any] = {+ "content": delta_contents,+ "usage": usage,+ "is_last": False,+ }+ if response_id:+ _kwargs["id"] = response_id+ yield ChatResponse(**_kwargs)++ final_contents: List[TextBlock | ToolCallBlock | ThinkingBlock] = []+ if acc_thinking.thinking:+ final_contents.append(acc_thinking)+ if acc_text.text:+ final_contents.append(acc_text)+ for tc in acc_tool_calls.values():+ final_contents.append(+ ToolCallBlock(+ id=tc["id"],+ name=tc["name"],+ input=tc["input"],+ ),+ )++ _final_kwargs: dict[str, Any] = {+ "content": final_contents,+ "usage": usage,+ "is_last": True,+ }+ if response_id:+ _final_kwargs["id"] = response_id+ yield ChatResponse(**_final_kwargs)++ def _parse_completion_response(+ self,+ start_datetime: datetime,+ response: ChatCompletion,+ ) -> ChatResponse:+ """Parse the DeepSeek non-streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`ChatCompletion`):+ The OpenAI-compatible chat completion object.++ Returns:+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True``.+ """+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []++ if response.choices:+ choice = response.choices[0]+ reasoning = getattr(choice.message, "reasoning_content", None)+ if isinstance(reasoning, str) and reasoning:+ content_blocks.append(ThinkingBlock(thinking=reasoning))++ if choice.message.content:+ content_blocks.append(TextBlock(text=choice.message.content))++ for tool_call in choice.message.tool_calls or []:+ content_blocks.append(+ ToolCallBlock(+ id=tool_call.id,+ name=tool_call.function.name,+ input=tool_call.function.arguments,+ ),+ )++ usage = None+ if response.usage:+ usage = ChatUsage(+ input_tokens=response.usage.prompt_tokens,+ output_tokens=response.usage.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=response.usage,+ )++ resp_kwargs: dict[str, Any] = {+ "content": content_blocks,+ "is_last": True,+ "usage": usage,+ }+ response_id = getattr(response, "id", None)+ if response_id:+ resp_kwargs["id"] = response_id++ return ChatResponse(**resp_kwargs)++ def _format_tool_choice(+ self,+ tool_choice: ToolChoice | None,+ tools: list[dict] | None,+ ) -> str | dict | None:+ """Format tool_choice parameter for the DeepSeek API.++ Args:+ tool_choice (`ToolChoice | None`):+ The unified tool choice parameter which can be ``"auto"``,+ ``"none"``, ``"required"``, or a specific function name.+ tools (`list[dict] | None`):+ The list of available tools, used for validation when+ ``tool_choice`` is a specific function name.++ Returns:+ `str | dict | None`:+ The formatted tool choice string or configuration dict for+ the DeepSeek API, or ``None`` if ``tool_choice`` is ``None``.+ """+ self._validate_tool_choice(tool_choice, tools)++ if tool_choice is None:+ return None++ if tool_choice in ["auto", "none", "required"]:+ return tool_choice++ return {"type": "function", "function": {"name": tool_choice}}diff --git a/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml b/src/agentscope/model/_deepseek/_models/deepseek-chat.yamlnew file mode 100644index 000000000..36adf5c7e--- /dev/null+++ b/src/agentscope/model/_deepseek/_models/deepseek-chat.yaml@@ -0,0 +1,17 @@+name: deepseek-chat+label: DeepSeek Chat+status: sunset+deprecated_at: "2026-07-24T00:00:00"++input_types:+ - text/plain++output_types:+ - text/plain++context_size: 1000000+output_size: 384000++parameter_overrides:+ max_tokens:+ maximum: 384000diff --git a/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml b/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yamlnew file mode 100644index 000000000..8c0b010c6--- /dev/null+++ b/src/agentscope/model/_deepseek/_models/deepseek-reasoner.yaml@@ -0,0 +1,18 @@+name: deepseek-reasoner+label: DeepSeek Reasoner+status: sunset+deprecated_at: "2026-07-24T00:00:00"++input_types:+ - text/plain++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 384000++parameter_overrides:+ max_tokens:+ maximum: 384000diff --git a/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml b/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yamlnew file mode 100644index 000000000..fed1a83f0--- /dev/null+++ b/src/agentscope/model/_deepseek/_models/deepseek-v4-flash.yaml@@ -0,0 +1,18 @@+name: deepseek-v4-flash+label: DeepSeek V4 Flash+status: active++input_types:+ - text/plain+ - application/x-thinking++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 384000++parameter_overrides:+ max_tokens:+ maximum: 384000diff --git a/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml b/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yamlnew file mode 100644index 000000000..ffb1a2e93--- /dev/null+++ b/src/agentscope/model/_deepseek/_models/deepseek-v4-pro.yaml@@ -0,0 +1,18 @@+name: deepseek-v4-pro+label: DeepSeek V4 Pro+status: active++input_types:+ - text/plain+ - application/x-thinking++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 384000++parameter_overrides:+ max_tokens:+ maximum: 384000diff --git a/src/agentscope/model/_gemini/__init__.py b/src/agentscope/model/_gemini/__init__.pynew file mode 100644index 000000000..66afd74a6--- /dev/null+++ b/src/agentscope/model/_gemini/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""The Google Gemini LLM API modules."""++from ._model import GeminiCredential, GeminiChatModel++__all__ = [+ "GeminiCredential",+ "GeminiChatModel",+]diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.pynew file mode 100644index 000000000..e96f6c612--- /dev/null+++ b/src/agentscope/model/_gemini/_model.py@@ -0,0 +1,522 @@+# -*- coding: utf-8 -*-+"""The Google Gemini chat model implementation."""+import base64+import copy+import json+import uuid+from datetime import datetime+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List++from pydantic import BaseModel, Field++from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import GeminiCredential+from ...formatter import FormatterBase, GeminiChatFormatter+from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...tool import ToolChoice+from ...tracing import trace_llm+from ..._logging import logger++if TYPE_CHECKING:+ from google.genai.types import GenerateContentResponse+else:+ GenerateContentResponse = Any+++def _flatten_json_schema(schema: dict) -> dict:+ """Flatten a JSON schema by resolving all $ref references.++ Gemini API does not support ``$defs`` and ``$ref`` in JSON schemas.++ Args:+ schema (`dict`):+ The JSON schema that may contain ``$defs`` and ``$ref`` references.++ Returns:+ `dict`:+ A flattened JSON schema with all references resolved inline.+ """+ schema = copy.deepcopy(schema)+ defs = schema.pop("$defs", {})++ def _resolve_ref(obj: Any, visited: set | None = None) -> Any:+ if visited is None:+ visited = set()+ if not isinstance(obj, dict):+ if isinstance(obj, list):+ return [_resolve_ref(item, visited.copy()) for item in obj]+ return obj+ if "$ref" in obj:+ ref_path = obj["$ref"]+ if ref_path.startswith("#/$defs/"):+ def_name = ref_path[len("#/$defs/") :]+ if def_name in visited:+ logger.warning(+ "Circular reference detected for '%s' in tool schema",+ def_name,+ )+ return {+ "type": "object",+ "description": f"(circular: {def_name})",+ }+ visited.add(def_name)+ if def_name in defs:+ resolved = _resolve_ref(defs[def_name], visited.copy())+ for key, value in obj.items():+ if key != "$ref":+ resolved[key] = _resolve_ref(value, visited.copy())+ return resolved+ return obj+ result = {}+ for key, value in obj.items():+ result[key] = _resolve_ref(value, visited.copy())+ return result++ return _resolve_ref(schema)+++class GeminiChatModel(ChatModelBase):+ """The Google Gemini chat model."""++ class Parameters(BaseModel):+ """The parameters for the Gemini chat model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of tokens for the LLM output.",+ gt=0,+ )++ thinking_enable: bool = Field(+ default=False,+ title="Thinking",+ description="Whether to enable thinking output.",+ )++ thinking_budget: int | None = Field(+ default=None,+ title="Thinking Budget",+ description="The thinking budget in tokens.",+ gt=0,+ )++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ le=2,+ )++ top_p: float | None = Field(+ default=None,+ title="Top P",+ description="The top P value for the LLM output.",+ gt=0,+ le=1,+ )++ type: Literal["gemini_chat"] = "gemini_chat"+ """The type of the chat model."""++ def __init__(+ self,+ credential: GeminiCredential,+ model: str,+ parameters: "GeminiChatModel.Parameters | None" = None,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 1048576,+ formatter: FormatterBase | None = None,+ ) -> None:+ """Initialize the Gemini chat model.++ Args:+ credential (`GeminiCredential`):+ The Google Gemini credential used to authenticate API calls.+ model (`str`):+ The Gemini model name, e.g. ``gemini-2.0-flash-exp``.+ parameters (`GeminiChatModel.Parameters | None`, defaults to \+ `None`):+ The Gemini API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the Gemini API.+ context_size (`int`, defaults to `1048576`):+ The model context size used for context compression.+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the Gemini API. When ``None``, a+ ``GeminiChatFormatter`` instance will be used.+ """+ super().__init__(+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,+ )+ self.credential = credential+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or GeminiChatFormatter()++ @trace_llm+ async def _call_api(+ self,+ model_name: str,+ messages: list[Any],+ tools: list[dict] | None = None,+ tool_choice: ToolChoice | None = None,+ **config_kwargs: Any,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Call the Gemini chat API.++ Args:+ model_name (`str`):+ The model name to use for this call.+ messages (`list`):+ A list of message objects for Gemini API.+ tools (`list[dict]`, default `None`):+ The tools JSON schemas.+ tool_choice (`ToolChoice | None`, optional):+ Controls which (if any) tool is called by the model.+ **config_kwargs (`Any`):+ Extra keyword arguments for the Gemini config.++ Returns:+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """+ from google import genai++ client = genai.Client(+ api_key=self.credential.api_key.get_secret_value(),+ )++ formatted_messages = await self.formatter.format(messages)++ config: dict[str, Any] = {**config_kwargs}++ if self.parameters.max_tokens is not None:+ config["max_output_tokens"] = self.parameters.max_tokens++ if self.parameters.temperature is not None:+ config["temperature"] = self.parameters.temperature++ if self.parameters.top_p is not None:+ config["top_p"] = self.parameters.top_p++ if self.parameters.thinking_enable:+ config["thinking_config"] = {+ "include_thoughts": True,+ "thinking_budget": self.parameters.thinking_budget or 1024,+ }++ if tools:+ config["tools"] = self._format_tools_json_schemas(tools)++ if tool_choice:+ config["tool_config"] = self._format_tool_choice(+ tool_choice,+ tools,+ )++ kwargs: dict[str, Any] = {+ "model": model_name,+ "contents": formatted_messages,+ "config": config,+ }++ start_datetime = datetime.now()++ if self.stream:+ response = await client.aio.models.generate_content_stream(+ **kwargs,+ )+ # Pass client to the generator so the aiohttp session it owns+ # stays alive until the stream is fully consumed.+ return self._parse_stream_response(+ start_datetime,+ response,+ client,+ )++ response = await client.aio.models.generate_content(**kwargs)+ return self._parse_completion_response(start_datetime, response)++ async def _parse_stream_response(+ self,+ start_datetime: datetime,+ response: Any,+ _client: Any = None,+ ) -> AsyncGenerator[ChatResponse, None]:+ """Parse the Gemini streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`Any`):+ The Gemini async stream object from+ ``client.aio.models.generate_content_stream``.+ _client (`Any`, optional):+ The ``genai.Client`` that produced the stream. Held here so+ its aiohttp session is not garbage-collected before the+ stream is fully consumed.++ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True``.+ """+ # All delta should have the same block identifier+ # Use the API's response_id when available (it arrives at the first+ # chunk); otherwise generate a UUID to ensure all chunks share a+ # stable id.+ response_id: str | None = None+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")+ acc_tool_calls: dict = {}+ usage = None++ async for chunk in response:+ # Capture response_id from the first chunk that carries it+ if response_id is None:+ response_id = (+ getattr(chunk, "response_id", None) or uuid.uuid4().hex+ )++ delta_content: list = []++ if (+ chunk.candidates+ and chunk.candidates[0].content+ and chunk.candidates[0].content.parts+ ):+ for part in chunk.candidates[0].content.parts:+ if part.text:+ if part.thought:+ acc_thinking.thinking += part.text+ delta_content.append(+ ThinkingBlock(+ id=acc_thinking.id,+ thinking=part.text,+ ),+ )+ else:+ acc_text.text += part.text+ delta_content.append(+ TextBlock(id=acc_text.id, text=part.text),+ )++ if part.function_call:+ keyword_args = part.function_call.args or {}+ if part.thought_signature:+ call_id = base64.b64encode(+ part.thought_signature,+ ).decode("utf-8")+ else:+ call_id = part.function_call.id+ input_str = json.dumps(+ keyword_args,+ ensure_ascii=False,+ )+ acc_tool_calls[call_id] = {+ "name": part.function_call.name,+ "input": input_str,+ }+ delta_content.append(+ ToolCallBlock(+ id=call_id,+ name=part.function_call.name,+ input=input_str,+ ),+ )++ usage = self._extract_usage(chunk.usage_metadata, start_datetime)++ if delta_content:+ yield ChatResponse(+ id=response_id,+ content=delta_content,+ is_last=False,+ usage=usage,+ )++ final_content: list = []+ if acc_thinking.thinking:+ final_content.append(acc_thinking)+ if acc_text.text:+ final_content.append(acc_text)+ for call_id, tc in acc_tool_calls.items():+ final_content.append(+ ToolCallBlock(id=call_id, name=tc["name"], input=tc["input"]),+ )++ yield ChatResponse(+ id=response_id or uuid.uuid4().hex,+ content=final_content,+ is_last=True,+ usage=usage,+ )++ def _parse_completion_response(+ self,+ start_datetime: datetime,+ response: GenerateContentResponse,+ ) -> ChatResponse:+ """Parse the Gemini non-streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`GenerateContentResponse`):+ The Gemini generate content response object.++ Returns:+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True``.+ """+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []++ if (+ response.candidates+ and response.candidates[0].content+ and response.candidates[0].content.parts+ ):+ for part in response.candidates[0].content.parts:+ if part.text:+ if part.thought:+ content_blocks.append(+ ThinkingBlock(thinking=part.text),+ )+ else:+ content_blocks.append(TextBlock(text=part.text))++ if part.function_call:+ keyword_args = part.function_call.args or {}+ if part.thought_signature:+ call_id = base64.b64encode(+ part.thought_signature,+ ).decode("utf-8")+ else:+ call_id = part.function_call.id+ content_blocks.append(+ ToolCallBlock(+ id=call_id,+ name=part.function_call.name,+ input=json.dumps(keyword_args, ensure_ascii=False),+ ),+ )++ usage = self._extract_usage(response.usage_metadata, start_datetime)++ return ChatResponse(+ id=getattr(response, "response_id", None) or uuid.uuid4().hex,+ content=content_blocks,+ is_last=True,+ usage=usage,+ )++ def _extract_usage(+ self,+ usage_metadata: Any,+ start_datetime: datetime,+ ) -> ChatUsage | None:+ """Extract ChatUsage from usage_metadata.++ Args:+ usage_metadata (`Any`):+ The usage metadata object from a Gemini response.+ start_datetime (`datetime`):+ The start datetime of the response generation.++ Returns:+ `ChatUsage | None`:+ A ``ChatUsage`` object if usage data is available, otherwise+ ``None``.+ """+ if not usage_metadata:+ return None+ prompt_tokens = usage_metadata.prompt_token_count+ total_tokens = usage_metadata.total_token_count+ if prompt_tokens is not None and total_tokens is not None:+ return ChatUsage(+ input_tokens=prompt_tokens,+ output_tokens=total_tokens - prompt_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=usage_metadata,+ )+ return None++ def _format_tools_json_schemas(+ self,+ schemas: list[dict[str, Any]],+ ) -> list[dict[str, Any]]:+ """Format tool schemas for the Gemini API.++ Args:+ schemas (`list[dict[str, Any]]`):+ The raw tool JSON schemas in the standard ``{"function": ...}``+ format.++ Returns:+ `list[dict[str, Any]]`:+ A list containing a single dict with+ ``"function_declarations"`` key, as required by the Gemini+ API.+ """+ function_declarations = []+ for schema in schemas:+ if "function" not in schema:+ continue+ func = schema["function"].copy()+ if "parameters" in func:+ func["parameters"] = _flatten_json_schema(func["parameters"])+ function_declarations.append(func)+ return [{"function_declarations": function_declarations}]++ def _format_tool_choice(+ self,+ tool_choice: ToolChoice | None,+ tools: list[dict] | None,+ ) -> dict | None:+ """Format tool_choice parameter for the Gemini API.++ Args:+ tool_choice (`ToolChoice | None`):+ The unified tool choice parameter which can be ``"auto"``,+ ``"none"``, ``"required"``, or a specific function name.+ tools (`list[dict] | None`):+ The list of available tools, used for validation when+ ``tool_choice`` is a specific function name.++ Returns:+ `dict | None`:+ The formatted ``tool_config`` dict for the Gemini API, or+ ``None`` if ``tool_choice`` is ``None``.+ """+ self._validate_tool_choice(tool_choice, tools)++ if tool_choice is None:+ return None++ mode_mapping = {+ "auto": "AUTO",+ "none": "NONE",+ "required": "ANY",+ }+ mode = mode_mapping.get(tool_choice)+ if mode:+ return {"function_calling_config": {"mode": mode}}+ return {+ "function_calling_config": {+ "mode": "ANY",+ "allowed_function_names": [tool_choice],+ },+ }diff --git a/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml b/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yamlnew file mode 100644index 000000000..9e1b9020a--- /dev/null+++ b/src/agentscope/model/_gemini/_models/gemini-2.5-flash.yaml@@ -0,0 +1,25 @@+name: gemini-2.5-flash+label: Gemini 2.5 Flash+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp+ - audio/mp3+ - audio/wav+ - video/mp4++output_types:+ - text/plain+ - application/x-thinking++context_size: 1048576+output_size: 65536++parameter_overrides:+ max_tokens:+ maximum: 65536diff --git a/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml b/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yamlnew file mode 100644index 000000000..6b975fe54--- /dev/null+++ b/src/agentscope/model/_gemini/_models/gemini-2.5-pro.yaml@@ -0,0 +1,25 @@+name: gemini-2.5-pro+label: Gemini 2.5 Pro+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp+ - audio/mp3+ - audio/wav+ - video/mp4++output_types:+ - text/plain+ - application/x-thinking++context_size: 1048576+output_size: 65536++parameter_overrides:+ max_tokens:+ maximum: 65536diff --git a/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml b/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yamlnew file mode 100644index 000000000..954f462e4--- /dev/null+++ b/src/agentscope/model/_gemini/_models/gemini-3-flash-preview.yaml@@ -0,0 +1,25 @@+name: gemini-3-flash-preview+label: Gemini 3 Flash Preview+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp+ - audio/mp3+ - audio/wav+ - video/mp4+ - application/pdf++output_types:+ - text/plain+ - application/x-thinking++context_size: 1048576+output_size: 65536++parameter_overrides:+ max_tokens:+ maximum: 65536diff --git a/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml b/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yamlnew file mode 100644index 000000000..4040646c1--- /dev/null+++ b/src/agentscope/model/_gemini/_models/gemini-3.1-pro-preview.yaml@@ -0,0 +1,25 @@+name: gemini-3.1-pro-preview+label: Gemini 3.1 Pro Preview+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp+ - audio/mp3+ - audio/wav+ - video/mp4+ - application/pdf++output_types:+ - text/plain+ - application/x-thinking++context_size: 1048576+output_size: 65536++parameter_overrides:+ max_tokens:+ maximum: 65536diff --git a/src/agentscope/model/_gemini_model.py b/src/agentscope/model/_gemini_model.pydeleted file mode 100644index 427cd85c9..000000000--- a/src/agentscope/model/_gemini_model.py+++ /dev/null@@ -1,583 +0,0 @@-# -*- coding: utf-8 -*--"""The Google Gemini model in agentscope."""-import base64-import copy-from datetime import datetime-import json-from typing import (- AsyncGenerator,- Any,- TYPE_CHECKING,- AsyncIterator,- Literal,- List,-)--from pydantic import BaseModel--from .._logging import logger-from ..formatter import FormatterBase, GeminiChatFormatter-from ..message import ToolCallBlock, TextBlock, ThinkingBlock-from ._model_usage import ChatUsage-from ._model_base import ChatModelBase-from ._model_response import ChatResponse-from ..tracing import trace_llm-from ..types import JSONSerializableObject-from ..tool import ToolChoice--if TYPE_CHECKING:- from google.genai.types import GenerateContentResponse-else:- GenerateContentResponse = "google.genai.types.GenerateContentResponse"---def _flatten_json_schema(schema: dict) -> dict:- """Flatten a JSON schema by resolving all $ref references.-- .. note::- Gemini API does not support `$defs` and `$ref` in JSON schemas.- This function resolves all `$ref` references by inlining the- referenced definitions, producing a self-contained schema without- any references.-- Args:- schema (`dict`):- The JSON schema that may contain `$defs` and `$ref` references.-- Returns:- `dict`:- A flattened JSON schema with all references resolved inline.- """- # Deep copy to avoid modifying the original schema- schema = copy.deepcopy(schema)-- # Extract $defs if present- defs = schema.pop("$defs", {})-- def _resolve_ref(obj: Any, visited: set | None = None) -> Any:- """Recursively resolve $ref references in the schema."""- if visited is None:- visited = set()-- if not isinstance(obj, dict):- if isinstance(obj, list):- return [_resolve_ref(item, visited.copy()) for item in obj]- return obj-- # Handle $ref- if "$ref" in obj:- ref_path = obj["$ref"]- # Extract definition name from "#/$defs/DefinitionName"- if ref_path.startswith("#/$defs/"):- def_name = ref_path[len("#/$defs/") :]-- # Prevent infinite recursion for circular references- if def_name in visited:- logger.warning(- "Circular reference detected for '%s' in tool schema",- def_name,- )- return {- "type": "object",- "description": f"(circular: {def_name})",- }-- visited.add(def_name)-- if def_name in defs:- # Recursively resolve any nested refs in the definition- resolved = _resolve_ref(- defs[def_name],- visited.copy(),- )- # Merge any additional properties from the original object- # (excluding $ref itself)- for key, value in obj.items():- if key != "$ref":- resolved[key] = _resolve_ref(value, visited.copy())- return resolved-- # If we can't resolve the ref, return as-is (shouldn't happen)- return obj-- # Recursively process all nested objects- result = {}- for key, value in obj.items():- result[key] = _resolve_ref(value, visited.copy())-- return result-- return _resolve_ref(schema)---class GeminiChatModel(ChatModelBase):- """The Google Gemini chat model class in agentscope."""-- class ThinkingConfig(BaseModel):- """Configuration for enabling thinking blocks in Gemini responses."""-- enable_thinking: bool- thinking_budget: int = 1024-- def __init__(- self,- model_name: str,- api_key: str,- context_length: int,- stream: bool = True,- max_retries: int = 0,- fallback_model_name: str | None = None,- formatter: FormatterBase | None = None,- thinking_config: ThinkingConfig | None = None,- client_kwargs: dict[str, JSONSerializableObject] | None = None,- generate_kwargs: dict[str, JSONSerializableObject] | None = None,- ) -> None:- """Initialize the Gemini chat model.-- Args:- model_name (`str`):- The name of the Gemini model to use, e.g. "gemini-2.5-flash".- api_key (`str`):- The API key for Google Gemini.- context_length (`int`):- The context length of the model, used in context compression.- stream (`bool`, default `True`):- Whether to use streaming output or not.- max_retries (`int`, optional):- Maximum number of retries on failure. Defaults to 0.- fallback_model_name (`str | None`, optional):- Fallback model name to use after all retries fail.- formatter (`FormatterBase | None`, optional):- Formatter for message preprocessing.- thinking_config (`ThinkingConfig | None`, optional):- Thinking config, supported models are 2.5 Pro, 2.5 Flash, etc.- client_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments to initialize the Gemini client.- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments used in Gemini API generation,- e.g. `temperature`, `seed`.- """-- try:- from google import genai- except ImportError as e:- raise ImportError(- "Please install gemini Python sdk with "- "`pip install -q -U google-genai`",- ) from e-- super().__init__(- model_name=model_name,- stream=stream,- context_length=context_length,- max_retries=max_retries,- fallback_model_name=fallback_model_name,- formatter=formatter or GeminiChatFormatter(),- )-- self.client = genai.Client(- api_key=api_key,- **(client_kwargs or {}),- )- self.thinking_config = thinking_config- self.generate_kwargs = generate_kwargs or {}-- @trace_llm- async def _call_api(- self,- model_name: str,- messages: list[dict],- tools: list[dict] | None = None,- tool_choice: Literal["auto", "none", "required"] | str | None = None,- **config_kwargs: Any,- ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:- """Call the Gemini model with the provided arguments.-- Args:- messages (`list[dict[str, Any]]`):- A list of dictionaries, where `role` and `content` fields are- required.- tools (`list[dict] | None`, default `None`):- The tools JSON schemas that the model can use.- tool_choice (`Literal["auto", "none", "required"] | str \- | None`, default `None`):- Controls which (if any) tool is called by the model.- Can be "auto", "none", "required", or specific tool name.- For more details, please refer to- https://ai.google.dev/gemini-api/docs/function-calling?hl=en&example=meeting#function_calling_modes- **config_kwargs (`Any`):- The keyword arguments for Gemini chat completions API.- """-- config: dict = {- **self.generate_kwargs,- **config_kwargs,- }- if self.thinking_config:- config["thinking_config"] = {- "include_thoughts": self.thinking_config.enable_thinking,- "thinking_budget": self.thinking_config.thinking_budget,- }-- if tools:- config["tools"] = self._format_tools_json_schemas(tools)-- if tool_choice:- config["tool_config"] = self._format_tool_choice(- tool_choice,- tools,- )-- # Prepare the arguments for the Gemini API call- kwargs: dict = {- "model": model_name,- "contents": messages,- "config": config,- }-- start_datetime = datetime.now()- if self.stream:- response = await self.client.aio.models.generate_content_stream(- **kwargs,- )-- return self._parse_gemini_stream_generation_response(- start_datetime,- response,- )-- # non-streaming- response = await self.client.aio.models.generate_content(- **kwargs,- )-- parsed_response = self._parse_gemini_generation_response(- start_datetime,- response,- )-- return parsed_response-- def _extract_usage(- self,- usage_metadata: Any,- start_datetime: datetime,- ) -> ChatUsage | None:- """Extract ChatUsage from usage_metadata safely, returning None if- unavailable or if token counts are None.-- Args:- usage_metadata:- The usage metadata object from the Gemini response.- start_datetime (`datetime`):- The start datetime of the generation.-- Returns:- `ChatUsage | None`:- A ChatUsage object, or None if data is unavailable.- """- if not usage_metadata:- return None- prompt_tokens = usage_metadata.prompt_token_count- total_tokens = usage_metadata.total_token_count- if prompt_tokens is not None and total_tokens is not None:- return ChatUsage(- input_tokens=prompt_tokens,- output_tokens=total_tokens - prompt_tokens,- time=(datetime.now() - start_datetime).total_seconds(),- )- return None-- # pylint: disable=too-many-branches- async def _parse_gemini_stream_generation_response(- self,- start_datetime: datetime,- response: AsyncIterator[GenerateContentResponse],- ) -> AsyncGenerator[ChatResponse, None]:- """Given a Gemini streaming generation response, extract the- content blocks and usages from it and yield ChatResponse objects.-- Args:- start_datetime (`datetime`):- The start datetime of the response generation.- response (`AsyncIterator[GenerateContentResponse]`):- Gemini GenerateContentResponse async iterator to parse.-- Returns:- `AsyncGenerator[ChatResponse, None]`:- An async generator that yields ChatResponse objects containing- the content blocks and usage information for each chunk in the- streaming response.- """-- # Accumulated state- acc_text = ""- acc_thinking = ""- acc_tool_calls: dict = {} # call_id -> {name, input}- usage = None-- async for chunk in response:- delta_content: list = []-- if (- chunk.candidates- and chunk.candidates[0].content- and chunk.candidates[0].content.parts- ):- for part in chunk.candidates[0].content.parts:- if part.text:- if part.thought:- acc_thinking += part.text- delta_content.append(- ThinkingBlock(thinking=part.text),- )- else:- acc_text += part.text- delta_content.append(TextBlock(text=part.text))-- if part.function_call:- keyword_args = part.function_call.args or {}- if part.thought_signature:- call_id = base64.b64encode(- part.thought_signature,- ).decode("utf-8")- else:- call_id = part.function_call.id-- input_str = json.dumps(- keyword_args,- ensure_ascii=False,- )- acc_tool_calls[call_id] = {- "name": part.function_call.name,- "input": input_str,- }- delta_content.append(- ToolCallBlock(- id=call_id,- name=part.function_call.name,- input=input_str,- ),- )-- usage = self._extract_usage(chunk.usage_metadata, start_datetime)-- if delta_content:- yield ChatResponse(- content=delta_content,- is_last=False,- usage=usage,- )-- # Build final accumulated content- final_content: list = []- if acc_thinking:- final_content.append(ThinkingBlock(thinking=acc_thinking))- if acc_text:- final_content.append(TextBlock(text=acc_text))- for call_id, tc in acc_tool_calls.items():- final_content.append(- ToolCallBlock(- id=call_id,- name=tc["name"],- input=tc["input"],- ),- )-- yield ChatResponse(- content=final_content,- is_last=True,- usage=usage,- )-- def _parse_gemini_generation_response(- self,- start_datetime: datetime,- response: GenerateContentResponse,- ) -> ChatResponse:- """Given a Gemini chat completion response object, extract the content- blocks and usages from it.-- Args:- start_datetime (`datetime`):- The start datetime of the response generation.- response (`GenerateContentResponse`):- The Gemini generation response object to parse.-- Returns:- ChatResponse (`ChatResponse`):- A ChatResponse object containing the content blocks and usage.- """- content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []-- if (- response.candidates- and response.candidates[0].content- and response.candidates[0].content.parts- ):- for part in response.candidates[0].content.parts:- if part.text:- if part.thought:- content_blocks.append(- ThinkingBlock(thinking=part.text),- )- else:- content_blocks.append(- TextBlock(text=part.text),- )-- if part.function_call:- keyword_args = part.function_call.args or {}- if part.thought_signature:- call_id = base64.b64encode(- part.thought_signature,- ).decode("utf-8")- else:- call_id = part.function_call.id-- content_blocks.append(- ToolCallBlock(- id=call_id,- name=part.function_call.name,- input=json.dumps(keyword_args, ensure_ascii=False),- ),- )-- usage = self._extract_usage(response.usage_metadata, start_datetime)-- return ChatResponse(- content=content_blocks,- is_last=True,- usage=usage,- )-- def _format_tools_json_schemas(- self,- schemas: list[dict[str, Any]],- ) -> list[dict[str, Any]]:- """Format the tools JSON schema into required format for Gemini API.-- .. note:: Gemini API does not support `$defs` and `$ref` in JSON- schemas. This function resolves all `$ref` references by inlining the- referenced definitions, producing a self-contained schema without- any references.-- Args:- schemas (`dict[str, Any]`):- The tools JSON schemas.-- Returns:- List[Dict[str, Any]]:- A list containing a dictionary with the- "function_declarations" key, which maps to a list of- function definitions.-- Example:- .. code-block:: python- :caption: Example tool schemas of Gemini API-- # Input JSON schema- schemas = [- {- 'type': 'function',- 'function': {- 'name': 'execute_shell_command',- 'description': 'xxx',- 'parameters': {- 'type': 'object',- 'properties': {- 'command': {- 'type': 'string',- 'description': 'xxx.'- },- 'timeout': {- 'type': 'integer',- 'default': 300- }- },- 'required': ['command']- }- }- }- ]-- # Output format (Gemini API expected):- [- {- 'function_declarations': [- {- 'name': 'execute_shell_command',- 'description': 'xxx.',- 'parameters': {- 'type': 'object',- 'properties': {- 'command': {- 'type': 'string',- 'description': 'xxx.'- },- 'timeout': {- 'type': 'integer',- 'default': 300- }- },- 'required': ['command']- }- }- ]- }- ]-- """- function_declarations = []- for schema in schemas:- if "function" not in schema:- continue- func = schema["function"].copy()- # Flatten the parameters schema to resolve $ref references- if "parameters" in func:- func["parameters"] = _flatten_json_schema(func["parameters"])- function_declarations.append(func)-- return [{"function_declarations": function_declarations}]-- def _format_tool_choice(- self,- tool_choice: ToolChoice | None,- tools: list[dict] | None,- ) -> dict | None:- """Format tool_choice parameter for API compatibility.-- Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be a mode ("auto",- "none", "required") or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation if- tool_choice is a specific function name.-- Returns:- `dict | None`:- The formatted tool choice configuration dict, or None if- tool_choice is None.- """- self._validate_tool_choice(tool_choice, tools)-- if tool_choice is None:- return None-- mode_mapping = {- "auto": "AUTO",- "none": "NONE",- "required": "ANY",- }- mode = mode_mapping.get(tool_choice)- if mode:- return {"function_calling_config": {"mode": mode}}- return {- "function_calling_config": {- "mode": "ANY",- "allowed_function_names": [tool_choice],- },- }diff --git a/src/agentscope/model/_kimi/__init__.py b/src/agentscope/model/_kimi/__init__.pynew file mode 100644index 000000000..fb5632be1--- /dev/null+++ b/src/agentscope/model/_kimi/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""The Kimi (Moonshot AI) LLM API modules."""++from ._model import KimiCredential, KimiChatModel++__all__ = [+ "KimiCredential",+ "KimiChatModel",+]diff --git a/src/agentscope/model/_kimi/_model.py b/src/agentscope/model/_kimi/_model.pynew file mode 100644index 000000000..1d3991a1c--- /dev/null+++ b/src/agentscope/model/_kimi/_model.py@@ -0,0 +1,375 @@+# -*- coding: utf-8 -*-+"""The Kimi (Moonshot AI) chat model implementation."""+from collections import OrderedDict+from datetime import datetime+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List++from pydantic import BaseModel, Field++from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import KimiCredential+from ...formatter import FormatterBase, KimiChatFormatter+from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...tool import ToolChoice+from ...tracing import trace_llm++if TYPE_CHECKING:+ from openai.types.chat import ChatCompletion+ from openai import AsyncStream+else:+ ChatCompletion = Any+ AsyncStream = Any+++class KimiChatModel(ChatModelBase):+ """The Kimi (Moonshot AI) chat model."""++ class Parameters(BaseModel):+ """The parameters for the Kimi chat model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of tokens for the LLM output.",+ gt=0,+ )++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ le=1,+ )++ top_p: float | None = Field(+ default=None,+ title="Top P",+ description="The top P value for the LLM output.",+ gt=0,+ le=1,+ )++ type: Literal["kimi_chat"] = "kimi_chat"+ """The type of the chat model."""++ def __init__(+ self,+ credential: KimiCredential,+ model: str,+ parameters: "KimiChatModel.Parameters | None" = None,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 131072,+ formatter: FormatterBase | None = None,+ ) -> None:+ """Initialize the Kimi chat model.++ Args:+ credential (`KimiCredential`):+ The Kimi (Moonshot AI) credential used to authenticate API+ calls.+ model (`str`):+ The Kimi model name, e.g. ``moonshot-v1-8k``.+ parameters (`KimiChatModel.Parameters | None`, defaults to \+ `None`):+ The Kimi API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the Kimi API.+ context_size (`int`, defaults to `131072`):+ The model context size used for context compression.+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the Kimi API. When ``None``, a+ ``KimiChatFormatter`` instance will be used.+ """+ super().__init__(+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,+ )+ self.credential = credential+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or KimiChatFormatter()++ @trace_llm+ async def _call_api(+ self,+ model_name: str,+ messages: list[Any],+ tools: list[dict] | None = None,+ tool_choice: ToolChoice | None = None,+ **generate_kwargs: Any,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Call the Kimi chat API (OpenAI-compatible).++ Args:+ model_name (`str`):+ The model name to use for this call.+ messages (`list`):+ A list of message dicts with ``role`` and ``content`` keys.+ tools (`list[dict]`, default `None`):+ The tools JSON schemas.+ tool_choice (`ToolChoice | None`, optional):+ Controls which (if any) tool is called by the model.+ **generate_kwargs (`Any`):+ Extra keyword arguments forwarded to the API.++ Returns:+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """+ import openai++ client = openai.AsyncClient(+ api_key=self.credential.api_key.get_secret_value(),+ base_url=self.credential.base_url,+ )++ formatted_messages = await self.formatter.format(messages)++ kwargs: dict[str, Any] = {+ "model": model_name,+ "messages": formatted_messages,+ "stream": self.stream,+ }++ if self.parameters.max_tokens is not None:+ kwargs["max_tokens"] = self.parameters.max_tokens++ if self.parameters.temperature is not None:+ kwargs["temperature"] = self.parameters.temperature++ if self.parameters.top_p is not None:+ kwargs["top_p"] = self.parameters.top_p++ kwargs.update(generate_kwargs)++ if tools:+ kwargs["tools"] = tools++ if tool_choice:+ kwargs["tool_choice"] = self._format_tool_choice(+ tool_choice,+ tools,+ )++ if self.stream:+ kwargs["stream_options"] = {"include_usage": True}++ start_datetime = datetime.now()+ response = await client.chat.completions.create(**kwargs)++ if self.stream:+ return self._parse_stream_response(start_datetime, response)++ return self._parse_completion_response(start_datetime, response)++ async def _parse_stream_response(+ self,+ start_datetime: datetime,+ response: AsyncStream,+ ) -> AsyncGenerator[ChatResponse, None]:+ """Parse the Kimi streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`AsyncStream`):+ The OpenAI-compatible async stream object.++ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True``.+ """+ usage = None+ response_id: str | None = None+ # All delta should have the same block identifier+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")+ acc_tool_calls: OrderedDict = OrderedDict()++ async with response as stream:+ async for chunk in stream:+ if chunk.usage:+ usage = ChatUsage(+ input_tokens=chunk.usage.prompt_tokens,+ output_tokens=chunk.usage.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=chunk.usage,+ )++ # Capture response_id from the first chunk that carries it+ response_id = response_id or getattr(chunk, "id", None)++ if not chunk.choices:+ continue++ choice = chunk.choices[0]+ delta = choice.delta++ # Kimi thinking models (kimi-k2.6, kimi-k2-thinking) return+ # reasoning_content before content in the stream.+ delta_thinking = (+ getattr(delta, "reasoning_content", None) or ""+ )+ if delta_thinking:+ acc_thinking.thinking += delta_thinking+ _thinking_kwargs: dict[str, Any] = {+ "content": [+ ThinkingBlock(+ id=acc_thinking.id,+ thinking=delta_thinking,+ ),+ ],+ "usage": usage,+ "is_last": False,+ }+ if response_id:+ _thinking_kwargs["id"] = response_id+ yield ChatResponse(**_thinking_kwargs)+ continue++ delta_text = getattr(delta, "content", None) or ""+ acc_text.text += delta_text++ for tool_call in getattr(delta, "tool_calls", None) or []:+ idx = tool_call.index+ if idx in acc_tool_calls:+ if tool_call.function.arguments is not None:+ acc_tool_calls[idx][+ "input"+ ] += tool_call.function.arguments+ else:+ acc_tool_calls[idx] = {+ "id": tool_call.id,+ "name": tool_call.function.name,+ "input": tool_call.function.arguments or "",+ }++ if delta_text:+ _text_kwargs: dict[str, Any] = {+ "content": [+ TextBlock(id=acc_text.id, text=delta_text),+ ],+ "usage": usage,+ "is_last": False,+ }+ if response_id:+ _text_kwargs["id"] = response_id+ yield ChatResponse(**_text_kwargs)++ final_contents: List[ThinkingBlock | TextBlock | ToolCallBlock] = []+ if acc_thinking.thinking:+ final_contents.append(acc_thinking)+ if acc_text.text:+ final_contents.append(acc_text)+ for tc in acc_tool_calls.values():+ final_contents.append(+ ToolCallBlock(id=tc["id"], name=tc["name"], input=tc["input"]),+ )++ _final_kwargs: dict[str, Any] = {+ "content": final_contents,+ "usage": usage,+ "is_last": True,+ }+ if response_id:+ _final_kwargs["id"] = response_id+ yield ChatResponse(**_final_kwargs)++ def _parse_completion_response(+ self,+ start_datetime: datetime,+ response: ChatCompletion,+ ) -> ChatResponse:+ """Parse the Kimi non-streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`ChatCompletion`):+ The OpenAI-compatible chat completion object.++ Returns:+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True``.+ """+ content_blocks: List[ThinkingBlock | TextBlock | ToolCallBlock] = []++ if response.choices:+ choice = response.choices[0]+ reasoning = getattr(choice.message, "reasoning_content", None)+ if reasoning:+ content_blocks.append(ThinkingBlock(thinking=reasoning))++ if choice.message.content:+ content_blocks.append(TextBlock(text=choice.message.content))++ for tool_call in choice.message.tool_calls or []:+ content_blocks.append(+ ToolCallBlock(+ id=tool_call.id,+ name=tool_call.function.name,+ input=tool_call.function.arguments,+ ),+ )++ usage = None+ if response.usage:+ usage = ChatUsage(+ input_tokens=response.usage.prompt_tokens,+ output_tokens=response.usage.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=response.usage,+ )++ resp_kwargs: dict[str, Any] = {+ "content": content_blocks,+ "is_last": True,+ "usage": usage,+ }+ response_id = getattr(response, "id", None)+ if response_id:+ resp_kwargs["id"] = response_id++ return ChatResponse(**resp_kwargs)++ def _format_tool_choice(+ self,+ tool_choice: ToolChoice | None,+ tools: list[dict] | None,+ ) -> str | dict | None:+ """Format tool_choice parameter for the Kimi API.++ Args:+ tool_choice (`ToolChoice | None`):+ The unified tool choice parameter which can be ``"auto"``,+ ``"none"``, ``"required"``, or a specific function name.+ tools (`list[dict] | None`):+ The list of available tools, used for validation when+ ``tool_choice`` is a specific function name.++ Returns:+ `str | dict | None`:+ The formatted tool choice string or configuration dict for+ the Kimi API, or ``None`` if ``tool_choice`` is ``None``.+ """+ self._validate_tool_choice(tool_choice, tools)++ if tool_choice is None:+ return None++ if tool_choice in ["auto", "none", "required"]:+ return tool_choice++ return {"type": "function", "function": {"name": tool_choice}}diff --git a/src/agentscope/model/_kimi/_models/kimi-k2.5.yaml b/src/agentscope/model/_kimi/_models/kimi-k2.5.yamlnew file mode 100644index 000000000..bc2e2739a--- /dev/null+++ b/src/agentscope/model/_kimi/_models/kimi-k2.5.yaml@@ -0,0 +1,22 @@+name: kimi-k2.5+label: Kimi K2.5+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 262144+output_size: 65536++parameter_overrides:+ max_tokens:+ maximum: 65536diff --git a/src/agentscope/model/_kimi/_models/kimi-k2.6.yaml b/src/agentscope/model/_kimi/_models/kimi-k2.6.yamlnew file mode 100644index 000000000..53c58bd9e--- /dev/null+++ b/src/agentscope/model/_kimi/_models/kimi-k2.6.yaml@@ -0,0 +1,27 @@+name: kimi-k2.6+label: Kimi K2.6+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp+ - video/mp4+ - video/mpeg+ - video/quicktime+ - video/avi+ - video/webm++output_types:+ - text/plain+ - application/x-thinking++context_size: 262144+output_size: 32768++parameter_overrides:+ max_tokens:+ maximum: 32768diff --git a/src/agentscope/model/_kimi/_models/moonshot-v1-128k.yaml b/src/agentscope/model/_kimi/_models/moonshot-v1-128k.yamlnew file mode 100644index 000000000..7bfa9a9fb--- /dev/null+++ b/src/agentscope/model/_kimi/_models/moonshot-v1-128k.yaml@@ -0,0 +1,16 @@+name: moonshot-v1-128k+label: Kimi Moonshot v1 128K+status: active++input_types:+ - text/plain++output_types:+ - text/plain++context_size: 131072+output_size: 131072++parameter_overrides:+ max_tokens:+ maximum: 131072diff --git a/src/agentscope/model/_kimi/_models/moonshot-v1-32k.yaml b/src/agentscope/model/_kimi/_models/moonshot-v1-32k.yamlnew file mode 100644index 000000000..b6ffdd288--- /dev/null+++ b/src/agentscope/model/_kimi/_models/moonshot-v1-32k.yaml@@ -0,0 +1,16 @@+name: moonshot-v1-32k+label: Kimi Moonshot v1 32K+status: active++input_types:+ - text/plain++output_types:+ - text/plain++context_size: 32768+output_size: 32768++parameter_overrides:+ max_tokens:+ maximum: 32768diff --git a/src/agentscope/model/_kimi/_models/moonshot-v1-8k.yaml b/src/agentscope/model/_kimi/_models/moonshot-v1-8k.yamlnew file mode 100644index 000000000..488cd8d74--- /dev/null+++ b/src/agentscope/model/_kimi/_models/moonshot-v1-8k.yaml@@ -0,0 +1,16 @@+name: moonshot-v1-8k+label: Kimi Moonshot v1 8K+status: active++input_types:+ - text/plain++output_types:+ - text/plain++context_size: 8192+output_size: 8192++parameter_overrides:+ max_tokens:+ maximum: 8192diff --git a/src/agentscope/model/_model_card.py b/src/agentscope/model/_model_card.pynew file mode 100644index 000000000..711ae6654--- /dev/null+++ b/src/agentscope/model/_model_card.py@@ -0,0 +1,150 @@+# -*- coding: utf-8 -*-+"""The model card class."""+import copy+from datetime import datetime+from typing import Literal, Self, Type++import yaml+from pydantic import BaseModel, Field+++class ModelCard(BaseModel):+ """The model card class."""++ type: Literal["chat_model"] = "chat_model"+ """The model card type."""++ name: str = Field(description="The name of the model")+ """The model name."""++ label: str = Field(description="The model label.")+ """The model label used for frontend rendering."""++ status: Literal["active", "deprecated", "sunset"] = Field(+ title="Status",+ description="The model status",+ )+ """The model status."""++ deprecated_at: datetime | None = Field(+ default=None,+ description="The model deprecation date and time.",+ title="Deprecation date",+ )+ """The model deprecated at."""++ input_types: list[str] = Field(+ description="The supported model input types.",+ title="Input types",+ default=["text/plain"],+ )+ """The model supported input types."""++ output_types: list[str] = Field(+ description="The supported model output types.",+ title="Output types",+ default=["text/plain"],+ )+ """The model supported output types."""++ context_size: int = Field(+ title="Context size",+ description="The context size.",+ gt=0,+ )+ """The model context size."""++ output_size: int = Field(+ title="Max output tokens",+ description="The maximum number of tokens.",+ gt=0,+ )+ """The model max output tokens."""++ parameter_schema: dict+ """The parameters schema, which will be combined with the schema from the+ DashScopeChatParameter class."""++ parameters_overrides: dict[str, dict]+ """The parameter overrides, which will be merged into the parameter schema.+ """++ @classmethod+ def from_yaml(+ cls,+ yaml_path: str,+ parameter_class: Type[BaseModel],+ ) -> Self:+ """Read a model card from a YAML file, and merge the parameter schema+ with the override parameter schema in the yaml file.++ Args:+ yaml_path (`str`):+ Path to the YAML file+ parameter_class (`Type[BaseModel]`):+ The parameter class (e.g., DashScopeChatParameters)++ Returns:+ `list[ModelCard]`:+ ModelCard instance with merged parameter schema+ """++ # Load YAML config+ with open(yaml_path, "r", encoding="utf-8") as file:+ config = yaml.safe_load(file)++ # Get base schema from parameter class+ base_schema = parameter_class.model_json_schema()+ properties = copy.deepcopy(base_schema.get("properties", {}))++ # Auto-filter: remove thinking parameters if not supported+ output_types = config.get("output_types", [])+ if "application/x-thinking" not in output_types:+ properties.pop("thinking_enable", None)+ properties.pop("thinking_budget", None)++ # Auto-inject: set max_tokens maximum from output_size+ if "max_tokens" in properties and "output_size" in config:+ properties["max_tokens"]["maximum"] = config["output_size"]++ # Apply parameter_overrides with simple dict merge+ overrides = config.get("parameter_overrides", {})+ for param_name, override in overrides.items():+ if override is None:+ # null means remove+ properties.pop(param_name, None)+ continue++ if isinstance(override, dict):+ # Check for hidden flag+ if override.get("hidden"):+ properties.pop(param_name, None)+ continue++ # Simple dict merge: {**base, **override}+ if param_name in properties:+ properties[param_name] = {+ **properties[param_name],+ **override,+ }++ # Build final parameter schema+ final_schema = {+ "type": "object",+ "properties": properties,+ "required": base_schema.get("required", []),+ }++ # Create ModelCard instance+ return cls(+ name=config["name"],+ label=config["label"],+ status=config.get("status", "active"),+ deprecated_at=config.get("deprecated_at"),+ input_types=config.get("input_types", ["text/plain"]),+ output_types=config.get("output_types", ["text/plain"]),+ context_size=config["context_size"],+ output_size=config["output_size"],+ parameter_schema=final_schema,+ parameters_overrides=config.get("parameter_overrides", {}),+ )diff --git a/src/agentscope/model/_ollama/__init__.py b/src/agentscope/model/_ollama/__init__.pynew file mode 100644index 000000000..0e152fc0c--- /dev/null+++ b/src/agentscope/model/_ollama/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""The Ollama LLM API modules."""++from ._model import OllamaCredential, OllamaChatModel++__all__ = [+ "OllamaCredential",+ "OllamaChatModel",+]diff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.pynew file mode 100644index 000000000..bd3dbb43e--- /dev/null+++ b/src/agentscope/model/_ollama/_model.py@@ -0,0 +1,310 @@+# -*- coding: utf-8 -*-+"""The Ollama chat model implementation."""+import json+import uuid+from datetime import datetime+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List++from pydantic import BaseModel, Field++from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import OllamaCredential+from ...formatter import FormatterBase, OllamaChatFormatter+from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...tool import ToolChoice+from ...tracing import trace_llm+from ..._logging import logger++if TYPE_CHECKING:+ from ollama._types import ChatResponse as OllamaChatResponse+else:+ OllamaChatResponse = Any+++class OllamaChatModel(ChatModelBase):+ """The Ollama chat model."""++ class Parameters(BaseModel):+ """The parameters for the Ollama chat model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of tokens for the LLM output.",+ gt=0,+ )++ thinking_enable: bool = Field(+ default=False,+ title="Thinking",+ description="Whether to enable thinking"+ " (for models like qwen3, deepseek-r1).",+ )++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ le=2,+ )++ type: Literal["ollama_chat"] = "ollama_chat"+ """The type of the chat model."""++ def __init__(+ self,+ credential: OllamaCredential | None = None,+ model: str = "",+ parameters: "OllamaChatModel.Parameters | None" = None,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 32768,+ formatter: FormatterBase | None = None,+ ) -> None:+ """Initialize the Ollama chat model.++ Args:+ credential (`OllamaCredential | None`, defaults to `None`):+ The Ollama connection settings. When ``None``, a default+ ``OllamaCredential`` (localhost) will be used.+ model (`str`):+ The Ollama model name, e.g. ``llama3.3`` or ``qwen3:14b``.+ parameters (`OllamaChatModel.Parameters | None`, defaults to \+ `None`):+ The Ollama API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the Ollama API.+ context_size (`int`, defaults to `32768`):+ The model context size used for context compression.+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the Ollama API. When ``None``, an+ ``OllamaChatFormatter`` instance will be used.+ """+ super().__init__(+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,+ )+ self.credential = credential or OllamaCredential()+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or OllamaChatFormatter()++ @trace_llm+ async def _call_api(+ self,+ model_name: str,+ messages: list[Any],+ tools: list[dict] | None = None,+ tool_choice: ToolChoice | None = None,+ **generate_kwargs: Any,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Call the Ollama chat API.++ Args:+ model_name (`str`):+ The model name to use for this call.+ messages (`list`):+ A list of message dicts with ``role`` and ``content`` keys.+ tools (`list[dict]`, default `None`):+ The tools JSON schemas.+ tool_choice (`ToolChoice | None`, optional):+ Not supported by Ollama yet (ignored with warning).+ **generate_kwargs (`Any`):+ Extra keyword arguments forwarded to the Ollama API.++ Returns:+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """+ import ollama++ client = ollama.AsyncClient(host=self.credential.host)++ formatted_messages = await self.formatter.format(messages)++ kwargs: dict[str, Any] = {+ "model": model_name,+ "messages": formatted_messages,+ "stream": self.stream,+ }++ options: dict[str, Any] = {}+ if self.parameters.max_tokens is not None:+ options["num_predict"] = self.parameters.max_tokens+ if self.parameters.temperature is not None:+ options["temperature"] = self.parameters.temperature+ if options:+ kwargs["options"] = options++ if self.parameters.thinking_enable:+ kwargs["think"] = True++ kwargs.update(generate_kwargs)++ if tools:+ kwargs["tools"] = tools++ if tool_choice:+ logger.warning("Ollama does not support tool_choice yet, ignored.")++ start_datetime = datetime.now()+ response = await client.chat(**kwargs)++ if self.stream:+ return self._parse_stream_response(start_datetime, response)++ return await self._parse_completion_response(start_datetime, response)++ async def _parse_stream_response(+ self,+ start_datetime: datetime,+ response: Any,+ ) -> AsyncGenerator[ChatResponse, None]:+ """Parse the Ollama streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`Any`):+ The Ollama async stream object.++ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True``.+ """+ # All delta should have the same block identifier.+ # Ollama does not return a request id, so we generate one upfront+ # to keep it stable.+ response_id = getattr(response, "id", None) or uuid.uuid4().hex+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")+ acc_tool_calls: dict = {}+ usage = None++ async for chunk in response:+ delta_content: list = []+ msg = chunk.message++ chunk_thinking = getattr(msg, "thinking", None)+ if chunk_thinking:+ acc_thinking.thinking += chunk_thinking+ delta_content.append(+ ThinkingBlock(id=acc_thinking.id, thinking=chunk_thinking),+ )++ if msg.content:+ acc_text.text += msg.content+ delta_content.append(+ TextBlock(id=acc_text.id, text=msg.content),+ )++ for idx, tool_call in enumerate(msg.tool_calls or []):+ function = tool_call.function+ tool_id = f"{idx}_{function.name}"+ input_str = json.dumps(function.arguments)+ acc_tool_calls[tool_id] = {+ "name": function.name,+ "input": input_str,+ }+ delta_content.append(+ ToolCallBlock(+ id=tool_id,+ name=function.name,+ input=input_str,+ ),+ )++ current_time = (datetime.now() - start_datetime).total_seconds()+ usage = ChatUsage(+ input_tokens=getattr(chunk, "prompt_eval_count", 0) or 0,+ output_tokens=getattr(chunk, "eval_count", 0) or 0,+ time=current_time,+ )++ if delta_content:+ yield ChatResponse(+ id=response_id,+ content=delta_content,+ is_last=False,+ usage=usage,+ )++ final_content: list = []+ if acc_thinking.thinking:+ final_content.append(acc_thinking)+ if acc_text.text:+ final_content.append(acc_text)+ for tool_id, tc in acc_tool_calls.items():+ final_content.append(+ ToolCallBlock(id=tool_id, name=tc["name"], input=tc["input"]),+ )++ yield ChatResponse(+ id=response_id,+ content=final_content,+ is_last=True,+ usage=usage,+ )++ async def _parse_completion_response(+ self,+ start_datetime: datetime,+ response: OllamaChatResponse,+ ) -> ChatResponse:+ """Parse the Ollama non-streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`OllamaChatResponse`):+ The Ollama chat response object.++ Returns:+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True``.+ """+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []++ message_thinking = getattr(response.message, "thinking", None)+ if message_thinking:+ content_blocks.append(ThinkingBlock(thinking=message_thinking))++ if response.message.content:+ content_blocks.append(TextBlock(text=response.message.content))++ for idx, tool_call in enumerate(response.message.tool_calls or []):+ content_blocks.append(+ ToolCallBlock(+ id=f"{idx}_{tool_call.function.name}",+ name=tool_call.function.name,+ input=json.dumps(tool_call.function.arguments),+ ),+ )++ usage = None+ prompt_eval = getattr(response, "prompt_eval_count", None)+ eval_count = getattr(response, "eval_count", None)+ if prompt_eval is not None and eval_count is not None:+ usage = ChatUsage(+ input_tokens=prompt_eval,+ output_tokens=eval_count,+ time=(datetime.now() - start_datetime).total_seconds(),+ )++ return ChatResponse(+ id=getattr(response, "id", None) or uuid.uuid4().hex,+ content=content_blocks,+ is_last=True,+ usage=usage,+ )diff --git a/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml b/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yamlnew file mode 100644index 000000000..4e968ad92--- /dev/null+++ b/src/agentscope/model/_ollama/_models/deepseek-r1-14b.yaml@@ -0,0 +1,17 @@+name: deepseek-r1:14b+label: DeepSeek R1 14B+status: active++input_types:+ - text/plain++output_types:+ - text/plain+ - application/x-thinking++context_size: 131072+output_size: 8192++parameter_overrides:+ max_tokens:+ maximum: 8192diff --git a/src/agentscope/model/_ollama/_models/llama4.yaml b/src/agentscope/model/_ollama/_models/llama4.yamlnew file mode 100644index 000000000..502df9207--- /dev/null+++ b/src/agentscope/model/_ollama/_models/llama4.yaml@@ -0,0 +1,22 @@+name: llama4+label: Llama 4 Scout+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain++context_size: 10485760+output_size: 8192++parameter_overrides:+ max_tokens:+ maximum: 8192+ thinking_enable:+ hidden: truediff --git a/src/agentscope/model/_ollama/_models/qwen3-14b.yaml b/src/agentscope/model/_ollama/_models/qwen3-14b.yamlnew file mode 100644index 000000000..e7fa9836e--- /dev/null+++ b/src/agentscope/model/_ollama/_models/qwen3-14b.yaml@@ -0,0 +1,17 @@+name: qwen3:14b+label: Qwen3 14B+status: active++input_types:+ - text/plain++output_types:+ - text/plain+ - application/x-thinking++context_size: 40960+output_size: 8192++parameter_overrides:+ max_tokens:+ maximum: 8192diff --git a/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml b/src/agentscope/model/_ollama/_models/qwen3.5-9b.yamlnew file mode 100644index 000000000..d517d33c7--- /dev/null+++ b/src/agentscope/model/_ollama/_models/qwen3.5-9b.yaml@@ -0,0 +1,17 @@+name: qwen3.5+label: Qwen3.5 9B+status: active++input_types:+ - text/plain++output_types:+ - text/plain+ - application/x-thinking++context_size: 262144+output_size: 8192++parameter_overrides:+ max_tokens:+ maximum: 8192diff --git a/src/agentscope/model/_ollama_model.py b/src/agentscope/model/_ollama_model.pydeleted file mode 100644index c69c0a480..000000000--- a/src/agentscope/model/_ollama_model.py+++ /dev/null@@ -1,352 +0,0 @@-# -*- coding: utf-8 -*--"""Model wrapper for Ollama models."""-import json-from datetime import datetime-from typing import (- Any,- TYPE_CHECKING,- List,- AsyncGenerator,- AsyncIterator,- Literal,-)--from pydantic import BaseModel--from . import ChatResponse-from ._model_base import ChatModelBase-from ._model_usage import ChatUsage-from .._logging import logger-from ..formatter import FormatterBase, OllamaChatFormatter-from ..message import ToolCallBlock, TextBlock, ThinkingBlock-from ..tracing import trace_llm-from ..types import JSONSerializableObject--if TYPE_CHECKING:- from ollama._types import ChatResponse as OllamaChatResponse-else:- OllamaChatResponse = "ollama._types.ChatResponse"---class OllamaChatModel(ChatModelBase):- """The Ollama chat model class in agentscope."""-- class ThinkingConfig(BaseModel):- """Configuration for thinking in Ollama chat models."""-- enable_thinking: bool-- def __init__(- self,- model_name: str,- context_length: int,- stream: bool = False,- max_retries: int = 0,- fallback_model_name: str | None = None,- formatter: FormatterBase | None = None,- thinking_config: ThinkingConfig | None = None,- options: dict = None,- keep_alive: str = "5m",- host: str | None = None,- client_kwargs: dict[str, JSONSerializableObject] | None = None,- generate_kwargs: dict[str, JSONSerializableObject] | None = None,- ) -> None:- """Initialize the Ollama chat model.-- Args:- model_name (`str`):- The name of the model.- context_length (`int`):- The context length of the model, which will be used in- context compression.- stream (`bool`, default `True`):- Streaming mode or not.- max_retries (`int`, optional):- Maximum number of retries on failure. Defaults to 0.- fallback_model_name (`str | None`, optional):- Fallback model name to use after all retries fail.- formatter (`FormatterBase | None`, optional):- Formatter for message preprocessing.- thinking_config (`ThinkingConfig | None`, default `None`)- Configuration for thinking, only for models such as qwen3,- deepseek-r1, etc.- options (`dict`, default `None`):- Additional parameters to pass to the Ollama API. These can- include temperature etc.- keep_alive (`str`, default `"5m"`):- Duration to keep the model loaded in memory. The format is a- number followed by a unit suffix (s for seconds, m for minutes- , h for hours).- host (`str | None`, default `None`):- The host address of the Ollama server. If None, uses the- default address (typically http://localhost:11434).- client_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments to initialize the Ollama client.- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments used in Ollama API generation.- """-- try:- import ollama- except ImportError as e:- raise ImportError(- "The package ollama is not found. Please install it by "- 'running command `pip install "ollama>=0.1.7"`',- ) from e-- super().__init__(- model_name=model_name,- stream=stream,- context_length=context_length,- max_retries=max_retries,- fallback_model_name=fallback_model_name,- formatter=formatter or OllamaChatFormatter(),- )-- self.client = ollama.AsyncClient(- host=host,- **(client_kwargs or {}),- )- self.options = options- self.keep_alive = keep_alive- self.thinking_config = thinking_config- self.generate_kwargs = generate_kwargs or {}-- @trace_llm- async def _call_api(- self,- model_name: str,- messages: list[dict[str, Any]],- tools: list[dict] | None = None,- tool_choice: Literal["auto", "none", "required"] | str | None = None,- **kwargs: Any,- ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:- """Get the response from Ollama chat completions API by the given- arguments.-- Args:- model_name (`str`):- The model name to use for this call.- messages (`list[dict]`):- A list of dictionaries, where `role` and `content` fields are- required, and `name` field is optional.- tools (`list[dict]`, default `None`):- The tools JSON schemas that the model can use.- tool_choice (`Literal["auto", "none", "required"] | str \- | None`, default `None`):- Ollama doesn't support `tool_choice` argument yet.- **kwargs (`Any`):- The keyword arguments for Ollama chat completions API,- e.g. `think`etc. Please refer to the Ollama API- documentation for more details.-- Returns:- `ChatResponse | AsyncGenerator[ChatResponse, None]`:- The response from the Ollama chat completions API.- """-- kwargs = {- "model": model_name,- "messages": messages,- "stream": self.stream,- "options": self.options,- "keep_alive": self.keep_alive,- **self.generate_kwargs,- **kwargs,- }-- if self.thinking_config and "think" not in kwargs:- kwargs["think"] = self.thinking_config.enable_thinking-- if tools:- kwargs["tools"] = self._format_tools_json_schemas(tools)-- if tool_choice:- logger.warning("Ollama does not support tool_choice yet, ignored.")-- start_datetime = datetime.now()- response = await self.client.chat(**kwargs)-- if self.stream:- return self._parse_ollama_stream_completion_response(- start_datetime,- response,- )-- parsed_response = await self._parse_ollama_completion_response(- start_datetime,- response,- )-- return parsed_response-- async def _parse_ollama_stream_completion_response(- self,- start_datetime: datetime,- response: AsyncIterator[OllamaChatResponse],- ) -> AsyncGenerator[ChatResponse, None]:- """Given an Ollama streaming completion response, extract the- content blocks and usages from it and yield ChatResponse objects.-- Args:- start_datetime (`datetime`):- The start datetime of the response generation.- response (`AsyncIterator[OllamaChatResponse]`):- Ollama streaming response async iterator to parse.-- Returns:- AsyncGenerator[ChatResponse, None]:- An async generator that yields ChatResponse objects containing- the content blocks and usage information for each chunk in the- streaming response.-- """- # Accumulated state- acc_text = ""- acc_thinking = ""- acc_tool_calls: dict = {} # tool_id -> {name, input}- response_id: str | None = None- usage = None-- async for chunk in response:- delta_content: list = []- msg = chunk.message-- # Handle thinking delta- if msg.thinking:- acc_thinking += msg.thinking- delta_content.append(ThinkingBlock(thinking=msg.thinking))-- # Handle text delta- if msg.content:- acc_text += msg.content- delta_content.append(TextBlock(text=msg.content))-- # Handle tool calls- for idx, tool_call in enumerate(msg.tool_calls or []):- function = tool_call.function- tool_id = f"{idx}_{function.name}"- input_str = json.dumps(function.arguments)- acc_tool_calls[tool_id] = {- "name": function.name,- "input": input_str,- }- delta_content.append(- ToolCallBlock(- id=tool_id,- name=function.name,- input=input_str,- ),- )-- if response_id is None:- response_id = getattr(chunk, "id", None)-- # Calculate usage- current_time = (datetime.now() - start_datetime).total_seconds()- usage = ChatUsage(- input_tokens=getattr(chunk, "prompt_eval_count", 0) or 0,- output_tokens=getattr(chunk, "eval_count", 0) or 0,- time=current_time,- )-- if delta_content:- _kwargs: dict[str, Any] = {- "content": delta_content,- "is_last": False,- "usage": usage,- }- if response_id:- _kwargs["id"] = response_id- yield ChatResponse(**_kwargs)-- # Build final accumulated content- final_content: list = []- if acc_thinking:- final_content.append(ThinkingBlock(thinking=acc_thinking))- if acc_text:- final_content.append(TextBlock(text=acc_text))- for tool_id, tc in acc_tool_calls.items():- final_content.append(- ToolCallBlock(- id=tool_id,- name=tc["name"],- input=tc["input"],- ),- )-- _final_kwargs: dict[str, Any] = {- "content": final_content,- "is_last": True,- "usage": usage,- }- if response_id:- _final_kwargs["id"] = response_id- yield ChatResponse(**_final_kwargs)-- async def _parse_ollama_completion_response(- self,- start_datetime: datetime,- response: OllamaChatResponse,- ) -> ChatResponse:- """Given an Ollama chat completion response object, extract the content- blocks and usages from it.-- Args:- start_datetime (`datetime`):- The start datetime of the response generation.- response (`OllamaChatResponse`):- Ollama OllamaChatResponse object to parse.-- Returns:- `ChatResponse`:- A ChatResponse object containing the content blocks and usage.- """- content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []-- if response.message.thinking:- content_blocks.append(- ThinkingBlock(thinking=response.message.thinking),- )-- if response.message.content:- content_blocks.append(- TextBlock(text=response.message.content),- )-- for idx, tool_call in enumerate(response.message.tool_calls or []):- content_blocks.append(- ToolCallBlock(- id=f"{idx}_{tool_call.function.name}",- name=tool_call.function.name,- input=json.dumps(tool_call.function.arguments),- ),- )-- usage = None- if "prompt_eval_count" in response and "eval_count" in response:- usage = ChatUsage(- input_tokens=response.get("prompt_eval_count", 0),- output_tokens=response.get("eval_count", 0),- time=(datetime.now() - start_datetime).total_seconds(),- )-- resp_kwargs: dict[str, Any] = {- "content": content_blocks,- "is_last": True,- "usage": usage,- }- response_id = getattr(response, "id", None)- if response_id:- resp_kwargs["id"] = response_id-- return ChatResponse(**resp_kwargs)-- def _format_tools_json_schemas(- self,- schemas: list[dict[str, Any]],- ) -> list[dict[str, Any]]:- """Format the tools JSON schemas to the Ollama format."""- return schemasdiff --git a/src/agentscope/model/_openai_chat/__init__.py b/src/agentscope/model/_openai_chat/__init__.pynew file mode 100644index 000000000..c3e39e091--- /dev/null+++ b/src/agentscope/model/_openai_chat/__init__.py@@ -0,0 +1,8 @@+# -*- coding: utf-8 -*-+"""The OpenAI Chat Completions API modules."""++from ._model import OpenAIChatModel++__all__ = [+ "OpenAIChatModel",+]diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.pynew file mode 100644index 000000000..3bcf4709d--- /dev/null+++ b/src/agentscope/model/_openai_chat/_model.py@@ -0,0 +1,394 @@+# -*- coding: utf-8 -*-+"""The OpenAI Chat Completions model implementation."""+from collections import OrderedDict+from datetime import datetime+from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, List++from pydantic import BaseModel, Field++from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import OpenAICredential+from ...formatter import FormatterBase, OpenAIChatFormatter+from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...tool import ToolChoice+from ...tracing import trace_llm++if TYPE_CHECKING:+ from openai.types.chat import ChatCompletion+ from openai import AsyncStream+else:+ ChatCompletion = Any+ AsyncStream = Any+++class OpenAIChatModel(ChatModelBase):+ """The OpenAI Chat Completions model."""++ class Parameters(BaseModel):+ """The parameters for the OpenAI Chat model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of tokens for the LLM output.",+ gt=0,+ )++ thinking_enable: bool = Field(+ default=False,+ title="Thinking",+ description=(+ "Whether to enable reasoning output. Note: for the OpenAI "+ "Chat Completions API, reasoning is controlled by model "+ "selection (e.g. o3, o4-mini) rather than an API parameter."+ ),+ )++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ le=2,+ )++ top_p: float | None = Field(+ default=None,+ title="Top P",+ description="The top P value for the LLM output.",+ gt=0,+ le=1,+ )++ parallel_tool_calls: bool = Field(+ default=True,+ title="Parallel Tool Calls",+ description="Whether to enable parallel tool calls.",+ )++ type: Literal["openai_chat"] = "openai_chat"+ """The type of the chat model."""++ def __init__(+ self,+ credential: OpenAICredential,+ model: str,+ parameters: "OpenAIChatModel.Parameters | None" = None,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 128000,+ formatter: FormatterBase | None = None,+ ) -> None:+ """Initialize the OpenAI chat model.++ Args:+ credential (`OpenAICredential`):+ The OpenAI credential used to authenticate API calls.+ model (`str`):+ The OpenAI model name, e.g. ``gpt-4.1``.+ parameters (`OpenAIChatModel.Parameters | None`, defaults to \+ `None`):+ The OpenAI Chat API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the OpenAI API.+ context_size (`int`, defaults to `128000`):+ The model context size used for context compression.+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the OpenAI API. When ``None``, an+ ``OpenAIChatFormatter`` instance will be used.+ """+ super().__init__(+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,+ )+ self.credential = credential+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or OpenAIChatFormatter()++ @trace_llm+ async def _call_api(+ self,+ model_name: str,+ messages: list[Any],+ tools: list[dict] | None = None,+ tool_choice: ToolChoice | None = None,+ **generate_kwargs: Any,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Call the OpenAI Chat Completions API.++ Args:+ model_name (`str`):+ The model name to use for this call.+ messages (`list`):+ A list of message dicts with ``role`` and ``content`` keys.+ tools (`list[dict]`, default `None`):+ The tools JSON schemas.+ tool_choice (`ToolChoice | None`, optional):+ Controls which (if any) tool is called by the model.+ **generate_kwargs (`Any`):+ Extra keyword arguments forwarded to the API.++ Returns:+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """+ import openai++ client = openai.AsyncClient(+ api_key=self.credential.api_key.get_secret_value(),+ organization=self.credential.organization,+ base_url=self.credential.base_url,+ )++ formatted_messages = await self.formatter.format(messages)++ kwargs: dict[str, Any] = {+ "model": model_name,+ "messages": formatted_messages,+ "stream": self.stream,+ }++ if self.parameters.max_tokens is not None:+ kwargs["max_tokens"] = self.parameters.max_tokens++ if self.parameters.temperature is not None:+ kwargs["temperature"] = self.parameters.temperature++ if self.parameters.top_p is not None:+ kwargs["top_p"] = self.parameters.top_p++ kwargs.update(generate_kwargs)++ if tools:+ kwargs["tools"] = tools+ if not self.parameters.parallel_tool_calls:+ kwargs["parallel_tool_calls"] = False++ if tool_choice:+ kwargs["tool_choice"] = self._format_tool_choice(+ tool_choice,+ tools,+ )++ if self.stream:+ kwargs["stream_options"] = {"include_usage": True}++ start_datetime = datetime.now()+ response = await client.chat.completions.create(**kwargs)++ if self.stream:+ return self._parse_stream_response(start_datetime, response)++ return self._parse_completion_response(start_datetime, response)++ async def _parse_stream_response(+ self,+ start_datetime: datetime,+ response: AsyncStream,+ ) -> AsyncGenerator[ChatResponse, None]:+ """Parse the OpenAI Chat streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`AsyncStream`):+ The OpenAI async stream object.++ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True``.+ """+ usage = None+ response_id: str | None = None+ # All delta should have the same block identifier+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")+ acc_tool_calls: OrderedDict = OrderedDict()++ async with response as stream:+ async for chunk in stream:+ if chunk.usage:+ usage = ChatUsage(+ input_tokens=chunk.usage.prompt_tokens,+ output_tokens=chunk.usage.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=chunk.usage,+ )++ # Capture response_id from the first chunk that carries it+ response_id = response_id or getattr(chunk, "id", None)++ if not chunk.choices:+ continue++ choice = chunk.choices[0]+ delta = choice.delta++ delta_thinking = getattr(delta, "reasoning_content", None)+ if not isinstance(delta_thinking, str):+ delta_thinking = getattr(delta, "reasoning", None)+ if not isinstance(delta_thinking, str):+ delta_thinking = ""++ delta_text = getattr(delta, "content", None) or ""++ acc_thinking.thinking += delta_thinking+ acc_text.text += delta_text++ for tool_call in getattr(delta, "tool_calls", None) or []:+ idx = tool_call.index+ if idx in acc_tool_calls:+ if tool_call.function.arguments is not None:+ acc_tool_calls[idx][+ "input"+ ] += tool_call.function.arguments+ else:+ acc_tool_calls[idx] = {+ "id": tool_call.id,+ "name": tool_call.function.name,+ "input": tool_call.function.arguments or "",+ }++ delta_contents: List[+ TextBlock | ToolCallBlock | ThinkingBlock+ ] = []+ if delta_thinking:+ delta_contents.append(+ ThinkingBlock(+ id=acc_thinking.id,+ thinking=delta_thinking,+ ),+ )+ if delta_text:+ delta_contents.append(+ TextBlock(id=acc_text.id, text=delta_text),+ )++ if delta_contents:+ _kwargs: dict[str, Any] = {+ "content": delta_contents,+ "usage": usage,+ "is_last": False,+ }+ if response_id:+ _kwargs["id"] = response_id+ yield ChatResponse(**_kwargs)++ final_contents: List[TextBlock | ToolCallBlock | ThinkingBlock] = []+ if acc_thinking.thinking:+ final_contents.append(acc_thinking)+ if acc_text.text:+ final_contents.append(acc_text)+ for tc in acc_tool_calls.values():+ final_contents.append(+ ToolCallBlock(id=tc["id"], name=tc["name"], input=tc["input"]),+ )++ _final_kwargs: dict[str, Any] = {+ "content": final_contents,+ "usage": usage,+ "is_last": True,+ }+ if response_id:+ _final_kwargs["id"] = response_id+ yield ChatResponse(**_final_kwargs)++ def _parse_completion_response(+ self,+ start_datetime: datetime,+ response: ChatCompletion,+ ) -> ChatResponse:+ """Parse the OpenAI Chat non-streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`ChatCompletion`):+ The OpenAI chat completion object.++ Returns:+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True``.+ """+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []++ if response.choices:+ choice = response.choices[0]+ reasoning = getattr(choice.message, "reasoning_content", None)+ if not isinstance(reasoning, str):+ reasoning = getattr(choice.message, "reasoning", None)+ if isinstance(reasoning, str) and reasoning:+ content_blocks.append(ThinkingBlock(thinking=reasoning))++ if choice.message.content:+ content_blocks.append(TextBlock(text=choice.message.content))++ for tool_call in choice.message.tool_calls or []:+ content_blocks.append(+ ToolCallBlock(+ id=tool_call.id,+ name=tool_call.function.name,+ input=tool_call.function.arguments,+ ),+ )++ usage = None+ if response.usage:+ usage = ChatUsage(+ input_tokens=response.usage.prompt_tokens,+ output_tokens=response.usage.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=response.usage,+ )++ resp_kwargs: dict[str, Any] = {+ "content": content_blocks,+ "is_last": True,+ "usage": usage,+ }+ response_id = getattr(response, "id", None)+ if response_id:+ resp_kwargs["id"] = response_id++ return ChatResponse(**resp_kwargs)++ def _format_tool_choice(+ self,+ tool_choice: ToolChoice | None,+ tools: list[dict] | None,+ ) -> str | dict | None:+ """Format tool_choice parameter for the OpenAI Chat Completions API.++ Args:+ tool_choice (`ToolChoice | None`):+ The unified tool choice parameter which can be ``"auto"``,+ ``"none"``, ``"required"``, or a specific function name.+ tools (`list[dict] | None`):+ The list of available tools, used for validation when+ ``tool_choice`` is a specific function name.++ Returns:+ `str | dict | None`:+ The formatted tool choice string or configuration dict for+ the OpenAI API, or ``None`` if ``tool_choice`` is ``None``.+ """+ self._validate_tool_choice(tool_choice, tools)++ if tool_choice is None:+ return None++ if tool_choice in ["auto", "none", "required"]:+ return tool_choice++ return {"type": "function", "function": {"name": tool_choice}}diff --git a/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml b/src/agentscope/model/_openai_chat/_models/gpt-4.1.yamlnew file mode 100644index 000000000..40ebbe051--- /dev/null+++ b/src/agentscope/model/_openai_chat/_models/gpt-4.1.yaml@@ -0,0 +1,22 @@+name: gpt-4.1+label: GPT-4.1+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain++context_size: 1047576+output_size: 32768++parameter_overrides:+ max_tokens:+ maximum: 32768+ thinking_enable:+ hidden: truediff --git a/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml b/src/agentscope/model/_openai_chat/_models/gpt-5.4.yamlnew file mode 100644index 000000000..ef1908708--- /dev/null+++ b/src/agentscope/model/_openai_chat/_models/gpt-5.4.yaml@@ -0,0 +1,22 @@+name: gpt-5.4+label: GPT-5.4+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain++context_size: 1050000+output_size: 128000++parameter_overrides:+ max_tokens:+ maximum: 128000+ thinking_enable:+ hidden: truediff --git a/src/agentscope/model/_openai_chat/_models/o3.yaml b/src/agentscope/model/_openai_chat/_models/o3.yamlnew file mode 100644index 000000000..7aedacce8--- /dev/null+++ b/src/agentscope/model/_openai_chat/_models/o3.yaml@@ -0,0 +1,21 @@+name: o3+label: o3+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 200000+output_size: 100000++parameter_overrides:+ max_tokens:+ maximum: 100000diff --git a/src/agentscope/model/_openai_chat/_models/o4-mini.yaml b/src/agentscope/model/_openai_chat/_models/o4-mini.yamlnew file mode 100644index 000000000..931013282--- /dev/null+++ b/src/agentscope/model/_openai_chat/_models/o4-mini.yaml@@ -0,0 +1,21 @@+name: o4-mini+label: o4-mini+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 200000+output_size: 100000++parameter_overrides:+ max_tokens:+ maximum: 100000diff --git a/src/agentscope/model/_openai_model.py b/src/agentscope/model/_openai_model.pydeleted file mode 100644index bcf0167da..000000000--- a/src/agentscope/model/_openai_model.py+++ /dev/null@@ -1,540 +0,0 @@-# -*- coding: utf-8 -*--"""OpenAI Chat model class."""-import warnings-from datetime import datetime-from typing import (- Any,- TYPE_CHECKING,- List,- AsyncGenerator,- Literal,-)-from collections import OrderedDict--from openai.types import ReasoningEffort-from pydantic import BaseModel--from . import ChatResponse-from ._model_base import ChatModelBase-from ._model_usage import ChatUsage-from ..formatter import FormatterBase, OpenAIChatFormatter-from ..message import (- TextBlock,- ThinkingBlock,- Base64Source,- DataBlock,- ToolCallBlock,-)-from ..tool import ToolChoice-from ..tracing import trace_llm-from ..types import JSONSerializableObject--if TYPE_CHECKING:- from openai.types.chat import ChatCompletion- from openai import AsyncStream-else:- ChatCompletion = "openai.types.chat.ChatCompletion"- AsyncStream = "openai.types.chat.AsyncStream"---def _format_audio_data_for_qwen_omni(messages: list[dict]) -> None:- """Qwen-omni uses OpenAI-compatible API but requires different audio- data format than OpenAI with "data:;base64," prefix.- Refer to `Qwen-omni documentation- <https://bailian.console.aliyun.com/?tab=doc#/doc/?type=model&url=2867839>`_- for more details.-- Args:- messages (`list[dict]`):- The list of message dictionaries from OpenAI formatter.- """- for msg in messages:- if isinstance(msg.get("content"), list):- for block in msg["content"]:- if (- isinstance(block, dict)- and "input_audio" in block- and isinstance(block["input_audio"].get("data"), str)- ):- if not block["input_audio"]["data"].startswith("http"):- block["input_audio"]["data"] = (- "data:;base64," + block["input_audio"]["data"]- )---class OpenAIChatModel(ChatModelBase):- """The OpenAI chat model class."""-- class ThinkingConfig(BaseModel):- """Configuration for reasoning effort levels."""-- enable_thinking: bool- reasoning_effect: ReasoningEffort | None = None-- def __init__(- self,- model_name: str,- context_length: int,- api_key: str | None = None,- stream: bool = True,- max_retries: int = 0,- fallback_model_name: str | None = None,- formatter: FormatterBase | None = None,- thinking_config: ThinkingConfig | None = None,- organization: str = None,- client_type: Literal["openai", "azure"] = "openai",- client_kwargs: dict[str, JSONSerializableObject] | None = None,- generate_kwargs: dict[str, JSONSerializableObject] | None = None,- ) -> None:- """Initialize the openai client.-- Args:- model_name (`str`, default `None`):- The name of the model to use in OpenAI API.- context_length (`int`):- The context length of the model, which will be used in- context compression.- api_key (`str`, default `None`):- The API key for OpenAI API. If not specified, it will- be read from the environment variable `OPENAI_API_KEY`.- stream (`bool`, default `True`):- Whether to use streaming output or not.- max_retries (`int`, optional):- Maximum number of retries on failure. Defaults to 0.- fallback_model_name (`str | None`, optional):- Fallback model name to use after all retries fail.- formatter (`FormatterBase | None`, optional):- Formatter for message preprocessing.- thinking_config (`ThinkingConfig | None`, optional):- Configuration for reasoning effort levels.- organization (`str`, default `None`):- The organization ID for OpenAI API.- client_type (`Literal["openai", "azure"]`, default `openai`):- Selects which OpenAI-compatible client to initialize.- client_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments to initialize the OpenAI client.- generate_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- The extra keyword arguments used in OpenAI API generation,- e.g. `temperature`, `seed`.- """- self.thinking_config = (- thinking_config- or OpenAIChatModel.ThinkingConfig(enable_thinking=False)- )-- super().__init__(- model_name=model_name,- stream=stream,- max_retries=max_retries,- context_length=context_length,- fallback_model_name=fallback_model_name,- formatter=formatter or OpenAIChatFormatter(),- )-- import openai-- if client_type not in ("openai", "azure"):- raise ValueError(- "Invalid client_type. Supported values: 'openai', 'azure'.",- )-- if client_type == "azure":- self.client = openai.AsyncAzureOpenAI(- api_key=api_key,- organization=organization,- **(client_kwargs or {}),- )- else:- self.client = openai.AsyncClient(- api_key=api_key,- organization=organization,- **(client_kwargs or {}),- )-- self.generate_kwargs = generate_kwargs or {}-- @trace_llm- async def _call_api(- self,- model_name: str,- messages: list[dict],- tools: list[dict] | None = None,- tool_choice: Literal["auto", "none", "required"] | str | None = None,- **kwargs: Any,- ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:- """Get the response from OpenAI chat completions API by the given- arguments.-- Args:- model_name (`str`):- The model name to use for this call.- messages (`list[dict]`):- A list of dictionaries, where `role` and `content` fields are- required, and `name` field is optional.- tools (`list[dict]`, default `None`):- The tools JSON schemas that the model can use.- tool_choice (`Literal["auto", "none", "required"] | str \- | None`, default `None`):- Controls which (if any) tool is called by the model.- **kwargs (`Any`):- The keyword arguments for OpenAI chat completions API.-- Returns:- `ChatResponse | AsyncGenerator[ChatResponse, None]`:- The response from the OpenAI chat completions API.- """-- # checking messages- if not isinstance(messages, list):- raise ValueError(- "OpenAI `messages` field expected type `list`, "- f"got `{type(messages)}` instead.",- )- if not all("role" in msg and "content" in msg for msg in messages):- raise ValueError(- "Each message in the 'messages' list must contain a 'role' "- "and 'content' key for OpenAI API.",- )-- # Qwen-omni requires different base64 audio format from openai- if "omni" in model_name.lower():- _format_audio_data_for_qwen_omni(messages)-- kwargs = {- "model": model_name,- "messages": messages,- "stream": self.stream,- **self.generate_kwargs,- **kwargs,- }- if (- self.thinking_config.enable_thinking- and self.thinking_config.reasoning_effect- ):- kwargs["reasoning_effort"] = self.thinking_config.reasoning_effect-- if tools:- kwargs["tools"] = self._format_tools_json_schemas(tools)-- if tool_choice:- # Handle deprecated "any" option with warning- if tool_choice == "any":- warnings.warn(- '"any" is deprecated and will be removed in a future '- "version.",- DeprecationWarning,- )- tool_choice = "required"- kwargs["tool_choice"] = self._format_tool_choice(- tool_choice,- tools,- )-- if self.stream:- kwargs["stream_options"] = {"include_usage": True}-- start_datetime = datetime.now()-- response = await self.client.chat.completions.create(**kwargs)-- if self.stream:- return self._parse_openai_stream_response(- start_datetime,- response,- )-- # Non-streaming response- parsed_response = self._parse_openai_completion_response(- start_datetime,- response,- )-- return parsed_response-- async def _parse_openai_stream_response(- self,- start_datetime: datetime,- response: AsyncStream,- ) -> AsyncGenerator[ChatResponse, None]:- """Given an OpenAI streaming completion response, extract the content- blocks and usages from it and yield ChatResponse objects.-- Args:- start_datetime (`datetime`):- The start datetime of the response generation.- response (`AsyncStream`):- OpenAI AsyncStream object to parse.-- Returns:- `AsyncGenerator[ChatResponse, None]`:- An async generator that yields ChatResponse objects containing- the content blocks and usage information for each chunk in- the streaming response.- """- usage = None-- # Accumulators- acc_text = ""- acc_thinking = ""- acc_audio = ""- acc_tool_calls = OrderedDict()-- async with response as stream:- async for chunk in stream:- if chunk.usage:- usage = ChatUsage(- input_tokens=chunk.usage.prompt_tokens,- output_tokens=chunk.usage.completion_tokens,- time=(datetime.now() - start_datetime).total_seconds(),- metadata=chunk.usage,- )-- if not chunk.choices:- continue-- choice = chunk.choices[0]-- # Extract delta content- delta_thinking = getattr(- choice.delta,- "reasoning_content",- None,- )- if not isinstance(delta_thinking, str):- delta_thinking = getattr(choice.delta, "reasoning", None)- if not isinstance(delta_thinking, str):- delta_thinking = ""-- delta_text = getattr(choice.delta, "content", None) or ""- delta_audio = ""-- if isinstance(getattr(choice.delta, "audio", None), dict):- if "data" in choice.delta.audio:- delta_audio = choice.delta.audio["data"]- if "transcript" in choice.delta.audio:- delta_text += choice.delta.audio["transcript"]-- # Accumulate- acc_thinking += delta_thinking- acc_text += delta_text- acc_audio += delta_audio-- # Handle tool calls- for tool_call in (- getattr(choice.delta, "tool_calls", None) or []- ):- if tool_call.index in acc_tool_calls:- if tool_call.function.arguments is not None:- acc_tool_calls[tool_call.index][- "input"- ] += tool_call.function.arguments- else:- acc_tool_calls[tool_call.index] = {- "id": tool_call.id,- "name": tool_call.function.name,- "input": tool_call.function.arguments or "",- }-- # Build delta content blocks- delta_contents: List[- TextBlock | ToolCallBlock | ThinkingBlock | DataBlock- ] = []-- if delta_thinking:- delta_contents.append(- ThinkingBlock(thinking=delta_thinking),- )-- if delta_audio:- media_type = self.generate_kwargs.get("audio", {}).get(- "format",- "wav",- )- delta_contents.append(- DataBlock(- source=Base64Source(- data=delta_audio,- media_type=f"audio/{media_type}",- ),- ),- )-- if delta_text:- delta_contents.append(- TextBlock(text=delta_text),- )-- # Yield delta response- if delta_contents:- yield ChatResponse(- content=delta_contents,- usage=usage,- is_last=False,- )-- # Build final accumulated content blocks- final_contents: List[- TextBlock | ToolCallBlock | ThinkingBlock | DataBlock- ] = []-- if acc_thinking:- final_contents.append(ThinkingBlock(thinking=acc_thinking))-- if acc_audio:- media_type = self.generate_kwargs.get("audio", {}).get(- "format",- "wav",- )- final_contents.append(- DataBlock(- source=Base64Source(- data=acc_audio,- media_type=f"audio/{media_type}",- ),- ),- )-- if acc_text:- final_contents.append(TextBlock(text=acc_text))-- for tool_call in acc_tool_calls.values():- final_contents.append(- ToolCallBlock(- id=tool_call["id"],- name=tool_call["name"],- input=tool_call["input"],- ),- )-- # Yield final accumulated response- yield ChatResponse(- content=final_contents,- usage=usage,- is_last=True,- )-- def _parse_openai_completion_response(- self,- start_datetime: datetime,- response: ChatCompletion,- ) -> ChatResponse:- """Given an OpenAI chat completion response object, extract the content- blocks and usages from it.-- Args:- start_datetime (`datetime`):- The start datetime of the response generation.- response (`ChatCompletion`):- OpenAI ChatCompletion object to parse.-- Returns:- ChatResponse (`ChatResponse`):- A ChatResponse object containing the content blocks and usage.- """- content_blocks: List[- TextBlock | ToolCallBlock | ThinkingBlock | DataBlock- ] = []-- if response.choices:- choice = response.choices[0]- reasoning = getattr(choice.message, "reasoning_content", None)- if not isinstance(reasoning, str):- reasoning = getattr(choice.message, "reasoning", None)- if not isinstance(reasoning, str):- reasoning = None-- if reasoning is not None:- content_blocks.append(- ThinkingBlock(thinking=reasoning),- )-- if choice.message.content:- content_blocks.append(- TextBlock(text=response.choices[0].message.content),- )- if choice.message.audio:- media_type = self.generate_kwargs.get("audio", {}).get(- "format",- "mp3",- )- content_blocks.append(- DataBlock(- source=Base64Source(- data=choice.message.audio.data,- media_type=f"audio/{media_type}",- ),- ),- )-- if choice.message.audio.transcript:- content_blocks.append(- TextBlock(text=choice.message.audio.transcript),- )-- for tool_call in choice.message.tool_calls or []:- content_blocks.append(- ToolCallBlock(- id=tool_call.id,- name=tool_call.function.name,- input=tool_call.function.arguments,- ),- )-- usage = None- if response.usage:- usage = ChatUsage(- input_tokens=response.usage.prompt_tokens,- output_tokens=response.usage.completion_tokens,- time=(datetime.now() - start_datetime).total_seconds(),- metadata=response.usage,- )-- resp_kwargs: dict[str, Any] = {- "content": content_blocks,- "is_last": True,- "usage": usage,- }- response_id = getattr(response, "id", None)- if response_id:- resp_kwargs["id"] = response_id-- return ChatResponse(**resp_kwargs)-- def _format_tools_json_schemas(- self,- schemas: list[dict[str, Any]],- ) -> list[dict[str, Any]]:- """Format the tools JSON schemas to the OpenAI format."""- return schemas-- def _format_tool_choice(- self,- tool_choice: ToolChoice | None,- tools: list[dict] | None,- ) -> str | dict | None:- """Format tool_choice parameter for API compatibility.-- Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be a mode ("auto",- "none", "required") or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation if- tool_choice is a specific function name.-- Returns:- `dict | None`:- The formatted tool choice configuration dict, or None if- tool_choice is None.- """- super()._validate_tool_choice(tool_choice, tools)-- if tool_choice is None:- return None-- if tool_choice in ["auto", "none", "required"]:- return tool_choice-- return {"type": "function", "function": {"name": tool_choice}}diff --git a/src/agentscope/model/_openai_response/__init__.py b/src/agentscope/model/_openai_response/__init__.pynew file mode 100644index 000000000..d6cbb08b5--- /dev/null+++ b/src/agentscope/model/_openai_response/__init__.py@@ -0,0 +1,8 @@+# -*- coding: utf-8 -*-+"""The OpenAI Responses API modules."""++from ._model import OpenAIResponseModel++__all__ = [+ "OpenAIResponseModel",+]diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.pynew file mode 100644index 000000000..d7854a1d1--- /dev/null+++ b/src/agentscope/model/_openai_response/_model.py@@ -0,0 +1,435 @@+# -*- coding: utf-8 -*-+"""The OpenAI Responses API chat model implementation."""+from datetime import datetime+from typing import Literal, Any, AsyncGenerator, List, TYPE_CHECKING++from pydantic import BaseModel, Field++from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import OpenAICredential+from ...formatter import FormatterBase, OpenAIResponseFormatter+from ...message import ThinkingBlock, ToolCallBlock, TextBlock+from ...tool import ToolChoice+from ...tracing import trace_llm++if TYPE_CHECKING:+ from openai.types.responses import Response+ from openai.types.responses import ResponseStreamEvent+ from openai import AsyncStream+else:+ Response = Any+ ResponseStreamEvent = Any+ AsyncStream = Any++_TOOL_CHOICE_LITERAL_MODES = ["auto", "none", "required"]+++class OpenAIResponseModel(ChatModelBase):+ """The OpenAI Responses API chat model.++ Compared with the Chat Completions API, the Responses API provides+ first-class streaming events for reasoning / thinking, text output+ and function-call arguments, which makes it a natural fit for models+ that expose chain-of-thought reasoning (e.g. ``o3``, ``o4-mini``).+ """++ class Parameters(BaseModel):+ """The parameters for the OpenAI Response API model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of output tokens.",+ gt=0,+ )++ reasoning_effort: Literal["low", "medium", "high"] | None = Field(+ default=None,+ title="Reasoning Effort",+ description=(+ "The reasoning effort level for reasoning models "+ "(e.g. o3, o4-mini)."+ ),+ )++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ le=2,+ )++ type: Literal["openai_response"] = "openai_response"+ """The type of the chat model."""++ def __init__(+ self,+ credential: OpenAICredential,+ model: str,+ parameters: "OpenAIResponseModel.Parameters | None" = None,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 200000,+ formatter: FormatterBase | None = None,+ ) -> None:+ """Initialize the OpenAI Responses API chat model.++ Args:+ credential (`OpenAICredential`):+ The OpenAI credential used to authenticate API calls.+ model (`str`):+ The OpenAI model name, e.g. ``o3`` or ``o4-mini``.+ parameters (`OpenAIResponseModel.Parameters | None`, defaults \+ to `None`):+ The OpenAI Responses API parameters. When ``None``, the+ default parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the OpenAI Responses API.+ context_size (`int`, defaults to `200000`):+ The model context size used for context compression.+ formatter (`FormatterBase | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to the format+ required by the OpenAI Responses API. When ``None``, an+ ``OpenAIResponseFormatter`` instance will be used.+ """+ super().__init__(+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,+ )+ self.credential = credential+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or OpenAIResponseFormatter()++ @trace_llm+ async def _call_api(+ self,+ model_name: str,+ messages: list[Any],+ tools: list[dict] | None = None,+ tool_choice: ToolChoice | None = None,+ **generate_kwargs: Any,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Call the OpenAI Responses API.++ Args:+ model_name (`str`):+ The model name to use for this call.+ messages (`list`):+ A list of input items for the Responses API.+ tools (`list[dict]`, default `None`):+ The tools JSON schemas.+ tool_choice (`ToolChoice | None`, optional):+ Controls which (if any) tool is called by the model.+ **generate_kwargs (`Any`):+ Extra keyword arguments forwarded to the API.++ Returns:+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """+ import openai++ client = openai.AsyncClient(+ api_key=self.credential.api_key.get_secret_value(),+ organization=self.credential.organization,+ base_url=self.credential.base_url,+ )++ formatted_messages = await self.formatter.format(messages)++ api_kwargs: dict[str, Any] = {+ "model": model_name,+ "input": formatted_messages,+ "stream": self.stream,+ }++ if self.parameters.max_tokens is not None:+ api_kwargs["max_output_tokens"] = self.parameters.max_tokens++ if self.parameters.temperature is not None:+ api_kwargs["temperature"] = self.parameters.temperature++ if self.parameters.reasoning_effort is not None:+ api_kwargs["reasoning"] = {+ "effort": self.parameters.reasoning_effort,+ }++ api_kwargs.update(generate_kwargs)++ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)+ if fmt_tools is not None:+ api_kwargs["tools"] = fmt_tools+ if fmt_tool_choice is not None:+ api_kwargs["tool_choice"] = fmt_tool_choice++ start_datetime = datetime.now()+ response = await client.responses.create(**api_kwargs)++ if self.stream:+ return self._parse_stream_response(start_datetime, response)++ return self._parse_completion_response(start_datetime, response)++ async def _parse_stream_response(+ self,+ start_datetime: datetime,+ response: "AsyncStream[ResponseStreamEvent]",+ ) -> AsyncGenerator[ChatResponse, None]:+ """Parse the OpenAI Responses API streaming response.++ Each event yields only the delta content produced by that event so+ that callers see a true incremental stream, consistent with other+ model implementations. The final ``response.completed`` event emits+ an ``is_last=True`` response with the full accumulated state.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`AsyncStream[ResponseStreamEvent]`):+ The OpenAI Responses API async stream object.++ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True``.+ """+ usage: ChatUsage | None = None+ response_id: str | None = None+ # All delta should have the same block identifier+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")+ tool_calls: dict[str, dict[str, Any]] = {}++ async for event in response:+ event_type = event.type++ if response_id is None:+ resp_obj = getattr(event, "response", None)+ if resp_obj is not None:+ response_id = getattr(resp_obj, "id", None)++ delta_contents: List[+ TextBlock | ToolCallBlock | ThinkingBlock+ ] = []++ if event_type == "response.reasoning_summary_text.delta":+ # Reasoning summary text is NOT emitted by all models.+ # As of 2026-05, o1 and o4-mini do not stream reasoning+ # summary deltas. This handler exists for forward+ # compatibility with models that do expose it.+ delta = event.delta+ acc_thinking.thinking += delta+ delta_contents.append(+ ThinkingBlock(id=acc_thinking.id, thinking=delta),+ )++ elif event_type == "response.output_text.delta":+ delta = event.delta+ acc_text.text += delta+ delta_contents.append(TextBlock(id=acc_text.id, text=delta))++ elif event_type == "response.output_item.added":+ item = event.item+ if getattr(item, "type", None) == "function_call":+ # item.id → fc_xxx (item identifier, needed for+ # function_call.id in multi-turn history)+ # item.call_id → call_xxx (needed for+ # function_call_output.call_id)+ tool_calls[item.id] = {+ "id": item.id,+ "call_id": getattr(item, "call_id", None),+ "name": getattr(item, "name", ""),+ "input": "",+ }++ elif event_type == "response.function_call_arguments.delta":+ item_id = event.item_id+ if item_id in tool_calls:+ tool_calls[item_id]["input"] += event.delta++ elif event_type == "response.completed":+ resp = event.response+ if response_id is None:+ response_id = getattr(resp, "id", None)+ if resp.usage:+ usage = ChatUsage(+ input_tokens=resp.usage.input_tokens,+ output_tokens=resp.usage.output_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=resp.usage,+ )+ # Attach reasoning item IDs from the completed response so the+ # formatter can echo them back in multi-turn history.+ # The Responses API requires every function_call item to be+ # accompanied by its preceding reasoning item (see the+ # function-calling guide). The reasoning item may have an+ # empty summary when the model does not expose it (e.g.+ # o1/o4-mini as of 2026-05).+ for output_item in getattr(resp, "output", []):+ if getattr(output_item, "type", None) == "reasoning":+ reasoning_item_id = getattr(output_item, "id", None)+ if reasoning_item_id:+ acc_thinking = ThinkingBlock(+ id=acc_thinking.id,+ thinking=acc_thinking.thinking,+ reasoning_item_id=reasoning_item_id,+ )+ # Emit the full accumulated state as the final response+ final_contents: List[+ TextBlock | ToolCallBlock | ThinkingBlock+ ] = []+ if acc_thinking.thinking or getattr(+ acc_thinking,+ "reasoning_item_id",+ None,+ ):+ final_contents.append(acc_thinking)+ if acc_text.text:+ final_contents.append(acc_text)+ for tc in tool_calls.values():+ final_contents.append(+ ToolCallBlock(+ id=tc["id"],+ call_id=tc.get("call_id"),+ name=tc["name"],+ input=tc["input"] or "{}",+ ),+ )+ final_kwargs: dict[str, Any] = {+ "content": final_contents,+ "is_last": True,+ "usage": usage,+ }+ if response_id:+ final_kwargs["id"] = response_id+ yield ChatResponse(**final_kwargs)+ return++ # Yield incremental delta for non-terminal events+ if delta_contents:+ chat_resp_kwargs: dict[str, Any] = {+ "content": delta_contents,+ "is_last": False,+ "usage": usage,+ }+ if response_id:+ chat_resp_kwargs["id"] = response_id+ yield ChatResponse(**chat_resp_kwargs)++ def _parse_completion_response(+ self,+ start_datetime: datetime,+ response: "Response",+ ) -> ChatResponse:+ """Parse the OpenAI Responses API non-streaming response.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`Response`):+ The OpenAI Responses API response object.++ Returns:+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True``.+ """+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []++ for item in response.output:+ item_type = getattr(item, "type", None)++ if item_type == "reasoning":+ reasoning_item_id = getattr(item, "id", None)+ combined_summary = " ".join(+ getattr(s, "text", "")+ for s in getattr(item, "summary", [])+ if getattr(s, "text", "")+ )+ if combined_summary:+ content_blocks.append(+ ThinkingBlock(+ type="thinking",+ thinking=combined_summary,+ reasoning_item_id=reasoning_item_id,+ ),+ )++ elif item_type == "message":+ for part in getattr(item, "content", []):+ if getattr(part, "type", None) == "output_text":+ content_blocks.append(+ TextBlock(type="text", text=part.text),+ )++ elif item_type == "function_call":+ content_blocks.append(+ ToolCallBlock(+ id=getattr(item, "id", ""),+ call_id=getattr(item, "call_id", None),+ name=item.name,+ input=getattr(item, "arguments", "") or "{}",+ ),+ )++ usage = None+ if response.usage:+ usage = ChatUsage(+ input_tokens=response.usage.input_tokens,+ output_tokens=response.usage.output_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=response.usage,+ )++ resp_kwargs: dict[str, Any] = {+ "content": content_blocks,+ "is_last": True,+ "usage": usage,+ }+ response_id = getattr(response, "id", None)+ if response_id:+ resp_kwargs["id"] = response_id++ return ChatResponse(**resp_kwargs)++ def _format_tools(+ self,+ tools: list[dict] | None,+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, str | dict | None]:+ """Format tools and tool_choice for the Responses API.++ Args:+ tools (`list[dict] | None`):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`):+ The tool choice configuration.++ Returns:+ `tuple[list[dict] | None, str | dict | None]`:+ A tuple of ``(formatted_tools, formatted_tool_choice)``+ ready for the Responses API.+ """+ self._validate_tool_choice(tool_choice, tools)++ fmt_tools = None+ if tools:+ fmt_tools = [+ {"type": "function", **tool["function"]} for tool in tools+ ]++ if not tool_choice:+ return fmt_tools, None++ if tool_choice not in _TOOL_CHOICE_LITERAL_MODES:+ return fmt_tools, {"type": "function", "name": tool_choice}++ return fmt_tools, tool_choicediff --git a/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml b/src/agentscope/model/_openai_response/_models/gpt-5.4.yamlnew file mode 100644index 000000000..6d99663b0--- /dev/null+++ b/src/agentscope/model/_openai_response/_models/gpt-5.4.yaml@@ -0,0 +1,22 @@+name: gpt-5.4+label: GPT-5.4 (Responses API)+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain++context_size: 1050000+output_size: 128000++parameter_overrides:+ max_tokens:+ maximum: 128000+ reasoning_effort:+ hidden: truediff --git a/src/agentscope/model/_openai_response/_models/o3.yaml b/src/agentscope/model/_openai_response/_models/o3.yamlnew file mode 100644index 000000000..a891bd1be--- /dev/null+++ b/src/agentscope/model/_openai_response/_models/o3.yaml@@ -0,0 +1,24 @@+name: o3+label: o3 (Responses API)+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 200000+output_size: 100000++parameter_overrides:+ max_tokens:+ maximum: 100000+ temperature:+ hidden: truediff --git a/src/agentscope/model/_openai_response/_models/o4-mini.yaml b/src/agentscope/model/_openai_response/_models/o4-mini.yamlnew file mode 100644index 000000000..587223a31--- /dev/null+++ b/src/agentscope/model/_openai_response/_models/o4-mini.yaml@@ -0,0 +1,24 @@+name: o4-mini+label: o4-mini (Responses API)+status: active++input_types:+ - text/plain+ - application/x-thinking+ - image/jpeg+ - image/png+ - image/gif+ - image/webp++output_types:+ - text/plain+ - application/x-thinking++context_size: 200000+output_size: 100000++parameter_overrides:+ max_tokens:+ maximum: 100000+ temperature:+ hidden: truediff --git a/src/agentscope/model/_xai/__init__.py b/src/agentscope/model/_xai/__init__.pynew file mode 100644index 000000000..a41fe21b2--- /dev/null+++ b/src/agentscope/model/_xai/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""The xAI LLM API modules."""++from ._model import XAICredential, XAIChatModel++__all__ = [+ "XAICredential",+ "XAIChatModel",+]diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.pynew file mode 100644index 000000000..6fc20d234--- /dev/null+++ b/src/agentscope/model/_xai/_model.py@@ -0,0 +1,416 @@+# -*- coding: utf-8 -*-+"""The xAI chat model implementation using the official xai_sdk."""+from datetime import datetime+from typing import Any, AsyncGenerator, List, Literal, TYPE_CHECKING++from pydantic import BaseModel, Field++from .._base import ChatModelBase+from .._model_response import ChatResponse+from .._model_usage import ChatUsage+from ...credential import XAICredential+from ...formatter._xai_formatter import XAIChatFormatter+from ...message import (+ TextBlock,+ ThinkingBlock,+ ToolCallBlock,+)+from ...tool import ToolChoice+from ...tracing import trace_llm++if TYPE_CHECKING:+ from xai_sdk import AsyncClient+ from xai_sdk.chat import Response, Chunk+else:+ AsyncClient = Any+ Response = Any+ Chunk = Any+++class XAIChatModel(ChatModelBase):+ """The xAI chat model using the official ``xai_sdk`` gRPC client.++ This model provides native access to xAI-specific features such as+ server-side agentic tools (web search, X search, code execution) and+ reasoning effort control, which are not available through the+ OpenAI-compatible REST endpoint.+ """++ class Parameters(BaseModel):+ """The parameters for the xAI chat model."""++ max_tokens: int | None = Field(+ default=None,+ title="Max Tokens",+ description="The maximum number of tokens for the LLM output.",+ gt=0,+ )+ """The maximum number of tokens to generate."""++ reasoning_effort: Literal["low", "medium", "high"] | None = Field(+ default=None,+ title="Reasoning Effort",+ description=(+ "Controls the depth of reasoning for models that support "+ "extended thinking (e.g. ``grok-3-mini``). Set to "+ "``'low'``, ``'medium'``, or ``'high'`` to enable reasoning "+ "with the corresponding effort level. ``None`` disables "+ "reasoning."+ ),+ )+ """Reasoning effort level for xAI reasoning models."""++ temperature: float | None = Field(+ default=None,+ title="Temperature",+ description="The temperature for the LLM output.",+ ge=0,+ le=2,+ )+ """The sampling temperature."""++ top_p: float | None = Field(+ default=None,+ title="Top P",+ description="The top-p nucleus sampling value.",+ gt=0,+ le=1,+ )+ """The top-p sampling parameter."""++ type: Literal["xai_chat"] = "xai_chat"+ """The type of the chat model."""++ def __init__(+ self,+ credential: XAICredential,+ model: str,+ parameters: "XAIChatModel.Parameters | None" = None,+ stream: bool = True,+ max_retries: int = 3,+ context_size: int = 131072,+ formatter: XAIChatFormatter | None = None,+ ) -> None:+ """Initialize the xAI chat model.++ Args:+ credential (`XAICredential`):+ The xAI credential used to authenticate API calls.+ model (`str`):+ The xAI model name, e.g. ``grok-3`` or ``grok-3-mini``.+ parameters (`XAIChatModel.Parameters | None`, defaults to \+ `None`):+ The xAI API parameters. When ``None``, the default+ parameters will be used.+ stream (`bool`, defaults to `True`):+ Whether to enable streaming output.+ max_retries (`int`, defaults to `3`):+ The maximum number of retries for the xAI API.+ context_size (`int`, defaults to `131072`):+ The model context size used for context compression.+ formatter (`XAIChatFormatter | None`, defaults to `None`):+ The formatter that converts ``Msg`` objects to xai_sdk+ proto messages. When ``None``, an ``XAIChatFormatter``+ instance will be used.+ """+ super().__init__(+ model=model,+ stream=stream,+ max_retries=max_retries,+ context_size=context_size,+ )+ self.credential = credential+ self.parameters = parameters or self.Parameters()+ self.formatter = formatter or XAIChatFormatter()++ @trace_llm+ async def _call_api(+ self,+ model_name: str,+ messages: list[Any],+ tools: list[dict] | None = None,+ tool_choice: ToolChoice | None = None,+ **generate_kwargs: Any,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Call the xAI API using the official ``xai_sdk`` gRPC client.++ Args:+ model_name (`str`):+ The model name to use for this call.+ messages (`list`):+ A list of ``Msg`` objects representing the conversation.+ tools (`list[dict]`, default `None`):+ The tools JSON schemas.+ tool_choice (`ToolChoice | None`, optional):+ Controls which (if any) tool is called by the model.+ **generate_kwargs (`Any`):+ Extra keyword arguments forwarded to the API.++ Returns:+ `ChatResponse | AsyncGenerator[ChatResponse, None]`:+ A ``ChatResponse`` when streaming is disabled, or an async+ generator of ``ChatResponse`` objects when streaming is+ enabled.+ """+ from xai_sdk import (+ AsyncClient as XAIAsyncClient,+ ) # pylint: disable=import-outside-toplevel++ client = XAIAsyncClient(+ api_key=self.credential.api_key.get_secret_value(),+ )++ xai_messages = await self.formatter.format(messages)++ xai_tools = self._convert_tools(tools) if tools else None+ xai_tool_choice = (+ self._convert_tool_choice(tool_choice, tools)+ if tool_choice+ else None+ )++ create_kwargs: dict[str, Any] = {"model": model_name}+ if self.parameters.max_tokens is not None:+ create_kwargs["max_tokens"] = self.parameters.max_tokens+ if self.parameters.temperature is not None:+ create_kwargs["temperature"] = self.parameters.temperature+ if self.parameters.top_p is not None:+ create_kwargs["top_p"] = self.parameters.top_p+ if self.parameters.reasoning_effort is not None:+ create_kwargs[+ "reasoning_effort"+ ] = self.parameters.reasoning_effort+ if xai_tools:+ create_kwargs["tools"] = xai_tools+ if xai_tool_choice is not None:+ create_kwargs["tool_choice"] = xai_tool_choice++ create_kwargs.update(generate_kwargs)++ chat = client.chat.create(**create_kwargs)+ for xai_msg in xai_messages:+ chat.append(xai_msg)++ start_datetime = datetime.now()++ if self.stream:+ return self._parse_stream_response(start_datetime, chat, client)++ try:+ response = await chat.sample()+ finally:+ await client.close()++ return self._parse_completion_response(start_datetime, response)++ def _convert_tools(self, tools: list[dict]) -> list:+ """Convert AgentScope tool schemas to ``xai_sdk`` ``Tool`` protos.++ Args:+ tools (`list[dict]`):+ A list of tool schemas in OpenAI function-calling format.++ Returns:+ `list`:+ A list of ``chat_pb2.Tool`` proto objects.+ """+ from xai_sdk.chat import tool++ xai_tools = []+ for t in tools:+ if t.get("type") == "function" and "function" in t:+ fn = t["function"]+ xai_tools.append(+ tool(+ name=fn["name"],+ description=fn.get("description", ""),+ parameters=fn.get("parameters", {}),+ ),+ )+ return xai_tools++ def _convert_tool_choice(+ self,+ tool_choice: ToolChoice | None,+ tools: list[dict] | None,+ ) -> Any:+ """Convert a ``ToolChoice`` value to an ``xai_sdk`` compatible object.++ Args:+ tool_choice (`ToolChoice | None`):+ The unified tool-choice parameter (``"auto"``, ``"none"``,+ ``"required"``, or a specific function name).+ tools (`list[dict] | None`):+ The list of available tools, used for validation.++ Returns:+ `Any`:+ The ``xai_sdk``-compatible tool-choice value, or ``None``.+ """+ from xai_sdk.chat import ( # pylint: disable=import-outside-toplevel+ required_tool,+ )++ self._validate_tool_choice(tool_choice, tools)++ if tool_choice is None:+ return None+ if tool_choice in ("auto", "none", "required"):+ return tool_choice+ return required_tool(tool_choice)++ async def _parse_stream_response(+ self,+ start_datetime: datetime,+ chat: Any,+ client: Any,+ ) -> AsyncGenerator[ChatResponse, None]:+ """Parse the xAI streaming response from ``xai_sdk``.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ chat (`Any`):+ The ``xai_sdk`` chat session object.+ client (`Any`):+ The ``xai_sdk.AsyncClient`` instance; closed when the+ generator is exhausted or abandoned.++ Yields:+ `ChatResponse`:+ Incremental ``ChatResponse`` objects with ``is_last=False``+ followed by a final one with ``is_last=True``.+ """+ acc_text = TextBlock(text="")+ acc_thinking = ThinkingBlock(thinking="")+ last_response = None+ response_id: str | None = None++ try:+ async for response, chunk in chat.stream():+ if response_id is None:+ response_id = getattr(response, "id", None) or None++ delta_text: str = chunk.content or ""+ delta_thinking: str = chunk.reasoning_content or ""++ delta_contents: List[TextBlock | ThinkingBlock] = []++ if delta_thinking:+ acc_thinking.thinking += delta_thinking+ delta_contents.append(+ ThinkingBlock(+ id=acc_thinking.id,+ thinking=delta_thinking,+ ),+ )+ if delta_text:+ acc_text.text += delta_text+ delta_contents.append(+ TextBlock(id=acc_text.id, text=delta_text),+ )++ if delta_contents:+ _kwargs: dict[str, Any] = {+ "content": delta_contents,+ "is_last": False,+ }+ if response_id:+ _kwargs["id"] = response_id+ yield ChatResponse(**_kwargs)++ last_response = response++ finally:+ await client.close()++ final_contents: List[TextBlock | ToolCallBlock | ThinkingBlock] = []+ if acc_thinking.thinking:+ final_contents.append(acc_thinking)+ if acc_text.text:+ final_contents.append(acc_text)++ if last_response is not None:+ for tc in last_response.tool_calls or []:+ final_contents.append(+ ToolCallBlock(+ id=tc.id,+ name=tc.function.name,+ input=tc.function.arguments,+ ),+ )++ usage = None+ if last_response is not None and last_response.usage is not None:+ u = last_response.usage+ usage = ChatUsage(+ input_tokens=u.prompt_tokens,+ output_tokens=u.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=u,+ )++ final_kwargs: dict[str, Any] = {+ "content": final_contents,+ "usage": usage,+ "is_last": True,+ }+ if response_id:+ final_kwargs["id"] = response_id+ yield ChatResponse(**final_kwargs)++ def _parse_completion_response(+ self,+ start_datetime: datetime,+ response: Any,+ ) -> ChatResponse:+ """Parse the xAI non-streaming response from ``xai_sdk``.++ Args:+ start_datetime (`datetime`):+ The start datetime of the response generation.+ response (`Any`):+ The ``xai_sdk`` ``Response`` object.++ Returns:+ `ChatResponse`:+ A single ``ChatResponse`` with ``is_last=True``.+ """+ content_blocks: List[TextBlock | ToolCallBlock | ThinkingBlock] = []++ if response.reasoning_content:+ content_blocks.append(+ ThinkingBlock(thinking=response.reasoning_content),+ )+ if response.content:+ content_blocks.append(TextBlock(text=response.content))++ for tc in response.tool_calls or []:+ content_blocks.append(+ ToolCallBlock(+ id=tc.id,+ name=tc.function.name,+ input=tc.function.arguments,+ ),+ )++ usage = None+ if response.usage is not None:+ u = response.usage+ usage = ChatUsage(+ input_tokens=u.prompt_tokens,+ output_tokens=u.completion_tokens,+ time=(datetime.now() - start_datetime).total_seconds(),+ metadata=u,+ )++ resp_kwargs: dict[str, Any] = {+ "content": content_blocks,+ "is_last": True,+ "usage": usage,+ }+ response_id = getattr(response, "id", None)+ if response_id:+ resp_kwargs["id"] = response_id++ return ChatResponse(**resp_kwargs)diff --git a/src/agentscope/model/_xai/_models/grok-3-mini.yaml b/src/agentscope/model/_xai/_models/grok-3-mini.yamlnew file mode 100644index 000000000..04f100adc--- /dev/null+++ b/src/agentscope/model/_xai/_models/grok-3-mini.yaml@@ -0,0 +1,17 @@+name: grok-3-mini+label: Grok 3 Mini+status: active++input_types:+ - text/plain++output_types:+ - text/plain+ - application/x-thinking++context_size: 131072+output_size: 16000++parameter_overrides:+ max_tokens:+ maximum: 16000diff --git a/src/agentscope/model/_xai/_models/grok-4.3.yaml b/src/agentscope/model/_xai/_models/grok-4.3.yamlnew file mode 100644index 000000000..4b712ef44--- /dev/null+++ b/src/agentscope/model/_xai/_models/grok-4.3.yaml@@ -0,0 +1,19 @@+name: grok-4.3+label: Grok 4.3+status: active++input_types:+ - text/plain+ - image/jpeg+ - image/png++output_types:+ - text/plain+ - application/x-thinking++context_size: 1000000+output_size: 30000++parameter_overrides:+ max_tokens:+ maximum: 30000diff --git a/tests/compress_context_test.py b/tests/compress_context_test.pyindex 2edb990c3..eed756a24 100644--- a/tests/compress_context_test.py+++ b/tests/compress_context_test.py@@ -469,7 +469,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):async def test_context_compression(self) -> None:"""Test the context compression logic."""- model = MockModel(context_length=100)+ model = MockModel(context_size=100)agent = Agent(name="Friday",system_prompt="".join(["0" for _ in range(20 * 4)]),diff --git a/tests/formatter_anthropic_test.py b/tests/formatter_anthropic_test.pynew file mode 100644index 000000000..88936831c--- /dev/null+++ b/tests/formatter_anthropic_test.py@@ -0,0 +1,532 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for AnthropicChatFormatter and+AnthropicMultiAgentFormatter, following the reference test style with exact+ground-truth comparisons.+"""+from unittest import IsolatedAsyncioTestCase++from agentscope.formatter import (+ AnthropicChatFormatter,+ AnthropicMultiAgentFormatter,+)+from agentscope.message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ Base64Source,+ ThinkingBlock,+)+from agentscope.message._block import ToolResultState+++class TestAnthropicFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for Anthropic Chat and MultiAgent formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared message fixtures and expected ground-truth dicts."""+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"++ # ---------------------------------------------------------------+ # Message fixtures+ # (No URL images: Anthropic URL handling downloads from the network)+ # ---------------------------------------------------------------+ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]++ self.msgs_conversation = [+ Msg(+ name="user",+ content="What is the capital of France?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]++ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ # ---------------------------------------------------------------+ # Ground truth: AnthropicChatFormatter+ # - No "name" field.+ # - Content is always a list of {"type": ..., ...} dicts.+ # - ToolResultBlock forces role to "user".+ # - ToolCallBlock "input" is a dict (parsed from JSON string).+ # ---------------------------------------------------------------+ self.gt_chat = [+ {+ "role": "system",+ "content": [+ {"type": "text", "text": "You're a helpful assistant."},+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": "What is the capital of France?",+ },+ ],+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of France is Paris.",+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": "What is the capital of Germany?",+ },+ ],+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of Germany is Berlin.",+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": "What is the capital of Japan?",+ },+ ],+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "call_1",+ "name": "get_capital",+ "input": {"country": "Japan"},+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_use_id": "call_1",+ "content": [+ {+ "type": "text",+ "text": "The capital of Japan is Tokyo.",+ },+ ],+ },+ ],+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of Japan is Tokyo.",+ },+ ],+ },+ ]++ # ---------------------------------------------------------------+ # Ground truth: AnthropicMultiAgentFormatter+ # - System: {"role": "system", "content": [{"type": "text", ...}]}+ # - Agent messages (is_first=True): wrapped in hist_prompt ++ # <history>...</history>.+ # - Agent messages (is_first=False): no wrapping at all.+ # ---------------------------------------------------------------+ _hist_prompt = (+ AnthropicMultiAgentFormatter().conversation_history_prompt+ )++ _conv_text = (+ "user: What is the capital of France?\n"+ "assistant: The capital of France is Paris.\n"+ "user: What is the capital of Germany?\n"+ "assistant: The capital of Germany is Berlin.\n"+ "user: What is the capital of Japan?"+ )++ # is_first=False: no wrapping (Anthropic only wraps on first group)+ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": "assistant: The capital of Japan is Tokyo.",+ },+ ],+ }+ # is_first=True: full wrapping with hist_prompt+ self._gt_trailing_asst_first = {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ _hist_prompt + "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }++ self._gt_tool_call = {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "call_1",+ "name": "get_capital",+ "input": {"country": "Japan"},+ },+ ],+ }+ self._gt_tool_result = {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_use_id": "call_1",+ "content": [+ {+ "type": "text",+ "text": "The capital of Japan is Tokyo.",+ },+ ],+ },+ ],+ }++ self.gt_multiagent = [+ {+ "role": "system",+ "content": [+ {"type": "text", "text": "You're a helpful assistant."},+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ _hist_prompt+ + "<history>\n"+ + _conv_text+ + "\n</history>"+ ),+ },+ ],+ },+ self._gt_tool_call,+ self._gt_tool_result,+ _gt_trailing_asst_nonfirst,+ ]++ # -------------------------------------------------------------------+ # AnthropicChatFormatter tests+ # -------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = AnthropicChatFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)++ async def test_chat_formatter_base64_image(self) -> None:+ """Base64-encoded image is formatted as Anthropic image source."""+ fmt = AnthropicChatFormatter()+ msgs = [+ Msg(+ name="user",+ content=[+ TextBlock(type="text", text="What's in this image?"),+ DataBlock(+ source=Base64Source(+ type="base64",+ data=self.image_b64,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertListEqual(+ [+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "What's in this image?"},+ {+ "type": "image",+ "source": {+ "type": "base64",+ "media_type": "image/png",+ "data": self.image_b64,+ },+ },+ ],+ },+ ],+ res,+ )++ async def test_chat_formatter_thinking_preserved(self) -> None:+ """ThinkingBlock is passed back as a thinking content block."""+ fmt = AnthropicChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ thinking_blocks = [+ b for b in res[0]["content"] if b.get("type") == "thinking"+ ]+ self.assertEqual(len(thinking_blocks), 1)+ self.assertEqual(thinking_blocks[0]["thinking"], "inner thoughts")+ self.assertEqual(thinking_blocks[0]["signature"], "")++ async def test_chat_formatter_tool_result_role_forced_to_user(+ self,+ ) -> None:+ """Anthropic forces tool_result messages to role='user'."""+ fmt = AnthropicChatFormatter()+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ tool_results = [+ m+ for m in res+ if any(+ b.get("type") == "tool_result"+ for b in (m.get("content") or [])+ )+ ]+ self.assertTrue(len(tool_results) > 0)+ for tr in tool_results:+ self.assertEqual(tr["role"], "user")++ async def test_chat_formatter_tool_result_with_image(self) -> None:+ """Tool result containing an image DataBlock inlines the image in the+ tool_result content without crashing on TextBlock system-reminders."""+ fmt = AnthropicChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_img",+ name="get_chart",+ input="{}",+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_img",+ name="get_chart",+ output=[+ TextBlock(type="text", text="Here is the chart."),+ DataBlock(+ source=Base64Source(+ data=self.image_b64,+ media_type="image/png",+ ),+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ # There should be 2 messages: the tool_call and the tool_result+ self.assertEqual(len(res), 2)+ # Find the tool_result message+ tool_result_msg = next(+ m+ for m in res+ if any(+ b.get("type") == "tool_result"+ for b in (m.get("content") or [])+ )+ )+ self.assertEqual(tool_result_msg["role"], "user")+ tr_content = next(+ b+ for b in tool_result_msg["content"]+ if b.get("type") == "tool_result"+ )["content"]+ # The content should have a text part and an image part+ types = [b.get("type") for b in tr_content]+ self.assertIn("text", types)+ self.assertIn("image", types)++ # -------------------------------------------------------------------+ # AnthropicMultiAgentFormatter tests+ # -------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = AnthropicMultiAgentFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only — is_first=True for trailing assistant+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools (no conversation) — same is_first=True+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)diff --git a/tests/formatter_dashscope_test.py b/tests/formatter_dashscope_test.pynew file mode 100644index 000000000..31235f139--- /dev/null+++ b/tests/formatter_dashscope_test.py@@ -0,0 +1,600 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for DashScopeChatFormatter and+DashScopeMultiAgentFormatter, following the reference test style with exact+ground-truth comparisons.+"""+from unittest import IsolatedAsyncioTestCase+from unittest.mock import patch++import shortuuid++from agentscope.formatter import (+ DashScopeChatFormatter,+ DashScopeMultiAgentFormatter,+)+from agentscope.message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ Base64Source,+ URLSource,+ ThinkingBlock,+)+from agentscope.message._block import ToolResultState+++# A fixed short-uuid used to make promote-to-multimodal tests deterministic.+_FIXED_ID = "TESTID1234567"+++class TestDashScopeFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for DashScope Chat and MultiAgent formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared message fixtures and expected ground-truth dicts."""+ # --- URL strings ---+ # Normalise through URLSource so that pydantic URL normalisation is+ # applied consistently to both input and expected values.+ _img_src = URLSource(+ url="https://example.com/image.png",+ media_type="image/png",+ )+ _aud_src = URLSource(+ url="https://example.com/audio.mp3",+ media_type="audio/mpeg",+ )+ self.image_url = str(_img_src.url)+ audio_url = str(_aud_src.url)++ # --- Base64 fixtures ---+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"++ # ---------------------------------------------------------------+ # Message fixtures+ # ---------------------------------------------------------------+ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]++ self.msgs_conversation = [+ Msg(+ name="user",+ content=[+ TextBlock(+ type="text",+ text="What is the capital of France?",+ ),+ DataBlock(+ source=URLSource(+ url=self.image_url,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content=[+ TextBlock(+ type="text",+ text="What is the capital of Germany?",+ ),+ DataBlock(+ source=URLSource(+ url=audio_url,+ media_type="audio/mpeg",+ ),+ ),+ ],+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]++ # Messages with ToolResultBlock must use role="assistant" because the+ # system-role validator rejects non-text blocks.+ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ # ---------------------------------------------------------------+ # Ground truth: DashScopeChatFormatter+ # - System/user/assistant content is always a list of dicts.+ # - Tool-result content is a plain string.+ # ---------------------------------------------------------------+ self.gt_chat = [+ {+ "role": "system",+ "content": [{"text": "You're a helpful assistant."}],+ },+ {+ "role": "user",+ "content": [+ {"text": "What is the capital of France?"},+ {"image": self.image_url},+ ],+ },+ {+ "role": "assistant",+ "content": [{"text": "The capital of France is Paris."}],+ },+ {+ "role": "user",+ "content": [+ {"text": "What is the capital of Germany?"},+ {"audio": audio_url},+ ],+ },+ {+ "role": "assistant",+ "content": [{"text": "The capital of Germany is Berlin."}],+ },+ {+ "role": "user",+ "content": [{"text": "What is the capital of Japan?"}],+ },+ {+ "role": "assistant",+ "content": [],+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ },+ {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ },+ {+ "role": "assistant",+ "content": [{"text": "The capital of Japan is Tokyo."}],+ },+ ]++ # ---------------------------------------------------------------+ # Ground truth: DashScopeMultiAgentFormatter+ # - System content is a plain string (via get_text_content()).+ # - Conversation history is collapsed into a single user message.+ # ---------------------------------------------------------------+ _hist_prompt = (+ DashScopeMultiAgentFormatter().conversation_history_prompt+ )++ # The trailing assistant message ("The capital of Japan is Tokyo.")+ # is always converted to a user <history> message by the multiagent+ # formatter. Whether it carries the full history_prompt prefix+ # depends on whether an "agent_message" group appeared before it:+ # * is_first=False (conversation preceded the tool sequence):+ # only <history>...</history>+ # * is_first=True (no prior agent_message, e.g. tools-only):+ # full history_prompt + <history>...</history>+ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "content": [+ {+ "text": (+ "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }+ self._gt_trailing_asst_first = {+ "role": "user",+ "content": [+ {+ "text": (+ _hist_prompt + "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }++ self._gt_tool_call = {+ "role": "assistant",+ "content": [],+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ }+ self._gt_tool_result = {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ }++ self.gt_multiagent = [+ {+ "role": "system",+ "content": "You're a helpful assistant.",+ },+ {+ "role": "user",+ "content": [+ {+ "text": (+ _hist_prompt + "<history>\n"+ "user: What is the capital of France?"+ ),+ },+ {"image": self.image_url},+ {+ "text": (+ "assistant: The capital of France is Paris.\n"+ "user: What is the capital of Germany?"+ ),+ },+ {"audio": audio_url},+ {+ "text": (+ "assistant: The capital of Germany is Berlin.\n"+ "user: What is the capital of Japan?\n"+ "</history>"+ ),+ },+ ],+ },+ self._gt_tool_call,+ self._gt_tool_result,+ # Trailing assistant message: is_first=False because conversation+ # preceded the tool sequence.+ _gt_trailing_asst_nonfirst,+ ]++ # -------------------------------------------------------------------+ # DashScopeChatFormatter tests+ # -------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = DashScopeChatFormatter()++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.maxDiff = None+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)++ async def test_chat_formatter_base64_image(self) -> None:+ """Base64-encoded image is inlined as a data URI."""+ fmt = DashScopeChatFormatter()+ msgs = [+ Msg(+ name="user",+ content=[+ TextBlock(type="text", text="What's in this image?"),+ DataBlock(+ source=Base64Source(+ type="base64",+ data=self.image_b64,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertListEqual(+ [+ {+ "role": "user",+ "content": [+ {"text": "What's in this image?"},+ {"image": self.image_data_uri},+ ],+ },+ ],+ res,+ )++ async def test_chat_formatter_url_image_in_tool_result(self) -> None:+ """URL images in tool results are promoted to a follow-up user message.++ The textual part of the tool result contains a system-reminder with a+ unique identifier; the identifier is mocked to be deterministic.+ """+ with patch.object(shortuuid, "uuid", return_value=_FIXED_ID):+ fmt = DashScopeChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_img",+ name="get_map",+ input='{"city": "Tokyo"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_img",+ name="get_map",+ output=[+ TextBlock(+ type="text",+ text="Here is the map.",+ ),+ DataBlock(+ source=URLSource(+ url=self.image_url,+ media_type="image/png",+ ),+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)++ expected_tool_content = (+ "Here is the map.\n"+ f"<system-reminder>A(n) image file is returned "+ f"and will be presented to you with the identifier "+ f"[{_FIXED_ID}].</system-reminder>"+ )+ self.assertEqual(len(res), 3)+ self.assertEqual(res[0]["role"], "assistant")+ self.assertEqual(res[1]["role"], "tool")+ self.assertEqual(res[1]["content"], expected_tool_content)+ # The promoted multimodal user message+ self.assertEqual(res[2]["role"], "user")+ image_blocks = [+ b for b in res[2]["content"] if b.get("image") == self.image_url+ ]+ self.assertEqual(len(image_blocks), 1)++ async def test_chat_formatter_thinking_dropped_without_flag(self) -> None:+ """ThinkingBlock is silently dropped when application/x-thinking is+ absent from input_types."""+ fmt = DashScopeChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ self.assertNotIn("reasoning_content", res[0])++ async def test_chat_formatter_thinking_becomes_reasoning_content(+ self,+ ) -> None:+ """ThinkingBlock becomes reasoning_content when application/x-thinking+ is in input_types."""+ fmt = DashScopeChatFormatter(+ input_types=["text/plain", "application/x-thinking"],+ )+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ self.assertEqual(res[0]["reasoning_content"], "inner thoughts")++ async def test_chat_formatter_multiple_thinking_blocks_joined(+ self,+ ) -> None:+ """Multiple ThinkingBlocks are joined with a newline into a single+ reasoning_content field."""+ fmt = DashScopeChatFormatter(+ input_types=["text/plain", "application/x-thinking"],+ )+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="part one"),+ ThinkingBlock(thinking="part two"),+ TextBlock(type="text", text="answer"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertIn("part one", res[0]["reasoning_content"])+ self.assertIn("part two", res[0]["reasoning_content"])++ # -------------------------------------------------------------------+ # DashScopeMultiAgentFormatter tests+ # -------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = DashScopeMultiAgentFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only — no prior agent_message group, so the trailing assistant+ # is formatted with is_first=True (includes the full history prompt).+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools (no conversation) — same is_first=True for the+ # trailing assistant message.+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)++ async def test_multiagent_formatter_thinking_in_tool_sequence(+ self,+ ) -> None:+ """ThinkingBlocks inside a tool sequence are forwarded as+ reasoning_content when application/x-thinking is in input_types."""+ fmt = DashScopeMultiAgentFormatter(+ input_types=["text/plain", "application/x-thinking"],+ )+ tc = ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ )+ tr = ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[TextBlock(type="text", text="Tokyo")],+ state=ToolResultState.SUCCESS,+ )+ msgs = [+ Msg(+ name="assistant",+ content=[ThinkingBlock(thinking="Need to check"), tc],+ role="assistant",+ ),+ Msg(name="tool", content=[tr], role="assistant"),+ ]+ res = await fmt.format(msgs)+ asst_msgs = [m for m in res if m.get("role") == "assistant"]+ self.assertTrue(len(asst_msgs) > 0)+ self.assertEqual(asst_msgs[0]["reasoning_content"], "Need to check")diff --git a/tests/formatter_deepseek_test.py b/tests/formatter_deepseek_test.pynew file mode 100644index 000000000..d4f697646--- /dev/null+++ b/tests/formatter_deepseek_test.py@@ -0,0 +1,324 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for DeepSeekChatFormatter and+DeepSeekMultiAgentFormatter, with exact ground-truth comparisons.+"""+from unittest import IsolatedAsyncioTestCase++from agentscope.formatter import (+ DeepSeekChatFormatter,+ DeepSeekMultiAgentFormatter,+)+from agentscope.message import (+ Msg,+ TextBlock,+ ToolCallBlock,+ ToolResultBlock,+ ThinkingBlock,+)+from agentscope.message._block import ToolResultState+++class TestDeepSeekFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for DeepSeek Chat and MultiAgent formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared fixtures and ground-truth dicts."""+ _hist_prompt = (+ DeepSeekMultiAgentFormatter().conversation_history_prompt+ )++ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]+ self.msgs_conversation = [+ Msg(+ name="user",+ content="What is the capital of France?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]+ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ # --- Chat formatter ground truth ---+ # DeepSeek content is a plain string (not a list of blocks).+ # All assistant messages include `reasoning_content` (empty string if+ # no ThinkingBlock).+ self.gt_chat = [+ {"role": "system", "content": "You're a helpful assistant."},+ {"role": "user", "content": "What is the capital of France?"},+ {+ "role": "assistant",+ "content": "The capital of France is Paris.",+ "reasoning_content": "",+ },+ {"role": "user", "content": "What is the capital of Germany?"},+ {+ "role": "assistant",+ "content": "The capital of Germany is Berlin.",+ "reasoning_content": "",+ },+ {"role": "user", "content": "What is the capital of Japan?"},+ {+ "role": "assistant",+ "content": None,+ "reasoning_content": "",+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ },+ {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ },+ {+ "role": "assistant",+ "content": "The capital of Japan is Tokyo.",+ "reasoning_content": "",+ },+ ]++ # --- MultiAgent formatter ground truth ---+ # System content is a plain string.+ # History is a plain string (not a list) with <history> tags.+ # The trailing assistant message (is_first=False) is wrapped in a+ # minimal <history> block without the full prompt prefix.+ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "content": (+ "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ }+ self._gt_trailing_asst_first = {+ "role": "user",+ "content": (+ _hist_prompt + "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ }+ self._gt_tool_call = {+ "role": "assistant",+ "content": None,+ "reasoning_content": "",+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ }+ self._gt_tool_result = {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ }++ self.gt_multiagent = [+ {"role": "system", "content": "You're a helpful assistant."},+ {+ "role": "user",+ "content": (+ _hist_prompt + "<history>\n"+ "user: What is the capital of France?\n"+ "assistant: The capital of France is Paris.\n"+ "user: What is the capital of Germany?\n"+ "assistant: The capital of Germany is Berlin.\n"+ "user: What is the capital of Japan?\n"+ "</history>"+ ),+ },+ self._gt_tool_call,+ self._gt_tool_result,+ _gt_trailing_asst_nonfirst,+ ]++ # ------------------------------------------------------------------+ # DeepSeekChatFormatter tests+ # ------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = DeepSeekChatFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ self.assertListEqual([], await fmt.format([]))++ async def test_chat_formatter_reasoning_content_always_present(+ self,+ ) -> None:+ """Every assistant message always has a reasoning_content field."""+ fmt = DeepSeekChatFormatter()+ msgs = [Msg(name="assistant", content="Answer", role="assistant")]+ res = await fmt.format(msgs)+ self.assertIn("reasoning_content", res[0])+ self.assertEqual(res[0]["reasoning_content"], "")++ async def test_chat_formatter_thinking_block(self) -> None:+ """ThinkingBlock is placed into reasoning_content."""+ fmt = DeepSeekChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="Let me think..."),+ TextBlock(type="text", text="Answer"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(res[0]["reasoning_content"], "Let me think...")+ self.assertEqual(res[0]["content"], "Answer")++ # ------------------------------------------------------------------+ # DeepSeekMultiAgentFormatter tests+ # ------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = DeepSeekMultiAgentFormatter()+ self.maxDiff = None++ # Full+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only (is_first=True for trailing assistant)+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools (is_first=True for trailing assistant)+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ self.assertListEqual([], await fmt.format([]))diff --git a/tests/formatter_gemini_test.py b/tests/formatter_gemini_test.pynew file mode 100644index 000000000..d2162f0aa--- /dev/null+++ b/tests/formatter_gemini_test.py@@ -0,0 +1,396 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for GeminiChatFormatter and+GeminiMultiAgentFormatter, following the reference test style with exact+ground-truth comparisons.+"""+from unittest import IsolatedAsyncioTestCase++from agentscope.formatter import (+ GeminiChatFormatter,+ GeminiMultiAgentFormatter,+)+from agentscope.message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ Base64Source,+ ThinkingBlock,+)+from agentscope.message._block import ToolResultState+++class TestGeminiFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for Gemini Chat and MultiAgent formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared message fixtures and expected ground-truth dicts."""+ image_b64 = "ZmFrZSBpbWFnZSBkYXRh"++ # ---------------------------------------------------------------+ # Message fixtures+ # (Use base64 images: Gemini URL handling downloads from the network)+ # ---------------------------------------------------------------+ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]++ self.msgs_conversation = [+ Msg(+ name="user",+ content=[+ TextBlock(+ type="text",+ text="What is the capital of France?",+ ),+ DataBlock(+ source=Base64Source(+ type="base64",+ data=image_b64,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]++ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ _inline_img = {+ "inline_data": {"data": image_b64, "mime_type": "image/png"},+ }++ # ---------------------------------------------------------------+ # Ground truth: GeminiChatFormatter+ # - System message becomes role="user" (no special system role).+ # - Assistant messages become role="model".+ # - Content is in "parts" (not "content") as a list of dicts.+ # - ToolCallBlock becomes "function_call" part.+ # - ToolResultBlock becomes a separate role="user" message with+ # "function_response" part.+ # ---------------------------------------------------------------+ self.gt_chat = [+ {+ "role": "user",+ "parts": [{"text": "You're a helpful assistant."}],+ },+ {+ "role": "user",+ "parts": [+ {"text": "What is the capital of France?"},+ _inline_img,+ ],+ },+ {+ "role": "model",+ "parts": [{"text": "The capital of France is Paris."}],+ },+ {+ "role": "user",+ "parts": [{"text": "What is the capital of Germany?"}],+ },+ {+ "role": "model",+ "parts": [{"text": "The capital of Germany is Berlin."}],+ },+ {+ "role": "user",+ "parts": [{"text": "What is the capital of Japan?"}],+ },+ {+ "role": "model",+ "parts": [+ {+ "function_call": {+ "id": "call_1",+ "name": "get_capital",+ "args": {"country": "Japan"},+ },+ },+ ],+ },+ {+ "role": "user",+ "parts": [+ {+ "function_response": {+ "id": "call_1",+ "name": "get_capital",+ "response": {+ "output": "The capital of Japan is Tokyo.",+ },+ },+ },+ ],+ },+ {+ "role": "model",+ "parts": [{"text": "The capital of Japan is Tokyo."}],+ },+ ]++ # ---------------------------------------------------------------+ # Ground truth: GeminiMultiAgentFormatter+ # - System message: role="user" (same as chat formatter).+ # - Agent messages: collapsed into role="user" with parts list.+ # - Media blocks interleaved (text flushed before each DataBlock).+ # - is_first=False still wraps with <history> (no hist_prompt+ # prefix).+ # ---------------------------------------------------------------+ _hist_prompt = GeminiMultiAgentFormatter().conversation_history_prompt++ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "parts": [+ {+ "text": (+ "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }+ self._gt_trailing_asst_first = {+ "role": "user",+ "parts": [+ {+ "text": (+ _hist_prompt + "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }++ self._gt_tool_call = {+ "role": "model",+ "parts": [+ {+ "function_call": {+ "id": "call_1",+ "name": "get_capital",+ "args": {"country": "Japan"},+ },+ },+ ],+ }+ self._gt_tool_result = {+ "role": "user",+ "parts": [+ {+ "function_response": {+ "id": "call_1",+ "name": "get_capital",+ "response": {+ "output": "The capital of Japan is Tokyo.",+ },+ },+ },+ ],+ }++ self.gt_multiagent = [+ {+ "role": "user",+ "parts": [{"text": "You're a helpful assistant."}],+ },+ {+ "role": "user",+ "parts": [+ {+ "text": (+ _hist_prompt + "<history>\n"+ "user: What is the capital of France?"+ ),+ },+ _inline_img,+ {+ "text": (+ "assistant: The capital of France is Paris.\n"+ "user: What is the capital of Germany?\n"+ "assistant: The capital of Germany is Berlin.\n"+ "user: What is the capital of Japan?\n"+ "</history>"+ ),+ },+ ],+ },+ self._gt_tool_call,+ self._gt_tool_result,+ _gt_trailing_asst_nonfirst,+ ]++ # -------------------------------------------------------------------+ # GeminiChatFormatter tests+ # -------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = GeminiChatFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)++ async def test_chat_formatter_thinking_preserved(self) -> None:+ """ThinkingBlock becomes a part with thought=True in Gemini format."""+ fmt = GeminiChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ thinking_parts = [+ p for p in res[0]["parts"] if p.get("thought") is True+ ]+ self.assertEqual(len(thinking_parts), 1)+ self.assertEqual(thinking_parts[0]["text"], "inner thoughts")++ # -------------------------------------------------------------------+ # GeminiMultiAgentFormatter tests+ # -------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = GeminiMultiAgentFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only — is_first=True for trailing assistant+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools — same is_first=True for trailing assistant+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)diff --git a/tests/formatter_kimi_test.py b/tests/formatter_kimi_test.pynew file mode 100644index 000000000..7045088db--- /dev/null+++ b/tests/formatter_kimi_test.py@@ -0,0 +1,485 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for KimiChatFormatter and+KimiMultiAgentFormatter, following the reference test style with exact+ground-truth comparisons.+"""+from unittest import IsolatedAsyncioTestCase++from agentscope.formatter import (+ KimiChatFormatter,+ KimiMultiAgentFormatter,+)+from agentscope.message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ Base64Source,+ URLSource,+ ThinkingBlock,+)+from agentscope.message._block import ToolResultState+++_FIXED_ID = "TESTID1234567"+++class TestKimiFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for Kimi Chat and MultiAgent formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared message fixtures and expected ground-truth dicts."""+ _img_src = URLSource(+ url="https://example.com/image.png",+ media_type="image/png",+ )+ image_url = str(_img_src.url)++ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"++ # ---------------------------------------------------------------+ # Message fixtures (no audio to avoid downloads)+ # ---------------------------------------------------------------+ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]++ self.msgs_conversation = [+ Msg(+ name="user",+ content=[+ TextBlock(+ type="text",+ text="What is the capital of France?",+ ),+ DataBlock(+ source=URLSource(+ url=image_url,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]++ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ # ---------------------------------------------------------------+ # Ground truth: KimiChatFormatter+ # - Same as OpenAI except ALL assistant messages have an extra+ # "reasoning_content" field (empty string when no ThinkingBlock).+ # ---------------------------------------------------------------+ self.gt_chat = [+ {+ "role": "system",+ "name": "system",+ "content": [+ {"type": "text", "text": "You're a helpful assistant."},+ ],+ },+ {+ "role": "user",+ "name": "user",+ "content": [+ {"type": "text", "text": "What is the capital of France?"},+ {+ "type": "image_url",+ "image_url": {"url": image_url},+ },+ ],+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of France is Paris.",+ },+ ],+ "reasoning_content": "",+ },+ {+ "role": "user",+ "name": "user",+ "content": [+ {+ "type": "text",+ "text": "What is the capital of Germany?",+ },+ ],+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of Germany is Berlin.",+ },+ ],+ "reasoning_content": "",+ },+ {+ "role": "user",+ "name": "user",+ "content": [+ {"type": "text", "text": "What is the capital of Japan?"},+ ],+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": None,+ "reasoning_content": "",+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ },+ {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": [+ {"type": "text", "text": "The capital of Japan is Tokyo."},+ ],+ "reasoning_content": "",+ },+ ]++ # ---------------------------------------------------------------+ # Ground truth: KimiMultiAgentFormatter+ # - Same as OpenAI MultiAgent, but tool-sequence assistant messages+ # carry "reasoning_content": "".+ # ---------------------------------------------------------------+ _hist_prompt = KimiMultiAgentFormatter().conversation_history_prompt++ _conv_text = (+ "user: What is the capital of France?\n"+ "assistant: The capital of France is Paris.\n"+ "user: What is the capital of Germany?\n"+ "assistant: The capital of Germany is Berlin.\n"+ "user: What is the capital of Japan?"+ )++ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }+ self._gt_trailing_asst_first = {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ _hist_prompt + "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }++ self._gt_tool_call = {+ "role": "assistant",+ "name": "assistant",+ "content": None,+ "reasoning_content": "",+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ }+ self._gt_tool_result = {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ }++ self.gt_multiagent = [+ {+ "role": "system",+ "content": "You're a helpful assistant.",+ },+ {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ _hist_prompt+ + "<history>\n"+ + _conv_text+ + "\n</history>"+ ),+ },+ {+ "type": "image_url",+ "image_url": {"url": image_url},+ },+ ],+ },+ self._gt_tool_call,+ self._gt_tool_result,+ _gt_trailing_asst_nonfirst,+ ]++ # -------------------------------------------------------------------+ # KimiChatFormatter tests+ # -------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = KimiChatFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)++ async def test_chat_formatter_thinking_to_reasoning_content(+ self,+ ) -> None:+ """ThinkingBlock becomes reasoning_content in Kimi (Preserved+ Thinking)."""+ fmt = KimiChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ self.assertEqual(res[0]["reasoning_content"], "inner thoughts")+ self.assertEqual(+ res[0]["content"],+ [{"type": "text", "text": "reply"}],+ )++ async def test_chat_formatter_assistant_always_has_reasoning_content(+ self,+ ) -> None:+ """All assistant messages always have reasoning_content (even when+ empty)."""+ fmt = KimiChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content="Hello!",+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ self.assertIn("reasoning_content", res[0])+ self.assertEqual(res[0]["reasoning_content"], "")++ async def test_chat_formatter_base64_image(self) -> None:+ """Base64-encoded image is inlined as a data URI."""+ fmt = KimiChatFormatter()+ msgs = [+ Msg(+ name="user",+ content=[+ TextBlock(type="text", text="What's in this image?"),+ DataBlock(+ source=Base64Source(+ type="base64",+ data=self.image_b64,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertListEqual(+ [+ {+ "role": "user",+ "name": "user",+ "content": [+ {"type": "text", "text": "What's in this image?"},+ {+ "type": "image_url",+ "image_url": {"url": self.image_data_uri},+ },+ ],+ },+ ],+ res,+ )++ # -------------------------------------------------------------------+ # KimiMultiAgentFormatter tests+ # -------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = KimiMultiAgentFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only — is_first=True for trailing assistant+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools — same is_first=True+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)diff --git a/tests/formatter_ollama_test.py b/tests/formatter_ollama_test.pynew file mode 100644index 000000000..9567ac09e--- /dev/null+++ b/tests/formatter_ollama_test.py@@ -0,0 +1,309 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for OllamaChatFormatter and+OllamaMultiAgentFormatter, with exact ground-truth comparisons.+"""+from unittest import IsolatedAsyncioTestCase++from agentscope.formatter import OllamaChatFormatter, OllamaMultiAgentFormatter+from agentscope.message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ Base64Source,+)+from agentscope.message._block import ToolResultState+++class TestOllamaFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for Ollama Chat and MultiAgent formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared fixtures and ground-truth dicts."""+ _hist_prompt = OllamaMultiAgentFormatter().conversation_history_prompt++ # Base64 image fixture+ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"++ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]+ self.msgs_conversation = [+ Msg(+ name="user",+ content="What is the capital of France?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]+ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ # --- Chat formatter ground truth ---+ # Ollama content is always a plain string.+ # Tool calls use dict arguments (not JSON string).+ self.gt_chat = [+ {"role": "system", "content": "You're a helpful assistant."},+ {"role": "user", "content": "What is the capital of France?"},+ {+ "role": "assistant",+ "content": "The capital of France is Paris.",+ },+ {"role": "user", "content": "What is the capital of Germany?"},+ {+ "role": "assistant",+ "content": "The capital of Germany is Berlin.",+ },+ {"role": "user", "content": "What is the capital of Japan?"},+ {+ "role": "assistant",+ "content": "",+ "tool_calls": [+ {+ "function": {+ "name": "get_capital",+ "arguments": {"country": "Japan"},+ },+ },+ ],+ },+ {"role": "tool", "content": "The capital of Japan is Tokyo."},+ {"role": "assistant", "content": "The capital of Japan is Tokyo."},+ ]++ # --- MultiAgent formatter ground truth ---+ # System content is a plain string.+ # History is a plain string with format "name:\ntext" per message.+ # For is_first=False, there are NO <history> tags (only in+ # is_first=True).+ _conv_text = (+ "user:\nWhat is the capital of France?\n"+ "assistant:\nThe capital of France is Paris.\n"+ "user:\nWhat is the capital of Germany?\n"+ "assistant:\nThe capital of Germany is Berlin.\n"+ "user:\nWhat is the capital of Japan?"+ )+ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "content": "assistant:\nThe capital of Japan is Tokyo.",+ }+ self._gt_trailing_asst_first = {+ "role": "user",+ "content": (+ _hist_prompt + "<history>\n"+ "assistant:\nThe capital of Japan is Tokyo.\n"+ "</history>"+ ),+ }+ self._gt_tool_call = {+ "role": "assistant",+ "content": "",+ "tool_calls": [+ {+ "function": {+ "name": "get_capital",+ "arguments": {"country": "Japan"},+ },+ },+ ],+ }+ self._gt_tool_result = {+ "role": "tool",+ "content": "The capital of Japan is Tokyo.",+ }++ self.gt_multiagent = [+ {"role": "system", "content": "You're a helpful assistant."},+ {+ "role": "user",+ "content": (+ _hist_prompt + "<history>\n" + _conv_text + "\n</history>"+ ),+ },+ self._gt_tool_call,+ self._gt_tool_result,+ _gt_trailing_asst_nonfirst,+ ]++ # ------------------------------------------------------------------+ # OllamaChatFormatter tests+ # ------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = OllamaChatFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ self.assertListEqual([], await fmt.format([]))++ async def test_chat_formatter_tool_call_arguments_are_dict(self) -> None:+ """Ollama requires tool call arguments as a dict, not a JSON string."""+ fmt = OllamaChatFormatter()+ tc = ToolCallBlock(id="c1", name="search", input='{"q": "weather"}')+ res = await fmt.format(+ [Msg(name="assistant", content=[tc], role="assistant")],+ )+ args = res[0]["tool_calls"][0]["function"]["arguments"]+ self.assertIsInstance(args, dict)+ self.assertEqual(args["q"], "weather")++ async def test_chat_formatter_base64_image(self) -> None:+ """Base64 image is placed in the 'images' list as a raw base64+ string."""+ fmt = OllamaChatFormatter()+ msgs = [+ Msg(+ name="user",+ content=[+ TextBlock(type="text", text="What is this?"),+ DataBlock(+ source=Base64Source(+ type="base64",+ data=self.image_b64,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ self.assertEqual(res[0]["content"], "What is this?")+ self.assertEqual(res[0]["images"], [self.image_b64])++ # ------------------------------------------------------------------+ # OllamaMultiAgentFormatter tests+ # ------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = OllamaMultiAgentFormatter()+ self.maxDiff = None++ # Full+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only (is_first=True for trailing assistant)+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools (is_first=True for trailing assistant)+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ self.assertListEqual([], await fmt.format([]))diff --git a/tests/formatter_openai_chat_test.py b/tests/formatter_openai_chat_test.pynew file mode 100644index 000000000..266a540e9--- /dev/null+++ b/tests/formatter_openai_chat_test.py@@ -0,0 +1,532 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for OpenAIChatFormatter and+OpenAIMultiAgentFormatter, following the reference test style with exact+ground-truth comparisons.+"""+from unittest import IsolatedAsyncioTestCase+from unittest.mock import patch++import shortuuid++from agentscope.formatter import (+ OpenAIChatFormatter,+ OpenAIMultiAgentFormatter,+)+from agentscope.message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ Base64Source,+ URLSource,+ ThinkingBlock,+)+from agentscope.message._block import ToolResultState+++_FIXED_ID = "TESTID1234567"+++class TestOpenAIFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for OpenAI Chat and MultiAgent formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared message fixtures and expected ground-truth dicts."""+ _img_src = URLSource(+ url="https://example.com/image.png",+ media_type="image/png",+ )+ self.image_url = str(_img_src.url)++ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"++ # ---------------------------------------------------------------+ # Message fixtures+ # (No audio in conversation: OpenAI URL audio requires a download)+ # ---------------------------------------------------------------+ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]++ self.msgs_conversation = [+ Msg(+ name="user",+ content=[+ TextBlock(+ type="text",+ text="What is the capital of France?",+ ),+ DataBlock(+ source=URLSource(+ url=self.image_url,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]++ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ # ---------------------------------------------------------------+ # Ground truth: OpenAIChatFormatter+ # - Content is a list of {"type": ..., ...} dicts.+ # - Tool-result content is a plain string.+ # - Messages have a "name" field.+ # ---------------------------------------------------------------+ self.gt_chat = [+ {+ "role": "system",+ "name": "system",+ "content": [+ {"type": "text", "text": "You're a helpful assistant."},+ ],+ },+ {+ "role": "user",+ "name": "user",+ "content": [+ {"type": "text", "text": "What is the capital of France?"},+ {+ "type": "image_url",+ "image_url": {"url": self.image_url},+ },+ ],+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of France is Paris.",+ },+ ],+ },+ {+ "role": "user",+ "name": "user",+ "content": [+ {+ "type": "text",+ "text": "What is the capital of Germany?",+ },+ ],+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of Germany is Berlin.",+ },+ ],+ },+ {+ "role": "user",+ "name": "user",+ "content": [+ {"type": "text", "text": "What is the capital of Japan?"},+ ],+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ },+ {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ },+ {+ "role": "assistant",+ "name": "assistant",+ "content": [+ {+ "type": "text",+ "text": "The capital of Japan is Tokyo.",+ },+ ],+ },+ ]++ # ---------------------------------------------------------------+ # Ground truth: OpenAIMultiAgentFormatter+ # - System content is a plain string.+ # - All conversation text is collapsed into a single text block,+ # with media blocks appended after.+ # - No "name" field on the user wrapper message.+ # ---------------------------------------------------------------+ _hist_prompt = OpenAIMultiAgentFormatter().conversation_history_prompt++ _conv_text = (+ "user: What is the capital of France?\n"+ "assistant: The capital of France is Paris.\n"+ "user: What is the capital of Germany?\n"+ "assistant: The capital of Germany is Berlin.\n"+ "user: What is the capital of Japan?"+ )++ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }+ self._gt_trailing_asst_first = {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ _hist_prompt + "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }++ self._gt_tool_call = {+ "role": "assistant",+ "name": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ },+ ],+ }+ self._gt_tool_result = {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": "The capital of Japan is Tokyo.",+ "name": "get_capital",+ }++ self.gt_multiagent = [+ {+ "role": "system",+ "content": "You're a helpful assistant.",+ },+ {+ "role": "user",+ "content": [+ {+ "type": "text",+ "text": (+ _hist_prompt+ + "<history>\n"+ + _conv_text+ + "\n</history>"+ ),+ },+ {+ "type": "image_url",+ "image_url": {"url": self.image_url},+ },+ ],+ },+ self._gt_tool_call,+ self._gt_tool_result,+ _gt_trailing_asst_nonfirst,+ ]++ # -------------------------------------------------------------------+ # OpenAIChatFormatter tests+ # -------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = OpenAIChatFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)++ async def test_chat_formatter_base64_image(self) -> None:+ """Base64-encoded image is inlined as a data URI."""+ fmt = OpenAIChatFormatter()+ msgs = [+ Msg(+ name="user",+ content=[+ TextBlock(type="text", text="What's in this image?"),+ DataBlock(+ source=Base64Source(+ type="base64",+ data=self.image_b64,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertListEqual(+ [+ {+ "role": "user",+ "name": "user",+ "content": [+ {"type": "text", "text": "What's in this image?"},+ {+ "type": "image_url",+ "image_url": {"url": self.image_data_uri},+ },+ ],+ },+ ],+ res,+ )++ async def test_chat_formatter_thinking_dropped(self) -> None:+ """ThinkingBlock is silently dropped by OpenAI formatter."""+ fmt = OpenAIChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ self.assertNotIn("reasoning_content", res[0])+ self.assertEqual(+ res[0]["content"],+ [{"type": "text", "text": "reply"}],+ )++ async def test_chat_formatter_url_image_in_tool_result(self) -> None:+ """URL images in tool results are promoted to a follow-up user+ message."""+ with patch.object(shortuuid, "uuid", return_value=_FIXED_ID):+ fmt = OpenAIChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_img",+ name="get_map",+ input='{"city": "Tokyo"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_img",+ name="get_map",+ output=[+ TextBlock(+ type="text",+ text="Here is the map.",+ ),+ DataBlock(+ source=URLSource(+ url=self.image_url,+ media_type="image/png",+ ),+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)++ expected_tool_content = (+ "Here is the map.\n"+ f"<system-reminder>A(n) image file is returned "+ f"and will be presented to you with the identifier "+ f"[{_FIXED_ID}].</system-reminder>"+ )+ self.assertEqual(len(res), 3)+ self.assertEqual(res[0]["role"], "assistant")+ self.assertEqual(res[1]["role"], "tool")+ self.assertEqual(res[1]["content"], expected_tool_content)+ # The promoted multimodal user message+ self.assertEqual(res[2]["role"], "user")+ image_blocks = [+ b+ for b in res[2]["content"]+ if b.get("type") == "image_url"+ and b["image_url"]["url"] == self.image_url+ ]+ self.assertEqual(len(image_blocks), 1)++ # -------------------------------------------------------------------+ # OpenAIMultiAgentFormatter tests+ # -------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = OpenAIMultiAgentFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only — is_first=True for the trailing assistant message+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools (no conversation) — same is_first=True+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)diff --git a/tests/formatter_openai_response_test.py b/tests/formatter_openai_response_test.pynew file mode 100644index 000000000..c7c51f1f7--- /dev/null+++ b/tests/formatter_openai_response_test.py@@ -0,0 +1,543 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for OpenAIResponseFormatter and+OpenAIResponseMultiAgentFormatter, following the reference test style with+exact ground-truth comparisons.++Key differences from OpenAI Chat formatter:+ - Text content type is "input_text" (not "text").+ - Image content type is "input_image" with flat "image_url" string.+ - Tool calls become top-level "function_call" items (not nested in a msg).+ - Tool results become top-level "function_call_output" items.+ - ThinkingBlock: only echoed when it has a "reasoning_item_id" attribute.+"""+from unittest import IsolatedAsyncioTestCase+from unittest.mock import patch++import shortuuid++from agentscope.formatter import (+ OpenAIResponseFormatter,+ OpenAIResponseMultiAgentFormatter,+)+from agentscope.message import (+ Msg,+ TextBlock,+ DataBlock,+ ToolCallBlock,+ ToolResultBlock,+ Base64Source,+ URLSource,+ ThinkingBlock,+)+from agentscope.message._block import ToolResultState+++_FIXED_ID = "TESTID1234567"+++class TestOpenAIResponseFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for OpenAI Responses API formatters."""++ async def asyncSetUp(self) -> None:+ """Set up shared message fixtures and expected ground-truth dicts."""+ _img_src = URLSource(+ url="https://example.com/image.png",+ media_type="image/png",+ )+ self.image_url = str(_img_src.url)++ self.image_b64 = "ZmFrZSBpbWFnZSBkYXRh"+ self.image_data_uri = f"data:image/png;base64,{self.image_b64}"++ # ---------------------------------------------------------------+ # Message fixtures (no audio to avoid downloads)+ # ---------------------------------------------------------------+ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]++ self.msgs_conversation = [+ Msg(+ name="user",+ content=[+ TextBlock(+ type="text",+ text="What is the capital of France?",+ ),+ DataBlock(+ source=URLSource(+ url=self.image_url,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]++ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ # ---------------------------------------------------------------+ # Ground truth: OpenAIResponseFormatter+ # - Text: {"type": "input_text", "text": ...}+ # - Image: {"type": "input_image", "image_url": url_string}+ # - ToolCallBlock → top-level {"type": "function_call", ...} item+ # - ToolResultBlock → top-level {"type": "function_call_output", ...}+ # - No "name" field on messages.+ # ---------------------------------------------------------------+ self.gt_chat = [+ {+ "role": "system",+ "content": [+ {+ "type": "input_text",+ "text": "You're a helpful assistant.",+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "input_text",+ "text": "What is the capital of France?",+ },+ {"type": "input_image", "image_url": self.image_url},+ ],+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "input_text",+ "text": "The capital of France is Paris.",+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "input_text",+ "text": "What is the capital of Germany?",+ },+ ],+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "input_text",+ "text": "The capital of Germany is Berlin.",+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "input_text",+ "text": "What is the capital of Japan?",+ },+ ],+ },+ {+ "type": "function_call",+ "id": "call_1",+ "call_id": "call_1",+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ },+ {+ "type": "function_call_output",+ "call_id": "call_1",+ "output": "The capital of Japan is Tokyo.",+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "input_text",+ "text": "The capital of Japan is Tokyo.",+ },+ ],+ },+ ]++ # ---------------------------------------------------------------+ # Ground truth: OpenAIResponseMultiAgentFormatter+ # - System: {"role": "system", "content": plain_string}+ # - Conversation history: input_text with history wrapping.+ # - Tool sequences use OpenAIResponseFormatter (function_call /+ # function_call_output top-level items).+ # ---------------------------------------------------------------+ _hist_prompt = (+ OpenAIResponseMultiAgentFormatter().conversation_history_prompt+ )++ _conv_text = (+ "user: What is the capital of France?\n"+ "assistant: The capital of France is Paris.\n"+ "user: What is the capital of Germany?\n"+ "assistant: The capital of Germany is Berlin.\n"+ "user: What is the capital of Japan?"+ )++ _gt_trailing_asst_nonfirst = {+ "role": "user",+ "content": [+ {+ "type": "input_text",+ "text": (+ "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }+ self._gt_trailing_asst_first = {+ "role": "user",+ "content": [+ {+ "type": "input_text",+ "text": (+ _hist_prompt + "<history>\n"+ "assistant: The capital of Japan is Tokyo.\n"+ "</history>"+ ),+ },+ ],+ }++ self._gt_tool_call = {+ "type": "function_call",+ "id": "call_1",+ "call_id": "call_1",+ "name": "get_capital",+ "arguments": '{"country": "Japan"}',+ }+ self._gt_tool_result = {+ "type": "function_call_output",+ "call_id": "call_1",+ "output": "The capital of Japan is Tokyo.",+ }++ self.gt_multiagent = [+ {+ "role": "system",+ "content": "You're a helpful assistant.",+ },+ {+ "role": "user",+ "content": [+ {+ "type": "input_text",+ "text": (+ _hist_prompt+ + "<history>\n"+ + _conv_text+ + "\n</history>"+ ),+ },+ {"type": "input_image", "image_url": self.image_url},+ ],+ },+ self._gt_tool_call,+ self._gt_tool_result,+ _gt_trailing_asst_nonfirst,+ ]++ # -------------------------------------------------------------------+ # OpenAIResponseFormatter tests+ # -------------------------------------------------------------------++ async def test_chat_formatter(self) -> None:+ """Chat formatter produces exact output for various subsets."""+ fmt = OpenAIResponseFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_chat, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_chat[1:], res)++ # Without conversation+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [self.gt_chat[0]] + self.gt_chat[-len(self.msgs_tools) :],+ res,+ )++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_chat[: -len(self.msgs_tools)], res)++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)++ async def test_chat_formatter_base64_image(self) -> None:+ """Base64-encoded image becomes an input_image item with data URI."""+ fmt = OpenAIResponseFormatter()+ msgs = [+ Msg(+ name="user",+ content=[+ TextBlock(type="text", text="What's in this image?"),+ DataBlock(+ source=Base64Source(+ type="base64",+ data=self.image_b64,+ media_type="image/png",+ ),+ ),+ ],+ role="user",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertListEqual(+ [+ {+ "role": "user",+ "content": [+ {+ "type": "input_text",+ "text": "What's in this image?",+ },+ {+ "type": "input_image",+ "image_url": self.image_data_uri,+ },+ ],+ },+ ],+ res,+ )++ async def test_chat_formatter_thinking_dropped_without_reasoning_item_id(+ self,+ ) -> None:+ """ThinkingBlock without reasoning_item_id is silently skipped."""+ fmt = OpenAIResponseFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ self.assertEqual(len(res), 1)+ self.assertEqual(res[0]["role"], "assistant")+ parts = res[0]["content"]+ self.assertEqual(len(parts), 1)+ self.assertEqual(parts[0]["type"], "input_text")++ async def test_chat_formatter_thinking_echoed_with_reasoning_item_id(+ self,+ ) -> None:+ """ThinkingBlock with reasoning_item_id is echoed as a reasoning+ item."""+ fmt = OpenAIResponseFormatter()+ thinking = ThinkingBlock(thinking="my reasoning")+ thinking.reasoning_item_id = "rs_001"+ msgs = [+ Msg(+ name="assistant",+ content=[thinking, TextBlock(type="text", text="reply")],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ reasoning_items = [r for r in res if r.get("type") == "reasoning"]+ self.assertEqual(len(reasoning_items), 1)+ self.assertEqual(reasoning_items[0]["id"], "rs_001")+ self.assertEqual(+ reasoning_items[0]["summary"],+ [{"type": "summary_text", "text": "my reasoning"}],+ )++ async def test_chat_formatter_url_image_in_tool_result(self) -> None:+ """URL images in tool results are promoted to a follow-up user+ message."""+ with patch.object(shortuuid, "uuid", return_value=_FIXED_ID):+ fmt = OpenAIResponseFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_img",+ name="get_map",+ input='{"city": "Tokyo"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_img",+ name="get_map",+ output=[+ TextBlock(+ type="text",+ text="Here is the map.",+ ),+ DataBlock(+ source=URLSource(+ url=self.image_url,+ media_type="image/png",+ ),+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)++ self.assertEqual(len(res), 3)+ # function_call+ self.assertEqual(res[0]["type"], "function_call")+ # function_call_output with reminder text+ self.assertEqual(res[1]["type"], "function_call_output")+ self.assertIn("Here is the map.", res[1]["output"])+ # promoted user message with the image+ self.assertEqual(res[2]["role"], "user")+ image_parts = [+ p+ for p in res[2]["content"]+ if p.get("type") == "input_image"+ and p.get("image_url") == self.image_url+ ]+ self.assertEqual(len(image_parts), 1)++ # -------------------------------------------------------------------+ # OpenAIResponseMultiAgentFormatter tests+ # -------------------------------------------------------------------++ async def test_multiagent_formatter(self) -> None:+ """MultiAgent formatter produces exact output for various subsets."""+ fmt = OpenAIResponseMultiAgentFormatter()+ self.maxDiff = None++ # Full history+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ self.assertListEqual(self.gt_multiagent, res)++ # Without system+ res = await fmt.format([*self.msgs_conversation, *self.msgs_tools])+ self.assertListEqual(self.gt_multiagent[1:], res)++ # Without tools+ res = await fmt.format([*self.msgs_system, *self.msgs_conversation])+ self.assertListEqual(self.gt_multiagent[:2], res)++ # System only+ res = await fmt.format(self.msgs_system)+ self.assertListEqual([self.gt_multiagent[0]], res)++ # Conversation only+ res = await fmt.format(self.msgs_conversation)+ self.assertListEqual([self.gt_multiagent[1]], res)++ # Tools only — is_first=True for trailing assistant+ res = await fmt.format(self.msgs_tools)+ self.assertListEqual(+ [+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # System + tools — same is_first=True+ res = await fmt.format([*self.msgs_system, *self.msgs_tools])+ self.assertListEqual(+ [+ self.gt_multiagent[0],+ self._gt_tool_call,+ self._gt_tool_result,+ self._gt_trailing_asst_first,+ ],+ res,+ )++ # Empty+ res = await fmt.format([])+ self.assertListEqual([], res)diff --git a/tests/formatter_xai_test.py b/tests/formatter_xai_test.pynew file mode 100644index 000000000..3a0aa9ad3--- /dev/null+++ b/tests/formatter_xai_test.py@@ -0,0 +1,347 @@+# -*- coding: utf-8 -*-+"""Comprehensive formatter unit tests for XAIChatFormatter and+XAIMultiAgentFormatter (xAI), following the reference test style.++Because these formatters return xai_sdk protobuf Message objects (not plain+dicts), a lightweight xai_sdk stub is built at module load so that tests run+without the real package. Assertions check mock object attributes+(role, args, kwargs, tool_calls, etc.) rather than plain-dict equality.+"""+import sys+from typing import Any+from types import ModuleType+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.formatter import XAIChatFormatter, XAIMultiAgentFormatter+from agentscope.message import (+ Msg,+ TextBlock,+ ToolCallBlock,+ ToolResultBlock,+ ThinkingBlock,+ ToolResultState,+)++# ---------------------------------------------------------------------------+# Build a lightweight xai_sdk stub so tests run without the real package.+# ---------------------------------------------------------------------------+++def _build_xai_sdk_stub() -> None:+ if "xai_sdk" in sys.modules:+ return++ chat_pb2 = ModuleType("xai_sdk.chat.chat_pb2")++ class _EnumHelper:+ _mapping = {+ "ROLE_ASSISTANT": 2,+ "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL": 1,+ }++ def Value(self, name: str) -> int:+ """Return the integer value for the given enum name."""+ return self._mapping.get(name, 0)++ chat_pb2.MessageRole = _EnumHelper()+ chat_pb2.ToolCallType = _EnumHelper()++ class _RepeatedField(list):+ def __init__(self, factory: Any) -> None:+ super().__init__()+ self._factory = factory++ def add(self) -> Any:+ """Add a new item using the factory and return it."""+ item = self._factory()+ self.append(item)+ return item++ class _FunctionSpec:+ name: str = ""+ arguments: str = ""++ class _ToolCallProto:+ id: str = ""+ type: int = 0+ function = _FunctionSpec()++ class _ContentPart:+ text: str = ""++ class _MessageProto:+ def __init__(self) -> None:+ self.role = 0+ self.content = _RepeatedField(_ContentPart)+ self.tool_calls = _RepeatedField(_ToolCallProto)++ chat_pb2.Message = _MessageProto++ xai_chat = ModuleType("xai_sdk.chat")+ xai_chat.chat_pb2 = chat_pb2+ xai_chat.user = lambda *args: MagicMock(role="user", args=args)+ xai_chat.assistant = lambda *args: MagicMock(role="assistant", args=args)+ xai_chat.system = lambda *args: MagicMock(role="system", args=args)+ xai_chat.tool_result = lambda *args, **kw: MagicMock(+ role="tool",+ args=args,+ kwargs=kw,+ )+ xai_chat.image = lambda url: MagicMock(type="image", url=url)++ xai_sdk = ModuleType("xai_sdk")+ xai_sdk.chat = xai_chat+ xai_sdk.AsyncClient = MagicMock()++ sys.modules["xai_sdk"] = xai_sdk+ sys.modules["xai_sdk.chat"] = xai_chat+ sys.modules["xai_sdk.chat.chat_pb2"] = chat_pb2+++_build_xai_sdk_stub()+++class TestXAIFormatter(IsolatedAsyncioTestCase):+ """Comprehensive tests for XAI Chat and MultiAgent formatters.++ The formatter returns proto/mock objects rather than dicts, so assertions+ inspect mock attributes (role, args, kwargs, tool_calls, etc.).+ """++ async def asyncSetUp(self) -> None:+ self.msgs_system = [+ Msg(+ name="system",+ content="You're a helpful assistant.",+ role="system",+ ),+ ]++ self.msgs_conversation = [+ Msg(+ name="user",+ content="What is the capital of France?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of France is Paris.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Germany?",+ role="user",+ ),+ Msg(+ name="assistant",+ content="The capital of Germany is Berlin.",+ role="assistant",+ ),+ Msg(+ name="user",+ content="What is the capital of Japan?",+ role="user",+ ),+ ]++ self.msgs_tools = [+ Msg(+ name="assistant",+ content=[+ ToolCallBlock(+ id="call_1",+ name="get_capital",+ input='{"country": "Japan"}',+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="tool",+ content=[+ ToolResultBlock(+ id="call_1",+ name="get_capital",+ output=[+ TextBlock(+ type="text",+ text="The capital of Japan is Tokyo.",+ ),+ ],+ state=ToolResultState.SUCCESS,+ ),+ ],+ role="assistant",+ ),+ Msg(+ name="assistant",+ content="The capital of Japan is Tokyo.",+ role="assistant",+ ),+ ]++ self._hist_prompt = (+ XAIMultiAgentFormatter().conversation_history_prompt+ )++ # -------------------------------------------------------------------+ # XAIChatFormatter tests+ # -------------------------------------------------------------------++ async def test_chat_formatter_system_message(self) -> None:+ """System message becomes a system() proto."""+ fmt = XAIChatFormatter()+ res = await fmt.format(self.msgs_system)+ self.assertEqual(len(res), 1)+ self.assertEqual(res[0].role, "system")+ self.assertIn("You're a helpful assistant.", res[0].args)++ async def test_chat_formatter_user_assistant(self) -> None:+ """User and assistant text messages are passed through correctly."""+ fmt = XAIChatFormatter()+ res = await fmt.format(self.msgs_conversation)+ roles = [m.role for m in res]+ self.assertEqual(roles.count("user"), 3)+ self.assertEqual(roles.count("assistant"), 2)++ async def test_chat_formatter_tool_call(self) -> None:+ """Assistant tool call becomes a _MessageProto with tool_calls set."""+ fmt = XAIChatFormatter()+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ # Find the tool call proto (has tool_calls list, role=ROLE_ASSISTANT=2)+ tool_call_msgs = [+ m+ for m in res+ if hasattr(m, "tool_calls") and len(m.tool_calls) > 0+ ]+ self.assertEqual(len(tool_call_msgs), 1)+ tc = tool_call_msgs[0].tool_calls[0]+ self.assertEqual(tc.id, "call_1")+ self.assertEqual(tc.function.name, "get_capital")+ self.assertIn('"country"', tc.function.arguments)++ async def test_chat_formatter_tool_result(self) -> None:+ """Tool result becomes a tool_result() proto with the right id."""+ fmt = XAIChatFormatter()+ res = await fmt.format(self.msgs_tools)+ tool_msgs = [m for m in res if m.role == "tool"]+ self.assertEqual(len(tool_msgs), 1)+ self.assertEqual(+ tool_msgs[0].kwargs.get("tool_call_id"),+ "call_1",+ )+ self.assertIn(+ "The capital of Japan is Tokyo.",+ tool_msgs[0].args,+ )++ async def test_chat_formatter_thinking_dropped(self) -> None:+ """ThinkingBlock is silently ignored in user/assistant xAI+ messages."""+ fmt = XAIChatFormatter()+ msgs = [+ Msg(+ name="assistant",+ content=[+ ThinkingBlock(thinking="inner thoughts"),+ TextBlock(type="text", text="reply"),+ ],+ role="assistant",+ ),+ ]+ res = await fmt.format(msgs)+ # thinking block is silently skipped for assistant text path+ self.assertEqual(len(res), 1)+ self.assertEqual(res[0].role, "assistant")++ async def test_chat_formatter_empty(self) -> None:+ """Empty input returns empty list."""+ fmt = XAIChatFormatter()+ res = await fmt.format([])+ self.assertListEqual([], res)++ # -------------------------------------------------------------------+ # XAIMultiAgentFormatter tests+ # -------------------------------------------------------------------++ async def test_multiagent_formatter_system_message(self) -> None:+ """System message is passed through as a system() proto."""+ fmt = XAIMultiAgentFormatter()+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation],+ )+ self.assertEqual(res[0].role, "system")+ self.assertIn("You're a helpful assistant.", res[0].args)++ async def test_multiagent_formatter_conversation_history(self) -> None:+ """Non-tool agent messages are collapsed into a user() history+ proto."""+ fmt = XAIMultiAgentFormatter()+ res = await fmt.format(self.msgs_conversation)+ self.assertEqual(len(res), 1)+ self.assertEqual(res[0].role, "user")+ hist_text = res[0].args[0]+ self.assertIn("<history>", hist_text)+ self.assertIn("</history>", hist_text)+ self.assertIn("user: What is the capital of France?", hist_text)+ self.assertIn("assistant: The capital of France is Paris.", hist_text)++ async def test_multiagent_formatter_first_group_has_hist_prompt(+ self,+ ) -> None:+ """First agent message group includes the conversation history+ prompt."""+ fmt = XAIMultiAgentFormatter()+ res = await fmt.format(self.msgs_conversation)+ hist_text = res[0].args[0]+ self.assertTrue(hist_text.startswith(self._hist_prompt))++ async def test_multiagent_formatter_full_history(self) -> None:+ """Full history produces system + conv_history + tool_call ++ tool_result + trailing."""+ fmt = XAIMultiAgentFormatter()+ res = await fmt.format(+ [*self.msgs_system, *self.msgs_conversation, *self.msgs_tools],+ )+ roles = [m.role for m in res]+ self.assertIn("system", roles)+ self.assertIn("user", roles)+ self.assertIn("tool", roles)++ async def test_multiagent_formatter_tools_only_is_first(self) -> None:+ """When only tools are given, trailing agent uses is_first=True+ history."""+ fmt = XAIMultiAgentFormatter()+ res = await fmt.format(self.msgs_tools)+ # tool_call proto, tool_result proto, trailing user history+ trailing = [m for m in res if m.role == "user"]+ self.assertEqual(len(trailing), 1)+ hist_text = trailing[0].args[0]+ self.assertIn(self._hist_prompt, hist_text)+ self.assertIn("assistant: The capital of Japan is Tokyo.", hist_text)++ async def test_multiagent_formatter_nonfirst_trailing_no_hist_prompt(+ self,+ ) -> None:+ """Trailing agent after a conversation group uses is_first=False+ (no prompt)."""+ fmt = XAIMultiAgentFormatter()+ res = await fmt.format(+ [*self.msgs_conversation, *self.msgs_tools],+ )+ user_msgs = [m for m in res if m.role == "user"]+ # First is conversation history (is_first=True), last is trailing+ # (is_first=False)+ trailing_text = user_msgs[-1].args[0]+ self.assertNotIn(self._hist_prompt, trailing_text)+ self.assertIn("<history>", trailing_text)++ async def test_multiagent_formatter_empty(self) -> None:+ """Empty input returns empty list."""+ fmt = XAIMultiAgentFormatter()+ res = await fmt.format([])+ self.assertListEqual([], res)diff --git a/tests/model_anthropic_test.py b/tests/model_anthropic_test.pynew file mode 100644index 000000000..b1b31e2b3--- /dev/null+++ b/tests/model_anthropic_test.py@@ -0,0 +1,131 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for AnthropicChatModel response parsing.++Formatter tests have been moved to tests/formatter_anthropic_test.py.+"""+import json+from typing import Any+from datetime import datetime+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock+from agentscope.model import AnthropicChatModel+from agentscope.credential import AnthropicCredential+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return AnthropicChatModel(+ credential=AnthropicCredential(api_key="test"),+ model="claude-opus-4-5",+ stream=False,+ context_size=200_000,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestAnthropicModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for AnthropicChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_anthropic_response(+ self,+ text: Any = None,+ tool_calls: Any = None,+ thinking: Any = None,+ ) -> "MagicMock":+ """Build a mock Anthropic API response object."""+ blocks = []+ if thinking:+ b = MagicMock()+ b.type = "thinking"+ b.thinking = thinking+ b.signature = ""+ blocks.append(b)+ if text:+ b = MagicMock()+ b.type = "text"+ b.text = text+ blocks.append(b)+ if tool_calls:+ for tc in tool_calls:+ b = MagicMock()+ b.type = "tool_use"+ b.id = tc["id"]+ b.name = tc["name"]+ b.input = tc["input"]+ blocks.append(b)++ resp = MagicMock()+ resp.id = "msg-1"+ resp.content = blocks+ resp.usage.input_tokens = 10+ resp.usage.output_tokens = 5+ return resp++ async def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_anthropic_response(text="Hello!")+ result = await self.model._parse_anthropic_completion_response(+ self.start,+ resp,+ )+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ async def test_parse_tool_call_response(self) -> None:+ """Parsing a tool-call response creates a ToolCallBlock."""+ resp = self._mock_anthropic_response(+ tool_calls=[+ {+ "id": "call-1",+ "name": "get_weather",+ "input": {"city": "Beijing"},+ },+ ],+ )+ result = await self.model._parse_anthropic_completion_response(+ self.start,+ resp,+ )+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(tcs[0].id, "call-1")+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")++ async def test_parse_thinking_response(self) -> None:+ """Parsing a response with thinking creates a ThinkingBlock."""+ resp = self._mock_anthropic_response(+ thinking="Let me think...",+ text="Answer",+ )+ result = await self.model._parse_anthropic_completion_response(+ self.start,+ resp,+ )+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(thinkings[0].thinking, "Let me think...")++ async def test_response_id_set(self) -> None:+ """The response ID from the API is stored in the ChatResponse."""+ resp = self._mock_anthropic_response(text="Hi")+ result = await self.model._parse_anthropic_completion_response(+ self.start,+ resp,+ )+ self.assertEqual(result.id, "msg-1")diff --git a/tests/model_dashscope_test.py b/tests/model_dashscope_test.pynew file mode 100644index 000000000..d3e4b1e08--- /dev/null+++ b/tests/model_dashscope_test.py@@ -0,0 +1,117 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for DashScopeChatModel response parsing.++Formatter tests have been moved to tests/formatter_dashscope_test.py.+"""+import json+from typing import Any+from datetime import datetime+from http import HTTPStatus+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock+from agentscope.model import DashScopeChatModel+from agentscope.credential import DashScopeCredential+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return DashScopeChatModel(+ credential=DashScopeCredential(api_key="test"),+ model="qwen3-max",+ stream=False,+ multimodality=True,+ max_retries=3,+ context_size=int(1500),+ parameters=DashScopeChatModel.Parameters(+ max_tokens=1000,+ thinking_enable=True,+ thinking_budget=100,+ ),+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestDashScopeModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for DashScopeChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_response(+ self,+ content: Any = None,+ tool_calls: Any = None,+ ) -> "MagicMock":+ """Build a minimal DashScope GenerationResponse mock."""+ message = {}+ if content is not None:+ message["content"] = content+ if tool_calls is not None:+ message["tool_calls"] = tool_calls++ msg_mock = MagicMock()+ msg_mock.get = lambda key, default=None: message.get(key, default)++ resp = MagicMock()+ resp.status_code = HTTPStatus.OK+ resp.output.choices[0].message = msg_mock+ resp.request_id = "req-1"+ resp.usage.input_tokens = 10+ resp.usage.output_tokens = 5+ return resp++ async def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_response(content="Hello!")+ result = await self.model._parse_dashscope_generation_response(+ self.start,+ resp,+ )+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ async def test_parse_tool_call_response(self) -> None:+ """Parsing a tool-call response creates a ToolCallBlock."""+ tool_calls = [+ {+ "id": "call-1",+ "function": {+ "name": "get_weather",+ "arguments": '{"city":"Beijing"}',+ },+ },+ ]+ resp = self._mock_response(tool_calls=tool_calls)+ result = await self.model._parse_dashscope_generation_response(+ self.start,+ resp,+ )+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].id, "call-1")+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")++ async def test_parse_response_with_status_error(self) -> None:+ """Non-OK status raises RuntimeError."""+ resp = self._mock_response(content="text")+ resp.status_code = HTTPStatus.BAD_REQUEST+ with self.assertRaises(RuntimeError):+ await self.model._parse_dashscope_generation_response(+ self.start,+ resp,+ )diff --git a/tests/model_deepseek_test.py b/tests/model_deepseek_test.pynew file mode 100644index 000000000..f775e72b0--- /dev/null+++ b/tests/model_deepseek_test.py@@ -0,0 +1,116 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for DeepSeekChatModel response parsing.++Formatter tests have been moved to tests/formatter_deepseek_test.py.+"""+from typing import Any+from datetime import datetime+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock+from agentscope.model import DeepSeekChatModel+from agentscope.credential import DeepSeekCredential+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return DeepSeekChatModel(+ credential=DeepSeekCredential(api_key="test"),+ model="deepseek-v4-pro",+ stream=False,+ context_size=65_536,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestDeepSeekModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for DeepSeekChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_completion(+ self,+ text: Any = None,+ tool_calls: Any = None,+ reasoning: Any = None,+ ) -> "MagicMock":+ """Build a mock DeepSeek API completion response object."""+ msg = MagicMock()+ msg.content = text+ setattr(msg, "reasoning_content", reasoning)+ msg.tool_calls = None++ if tool_calls:+ tc_mocks = []+ for tc in tool_calls:+ m = MagicMock()+ m.id = tc["id"]+ m.function.name = tc["name"]+ m.function.arguments = tc["arguments"]+ tc_mocks.append(m)+ msg.tool_calls = tc_mocks++ choice = MagicMock()+ choice.message = msg++ resp = MagicMock()+ resp.id = "deepseek-1"+ resp.choices = [choice]+ resp.usage.prompt_tokens = 10+ resp.usage.completion_tokens = 5+ return resp++ def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_completion(text="Hello!")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ def test_parse_tool_call_response(self) -> None:+ """Parsing a tool-call response creates a ToolCallBlock."""+ resp = self._mock_completion(+ tool_calls=[+ {+ "id": "call-1",+ "name": "get_weather",+ "arguments": '{"city":"Beijing"}',+ },+ ],+ )+ result = self.model._parse_completion_response(self.start, resp)+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].id, "call-1")+ self.assertEqual(tcs[0].name, "get_weather")++ def test_parse_thinking_response(self) -> None:+ """Parsing a response with reasoning creates a ThinkingBlock."""+ resp = self._mock_completion(+ text="Answer",+ reasoning="Let me think...",+ )+ result = self.model._parse_completion_response(self.start, resp)+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(len(thinkings), 1)+ self.assertEqual(thinkings[0].thinking, "Let me think...")++ def test_response_id_set(self) -> None:+ """The response ID from the API is stored in the ChatResponse."""+ resp = self._mock_completion(text="Hi")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertEqual(result.id, "deepseek-1")diff --git a/tests/model_gemini_test.py b/tests/model_gemini_test.pynew file mode 100644index 000000000..53736994f--- /dev/null+++ b/tests/model_gemini_test.py@@ -0,0 +1,117 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for GeminiChatModel response parsing.++Formatter tests have been moved to tests/formatter_gemini_test.py.+"""+import json+from typing import Any+from datetime import datetime+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock+from agentscope.model import GeminiChatModel+from agentscope.credential import GeminiCredential+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return GeminiChatModel(+ credential=GeminiCredential(api_key="test"),+ model="gemini-2.5-flash",+ stream=False,+ context_size=1_048_576,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestGeminiModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for GeminiChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_response(+ self,+ text: Any = None,+ function_calls: Any = None,+ thought: Any = None,+ ) -> "MagicMock":+ """Build a mock Gemini API response object."""+ parts = []+ if thought:+ p = MagicMock()+ p.text = thought+ p.thought = True+ p.function_call = None+ p.thought_signature = None+ parts.append(p)+ if text:+ p = MagicMock()+ p.text = text+ p.thought = False+ p.function_call = None+ p.thought_signature = None+ parts.append(p)+ if function_calls:+ for fc in function_calls:+ p = MagicMock()+ p.text = None+ p.thought = False+ p.thought_signature = None+ p.function_call.name = fc["name"]+ p.function_call.args = fc["args"]+ p.function_call.id = fc.get("id", "call-1")+ parts.append(p)++ resp = MagicMock()+ resp.candidates = [MagicMock()]+ resp.candidates[0].content.parts = parts+ resp.usage_metadata = MagicMock()+ resp.usage_metadata.prompt_token_count = 10+ resp.usage_metadata.candidates_token_count = 5+ return resp++ def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_response(text="Hello!")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ def test_parse_tool_call_response(self) -> None:+ """Parsing a function_call response creates a ToolCallBlock."""+ resp = self._mock_response(+ function_calls=[+ {+ "name": "get_weather",+ "args": {"city": "Beijing"},+ "id": "call-1",+ },+ ],+ )+ result = self.model._parse_completion_response(self.start, resp)+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")++ def test_parse_thinking_response(self) -> None:+ """Parsing a response with thought creates a ThinkingBlock."""+ resp = self._mock_response(thought="Let me think...", text="Answer")+ result = self.model._parse_completion_response(self.start, resp)+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(len(thinkings), 1)+ self.assertEqual(thinkings[0].thinking, "Let me think...")diff --git a/tests/model_kimi_test.py b/tests/model_kimi_test.pynew file mode 100644index 000000000..8dc98adbe--- /dev/null+++ b/tests/model_kimi_test.py@@ -0,0 +1,115 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for KimiChatModel response parsing.++Formatter tests have been moved to tests/formatter_kimi_test.py.+"""+import json+from typing import Any+from datetime import datetime+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock+from agentscope.model import KimiChatModel+from agentscope.credential import KimiCredential+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return KimiChatModel(+ credential=KimiCredential(api_key="test"),+ model="kimi-k2-5",+ stream=False,+ context_size=131_072,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestKimiModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for KimiChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_completion(+ self,+ text: Any = None,+ tool_calls: Any = None,+ reasoning: Any = None,+ ) -> "MagicMock":+ """Build a mock Kimi API completion response object."""+ msg = MagicMock()+ msg.content = text+ setattr(msg, "reasoning_content", reasoning)+ msg.tool_calls = None++ if tool_calls:+ tc_mocks = []+ for tc in tool_calls:+ m = MagicMock()+ m.id = tc["id"]+ m.function.name = tc["name"]+ m.function.arguments = tc["arguments"]+ tc_mocks.append(m)+ msg.tool_calls = tc_mocks++ choice = MagicMock()+ choice.message = msg++ resp = MagicMock()+ resp.id = "kimi-1"+ resp.choices = [choice]+ resp.usage.prompt_tokens = 10+ resp.usage.completion_tokens = 5+ return resp++ def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_completion(text="Hello!")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ def test_parse_tool_call_response(self) -> None:+ """Parsing a tool-call response creates a ToolCallBlock."""+ resp = self._mock_completion(+ tool_calls=[+ {+ "id": "call-1",+ "name": "get_weather",+ "arguments": '{"city":"Beijing"}',+ },+ ],+ )+ result = self.model._parse_completion_response(self.start, resp)+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].id, "call-1")+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")++ def test_parse_thinking_response(self) -> None:+ """Parsing a response with reasoning creates a ThinkingBlock."""+ resp = self._mock_completion(text="Answer", reasoning="Thinking...")+ result = self.model._parse_completion_response(self.start, resp)+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(len(thinkings), 1)+ self.assertEqual(thinkings[0].thinking, "Thinking...")++ def test_response_id_set(self) -> None:+ """The response ID from the API is stored in the ChatResponse."""+ resp = self._mock_completion(text="Hi")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertEqual(result.id, "kimi-1")diff --git a/tests/model_ollama_test.py b/tests/model_ollama_test.pynew file mode 100644index 000000000..c8637bce6--- /dev/null+++ b/tests/model_ollama_test.py@@ -0,0 +1,101 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for OllamaChatModel response parsing.++Formatter tests have been moved to tests/formatter_ollama_test.py.+"""+import json+from typing import Any+from datetime import datetime+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock+from agentscope.model import OllamaChatModel+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return OllamaChatModel(+ model="qwen3:8b",+ stream=False,+ context_size=40_960,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestOllamaModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for OllamaChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_response(+ self,+ content: Any = None,+ tool_calls: Any = None,+ thinking: Any = None,+ ) -> "MagicMock":+ """Build a mock Ollama API response object."""+ msg = MagicMock()+ msg.content = content or ""+ setattr(msg, "thinking", thinking)++ if tool_calls:+ tc_mocks = []+ for tc in tool_calls:+ m = MagicMock()+ m.function.name = tc["name"]+ m.function.arguments = tc["args"]+ tc_mocks.append(m)+ msg.tool_calls = tc_mocks+ else:+ msg.tool_calls = None++ resp = MagicMock()+ resp.message = msg+ resp.prompt_eval_count = 10+ resp.eval_count = 5+ setattr(resp, "id", "ollama-1")+ return resp++ async def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_response(content="Hello!")+ result = await self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ async def test_parse_tool_call_response(self) -> None:+ """Parsing a tool-call response creates a ToolCallBlock."""+ resp = self._mock_response(+ tool_calls=[+ {"name": "get_weather", "args": {"city": "Beijing"}},+ ],+ )+ result = await self.model._parse_completion_response(self.start, resp)+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertIn("city", json.loads(tcs[0].input))++ async def test_parse_thinking_response(self) -> None:+ """Parsing a response with thinking creates a ThinkingBlock."""+ resp = self._mock_response(+ content="Answer",+ thinking="Let me think...",+ )+ result = await self.model._parse_completion_response(self.start, resp)+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(thinkings[0].thinking, "Let me think...")diff --git a/tests/model_openai_chat_test.py b/tests/model_openai_chat_test.pynew file mode 100644index 000000000..62d731865--- /dev/null+++ b/tests/model_openai_chat_test.py@@ -0,0 +1,122 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for OpenAIChatModel response parsing.++Formatter tests have been moved to tests/formatter_openai_chat_test.py.+"""+import json+from typing import Any+from datetime import datetime+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock+from agentscope.model import OpenAIChatModel+from agentscope.credential import OpenAICredential+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return OpenAIChatModel(+ credential=OpenAICredential(api_key="test"),+ model="gpt-4o",+ stream=False,+ context_size=128_000,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestOpenAIChatModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for OpenAIChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_completion(+ self,+ text: Any = None,+ tool_calls: Any = None,+ reasoning: Any = None,+ ) -> "MagicMock":+ """Build a minimal ChatCompletion mock."""+ msg = MagicMock()+ msg.content = text+ msg.tool_calls = None+ setattr(msg, "reasoning_content", reasoning)+ setattr(msg, "reasoning", None)++ if tool_calls:+ tc_mocks = []+ for tc in tool_calls:+ m = MagicMock()+ m.id = tc["id"]+ m.function.name = tc["name"]+ m.function.arguments = tc["arguments"]+ tc_mocks.append(m)+ msg.tool_calls = tc_mocks++ choice = MagicMock()+ choice.message = msg+ choice.delta = msg++ resp = MagicMock()+ resp.id = "resp-1"+ resp.choices = [choice]+ resp.usage.prompt_tokens = 10+ resp.usage.completion_tokens = 5+ return resp++ def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_completion(text="Hello!")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(len(texts), 1)+ self.assertEqual(texts[0].text, "Hello!")++ def test_parse_tool_call_response(self) -> None:+ """Parsing a tool-call response creates a ToolCallBlock."""+ resp = self._mock_completion(+ tool_calls=[+ {+ "id": "call-1",+ "name": "get_weather",+ "arguments": '{"city":"Beijing"}',+ },+ ],+ )+ result = self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].id, "call-1")+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")++ def test_parse_thinking_response(self) -> None:+ """Parsing a response with reasoning creates a ThinkingBlock."""+ resp = self._mock_completion(+ text="Answer",+ reasoning="Let me think...",+ )+ result = self.model._parse_completion_response(self.start, resp)+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(len(thinkings), 1)+ self.assertEqual(thinkings[0].thinking, "Let me think...")++ def test_response_id_set(self) -> None:+ """The response ID from the API is stored in the ChatResponse."""+ resp = self._mock_completion(text="Hi")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertEqual(result.id, "resp-1")diff --git a/tests/model_openai_response_test.py b/tests/model_openai_response_test.pynew file mode 100644index 000000000..fe6edfb66--- /dev/null+++ b/tests/model_openai_response_test.py@@ -0,0 +1,138 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for OpenAIResponseModel response parsing.++Formatter tests have been moved to tests/formatter_openai_response_test.py.+"""+import json+from typing import Any+from datetime import datetime+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock+from agentscope.model import OpenAIResponseModel+from agentscope.credential import OpenAICredential+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return OpenAIResponseModel(+ credential=OpenAICredential(api_key="test"),+ model="o4-mini",+ stream=False,+ context_size=200_000,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestOpenAIResponseModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for OpenAIResponseModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_response(+ self,+ text: Any = None,+ function_calls: Any = None,+ reasoning_summary: Any = None,+ reasoning_id: str = "rs_test123",+ ) -> "MagicMock":+ """Build a mock OpenAI Responses API response object."""+ output = []++ if reasoning_summary:+ reasoning_item = MagicMock()+ reasoning_item.type = "reasoning"+ reasoning_item.id = reasoning_id+ summary_mock = MagicMock()+ summary_mock.text = reasoning_summary+ reasoning_item.summary = [summary_mock]+ output.append(reasoning_item)++ if text:+ msg_item = MagicMock()+ msg_item.type = "message"+ part = MagicMock()+ part.type = "output_text"+ part.text = text+ msg_item.content = [part]+ output.append(msg_item)++ if function_calls:+ for fc in function_calls:+ fc_item = MagicMock()+ fc_item.type = "function_call"+ fc_item.id = fc["id"]+ fc_item.call_id = fc["call_id"]+ fc_item.name = fc["name"]+ fc_item.arguments = fc["arguments"]+ output.append(fc_item)++ resp = MagicMock()+ resp.id = "resp-openai-1"+ resp.output = output+ resp.usage.input_tokens = 10+ resp.usage.output_tokens = 5+ return resp++ def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_response(text="Hello!")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ def test_parse_tool_call_response(self) -> None:+ """Parsing a function_call response creates a ToolCallBlock."""+ resp = self._mock_response(+ function_calls=[+ {+ "id": "fc_abc123",+ "call_id": "call-1",+ "name": "get_weather",+ "arguments": '{"city":"Beijing"}',+ },+ ],+ )+ result = self.model._parse_completion_response(self.start, resp)+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].id, "fc_abc123")+ self.assertEqual(tcs[0].call_id, "call-1")+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")++ def test_parse_reasoning_response(self) -> None:+ """Parsing a reasoning item creates a ThinkingBlock with item id."""+ resp = self._mock_response(+ reasoning_summary="Thinking step...",+ text="Answer",+ reasoning_id="rs_abc999",+ )+ result = self.model._parse_completion_response(self.start, resp)+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(len(thinkings), 1)+ self.assertEqual(thinkings[0].thinking, "Thinking step...")+ self.assertEqual(+ getattr(thinkings[0], "reasoning_item_id", None),+ "rs_abc999",+ )++ def test_response_id_set(self) -> None:+ """The response ID from the API is stored in the ChatResponse."""+ resp = self._mock_response(text="Hi")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertEqual(result.id, "resp-openai-1")diff --git a/tests/model_xai_test.py b/tests/model_xai_test.pynew file mode 100644index 000000000..d3328ced4--- /dev/null+++ b/tests/model_xai_test.py@@ -0,0 +1,201 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Unit tests for XAIChatModel (xAI) response parsing.++Formatter tests have been moved to tests/formatter_xai_test.py.+"""+import json+import sys+from typing import Any+from datetime import datetime+from types import ModuleType+from unittest import IsolatedAsyncioTestCase+from unittest.mock import MagicMock++from agentscope.message import (+ TextBlock,+ ToolCallBlock,+ ThinkingBlock,+)+from agentscope.model import XAIChatModel+from agentscope.credential import XAICredential+++# ---------------------------------------------------------------------------+# Build a lightweight xai_sdk stub so tests run without the real package.+# ---------------------------------------------------------------------------+++def _build_xai_sdk_stub() -> None:+ """Register stub modules for xai_sdk so imports don't fail."""+ if "xai_sdk" in sys.modules:+ return++ # chat_pb2 stub -----------------------------------------------------------+ chat_pb2 = ModuleType("xai_sdk.chat.chat_pb2")++ class _EnumHelper:+ """Helper that makes .Value() return an integer."""++ _mapping = {+ "ROLE_ASSISTANT": 2,+ "TOOL_CALL_TYPE_CLIENT_SIDE_TOOL": 1,+ }++ def Value(self, name: str) -> int:+ """Return the integer value for the given enum name."""+ return self._mapping.get(name, 0)++ chat_pb2.MessageRole = _EnumHelper()+ chat_pb2.ToolCallType = _EnumHelper()++ class _RepeatedField(list):+ """Minimal repeated proto field that supports .add()."""++ def __init__(self, factory: Any) -> None:+ super().__init__()+ self._factory = factory++ def add(self) -> Any:+ """Add a new item using the factory and return it."""+ item = self._factory()+ self.append(item)+ return item++ class _FunctionSpec:+ name: str = ""+ arguments: str = ""++ class _ToolCallProto:+ id: str = ""+ type: int = 0+ function = _FunctionSpec()++ class _ContentPart:+ text: str = ""++ class _MessageProto:+ def __init__(self) -> None:+ self.role = 0+ self.content = _RepeatedField(_ContentPart)+ self.tool_calls = _RepeatedField(_ToolCallProto)++ chat_pb2.Message = _MessageProto++ # xai_sdk.chat stub -------------------------------------------------------+ xai_chat = ModuleType("xai_sdk.chat")+ xai_chat.chat_pb2 = chat_pb2+ xai_chat.user = lambda *args: MagicMock(role="user", args=args)+ xai_chat.assistant = lambda *args: MagicMock(role="assistant", args=args)+ xai_chat.system = lambda *args: MagicMock(role="system", args=args)+ xai_chat.tool_result = lambda *args, **kw: MagicMock(+ role="tool",+ args=args,+ kwargs=kw,+ )+ xai_chat.image = lambda url: MagicMock(type="image", url=url)++ # xai_sdk stub ------------------------------------------------------------+ xai_sdk = ModuleType("xai_sdk")+ xai_sdk.chat = xai_chat+ xai_sdk.AsyncClient = MagicMock()++ sys.modules["xai_sdk"] = xai_sdk+ sys.modules["xai_sdk.chat"] = xai_chat+ sys.modules["xai_sdk.chat.chat_pb2"] = chat_pb2+++_build_xai_sdk_stub()++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_model() -> Any:+ return XAIChatModel(+ credential=XAICredential(api_key="test"),+ model="grok-3",+ stream=False,+ context_size=131_072,+ )+++# ---------------------------------------------------------------------------+# Model response parsing tests+# ---------------------------------------------------------------------------+++class TestXAIModelParsing(IsolatedAsyncioTestCase):+ """Unit tests for XAIChatModel response parsing."""++ def setUp(self) -> None:+ """Set up a fresh model instance and start time."""+ self.model = _make_model()+ self.start = datetime.now()++ def _mock_response(+ self,+ text: Any = None,+ tool_calls: Any = None,+ reasoning: Any = None,+ ) -> "MagicMock":+ """Build a mock xAI API response object."""+ resp = MagicMock()+ resp.id = "xai-resp-1"+ resp.content = text or ""+ resp.reasoning_content = reasoning or ""+ resp.tool_calls = None+ resp.usage = None++ if tool_calls:+ tc_mocks = []+ for tc in tool_calls:+ m = MagicMock()+ m.id = tc["id"]+ m.function.name = tc["name"]+ m.function.arguments = tc["arguments"]+ tc_mocks.append(m)+ resp.tool_calls = tc_mocks++ return resp++ def test_parse_text_response(self) -> None:+ """Parsing a text response creates a TextBlock."""+ resp = self._mock_response(text="Hello!")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertTrue(result.is_last)+ texts = [b for b in result.content if isinstance(b, TextBlock)]+ self.assertEqual(texts[0].text, "Hello!")++ def test_parse_tool_call_response(self) -> None:+ """Parsing a tool call response creates a ToolCallBlock."""+ resp = self._mock_response(+ tool_calls=[+ {+ "id": "call-1",+ "name": "get_weather",+ "arguments": '{"city":"Beijing"}',+ },+ ],+ )+ result = self.model._parse_completion_response(self.start, resp)+ tcs = [b for b in result.content if isinstance(b, ToolCallBlock)]+ self.assertEqual(len(tcs), 1)+ self.assertEqual(tcs[0].id, "call-1")+ self.assertEqual(tcs[0].name, "get_weather")+ self.assertEqual(json.loads(tcs[0].input)["city"], "Beijing")++ def test_parse_thinking_response(self) -> None:+ """Parsing a response with reasoning creates a ThinkingBlock."""+ resp = self._mock_response(text="Answer", reasoning="Let me think...")+ result = self.model._parse_completion_response(self.start, resp)+ thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]+ self.assertEqual(len(thinkings), 1)+ self.assertEqual(thinkings[0].thinking, "Let me think...")++ def test_response_id_set(self) -> None:+ """The response ID from the API is stored in the ChatResponse."""+ resp = self._mock_response(text="Hi")+ result = self.model._parse_completion_response(self.start, resp)+ self.assertEqual(result.id, "xai-resp-1")diff --git a/tests/utils.py b/tests/utils.pyindex 90fada666..dc8356cee 100644--- a/tests/utils.py+++ b/tests/utils.py@@ -4,10 +4,8 @@ from typing import Any, AsyncGenerator, Typefrom pydantic import BaseModel-from agentscope.formatter import DashScopeChatFormatterfrom agentscope.message import Msg-from agentscope.model import ChatModelBase, ChatResponse-from agentscope.model._model_response import StructuredResponse+from agentscope.model import ChatModelBase, ChatResponse, StructuredResponseclass AnyString:@@ -25,18 +23,20 @@ class AnyString:class MockModel(ChatModelBase):"""A mock model for testing."""- def __init__(self, context_length: int = 10000) -> None:+ def __init__(+ self,+ model: str = "mock-model",+ context_size: int = 1000,+ mock_chat_responses: list | None = None,+ mock_structured_response: Any = None,+ ) -> None:"""Initialize the mock model."""super().__init__(- model_name="mock-model",- stream=True,- context_length=context_length,- max_retries=0,- fallback_model_name=None,- formatter=DashScopeChatFormatter(),+ model=model,+ context_size=context_size,)- self.mock_chat_responses = []- self.mock_structured_response = None+ self.mock_chat_responses = mock_chat_responses or []+ self.mock_structured_response = mock_structured_responseself.cnt = 0def set_responses(