atif-sql 0.2.0__py3-none-any.whl

atif_duck/infrastructure/stored_artifacts.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Find and read a session's stored JSON artifacts, compressed or plain.
+
+:mod:`atif_duck.domain.artifacts` says which artifacts may be stored as
+``<name>.zst``; this module does the filesystem half. DuckDB's JSON readers
+decompress a ``.zst`` file on their own (the compression is detected per file
+from its extension), so a SQL reader only needs the right path. The Python
+readers (the columnar producer's events input, the lake loader's trajectory
+decode) go through :func:`read_bytes` and :func:`iter_lines`.
+
+A zstd frame written by atif-sql records its decompressed size in the frame
+header, which :func:`decoded_size` reads (18 bytes, no decompression): DuckDB's
+``maximum_object_size`` has to be sized from the document, not from the far
+smaller compressed file. A frame without that field (written by another tool)
+is measured by decompressing it once.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING
+
+from atif_duck.domain.artifacts import COMPRESSED_SUFFIX, stored_names
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+#: The largest zstd frame header (magic, descriptor, window, dictionary id,
+#: content size): enough bytes to read the content size of any frame.
+_FRAME_HEADER_MAX_BYTES: int = 18
+
+#: Chunk size for the fallback that measures a frame by decompressing it.
+_MEASURE_CHUNK_BYTES: int = 1024 * 1024
+
+
+def is_compressed(path: Path) -> bool:
+    """True when ``path`` is a compressed artifact (by its suffix, as DuckDB decides)."""
+    return path.name.endswith(COMPRESSED_SUFFIX)
+
+
+def stored_artifact(session_dir: Path, name: str) -> Path | None:
+    """The file ``name`` is stored under in ``session_dir``, or ``None`` if neither exists."""
+    for candidate in stored_names(name):
+        path = session_dir / candidate
+        if path.is_file():
+            return path
+    return None
+
+
+def _measure(path: Path) -> int:
+    import zstandard
+
+    if not is_compressed(path):
+        return path.stat().st_size
+    with path.open("rb") as handle:
+        header = handle.read(_FRAME_HEADER_MAX_BYTES)
+    size = zstandard.frame_content_size(header) if header else 0
+    if size >= 0:
+        return int(size)
+    total = 0
+    with path.open("rb") as handle, zstandard.ZstdDecompressor().stream_reader(handle) as reader:
+        while chunk := reader.read(_MEASURE_CHUNK_BYTES):
+            total += len(chunk)
+    return total
+
+
+def decoded_size(path: Path) -> int:
+    """The artifact's size once decompressed (a plain file's own size); 0 if unreadable."""
+    import zstandard
+
+    try:
+        return _measure(path)
+    except (OSError, zstandard.ZstdError):
+        return 0
+
+
+def read_bytes(path: Path) -> bytes:
+    """The artifact's decompressed bytes."""
+    if not is_compressed(path):
+        return path.read_bytes()
+    import zstandard
+
+    with path.open("rb") as handle, zstandard.ZstdDecompressor().stream_reader(handle) as reader:
+        return reader.readall()
+
+
+def iter_lines(path: Path) -> Iterator[str]:
+    """The artifact's decompressed text, line by line (a missing file yields nothing)."""
+    try:
+        raw = path.open("rb")
+    except FileNotFoundError:
+        return
+    with raw:
+        if is_compressed(path):
+            import zstandard
+
+            with (
+                zstandard.ZstdDecompressor().stream_reader(raw) as reader,
+                io.TextIOWrapper(reader, encoding="utf-8") as text,
+            ):
+                yield from text
+        else:
+            with io.TextIOWrapper(raw, encoding="utf-8") as text:
+                yield from text
+
+
+__all__ = [
+    "decoded_size",
+    "is_compressed",
+    "iter_lines",
+    "read_bytes",
+    "stored_artifact",
+]

