knobik/sql-agent
Self-learning text-to-SQL agent for Laravel that turns natural language into accurate SQL using knowledge bases, memory, and live schema context. Includes SQL safety guardrails and a built-in chat UI.
Architecture fit. This is a Laravel-first package, which matters more than the star count: it installs via Composer + Artisan, ships a facade (SqlAgent::run() returning a structured AgentResponse with answer, sql, results), and hooks into the framework's event system and config. For a Laravel product team, the integration surface is small and idiomatic — no sidecar service, no new language runtime. The package sits on top of Prism PHP for LLM abstraction, which buys provider portability (OpenAI, Anthropic, Gemini, Ollama, Mistral, xAI) but adds a second young dependency to the trust chain. The architecture is explicitly layered: three static context layers preloaded into the system prompt (table metadata, business rules, known-good SQL), a self-learning layer accumulated at runtime, and two on-demand tool layers (live schema introspection, custom institutional-knowledge tools). That separation is the most product-relevant thing about the package, because it tells you where your leverage is: the knowledge base is a content asset you own, not code you inherit.
Integration feasibility. The facade is a clean seam — you can wrap it in an internal TextToSqlService interface on day one and insulate the product from beta API churn. The Livewire chat UI is optional and, for a product surface, probably something to skip in favor of an API endpoint with your own front end. The genuine accelerant is the shipped evaluation framework: automated accuracy testing against a query set is the thing most teams fail to build when they hand-roll text-to-SQL, and it converts "does the agent work?" from a demo into a release gate. Two feasibility caveats. First, semantic retrieval quality depends on pgvector (PostgreSQL + embeddings); the fallback is database full-text search, which is materially weaker on synonym-heavy business language. Second, sql-agent:install scaffolds a knowledge directory you must then populate — the install is minutes, the curation is weeks.
Technical risk. Ranked by expected damage:
Key questions. What is the accuracy threshold, on which query set, and who signs off? Can we obtain a read-only database role and treat the package's guardrails as defense-in-depth rather than the primary control? Who owns knowledge-base curation as a standing responsibility, and what is the review SLA? Do we require per-tenant isolation, and does multi-connection support satisfy it? What is the user-facing fallback when the agent fails or times out? Which provider/model do we standardize on, and what is the cost ceiling per question? What is our fork-and-own contingency if the maintainer goes quiet?
Stack fit. Requires PHP 8.2+, Laravel 11 or 12, and Prism PHP (auto-installed). The decision that shapes everything downstream is the search driver: if you are already on PostgreSQL, enabling pgvector is the right call and makes this a one-database integration; on MySQL you fall back to full-text search and should expect to compensate with a denser, more synonym-rich knowledge base. Point the agent at a read replica with a read-only role — this also cleanly bounds the blast radius of any guardrail bypass. For the product surface, expose an authenticated API endpoint rather than shipping Livewire; keep the Livewire UI as an internal debug tool for the team curating the knowledge base.
Migration path. Phase 0: pin the version explicitly (not a loose caret) and wrap the facade behind your own interface. Phase 1: install to staging against anonymized data, load metadata and business rules for one bounded domain — a reporting or analytics module, not the primary transactional flow. Phase 2: build a 30–50 question golden set with known-correct answers and use the built-in evaluation framework to establish a baseline accuracy number per model. Phase 3: ship behind a feature flag to a small internal cohort with a thumbs-down affordance; capture every failure with the generated SQL so triage is possible. Phase 4: promote to a user-facing surface only after the golden set clears your threshold twice across releases.
Compatibility. Version-sensitive: the 0.x series has already changed internals (SearchManager replacing QueryPatternSearch in 0.8.0) and added multi-connection support in 0.6.0. Assume breaking changes and budget a re-evaluation run on every minor bump. The package's database support (MySQL, PostgreSQL, SQLite, SQL Server) is broad, but your joins and window functions are exactly where generated SQL degrades — validate on your actual schema, not the demo. Prism PHP's own release cadence is a second compatibility axis to watch.
Sequencing. Do not sequence this as "integrate, then tune." Sequence it as: knowledge-base scaffolding and golden-set authoring first (they are the real work and must exist before you can measure anything), then a thin API wrapper, then an eval-gated rollout. The TPM's sequencing job is to protect the evaluation workstream from being treated as a nice-to-have — it is the only thing that turns a demo into a shippable capability.
Maintenance. Three recurring costs, all of them owned by someone. (1) Knowledge-base drift — every schema migration, renamed column, or changed business definition invalidates curated context; wire schema introspection refresh into your migration/post-deploy hooks and assign a named curator. (2) Learning curation — review accumulated learnings on a cadence, promote good ones, delete bad ones; treat this as a small editorial backlog, not an automated process. (3) Dependency tracking — Prism, Laravel, and provider model deprecations all move under you; a quarterly re-run of the golden set is the minimum.
Support. The package ships solid reference documentation (config, commands, API, tools, events, troubleshooting), so the ramp for a Laravel developer is short — a spike in days, productive work in one to two weeks. What the docs cannot give you is prompt and retrieval tuning skill; plan for one person to develop genuine expertise in the knowledge base and evaluation loop, because that is where accuracy comes from. Tier-1 support needs a documented fallback path and a way to surface the generated SQL alongside the answer, so users can self-diagnose and support can triage without reading LLM transcripts.
Scaling. The bottleneck is not your database, it is the LLM: rate limits, per-question cost, and multi-second latency. Concurrency beyond your provider tier will queue. Mitigate with aggressive caching of repeated questions and their results, routing simple questions to a cheaper model and reserving the strong model for the tool loop, and asynchronous execution for anything non-interactive. Long-running concerns: context window pressure as the knowledge base grows (every one of layers 1–3 goes into the system prompt), which argues for disciplined scoping of what gets curated rather than dumping the whole schema in.
Failure modes. Enumerate and instrument them: LLM outage or rate-limit (needs graceful degradation to "unavailable, try again" — never a partial answer); timeout on the agentic loop; hallucinated columns or joins (caught only by evaluation and user feedback); plausible-but-wrong aggregates (the dangerous one — mitigate with result spot-audits on high-value questions and showing generated SQL in the UI); guardrail bypass or restricted-table leakage (mitigate with read-only credentials); knowledge poisoning from unreviewed learnings; cost runaway from a single verbose user session (set per-session and per-day budgets with alerts); and prompt injection via user input. Build a dashboard from day one covering accuracy on the golden set, per-question cost, p95 latency, error rate, and thumbs-down rate — those five metrics are the operational contract for this feature, and without them you cannot tell whether the self-learning loop is helping or quietly degrading the product.
How can I help you explore Laravel packages today?