Search by

adachsoft / ai-integration-xai

Arkadiusz Adach

xAI SPI provider for adachsoft/ai-integration: tool-calling chat integration with Grok models (OpenAI-compatible endpoint).

Package info

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

Issues

pkg:composer/adachsoft/ai-integration-xai

Statistics

Installs: 25

Dependents: 0

Suggesters: 0

Stars: 0

v0.4.0 2026-11-16 20:43 UTC

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.10
  • adachsoft/ai-conversation-model ^0.2
  • guzzlehttp/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.