feat(models): add Kimi (Moonshot AI) adaptation with dedicated provider and formatters

[Leeaoyin]

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

Fiexs #2213
This PR adds first-class Kimi (Moonshot AI) support on top of the OpenAI-compatible extension module, adapted to the latest official Kimi open platform documentation (kimi-k3 / kimi-k2.7-code / kimi-k2.6 / kimi-k2.5 / moonshot-v1 series).

New implementations (io.agentscope.extensions.model.openai.compat.kimi)

• KimiFormatter — extends OpenAIChatFormatter with Kimi-specific request adaptations. Unlike other vendors, Kimi's constraints differ per model series, so the sanitization is model-aware:
  • temperature / top_p / frequency_penalty / presence_penalty are fixed by the platform on kimi-* models (the API rejects other values) and are stripped from requests; they are passed through for the moonshot-v1 series, which still accepts them.
  • reasoning_effort (low / high / max) is only supported by kimi-k3 and stripped on other models; thinking_budget is not a Kimi parameter and always stripped (K2.x thinking is controlled via the thinking body param instead).
  • Only max_tokens is documented: max_completion_tokens (newer OpenAI style) is mapped onto it.
  • tool_choice matrix per the official guide: auto / none pass through everywhere; required is kimi-k3-only and degraded to auto on the K2.x series; forcing a specific function is incompatible with thinking enabled (HTTP 400), so it is degraded to auto on always-thinking models (kimi-k3, kimi-k2.7-code) and passed through otherwise.
  • The strict parameter in tool definitions is not sent (not documented by Kimi).
  • Assistant reasoning_content is preserved in the request history, satisfying Preserved Thinking on kimi-k3 / kimi-k2.7-code and thinking.keep = "all" on kimi-k2.6.
• KimiMultiAgentFormatter — extends OpenAIMultiAgentFormatter, reusing the same Kimi-specific sanitization and tool-choice handling.
• KimiModelProvider — resolves kimi:<model> ids through ModelRegistry (Java SPI). Creates OpenAIChatModel instances preconfigured with:
  • base URL https://api.moonshot.cn/v1 (consistent with KimiCredential.DEFAULT_BASE_URL);
  • API key from ModelCreationContext, then MOONSHOT_API_KEY, then KIMI_API_KEY;
  • KimiFormatter as the default formatter (a custom Formatter component takes precedence);
  • nativeStructuredOutput disabled by default (Kimi response_format only supports json_object, agents fall back to the generate_response tool) and nativeStructuredOutputWithTools disabled by default (Kimi prioritises response_format over tool invocations); both re-enablable via context options.

Other changes

• SPI registration for KimiModelProvider in META-INF/services/io.agentscope.core.model.spi.ModelProvider.
• OpenAIChatModel javadoc now lists KimiFormatter among provider-specific formatters.

Tests

• KimiFormatterTest (27 cases): model classification helpers, fixed-sampling-param stripping vs moonshot-v1 pass-through, reasoning_effort handling, max_completion_tokens mapping, thinking body-param pass-through, the full tool_choice degradation matrix, and reasoning_content preservation in formatted history.
• KimiMultiAgentFormatterTest (8 cases): multi-agent merging plus shared sanitization behavior.
• KimiModelProviderTest (8 cases): provider id / supports / creation with ModelCreationContext, structured-output defaults and overrides, ServiceLoader resolution via ModelRegistry.
• Verified locally: mvn spotless:check passes; module tests (422) and the full-repository mvn test all pass.

Documentation

• docs/v2/{zh,en}/integration/model/openai.md: new "Kimi (Moonshot AI)" section with kimi:<model> and explicit-builder examples, the full list of request adaptations, and thinking-related parameter usage (thinking body param for K2.x, reasoning_effort for kimi-k3, Preserved Thinking notes).
• docs/v2/{zh,en}/docs/building-blocks/model.md: environment variable list now includes MOONSHOT_API_KEY.

References

• https://platform.kimi.com/docs/api/overview
• https://platform.kimi.com/docs/api/models-overview
• https://platform.kimi.com/docs/guide/use-kimi-k2-thinking-model
• https://platform.kimi.com/docs/guide/use-thinking-effort
• https://platform.kimi.com/docs/guide/use-kimi-api-to-complete-tool-calls
• https://platform.kimi.com/docs/guide/use-json-mode-feature-of-kimi-api
• https://platform.kimi.com/docs/guide/use-tool-choice

Checklist

• Code is formatted with mvn spotless:apply
• All new functionality is covered by unit tests
• Existing tests pass (mvn test)
• Documentation updated (zh + en)

[Copilot]

Pull request overview

This PR adds first-class support for Kimi (Moonshot AI) on top of the existing OpenAI-compatible model extension by introducing Kimi-specific formatters and a dedicated ModelProvider (SPI-registered), along with docs and unit tests.

Changes:

• Add KimiFormatter / KimiMultiAgentFormatter to apply Kimi model-series-specific request sanitization and tool-choice handling.
• Add KimiModelProvider to resolve kimi:<model> IDs via ModelRegistry and create preconfigured OpenAIChatModel instances (Kimi base URL, env-var API key fallback, structured output defaults).
• Add docs (EN/ZH) and comprehensive unit tests for formatter behavior and provider resolution.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/v2/zh/integration/model/openai.md	Document Kimi usage (kimi:<model>) and Kimi-specific request adaptations (ZH).
docs/v2/zh/docs/building-blocks/model.md	Add MOONSHOT_API_KEY to environment variable list (ZH).
docs/v2/en/integration/model/openai.md	Document Kimi usage (kimi:<model>) and Kimi-specific request adaptations (EN).
docs/v2/en/docs/building-blocks/model.md	Add MOONSHOT_API_KEY to environment variable list (EN).
agentscope-extensions/.../KimiMultiAgentFormatterTest.java	Unit tests for multi-agent formatting + shared Kimi sanitization behavior.
agentscope-extensions/.../KimiModelProviderTest.java	Unit tests for provider ID/supports/create defaults and ServiceLoader resolution.
agentscope-extensions/.../KimiFormatterTest.java	Unit tests for Kimi request sanitization, tool_choice matrix, and preserved reasoning content.
agentscope-extensions/.../META-INF/services/io.agentscope.core.model.spi.ModelProvider	Register KimiModelProvider for SPI discovery.
agentscope-extensions/.../OpenAIChatModel.java	Extend Javadoc to mention KimiFormatter as a provider-specific formatter.
agentscope-extensions/.../KimiMultiAgentFormatter.java	New multi-agent Kimi formatter that reuses shared sanitization/tool-choice logic.
agentscope-extensions/.../KimiModelProvider.java	New ModelProvider for kimi:<model> IDs with Kimi defaults and option overrides.
agentscope-extensions/.../KimiFormatter.java	New Kimi-aware formatter implementing model-series-specific request sanitization and tool-choice behavior.

[codecov]

Codecov Report

❌ Patch coverage is 86.27451% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ns/model/openai/compat/kimi/KimiModelProvider.java	76.62%	8 Missing and 10 partials ⚠️
...nsions/model/openai/compat/kimi/KimiFormatter.java	95.45%	1 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!