Laravel Semantic Search Laravel Package

Product Decisions This Supports

• Build vs. buy vs. spike for natural-language data access. This package is best treated as evidence for a feasibility decision, not as an adoption decision. A short spike answers whether static code analysis can translate English into safe Eloquent queries on your schema, or whether you need an LLM/embedding-based stack.
• Roadmap for internal admin and support tooling. Its core use case — “active users older than 25,” “count orders by status,” “customers with more than 5 orders” — maps directly to back-office list/filter/aggregate screens. That informs whether an NL query bar is worth adding to internal tools.
• Differentiation vs. commodity search. The package is query translation, not relevance ranking. It helps separate two roadmap items that are often conflated: (a) keyword/semantic search (Laravel Scout + Meilisearch/Typesense) and (b) NL-to-SQL analytics. This package only supports the latter.
• Multilingual product scope. Built-in English, Spanish, French, German, and Portuguese support is a useful data point for whether multilingual NL input is table stakes for your admin UX.
• Security and guardrail requirements. Restricted models/fields, row caps, query timeouts, and access checks are exactly the non-negotiables any NL data-access feature needs. These should become requirements regardless of vendor choice.
• Vendor and dependency risk policy. A 0.3.0 release that removed SearchEngine and QueryParser is a concrete example of pre-1.0 API churn. This supports a standing decision to wrap third-party query layers behind an internal interface and pin versions.
• Evidence check on “production-ready” claims. One GitHub star, zero dependents, and an opportunity score of ~31 are weak adoption signals. Use them to calibrate how much of the README’s “production-ready” positioning you trust in planning.

When to Consider This Package

Consider it when:

• The use case is internal and low blast radius — admin panels, support consoles, internal reporting — with a read-only database user and an allowlist of models and fields.
• You want a time-boxed spike (1–2 engineer-weeks) to measure parse accuracy on your actual schema before committing to a larger NL-search investment.
• You are on Laravel 9–11 / PHP 8.1+ and want a no-embeddings, no-ML-infrastructure path with optional OpenAI fallback for complex queries.
• Query volume is low and latency-tolerant, and results are cacheable (the package provides metadata, schema, query, and LLM caches).
• You need simple filtered and aggregate queries, not relevance-ranked semantic search.
• Your team is comfortable owning a fork and writing an evaluation suite, because the package’s maturity (README + changelog, pre-1.0, one star) implies you will be the primary maintainer in practice.

Look elsewhere when:

• The feature is customer-facing with high QPS, SLAs, or strict latency budgets.
• Data is regulated or auditable and generated SQL must be deterministic, explainable, and reviewable. Static-analysis parsing plus optional LLM fallback is hard to certify.
• Multi-tenant authorization must be enforced at the query layer; generated queries are a high-risk surface for tenant leakage.
• You actually need semantic/relevance search — embeddings, hybrid ranking, typo tolerance. Use Laravel Scout with Meilisearch/Typesense, or pgvector, instead. The package name overpromises relative to what it does.
• You need complex analytics — use a BI/semantic layer or LLM tool-calling over vetted query APIs rather than free-form NL-to-SQL.
• You require a stable production dependency. Zero dependents and breaking changes in a 0.x release mean the ecosystem has not stress-tested this API.
• You cannot absorb the real cost, which is not the Composer package but the guardrails, evaluation harness, prompt/parse tuning, and ongoing maintenance.

How to Pitch It (Stakeholders)

To executives: This is a cheap experiment, not a platform bet. I recommend a 1–2 engineer-week spike against a non-critical internal dataset to test whether natural-language querying over our Laravel models is viable without standing up vector databases or ML infrastructure. Success criteria should be concrete: at least 80–85% correct interpretation on a curated set of 50–100 real business questions, acceptable p95 latency, and zero access to restricted models or fields. Kill criteria: inaccurate parses on core entities, unsafe query generation, or maintenance cost exceeding the value. Adoption evidence is currently thin — one GitHub star, zero dependents, and a pre-1.0 breaking-change history — so we should not put it on a customer-facing critical path. The license is MIT, so the code is a low-cost reference architecture even if we do not adopt the package.

To engineering: The pitch is Laravel-native static analysis plus optional OpenAI fallback, no embeddings or training, with built-in caching, row limits, timeouts, and model/field restrictions. The ask is to evaluate it behind an internal SearchGateway interface, pin the version, run it against a read-only database user, and add an evaluation harness and query logging before any demo. Expect to fork or vendor it; the 0.3.0 release removed public classes, so we should assume API churn. Generated SQL must be treated as untrusted output.

To product and UX: A natural-language query box could lower the training burden for internal tools, but it should ship with a visible “interpreted as…” explanation and a structured filter fallback. Do not position it as an answer engine or chatbot — it translates questions into filters and aggregates; it does not summarize or reason over results. Set user expectations accordingly, and keep the scope to internal read-only workflows in the first iteration.