Laravel Manticore Eloquent Laravel Package

Product Decisions This Supports

• Semantic / vector search roadmap: v2.0.0 makes "more like this" retrieval a first-class, one-line capability (knn('embedding', $article->id, k: 10)), which is the building block for related-content, recommendations, duplicate detection, and RAG-style retrieval without standing up a separate vector database. This directly informs whether semantic search ships this quarter or slips.
• Build vs. buy for search: a mature Laravel-native Manticore integration with hybrid keyword + vector search, casts, and Eloquent parity reduces the case for buying a managed vector search vendor or building a custom search service. Re-evaluate the buy case only if you need managed scaling, multi-tenant isolation, or replication guarantees the package doesn't cover.
• Schema and data-model decisions: VectorCast means embeddings become an ordinary model attribute — a product-level unlock, because it removes raw SQL from the write path and lets any team seed/read vectors through normal Eloquent. It also surfaces a real constraint: cosine columns normalize stored vectors on read-back, and KNN-indexed columns can't be UPDATEd (use replace()). That shapes whether embeddings are treated as immutable, versioned artifacts in your data model.
• Security posture / risk acceptance: option names and values are now validated by shape instead of interpolation, closing an injection path reachable from request input via ->option($key, $value). If any internal API or admin surface passes user-supplied ranking or sorting options, this is a reason to prioritize the upgrade rather than defer it.
• Upgrade planning as a roadmap input: the breaking changes are narrow (function-call option values need DB::raw(), knn()/whereKnn() signature changes, wheres key ef → options) but they touch extension points. Worth sizing the migration before committing dependent features to a date.
• Use cases enabled cheaply: "related articles," "similar tickets," "find near-duplicate listings," semantic autocomplete — all expressible as one query builder call, which is the kind of thing that turns a speculative spike into a shippable increment.

When to Consider This Package

Adopt when:

• You're on Laravel/Eloquent and want keyword + vector search without leaving the ORM or adding a second datastore to the stack.
• Semantic similarity (document-to-document or vector-to-document) is on the roadmap and you want it as a query-builder primitive rather than a bespoke service.
• You have Manticore Search already, or are willing to run it — the package is an Eloquent adapter, not a search engine.
• Your team values raw-SQL-free application code; VectorCast is a meaningful ergonomics and safety win here.
• You can accept the v2.0.0 breaking changes now, or can pin v1.x while you schedule them.

Look elsewhere when:

• You need managed infrastructure, elastic autoscaling, or vendor SLA — this is a self-hosted open-source integration, and you own the server.
• You require vectors to be mutable in place; Manticore refuses UPDATE on KNN-indexed columns, so any product flow that "edits" an embedding needs replace semantics or a new document.
• You depend on exact vector read-back — cosine columns store unit-normalized vectors, so consumers comparing stored to original embeddings will need to normalize consistently.
• Your search needs are pure BM25/keyword with no vector ambitions; the added surface (KNN, option blocks, casts) is complexity you won't use.
• You pass arbitrary user input into search options and cannot validate it upstream — the package now enforces shape safety, but treating user input as ranking keywords is still a product risk worth designing away.
• You need a broad ecosystem of first-party drivers, managed hosting integrations, or community plugins; this is a focused, single-maintainer-shaped package.

How to Pitch It (Stakeholders)

To executives: The search layer we already run just gained vector and "similar to this" search in the ORM we already use — no new vendor, no new datastore, no new headcount. That means related-content, recommendations, and semantic retrieval move from "needs a platform project" to "a feature we can schedule." It also closes a security gap where search options fed from request input could inject query fragments; that alone justifies the upgrade. Cost is a bounded migration, not a rewrite.

To engineering: v2.0.0 fixes a real correctness bug — the old knn() emitted a positional form Manticore rejects, so the feature simply didn't run; it now emits the {ef=…} block Manticore parses, with no caller change. Option blocks now pass through whatever the server accepts, so new Manticore options don't require a package release, and option names/values are validated by shape rather than a list that rots. VectorCast removes the last raw-SQL requirement for vector writes and reads. Three things to plan for: function-call option values must be wrapped in DB::raw() (bare keywords, numbers, bools, arrays, and quoted literals are unaffected), knn()/whereKnn() signatures changed and the wheres key ef is now options if you extend the package, and two live-server gotchas are document — cosine columns normalize stored vectors, and vectors on KNN-indexed columns must be changed with replace(). Verified against Manticore 17.5.1 with 79 tests / 140 assertions.

Recommendation: Upgrade. The security fix and the working knn() are non-optional for anyone actually using vector search; the breaking changes are small, mechanical, and confined to option values and extension points.