Skip to main content

Sovereign AI for Laravel

IONOS AI Model Hub and OVHcloud AI Endpoints as providers of the Laravel AI SDK (laravel/ai). The package registers both under ai.providers, holds every request to the endpoints it lists for each cloud, refuses a request whose model cannot do what it asks for, and names the provider and the cause in every error.

A PHP example and the request it sends. The example asks an agent of laravel/ai, through the provider ionos, what the capital of France is. Under it the request the package sent: POST to https://openai.inference.de-txl.ionos.com/v1/chat/completions, the endpoint of IONOS in Berlin, with the default model meta-llama/Llama-3.3-70B-Instruct, marked, and two messages, the instruction and the question.

The request in the picture as text, as the first example under Sending a request sends it:

POST https://openai.inference.de-txl.ionos.com/v1/chat/completions
{
"model": "meta-llama/Llama-3.3-70B-Instruct",
"messages": [
{
"role": "system",
"content": "You answer in one sentence."
},
{
"role": "user",
"content": "What is the capital of France?"
}
]
}

Installation​

composer require pushery/sovereign-ai-for-laravel

The service provider is registered automatically through package discovery. The package needs laravel/ai 1.4 or later, which Composer installs with it, and no database.

Put the keys of the clouds you use into .env:

SOVEREIGN_AI_IONOS_KEY=
SOVEREIGN_AI_OVHCLOUD_KEY=

The IONOS key is a token from the Token Manager of the IONOS Data Center Designer. The OVHcloud key is an access key of a Public Cloud project; a project in discovery mode, without a payment method, cannot use the service.

The package works with its defaults and needs no configuration file of its own. To change a default, such as a default model or the catalog, publish config/sovereign-ai.php:

php artisan vendor:publish --tag=sovereign-ai-config

Sending a request​

The two providers are called ionos and ovhcloud, and every agent of laravel/ai can use them:

use function Laravel\Ai\agent;

$response = agent('You answer in one sentence.')->prompt('What is the capital of France?', provider: 'ionos');

$response->text;

Without a model, a request uses the default of its provider: meta-llama/Llama-3.3-70B-Instruct at IONOS and Mistral-Small-3.2-24B-Instruct-2506 at OVHcloud. Another model is named per request:

$response = agent('You answer in one sentence.')->prompt('What is the capital of France?', provider: 'ovhcloud', model: 'gpt-oss-120b');

Embeddings come from the default embeddings model, BAAI/bge-m3 at IONOS and bge-m3 at OVHcloud:

use Laravel\Ai\Ai;

$vectors = Ai::embeddingProvider('ionos')->embeddings(['Invoice 2026-114 is overdue.'])->embeddings;

An agent that names both providers falls over to the second when the first is rate limited, out of credits or quota, overloaded, or cannot be reached because the connection is refused or times out, as laravel/ai does for every provider:

$response = agent('You answer in one sentence.')->prompt('What is the capital of France?', provider: ['ionos', 'ovhcloud']);

A request waits as long as laravel/ai gives it: 60 seconds for an agent and 30 for embeddings, unless the application names another. An agent names its own with the attribute #[Timeout(120)] from Laravel\Ai\Attributes or with a timeout() method, and a single prompt with timeout::

$response = agent('You answer in one sentence.')->prompt('What is the capital of France?', provider: 'ionos', timeout: 120);

Embeddings take timeout: on embeddings(), and a transcription takes ->timeout(). The package changes none of these. Its own setting, sovereign-ai.providers.timeout, is the wait of a request laravel/ai sends without a timeout, such as the prompt that titles a remembered conversation.

The endpoints​

Each cloud has a list of endpoints in the package, and a request goes to no other address:

ProviderEndpointWhere it runs
ionoshttps://openai.inference.de-txl.ionos.com/v1IONOS data center in Berlin
ovhcloudhttps://oai.endpoints.kepler.ai.cloud.ovh.net/v1OVHcloud, in the EU (see data processing)