atif_embed/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""atif-embed: embedding provider + LanceDB vector store + embed backfill.
+
+The VSS write path over the ATIF corpus: Cohere Embed v4 on Bedrock
+(``infrastructure/cohere_bedrock.py``), a local LanceDB embeddings store
+(``infrastructure/lance_store.py``), a contract-layout corpus reader behind
+the :class:`~atif_embed.domain.ports.TextRowsPort`
+(``infrastructure/corpus_text_rows.py``), and the backfill use case
+(``application/embed.py``). Independent of every sibling package — only
+atif-cli composes (import-linter independence contract).
+"""

atif_embed/application/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Application use cases for atif-embed: the embedding backfill."""

atif_embed/application/embed.py

@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Embedding backfill use case.
+
+Discovers steps with no CURRENT embedding (through :class:`TextRowsPort`,
+against the Lance store's ``{uuid: text_hash}`` map), embeds them through the
+:class:`EmbeddingProvider` port, and appends the vectors to the LanceDB store
+keyed by the step's primary raw-record uuid.
+
+The provider's ``model_id`` / ``dimension`` are stamped on every row and
+enforced against the store's prior stamp (fail-loud on a provider switch:
+mixing vector spaces silently corrupts kNN search). Loss is bounded at three
+levels: discovery is consumed one chunk at a time, checkpoints of
+``max(batch_size * 4, 256)`` rows commit progress mid-run, and a batch that
+fails terminally inside a chunk does not discard the batches around it. A
+Lance ``optimize()`` runs every 8 chunks and a final optimize +
+``ensure_index`` on the way out.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime
+from itertools import islice
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from atif_embed.domain.embedding_guard import ensure_store_matches
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from atif_embed.domain.ports import EmbeddingProvider, TextRowsPort, VectorStorePort
+    from atif_embed.domain.text_stamp import PendingText
+    from atif_embed.infrastructure.settings import EmbedSettings
+
+#: Optimize the Lance store after this many appended chunks.
+_OPTIMIZE_EVERY_CHUNKS = 8
+
+
+def discover_unembedded(
+    corpus_root: Path,
+    *,
+    text_rows: TextRowsPort,
+    store: VectorStorePort,
+    limit: int | None = None,
+) -> Iterator[PendingText]:
+    """Yield the texts that have no CURRENT embedding.
+
+    The store's ``{uuid: text_hash}`` map is read once (column-projected
+    scan) and the staleness comparison happens inside the text-rows adapter,
+    before the limit cap, so ``--limit N`` always makes N rows of forward
+    progress. Lazy: the caller consumes one write-chunk at a time.
+    """
+    embedded = store.get_embedded_hashes()
+    return text_rows.iter_unembedded(corpus_root, embedded=embedded, limit=limit)
+
+
+async def run_backfill(
+    *,
+    corpus_root: Path,
+    settings: EmbedSettings,
+    embedder: EmbeddingProvider | None = None,
+    text_rows: TextRowsPort | None = None,
+    store: VectorStorePort | None = None,
+    limit: int | None = None,
+    dry_run: bool = False,
+) -> int | dict[str, Any]:
+    """Discover unembedded steps, embed them, and append to the Lance store.
+
+    A run that embedded every row its discovery yielded, and whose discovery
+    ran to its end, calls ``text_rows.commit`` with the store's row count, so
+    a reader with a watermark (the lake reader) can start the next run from
+    there. A dry run never commits.
+
+    Parameters
+    ----------
+    corpus_root
+        Materialized corpus root (the directory containing ``sessions/``).
+    settings
+        Embedding settings (model, batch size, concurrency, lance uri).
+    embedder
+        Optional :class:`EmbeddingProvider`; defaults to the provider
+        ``settings.embed_provider`` selects (imported lazily so dry runs never
+        load boto3 or torch).
+    text_rows
+        Optional :class:`TextRowsPort`; defaults to the contract-layout
+        DuckDB reader.
+    store
+        Optional :class:`VectorStorePort`; defaults to the Lance-backed store
+        over ``settings.lance_uri``.
+    limit
+        Optional cap on the number of steps embedded this run.
+    dry_run
+        If true, log the plan and return a plan dict without embedding calls.
+
+    Returns
+    -------
+    int | dict
+        Under ``dry_run=True``, a plan dict with ``{pipeline, discovery,
+        candidates, batches, batch_size, concurrency, provider, model, dim,
+        store, limit, dry_run}``.
+        Otherwise, count of newly written rows (0 when nothing is pending).
+    """
+    import polars as pl
+
+    lance_uri = settings.resolve_lance_uri(corpus_root)
+    if text_rows is None:
+        from atif_embed.infrastructure.corpus_text_rows import DuckDbTextRows
+
+        text_rows = DuckDbTextRows()
+    if store is None:
+        from atif_embed.infrastructure.lance_store import LanceVectorStore
+
+        store = LanceVectorStore(lance_uri, dim=settings.embedding_dim)
+
+    plan_model = settings.expected_embedding_identity()[0]
+    batch_size = settings.active_batch_size
+    stored = store.get_embedded_hashes()
+    pending = text_rows.iter_unembedded(corpus_root, embedded=stored, limit=limit)
+
+    if dry_run:
+        candidates = sum(1 for _ in pending)
+        n_batches = (candidates + batch_size - 1) // batch_size
+        if candidates == 0:
+            logger.info("No unembedded steps found - nothing to do")
+        else:
+            logger.info(
+                "Backfill plan: {} steps, {} batches, concurrency={}, model={}; "
+                "dry_run=True - skipping embedding calls",
+                candidates,
+                n_batches,
+                settings.active_concurrency,
+                plan_model,
+            )
+        return {
+            "pipeline": "embed",
+            "discovery": text_rows.discovery,
+            "candidates": candidates,
+            "batches": n_batches,
+            "batch_size": batch_size,
+            "concurrency": settings.active_concurrency,
+            "provider": settings.embed_provider,
+            "model": plan_model,
+            "dim": settings.embedding_dim,
+            "store": str(lance_uri),
+            "limit": limit,
+            "dry_run": True,
+        }
+
+    # Chunk must be a multiple of batch_size so a checkpoint boundary never
+    # splits a provider batch.
+    chunk_size = max(batch_size * 4, 256)
+    rows = iter(pending)
+    first_chunk = list(islice(rows, chunk_size))
+    if not first_chunk:
+        logger.info("No unembedded steps found - nothing to do")
+        text_rows.commit(stored_rows=len(stored))
+        return 0
+
+    # Build the provider once for the whole run. dimension / model_id become
+    # the single contract source. Deferred import keeps boto3 and torch off
+    # the dry-run / nothing-pending paths above, which return before this point.
+    if embedder is None:
+        from atif_embed.infrastructure.providers import build_embedder
+
+        embedder = build_embedder(settings)
+    model_id = embedder.model_id
+    dim = embedder.dimension
+
+    # Fail-loud guard: if the store was written by a different provider/model,
+    # refuse to append into it (mixing vector spaces silently corrupts kNN).
+    identity = store.table_identity()
+    if identity is not None:
+        stored_model, stored_dim = identity
+        ensure_store_matches(
+            stored_model=stored_model,
+            stored_dim=stored_dim,
+            expected_model=model_id,
+            expected_dim=dim,
+        )
+
+    total_t0 = time.monotonic()
+    written = 0
+    skipped = 0
+    chunk_index = 0
+    chunks_since_optimize = 0
+    chunk: list[PendingText] | None = first_chunk
+    while chunk:
+        chunk_index += 1
+        logger.info("Chunk {}: embedding {} steps", chunk_index, len(chunk))
+        t0 = time.monotonic()
+        vectors = await embedder.embed_documents([p.text for p in chunk])
+        elapsed = time.monotonic() - t0
+
+        embedded = [
+            (pending_text, vector)
+            for pending_text, vector in zip(chunk, vectors, strict=True)
+            if vector is not None
+        ]
+        failed = len(chunk) - len(embedded)
+        skipped += failed
+        logger.info(
+            "Chunk done in {:.1f}s ({:.1f} vec/s){}",
+            elapsed,
+            len(embedded) / elapsed if elapsed > 0 else 0.0,
+            f"; {failed} rows failed and stay unembedded for the next run" if failed else "",
+        )
+
+        if embedded:
+            # Replace before append: a stale row under the same uuid would
+            # otherwise sit beside the new vector and fan the kNN join out
+            # across both.
+            stale = [p.uuid for p, _ in embedded if p.replaces_existing]
+            if stale:
+                deleted = store.delete_uuids(stale)
+                logger.info("Replacing {} stale rows whose source text changed", deleted)
+            now = datetime.now(UTC)
+            # Force a fixed-size Array so to_arrow() produces
+            # pa.list_(pa.float32, dim) — what Lance requires for vector
+            # columns. A regular pl.List becomes a variable-size list and
+            # Lance rejects it for indexing.
+            df = pl.DataFrame(
+                {
+                    "uuid": [p.uuid for p, _ in embedded],
+                    "model": [model_id] * len(embedded),
+                    "dim": [dim] * len(embedded),
+                    "embedding": [v for _, v in embedded],
+                    "embedded_at": [now] * len(embedded),
+                    "text_hash": [p.text_hash for p, _ in embedded],
+                    "truncated": [p.truncated for p, _ in embedded],
+                },
+                schema={
+                    "uuid": pl.Utf8,
+                    "model": pl.Utf8,
+                    "dim": pl.Int32,
+                    "embedding": pl.Array(pl.Float32, dim),
+                    "embedded_at": pl.Datetime("us", "UTC"),
+                    "text_hash": pl.Utf8,
+                    "truncated": pl.Boolean,
+                },
+            )
+            store.add_chunk(df)
+            written += len(embedded)
+            chunks_since_optimize += 1
+            logger.info("Checkpoint: {} rows -> {}", len(df), lance_uri)
+
+            # Compact periodically so fragment count stays bounded during long
+            # backfills.
+            if chunks_since_optimize >= _OPTIMIZE_EVERY_CHUNKS:
+                store.optimize()
+                chunks_since_optimize = 0
+
+        chunk = list(islice(rows, chunk_size))
+
+    # Final compaction + index ensure on the way out so the search command
+    # sees an up-to-date index without paying brute-force scan latency.
+    store.optimize()
+    store.ensure_index(metric=settings.hnsw_metric)
+
+    # A watermark may only move past rows that are all stored: a failed row
+    # has to be found again next run, and a run cut short by --limit never
+    # read the rest (the reader itself checks that second half).
+    if skipped == 0:
+        text_rows.commit(stored_rows=len(store.get_embedded_hashes()))
+
+    total_elapsed = time.monotonic() - total_t0
+    logger.info(
+        "Backfill complete: {} embeddings in {:.1f}s ({:.1f} vec/s overall){}",
+        written,
+        total_elapsed,
+        written / total_elapsed if total_elapsed > 0 else 0.0,
+        f"; {skipped} rows failed and remain unembedded" if skipped else "",
+    )
+    return written
+
+
+def embed_query(text: str, *, settings: EmbedSettings) -> list[float]:
+    """Embed a single query string for nearest-neighbor search.
+
+    Thin shim over the selected provider (imported lazily): returns a float
+    query vector of length ``settings.embedding_dim``. Cohere forces ``float``
+    for queries even when documents were stored int8; EmbeddingGemma 2 embeds
+    under its ``SearchQuery`` prompt.
+    """
+    from atif_embed.infrastructure.providers import build_embedder
+
+    return build_embedder(settings).embed_query(text)
+
+
+__all__ = ["discover_unembedded", "embed_query", "run_backfill"]

