adachsoft / ai-integration-openrouter
OpenRouter integration for adachsoft/ai-integration.
Package info
gitlab.com/a.adach/ai-integration-openrouter
pkg:composer/adachsoft/ai-integration-openrouter
Requires
- php: ^8.4
- adachsoft/ai-conversation-model: ^0.2
- adachsoft/ai-integration: ^0.10
- adachsoft/model-pricing-contracts: ^0.4
Requires (Dev)
- adachsoft/ai-integration-tester: ^0.5.2
- adachsoft/php-code-style: ^0.5.0
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^13.0
- rector/rector: ^2.6
- symplify/phpstan-rules: ^14.12
- vlucas/phpdotenv: ^5.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 14:13:00 UTC
README
This package connects OpenRouter to the shared tool-calling SPI provided by adachsoft/ai-integration, using OpenRouter's OpenAI-compatible chat completions API.
Requirements
- PHP
^8.4 adachsoft/ai-integration^0.10adachsoft/ai-conversation-model^0.2adachsoft/model-pricing-contracts^0.4
Installation
composer require adachsoft/ai-integration-openrouter
Registration and factory
Create an OpenRouterConfigVo with your API key and use OpenRouterToolCallingChatSpiFactory to create the shared ToolCallingChatSpiInterface implementation:
use AdachSoft\AiIntegrationOpenRouter\Config\OpenRouterConfigVo;
use AdachSoft\AiIntegrationOpenRouter\OpenRouterToolCallingChatSpiFactory;
$config = new OpenRouterConfigVo(apiKey: 'your-openrouter-api-key');
$spi = (new OpenRouterToolCallingChatSpiFactory($config))->create();
// Register $spi with your application's ai-integration setup.
The factory builds on the shared OpenAI-compatible SPI and applies the OpenRouter-specific OpenRouterErrorClassifier. The default endpoint is https://openrouter.ai/api/v1/chat/completions; the default provider ID is openrouter. HTTP 402 responses are classified as exhausted provider resources.
The model is supplied with each request; it is not part of OpenRouterConfigVo.
Reasoning metadata
The integration preserves the reasoning and reasoning_details fields in assistant choice metadata. Both fields are also retained when the assistant message is replayed in conversation history.
Cost
OpenRouterUsageNormalizer implements UsageNormalizerInterface from adachsoft/model-pricing-contracts and normalizes OpenRouter token usage, cache usage, and the provider-reported usage.cost in USD. BYOK responses are marked incomplete because provider charges are billed separately.
Multimodal content
Images and media included in tool results use the OpenAI-compatible content format. Support for a particular modality depends on the selected model.
Configuration
Provide the API key through OPENROUTER_API_KEY. Select the model per request with OPENROUTER_MODEL; when no model is selected, use openai/gpt-4.1-mini as the default.
OPENROUTER_API_KEY=...
OPENROUTER_MODEL=openai/gpt-4.1-mini
Tests
Run the unit test suite without external API requests:
composer test
Run the production suite against the real OpenRouter API:
composer test:production
The production suite uses the adachsoft/ai-integration-tester 0.5 profile and makes real, potentially billable API requests. It uses OPENROUTER_API_KEY and defaults to the openai/gpt-4.1-mini model.
Migrating from 0.1.x
Version 0.2.0 introduces a breaking change: the integration's former ai-integration 0.8 conversation and tool-calling types have been replaced by the shared conversation model. Update the dependencies to adachsoft/ai-integration ^0.10 and adachsoft/ai-conversation-model ^0.2, and update application type references to the shared model and SPI interfaces.