feat: add PGVectorStore — pgvector implementation of VectorStoreInter…

[theap06]

##Summary
Adds PostgreSQL pgvector as a vector store backend for GenericRAGAdapter. Supports cosine/L2/inner-product distance, hybrid search via tsvector, JSONB metadata filtering, HNSW indexing, and upsert/delete operations.

---

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
pyproject.toml	Unsupported file format
src/gepa/adapters/generic_rag_adapter/__init__.py	0% smaller
src/gepa/adapters/generic_rag_adapter/vector_stores/pgvector_store.py	0% smaller
uv.lock	Unsupported file format

[LakshyAAAgrawal]

Reviewed the PGVectorStore implementation. Overall structure matches the sibling stores well and the SQL is parameterized correctly (good use of psycopg2.sql.Identifier / sql.Literal everywhere — no injection holes I could spot). Ruff + pyright both clean.

A few things worth fixing or discussing before merge:

Blocking

1. uv.lock is still in the diff (1,038 / 1,562 added lines). Your earlier request to revert it isn't addressed — that's almost all of the line count of this PR. Please drop the uv.lock changes; CI will lock against the existing version.

Correctness / behavior

2. zip(ids, documents, embeddings, strict=False) at pgvector_store.py:263. The constructor already validates len(documents) == len(embeddings) and len(ids) == len(documents) on lines 246–251, so the lengths are guaranteed equal here — strict=True would correctly assert that invariant. With strict=False, a future refactor that drops one of those checks would silently truncate writes. Cheap fix, real safety improvement.

3. Hybrid search hard-codes 'english' at line 169 (to_tsvector('english', content), plainto_tsquery('english', %s)). Silently degrades for non-English corpora. Add a tsvector_language: str = "english" constructor parameter and thread it through. (Same pattern other stores expose for language config.)

4. No GIN index on metadata. create_table only creates the HNSW index on embedding. The moment a user uses filters={...}, every metadata->>%s = ... predicate does a sequential scan over the metadata JSONB. For the "production RAG" use case the docstring emphasizes, this matters. Either:

   • auto-create CREATE INDEX ... USING GIN (metadata) inside create_table, or
   • document in the docstring that users should add it themselves for filterable tables.

5. get_collection_info silently swallows errors and returns dimension=0 (lines 223–231). If the table exists but the metadata SELECT fails (e.g., permission issue, pg_catalog quirk), callers checking info["dimension"] get a misleading zero. The error field gets set, but most callers won't check it. Recommend either re-raising or replacing the broken-state dict with a dimension=None sentinel.

Design / cleanup

6. create_local / create_remote / from_connection_string are nearly identical. create_remote is literally from_connection_string(...) (line 510). create_local is from_connection_string with kwargs instead of a DSN. Two classmethods would cover both: from_connection_string (DSN) and from_credentials (kwargs). Three feels like API surface for no extra capability.

7. Connection ownership is undefined. The class never closes self.conn, even when it created the connection itself via the classmethods. Most sibling stores have the same issue, but adding a close() method (and __enter__/__exit__) would be a clear win — especially for the create_local/create_remote paths that opened the connection on the user's behalf.

8. embedding_function is untyped in __init__ and the classmethods. Should be Callable[[str], list[float]] | None. Same for conn (could type as psycopg2.extensions.connection | Any via TYPE_CHECKING import to keep the lazy-import contract).

9. Repeated from psycopg2 import sql inside every method. Other lazy-imported stores tend to do psycopg2 = None at module level inside a try/except, then from psycopg2 import sql once. The repetition here is noisy. Minor — only worth doing if you're refactoring anyway.

Smaller nits

10. HNSW index uses pgvector defaults (m=16, ef_construction=64 ish). Reasonable, but the docstring sells this as production-ready. Either accept hnsw_m / hnsw_ef_construction parameters in create_table, or doc that users should tune via CREATE INDEX ... WITH (...) if needed.

11. get_collection_info's dimension query depends on the column being literally named "embedding". This is fine because create_table enforces that name, but it's an implicit contract. A one-line docstring note ("Assumes the embedding column is named embedding — set by create_table") would help anyone subclassing.

12. No tests added. Sibling stores (chroma, milvus, qdrant) likewise lack live-service tests, so this isn't a blocker — but you could add a mock-based test for _build_where_clause and _vector_score_sql since they generate non-trivial SQL fragments and would be easy to break silently. The existing tests/test_rag_adapter/test_vector_store_interface.py MockVectorStore pattern is a natural fit.

Items 1 and 2 are the ones I'd want fixed before merge. Items 3–5 are real bugs but ones you could fix in a follow-up if you're trying to land this quickly. The rest are polish.

Nice clean implementation overall — the parameterized SQL is genuinely safer than I usually see in vector-store PRs.

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

🟡 Collection info returns a non-integer dimension, breaking the inherited dimension-getter

The dimension field is set to None (pgvector_store.py:221) instead of the integer 0 expected by the interface, so the inherited get_embedding_dimension() method returns None instead of int.

Impact: Any caller relying on get_embedding_dimension() to return an integer (e.g. for arithmetic or size checks) will get None and fail.

Interface contract violation and comparison with all other stores

The VectorStoreInterface documents "dimension" as (int): Vector embedding dimension (0 if unknown) at vector_store_interface.py:170. The base-class get_embedding_dimension() at vector_store_interface.py:193-194 calls info.get("dimension", 0) — if the key exists with value None, .get() returns None rather than the default 0.

Every other store implementation (Chroma, Qdrant, Milvus, LanceDB, Weaviate) returns "dimension": 0 when the dimension is unknown. PGVectorStore returns None in both the success path (line 221) and the error path (line 235).

Suggested change

	dimension = row[0] if row else None
	dimension = row[0] if row else 0

---

Was this helpful? React with 👍 or 👎 to provide feedback.