Sql Agent Laravel Package

Product Decisions This Supports

• Build vs. buy for natural-language analytics. This package is effectively a pre-built text-to-SQL stack: schema introspection, prompt/knowledge management, tool-calling agent loop, guardrails, chat UI, and an evaluation harness. If the roadmap contains any "ask your data a question" surface, the honest comparison is not "build vs. this" but "spend 1–2 quarters building vs. spend days integrating and a few weeks hardening."
• Whether to expose data to non-technical users at all. The Knowledge Base layers (table metadata, business definitions, known-good query patterns) are the product lever: they decide whether "revenue" means bookings or recognized revenue. That's a product/analytics-ownership decision, and the package makes it a file-based, reviewable artifact rather than a prompt buried in code.
• Support-deflection and internal-tooling roadmap. Strongest near-term fit is internal: CS/support triaging "how many orders are stuck," ops pulling ad-hoc counts, analysts offloading repetitive requests. Lower-risk than customer-facing, and it generates the query corpus you'd need for any future public feature.
• Self-hosted vs. vendor BI assistant. Because it supports Ollama and any Prism provider, this is a genuine option for teams with data-residency constraints that rule out sending schema and sample rows to a third-party NL2SQL SaaS. That's a procurement/legal-driven decision this package unblocks.
• Scope of the "AI feature" bet. The package deliberately exposes both a Livewire UI (demo/ops tool) and a facade/API (embedded feature). Choosing one or both is a product decision with very different surface area, support burden, and failure modes.
• Investment in the feedback loop. Self-learning only pays off if wrong answers are surfaced and corrected. Deciding to ship a "this is wrong" affordance and staff review time is a product commitment the package can support but cannot make for you.
• Read-only analytics vs. write access. Configurable statement restrictions and row limits mean you can ship read-only first. Whether the agent ever gets write/DDL reach is a risk decision this package lets you defer rather than foreclose.

When to Consider This Package

Consider adoption when:

• The stack is Laravel 11/12 on PHP 8.2+ and the team is comfortable with a Composer + Artisan install and a config file.
• The use case is read-only analytical Q&A over a schema you understand well — reporting, internal dashboards, support tooling, "how many / top N / trend" questions.
• You can invest in the Knowledge Base (metric definitions, business rules, curated query patterns). Without this, accuracy will disappoint; with it, this is the package's main differentiator.
• Your database is MySQL, PostgreSQL, SQLite, or SQL Server on a Laravel connection, and latency tolerance is seconds, not milliseconds.
• You need model flexibility or must self-host inference (Ollama) for privacy or cost reasons.
• You want a working prototype in days to test demand before committing engineering headcount — and you're explicitly treating it as an evaluation, not a foundation.
• You're prepared to pin the version, read the source, and fork if necessary. This is a small-maintainer, single-author package.

Look elsewhere (or build) when:

• You need enterprise support, an SLA, a security review with vendor backing, or a deprecation policy. There is one maintainer, 19 stars, 0 dependents, and no third-party production track record.
• You require API stability. The README itself flags beta; the 0.5→0.9 release cadence shows breaking changes (SearchManager replacing QueryPatternSearch, multi-connection support) landing in minor versions. Anything you build against the facade needs a compatibility buffer.
• The target is customer-facing, high-volume, latency-sensitive Q&A. Per-query LLM calls plus a tool loop mean cost and tail latency you'll have to engineer around (caching, async, cheaper models) — work that erodes the buy-vs-build savings.
• The schema is enormous, heavily permissioned, or riddled with ambiguous naming. Row-level authorization per user is a hard problem; the package's table restrictions are a blunt instrument, not a multi-tenant ACL.
• You need guaranteed correctness for anything financial or regulatory. Text-to-SQL will be confidently wrong sometimes; if a wrong answer is unacceptable rather than annoying, this isn't the tool.
• The team won't own an evaluation suite. The package ships the framework, but someone must write the question/expected-answer pairs and keep them green through schema drift.
• You need deep Postgres-specific optimization, warehouse-scale (BigQuery/Snowflake) targets, or complex multi-hop query generation beyond what a tool loop handles reliably.

Also worth flagging: the 0.9.1 fix for restricted tables leaking through references on permitted ones is a reminder that the safety layer is young. Treat any table-restriction config as unproven until you've adversarially tested it in staging.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can test a natural-language data assistant without a build project. knobik/sql-agent is an Apache-2.0 Laravel package that turns plain-English questions into SQL against our existing database, with a guardrailed read-only path, a working chat UI, and — critically — a way to teach it our business definitions so "active customer" means what we say it means. A pilot is roughly a week of integration plus a few weeks of curating definitions and building an accuracy test suite. The trade-off is maturity: it's beta, maintained by one developer, with no enterprise support. So the ask is a time-boxed, read-only internal pilot on non-critical data — deliberately scoped so that if the package stalls or the accuracy isn't there, we've lost weeks, not a quarter, and we keep the evaluation suite and definition work either way. The decision this informs is whether to buy, build, or shelve an NL-analytics feature at all.

For engineering: Laravel 11/12, PHP 8.2+, installs via Composer + Artisan, LLM access through Prism (OpenAI, Anthropic, Gemini, Mistral, xAI, Ollama). Usage is a facade call returning answer/SQL/results, or a Livewire chat UI if we want something demoable immediately. Six-layer context: three knowledge layers loaded into the prompt, self-learned error fixes accumulated over time, live schema introspection and custom tools on demand. Read-only enforcement and row limits are configurable. The facade is mockable, which keeps our own test suite clean. Two things we own: pin the version (beta, breaking changes in minors — plan for a fork-and-patch path or a thin adapter around the facade), and adversarially test the table-restriction guardrails before anyone points this at production data. Also budget for LLM cost/latency observability from day one — per-query spend and p95 latency are the metrics that decide whether this scales past the pilot.

For the analytics/data team: The package's leverage is the Knowledge Base, and that's your artifact. Table and column metadata, metric definitions, business rules, and a set of SQL queries known to be correct — all versioned as files, reviewable in a PR, and owned by the people who actually define the numbers. The self-learning layer records error/fix pairs as the agent recovers, which is useful but needs periodic review, not blind trust. The evaluation framework is the real deliverable: a question set with expected answers that runs on demand. That suite is valuable independent of whether we keep the package, because it's the only way to know if schema drift or a model swap quietly broke things.