adachsoft / ai-integration-xai
xAI SPI provider for adachsoft/ai-integration: tool-calling chat integration with Grok models (OpenAI-compatible endpoint).
Requires
- php: ^8.3
- adachsoft/ai-conversation-model: ^0.2
- adachsoft/ai-integration: ^0.10
- adachsoft/model-pricing-contracts: ^0.4
- guzzlehttp/guzzle: ^7.0
Requires (Dev)
- adachsoft/ai-integration-tester: ^0.5.2
- adachsoft/php-code-style: ^0.7.2
- friendsofphp/php-cs-fixer: ^3.94
- 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
This package is auto-updated.
Last update: 2026-11-16 19:47:26 UTC
README
adachsoft/ai-integration-xai connects xAI's Chat Completions API to adachsoft/ai-integration through its shared OpenAI-compatible tool-calling SPI.
Installation
Requirements
- PHP 8.3 or higher
adachsoft/ai-integration^0.10adachsoft/ai-conversation-model^0.2guzzlehttp/guzzle^7.0- An xAI API key
Install the package with Composer:
composer require adachsoft/ai-integration-xai
Composer installs the required PHP packages automatically.
Configuration
The library does not load environment variables itself. Read them in your application and pass their values to XaiConfig:
XAI_API_KEY=your-xai-api-key
XAI_MODEL=grok-4
use AdachSoft\AiIntegrationXai\Config\XaiConfig;
$apiKey = getenv('XAI_API_KEY');
if (!is_string($apiKey) || $apiKey === '') {
throw new \RuntimeException('XAI_API_KEY must be set.');
}
$modelId = getenv('XAI_MODEL');
$xaiConfig = new XaiConfig(
apiKey: $apiKey,
defaultModelId: is_string($modelId) && $modelId !== '' ? $modelId : 'grok-4',
);
XAI_API_KEY is required. XAI_MODEL is optional and defaults to grok-4. XaiConfig also allows overriding the base URI (default: https://api.x.ai/v1/chat/completions) and provider ID (default: xai).
Usage
Create the SPI with XaiToolCallingChatSpiFactory, then register it with the ai-integration facade builder used by your application:
use AdachSoft\AiIntegrationXai\XaiToolCallingChatSpiFactory;
$xaiSpi = (new XaiToolCallingChatSpiFactory($xaiConfig))->create();
// Register the provider on your existing facade builder.
$chatFacadeBuilder->withSpiProvider($xaiConfig->providerId, $xaiSpi);
The factory delegates chat-completion handling to the shared OpenAI-compatible SPI and configures XaiErrorClassifier for xAI-specific error responses. It also preserves the reasoning_content choice field as assistant-message metadata in conversation history.
Use the standard adachsoft/ai-integration APIs to build prompts, register tools, and run tool-calling conversations.
Supported input and limitations
- Text and tool-calling chat are supported.
- Images in user messages are supported for vision-capable xAI models.
- The adapter targets xAI Chat Completions. PDF input, xAI file IDs, and audio are not supported; those require the xAI Responses/Files APIs, which are outside this library's scope.
Tests
Run the default unit-test suite with:
vendor/bin/phpunit
The separate production suite uses the xAI profile from adachsoft/ai-integration-tester ^0.5.2 and calls the real xAI API. These requests may incur charges. Set XAI_API_KEY and, optionally, XAI_MODEL before explicitly running it:
vendor/bin/phpunit --testsuite production
Migration from 0.8-era types
This upgrade is a breaking type-contract change. The provider now uses the shared conversation model instead of the 0.8-era types. Update imports and type declarations that refer to those older conversation/message types to their shared equivalents from adachsoft/ai-conversation-model ^0.2; use adachsoft/ai-integration ^0.10 for the provider SPI and facade APIs.
Versioning
This library follows semantic versioning. See CHANGELOG.md for release history.
License
This library is open-sourced under the MIT license.