Write a sovereign provider

Goal. Add a real AI transport — Regolo (EU), Ollama (on-prem), or your own sovereign endpoint — without
touching the governance layer. You implement one tiny interface and rebind it; redaction, the hallucination
guard, and audit keep running above it unchanged.

The contract

Padosoft\Iam\Ai\Contracts\AiProvider is deliberately minimal — two methods:

interface AiProvider
{
    /** Identifier for audit/telemetry: 'regolo' | 'ollama' | 'deterministic' | … */
    public function name(): string;

    /** Complete a prompt (system + user) and return the model's raw text. */
    public function complete(string $system, string $user): string;
}

The complete() you implement receives an already-redacted prompt and should return raw model text. You do
not redact, guard, or audit — the AdvisoryClient does that around your call.

Implement it

use Padosoft\Iam\Ai\Contracts\AiProvider;
use Illuminate\Support\Facades\Http;

final class MySovereignProvider implements AiProvider
{
    public function __construct(
        private readonly string $endpoint,
        private readonly string $model,
    ) {}

    public function name(): string
    {
        return 'my-sovereign'; // shows up in the Advisory + audit as the provider
    }

    public function complete(string $system, string $user): string
    {
        $response = Http::timeout(20)
            ->baseUrl($this->endpoint)
            ->post('/v1/chat/completions', [
                'model'    => $this->model,
                'messages' => [
                    ['role' => 'system', 'content' => $system],
                    ['role' => 'user',   'content' => $user],
                ],
            ])
            ->throw(); // let it throw — AdvisoryClient catches it and falls back deterministically

        return (string) data_get($response->json(), 'choices.0.message.content', '');
    }
}

Rebind it

Bind your provider in a service provider’s register() (after the module’s provider has registered its default
DisabledProvider):

use Padosoft\Iam\Ai\Contracts\AiProvider;

public function register(): void
{
    $this->app->bind(AiProvider::class, fn () => new MySovereignProvider(
        endpoint: config('services.my_sovereign.endpoint'),
        model:    (string) config('iam-ai.model'),
    ));
}

Then turn the module on:

IAM_AI_ENABLED=true
IAM_AI_PROVIDER=my-sovereign
IAM_AI_MODEL=your-model

Verify with a fake first

The test suite shows the seam clearly — you can drive the whole pipeline with an anonymous provider:

$provider = new class implements AiProvider {
    public function name(): string { return 'fake'; }
    public function complete(string $s, string $u): string {
        return 'Explanation citing dec_ABC12345.';
    }
};

$client = new AdvisoryClient($provider, new Redactor, new HallucinationGuard, app(AuditRecorder::class));
config(['iam-ai.enabled' => true]);

$advisory = $client->advise('t', 'sys', 'explain', [], ['dec_ABC12345'], 'fallback');
$advisory->aiUsed;      // true
$advisory->guardPassed; // true

Checklist

Gotchas

See also

• Sovereign by default
• The advisory pipeline
• PHP API — the AiProvider and DisabledProvider reference.