The check runs twice. When the application boots, every entry of ai.providers whose driver is ionos or ovhcloud must point to an endpoint of its cloud; a trailing slash makes no difference. Any other URL stops the boot with a Pushery\SovereignAi\Exceptions\EndpointNotAllowed that names the provider and the value. Before every request, the gateway checks the URL again, so a configuration changed after the boot cannot send a request elsewhere either.

The gateway follows no redirect. When an endpoint answers with one, such as a 307 or a 308 whose Location names another address, the request ends in a Pushery\SovereignAi\Exceptions\ProviderRequestFailed that names the status, and nothing is sent to that address.

The names ionos and ovhcloud belong to the package while it registers them. An entry under one of these names in config/ai.php keeps every key it sets, but its driver must be the one of the same name. To use one of the names for something else, remove the cloud from sovereign-ai.providers.register.

The drivers can back further entries, for example a second IONOS provider with another default model:

// config/ai.php
'providers' => [
'ionos-small' => [
'driver' => 'ionos',
'url' => 'https://openai.inference.de-txl.ionos.com/v1',
'key' => env('SOVEREIGN_AI_IONOS_KEY'),
'models' => ['text' => ['default' => 'Qwen/Qwen3.5-9B']],
],
],

The model catalog​

Not every model of the two clouds can answer against a JSON schema, call tools or produce embeddings. The package keeps a catalog of the models of each cloud with the capabilities their documentation states, read on 2026-11-11. A request that needs a capability its model does not have is refused before it is sent, with a Pushery\SovereignAi\Exceptions\UnsupportedCapability that names the model and the capability:

  • an agent with structured output needs structured_output
  • an agent with tools, or with at least one skill, needs tools
  • an embeddings request needs embeddings

A plain text request goes to any model.

IONOS AI Model Hub. IONOS lists tool calls on the page of each model. For structured output it says only that the supported formats depend on the model, and the one model its documentation shows with a JSON schema is Llama 3.3 70B. The catalog therefore lists structured output for that model alone.

ModelStructured outputToolsEmbeddings
meta-llama/Llama-3.3-70B-Instructyesyes
mistralai/Mistral-Small-24B-Instructyes
openai/gpt-oss-120byes
Qwen/Qwen3.5-9Byes
Qwen/Qwen3.5-397B-A17Byes
Qwen/Qwen3.8-27Byes
Qwen/Qwen3-Coder-Nextyes
lightonai/LightOnOCR-2-1B
BAAI/bge-m3yes
Qwen/Qwen3-VL-Embedding-8Byes

IONOS removes sentence-transformers/paraphrase-multilingual-mpnet-base-v2 on 2026-11-30 and names BAAI/bge-m3 as its successor, so the catalog leaves it out.

