Weave Code
Laravel Ai Bridge Laravel Package
tetrixdev/laravel-ai-bridge
laravel-ai-bridge is a lightweight Laravel package for connecting your application to AI services through a simple, unified bridge. It helps you organize AI provider configuration and keep prompt/response integrations clean and maintainable.
Laravel package for AI Bridge — unified streaming interface for CLI Bridge, BYOK, and managed AI modes
Frequently asked questions about Laravel Ai Bridge
- How do I install and set up tetrixdev/laravel-ai-bridge?
- Install it with Composer using composer require tetrixdev/laravel-ai-bridge. The package ships a service provider and a config file, so publish the config and set your bridge connection details and mode. It acts as a Laravel-side abstraction over an external ai-bridge service, so you also need that service reachable from your app. Once configured, you can hit the bundled conversation routes or call the PHP client API directly from your own controllers and services.
- Do I need the external ai-bridge service running to use this package?
- Yes. laravel-ai-bridge is a thin HTTP client, service provider and configuration layer over an external ai-bridge service rather than a self-contained AI implementation. The evaluation notes a hard dependency on ai-bridge 0.32.0 or higher for features like effort to work at all. That makes upgrades a coordinated cross-service release rather than an independent Composer bump. If the bridge is unreachable, the package's conversation routes cannot return model output.
- What is the difference between CLI Bridge, BYOK, and managed AI modes?
- The package offers three modes behind one unified streaming interface: CLI Bridge, BYOK (bring your own key), and managed AI. Which mode you use determines where credentials live and who owns provider billing and routing. The modes are not fully interchangeable at the feature level, so any feature you expose in your UI should branch on mode rather than assuming parity. For example, the effort option is only transmitted for Claude conversations and is never sent in BYOK or managed mode.
- How do I stream AI responses into my Laravel app with this package?
- The bridge exposes a streaming conversation route plus a connection-status endpoint, so you can relay tokens to the browser as they arrive. The bundled Blade component, x-ai-bridge::chat, handles the streaming details for you and sends the required token itself. If you build a custom front end or JS proxy, you own that token handling and any request payload changes. Keep those custom consumers in lockstep with package upgrades, since route contracts can tighten between minor versions.
- How does the effort option work and which providers support it?
- Effort is a pass-through value placed in ai_request.options.effort and forwarded to the bridge, with no extra persistence or schema changes. It only affects Claude conversations; BYOK and managed mode never transmit it, so an effort control in your UI will silently do nothing unless you branch on provider and mode. Available levels are discovered from the bridge's effort_levels field on the connection-status endpoint rather than hardcoded, which keeps you forward compatible. The conversation route validates the value against a narrow lowercase-token pattern and returns 422 if it does not match.
- What are the Laravel and PHP requirements for laravel-ai-bridge?
- Supported setups explicitly require laravel/framework, so confirm the exact constraint in the package's composer.json before planning an upgrade. The package is a lightweight HTTP client and service-provider layer, so it has no database migrations or domain model of its own. You should also check the required ai-bridge service version, since some features depend on bridge-side support. Verify both constraints in CI rather than relying on documentation alone.
- Why does my MCP relay route return 422 tool_call_id_required?
- Since v0.21.0 the browser-facing MCP route requires a tool_call_id, which ties a relayed call to a tool card that was actually shown in the conversation. This is a deliberate data-integrity constraint on the relay path, not a transport detail. The PHP client API keeps tool_call_id optional so trusted server-to-server code remains ergonomic. Any non-PHP consumer, such as a JS proxy, webhook bridge, or custom front-end relay, must be updated before you deploy the new package version.
- How does CSRF protection work in v0.21.0 and can I turn it off?
- The package enforces CSRF tokens on its own state-changing browser routes, such as the MCP and upstream sign-in endpoints, and it owns that check because it owns the browser-facing surface. It is strict by default: it ignores your app's allowSameSite setting and CSRF except list, and applies even to cookie-authenticated requests with no started session. Only token-authenticated calls such as bearer tokens or Sanctum personal access tokens bypass the check. Upstream route protection is configurable and on by default, while broader route coverage is off by default and becomes the default in the next major, so teams with existing exemptions on those paths need to plan accordingly.
- Why did my requests start using a different model than the conversation's stored model?
- A per-turn model now takes precedence over the conversation's stored model; previously the stored model was authoritative. Any caller that passes a model field incidentally, or that relied on a conversation's pinned model for cost or quality guarantees, will now silently route differently. Audit your callers for stray model parameters before upgrading, and pin the model explicitly wherever behaviour must be predictable. The package's decision records document the rationale, which is useful evidence for change review.
- How do I test AI integrations in my Laravel suite without hitting real providers?
- Because the package is an HTTP client with config and no persistence, you can point it at a stubbed bridge endpoint in your test environment and assert on the outgoing request payloads. That lets you cover effort pass-through, tool_call_id behaviour, and mode-specific branching without live model calls. Use the connection-status endpoint's advertised effort_levels to drive capability-negotiation tests instead of hardcoding level names. Also add a test asserting your own CSRF expectations, since the package applies its own policy independently of your app's exemptions.
Weaver
How can I help you explore Laravel packages today?