README

This standalone Composer package integrates Z.AI Chat Completions with the shared adachsoft/ai-integration tool-calling SPI. It reuses the core HTTP transport, request payload builder, response parser, and domain DTOs.

Requirements and installation

PHP ^8.3
adachsoft/ai-integration ^0.8

Install the package in an application that already uses the core integration library:

composer require adachsoft/ai-integration-zai

The provider does not read environment variables, configuration files, or secret stores at runtime. Supply the API key explicitly when creating the provider.

Register the provider

Use the factory as the public creation point, then register the SPI through the existing facade builder:

use AdachSoft\AiIntegration\PublicApi\Builder\ToolCallingChatFacadeBuilder;
use AdachSoft\AiIntegrationZai\Factory\ZaiToolCallingChatSpiFactory;

$builder = ToolCallingChatFacadeBuilder::create()
    ->withSpiProvider('zai', ZaiToolCallingChatSpiFactory::create($apiKey));

$facade = $builder->build();

The factory uses https://api.z.ai/api/paas/v4/chat/completions by default. Pass a full Chat Completions endpoint URL as the optional second argument when a custom endpoint is required:

$spi = ZaiToolCallingChatSpiFactory::create($apiKey, $chatCompletionsEndpoint);

An empty API key is rejected. The key is passed unchanged to the shared HTTP transport and is not written to request bodies or application logs.

Models, tools, and parameters

Pass the model identifier and generation parameters through the existing core request API. The provider does not maintain a model allow-list or add provider-specific defaults to caller parameters. For example, Z.AI thinking can be enabled explicitly with:

$parameters = [
    'thinking' => [
        'type' => 'enabled',
        'clear_thinking' => false,
    ],
];

The same parameters are sent top-level in the Chat Completions request. Tool definitions, tool-call identifiers, arguments, results, message order, and token usage use the existing core contracts.

When a conversation is continued, preserve assistant message metadata from the response. If the response includes metadata['reasoning_content'], keep it on the corresponding assistant message in the next request. The provider sends this value as the assistant message's top-level reasoning_content field without trimming or changing its contents. It does not add this field to system, user, or tool messages. Missing or null reasoning content remains absent; an invalid non-string value is rejected.

The implementation accepts one response choice, as required by this provider contract. A missing, malformed, or multi-choice response is reported as an SPI error rather than silently discarding choices.

Error handling

For HTTP 429 responses, the provider recognizes the documented Z.AI business codes:

1113 maps to a resource-exhausted SPI exception.
1302 maps to a retriable SPI exception and preserves a numeric Retry-After delay; missing or invalid values use zero seconds.

Other error responses and unknown codes are delegated unchanged to the shared core classifier. See the Z.AI error-code reference and Chat Completion API.

Public and internal classes

AdachSoft\AiIntegrationZai\Factory\ZaiToolCallingChatSpiFactory is the package's public provider factory. The SPI implementation and Z.AI error classifier in AdachSoft\AiIntegrationZai\Infrastructure are internal implementation details; consumers should not instantiate them directly. Core request/response DTOs and collections are reused rather than duplicated.

Tests and static analysis

Unit tests use local transport doubles and do not make external requests:

composer test:unit
composer stan

Live provider conformance and preserved-thinking tests are in the separate integration suite and PHPUnit production group. Copy .env.example to .env, provide a valid ZAI_API_KEY, and optionally set ZAI_MODEL to override the integration-test model (default glm-5.3). The .env file is used only by tests and is ignored by Git.

Run the complete test scripts or the live suite explicitly:

composer test
composer test:integration
vendor/bin/phpunit --testsuite integration --group production

Without ZAI_API_KEY, live tests are marked skipped. A skipped test does not verify external API compatibility; run the suite with valid credentials to confirm real Z.AI behavior.

adachsoft / ai-integration-zai

Package info

Security

Statistics