Ai Cache Store Laravel Package

Product Decisions This Supports

• Feature scoping: separate "cache" from "search." The strongest use case for this package is not vector search at all — it's an embedding/response cache keyed by content hash, so repeated prompts, retrieved documents, or product descriptions reuse an existing embedding instead of re-calling a paid embedding API. That is a cost-and-latency feature we can ship in a sprint, not a platform migration.
• Build vs. buy: buy time, not infrastructure. Adopting this defers the decision to stand up Pinecone/Weaviate/pgvector. It lets us validate whether a semantic feature has demand before committing to a vector database contract, ops runbook, and monthly spend. Treat it as a reversible, low-cost option, not a foundation.
• Roadmap sequencing for AI features. A defensible three-step path: (1) cache-backed store on our existing Redis for dev/staging and low-volume production; (2) measure hit rate, p95 retrieval latency, and dataset size; (3) migrate to a real vector index when any threshold is breached. This package is phase 1 only — and should be documented as such in the ADR. v0.14.0's count() support makes step 2 cheaper to instrument: corpus size becomes a first-class, queryable metric rather than something we estimate from write logs.
• Use cases that genuinely fit today:
  • Embedding deduplication and reuse across jobs, importers, and queue workers.
  • Semantic search over small, slow-changing corpora (internal docs, help-center articles, a few thousand SKUs) where an O(n) scan in PHP is acceptable.
  • Metadata-filtered lookups — v0.4.0 added a query abstraction with filter support and remove(), and v0.14.0 adds count() for metadata-scoped retrieval, cache invalidation, and corpus telemetry.
  • Runtime size guards. count() lets us assert corpus size before an O(n) scan and fall back to a cheaper path (metadata filter, keyword lookup, or a queued job) when a threshold is crossed — a guardrail, not just a dashboard.
  • Local/dev parity — reproducible vector fixtures in CI with no external service or API key.
• Decisions this does not support: real-time recommendations, per-user personalization at scale, multi-tenant semantic search, or anything with a latency SLO measured in tens of milliseconds over a large corpus. Cache backends are key-value stores; similarity is computed in PHP over fetched candidates, so cost grows with corpus size, not with k. Nothing in v0.14.0 changes this — there is still no ANN index.

When to Consider This Package

Adopt if all of the following hold:

• You are already on, or actively evaluating, Symfony AI (symfony/ai) as the AI abstraction layer. This repo is a thin bridge inside the Symfony AI monorepo — its README is five lines and points to the parent project for issues and PRs. The real evaluation is of symfony/ai, not this package.
• You already run a durable Redis (or equivalent PSR-16 cache) and want zero new infrastructure. Prefer Redis with persistence enabled over file/database cache — cache eviction and TTL are the dominant failure mode here.
• Your corpus is small-to-medium (order of thousands to low hundreds of thousands of vectors, not millions), and stale-on-eviction is an acceptable failure mode.
• You need basic insert/query/count/remove with metadata filters, and can live without approximate nearest neighbor search, hybrid keyword+vector search, or custom similarity metrics.
• You accept that cache semantics ≠ storage semantics: TTLs, LRU eviction, and flush will silently delete vectors. Confirm the data is derived (re-computable from source) rather than authoritative.

Look elsewhere if:

• You are Laravel-first and not otherwise using Symfony AI. This is Symfony AI's bridge, not Laravel's. Wiring it means pulling in symfony/ai, binding a StoreFactory/CacheStore into Laravel's container, and maintaining that glue yourself — with no Laravel-specific docs or examples. The integration tax is real and recurring.
• Maturity signals are disqualifying for your risk profile. One GitHub star, zero dependents, and a release history that includes several entries marked "no significant changes" (v0.5.0, v0.6.0, v0.8.0). The project is now at v0.14.0 — still pre-1.0, so breaking changes remain expected; the Symfony AI ecosystem is itself early. There is no commercial support and no SLA.
• You need vector search, not vector caching. No ANN index, no quantized storage, no similarity pushed down to the datastore. If "search" must be fast over a growing corpus, budget for pgvector or a managed vector DB from the start — the migration is not free later.
• You have compliance, residency, or audit requirements. Cache layers typically lack retention controls, per-record auditability, and backup/restore semantics you'd need to attest to.
• You are on a managed or serverless cache tier (e.g., a hosted Redis with aggressive eviction and no persistence) — vectors will disappear without warning.

Gate before committing: run a two-day spike against a representative corpus. Measure insert throughput, p95 query latency at 10k / 100k vectors, serialization overhead in the chosen cache driver, and behavior under eviction. Additionally, benchmark count() on the target driver — it may be a cheap key count on some backends and a full scan on others; if it is expensive, keep it off request paths and use it only in scheduled telemetry. If p95 latency or memory exceeds the target at 10x current corpus size, stop and go straight to phase 3.

How to Pitch It (Stakeholders)

To executives (one paragraph): "We have a cheap way to test whether semantic search and AI-assisted features are worth investing in. This package lets the AI layer reuse the Redis cache we already pay for as a lightweight vector store, so a prototype costs engineering days instead of a new vendor contract and a new system to operate. The latest release adds corpus-size counting, which means we can put hard guardrails and cost telemetry around the pilot from week one instead of guessing. It also avoids locking us in: the same interface swaps to a dedicated vector database when volume justifies it. The trade-off is honest — it's early-stage, pre-1.0, and appropriate for prototypes and small corpora, not for high-traffic production search. I'm recommending a time-boxed pilot with explicit go/no-go thresholds, not a platform commitment."

To engineering (the important caveats):

• It's a Symfony AI bridge, and we're a Laravel shop. Plan for container wiring (StoreFactory / CacheStore binding in a service provider), a thin facade, and our own tests — there are no Laravel examples upstream.
• The store is only as good as the cache behind it. Pick Redis with persistence; treat file and database caches as dev-only. Document that flush, TTL expiry, and LRU eviction delete vectors, and make every write idempotent and re-derivable.
• Query cost is O(n) scans with PHP-side similarity. Don't let it creep into a request path with a latency budget; keep it in jobs or behind an explicit size guard. As of v0.14.0 that guard can use count() — but verify the driver implements it cheaply before trusting it in a hot path.
• v0.14.0 also introduces VectorDocumentInterface. Use it as the swap seam: type our internal vector-store wrapper against that interface rather than the concrete cache store, so a move to pgvector or a managed store is a single-class change. Note this is an additive abstraction, not a stability guarantee — pre-1.0, expect it to move.
• Pin the version. At 0.14.x with periodic "no significant changes" releases, churn can arrive without signal — read diffs in the parent symfony/ai repo, and keep vector-store usage behind an internal interface.
• Success criteria to instrument from day one: cache hit rate, p95 query latency, corpus size (via count()), eviction count, and embedding spend avoided. Those numbers are what turn this pilot into either a production decision or a fast, cheap "no."

To data/ML stakeholders: you get persistence, filtered retrieval, and now corpus counts for embeddings inside the PHP stack, which is enough to validate retrieval quality and prompt/embedding caching offline. You do not get ANN, re-ranking at scale, or a query planner — treat any quality evaluation here as directional, and expect to re-run it against the real index before we commit to a search product.