Retrieval Python v0.5.0

betterdb-retrieval v0.3.0

Developer-facing retrieval SDK over Valkey Search — typed schema, idempotent
index lifecycle, upsert/delete, and vector + filtered + hybrid query, with
built-in observability seams.

What's new in v0.3.0

• Product analytics now start on the first data-path call (query, upsert,
  delete, describe_index, health, drop_index), not only on
  create_index. Apps that attach to an existing index and only query now
  report usage analytics as expected. Opt out with BETTERDB_TELEMETRY=false.

Analytics (since v0.2.0)

• Opt-out anonymous usage analytics (PostHog). Disable with
  BETTERDB_TELEMETRY=false (or 0/no/off), or per-instance via options.
  Instance id is an anonymous UUID persisted in Valkey; no payload data is sent.

Requires Valkey 8+ with the valkey-search module (vector index support).
Works with ElastiCache for Valkey, Memorystore for Valkey, and MemoryDB.

Built on betterdb-valkey-search-kit.

---

Installation

pip install betterdb-retrieval

---

What's included

Retriever

Method	Description
create_index()	Create or attach to the vector index (idempotent)
upsert(...)	Insert or update a document with its vector and fields
delete(id)	Delete a document by id
query(...)	Vector, filtered, and hybrid (vector + filter) search
health()	Index name, doc count, vector dimension

Schema & fields

Typed RetrievalSchema with TAG / NUMERIC / vector field builders, validated
against the live FT.INFO to tolerate version skew.

Discovery

Shared discovery registry with atomic register/unregister (EVAL compare-and-set).

Observability

• RetrievalMetrics / RetrievalTracer instrumentation seams
• Prometheus metrics for query latency and result counts

---

Full changelog

See the repository history for detailed changes.