ragleap-memory v0.3.0 release notes

ragleap-memory 0.3.0

Vector and hybrid search over vectors that your own embedder function produces. The library has no provider code, no keys and no network access. Keyword search stays the default. Python 3.10 and newer.

Behaviour changes (read first)

A 0.1.0 or 0.2.0 database file is migrated in place to schema 3 on first open (one transaction). A migrated file cannot be opened by 0.2.0 or older. Back up the file first if you may need to go back.
search() takes two new keyword arguments, mode and query_vector. The default (mode="keyword") is unchanged.
usage() has two new keys: embedded_tokens and embed_calls.
forget, erase and sweep_expired also remove the entry's vector (a database trigger).

What is new

Options on SQLiteStore and ShardedStore: embedder, embedding_model, embedding_dim, embed_quota_tokens, embed_batch_size, max_vector_candidates.
embed_pending(scope, limit, dry_run, replace_stale) gives vectors to entries that have none. add() never calls the embedder, and dry_run=True shows what would be sent without sending anything.
search(mode="vector" | "hybrid", query_vector=...): cosine similarity over at most max_vector_candidates entries (newest first, after all filters), or reciprocal rank fusion of keyword and vector results. kinds, min_trust, k, max_tokens, superseded and expired entries work in every mode.
A per-tenant daily cap on embedder tokens, checked and counted before each call. If a batch would pass the cap, only the entries that fit are embedded; if not even one fits, QuotaExceededError is raised before your function is called.
EmbedderError when the embedder fails or returns something unusable; its message never contains text or vectors, and nothing from that batch is stored.

What this does not defend

Vectors are stored unencrypted next to the text and can reveal information about it. The texts you embed leave the process wherever your embedder sends them. A vector scan covers at most max_vector_candidates entries; older entries are not scanned in vector mode. Search quality depends on your embedder and has not been measured. See docs/threat-model.md (rows 13 to 15). No independent security review has happened.

Verified (real output)

Pull request #1284: all 52 CI checks passed, including ragleap-memory-tests on Python 3.10, 3.11 and 3.12.
VPS (Python 3.10.12, SQLite 3.37.2): 472 tests pass (306 from 0.2.0 and 166 new).
Sandbox: 472 tests pass on Python 3.12.3 and 3.10.20. Mutation check: 177 of 177 mutations killed on both.
The released wheel was installed fresh from PyPI on Python 3.10.20. A database written by the released 0.2.0 opened with it, migrated to schema 3, kept its usage counters, and was then embedded and searched; each tenant only got its own vectors. The four Python files in the wheel are identical to the files merged in #1284.

Not verified

Windows and macOS; big-endian machines (vectors are stored little-endian with a byte swap that has never been run).
No real embedding provider was used (the tests use a deterministic fake embedder); retrieval quality has not been measured.
The scan timings in the threat model (about 128 ms for 10,000 vectors of 384 numbers) were measured once, in the sandbox.
The mutation check was not run on the VPS. The provenance record of the source archive was not checked (only the wheel's).
Several processes writing one file, and network file systems.

Provenance

Tag ragleap-memory-v0.3.0 on commit 928ef2b44f981dd5f72cae279814054a31401afc (merge of #1284).
Published from GitHub Actions by trusted publishing (repository ragleap/ragleap-core, workflow release.yml, environment pypi). PyPI holds a provenance record for the wheel; its digest matches the wheel.
SHA-256: wheel d1672d160e7cbd4b7e1a404a3968951e9d0a8f6ad60f22b5e5ae74da1738f0b2; source archive 3d78d0a219e520fa22d869356958910e1cbdc2655a813bb2cfb0e5b4521e83db.