Search by

adachsoft / ai-integration-xai-responses

Arkadiusz Adach

xAI Responses API integration for AdachSoft AI Integration tool calling

Package info

gitlab.com/a.adach/ai-integration-xai-responses

Issues

pkg:composer/adachsoft/ai-integration-xai-responses

Statistics

Installs: 31

Dependents: 0

Suggesters: 0

Stars: 0

v0.4.1 2026-11-17 12:25 UTC

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.10
  • adachsoft/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 to grok-4.
  • baseUri — xAI API base URI; defaults to https://api.x.ai/v1.
  • defaultTemperature — temperature used when a request does not provide one; defaults to 0.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 n parameter is rejected, as is stream: true; stream: false is ignored.
  • Other supported string-keyed generation parameters are passed through. The temperature parameter uses the shared temperature field.
  • maxTokens, max_tokens, and max_output_tokens are mapped to the API's max_output_tokens field. Supply at most one of these aliases.
  • User images are encoded as xAI input_image content 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.