PHPackages                             padosoft/laravel-ai-regolo - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. padosoft/laravel-ai-regolo

ActiveLibrary[API Development](/categories/api)

padosoft/laravel-ai-regolo
==========================

Laravel AI SDK provider extension that adds Seeweb Regolo — chat, embeddings, reranking, plus a 30+ open-model catalog hosted in Italy — as a first-class provider for the official laravel/ai SDK.

v1.0.1(4w ago)25.1k1Apache-2.0PHPPHP ^8.3CI passing

Since Apr 28Pushed 4w agoCompare

[ Source](https://github.com/padosoft/laravel-ai-regolo)[ Packagist](https://packagist.org/packages/padosoft/laravel-ai-regolo)[ RSS](/packages/padosoft-laravel-ai-regolo/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (6)Dependencies (7)Versions (13)Used By (1)

laravel-ai-regolo
=================

[](#laravel-ai-regolo)

 **The fastest way to ship a Laravel app on Italian sovereign AI infrastructure.**
 A first-class [Seeweb Regolo](https://regolo.ai) provider for the official [`laravel/ai`](https://github.com/laravel/ai) SDK — chat, embeddings, reranking, image generation, audio transcription, text-to-speech, plus a 30+ open-model catalog hosted entirely in Italy.

 [![CI status](https://camo.githubusercontent.com/9da9271ba1548424e0a851705b27ba0016e6efde78b696b3528785c77309f85e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7061646f736f66742f6c61726176656c2d61692d7265676f6c6f2f63692e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473)](https://github.com/padosoft/laravel-ai-regolo/actions/workflows/ci.yml) [![Packagist version](https://camo.githubusercontent.com/066ddfef690dfa649f7eaa8cd0034c50eee0305e66ecc4f511c6984bf0df88df/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7061646f736f66742f6c61726176656c2d61692d7265676f6c6f2e7376673f6c6162656c3d7061636b6167697374)](https://packagist.org/packages/padosoft/laravel-ai-regolo) [![Total downloads](https://camo.githubusercontent.com/8851bbe6e7c1954b8f672a3a0fc83675ec07c2fb101e8f8ba1dbac806f26ebb0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7061646f736f66742f6c61726176656c2d61692d7265676f6c6f2e7376673f6c6162656c3d646f776e6c6f616473)](https://packagist.org/packages/padosoft/laravel-ai-regolo) [![License](https://camo.githubusercontent.com/798509b4df525f56802b56f8096862487f08023e3d7561c68656f8dab10d0d6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4170616368652d2d322e302d626c75652e737667)](LICENSE) [![PHP version](https://camo.githubusercontent.com/2457b6d694af1315d4c3b980954cd62f302ca8263328d648e57ac15df2f05974/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e33253230253743253230382e34253230253743253230382e352d373737424234)](https://camo.githubusercontent.com/2457b6d694af1315d4c3b980954cd62f302ca8263328d648e57ac15df2f05974/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e33253230253743253230382e34253230253743253230382e352d373737424234) [![Laravel version](https://camo.githubusercontent.com/26b345c07758850b08014603358538a5ede6d1aa67d23cc11fd9fdf9b45a704d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d313225323025374325323031332d464632443230)](https://camo.githubusercontent.com/26b345c07758850b08014603358538a5ede6d1aa67d23cc11fd9fdf9b45a704d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d313225323025374325323031332d464632443230) [![GitHub issues](https://camo.githubusercontent.com/f1733e76fd051fa2c780a60fc915d9da52ded54a1d863aaebae14c8daed8e102/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f7061646f736f66742f6c61726176656c2d61692d7265676f6c6f)](https://github.com/padosoft/laravel-ai-regolo/issues)

 [![laravel-ai-regolo — Italian sovereign AI for Laravel](resources/banner.png)](resources/banner.png)

---

Table of contents
-----------------

[](#table-of-contents)

1. [Why this package](#why-this-package)
2. [Design rationale](#design-rationale)
3. [Features at a glance](#features-at-a-glance)
4. [See it in action — laravel-ai-chat demo](#see-it-in-action--laravel-ai-chat-demo)
5. [Comparison vs alternatives](#comparison-vs-alternatives)
6. [When to use Regolo vs OpenAI](#when-to-use-regolo-vs-openai)
7. [Installation](#installation)
8. [Quick start](#quick-start)
9. [Usage examples](#usage-examples)
10. [Configuration reference](#configuration-reference)
11. [Architecture](#architecture)
12. [🚀 AI vibe-coding pack included](#ai-vibe-coding-pack-included)
13. [Testing](#testing)
    - [Default suite — offline](#default-suite--offline-zero-cost-runs-everywhere)
    - [Running the live test suite](#running-the-live-test-suite-against-the-real-regolo-api)
14. [Roadmap](#roadmap)
15. [Contributing](#contributing)
16. [Security](#security)
17. [License & credits](#license--credits)

---

Why this package
----------------

[](#why-this-package)

`laravel/ai` is the official Laravel AI SDK, and it ships 14+ providers out of the box (OpenAI, Anthropic, Gemini, Mistral, Groq, Cohere, DeepSeek, Bedrock, Azure OpenAI, OpenRouter, Ollama, Jina, VoyageAI, xAI, ElevenLabs).

What it **does not ship** is a provider for [**Regolo**](https://regolo.ai) — Seeweb's Italian sovereign AI cloud. Regolo gives you:

- A growing catalog of **30+ open models** hosted in Italy (Llama 3, Qwen, Mistral, Gemma, Phi, DeepSeek, ...).
- **Chat + embeddings + reranking** under a single API.
- **GDPR + EU AI Act-friendly** hosting — your traffic and your customers' data never leave the EU.
- **Pay-as-you-go pricing** competitive with US-hosted providers, billed in EUR.
- A REST surface that is **OpenAI-compatible** for chat and embeddings (and Cohere/Jina-shaped for reranking), so the same prompts and tooling that work against OpenAI work against Regolo with one config change.

This package fills the gap. Drop it in alongside `laravel/ai`, set a single env var, and Regolo becomes available through the same unified `Agent::for()` / `Embeddings::for()` / `Reranking::of()` APIs the SDK already exposes — no adapter, no wrapper, no learning curve.

> **Italian sovereign cloud, official Laravel API, zero leakage of provider concepts into your domain code.**

Design rationale
----------------

[](#design-rationale)

A few decisions are worth surfacing up front, because they shape the package's footprint and the kind of bugs you can or cannot have.

### 1. Provider extension, not SDK fork

[](#1-provider-extension-not-sdk-fork)

`laravel/ai` is a young but well-architected SDK. Forking it to add Regolo would split the ecosystem and force consumers to choose. Instead, this package implements the **public capability contracts** (`TextProvider`, `EmbeddingProvider`, `RerankingProvider`) and the **public gateway contracts** (`TextGateway`, `EmbeddingGateway`, `RerankingGateway`). A single `Padosoft\LaravelAiRegolo\LaravelAiRegoloServiceProvider` registers the binding `ai.provider.regolo`, and the SDK takes it from there.

The blast radius is small: when `laravel/ai` ships a new minor version, you get the upgrade for free; only a contract change in those interfaces would force a release here.

### 2. OpenAI-classic, not OpenAI-Responses

[](#2-openai-classic-not-openai-responses)

The upstream `OpenAiGateway` targets OpenAI's newer Responses API (`POST /v1/responses`). Regolo is OpenAI-compatible on the **classic** Chat Completions surface (`POST /v1/chat/completions`). The closest upstream template is therefore `MistralGateway` — we mirror its concern split (`BuildsTextRequests` / `MapsMessages` / `MapsTools` / `MapsAttachments` / `HandlesTextStreaming` / `ParsesTextResponses`) and adapt only the namespace and the provider name in the validation exception. See [`docs/laravel-ai-integration-notes.md`](docs/laravel-ai-integration-notes.md) for the full audit.

### 3. Stateless gateway, configuration on the provider

[](#3-stateless-gateway-configuration-on-the-provider)

`RegoloGateway::__construct(Dispatcher $events)` takes only the event dispatcher. Credentials and base URL are read from the `Provider` argument on each call via `providerCredentials()['key']` and `additionalConfiguration()['url']`. Two consequences:

- The same gateway instance is safe to share across configurations or to bind as a singleton.
- Rotating an API key or pointing at a staging endpoint is a `config()` change, not a service-provider rebuild.

### 4. Standalone, agnostic

[](#4-standalone-agnostic)

The package has zero dependencies on AskMyDocs, Padosoft proprietary code, or any sister package. It works in any Laravel 12 or 13 application that has `laravel/ai` installed (Laravel 11 is unsupported because the upstream `laravel/ai` SDK itself requires `illuminate/support: ^12.0|^13.0` — see the [Features at a glance](#features-at-a-glance) note). The reverse is true too: `lopadova/askmydocs` and `padosoft/askmydocs-pro` consume this package, never the inverse.

Features at a glance
--------------------

[](#features-at-a-glance)

- **Chat completion + streaming** via `Agent::for(...)->using('regolo', $model)->prompt()` and `->stream()`.
- **Embeddings** via `Embeddings::for($inputs)->generate('regolo', $model)`.
- **Reranking** via `Reranking::of($docs)->limit($k)->rerank($query, 'regolo', $model)`.
- **Image generation** via `Image::of($prompt)->generate('regolo', $model)` — default model `Qwen-Image`, OpenAI-compatible request shape.
- **Audio transcription (STT)** via `Transcription::of($audio)->using('regolo', $model)->generate()` — default model `faster-whisper-large-v3`, supports per-segment diarization.
- **Audio generation (TTS)** via `Audio::for($text)->generate('regolo', $model)` — wired against `POST /v1/audio/speech`; the upstream catalogue is not fully public yet, so the model id must be supplied explicitly.
- **Open-model catalog** with Italian sovereign hosting (Llama-3.x, Qwen-3, Mistral, Gemma, Phi, DeepSeek, Qwen-Image, faster-whisper, more).
- **Tool calling** — native function calling on models that support it; ReAct-style fallback on those that don't.
- **Strict typing** — PHP 8.3+, readonly DTOs, fully-typed signatures, Pint-formatted, PHPStan level 6.
- **CI matrix** — every push runs against PHP 8.3 / 8.4 / 8.5 × Laravel 12 / 13 (6 jobs). Laravel 11 is **not supported** — `laravel/ai` itself requires `illuminate/support: ^12.0|^13.0`.
- **82 unit tests / 184 assertions** — every Python-SDK happy-path is ported, plus 60+ robustness scenarios (4xx / 429 / 503 / connection-failure / malformed-JSON / Unicode / very-long-prompts / batch boundaries / score-ordering / multi-turn / timeout-fallback misconfiguration / image-edit rejection / multipart-language omission / diarization toggling).
- 🚀 **AI vibe-coding pack ships in the box** — every release includes the [Padosoft Claude pack](#ai-vibe-coding-pack-included) under `.claude/` (skills, rules, agents, slash-commands). The moment you `composer require` this package and open the project in Claude Code, the agent picks up Padosoft's house conventions automatically. **No other Laravel AI provider package ships this today.**
- 🧪 **Opt-in live test suite** — point `REGOLO_API_KEY` at a real key and run `vendor/bin/phpunit --testsuite Live` to verify wire compatibility against `api.regolo.ai`. Default suite remains 100% offline. See [Running the live test suite](#running-the-live-test-suite-against-the-real-regolo-api).

See it in action — laravel-ai-chat demo
---------------------------------------

[](#see-it-in-action--laravel-ai-chat-demo)

Want to see this package powering a real ChatGPT-style chatbot? **[`padosoft/laravel-ai-chat`](https://github.com/padosoft/laravel-ai-chat)** is a runnable, MIT-licensed demo on Laravel 13 + React that drops this provider behind the [Vercel AI SDK UI](https://ai-sdk.dev) (`@ai-sdk/react`'s `useChat()` hook + `ai` v6 message-stream protocol). Five suggested prompts trigger five tools that render inline as image / document / link-list / code-snippet / data-table artifacts — token-by-token streaming end-to-end, no glue code on top of `laravel/ai` and this package.

 [ ![laravel-ai-chat — animated demo: streaming Regolo reply with image · doc · links · code · table artifacts rendering inline](resources/Laravel-AI-Chat-Demo.gif) ](https://github.com/padosoft/laravel-ai-chat)

 **[▶ Open the demo on GitHub →](https://github.com/padosoft/laravel-ai-chat)**

Clone it, paste your Regolo key, run three commands, and you have a working chat in five minutes — the cleanest way to verify this package end-to-end and the fastest starting point for your own AI product on top of it.

Comparison vs alternatives
--------------------------

[](#comparison-vs-alternatives)

If you are evaluating how to call Regolo from a Laravel app, here are the realistic options on the table today.

CapabilityCustom `Http::` client`prism-php/prism`OpenAI-PHP repurposed**`laravel/ai` + this package**Chat completion✅✅✅✅**Streaming** (SSE)⚠️ DIY✅⚠️ partial✅**Embeddings**⚠️ DIY❌✅✅**Reranking**⚠️ DIY❌❌✅**Tool calling**⚠️ DIY✅✅✅Multi-step tool loops❌✅⚠️ DIY✅**Italian sovereign hosting**✅❌❌✅Same API as 14+ other providers❌✅❌✅First-class Laravel facade & queue support❌✅⚠️ partial✅Vercel AI SDK UI compatibility (streaming)❌❌❌✅82 tests / 6-cell CI matrix❌N/A❌✅Maintenance burden when SDK ships featuresyouN/Ayouyou get them free**Bottom line:** if you want Regolo behind the same API surface that powers OpenAI, Anthropic, Gemini, Mistral, and Ollama in `laravel/ai`, this is the only package that does it.

When to use Regolo vs OpenAI
----------------------------

[](#when-to-use-regolo-vs-openai)

`laravel/ai` ships an OpenAI provider out of the box, so the natural follow-up question is "why would I send traffic to Regolo instead of OpenAI?" Both are valid choices for Laravel apps; they optimise for different things.

### Pick **Regolo** when at least one of these is true

[](#pick-regolo-when-at-least-one-of-these-is-true)

- **GDPR / EU AI Act exposure.** The traffic and the prompts (which often contain user PII, contracts, internal docs, customer support transcripts) never leave the EU — Seeweb's data centres are in Italy, and the privacy policy is bound by Italian law. OpenAI's data-residency story is gradually improving but the default request path still terminates in the US, and the legal review for a regulated workload (banking, healthcare, public-sector, insurance, legal) is materially heavier.
- **Italian-speaking workloads.** Llama-3.x, Qwen3, Mistral and Gemma in Regolo's catalogue are tuned and benchmarked on Italian content; results on idiomatic Italian, technical Italian, and bilingual IT/EN prompts compete with much larger US-hosted closed models.
- **Open-weight models.** Regolo serves open-weight families (Llama, Qwen, Mistral, Gemma, Phi, DeepSeek, Qwen-Image, faster-whisper, ...). If you need to migrate the workload to a self-hosted vLLM / Ollama deployment later, the prompts and the model id port over with zero rewrites — same model, same tokenizer, just a different base URL. Lock-in on closed weights (`gpt-4o`, `claude-sonnet`) makes that migration fundamentally impossible.
- **EUR-billed pay-as-you-go.** Invoices in EUR, Italian VAT applied correctly, no FX-on-USD overhead. Material for finance teams in regulated procurement.
- **Sovereign-cloud procurement requirements.** Public-sector tenders, defence-adjacent workloads, healthcare buyers, and several large Italian enterprises now require an EU-resident inference path as a hard procurement filter. Regolo satisfies it; OpenAI typically does not without the dedicated Microsoft Azure OpenAI EU residency tier.

### Pick **OpenAI** (or stay on it) when

[](#pick-openai-or-stay-on-it-when)

- **Frontier model quality is the deciding factor.** GPT-4o / o1 / GPT-5 still lead on the hardest reasoning, math, and tool-use benchmarks. If your product depends on the absolute top of the curve, OpenAI is hard to beat today.
- **You need Responses API features that have no Regolo counterpart yet.** Hosted Web Search, Code Interpreter as a built-in tool, the new `responses.create` streaming envelope. Regolo's roadmap (see [Roadmap](#roadmap)) tracks these but the upstream catalogue is what determines availability.
- **Heavy ecosystem reliance on OpenAI-specific APIs.** Function calling extensions (parallel tool calls with pinned schemas), structured outputs at scale, the Files / Assistants / Vector Stores managed services. Some of these have analogues on the Regolo side (`/v1/embeddings`, `/v1/rerank`); others do not.
- **No EU-residency requirement and no model-portability concern.** If your workload is happy on US-hosted closed weights and you're not preparing for a self-host migration, the procurement-and-compliance argument for moving away from OpenAI shrinks meaningfully.

### Mix-and-match is fine and expected

[](#mix-and-match-is-fine-and-expected)

Because both providers register through `laravel/ai`'s identical SDK surface, you can route per-feature in a single Laravel app:

```
// config/ai.php — both providers wired side-by-side
'providers' => [
    'openai' => [/* … OpenAI key, models … */],
    'regolo' => [/* … Regolo key, models … */],
],

// Anti-hallucination KB chat → Regolo (EU residency for the user prompts).
$answer = Agent::for($question)->using('regolo', 'Llama-3.3-70B-Instruct')->prompt();

// Frontier reasoning over a synthetic dataset (no PII) → OpenAI.
$reasoning = Agent::for($problem)->using('openai', 'gpt-4o')->prompt();
```

This is also why the [Comparison table above](#comparison-vs-alternatives) emphasises "same API as 14+ other providers" — the value of `laravel/ai` is precisely that you can rebalance traffic across providers without touching application code.

Installation
------------

[](#installation)

```
composer require laravel/ai
composer require padosoft/laravel-ai-regolo
```

The package auto-registers via Laravel's package discovery — no manual provider entry in `config/app.php` needed.

Add the `regolo` entry to your `config/ai.php` (publish it from `laravel/ai` if you haven't yet):

```
return [

    'providers' => [
        // Built-in providers from laravel/ai (OpenAI / Anthropic / Gemini /
        // Mistral / Groq / Cohere / DeepSeek / Bedrock / Azure OpenAI /
        // OpenRouter / Ollama / Jina / VoyageAI / xAI / ElevenLabs)
        'openai' => ['driver' => 'openai', 'key' => env('OPENAI_API_KEY')],
        'ollama' => ['driver' => 'ollama'],

        // Added by this package
        'regolo' => [
            'driver'  => 'regolo',
            'name'    => 'regolo',
            'key'     => env('REGOLO_API_KEY'),
            'url'     => env('REGOLO_BASE_URL', 'https://api.regolo.ai/v1'),
            'timeout' => 60,
            'models'  => [
                'text'       => [
                    'default'  => 'Llama-3.1-8B-Instruct',
                    'cheapest' => 'Llama-3.1-8B-Instruct',
                    'smartest' => 'Llama-3.3-70B-Instruct',
                ],
                'embeddings' => [
                    'default'    => 'Qwen3-Embedding-8B',
                    'dimensions' => 4096,
                ],
                'reranking'  => [
                    'default' => 'Qwen3-Reranker-4B',
                ],
            ],
        ],
    ],

    'defaults' => [
        'text'        => env('AI_DEFAULT_TEXT', 'regolo'),
        'embeddings'  => env('AI_DEFAULT_EMBEDDINGS', 'regolo'),
        'reranking'   => env('AI_DEFAULT_RERANKING', 'regolo'),
    ],

];
```

In your `.env`:

```
REGOLO_API_KEY=rg_live_...
REGOLO_BASE_URL=https://api.regolo.ai/v1   # optional
AI_DEFAULT_TEXT=regolo                      # or any other configured provider
```

Quick start
-----------

[](#quick-start)

```
use Laravel\Ai\Agent;

$response = Agent::for('Tell me three things about Rome.')
    ->using('regolo', 'Llama-3.3-70B-Instruct')
    ->prompt();

echo $response->text;
//  Rome was founded in 753 BC. It hosts the Vatican City...
```

That's it. Five lines.

Usage examples
--------------

[](#usage-examples)

### Chat completion

[](#chat-completion)

```
use Laravel\Ai\Agent;

$response = Agent::for('Riassumi il manzoniano "Addio monti" in tre righe.')
    ->using('regolo', 'Llama-3.3-70B-Instruct')
    ->prompt();

$response->text;             // string — final assistant message
$response->usage->promptTokens;
$response->usage->completionTokens;
$response->meta->provider;   // 'regolo'
$response->meta->model;      // 'Llama-3.3-70B-Instruct'
```

### Streaming (token-by-token)

[](#streaming-token-by-token)

```
use Laravel\Ai\Agent;
use Laravel\Ai\Streaming\Events\TextDelta;

foreach (Agent::for('Spiega il teorema di Pitagora.')->using('regolo')->stream() as $event) {
    if ($event instanceof TextDelta) {
        echo $event->delta;
    }
}
```

### Streaming with a Vercel AI SDK UI frontend

[](#streaming-with-a-vercel-ai-sdk-ui-frontend)

```
return Agent::for($prompt)
    ->using('regolo')
    ->stream()
    ->usingVercelDataProtocol();
```

The response is a Vercel-compatible byte stream you can consume directly from `@ai-sdk/react`'s `useChat()` hook on the frontend.

### Tool calling

[](#tool-calling)

```
use Laravel\Ai\Agent;
use Laravel\Ai\Contracts\Tool;
use Illuminate\JsonSchema\JsonSchema;

class GetWeather implements Tool
{
    public function description(): string { return 'Lookup current weather for an Italian city.'; }

    public function schema(JsonSchema $schema): array
    {
        return $schema->object()
            ->property('city', $schema->string()->required())
            ->toArray();
    }

    public function handle(\Laravel\Ai\Tools\Request $request): string
    {
        $city = $request->arguments['city'];
        return "The weather in {$city} is sunny, 24°C.";
    }
}

$response = Agent::for('Che tempo fa a Roma oggi?')
    ->using('regolo', 'Llama-3.3-70B-Instruct')
    ->withTool(new GetWeather)
    ->prompt();

$response->text;            // includes the tool's output, woven into the answer
$response->toolCalls;       // Collection
$response->toolResults;     // Collection
```

### Embeddings (single + batch)

[](#embeddings-single--batch)

```
use Laravel\Ai\Embeddings;

// Single input
$single = Embeddings::for(['Roma è la capitale d\'Italia.'])
    ->generate('regolo', 'Qwen3-Embedding-8B');

$single->first();       // float[]  — 4096-dim vector
$single->tokens;        // int      — billed token count

// Batch (one HTTP call, one billed request)
$batch = Embeddings::for([
    'Roma è la capitale d\'Italia.',
    'Parigi è la capitale della Francia.',
    'Madrid è la capitale della Spagna.',
])->generate('regolo');

count($batch->embeddings);   // 3
$batch->meta->model;         // 'Qwen3-Embedding-8B' (default from config)
```

### Reranking (Cohere/Jina-shaped)

[](#reranking-coherejina-shaped)

```
use Laravel\Ai\Reranking;

$ranked = Reranking::of([
    'Rome is the capital of Italy.',
    'Paris is the capital of France.',
    'Pasta al pomodoro is a classic Italian dish.',
])
    ->limit(2)
    ->rerank('What is the capital of Italy?', 'regolo', 'Qwen3-Reranker-4B');

foreach ($ranked->results as $result) {
    echo "{$result->score}  {$result->document}\n";
}
//  0.91  Rome is the capital of Italy.
//  0.05  Pasta al pomodoro is a classic Italian dish.
```

The original `index` and `document` are preserved on each result so you can map back to your source data without a second lookup.

Configuration reference
-----------------------

[](#configuration-reference)

KeyTypeDefaultNotes`ai.providers.regolo.driver`string`regolo`Required. Resolves the binding `ai.provider.regolo`.`ai.providers.regolo.name`string`regolo`Echoed in `Meta::$provider`.`ai.providers.regolo.key`string`env('REGOLO_API_KEY')`**Required.** Bearer token sent on every request.`ai.providers.regolo.url`string`https://api.regolo.ai/v1`Override for staging or self-hosted Regolo instances.`ai.providers.regolo.timeout`int`60`Per-call timeout in seconds. Override at call-time via `$timeout`.`ai.providers.regolo.models.text.default`string`Llama-3.1-8B-Instruct`Model used when `Agent::using('regolo')` is called without a model.`ai.providers.regolo.models.text.cheapest`string`Llama-3.1-8B-Instruct`Used by `Lab::Cheapest` shorthand.`ai.providers.regolo.models.text.smartest`string`Llama-3.3-70B-Instruct`Used by `Lab::Smartest` shorthand.`ai.providers.regolo.models.embeddings.default`string`Qwen3-Embedding-8B`Used by `Embeddings::for()->generate('regolo')`.`ai.providers.regolo.models.embeddings.dimensions`int`4096`Embedding vector dimension. Must match downstream vector store.`ai.providers.regolo.models.reranking.default`string`Qwen3-Reranker-4B`Used by `Reranking::of()->rerank(..., 'regolo')`.`ai.providers.regolo.models.image.default`string`Qwen-Image`Used by `Image::of(...)->generate('regolo')`. Wire to `env('REGOLO_IMAGE_MODEL', 'Qwen-Image')` in `config/ai.php` for env-var override.`ai.providers.regolo.models.transcription.default`string`faster-whisper-large-v3`Used by `Transcription::of($audio)->using('regolo')->generate()`. Wire to `env('REGOLO_TRANSCRIPTION_MODEL', 'faster-whisper-large-v3')`.`ai.providers.regolo.models.audio.default`string*empty*Used by `Audio::for(...)->generate('regolo')` (TTS). Regolo's TTS catalogue is not on `GET /v1/models` yet; pass the model id explicitly. Wire to `env('REGOLO_AUDIO_MODEL')`.Architecture
------------

[](#architecture)

 ```
flowchart LR
    subgraph App[Your Laravel app]
        A[Agent / Embeddings / Reranking facades]
    end

    subgraph SDK[laravel/ai SDK]
        AI(AiManager) -->|resolves| RP(RegoloProvider)
    end

    subgraph Pkg[padosoft/laravel-ai-regolo]
        RP --> RG(RegoloGateway)
        RG -->|chat/completions| C[Concerns: BuildsTextRequests + MapsMessages + MapsTools + MapsAttachments]
        RG -->|stream| S[Concerns: HandlesTextStreaming + ParsesServerSentEvents]
        RG -->|embeddings| E[generateEmbeddings]
        RG -->|rerank| R[rerank — Cohere/Jina shape]
        RG --> CR[CreatesRegoloClient: Http::withToken + baseUrl]
    end

    subgraph Cloud[Italian sovereign cloud]
        Regolo[(api.regolo.ai/v1)]
    end

    A --> AI
    CR --> Regolo
```

      Loading The package contributes only the orange box. Everything else is upstream `laravel/ai`. A change to your prompt does not need a single line of provider code touched.

🚀 AI vibe-coding pack included
------------------------------

[](#-ai-vibe-coding-pack-included)

> **No other Laravel AI provider package on Packagist ships this today.**

Every release of this package includes the [Padosoft Claude pack](.claude/) under the `.claude/` directory: the same skills, rules, agents, and slash-commands the Padosoft team uses internally to keep AI-driven development consistent across all our repos. The moment you `composer require padosoft/laravel-ai-regolo` and open the project in [Claude Code](https://claude.com/claude-code), the agent automatically picks up the pack and applies it.

### What ships in the pack

[](#what-ships-in-the-pack)

```
.claude/
├── skills/
│   └── copilot-pr-review-loop/   ← R36: 9-step PR flow (--reviewer copilot,
│                                    wait CI green, wait Copilot review, fix,
│                                    re-CI, merge only when both gates green)
└── (more skills, rules, agents, slash-commands as the pack grows;
    see padosoft/* sister packages for the full set)

```

### Why this matters

[](#why-this-matters)

When a contributor (you, a team-mate, the Seeweb engineer doing wire-compatibility verification, or a random open-source PR author) opens this repo in Claude Code:

1. The agent reads the pack on session start.
2. The R36 PR-review skill kicks in automatically the first time the contributor types `gh pr create`. The agent uses `--reviewer copilot`, waits for CI, waits for Copilot review, addresses comments, re-checks CI, and only merges when both gates are green.
3. Future skills (style enforcement, security review, release-note generator, ...) plug into the same pack with zero configuration on the consumer side.

The result: **you get the Padosoft AI engineering culture in the same `composer require` that gets you the Regolo provider.** Drop-in vibe-coding for any team that wants to ship Italian-sovereign AI without re-inventing the development workflow.

### Opting out

[](#opting-out)

Do not want the pack? Add `.claude/` to your `.gitignore` (or delete it locally). The package code under `src/` works completely independently of the pack — the pack is purely a developer-experience layer for repos that use Claude Code.

### Want to contribute a skill?

[](#want-to-contribute-a-skill)

The same pack is shared across `padosoft/laravel-ai-regolo`, `padosoft/laravel-flow`, `padosoft/eval-harness`, `padosoft/laravel-pii-redactor`, and the upcoming `padosoft/laravel-patent-box-tracker` — open a PR on any of those repos and we will sync the skill across the family.

Testing
-------

[](#testing)

### Default suite — offline, zero cost, runs everywhere

[](#default-suite--offline-zero-cost-runs-everywhere)

The package ships **82 unit tests / 184 assertions** that run against a fake HTTP layer (`Http::fake()`), so the test suite never hits the real Regolo API and is safe to run in CI on every PR. No API key needed; no network needed; no money spent.

```
composer install
vendor/bin/phpunit
# OK (82 tests, 184 assertions)
```

Coverage breakdown:

SuiteTestsDescription`RegoloGatewayChatTest`214 ported from Regolo Python SDK + 17 robustness (streaming, errors)`RegoloGatewayEmbeddingsTest`121 ported + 11 robustness (empty / batch / Unicode / 4xx / 429 / 503)`RegoloGatewayRerankTest`131 ported + 12 robustness (top\_n / score-ordering / index integrity)`RegoloGatewayImageTest`8`images/generations` happy + size/quality + edit-rejection + timeout const + provider-config precedence`RegoloGatewayAudioTest`6`audio/speech` (TTS) happy + voice/instructions forwarding + empty-body resilience`RegoloGatewayTranscriptionTest`7`audio/transcriptions` (STT) happy + diarize + Whisper usage mapping + multipart-filename MIME extension matrix`RegoloGatewayTimeoutFallbackTest`8provider-level timeout fallback (numeric / empty / non-numeric / negative)`ServiceProviderTest`7container binding + capability interfaces + gateway compositionalThe test inventory and the rationale for each robustness scenario is documented in [`docs/test-coverage-vs-python-sdk.md`](docs/test-coverage-vs-python-sdk.md).

CI matrix: PHP 8.3 / 8.4 / 8.5 × Laravel 12 / 13 (6 cells — Laravel 11 is unsupported because the upstream `laravel/ai` SDK itself requires `illuminate/support: ^12.0|^13.0`), plus a separate static-analysis job that runs PHPStan and Pint.

### Running the live test suite (against the real Regolo API)

[](#running-the-live-test-suite-against-the-real-regolo-api)

If you want to verify behaviour against the real Regolo servers — for example you are a [Seeweb](https://www.seeweb.it/) / Regolo engineer validating the package, an enterprise adopter doing a pre-deploy smoke-test, or an open-source contributor confirming wire compatibility before tagging a release — the package ships a dedicated **`Live`** PHPUnit testsuite that hits `https://api.regolo.ai/v1` end-to-end.

The live suite is **opt-in by design**:

- A fresh `git clone` + `composer install` + `vendor/bin/phpunit` runs only the offline `Unit` suite. No accidental cost.
- The `Live` suite **self-skips** when `REGOLO_API_KEY` is missing, so it cannot accidentally fail a CI job that does not have credentials.
- The CI matrix on this repo runs **only** the offline `Unit` suite. Live tests run only when invoked explicitly with `--testsuite Live`.

#### 1. Get a Regolo API key

[](#1-get-a-regolo-api-key)

[regolo.ai](https://regolo.ai) → sign up → copy your `rg_live_...` key.

**Step 1 — open the API keys section in the Regolo dashboard:**

[![Regolo dashboard — API keys section](resources/regolo-api-key-step1.png)](resources/regolo-api-key-step1.png)

**Step 2 — create a new key and copy it:**

[![Regolo dashboard — create new API key](resources/regolo-api-key-step2.png)](resources/regolo-api-key-step2.png)

#### 2. Configure the environment

[](#2-configure-the-environment)

The bare minimum is a single env var:

```
export REGOLO_API_KEY=rg_live_...
```

Optional overrides (defaults pick the same models the package ships as defaults):

```
export REGOLO_BASE_URL=https://api.regolo.ai/v1     # change for staging
export REGOLO_LIVE_TEXT_MODEL=Llama-3.1-8B-Instruct
export REGOLO_LIVE_EMBEDDINGS_MODEL=Qwen3-Embedding-8B
export REGOLO_LIVE_RERANKING_MODEL=Qwen3-Reranker-4B
export REGOLO_LIVE_IMAGE_MODEL=Qwen-Image
export REGOLO_LIVE_TRANSCRIPTION_MODEL=faster-whisper-large-v3
export REGOLO_LIVE_TIMEOUT=60                       # seconds

# Multimodal — required for the corresponding live test (the test
# self-skips when the var is unset):
# REGOLO_LIVE_AUDIO_MODEL=...                       # TTS model id from Seeweb (catalogue not on /v1/models yet)
# REGOLO_LIVE_TRANSCRIPTION_AUDIO_PATH=/path/to/sample.mp3  # any short speech recording

# Multimodal — optional overrides (defaults apply when unset):
# REGOLO_LIVE_AUDIO_VOICE=alloy                     # voice id forwarded verbatim to TTS
# REGOLO_LIVE_TRANSCRIPTION_LANGUAGE=it             # ISO 639-1; omit to let Whisper auto-detect
```

On Windows PowerShell — single var:

```
$env:REGOLO_API_KEY = "rg_live_..."
```

If you prefer keeping the live-suite credentials in a `.env` file at the package root (the same format `.env.example` ships), you can hydrate the current shell from it before invoking PHPUnit. PHPUnit itself does **not** read `.env` — it reads only what the shell (or `` in `phpunit.xml`) hands it — so a small loader is the standard pattern:

**PowerShell:**

```
Get-Content .env |
    Where-Object { $_ -match '^[A-Z_][A-Z0-9_]*=' -and $_ -notmatch '^#' } |
    ForEach-Object {
        $parts = $_ -split '=', 2
        [Environment]::SetEnvironmentVariable($parts[0], $parts[1], 'Process')
    }
```

**Bash / zsh:**

```
set -a && source .env && set +a
```

#### 3. Run the live suite

[](#3-run-the-live-suite)

```
vendor/bin/phpunit --testsuite Live
```

…or, with the testdox formatter so each scenario prints by name:

```
vendor/bin/phpunit --testsuite Live --testdox
```

Expected output (with a working `REGOLO_API_KEY` + the default models, and `REGOLO_LIVE_AUDIO_MODEL` / `REGOLO_LIVE_TRANSCRIPTION_AUDIO_PATH` left **unset** — the package's intentional default state):

```
PHPUnit 12.x by Sebastian Bergmann.

S.......S                                  9 / 9 (100%)

Time: ~30s   Memory: 40 MB

OK, but some tests were skipped!
Tests: 9, Assertions: 53, Skipped: 2.

```

The two `S` are the audio-TTS and transcription tests self-skipping by design — Regolo's TTS catalogue is not on `/v1/models` yet (Seeweb-only model id) and transcription needs a real speech recording on disk. Set both vars and the full 9/9 runs.

If the API key is unset:

```
PHPUnit 12.x by Sebastian Bergmann.

SSSSSSSSS                                  9 / 9 (100%)

Time: ~0.1s

OK, but some tests were skipped!
Tests: 9, Assertions: 0, Skipped: 9.

```

#### What the live suite verifies

[](#what-the-live-suite-verifies)

FileWhat it asserts on the real APICost`RegoloChatLiveTest``POST /v1/chat/completions` returns non-empty `text` + non-zero token usage~200 tokens`RegoloStreamingLiveTest``POST /v1/chat/completions` with `stream: true` emits SSE → `TextDelta` events~150 tokens`RegoloEmbeddingsLiveTest``POST /v1/embeddings` returns non-empty vectors with uniform length across a batch~100 tokens`RegoloRerankLiveTest``POST /v1/rerank` orders documents by relevance, top-1 matches the obvious answerminimal`RegoloImageLiveTest``POST /v1/images/generations` (Qwen-Image) returns a valid base64 image — `image/png`, `image/jpeg`, `image/webp`, or `image/gif`, cross-checked against the canonical magic-byte signature for the gateway-claimed MIME (`Qwen-Image` empirically returns JPEG today)~€0.001`RegoloAudioLiveTest``POST /v1/audio/speech` (TTS) returns valid base64 MP3 (ID3 tag or MPEG sync word) — **self-skips** unless `REGOLO_LIVE_AUDIO_MODEL` is set, since Regolo's TTS catalogue is not on `/v1/models` yetminimal`RegoloTranscriptionLiveTest``POST /v1/audio/transcriptions` (faster-whisper-large-v3) returns non-empty `text` — **self-skips** unless `REGOLO_LIVE_TRANSCRIPTION_AUDIO_PATH` points at a real speech fileminimal**Total cost per run**: well under €0.01 with the default small-model selection. Pick a heavier text model via `REGOLO_LIVE_TEXT_MODEL` if you want to validate a specific catalogue entry — the cost scales linearly with the model.

The Regolo dashboard's **Usage** tab confirms the per-run footprint — the snapshot below is from a real `vendor/bin/phpunit --testsuite Live` invocation against the package defaults:

[![Regolo dashboard — usage report after a single live test run](resources/regolo-usage-live-test.png)](resources/regolo-usage-live-test.png)

#### CI policy

[](#ci-policy)

The live suite is **never** run from this package's `.github/workflows/ci.yml`. The matrix invokes `vendor/bin/phpunit` (default config = `Unit` testsuite). To run the live suite in your own pipeline:

```
- name: Live verification (manual workflow_dispatch only)
  if: env.REGOLO_API_KEY != ''
  env:
    REGOLO_API_KEY: ${{ secrets.REGOLO_API_KEY }}
  run: vendor/bin/phpunit --testsuite Live
```

Open an issue or PR if you want a `workflow_dispatch` job added to this repo to support scheduled live verification.

Roadmap
-------

[](#roadmap)

VersionStatusHighlightsv0.1shippedChat + streaming + embeddings + reranking + 61 tests + 6-cell CI matrix + WOW README + opt-in Live testsuite + AI vibe-coding pack. **First public release.**v0.2shippedMultimodal: image generation (`Image::of(...)->generate('regolo', ...)` against `/v1/images/generations`, default `Qwen-Image`), audio transcription (`Transcription::of($audio)->using('regolo', ...)->generate()` against `/v1/audio/transcriptions`, default `faster-whisper-large-v3`), text-to-speech (`Audio::for($text)->generate('regolo', ...)` against `/v1/audio/speech`). 82 tests / 184 assertions.v0.3plannedProvider-tools registry (Regolo-hosted web search / code interpreter, when published).v0.4exploringAdaptive routing helper — pick `cheapest` vs `smartest` model per prompt with a small classifier.v1.0trackingStable contract pinned against `laravel/ai` ^1.0 GA.Open issues and feature votes: [github.com/padosoft/laravel-ai-regolo/issues](https://github.com/padosoft/laravel-ai-regolo/issues).

Contributing
------------

[](#contributing)

Contributions are welcome — bug reports, test cases, new robustness scenarios, documentation polish.

1. Fork the repository.
2. Create a feature branch (`feature/your-thing`) targeting `main`.
3. Run `vendor/bin/phpunit` and `vendor/bin/pint --test` locally.
4. Open a PR with a clear description and a test that covers the change.

We follow the project conventions documented in [`CONTRIBUTING.md`](CONTRIBUTING.md). Please respect the existing concern split (`src/Gateway/Regolo/Concerns/`) when adding capabilities — it keeps the package legible, easy to test, and easy to align with future upstream `laravel/ai` releases.

Security
--------

[](#security)

Found a security issue? Please **do not open a public issue**. Email `security@padosoft.com` instead. We follow standard responsible-disclosure timelines documented in [`SECURITY.md`](SECURITY.md).

License & credits
---------------------

[](#license--credits)

Apache-2.0 — see [`LICENSE`](LICENSE).

Built and maintained by [Padosoft](https://padosoft.com). Initially developed alongside [AskMyDocs](https://github.com/lopadova/AskMyDocs), but the package is fully **standalone agnostic** — no AskMyDocs dependency, no Padosoft proprietary glue.

Sister packages in the Padosoft AI stack:

- [`padosoft/laravel-flow`](https://github.com/padosoft/laravel-flow) — saga / workflow orchestration for Laravel.
- [`padosoft/eval-harness`](https://github.com/padosoft/eval-harness) — RAG + agent evaluation harness.
- [`padosoft/laravel-pii-redactor`](https://github.com/padosoft/laravel-pii-redactor) — PII redaction middleware for AI prompts.
- [`padosoft/laravel-patent-box-tracker`](https://github.com/padosoft/laravel-patent-box-tracker) — Italian Patent Box R&D auto-tracker.

Each is independently usable. None requires the others. Pick what you need.

---

 Made with ☕ in Italy by [Padosoft](https://padosoft.com).

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance94

Actively maintained with recent releases

Popularity28

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

9

Last Release

29d ago

Major Versions

v0.2.2 → 1.0.02026-05-01

v0.2.3 → v1.0.12026-05-11

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/10467699?v=4)[Lorenzo](/maintainers/lopadova)[@lopadova](https://github.com/lopadova)

---

Top Contributors

[![lopadova](https://avatars.githubusercontent.com/u/10467699?v=4)](https://github.com/lopadova "lopadova (38 commits)")

---

Tags

aiai-providerai-sdklaravellaravel-ailaravel-ai-sdklaravelaillmgdprAI SDKembeddingsrerankingregoloseewebopen-modelsitalian-aisovereign-cloud

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/padosoft-laravel-ai-regolo/health.svg)

```
[![Health](https://phpackages.com/badges/padosoft-laravel-ai-regolo/health.svg)](https://phpackages.com/packages/padosoft-laravel-ai-regolo)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

815320.5k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client

Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof.

5019.3k](/packages/simplestats-io-laravel-client)[neuron-core/neuron-laravel

Official Neuron AI Laravel SDK.

11025.7k](/packages/neuron-core-neuron-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)