Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(moonshot): support kimi k3.1 pro variants (#3578)
YingchaoX32fe303c7152
diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.pyindex d77d55e20..03c35c8a7 100644--- a/src/agentscope/model/_moonshot/_model.py+++ b/src/agentscope/model/_moonshot/_model.py@@ -22,9 +22,20 @@ else:ChatCompletion = AnyAsyncStream = Any+_K3_MODELS = {"kimi-k3", "kimi-k3.1-pro", "kimi-k3.1-pro-highspeed"}+class MoonshotChatModel(ChatModelBase):- """The Moonshot AI chat model."""+ """The Moonshot AI chat model.++ For the Kimi K3 series, thinking is always enabled. Fixed+ sampling parameters (``temperature``, ``top_p``, ``n``,+ ``presence_penalty``, ``frequency_penalty``) and ``thinking`` are+ omitted, including values supplied through ``extra_body``. Call-level+ reasoning and token budgets override :class:`Parameters`. Token budgets+ in ``extra_body`` override top-level budgets; within each level,+ ``max_completion_tokens`` takes precedence over ``max_tokens``.+ """class Parameters(BaseModel):"""The parameters for the Moonshot AI chat model."""@@ -32,7 +43,10 @@ class MoonshotChatModel(ChatModelBase):max_tokens: int | None = Field(default=None,title="Max Tokens",- description="The maximum number of tokens for the LLM output.",+ description=(+ "The maximum number of tokens for the LLM output. "+ "Sent as max_completion_tokens for Kimi K3 and K3.1 Pro."+ ),gt=0,)@@ -44,7 +58,8 @@ class MoonshotChatModel(ChatModelBase):"thinking is always enabled. For kimi-k2.6, thinking is ""enabled by default but can be disabled. When None, no ""``thinking`` option is sent and the model's default "- "behavior applies."+ "behavior applies. "+ "Ignored for the Kimi K3 series, which always thinks."),)@@ -52,7 +67,7 @@ class MoonshotChatModel(ChatModelBase):default=None,title="Reasoning Effort",description=(- "The reasoning effort level for kimi-k3. "+ "The reasoning effort level for Kimi K3 and K3.1 Pro. ""Supports 'low', 'high', and 'max' ""(default 'max')."),@@ -95,7 +110,8 @@ class MoonshotChatModel(ChatModelBase):credential (`MoonshotCredential`):The Moonshot AI credential used to authenticate API calls.model (`str`):- The model name, e.g. ``moonshot-v1-8k``, ``kimi-k2.6``.+ The model name, e.g. ``moonshot-v1-8k``, ``kimi-k3.1-pro``,+ or ``kimi-k3.1-pro-highspeed``.parameters (`MoonshotChatModel.Parameters | None`, defaults to \`None`):The API parameters. When ``None``, the default parameters@@ -191,13 +207,10 @@ class MoonshotChatModel(ChatModelBase):"stream": self.stream,}- is_k3 = model_name == "kimi-k3"+ is_k3 = model_name in _K3_MODELSif self.parameters.max_tokens is not None:- if is_k3:- kwargs["max_completion_tokens"] = self.parameters.max_tokens- else:- kwargs["max_tokens"] = self.parameters.max_tokens+ kwargs["max_tokens"] = self.parameters.max_tokensif self.parameters.temperature is not None:kwargs["temperature"] = self.parameters.temperature@@ -205,12 +218,12 @@ class MoonshotChatModel(ChatModelBase):if self.parameters.top_p is not None:kwargs["top_p"] = self.parameters.top_p+ if is_k3 and self.parameters.reasoning_effort is not None:+ kwargs["reasoning_effort"] = self.parameters.reasoning_effort+kwargs.update(generate_kwargs)- if is_k3:- if self.parameters.reasoning_effort is not None:- kwargs["reasoning_effort"] = self.parameters.reasoning_effort- elif self.parameters.thinking_enable is not None:+ if not is_k3 and self.parameters.thinking_enable is not None:thinking_type = ("enabled" if self.parameters.thinking_enable else "disabled")@@ -224,6 +237,37 @@ class MoonshotChatModel(ChatModelBase):},}+ if is_k3:+ if "max_tokens" in kwargs:+ kwargs.setdefault(+ "max_completion_tokens",+ kwargs.pop("max_tokens"),+ )+ # The API fixes these settings. Copy extra_body before filtering+ # so SDK-level overrides cannot reintroduce them or mutate input.+ omitted = {+ "temperature",+ "top_p",+ "n",+ "presence_penalty",+ "frequency_penalty",+ "thinking",+ }+ for key in omitted:+ kwargs.pop(key, None)+ if isinstance(kwargs.get("extra_body"), dict):+ kwargs["extra_body"] = {+ key: value+ for key, value in kwargs["extra_body"].items()+ if key not in omitted+ }+ extra_body = kwargs["extra_body"]+ if "max_tokens" in extra_body:+ extra_body.setdefault(+ "max_completion_tokens",+ extra_body.pop("max_tokens"),+ )+fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)if fmt_tools:@@ -428,8 +472,9 @@ class MoonshotChatModel(ChatModelBase):When ``tool_choice.tools`` is specified the schemas list is filteredto only those tools. When ``tool_choice.mode`` is a specific tool name- (str) the model is forced to call exactly that tool without needing to- filter the list, preserving prompt-cache efficiency.+ (str), K3 models receive only that tool with ``required`` because+ named tool choice is incompatible with always-on thinking. Other+ models receive a named tool choice without filtering the list.Args:tools (`list[dict] | None`, optional):@@ -453,12 +498,18 @@ class MoonshotChatModel(ChatModelBase):mode = tool_choice.modeif mode not in _TOOL_CHOICE_LITERAL_MODES:+ if self.model in _K3_MODELS and tools:+ return [+ tool for tool in tools if tool["function"]["name"] == mode+ ], "required"return tools, {"type": "function", "function": {"name": mode}}return tools, modedef _get_disable_thinking_kwargs(self) -> dict:- """Moonshot uses ``thinking.type=disabled`` in extra_body."""+ """Skip the disable-thinking fallback for the K3 series."""+ if self.model in _K3_MODELS:+ return {}return {"extra_body": {"thinking": {"type": "disabled"}},}diff --git a/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro-highspeed.yaml b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro-highspeed.yamlnew file mode 100644index 000000000..7881429a7--- /dev/null+++ b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro-highspeed.yaml@@ -0,0 +1,33 @@+name: kimi-k3.1-pro-highspeed+label: Kimi K3.1 Pro Highspeed+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: 1048576+output_size: 1048576++parameter_overrides:+ max_tokens:+ maximum: 1048576+ thinking_enable:+ hidden: true+ temperature:+ hidden: true+ top_p:+ hidden: truediff --git a/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro.yaml b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro.yamlnew file mode 100644index 000000000..6c8fd9efb--- /dev/null+++ b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro.yaml@@ -0,0 +1,33 @@+name: kimi-k3.1-pro+label: Kimi K3.1 Pro+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: 1048576+output_size: 1048576++parameter_overrides:+ max_tokens:+ maximum: 1048576+ thinking_enable:+ hidden: true+ temperature:+ hidden: true+ top_p:+ hidden: truediff --git a/src/agentscope/model/_moonshot/_models/kimi-k3.yaml b/src/agentscope/model/_moonshot/_models/kimi-k3.yamlindex 71dd5cf1f..3c85cc874 100644--- a/src/agentscope/model/_moonshot/_models/kimi-k3.yaml+++ b/src/agentscope/model/_moonshot/_models/kimi-k3.yaml@@ -27,3 +27,7 @@ parameter_overrides:maximum: 1048576thinking_enable:hidden: true+ temperature:+ hidden: true+ top_p:+ hidden: truediff --git a/tests/model_moonshot_test.py b/tests/model_moonshot_test.pyindex 57208061b..a508efb95 100644--- a/tests/model_moonshot_test.py+++ b/tests/model_moonshot_test.py@@ -4,19 +4,26 @@Tests cover both non-streaming and streaming modes."""+from copy import deepcopy+from dataclasses import asdict+import jsonfrom typing import Anyimport unittestfrom unittest import IsolatedAsyncioTestCase-from unittest.mock import AsyncMock, MagicMock+from unittest.mock import AsyncMock, MagicMock, call++import httpxfrom utils import AnyString-from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock-from agentscope.model import MoonshotChatModel+from agentscope.exception import StructuredOutputError+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock, UserMsg+from agentscope.model import MoonshotChatModel, StructuredResponsefrom agentscope.credential import MoonshotCredentialfrom agentscope.tool import ToolChoiceA = AnyString()+_K3_MODELS = ("kimi-k3", "kimi-k3.1-pro", "kimi-k3.1-pro-highspeed")# ---------------------------------------------------------------------------@@ -690,3 +697,505 @@ class TestMoonshotFormatTools(unittest.TestCase):fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)self.assertEqual(fmt_tools, _FT_TOOLS)self.assertIsNone(fmt_choice)+++class MoonshotK3Test(IsolatedAsyncioTestCase):+ """Verify the shared request contract for the K3 series."""++ async def test_request_parameters(self) -> None:+ """Translate budgets, preserve overrides, and omit fixed settings."""+ cases: list[tuple[dict[str, Any], dict[str, Any], dict[str, Any]]] = [+ ({}, {}, {}),+ ({"max_tokens": 1024}, {}, {"max_completion_tokens": 1024}),+ (+ {"max_tokens": 1024},+ {"max_tokens": 2048},+ {"max_completion_tokens": 2048},+ ),+ (+ {"max_tokens": 1024},+ {"max_completion_tokens": 4096},+ {"max_completion_tokens": 4096},+ ),+ (+ {"max_tokens": 1024},+ {"max_tokens": 2048, "max_completion_tokens": 4096},+ {"max_completion_tokens": 4096},+ ),+ (+ {},+ {"max_tokens": 1048576},+ {"max_completion_tokens": 1048576},+ ),+ (+ {+ "temperature": 0.2,+ "top_p": 0.4,+ "thinking_enable": False,+ },+ {},+ {},+ ),+ ({"thinking_enable": True}, {}, {}),+ (+ {},+ {+ "temperature": 1.0,+ "top_p": 0.95,+ "n": 1,+ "presence_penalty": 0,+ "frequency_penalty": 0,+ },+ {},+ ),+ (+ {},+ {+ "temperature": 0.2,+ "top_p": 0.4,+ "n": 2,+ "presence_penalty": 1,+ "frequency_penalty": 1,+ "thinking": {"type": "disabled"},+ },+ {},+ ),+ (+ {},+ {+ "extra_body": {+ "temperature": 0.2,+ "top_p": 0.4,+ "n": 2,+ "presence_penalty": 1,+ "frequency_penalty": 1,+ "thinking": {"type": "disabled"},+ "prompt_cache_options": {"ttl": "1h"},+ },+ },+ {"extra_body": {"prompt_cache_options": {"ttl": "1h"}}},+ ),+ ]+ for effort in ("low", "high", "max"):+ cases.extend(+ [+ (+ {"reasoning_effort": effort},+ {},+ {"reasoning_effort": effort},+ ),+ (+ {"reasoning_effort": "max"},+ {"reasoning_effort": effort},+ {"reasoning_effort": effort},+ ),+ ],+ )+ for name in _K3_MODELS:+ model = _make_model()+ model.model = name+ create = AsyncMock(return_value=_mock_completion(text="OK"))+ model.client.chat.completions.create = create+ for parameters, kwargs, expected in cases:+ with self.subTest(+ model=name,+ parameters=parameters,+ kwargs=kwargs,+ ):+ model.parameters = MoonshotChatModel.Parameters(+ **parameters,+ )+ original = deepcopy(kwargs)+ await model([], **kwargs)+ self.assertDictEqual(+ create.call_args.kwargs,+ {+ "model": name,+ "messages": [],+ "stream": False,+ **expected,+ },+ )+ self.assertDictEqual(kwargs, original)+ await model.client.close()++ async def test_extra_body_budget_http_request(self) -> None:+ """Normalize budgets before the SDK merges the final HTTP body."""+ cases: list[+ tuple[int | None, dict[str, int], dict[str, int], dict[str, int]]+ ] = [+ (None, {}, {}, {}),+ (None, {}, {"max_tokens": 2048}, {"max_completion_tokens": 2048}),+ (1024, {}, {}, {"max_completion_tokens": 1024}),+ (1024, {}, {"max_tokens": 2048}, {"max_completion_tokens": 2048}),+ (+ 1024,+ {},+ {"max_completion_tokens": 2048},+ {"max_completion_tokens": 2048},+ ),+ (+ 1024,+ {"max_tokens": 4096},+ {"max_tokens": 2048},+ {"max_completion_tokens": 2048},+ ),+ (+ 1024,+ {"max_completion_tokens": 4096},+ {"max_tokens": 2048},+ {"max_completion_tokens": 2048},+ ),+ (+ 1024,+ {"max_tokens": 4096, "max_completion_tokens": 8192},+ {"max_tokens": 2048, "max_completion_tokens": 3072},+ {"max_completion_tokens": 3072},+ ),+ ]+ bodies: list[dict] = []++ def handle(request: httpx.Request) -> httpx.Response:+ body = json.loads(request.content)+ bodies.append(body)+ if body["stream"]:+ return httpx.Response(+ 200,+ headers={"content-type": "text/event-stream"},+ text="data: [DONE]\n\n",+ )+ return httpx.Response(+ 200,+ json={+ "id": "kimi-1",+ "created": 0,+ "model": body["model"],+ "object": "chat.completion",+ "choices": [+ {+ "index": 0,+ "finish_reason": "stop",+ "message": {"role": "assistant", "content": "OK"},+ },+ ],+ },+ )++ for name in _K3_MODELS:+ for stream in (False, True):+ model = MoonshotChatModel(+ credential=MoonshotCredential(api_key="test"),+ model=name,+ stream=stream,+ client_kwargs={+ "http_client": httpx.AsyncClient(+ transport=httpx.MockTransport(handle),+ ),+ },+ )+ self.addAsyncCleanup(model.client.close)+ for budget, kwargs, extra_budget, expected in cases:+ with self.subTest(+ model=name,+ stream=stream,+ budget=budget,+ kwargs=kwargs,+ extra_budget=extra_budget,+ ):+ model.parameters = MoonshotChatModel.Parameters(+ max_tokens=budget,+ )+ extra_body = {+ **extra_budget,+ "prompt_cache_options": {"ttl": "1h"},+ "temperature": 0.2,+ "thinking": {"type": "disabled"},+ }+ original = deepcopy(extra_body)+ bodies.clear()+ response = await model(+ [],+ extra_body=extra_body,+ **kwargs,+ )+ if stream:+ async for _ in response:+ pass+ self.assertEqual(+ bodies,+ [+ {+ "model": name,+ "messages": [],+ "stream": stream,+ "prompt_cache_options": {"ttl": "1h"},+ **expected,+ **(+ {+ "stream_options": {+ "include_usage": True,+ },+ }+ if stream+ else {}+ ),+ },+ ],+ )+ self.assertEqual(extra_body, original)++ async def test_legacy_request_parameters(self) -> None:+ """Existing models keep their sampling and thinking behavior."""+ for name in (+ "kimi-k2.6",+ "kimi-k2.7-code",+ "kimi-k2.7-code-highspeed",+ "moonshot-v1-8k",+ ):+ with self.subTest(model=name):+ model = _make_model()+ model.model = name+ model.parameters = MoonshotChatModel.Parameters(+ max_tokens=1024,+ reasoning_effort="high",+ temperature=0.2,+ top_p=0.4,+ )+ create = AsyncMock(return_value=_mock_completion(text="OK"))+ model.client.chat.completions.create = create+ await model([])+ expected = {+ "model": name,+ "messages": [],+ "stream": False,+ "temperature": 0.2,+ "top_p": 0.4,+ "max_tokens": 1024,+ }+ self.assertDictEqual(create.call_args.kwargs, expected)+ self.assertDictEqual(+ model._get_disable_thinking_kwargs(),+ {+ "extra_body": {+ "thinking": {"type": "disabled"},+ },+ },+ )+ await model.client.close()++ async def test_structured_output_skips_disable_thinking(self) -> None:+ """The real fallback ladder must not attempt to turn thinking off."""+ for name in _K3_MODELS:+ with self.subTest(model=name):+ model = _make_model()+ model.model = name+ messages = [UserMsg("user", "Return an answer")]+ schema = {"type": "object"}+ attempt = AsyncMock(+ side_effect=[+ StructuredOutputError("try auto"),+ StructuredOutputError("try unforced"),+ StructuredResponse(content={"answer": 42}),+ ],+ )+ model._call_api_with_structured_output = attempt+ result = await model.generate_structured_output(+ messages,+ schema,+ )+ self.assertDictEqual(+ asdict(result),+ {+ "content": {"answer": 42},+ "usage": None,+ "id": AnyString(),+ "created_at": AnyString(),+ "type": "structured_response",+ "metadata": {},+ "finished_reason": "completed",+ },+ )+ self.assertListEqual(+ attempt.call_args_list,+ [+ call(+ name,+ messages=messages,+ structured_model=schema,+ tool_choice=ToolChoice(+ mode="generate_structured_output",+ ),+ ),+ call(+ name,+ messages=messages,+ structured_model=schema,+ tool_choice=ToolChoice(mode="auto"),+ ),+ call(+ name,+ messages=messages,+ structured_model=schema,+ tool_choice=None,+ ),+ ],+ )+ await model.client.close()++ async def test_named_tool_request(self) -> None:+ """Force only the selected tool without mutating caller schemas."""+ for name in _K3_MODELS:+ with self.subTest(model=name):+ model = _make_model()+ self.addAsyncCleanup(model.client.close)+ model.model = name+ create = AsyncMock(return_value=_mock_completion(text="OK"))+ model.client.chat.completions.create = create+ tools = deepcopy(_FT_TOOLS)+ await model(+ [],+ tools=tools,+ tool_choice=ToolChoice(mode="get_weather"),+ )+ self.assertDictEqual(+ create.call_args.kwargs,+ {+ "model": name,+ "messages": [],+ "stream": False,+ "tools": [_FT_TOOLS[0]],+ "tool_choice": "required",+ },+ )+ self.assertEqual(tools, _FT_TOOLS)++ async def test_structured_output_uses_required(self) -> None:+ """Generate structured output on the first API request."""+ schema = {+ "type": "object",+ "properties": {"answer": {"type": "integer"}},+ "required": ["answer"],+ }+ for name in _K3_MODELS:+ with self.subTest(model=name):+ model = _make_model()+ self.addAsyncCleanup(model.client.close)+ model.model = name+ create = AsyncMock(+ return_value=_mock_completion(+ tool_calls=[+ {+ "id": "call-1",+ "name": "generate_structured_output",+ "arguments": '{"answer": 42}',+ },+ ],+ ),+ )+ model.client.chat.completions.create = create+ result = await model.generate_structured_output(+ [UserMsg("user", "Return an answer")],+ schema,+ )+ self.assertEqual(result.content, {"answer": 42})+ create.assert_awaited_once()+ self.assertEqual(+ (+ create.call_args.kwargs["tool_choice"],+ create.call_args.kwargs["tools"],+ ),+ (+ "required",+ [+ {+ "type": "function",+ "function": {+ "name": "generate_structured_output",+ "description": "Call this function to "+ "generate structured output required "+ "by the user.",+ "parameters": schema,+ },+ },+ ],+ ),+ )++ def test_model_cards(self) -> None:+ """All K3 models expose consistent capabilities and parameters."""+ cards = {card.name: card for card in MoonshotChatModel.list_models()}+ labels = {+ "kimi-k3": "Kimi K3",+ "kimi-k3.1-pro": "Kimi K3.1 Pro",+ "kimi-k3.1-pro-highspeed": "Kimi K3.1 Pro Highspeed",+ }+ for name in _K3_MODELS:+ with self.subTest(model=name):+ self.assertIn(name, cards)+ self.assertDictEqual(+ cards[name].model_dump(),+ {+ "type": "chat_model",+ "model_class": "moonshot_chat",+ "name": name,+ "label": labels[name],+ "status": "active",+ "deprecated_at": None,+ "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": 1048576,+ "output_size": 1048576,+ "parameters_overrides": {+ "max_tokens": {"maximum": 1048576},+ "thinking_enable": {"hidden": True},+ "temperature": {"hidden": True},+ "top_p": {"hidden": True},+ },+ "parameter_schema": {+ "type": "object",+ "required": [],+ "properties": {+ "max_tokens": {+ "anyOf": [+ {+ "exclusiveMinimum": 0,+ "type": "integer",+ },+ {"type": "null"},+ ],+ "default": None,+ "title": "Max Tokens",+ "description": AnyString(),+ "maximum": 1048576,+ },+ "reasoning_effort": {+ "anyOf": [+ {+ "enum": ["low", "high", "max"],+ "type": "string",+ },+ {"type": "null"},+ ],+ "default": None,+ "title": "Reasoning Effort",+ "description": AnyString(),+ },+ },+ },+ },+ )