Skip to content

v2.3.0 — Embedder identity tracking

Choose a tag to compare

View all tags
@frandi frandi released this 09 May 04:39
· 7 commits to main since this release
v2.3.0
8e3c1a9

This release lays the groundwork for an upcoming WASM-backed embedder by adding embedder identity tracking to the persisted file format. The change closes a real footgun on its own — it warns when stored vectors and the current embedder come from different embedding spaces — and ensures users upgrading to a future edge-embedder release have the protection in place from day one.

All public APIs remain backward compatible with 2.2.0.

Install

npm install @trovec/core@2.3.0

Adapter packages are aligned at the same version:

npm install @trovec/embedder-local@2.3.0
npm install @trovec/embedder-ollama@2.3.0
npm install @trovec/embedder-openai@2.3.0
npm install -g @trovec/cli@2.3.0

Added

  • @trovec/core: Embedder identity tracking. Persisted .trovec files now record the Embedder.model string in a small JSON metadata section, and create() emits a console.warn on load when the configured embedder differs from the one that produced the stored vectors. This catches the silent-incompatibility footgun that occurs when users swap embedders without rebuilding the collection. The Embedder interface is unchanged; existing adapters need no updates. New public type export: PersistedMetadata.

Changed

  • @trovec/core: Persisted file format bumped from v1 to v2. The 16-byte header layout is preserved; a uint16-prefixed JSON metadata section now sits between header and entries.
    • Forward-compatible: the new core reads existing v1 files silently.
    • Not backward-compatible: older @trovec/core versions cannot read files written by this release. Users who downgrade after upgrading must rebuild affected collections.
    • WAL and encryption paths are unaffected.
  • Internal dependency ranges between @trovec/* packages have been tightened from ^2.2.0 to ^2.3.0.

Upgrade notes

For most users, upgrade is transparent — no code or data changes required. New writes use the v2 format automatically; existing v1 files keep reading.

If you are working with an embedder whose model string changes across versions (custom adapters, future bundled-weight adapters), expect to see a console.warn after upgrade pointing at the mismatch. The warning is informational; the load still succeeds. Either align your embedder configuration with the persisted identity, or rebuild the collection.

If you maintain rollback tooling that downgrades @trovec/core after upgrading, note that older versions cannot read v2 files. Plan for a rebuild step in your downgrade path.

Adapter convention

Adapters that bundle their own model weights should include a version suffix in their `model` string (for example, `"all-MiniLM-L6-v2@1.0.0"`) so weight upgrades trigger the warning. Adapters that delegate to an external service (`embedder-openai`, `embedder-ollama`) can use the model name as-is — versioning is owned by the service.

Full changelog: v2.2.0...v2.3.0

Assets 2
Loading