Ai Meta Platform Laravel Package

Getting Started

Install and pin. The package is pre-1.0. v0.15.0 has landed and, like v0.14.0 before it, the changelog is a single line: "Bump version constraints to 0.15." That is not evidence of stability; it's evidence the changelog isn't written for consumers. Two releases in a row with zero consumer-facing detail — treat that as the operating assumption, not a one-off. Install with a tight constraint and let composer.lock do the work:

composer require symfony/ai-meta-platform:^0.15 symfony/http-client

You need symfony/http-client alongside it — the bridge sits on Symfony's HTTP contracts, not on Guzzle. Installing it in a Laravel app is harmless; your existing Guzzle usage is untouched.

Where to look first. The README is still three links to Meta's prompt-format docs and nothing else, so treat the source as the documentation:

1. vendor/symfony/ai-meta-platform/src/PlatformFactory.php — the constructor you actually call.
2. The Model enum/class next to it — the exact model identifiers the bridge accepts.
3. vendor/symfony/ai-platform/src/ — the PlatformInterface, message and result types you'll be typing against.

Spend ten minutes here before writing anything. It is faster than guessing at an API with no docs. Also read the diff between the version you install and the next one before you upgrade — that is where the real documentation lives.

Wire it into the container. Keep credentials in config/services.php, never env() calls at runtime (config caching will bite you):

// config/services.php
'meta_llama' => [
    'api_key'       => env('META_LLAMA_API_KEY'),
    'default_model' => env('META_LLAMA_MODEL', 'llama3.3-70b'),
    'timeout'       => env('META_LLAMA_TIMEOUT', 60),
],

// app/Providers/AppServiceProvider.php
use Symfony\AI\Platform\Bridge\Meta\PlatformFactory;
use Symfony\AI\Platform\PlatformInterface;
use Symfony\Component\HttpClient\HttpClient;

$this->app->singleton(PlatformInterface::class, function () {
    return PlatformFactory::create(
        config('services.meta_llama.api_key'),
        HttpClient::create(['timeout' => config('services.meta_llama.timeout')]),
    );
});

Check the actual parameter order in PlatformFactory — factories across the Symfony AI bridges have shifted argument order between releases, and this one has shipped seven minors since the 0.8 line.

First use case. Start with a queued job or an artisan command doing one-shot generation against a plain string prompt. Do not start with a live chat endpoint: you want to isolate prompt formatting and response shape before adding latency and streaming to the picture.

$result = app(PlatformInterface::class)->invoke(
    config('services.meta_llama.default_model'),
    new MessageBag(UserMessage::fromText('Summarise: ' . $text)),
);

$summary = $result->asText();

Implementation Patterns

Never let the platform type leak. The single highest-value thing you can do in a Laravel app is put your own interface in front of this package:

interface LlamaClient
{
    public function complete(string $prompt, array $options = []): string;
    public function chat(array $messages, array $options = []): string;
}

Bind the Symfony-backed implementation in the container. Nine months from now, when this bridge is renamed, merged into a larger bundle, or replaced by an Ollama bridge for local Llama, you change one binding instead of grepping 40 call sites. Pre-1.0 with a thin changelog means assume churn, not abandonment.

Inject, don't resolve. Constructor-inject LlamaClient into jobs, actions, and services. Avoid app(PlatformInterface::class) outside providers — the facade-style call hides a network dependency and makes tests slow by default.

Route by model through config, not code. A multi-model strategy is the main reason to pick this package over a single-vendor SDK. Put the routing in config so product can retune it without a deploy:

// config/ai.php
'routes' => [
    'summarise' => env('AI_MODEL_SUMMARISE', 'llama3.2-3b'),
    'extract'   => env('AI_MODEL_EXTRACT', 'llama3.3-70b'),
],

Small Llama for high-volume classification and summarisation, larger variants for anything where quality is visible to the user. Keep the mapping in one place so a model rename is a config change, not a find-and-replace.

Push everything to the queue. Llama inference over HTTP is slow and variable. A job with $timeout = 90 and $tries = 3 is the correct default. Reserve synchronous calls for admin tooling you personally use.

