adachsoft / ai-integration-moonshot
Moonshot provider for adachsoft/ai-integration tool-calling API
Package info
gitlab.com/a.adach/ai-integration-moonshot
pkg:composer/adachsoft/ai-integration-moonshot
Requires
- php: ^8.3
- adachsoft/ai-conversation-model: ^0.2
- adachsoft/ai-integration: ^0.10
- adachsoft/model-pricing-contracts: ^0.3 || ^0.4.0
Requires (Dev)
- adachsoft/ai-integration-tester: ^0.5.1
- adachsoft/php-code-style: ^0.7
- friendsofphp/php-cs-fixer: ^3.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^13.0
- rector/rector: ^2.3
- symplify/phpstan-rules: ^14.9
- vlucas/phpdotenv: ^5.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Moonshot provider for the adachsoft/ai-integration tool-calling API.
Requirements
- PHP
^8.3 adachsoft/ai-integration^0.10adachsoft/ai-conversation-model^0.2adachsoft/model-pricing-contracts^0.3
Installation
composer require adachsoft/ai-integration-moonshot
Usage
Use MoonshotProvider::register() to configure the Moonshot provider on the shared tool-calling facade builder.
Registration
MoonshotProvider::register() registers Moonshot on the shared tool-calling facade builder. It uses the shared OpenAI-compatible tool-calling SPI and Moonshot's chat-completions endpoint by default.
use AdachSoft\AiIntegration\PublicApi\Builder\ToolCallingChatFacadeBuilder;
use AdachSoft\AiIntegrationMoonshot\MoonshotProvider;
$apiKey = getenv('MOONSHOT_API_KEY');
if (!is_string($apiKey) || $apiKey === '') {
throw new RuntimeException('Set the MOONSHOT_API_KEY environment variable.');
}
$builder = MoonshotProvider::register(ToolCallingChatFacadeBuilder::create(), $apiKey);
$facade = $builder->build();
If you compose the SPI directly, use MoonshotToolCallingChatSpiFactory::create($apiKey, $baseUri = null). The optional base URI can replace the default endpoint.
Cost
MoonshotUsageNormalizer implements UsageNormalizerInterface from adachsoft/model-pricing-contracts. Pass it a UsageNormalizationRequestDto populated from the Chat Completions usage and response metadata. It separates uncached input tokens from cached_tokens, reports cache_write_tokens as cache_write_5m, and maps completion_tokens to output tokens without adding reasoning_tokens again. The context input count remains equal to prompt_tokens.
A missing service_tier or the value default maps to standard; other reported tiers are preserved. Kimi defaults cache writes to a 5-minute TTL when none is specified. Since this library does not set a cache-write TTL, positive cache-write usage is reported as cache_write_5m without a warning.
Reasoning content
For thinking models, the response choice stores provider-specific assistant fields in ChatChoiceDto::$metadata['openai_compatible_message_fields']. Read reasoning_content from that metadata and preserve the choice metadata on the assistant message when carrying the conversation into a subsequent request. The provider round-trips the value unchanged. With thinking disabled, Moonshot may return an empty reasoning_content value.
Images and other media
Moonshot accepts supported base64 user images (image/jpeg, image/png, image/gif, and image/webp) and user image file IDs. Represent a file ID with MediaSourceEnum::FileId; the provider encodes it as ms://<file_id> in the request.
URL-backed media, PDFs, audio, and other unsupported media are rejected with UnsupportedContentException before an HTTP request is sent. A Developer message is sent to Moonshot with the system role.
Tests
The default PHPUnit suite is unit and does not call the paid Moonshot API:
vendor/bin/phpunit
The separate production suite sends requests to the real API and may incur charges. Set MOONSHOT_API_KEY before running it; MOONSHOT_CONFORMANCE_MODEL optionally overrides the default model kimi-k2.6.
vendor/bin/phpunit --testsuite production
The conformance profile uses adachsoft/ai-integration-tester ^0.5.1. Its adaptParameters() method sets temperature to 1.0 for Kimi K2.6 while retaining the other supported generation parameters.
Migrating from 1.0.x
This is a breaking change. The integration now uses adachsoft/ai-integration ^0.10 and the shared DTOs from adachsoft/ai-conversation-model ^0.2 instead of the 0.8-era integration types. Update imports and message construction to use the shared model.
The provider-specific MoonshotToolCallingChatSpi, MoonshotPayloadBuilder, and MoonshotResponseParser classes have been removed. Register the provider through MoonshotProvider::register() or create the shared SPI directly with MoonshotToolCallingChatSpiFactory::create().