litestar-org / litestar-org/sqlspec
feat(adk): add vector memory support for psqlpy and PostgreSQL ADBC
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 102
- Forks
- 9
- Avg merge
- 6h 34m
- Merged PRs (30d)
- 46
Description
## Summary
The psqlpy and ADBC ADK memory stores accept `StoredMemory.embedding` and an `embedding` search argument through the shared public contract, but currently ignore both.
- `PsqlpyADKMemoryStore` creates no vector column, omits embeddings from inserts, and performs text-only searches.
- `AdbcADKMemoryStore` is multi-dialect and reduced-scope; its PostgreSQL path likewise has no vector column or search branch and returns `embedding=None`.
This makes PostgreSQL vector-memory behavior inconsistent across SQLSpec adapters and silently discards caller data.
## Proposed behavior
Add PostgreSQL ADK vector-memory support for psqlpy and the PostgreSQL ADBC backend while preserving reduced-scope behavior for non-PostgreSQL ADBC drivers.
- Persist nullable embeddings in owner and non-owner insert paths.
- Add vector-only nearest-neighbor search with null embeddings excluded.
- Use codec-independent parameter binding. Psqlpy supports explicit SQL casts; determine and document the portable ADBC PostgreSQL binding representation rather than assuming native pgvector codecs.
- Return stored embeddings when the backend exposes them.
- Do not silently ignore a supplied embedding on an unsupported ADBC backend; fail clearly or expose an explicit capability boundary.
- Decide whether `pg_textsearch` BM25/hybrid search should reach parity in the same implementation or remain a separately declared capability.
## Acceptance criteria
- Unit tests cover SQL, nullable embeddings, owner-column parameter ordering, and vector query operands for both adapters.
- PostgreSQL integrations insert via the public memory-store API and assert nearest-neighbor IDs/order with client pgvector codecs disabled.
- ADBC tests cover PostgreSQL vector decoding and unsupported non-PostgreSQL behavior.
- Adapter documentation and the ADK backend matrix accurately describe vector and BM25 capabilities.
- No public method signatures or shared record types change.
Related: #726, #727
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the PsqlpyADKMemoryStore and AdbcADKMemoryStore implementations and the shared StoredMemory embedding contract. Review the existing unit and PostgreSQL integration tests, then verify parameter binding and behavior for PostgreSQL versus unsupported ADBC drivers. Done means nullable embeddings are persisted and returned, nearest-neighbor ordering works, unsupported backends fail clearly, and capability documentation and tests cover the stated matrix.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgresql, python
- Domain
- backend, databases
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100