Chat Hybrid Ai Laravel Package

Product Decisions This Supports

• Build vs. buy for an in-app assistant. This package is a credible "buy/assemble" option: instead of building a chat UI, provider plumbing, tool-calling layer, identity scoping, and human handoff from scratch, a team can ship a scoped assistant inside an existing Laravel app in days. The decision this most directly informs is whether an AI support/assistant surface is a differentiator worth custom building or a commodity capability worth dropping in.
• Roadmap sequencing for self-serve support. The combination of SearchRecords, FindRecord, Check, and request_human maps cleanly to a phased roadmap: (1) answer from docs/site search, (2) answer account-specific questions for signed-in users, (3) automate deterministic checks (coupon validity, delivery windows), (4) escalate to humans. That is a defensible maturity path rather than a big-bang AI launch.
• Provider strategy and cost/continuity risk. HYBRID_CHAT_AI_PROVIDERS=anthropic,openai with failover plus support for 13+ providers (including Ollama and any OpenAI-compatible endpoint) turns model choice into a config decision, not an architecture decision. This supports negotiating on price/latency and de-risking a single-vendor outage or deprecation.
• Data access governance as a product constraint. The "tools read your data, the AI never writes SQL" design, plus signed visitor identity (auth()->user()), is a product-level safety boundary: it constrains the assistant to read-only, per-visitor-scoped lookups. That is the decision that makes an AI agent approvable in a product with customer PII, and it sets a clear "no autonomous writes" scope for v1.
• Trust and support operations. Admins seeing every lookup under the AI's reply is an auditability feature. It supports a decision to run a hybrid model (AI first, human on request) with observable behavior, rather than an unattended bot.
• Upgrade planning itself. v2.0.0 is a breaking release (drivers replaced by laravel-ai, new migration). If the package is already in use, this is a scheduled migration decision, not a routine bump.

When to Consider This Package

Consider adoption when:

• You have an existing Laravel application with Eloquent models the assistant should answer from (orders, accounts, catalog, tickets) and you want the assistant embedded in your own product, not in a third-party helpdesk.
• You want a drop-in chat bubble (<x-chat-hybrid-ai-bubble>) rather than a custom front end, and you are comfortable with Blade/Livewire-style integration.
• Human handoff is a requirement, not a nice-to-have — request_human plus the hybrid model is the core value proposition.
• You need per-visitor data scoping (signed-in identity; guest confirmation flows) and an admin-visible audit trail of lookups.
• Provider flexibility or failover matters — multi-provider config, Ollama for self-hosting, or OpenAI-compatible endpoints for a gateway/proxy setup.
• You are on or can move to the Laravel AI SDK and can absorb a migration and schema change.

Look elsewhere when:

• The app is not Laravel/PHP, or the team is unwilling to take a dependency on laravel-ai as the default driver.
• You need autonomous write actions (refunds, cancellations, record mutation). This package is deliberately read-only at the tool layer.
• You need a full agent workspace: SLA routing, queues, canned responses, CSAT, workforce analytics, multi-channel (email/voice/social). That is a helpdesk product, not this.
• You require enterprise compliance artifacts (SOC 2, HIPAA BAAs, data residency guarantees) at the vendor level; here you own the data path and the compliance posture yourself.
• You need heavy retrieval infrastructure — large-corpus semantic search, embedding pipelines, re-ranking. SimilaritySearch and Scout support exist, but if retrieval quality is the product, you will be building that layer regardless.
• Your team cannot run migrations and manage a major-version upgrade on the required cadence.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, Laravel-native way to put an AI assistant in front of customers that answers from our own data without us building an AI stack. It deflects repetitive support questions, escalates to a human on request, and keeps every lookup auditable. Model choice is a config line, so we are not locked into one AI vendor and can fail over if one goes down. The scoping rules mean the assistant only shows people their own records, which is the control that makes this approvable.

For engineering: v2.0.0 rebases the agent on the Laravel AI SDK, replacing the bespoke anthropic/openai drivers with a laravel-ai default and adding multi-provider failover. Tools are closures — SearchRecords (LIKE or Scout), FindRecord (scoped to signed-in visitor or guest-confirmed), Check (arbitrary validation logic), request_human, plus any laravel/ai tool including WebSearch and SimilaritySearch. The AI never writes SQL; all data access is through these declared tools. Breaking changes: driver config changes and a required php artisan migrate. Plan the upgrade as a real migration with a staging pass, and review the tool scopes before enabling identity for signed-in users.