atif_embed/application/prune.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Find, and on request delete, the stored vectors no lake step names.
+
+A row in the Lance store is an orphan when its uuid is the primary uuid of no
+step the lake holds for the corpus: its session was deleted before the corpus
+kept removed sessions, or a converter change re-keyed the step. Search joins
+hits to steps, so an orphan never shows up in a result, but it still takes
+space and still competes for the top-k before the join drops it.
+
+The lake is the reference because it holds every session the corpus holds,
+retained ones included. The caller must make sure no session is still
+waiting for a lake write (atif-cli checks the corpus's pending list), since
+such a session's vectors would look orphaned until its rows land.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from atif_embed.domain.ports import LakeStepsPort, VectorStorePort
+
+#: uuids per Lance delete predicate.
+_DELETE_CHUNK = 1000
+
+
+def prune_orphans(
+    corpus_root: Path,
+    *,
+    lake: LakeStepsPort,
+    store: VectorStorePort,
+    dry_run: bool = True,
+) -> dict[str, Any] | None:
+    """Count the store's orphan rows, and delete them unless ``dry_run``.
+
+    Returns ``None`` when there is no lake to check against. Otherwise
+    ``{pipeline, stored, lake_keys, orphans, deleted, dry_run}``. A corpus
+    the lake holds no steps for is refused (nothing deleted, ``orphans``
+    still counted) rather than read as "every row is an orphan".
+    """
+    snapshot = lake.open_steps(corpus_root)
+    if snapshot is None:
+        return None
+    with snapshot:
+        keys = snapshot.step_keys()
+        position = snapshot.position
+    stored = store.get_embedded_hashes()
+    orphans = sorted(uuid for uuid in stored if uuid not in keys)
+    report: dict[str, Any] = {
+        "pipeline": "prune_orphans",
+        "lake_snapshot": position.snapshot_id,
+        "stored": len(stored),
+        "lake_keys": len(keys),
+        "orphans": len(orphans),
+        "deleted": 0,
+        "dry_run": dry_run,
+    }
+    if not keys:
+        logger.warning(
+            "prune: the lake holds no steps for {}; refusing to treat every stored row as an orphan",
+            corpus_root,
+        )
+        report["refused"] = "the lake holds no steps for this corpus"
+        return report
+    if dry_run or not orphans:
+        return report
+    for start in range(0, len(orphans), _DELETE_CHUNK):
+        store.delete_uuids(orphans[start : start + _DELETE_CHUNK])
+    store.optimize()
+    report["deleted"] = len(orphans)
+    logger.info("prune: deleted {} orphan rows from the store", len(orphans))
+    return report
+
+
+__all__ = ["prune_orphans"]

atif_embed/domain/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pure domain rules for atif-embed: ports, errors, and the identity guard."""

atif_embed/domain/discovery.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Turn ordered ``(uuid, text)`` step rows into the texts that need embedding.
+
+Every discovery source (the per-session trajectory reader and the lake reader)
+yields the same thing: the corpus's embeddable step rows in corpus order,
+``(primary uuid, flattened text)``. What happens next is one rule set, kept
+here so the two sources can't drift apart:
+
+* the first row for a uuid wins, so the store never gets two vectors for one
+  key (a resumed session can repeat an earlier session's records);
+* a uuid whose stored ``text_hash`` equals the current text's hash is already
+  embedded and is skipped;
+* a uuid stored under a different hash is STALE and comes back with
+  ``replaces_existing=True``;
+* ``limit`` caps the rows yielded, and it's applied AFTER the store
+  comparison, so ``--limit N`` always makes N rows of progress.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from atif_embed.domain.text_stamp import PendingText, text_hash
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+
+class PendingSelection:
+    """One pass of the selection rules over one stream of step rows.
+
+    :attr:`exhausted` turns true only when the stream ran out before the
+    limit did. A caller that keeps a watermark reads it to tell a complete
+    pass from one ``--limit`` cut short.
+    """
+
+    def __init__(self, *, embedded: dict[str, str] | None, limit: int | None) -> None:
+        self._embedded = embedded or {}
+        self._limit = limit
+        self.exhausted = False
+        self.yielded = 0
+
+    def select(self, rows: Iterable[tuple[str, str]]) -> Iterator[PendingText]:
+        """Yield the rows that need embedding, lazily."""
+        limit = self._limit
+        if limit is not None and limit <= 0:
+            return
+        seen: set[str] = set()
+        for uuid, text in rows:
+            if uuid in seen:
+                continue
+            seen.add(uuid)
+            stamp = text_hash(text)
+            stored = self._embedded.get(uuid)
+            if stored == stamp:
+                continue
+            self.yielded += 1
+            yield PendingText(
+                uuid=uuid,
+                text=text,
+                text_hash=stamp,
+                replaces_existing=stored is not None,
+            )
+            if limit is not None and self.yielded >= limit:
+                return
+        self.exhausted = True
+
+
+__all__ = ["PendingSelection"]

atif_embed/domain/embedding_guard.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""The fail-loud embedding provider/dimension guard (pure domain rule).
+
+Every embeddings-store row is stamped with the embedder's ``model_id`` and
+``dimension``, and both the write path
+(:func:`atif_embed.application.embed.run_backfill`) and the read/bind path
+(``atif_duck.infrastructure.registry.register_vss``, via the caller-supplied
+``expected_model`` / ``expected_dim``) read that stamp back and call
+:func:`ensure_store_matches` before touching vectors. A provider switch is
+destructive (different models live in incompatible vector spaces even at
+matching widths), so the guard fails loud rather than silently corrupting
+the kNN index.
+
+DELIBERATE TWIN of ``atif_duck.domain.embedding_guard``: atif-duck may never
+import atif-embed (independence contract) and this is a tiny pure rule, so
+each package carries its own copy. A behavioral change in one — including
+the recovery message — must be ported to the other.
+"""
+
+from __future__ import annotations
+
+from atif_embed.domain.errors import EmbeddingProviderMismatch
+
+#: Recovery instruction appended to the mismatch message. The store lives at
+#: ``<corpus_root>/embeddings_lance`` by default (see
+#: ``EmbedSettings.resolve_lance_uri``), NOT under a fixed home directory —
+#: naming a path the store isn't at makes the operator delete nothing and
+#: stay broken. Kept identical to atif-duck's twin copy.
+RECOVERY_HINT = (
+    "Re-embed under the new provider: rm -rf the Lance store directory "
+    "(ATIF_SQL_LANCE_URI, or <corpus-root>/embeddings_lance by default) "
+    "and re-run `atif-sql embed --all --no-dry-run` (a bare `atif-sql embed` "
+    "exits 64: a real run needs an explicit scope)."
+)
+
+
+def ensure_store_matches(
+    *,
+    stored_model: str | None,
+    stored_dim: int | None,
+    expected_model: str,
+    expected_dim: int | None,
+) -> None:
+    """Fail loud if a store's stamped identity differs from the active embedder.
+
+    ``stored_model`` / ``stored_dim`` come from the Lance ``model`` / ``dim``
+    columns (both stamped on every row). ``None`` for either means the store
+    is empty (fresh install) and any provider may claim it, so the check is a
+    no-op.
+
+    ``model_id`` is the primary identity: it is globally unique and encodes
+    the provider + model, so a match guarantees a compatible vector space.
+    Cohere is the one provider whose single ``model_id`` can emit different
+    Matryoshka widths, so ``expected_dim`` is also checked when supplied;
+    ``expected_dim=None`` trusts ``model_id`` alone.
+
+    On a genuine mismatch this raises :class:`EmbeddingProviderMismatch`
+    naming both sides and the exact recovery command.
+    """
+    if stored_model is None or stored_dim is None:
+        return
+    model_ok = stored_model == expected_model
+    dim_ok = expected_dim is None or stored_dim == expected_dim
+    if model_ok and dim_ok:
+        return
+    # The message stays INSIDE the raise: `test_guard_twin_pin.py` reads both
+    # twin modules as source text and requires `{RECOVERY_HINT}` to appear after
+    # the `raise EmbeddingProviderMismatch` keyword, which is what proves the
+    # shared constant reaches the operator rather than only sitting in the
+    # module. Hoisting the message to a local satisfies EM102 / TRY003 and
+    # defeats that pin, so both are suppressed here instead.
+    raise EmbeddingProviderMismatch(  # noqa: TRY003
+        "Embedding store was written by a different provider/model. "  # noqa: EM102
+        f"stored=(model={stored_model!r}, dim={stored_dim}) "
+        f"active=(model={expected_model!r}, dim={expected_dim}). "
+        "Vectors from different models live in incompatible spaces (even at "
+        "matching dimensions), so mixing them silently corrupts kNN search. "
+        f"{RECOVERY_HINT}"
+    )
+
+
+__all__ = ["RECOVERY_HINT", "ensure_store_matches"]