Ai Laravel Package

Product Decisions This Supports

• Build vs. buy for our AI integration layer. laravel/ai is an MIT-licensed, Laravel-maintained abstraction over OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI, Mistral, Groq, xAI, DeepSeek, Cohere, OpenRouter, VoyageAI, and any OpenAI-compatible endpoint. The build path is a bespoke internal wrapper plus per-provider HTTP clients; the buy path is one dependency we do not maintain. This package is the buy option and it materially shortens the estimate on any AI-adjacent roadmap item.
• Provider optionality as a contractual position. Because the SDK normalizes request/response shapes, provider choice becomes configuration rather than architecture. That gives us leverage in pricing and terms negotiations, and it lets us answer data-residency or procurement questions (Bedrock/Azure) without a rewrite.
• Feature scoping across the full AI surface, not just chat. One dependency covers agents and tools, structured JSON output, streaming (including SSE routes and broadcasting), queued generation, image generation, TTS, STT, embeddings with caching, reranking, file storage, and vector stores. That means we can spec an "AI features" epic as a coherent set rather than a series of unrelated integrations.
• Reliability and cost requirements are expressible as product requirements. Built-in failover on provider/gateway errors, per-prompt provider/model/timeout overrides, embeddings caching, and per-run usage reporting (invocation IDs, tool timing, terminal failures) map directly to SLOs, unit-economics targets, and support triage needs. We can write "AI features degrade gracefully on provider outage" into a spec and have it be implementable.
• Human-in-the-loop as a compliance lever. The 0.10 line added human-in-the-loop and polymorphic conversation participants. Any feature with real-world side effects (sending email, issuing refunds, mutating records) can ship with an approval gate rather than being blocked by risk review.
• Test strategy and CI spend. First-class fakes (Agent::fake, assertPromptedTimes, fakes for images/audio/transcription/embeddings) mean the test suite does not call paid APIs. This is a budget line and a velocity decision: deterministic tests in CI, live calls only in a small eval suite.
• Team topology. It lets a PHP/Laravel team own AI features end to end, avoiding a Python service and the associated handoff, deployment, and on-call overhead.

When to Consider This Package

Adopt when most of these hold:

• We are on Laravel (roughly 11/12-era) and the AI work is application-embedded — chat, summarization, extraction, classification, search, media generation — rather than model training.
• We want more than one provider, or want failover, or want to keep the ability to switch providers within a quarter.
• The team is PHP-first and adding a second runtime is genuinely expensive.
• We need the boring-but-critical plumbing (queues, streaming, retries, caching, conversation persistence, fakes) and do not want to own it.
• The AI surface is broad but each individual feature is moderate in complexity — the abstraction pays off across many small integrations.

Look elsewhere or wait when:

• The feature is a durable, multi-year platform commitment. This is a 0.x package: it moved 0.9 → 0.10 → 0.11 in weeks, and the changelog contains behavioral changes (stream errors now throw instead of ending silently; failover trigger conditions expanded; default Gemini models bumped). Plan for pinning versions, reading every changelog, and budgeting upgrade work — the addition of Rector automation is a signal that automated refactors are expected to be needed.
• We need day-one parity with a provider's newest capability. An abstraction lags native SDKs by design; anything on the frontier belongs behind a direct integration until the SDK catches up.
• The workload is heavy RAG/agent orchestration at scale — complex graph orchestration, custom retrieval pipelines, evaluation harnesses. LangChain/LlamaIndex or a Python service remains the better fit.
• Inference must be self-hosted or on-prem. Confirm provider coverage against your actual constraint before committing.
• We require vendor-backed SLAs and support contracts. MIT and community maintainership means no commercial support path.
• We are not on Laravel, or the surrounding platform is polyglot and the AI service should be language-agnostic.
• Ecosystem maturity matters to us. Packagist shows zero dependents — good in that churn is contained, but it also means few battle-tested downstream patterns to copy and a thinner pool of community answers.

Mitigation for adoption regardless: wrap our own thin domain layer over the SDK (our SupportAgent, DocumentClassifier classes own the SDK calls) so that a 0.x breaking change or a future swap is a localized diff.

How to Pitch It (Stakeholders)

For executives: This is Laravel's official AI SDK — MIT licensed, no vendor fee, maintained by the framework team. It turns AI from a bespoke integration project into a configuration exercise, covering text, images, audio, transcription, embeddings, search, and file handling behind one API across a dozen providers. The commercial value is threefold: (1) time-to-market, because we stop rebuilding per-provider plumbing; (2) cost control, through model routing per request, embeddings caching, and per-run usage reporting; (3) leverage, because switching or multi-sourcing providers becomes a config change rather than a re-platforming project. The trade-off is explicit and manageable: the package is pre-1.0, so we pin versions, budget modest upgrade effort each quarter, and keep our own thin wrapper so no single dependency becomes load-bearing.

For engineering: Idiomatic Laravel — an Agent class with Promptable, HasStructuredOutput for typed JSON, RemembersConversations for persisted history, ->queue()->then() for async, ->stream() returning SSE from a route. Providers, models, and timeouts are overridable per prompt; failover across providers is built in. Tool calling, provider-hosted tools, web search/fetch, middleware, MCP, and human-in-the-loop approval are supported. Observability is improving quickly — a single invocation ID threads an entire agent run, with per-step and per-tool reporting and terminal failure reporting on the run context. Fakes exist for every generation type, so CI is deterministic and doesn't burn API credits. Known costs: it's 0.x, defaults change between minors, and stream errors now throw rather than failing silently — read the changelog on every bump.

Recommendation: Pilot on one internal, low-blast-radius feature with a pinned version and our own domain wrapper. If the upgrade cadence and abstraction coverage hold up over one quarter, standardize on it for application-level AI across the Laravel estate; keep frontier-capability and heavy-orchestration work outside the abstraction.