ragleap-vectorstores

Install

Each backend's real client SDK is an optional extra — installing the bare package alone pulls in no heavy dependencies beyond ragleap-rag itself.

pip install ragleap-vectorstores[chroma]
# or, with uv
uv add ragleap-vectorstores[chroma]

pip install ragleap-vectorstores[lancedb]
# or, with uv
uv add ragleap-vectorstores[lancedb]

pip install ragleap-vectorstores[redis]
# or, with uv
uv add ragleap-vectorstores[redis]

pip install ragleap-vectorstores[upstash]
# or, with uv
uv add ragleap-vectorstores[upstash]

Quick start

database_url= is still required even when using one of these backends for vectors — ragleap-rag's conversation memory is always Postgres-backed regardless of which vector_backend is chosen; only vector storage moves. Swap ChromaBackend for LanceDBBackend(uri="./lancedb_data") to use LanceDB instead, or RedisBackend(redis_url="redis://localhost:6379/0") for Redis (requires a real Redis Stack instance, or plain Redis + the RediSearch module), or UpstashBackend(url="...", token="...") for Upstash Vector (requires an already-created dense-type index — see the Upstash console) — same interface, same rest of the setup.

from ragleap_vectorstores import ChromaBackend
from ragleap import RagLeap, ProviderConfig, EmbeddingConfig

backend = ChromaBackend(persist_directory="./chroma_data")

rag = RagLeap(
    database_url="postgresql://...",   # still required — conversation memory
    vector_backend=backend,             # vectors go to Chroma instead
    primary=ProviderConfig(provider="gemini", api_key="..."),
    embedder=EmbeddingConfig(provider="gemini", api_key="..."),
)
rag.init_schema()
rag.ingest("report.pdf")
answer = rag.ask("What were Q3's key findings?")

Full public API surface

Confirmed via direct source reading, not inspect().

from ragleap_vectorstores import VectorBackend, ChromaBackend, LanceDBBackend, RedisBackend, UpstashBackend, OpenSearchBackend, __version__

ChromaBackend — implements VectorBackend

LanceDBBackend — implements VectorBackend

RedisBackend — implements VectorBackend

UpstashBackend — implements VectorBackend

OpenSearchBackend — implements VectorBackend

Known limitations

Drawn from live testing against the real installed chromadb==1.5.9, lancedb==0.37.1, redis-py==7.3.0, upstash-vector==0.8.0, and opensearch-py==3.2.0 packages, plus a real Redis Stack instance, a real Upstash Vector index, and a real OpenSearch 3.8.0 instance — not from documentation alone.

Applies to all backends

• No native sparse/keyword search. supports_sparse() honestly reports False for all five — none has a tested full-text/keyword search path in this release, so search_hybrid() falls back to dense-only.
• database_url= is still required. Conversation memory is always Postgres-backed in ragleap-rag, regardless of which vector backend is chosen — these backends only replace vector storage.

Chroma-specific

• where= filters need exactly one top-level operator. A plain multi-key metadata filter dict raises ValueError against real chromadb — ChromaBackend wraps multi-key filters in $and automatically, but this is a real constraint worth knowing if you're debugging filter behavior directly against chromadb.
• Dependency footprint. chromadb's own transitive dependencies are non-trivial (kubernetes client libs, OpenTelemetry, uvicorn extras) — correctly gated behind the optional [chroma] extra, but worth knowing before installing into a size-sensitive environment.

LanceDB-specific

• Default metric is L2, not cosine. LanceDBBackend sets .metric("cosine") explicitly on every query to avoid this — worth knowing if you're querying LanceDB directly outside this backend.
• LanceDB does support full-text search via tantivy (fts_columns=), but that surface wasn't implemented or tested in this release.

Redis-specific

• Requires a real running server. Unlike Chroma/LanceDB, there's no embedded/local mode — plain Redis has no vector search at all. init_schema() checks MODULE LIST and raises a clear error if the search module (RediSearch/Redis Stack) isn't loaded.
• Metadata filtering is limited to document_id. RediSearch requires fields to be predeclared in the index schema up front — unlike Chroma's flexible where=, arbitrary metadata keys can't be filtered on without a schema change.
• TAG field values must be escaped. An un-escaped UUID-style document_id (containing hyphens) inside a TAG query silently returns zero matches — RediSearch parses hyphens as query syntax, not literal characters. Handled automatically, but worth knowing if querying Redis directly.
• Redis does support full-text search via TextField/BM25 scorers, but that surface wasn't implemented or tested in this release.

Upstash-specific

• No local mode at all. Unlike every other backend here (including self-hostable Redis), there is no way to run Upstash Vector locally — it's a managed cloud service only, and the index must already exist, created via the Upstash console.
• An index can be "dense" or "hybrid" at creation time. A hybrid-type index rejects dense-only upserts with a confusing error — live-verified. init_schema() checks this via info() and fails clearly up front instead.
• Writes are eventually consistent. A short delay after insert_chunk() may be needed before a search_dense() reliably sees it — live-verified in this package's own test suite, which waits ~1-1.5s after seeding data.
• Upstash does support real hybrid dense+sparse search, but that requires a hybrid-type index and sparse embeddings this package doesn't generate, so it's honestly reported as unsupported.

OpenSearch-specific

• Requires a real running instance. There is no embedded/local mode, unlike Chroma/LanceDB.
• The nmslib k-NN engine is rejected on OpenSearch 3.0+. Most tutorials use it; attempting it raises mapper_parsing_exception at index creation — live-verified. This backend uses engine: "lucene" instead.
• The k-NN score is not raw cosine similarity. With cosinesimil and the lucene engine, the score is (1 + cosine_similarity) / 2, mapping [-1, 1] onto [0, 1] — derived from real numbers (near-identical vectors scored 0.9969, orthogonal vectors 0.5552) and used directly as similarity_score.
• No bulk-insert path yet. insert_chunk() indexes one document per request — fine for moderate chunk counts, not optimized for very large ingests.
• Tested locally only. The 16 OpenSearch tests ran against OpenSearch 3.8.0 in Docker on a local Windows machine (Python 3.14, opensearch-py==3.2.0); they skip when OPENSEARCH_TEST_URL is unset and have not been run in CI or on Linux.
• OpenSearch does support real BM25/hybrid search, but that surface wasn't implemented in this release, so it's honestly reported as unsupported.

Fixed in v0.5.1

• REAL BUG in v0.5.0, on Python 3.10 only. OpenSearchBackend.insert_document() used datetime.UTC, which only exists on Python 3.11+, so it raised AttributeError on Python 3.10 - despite this package declaring support for 3.10. Reproduced with the published v0.5.0 wheel; fixed in v0.5.1 by switching to datetime.timezone.utc, which works on every supported version and produces the same timestamp. Python 3.11+ was never affected.
• The deprecated datetime.utcnow() was also removed from the Chroma, LanceDB, Redis and Upstash backends in v0.5.1, with the identical naive-UTC timestamp string preserved - stored data and list_documents() output are unchanged.