Search by

adachsoft / ai-integration-openrouter

Arkadiusz Adach

OpenRouter integration for adachsoft/ai-integration.

Package info

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

Issues

pkg:composer/adachsoft/ai-integration-openrouter

Statistics

Installs: 15

Dependents: 0

Suggesters: 0

Stars: 0

v0.3.1 2026-11-17 13:49 UTC

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