laravel-ai-regolo

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

📚 Public docs: doc.laravel-ai-regolo.padosoft.com

Table of contents

1. Why this package
2. Design rationale
3. Features at a glance
4. See it in action — laravel-ai-chat demo
5. Comparison vs alternatives
6. When to use Regolo vs OpenAI
7. Installation
8. Quick start
9. Usage examples
10. Configuration reference
11. Architecture
12. 🚀 AI vibe-coding pack included
13. Testing
    • Default suite — offline
    • Running the live test suite
14. Roadmap
15. Contributing
16. Security
17. License & credits

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 — 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

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

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

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 for the full audit.

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

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 note). The reverse is true too: lopadova/askmydocs and padosoft/askmydocs-pro consume this package, never the inverse.

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.
• 94 unit tests / 196 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 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.

See it in action — laravel-ai-chat demo

Want to see this package powering a real ChatGPT-style chatbot? padosoft/laravel-ai-chat is a runnable, MIT-licensed demo on Laravel 13 + React that drops this provider behind the Vercel AI SDK UI (@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.

▶ Open the demo on GitHub →

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

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

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

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

• 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

• 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) 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

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

This is also why the Comparison table above 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

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):

In your .env:

Quick start

That's it. Five lines.

Usage examples

Chat completion

Streaming (token-by-token)

Streaming with a Vercel AI SDK UI frontend

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

Tool calling

Embeddings (single + batch)

Reranking (Cohere/Jina-shaped)

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

Architecture

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

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

Every release of this package includes the Claude Code, the agent automatically picks up the pack and applies it.

What ships in the pack

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

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?

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

Default suite — offline, zero cost, runs everywhere

The package ships 94 unit tests / 196 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.

Coverage breakdown:

The test inventory and the rationale for each robustness scenario is documented in 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)

If you want to verify behaviour against the real Regolo servers — for example you are a Seeweb / 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

regolo.ai → sign up → copy your rg_live_... key.

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

Step 2 — create a new key and copy it:

2. Configure the environment

The bare minimum is a single env var:

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

On Windows PowerShell — single var:

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 <php><env> in phpunit.xml) hands it — so a small loader is the standard pattern:

PowerShell:

Bash / zsh:

3. Run the live suite

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

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):

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:

What the live suite verifies

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:

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:

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

Roadmap

Open issues and feature votes: github.com/padosoft/laravel-ai-regolo/issues.

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. 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

Found a security issue? Please do not open a public issue. Email [email protected] instead. We follow standard responsible-disclosure timelines documented in SECURITY.md.

License & credits

Apache-2.0 — see LICENSE.

Built and maintained by Padosoft. Initially developed alongside 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 — saga / workflow orchestration for Laravel.
• padosoft/eval-harness — RAG + agent evaluation harness.
• padosoft/laravel-pii-redactor — PII redaction middleware for AI prompts.
• 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.}