OVHcloud AI Endpoints. OVHcloud states both capabilities per model in its catalog API (https://catalog.endpoints.ai.ovh.net/rest/v1/models_v2). The catalog holds the models that API marks as available.

ModelStructured outputToolsEmbeddings
gpt-oss-120byesyes
gpt-oss-20byesyes
Mistral-Small-3.2-24B-Instruct-2506yesyes
Qwen3.5-397B-A17Byesyes
Qwen3.5-9Byesyes
Qwen3.8-27Byesyes
Qwen3Guard-Gen-0.6B
Qwen3Guard-Gen-8B
bge-m3yes
Qwen3-Embedding-8Byes

A model the catalog does not name is refused for a request that needs a capability, because whether it has the capability is not known. Name such a model, or a model that can do more today than the catalog lists, under the catalog key of its cloud; an entry there replaces the catalog's entry of the same model:

// config/sovereign-ai.php
'ionos' => [
'catalog' => [
'Qwen/Qwen3.5-397B-A17B' => ['structured_output', 'tools'],
],
],

Each entry is the id of a model with the list of its capabilities, written structured_output, tools and embeddings; an empty list names a model that can do none of the three. An entry the package cannot read stops the boot with a Pushery\SovereignAi\Exceptions\InvalidCatalog that names the cloud, the model, the value and the known capabilities: a key that is no model id, such as an empty one, a value that is no list, and a capability by another name, such as structured-output. The prompt of an agent and an embeddings request read the setting again, so an entry changed after the boot ends such a request before it is sent.

Setting sovereign-ai.providers.refuse_unknown_models to false sends a request to a model the catalog does not name. A model the catalog names without the capability is refused either way.

Errors​

What happenedException
The key is missing or was rejected (401), refused for the request (403), the model or path is unknown (404), the request was refused (400, 422) or is too large (413)Pushery\SovereignAi\Exceptions\ProviderRequestFailed, with the provider, the status, its cause and the cloud's own message
The endpoint answered with a redirect (300 to 399)Pushery\SovereignAi\Exceptions\ProviderRequestFailed, with the provider and the status; the redirect is not followed
Rate limited (429)Laravel\Ai\Exceptions\RateLimitedException
Out of credits or quota (402, or a 429 whose error code names an exhausted quota)Laravel\Ai\Exceptions\InsufficientCreditsException
Overloaded (502, 503, 504, 520, 522, 524, and the 529 of IONOS)Laravel\Ai\Exceptions\ProviderOverloadedException
Any other error status, 500 includedPushery\SovereignAi\Exceptions\ProviderRequestFailed, with the provider, the status, the cause "the request failed" and the cloud's own message
The cloud cannot be reached: the connection was refused or timed outLaravel\Ai\Exceptions\ProviderConnectionException
A model without the capability the request needsPushery\SovereignAi\Exceptions\UnsupportedCapability, before the request is sent
A classification, with a model or without onePushery\SovereignAi\Exceptions\UnsupportedCapability, before the request is sent, because neither cloud offers one
A URL outside the endpoints of the cloudPushery\SovereignAi\Exceptions\EndpointNotAllowed, at the boot or before the request
An entry under sovereign-ai.ionos.catalog or sovereign-ai.ovhcloud.catalog the package cannot readPushery\SovereignAi\Exceptions\InvalidCatalog, at the boot or before the request

ProviderRequestFailed and UnsupportedCapability extend Laravel\Ai\Exceptions\AiException. The rate limit, the exhausted credits or quota, the overload and the connection that fails keep the exceptions of laravel/ai, because those four are the ones its failover between providers acts on. IONOS answers an exhausted capacity with the status 529, which laravel/ai does not count as overloaded on its own. The package counts it as one, so a 529 is handled as a 503 is: with a Retry-After of up to ten seconds, laravel/ai waits that long and tries once more, and otherwise the request ends in the same exception.

Token usage​

Both clouds report prompt_tokens and completion_tokens with every chat completion, and the usage of a response carries them as laravel/ai reports them for every provider:

$response->usage->inputTokens;
$response->usage->outputTokens;

A streamed answer carries the same two counts once it has ended. The package asks each cloud for them with stream_options, which laravel/ai sends to an OpenAI-compatible provider only where its configuration names them; an entry of the application under ai.providers with stream_options of its own keeps those.

Neither cloud reports tokens read from or written to a prompt cache, so those counts stay empty. IONOS may report reasoning tokens, and counts them in the completion tokens.

Configuration​

The file the publish step under Installation writes, without its comments:

// config/sovereign-ai.php
return [
'providers' => [
'register' => ['ionos', 'ovhcloud'],
'refuse_unknown_models' => true,
'timeout' => is_numeric($timeout = env('SOVEREIGN_AI_TIMEOUT')) && (int) $timeout >= 1
? (int) $timeout
: 60,
],
'ionos' => [
'key' => env('SOVEREIGN_AI_IONOS_KEY'),
'url' => 'https://openai.inference.de-txl.ionos.com/v1',
'models' => [
'text' => [
'default' => 'meta-llama/Llama-3.3-70B-Instruct',
],
'embeddings' => [
'default' => 'BAAI/bge-m3',
],
],
'catalog' => [],
],
'ovhcloud' => [
'key' => env('SOVEREIGN_AI_OVHCLOUD_KEY'),
'url' => 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
'models' => [
'text' => [
'default' => 'Mistral-Small-3.2-24B-Instruct-2506',
],
'embeddings' => [
'default' => 'bge-m3',
],
],
'catalog' => [],
],
];
KeyWhat it does
providers.registerThe clouds registered in ai.providers, each under its own name. A name the package does not know stops the boot.
providers.refuse_unknown_modelsWhether a request that needs a capability is refused for a model the catalog does not name.
providers.timeoutThe seconds a request waits for its cloud when laravel/ai sends it without a timeout, such as the prompt that titles a remembered conversation, from SOVEREIGN_AI_TIMEOUT; 60 by default, and a value below 1 or no number at all lands on 60. An agent, embeddings and a transcription carry a timeout of their own, which this does not change; see Sending a request.
ionos.key, ovhcloud.keyThe key of the cloud, from SOVEREIGN_AI_IONOS_KEY and SOVEREIGN_AI_OVHCLOUD_KEY.
ionos.url, ovhcloud.urlThe endpoint. Only an endpoint of the cloud's list is accepted.
ionos.models, ovhcloud.modelsThe default models of the provider, in the form of laravel/ai: text.default, and optionally text.cheapest and text.smartest, and embeddings.default.
ionos.catalog, ovhcloud.catalogModels with their capabilities, beside or instead of the catalog's entries. An entry the package cannot read stops the boot.

Data processing and training​

This section reports what the two providers state, read on 2026-11-11, with the sources. It does not replace a review of the contracts for your own use.

IONOS AI Model Hub.

  • Training: prompts and outputs are not written to any log or to persistent storage, are not used to train or improve any model, and are not disclosed to any third party (Data handling). The terms for AI services forbid any use for training, retraining or further development of models in clause 2.3 (Nutzungsbedingungen für KI-Dienste).
  • Location: all inference runs in IONOS data centers in Germany, and operational access is limited to staff within the European Union. IONOS engages no third-party sub-processors for the AI Model Hub (Data handling).
  • Data processing agreement: it applies as part of the contract with IONOS and needs no separate signature (Data handling).
  • Retention: IONOS records the time, the model and the number of tokens of a request, and keeps operational logs under an internal retention policy whose period the page does not state.
  • Use from software: clause 2.5 of the terms for AI services describes the services as meant for interactive use by a natural person unless the service description says otherwise, clause 2.6 counts software-driven queries as misuse, and clause 2.8 exempts a use the service description provides for. The documentation calls the AI Model Hub an API-first solution (FAQ). No source states whether that exempts an application's automated requests; ask IONOS before relying on it.

OVHcloud AI Endpoints.

  • Training: data is never used to train OVHcloud's models (AI Endpoints). The special conditions for Public Cloud state that OVHcloud has no knowledge of inputs and outputs, does not reuse them and does not back them up, except for the Batch API (Special conditions, appendix 10).
  • Location: OVHcloud states that AI Endpoints is hosted and run in the European Union (AI Endpoints), and its catalog API lists France for every model. The documentation does not name the data center behind the endpoint; a press release of 2025-04-29 says the service is deployed from the Gravelines data center (Newsroom).
  • Data processing agreement: OVHcloud's agreement under article 28 GDPR forms part of the contract for its services (DPA, AVV). It does not name AI Endpoints.
  • Retention: OVHcloud keeps only the data billing needs; the Batch API stores its input and output files for a time (AI Endpoints).

What the package does not do​

  • It sends no request to an address outside the endpoints listed above, and offers no way to add one.
  • It does not check what a cloud does with the data it receives; the section above reports what the clouds state.
  • Its catalog is the state of the clouds' documentation on the day it was read. A model a cloud adds later is refused for structured output, tools and embeddings until it is in the catalog or named in the configuration, and a model a cloud removes answers with a 404.
  • It registers no other cloud.
  • It classifies nothing. laravel/ai sends a classification to the decisions endpoint of OpenAI, which IONOS does not serve and OVHcloud serves for none of its models, so the package refuses one before it is sent. A text model with structured output answers the same questions against a schema.