Stream with StreamedResponse, not response()->json(). For chat UX, consume the bridge's streaming result and forward chunks over SSE. Disable middleware that buffers (VerifyCsrfToken is fine, but output buffering and some compression middlewares are not), and call fastcgi_finish_request where appropriate. If you'd rather not own SSE, broadcast chunks over a private channel and consume them in Livewire/Inertia.

Test against MockHttpClient. Inject Symfony's MockHttpClient into PlatformFactory in your test suite and assert on the request body — that's the only way to verify prompt formatting without burning API credits:

$client = new MockHttpClient(new MockResponse(json_encode([...])));
$this->app->instance(PlatformInterface::class, PlatformFactory::create('test', $client));

Keep a handful of opt-in, env-gated integration tests (@group live) that hit the real API to catch response-shape drift. Given how little the changelog says per release, these tests are your upgrade safety net, not a nice-to-have.

Use the prompt-format bridge rather than string concatenation. The whole point of the package is that it emits Llama 3 / 3.2 / 3.3 [INST]-style scaffolding correctly. The moment you start gluing <<SYS>> blocks into strings yourself, you've paid for the dependency and thrown away its value. Pass structured messages and system prompts through the platform's message types.

Gotchas and Tips

• There is no Laravel bundle. No auto-discovery, no published config, no model catalog registration. Everything — singleton binding, config keys, timeouts — is manual. Budget half a day, not half an hour, for the first integration.
• Don't try to swap in Laravel's Http facade. The bridge needs Symfony\Contracts\HttpClient\HttpClientInterface. Install symfony/http-client and move on; if you genuinely need a PSR-18/Guzzle path, use Psr18Client as the adapter rather than rewriting the factory.
• Move all symfony/ai-* packages in lockstep. v0.15.0's only change is bumping inter-package constraints to 0.15. If you also use symfony/ai-platform directly or another bridge, a mixed 0.14/0.15 set will fail Composer resolution — upgrade the whole family in one commit and re-run your live tests.
• Pre-1.0, and the changelog won't protect you. Releases arrive regularly and are often a one-line "bump version" entry, which tells you nothing about whether a signature moved. v0.14.0 and v0.15.0 are both exactly this shape — no consumer-facing detail at all. Pin to the minor, read the diff on upgrade, and keep the LlamaClient boundary so a bad release costs you an afternoon rather than a sprint.
• Model name must match prompt format expectations. Feeding a llama3.2 identifier into a code path written against 3.3 conventions produces subtly degraded output rather than an error. Centralise model identifiers in config and pair each with the prompt style it expects.
• Exceptions are Symfony's, not Laravel's. You'll get Symfony\Contracts\HttpClient\Exception\* (transport, 4xx, 5xx) — not Illuminate\Http\Client\RequestException. Catch these explicitly, map 429 and 5xx to retryable job failures, and let 4xx fail fast so a malformed prompt doesn't burn three retries.
• Retry with Laravel, not with the client. Prefer queue-level backoff() and retryUntil() over layering Symfony's retry options on top; double retries produce unpredictable request counts and muddy your rate-limit accounting.
• Handle truncation explicitly. Check finish_reason on the response. A truncated summary looks like a model quality problem and will send you tuning prompts that were never the issue.
• Cloud-only by design. This bridge targets Meta's platform; local Llama means Ollama or vLLM through a different bridge. If local hosting is on your roadmap, say so in the LlamaClient interface now so the swap is a binding change.
• Debugging without a profiler. Laravel has no Symfony profiler panel for this. Log the outgoing request and raw response behind a config('app.debug') && config('services.meta_llama.trace') flag, or attach a PSR-3 logger to the HTTP client. Without it, a formatting problem and an auth problem look identical.
• Extension points worth knowing: implement PlatformInterface yourself to add caching, logging, or a fallback-on-failure decorator; decorate the model catalog to add or alias model names; and register the whole thing as a singleton so you don't rebuild the HTTP client per job dispatch.
• The maintenance signal is the release cadence, not the changelog. The package ships steadily out of the larger symfony/ai monorepo — v0.15.0 is a pure version-sync release, which tells you the monorepo is moving even when nothing user-facing changed. You are unlikely to be stranded, but equally unlikely to get a written migration guide. Wrap it, pin it, and keep a 30-line fallback that talks to Meta's API directly with Http::withToken() so an API break is a swap rather than an outage.