litestar-org / litestar-org/sqlspec

feat(adk): add vector memory support for psqlpy and PostgreSQL ADBC

Open
#728 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.