adachsoft / ai-integration-xai-responses
xAI Responses API integration for AdachSoft AI Integration tool calling
Package info
gitlab.com/a.adach/ai-integration-xai-responses
pkg:composer/adachsoft/ai-integration-xai-responses
Requires
- php: ^8.3
- adachsoft/ai-conversation-model: ^0.2
- adachsoft/ai-integration: ^0.10
- adachsoft/model-pricing-contracts: ^0.4
- guzzlehttp/guzzle: ^7.8
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.46
- phpunit/phpunit: ^13.1
- rector/rector: ^2.4
- symplify/phpstan-rules: ~14.10.0
- vlucas/phpdotenv: ^5.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 11:46:17 UTC
README
PHP integration for the xAI Responses API using the shared tool-calling abstractions from adachsoft/ai-integration.
The integration maps shared chat requests to xAI Responses API payloads and maps API responses back to the shared completion model. It supports text, tool calling, and image input.
Requirements
- PHP 8.3 or newer
adachsoft/ai-integration^0.10adachsoft/ai-conversation-model^0.2- An xAI API key for requests to the live API
Installation
composer require adachsoft/ai-integration-xai-responses
Usage
Register the provider
Register the package SPI with the shared facade builder under the xai/responses provider ID:
use AdachSoft\AiIntegration\PublicApi\Builder\ToolCallingChatFacadeBuilder;
use AdachSoft\AiIntegrationXaiResponses\Config\XaiResponsesConfig;
use AdachSoft\AiIntegrationXaiResponses\XaiResponsesToolCallingChatSpiFactory;
$config = new XaiResponsesConfig(
apiKey: $xaiApiKey, // Load this value from an environment variable or secret store.
defaultModelId: 'grok-4',
);
$chat = ToolCallingChatFacadeBuilder::create()
->withSpiProvider(
XaiResponsesConfig::PROVIDER_ID, // xai/responses
XaiResponsesToolCallingChatSpiFactory::create($config),
)
->build();
$chat implements the shared ToolCallingChatFacadeInterface. Use XaiResponsesToolCallingChatSpiFactory::createWithLogger() to register the SPI with an HTTP traffic logger.
Configuration
XaiResponsesConfig supports the following settings:
apiKey— xAI API key.defaultModelId— model used when a request does not provide one; defaults togrok-4.baseUri— xAI API base URI; defaults tohttps://api.x.ai/v1.defaultTemperature— temperature used when a request does not provide one; defaults to0.7.
When using the AI Integration Tester profile, XAI_API_KEY provides the API key and XAI_RESPONSES_MODEL optionally overrides the model. The profile defaults to grok-4.
Keep API keys in environment variables or another secure secret store. Do not commit credentials to source control.
Request and response behavior
- The Responses API integration returns one choice. The
nparameter is rejected, as isstream: true;stream: falseis ignored. - Other supported string-keyed generation parameters are passed through. The
temperatureparameter uses the shared temperature field. maxTokens,max_tokens, andmax_output_tokensare mapped to the API'smax_output_tokensfield. Supply at most one of these aliases.- User images are encoded as xAI
input_imagecontent parts. - xAI reasoning items are preserved in the choice metadata under
reasoning_items. When appending the choice to conversation history, copy that metadata to the assistant message so the reasoning items can be included in the next request.
PDF and file-ID inputs, audio, and media returned by tools are not supported.
Cost
Cost\XaiResponsesUsageNormalizer implements the adachsoft/model-pricing-contracts usage-normalizer contract. It separates cached input from uncached input and counts all output tokens, including reasoning tokens, as output. The default service tier maps to standard, while priority remains priority. xAI source and server-side tool counts, context details, and cost_in_usd_ticks are recognized but are not separately priced by this token normalizer.
HTTP traffic logging
FileHttpTrafficLogger writes request and response records as JSON Lines. It shortens long base64 or data-URI values and encrypted_content values to byte-count placeholders before writing them to the log file. Configure the log directory appropriately and avoid logging credentials.
Tests
The default PHPUnit suite contains unit tests and does not call the xAI API:
vendor/bin/phpunit
The xAI conformance profile targets AI Integration Tester 0.5.2 and is marked as a production test. Running the separate production suite sends real API requests and may incur charges; configure XAI_API_KEY before choosing to run it:
vendor/bin/phpunit --testsuite production
The conformance profile declares text, tool-calling, and vision-input capabilities and includes the tester's tool-calling and multimodal scenario packs.
Migration (breaking)
This integration requires the AI Integration ^0.10 and AI Conversation Model ^0.2 contracts. Applications migrating from earlier contract versions must update their shared request, message, content, and tool DTOs and register the SPI with the common facade builder under xai/responses.
License
This package is licensed under the MIT License. See the LICENSE file for details.