Ai Postgres Store Laravel Package

Technical Evaluation

Architecture Fit

• symfony/ai-postgres-store is a bridge, not a platform: it implements Symfony AI's StoreInterface against PostgreSQL + pgvector. In a Laravel codebase it slots in as an infrastructure adapter behind a domain-level VectorStore contract, not as something controllers or jobs call directly.
• The package's real architectural value is avoiding a second datastore. Teams already running PostgreSQL get semantic search, ANN indexing, and hybrid retrieval (vector similarity + native full-text) without procuring Pinecone/Weaviate. From a TPM standpoint that is a build-vs-buy decision that mostly resolves to "buy the bridge, keep the database we already operate."
• VectorDocumentInterface (v0.14.0) is the most consequential API surface for us: it gives a stable contract to map Eloquent models or DTOs into stored documents. That determines whether vector data stays aligned with our domain model or degrades into opaque array payloads.
• count() support (v0.14.0) and clear() (v0.11.0) are the features that make this operable rather than demo-ware — pagination, "N results found" UX, index-size dashboards, and reindex workflows all depend on them.

Integration Feasibility

• Feasible but not turnkey. There is no Laravel package here: no service provider, no config publish, no facade. We own a thin adapter (~1 service provider + 1 repository class + migrations). Budget this explicitly; it is the single most underestimated line item.
• Hard dependency on the pgvector extension. That is a provisioning/DBA conversation, not a code conversation, and it must be resolved in CI, staging, and production before any sprint is committed. Managed Postgres providers vary in whether they allow CREATE EXTENSION vector.
• Eloquent has no native vector/halfvec column type. Migrations will need raw SQL or a custom schema grammar macro; query building for distance operators (<->, <#>, <=>) will need raw expressions or a small query builder wrapper.
• Version posture: the package is 0.x (currently ~0.14), 2 stars, 0 dependents, and lives inside the main symfony/ai monorepo with issues tracked there. It is credible because of the Symfony org backing, but it is pre-1.0 and interfaces have already moved (VectorDocumentInterface, clear(), count).

Technical Risk

• Pre-1.0 churn: minor releases have introduced interface changes. Pin exact minor versions, keep the adapter layer small, and treat every bump as a tested change, not a composer update.
• Adoption risk: 2 stars / 0 dependents means we are near the front of the adoption curve. We will find the edge cases. Mitigation is architectural, not contractual — the StoreInterface boundary means a swap to another pgvector client or a managed vector DB is a contained change if we do not leak Symfony types upward.
• Count performance: exact COUNT(*) over large vector tables with filters can be expensive. Decide up front whether counts are exact, cached, or approximate; do not let a dashboard query dictate the data model.
• Observability gap: the package gives no metrics. Vector query latency, index health (HNSW recall), and count latency need our own instrumentation.
• Scaling ceiling: pgvector is excellent to a few million vectors with HNSW; beyond that it is partitioning, read replicas, or a dedicated vector service. We should state the volume assumption in the design doc.

Key Questions

1. What is the projected vector volume at 12 and 24 months, and does it stay inside pgvector's practical HNSW range?
2. Does our Postgres provider permit the pgvector extension, and at what version? Who owns that change?
3. Are counts on the critical path of user-facing pagination (exact required) or only admin metrics (approximate acceptable)?
4. Do we map Eloquent models directly to VectorDocumentInterface, or keep a dedicated DTO layer? (Recommend DTO — it insulates us from interface churn.)
5. Is hybrid retrieval (vector + full-text + metadata filters) an actual requirement, or is vector-only sufficient for v1?
6. Who owns embedding generation, re-embedding on model change, and backfill? The store persists vectors; it does not create them.
7. What is the fallback if pgvector query latency degrades under production load?

Integration Approach

Stack Fit

• Laravel 10/11 + PHP 8.2+: bind the store via a VectorStoreServiceProvider, expose a VectorStore facade/contract, and keep Symfony AI types confined to app/Infrastructure/VectorStore/.
• PostgreSQL 13+ with pgvector: the only non-negotiable infrastructure requirement. Verify extension availability in every environment before committing to the approach.
• Doctrine DBAL or raw DB::statement: necessary for vector/halfvec columns and distance-operator queries. Do not fight Eloquent here; wrap it once.
• Queue workers: embedding generation and bulk upserts belong in queued jobs, not request cycles — batching materially changes throughput and cost.
• Cache (Redis/database): for count results and hot query results where exactness is not contractual.
• Deliberately excluded for v1: Laravel Scout integration. Dual-store synchronization is a large hidden cost; only pursue it if existing search infrastructure must be preserved.

Migration Path

1. Feasibility spike (1 week): provision pgvector in a dev branch, create a vector column via raw migration, write one embedding, run one similarity query and one count(). This retires the two biggest unknowns before roadmap commitment.
2. Contract first: define our own VectorStore interface (upsert, query, count, delete, clear) with VectorDocument DTOs. Implement it with the Symfony bridge. This is the decision that makes the pre-1.0 risk manageable.
3. Schema: versioned migration using raw SQL for the vector column, dimension chosen and frozen, HNSW index created concurrently outside the migration transaction.
4. Dependency pinning: symfony/ai and symfony/ai-postgres-store pinned to an exact minor; upgrades done deliberately with changelog review against the main symfony/ai repo.
5. Backfill and dual-write: populate the index from the source of truth via queued jobs; add an idempotent reindex command before enabling user-facing features.
6. Feature rollout: admin/internal use (index coverage dashboards, count metrics) → read-only semantic search behind a flag → user-facing search once latency and recall are validated.
7. Instrumentation before GA: log query latency, count latency, index size, and embedding coverage; set alerts on p95 query latency.

Compatibility

• Pin minor versions; treat each 0.x bump as a change requiring regression tests against the adapter.
• Test against the exact PHP/Postgres versions in production — pgvector operator behavior and index performance vary by server version.
• Avoid VectorDocumentInterface in domain code; adapt to it at the boundary so upstream changes cost one file, not a refactor.
• Keep the Symfony AI store swap-out documented: the adapter boundary is our exit ramp to a managed vector service if volume outgrows pgvector.

Sequencing Feasibility spike → contract + adapter → schema + index → backfill/reindex tooling → internal/admin surface → flagged user-facing search → production hardening. Do not start with user-facing search; the operational tooling (reindex, coverage counts, latency metrics) is what makes it survive contact with production.

Operational Impact

Maintenance

• Two maintenance surfaces: the adapter layer we own, and the upstream package we do not. The adapter should stay small enough that a 0.x interface change is hours, not a sprint.
• Pin dependencies and review the symfony/ai monorepo changelog before every bump; releases like VectorDocumentInterface and StoreInterface::clear() are the kind of change that silently breaks custom implementations.
• The SQL layer (vector columns, index DDL, distance operators) is hand-rolled and needs an owner with PostgreSQL familiarity. This is a real, ongoing cost — not a one-time setup.

Support

• Support must distinguish three failure classes: extension missing/misconfigured, slow queries, and adapter/interface mismatch after an upgrade. Runbooks should cover all three.
• Publish count semantics explicitly (exact vs. cached vs. approximate) — otherwise product will treat a cached number as authoritative and support will absorb the resulting tickets.
• Escalation path for upstream bugs is the main symfony/ai repository, under a Symfony org, with a 2-star package's worth of community attention. Do not assume responsive upstream support; assume we can patch or vendor a fork if needed.

Scaling

• HNSW index build time and memory grow materially with volume; index builds should be CONCURRENTLY, off-peak, and monitored.
• Exact counts degrade first under load — cache or approximate them before they become a paging bottleneck.
• Beyond a few million vectors, expect partitioning, read replicas for query traffic, or a migration to a dedicated vector service. The adapter boundary is what makes that a contained project rather than a rewrite.
• Embedding generation cost (API spend and worker throughput) will likely dominate infrastructure cost before vector storage does.

Failure Modes

• pgvector extension absent in a newly provisioned environment → migrations fail on deploy. Mitigation: provisioning check in CI and a pre-deploy assertion.
• Dimension mismatch between the embedding model and the column → silent upsert failures or rejected queries. Mitigation: freeze dimensionality in config, assert on write.
• Slow/timing-out count queries under load. Mitigation: statement timeouts, caching, approximate counts, and a documented fallback.
• Interface breakage on upgrade in custom document/store implementations. Mitigation: adapter isolation plus a pinned version and a test suite around the adapter.
• Recall degradation as data grows and index parameters become stale. Mitigation: periodic recall sampling against exact-search baselines.
• Index and source-of-truth drift (deleted records still in the index). Mitigation: clear()/remove() wired into model events, plus a scheduled reconciliation job.

Ramp-Up

• Moderate. Engineers need working pgvector/PostgreSQL knowledge (operators, index types, EXPLAIN on vector queries) plus familiarity with the Symfony AI store contracts — neither is common Laravel background.
• Plan for roughly one engineer-week of ramp plus the feasibility spike before the team is productive.
• Onboarding must cover: the adapter boundary and why it exists, the reindex command, count semantics, and the upgrade procedure for pinned dependencies.