Chat Hybrid Ai Laravel Package

Getting Started

Upgrade path from 1.x first, then wire identity before you touch tools — the package is only as safe as the scope you give it.

composer require siberfx/chat-hybrid-ai   # v2.0.0+
php artisan vendor:publish --tag=chat-hybrid-ai-config
php artisan migrate                        # REQUIRED in v2.0.0

Set at least one provider key and the provider list in .env:

HYBRID_CHAT_AI_PROVIDERS=anthropic,openai
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Drop the bubble into your layout (typically resources/views/layouts/app.blade.php, just before </body>):

<x-chat-hybrid-ai-bubble :identify="auth()->user()" />

Look first at config/chat-hybrid-ai.php after publishing — that's where providers, default model, and tool registration live — then routes/ to see what the bubble posts to and whether the endpoint is behind auth/web middleware as you expect.

First use case: let guests search your docs/blog through SearchRecords on a Post model, with no writes and no SQL. Confirm the bubble streams a reply, then check the admin lookup panel to see exactly what was queried. Once that's green, add FindRecord scoped to the signed-in user for order lookups.

Implementation Patterns

Provider failover. Order matters — cheapest/fastest first, most reliable last. The list is comma-separated and tried in sequence:

HYBRID_CHAT_AI_PROVIDERS=groq,anthropic,openai

Use ollama locally to avoid burning tokens during development, and keep a hosted provider as the final fallback.

Site search without SQL. SearchRecords is the workhorse. Register it per model with the columns you're willing to expose:

SearchRecords::make(Post::class)
    ->searchable(['title', 'excerpt'])
    ->limit(5);

Swap LIKE for Scout when volume grows — the API is the same, but results and ranking change, so re-verify relevance after switching.

Scoped record lookup. FindRecord is the tool that needs the most care. It relies on the signed identity to build the query constraint:

<x-chat-hybrid-ai-bubble :identify="auth()->user()" />

or, in a controller/middleware for non-Blade entry points:

HybridChat::identity(auth()->user());

For guests, the package confirms identity out-of-band before returning anything — treat that confirmation as a security boundary and test it explicitly (e.g. guest asks "where is my order #1234" → must not leak another customer's record).

Deterministic business rules via Check. Anything you'd otherwise be tempted to let the model reason about should be a closure:

Check::make('coupon_valid')
    ->describe('Whether a coupon code is currently valid')
    ->using(fn (string $code) => Coupon::where('code', $code)->valid()->exists());

Same for delivery windows, stock availability, refund eligibility. Closures must be read-only and fast — they run inline with the request.

Human handoff. request_human doesn't do anything on its own; wire it to your existing support channel (ticket creation, Slack webhook, Log::channel('support')) via the config's handler. Otherwise the agent politely promises a human and nothing happens.

Compose with native laravel/ai tools. WebSearch and SimilaritySearch register like any other tool, which is the cleanest way to add RAG over your vector store without writing a bespoke tool.

Admin audit. The lookup panel under each AI reply is your primary debugging surface — it shows every SearchRecords/FindRecord/Check invocation. Gate it behind your existing admin middleware; don't rely on the package to hide it.

Gotchas and Tips

• Breaking in 2.0.0: the bespoke anthropic and openai drivers are gone, replaced by laravel-ai. If you pinned driver names in config or referenced driver classes in your own code, migrate to the laravel-ai driver and provider strings (HYBRID_CHAT_AI_PROVIDERS). Anything extending the old driver interfaces will fatal.
• php artisan migrate is not optional. Skipping it leaves the agent unable to persist conversations/lookups and produces confusingly generic errors rather than a schema exception.
• Identity must be resolved per request. Setting HybridChat::identity() in a service provider or caching it will leak one user's scope into another's session under Octane/queue workers. Set it in middleware or the Blade component only.
• Never expose raw Eloquent models to a tool. Return arrays or resources with $hidden/$visible respected; FindRecord on a User model with a password column is the classic footgun.
• Searchable columns are a public surface. The AI will echo back whatever you list. Audit ->searchable([...]) the same way you'd audit a JSON API response.
• Tool descriptions drive behaviour. Vague describe() strings cause the agent to pick the wrong tool or skip tools entirely. Write them as you would for a new hire.
• Closures run inline — no queue, no timeout guard beyond your PHP limits. Keep lookups indexed; a slow closure stalls the streamed reply.
• Failover hides provider outages but also hides cost. Log which provider answered (the audit panel shows it) and alert if you're silently pinned to the expensive one.
• Debugging empty replies: check provider keys first, then whether the tool registry is actually loaded (a tool that throws during registration often degrades to "no tools" rather than a hard error). Log::debug around your Check closures is the fastest confirmation they're being invoked.
• Extension points: the config file for provider/model defaults and tool registration, the published views for bubble markup/styling, and laravel/ai's tool contract for anything custom — prefer the documented tool classes over subclassing package internals, which are the most likely to break again in a minor release.
• Guests + FindRecord: test with a different guest session before shipping. Confirmation flows that trust the session rather than a verified token are the usual failure mode.