Laravel Semantic Search Laravel Package

Technical Evaluation

Architecture fit. The package fits the Laravel idiom cleanly: a service provider, a publishable config/semantic-search.php, a facade (SemanticSearch::search()), and Eloquent-backed execution. The architectural bet is the interesting part — it replaces embedding/vector-search infrastructure with static code analysis plus a heuristic English-to-SQL parser. For a TPM, that is a meaningful operational simplification (no vector DB, no embedding pipeline, no model hosting, no GPU spend), but it shifts complexity into the parser. The ceiling of a heuristic parser is bounded by the grammar it recognizes; the README's headline examples ("active users who made purchases over $500 in the last 30 days") are precisely the class of multi-clause queries heuristics handle least reliably. The optional LLM fallback is the escape hatch, but enabling it reintroduces an external dependency and a latency/cost profile the static path was meant to avoid. In other words: the package's value proposition is strongest for simple NL queries and weakest for the complex ones it advertises.

Integration feasibility. Low friction on paper. composer require, publish config, flip an env flag for LLM. Auto-discovery of models, controllers, views, and routes means near-zero wiring. The risk is that auto-discovery is a filesystem scan — that has implications for read-only container filesystems, autoscaled ephemeral instances, and cache invalidation when code changes but the analysis cache does not.

Technical risk: high. The observable maturity signals do not support the README's "production-ready" claim. One star, zero dependents, version 0.3.0 that already shipped a breaking change (SearchEngine → EnhancedSemanticSearchService, QueryParser removed), no visible CI/coverage badges, no security policy, no commercial support, and a test count referenced only in changelog prose ("26/26 tests passing"). The gap between marketing language and observable evidence is itself a risk signal — it suggests the docs are aspirational. You would not be an early adopter; you would be the first production user.

Key questions to resolve before any commitment.

• Does the parser fail loudly or silently on ambiguous/unsupported queries? Silent misparse returning plausible-but-wrong rows is the most dangerous failure mode for reporting or billing surfaces.
• What is the multi-tenancy posture? Does generated Eloquent respect global scopes, wherePolicies, and tenant scoping, or does it bypass them? This is a blocker if the answer is unclear.
• The security config is blocklist-based (restricted_models, restricted_fields) — blocklists fail open for any new model or column. Is there an allowlist mode?
• What exactly is sent to OpenAI when LLM fallback is on (schema? column names? query text?) — a compliance question, not a code question.
• Is there a stable contract across 0.x, or will every minor bump be a migration?
• Who maintains this, and what is the bus factor?

Integration Approach

Stack fit. Laravel 9–11 / PHP 8.1+ / MySQL 8, Postgres 12, SQLite covers the common enterprise baseline. Watch for Laravel 12 — no stated support yet, and with zero dependents there is no ecosystem pressure to keep pace.

Migration path. Effectively none — this is greenfield adoption, not a replacement for an existing search layer. Treat every 0.x upgrade as a mini-migration given the demonstrated willingness to break public classes.

Compatibility discipline. Pin to an exact version in composer.json, not a caret range. Because there are no dependents de-risking the package for you, you are absorbing all compatibility risk; pinning is the only control you have.

Sequencing (the TPM recommendation).

1. Spike in an isolated branch, pointed at a read replica or sandbox database — never against production data during evaluation.
2. Assemble a query corpus from your actual product vocabulary: 50–100 real natural-language queries your users or internal analysts would type, with expected result sets. This is the single highest-leverage artifact you can build; it converts a vague "does it work?" into a measurable acceptance bar.
3. Measure parse success rate, correctness vs. hand-written Eloquent, p50/p95 latency, and cache hit rate. Separate static-only from static+LLM results.
4. Decide static-only vs. LLM-assisted based on that data, not on the README.
5. Wrap behind your own interface (adapter/facade of your own) before any production exposure. Given the maturity, the ability to swap or fork is non-negotiable — do not let Venmail\SemanticSearch\Facades\SemanticSearch leak into controllers and services.
6. Roll out to a read-only, non-critical surface first (internal admin search, not customer-facing or financial reporting).

Operational Impact

Maintenance. Realistically, you become the de facto maintainer. The static analyzer is coupled to your code's shape — moving models, renaming columns, introducing traits or polymorphic relations can silently degrade parse quality. Budget for a regression suite of NL queries in CI (the corpus from step 2) so refactors fail loudly rather than degrading quietly. Expect to vendor-patch or fork within a year.

Support. GitHub issues only, no SLA, one star, no commercial backing, no community. For any customer-facing surface this is a genuine support risk; for internal tooling it is tolerable if you own the runbook.

Scaling. Static analysis is cached, which is good, but query translation is CPU work per request, and the LLM fallback adds an external hop with a 10-second configured timeout — that is a long tail for a synchronous request path. The LLM path also needs rate-limit/backoff handling that isn't clearly documented, and per-token cost scales with query volume. max_rows: 10000 is a safety valve but also a functional ceiling.

Failure modes to design for.

• Silent misparse → wrong data returned with a 200 OK. Most dangerous mode; mitigate with confidence thresholds surfaced to the caller and a "did you mean" / clarification UX rather than guessing.
• LLM timeout or provider outage → user-facing latency spike; need a kill switch and a fast-fail static-only degradation.
• Cache staleness after code or schema changes → stale vocabulary and stale results; tie cache busting to deploy, not just TTL.
• Scanner failures on read-only or ephemeral filesystems in containerized deployments.
• Authorization gaps — blocklist security defaults fail open; verify relationship traversal respects policies and tenancy before exposing to multi-tenant data.

Ramp-up. Low for consumers (a clean facade), higher for operators. On-call needs a runbook covering: how to read parser confidence, how to disable LLM fallback at runtime, how to clear the cache safely, and how to reproduce "why did this query return wrong results." Without that runbook, every misparse becomes an escalation.

Bottom line for a TPM. The concept is genuinely attractive — natural-language querying without an ML platform is a real operational win — but the execution evidence does not yet justify production adoption. Recommend a time-boxed spike against a real query corpus, wrapped in an adapter, deployed only to a non-critical surface if it passes. Do not put this on a customer-facing or financial path until it has a release history, CI evidence, and clarity on tenancy and authorization. Opportunity score of ~31 reflects exactly this: interesting whitespace, unproven artifact.