ltcai 11.9.0 → 12.0.0

package/latticeai/core/embedding_providers/base.py

@@ -45,8 +45,18 @@ _KNOWN_DIMS = {
     "gte-small": 384,
     "gte-base": 768,
     "gte-large": 1024,
+    "e5-small": 384,
+    "e5-base": 768,
     "e5-large": 1024,
+    "multilingual-e5-small": 384,
+    "multilingual-e5-small-mlx": 384,
+    "multilingual-e5-base": 768,
+    "multilingual-e5-base-mlx": 768,
     "multilingual-e5-large": 1024,
+    "multilingual-e5-large-mlx": 1024,
+    "snowflake-arctic-embed-l-v2.0-8bit": 1024,
+    "embeddinggemma-300m-4bit": 768,
+    "embeddinggemma-300m-8bit": 768,
     "text-embedding-3-small": 1536,
     "text-embedding-3-large": 3072,
     "text-embedding-ada-002": 1536,
@@ -86,6 +96,21 @@ class EmbeddingProvider:
     def embed_batch(self, texts: Sequence[str]) -> List[List[float]]:
         raise NotImplementedError
 
+    # ── optional: asymmetric models ───────────────────────────────────────
+    def embed_batch_for(
+        self, texts: Sequence[str], kind: str = "passage"
+    ) -> List[List[float]]:
+        """Embed for a *role*: ``"query"`` or ``"passage"``.
+
+        Most embedders are symmetric and ignore the role — the default here
+        does. The E5 family is not: it was trained with a literal ``query: ``
+        or ``passage: `` in front of the text, and dropping the instruction
+        costs real retrieval accuracy. ``POST /worker/embed`` already carries
+        the role (``kind``), so the one provider that needs it can have it
+        without every caller learning about instructions.
+        """
+        return self.embed_batch(texts)
+
     # ── derived (shared) ──────────────────────────────────────────────────
     def _model_id_with_dim(self, dim: int) -> str:
         """This provider's ``model_id`` restated at ``dim``.

package/latticeai/core/embedding_providers/profiles.py

@@ -10,6 +10,50 @@ from __future__ import annotations
 from typing import Any, Dict, List
 
 PRODUCTION_PROVIDER_PROFILES: Dict[str, Dict[str, Any]] = {
+    # ── one-click local profiles (v12.0.0) ────────────────────────────────
+    # These three carry `hf_repo_id` and `download_gb` because they are the
+    # ones a setup surface can *offer to fetch*: the id is what
+    # `huggingface_hub.snapshot_download` takes and what
+    # `autodetect.detect_local_mlx` looks for in the cache, so "offer",
+    # "download" and "detect" all name the same string. The rest of the table
+    # describes providers the user has to bring themselves (an Ollama server,
+    # an API key), which is why they have no repo id.
+    "local:multilingual-e5-small": {
+        "id": "local:multilingual-e5-small",
+        "provider": "mlx",
+        "model": "mlx-community/multilingual-e5-small-mlx",
+        "hf_repo_id": "mlx-community/multilingual-e5-small-mlx",
+        "download_gb": 0.24,
+        "dimensions": 384,
+        "grade": "production",
+        "family": "local",
+        "label": "Multilingual E5 Small (로컬)",
+        "detail": "한국어를 포함한 100여 개 언어. 240MB, 해시 임베더와 같은 384차원.",
+    },
+    "local:multilingual-e5-base": {
+        "id": "local:multilingual-e5-base",
+        "provider": "mlx",
+        "model": "mlx-community/multilingual-e5-base-mlx",
+        "hf_repo_id": "mlx-community/multilingual-e5-base-mlx",
+        "download_gb": 1.1,
+        "dimensions": 768,
+        "grade": "production",
+        "family": "local",
+        "label": "Multilingual E5 Base (로컬)",
+        "detail": "더 정확한 다국어 임베딩. 768차원이라 기존 색인은 다시 만들어야 합니다.",
+    },
+    "local:arctic-embed-l-v2": {
+        "id": "local:arctic-embed-l-v2",
+        "provider": "mlx",
+        "model": "mlx-community/snowflake-arctic-embed-l-v2.0-8bit",
+        "hf_repo_id": "mlx-community/snowflake-arctic-embed-l-v2.0-8bit",
+        "download_gb": 0.6,
+        "dimensions": 1024,
+        "grade": "production",
+        "family": "local",
+        "label": "Arctic Embed L v2 (로컬)",
+        "detail": "다국어 고품질 검색용 임베딩. 1024차원.",
+    },
     "local:bge-m3": {
         "id": "local:bge-m3",
         "provider": "mlx",

package/latticeai/core/embedding_providers/text.py

@@ -57,7 +57,32 @@ def _as_float_list(value: Any) -> List[Any]:
     return list(value)
 
 
+#: Longest token sequence an encoder-family embedding model accepts. BERT and
+#: XLM-R both stop at 512 including the two special tokens; a longer sequence
+#: is a hard failure inside the model, not a slow answer, so the ids are cut
+#: here rather than discovered at inference time.
+MLX_MAX_TOKENS = 512
+
+#: The E5 family was trained with these literal prefixes and loses accuracy
+#: without them. Keyed on the ``kind`` ``POST /worker/embed`` already sends.
+E5_PREFIXES: Dict[str, str] = {"query": "query: ", "passage": "passage: "}
+
+
+def _wants_e5_prefix(model: str) -> bool:
+    """Whether this model id names an E5-family checkpoint."""
+    return "e5" in str(model or "").lower()
+
+
 class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
+    """A local Apple-Silicon sentence embedder through ``mlx_embeddings``.
+
+    Nothing here reaches the network: the model must already be in the local
+    Hugging Face cache (that is exactly what
+    :func:`~.autodetect.detect_local_mlx` looks for). A missing package or a
+    missing snapshot is :class:`EmbeddingUnavailable`, which
+    :func:`resolve_embedder` turns into the honest hash fallback.
+    """
+
     provider = "mlx"
 
     def __init__(self, cfg: _RemoteConfig):
@@ -66,6 +91,7 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
             self.dim = _guess_dim(cfg.model, DEFAULT_EMBEDDING_DIM)
         self.model_id = f"mlx:{cfg.model}:{self.dim}"
         self._encoder: Optional[Tuple[str, Any, Any]] = None
+        self._prefixed = _wants_e5_prefix(cfg.model)
 
     def _load(self):
         if self._encoder is not None:
@@ -79,25 +105,37 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
         except Exception as exc:  # pragma: no cover - environment dependent
             raise EmbeddingUnavailable(f"MLX embedding model unavailable: {exc}") from exc
 
+    def embed_batch_for(
+        self, texts: Sequence[str], kind: str = "passage"
+    ) -> List[List[float]]:
+        """E5 asymmetry, honoured. Non-E5 models see the text unchanged."""
+        if not self._prefixed:
+            return self.embed_batch(texts)
+        prefix = E5_PREFIXES.get(str(kind or "passage").lower(), E5_PREFIXES["passage"])
+        return self.embed_batch([f"{prefix}{text}" for text in texts])
+
     def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
-        kind, model, tokenizer = self._load()
+        _, model, tokenizer = self._load()
         try:
             import mlx.core as mx  # type: ignore
 
             out: List[List[float]] = []
             for text in texts:
-                ids = tokenizer.encode(text)
-                tokens = mx.array([ids])
-                result = model(tokens)
-                pooled = result[0] if isinstance(result, (tuple, list)) else result
-                vec = mx.mean(pooled, axis=1)[0] if pooled.ndim == 3 else pooled[0]
-                out.append([float(x) for x in _as_float_list(vec.tolist())])
+                ids = list(tokenizer.encode(text))[:MLX_MAX_TOKENS]
+                result = model(mx.array([ids]))
+                out.append([float(x) for x in _pool(mx, result)])
             return out
         except EmbeddingUnavailable:
             raise
         except Exception as exc:  # pragma: no cover - environment dependent
             raise EmbeddingUnavailable(f"MLX embedding failed: {exc}") from exc
 
+    def metadata(self) -> Dict[str, Any]:
+        info = super().metadata()
+        info["instruction_prefixes"] = self._prefixed
+        info["max_tokens"] = MLX_MAX_TOKENS
+        return info
+
     def health(self) -> Dict[str, Any]:
         try:
             self._load()
@@ -106,6 +144,27 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
             return {"status": "unavailable", "detail": str(exc)}
 
 
+def _pool(mx: Any, result: Any) -> List[Any]:
+    """One sentence vector out of whatever shape the model handed back.
+
+    ``mlx_embeddings`` models return an output object carrying a pooled
+    ``text_embeds`` on newer versions and a bare hidden-state tensor on older
+    ones. Preferring the model's own pooled output matters: a checkpoint with a
+    trained pooler produces a better vector than a mean over its last layer,
+    and mean-pooling on top of an already-pooled row would be nonsense.
+    """
+    for attribute in ("text_embeds", "pooler_output"):
+        pooled = getattr(result, attribute, None)
+        if pooled is not None:
+            row = pooled[0] if pooled.ndim > 1 else pooled
+            return _as_float_list(row.tolist())
+    hidden = getattr(result, "last_hidden_state", None)
+    if hidden is None:
+        hidden = result[0] if isinstance(result, (tuple, list)) else result
+    row = mx.mean(hidden, axis=1)[0] if hidden.ndim == 3 else hidden[0]
+    return _as_float_list(row.tolist())
+
+
 class OllamaEmbeddingProvider(_NetworkEmbeddingProvider):
     provider = "ollama"
 
@@ -285,9 +344,13 @@ class ResolvedEmbedder:
     fell_back: bool
     health: Dict[str, Any]
     detail: str = ""
+    #: What :mod:`.autodetect` found on this machine, if anyone looked. It is
+    #: reported whether or not it was adopted, so a user running on the hash
+    #: fallback with a real embedder already downloaded can *see* that.
+    detected: Optional[Any] = None
 
     def as_dict(self) -> Dict[str, Any]:
-        return {
+        payload: Dict[str, Any] = {
             "requested_provider": self.requested,
             "active_provider": self.active,
             "fell_back": self.fell_back,
@@ -295,6 +358,9 @@ class ResolvedEmbedder:
             "detail": self.detail,
             **self.provider.metadata(),
         }
+        if self.detected is not None and hasattr(self.detected, "as_dict"):
+            payload["detected"] = self.detected.as_dict()
+        return payload
 
 
 def resolve_embedder(

package/latticeai/core/vector_index/__init__.py

@@ -0,0 +1,61 @@
+"""Search-side vector index backends (HNSW append + query).
+
+``POST /worker/vector/query`` serves this sidecar. ``lattice-retrieval``
+asks for top-k candidates when ``LATTICEAI_VECTOR_INDEX=hnsw`` and
+re-scores them exactly. Default env stays the brute scan.
+
+This package is the Python HNSW sidecar: a disposable ``.hnsw`` graph
+next to the brain database, with incremental ``add_items`` so a write no
+longer rebuilds the whole graph.
+
+Rebuild (not append) when:
+
+* the embedder identity (``model_id`` / dim / space) changed
+* any previously indexed id is absent (deletion). Tombstones exist in
+  hnswlib (``mark_deleted``) but a deletion-heavy store (more than
+  :data:`DELETE_REBUILD_RATIO` of the graph, or any delete when the
+  sidecar was loaded without source vectors) is cheaper to rebuild
+  than to fragment.
+"""
+
+from .hnsw import (
+    DELETE_REBUILD_RATIO,
+    HNSW_BACKEND,
+    HNSW_META_SUFFIX,
+    HNSW_SUFFIX,
+    HNSWLIB_MODULE,
+    HnswIndex,
+    hnswlib_available,
+    load_hnswlib,
+    sidecar_paths,
+)
+from .sidecar import (
+    GRAPH_DB_NAME,
+    VECTOR_QUERY_K_CAP,
+    decode_f32le,
+    query_sidecar,
+    reset_sidecar_cache,
+    resolve_graph_db,
+    sidecar_fingerprint,
+    sidecar_freshness,
+)
+
+__all__ = [
+    "DELETE_REBUILD_RATIO",
+    "GRAPH_DB_NAME",
+    "HNSW_BACKEND",
+    "HNSW_META_SUFFIX",
+    "HNSW_SUFFIX",
+    "HNSWLIB_MODULE",
+    "HnswIndex",
+    "VECTOR_QUERY_K_CAP",
+    "decode_f32le",
+    "hnswlib_available",
+    "load_hnswlib",
+    "query_sidecar",
+    "reset_sidecar_cache",
+    "resolve_graph_db",
+    "sidecar_fingerprint",
+    "sidecar_freshness",
+    "sidecar_paths",
+]

package/latticeai/core/vector_index/hnsw.py

@@ -0,0 +1,383 @@
+"""Approximate nearest-neighbour index with incremental append.
+
+``hnswlib`` is optional (``pip install hnswlib``; the published
+``ltcai[hnsw]`` extra was retired in 11.6.0 when the write path moved to
+Rust). When the compiled module is missing the import is caught here and
+reported as a reason string; search then returns no ANN hits rather than
+pretending.
+
+Policy, also stated on :meth:`HnswIndex.add_items`:
+
+* **Append** new ids onto the live graph (``resize_index`` + ``add_items``).
+* **Full rebuild** on provider/dim/space change, on any deletion when the
+  graph was loaded from a sidecar without source vectors, or when deletes
+  exceed :data:`DELETE_REBUILD_RATIO` of the current size.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+HNSW_BACKEND = "hnsw"
+HNSWLIB_MODULE = "hnswlib"
+HNSW_SUFFIX = ".hnsw"
+HNSW_META_SUFFIX = ".hnsw.meta.json"
+#: Rebuild instead of tombstoning once this fraction of the graph would go.
+DELETE_REBUILD_RATIO = 0.10
+
+IndexItem = Tuple[str, Sequence[float], Mapping[str, Any]]
+ScoredId = Tuple[str, float]
+
+
+def load_hnswlib() -> Tuple[Optional[Any], Optional[str]]:
+    """Import ``hnswlib`` or explain why it is unavailable (never raises)."""
+    try:
+        import hnswlib  # noqa: PLC0415 — guarded, optional, import-on-demand
+    except Exception as exc:  # noqa: BLE001 — any import failure is "no ANN"
+        return None, (
+            f"{HNSWLIB_MODULE} is not available ({exc}); install it with "
+            "`pip install hnswlib` to use the approximate index"
+        )
+    return hnswlib, None
+
+
+def hnswlib_available() -> bool:
+    """True when the optional ANN engine can actually be imported."""
+    module, _ = load_hnswlib()
+    return module is not None
+
+
+def sidecar_paths(db_path: Any) -> Tuple[Path, Path]:
+    """``(index file, meta file)`` for a brain database path."""
+    base = Path(db_path)
+    return (
+        base.with_suffix(HNSW_SUFFIX),
+        base.with_suffix(HNSW_META_SUFFIX),
+    )
+
+
+class HnswIndex:
+    """Small-M HNSW graph over the brain's embeddings."""
+
+    def __init__(
+        self,
+        *,
+        dim: int,
+        space: str = "cosine",
+        ef_construction: int = 400,
+        m: int = 32,
+        ef_search: int = 400,
+        model_id: str = "",
+    ) -> None:
+        self._dim = int(dim)
+        self._space = str(space)
+        self._ef_construction = int(ef_construction)
+        self._m = int(m)
+        self._ef_search = int(ef_search)
+        self._model_id = str(model_id)
+        self._module, self._detail = load_hnswlib()
+        self._vectors: Dict[str, List[float]] = {}
+        self._metadata: Dict[str, Dict[str, Any]] = {}
+        self._labels: List[str] = []
+        self._ann: Any = None
+        self._dirty = True
+        self._loaded = False
+
+    @property
+    def backend(self) -> str:
+        return HNSW_BACKEND
+
+    @property
+    def approx(self) -> bool:
+        return True
+
+    @property
+    def exhaustive(self) -> bool:
+        return False
+
+    @property
+    def available(self) -> bool:
+        return self._module is not None
+
+    @property
+    def unavailable_detail(self) -> Optional[str]:
+        return self._detail
+
+    @property
+    def loaded_from_sidecar(self) -> bool:
+        """True when the graph came off disk instead of being rebuilt."""
+        return self._loaded
+
+    @property
+    def dim(self) -> int:
+        return self._dim
+
+    @property
+    def model_id(self) -> str:
+        return self._model_id
+
+    def _identity_matches(self, dim: int, space: str, model_id: str) -> bool:
+        return (
+            int(dim) == self._dim
+            and str(space) == self._space
+            and str(model_id) == self._model_id
+        )
+
+    def add(
+        self,
+        id: str,
+        vector: Sequence[float],
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        if self._loaded:
+            raise RuntimeError(
+                "this HnswIndex was loaded from a sidecar and holds no source "
+                "vectors; rebuild it from vector_embeddings before mutating"
+            )
+        key = str(id)
+        self._vectors[key] = [float(value) for value in vector]
+        self._metadata[key] = dict(metadata or {})
+        self._dirty = True
+
+    def remove(self, id: str) -> None:
+        if self._loaded:
+            raise RuntimeError(
+                "this HnswIndex was loaded from a sidecar and holds no source "
+                "vectors; rebuild it from vector_embeddings before mutating"
+            )
+        key = str(id)
+        self._vectors.pop(key, None)
+        self._metadata.pop(key, None)
+        self._dirty = True
+
+    def rebuild(self, items: Iterable[IndexItem]) -> None:
+        """Replace the held set and mark the graph for a full rebuild."""
+        self._vectors.clear()
+        self._metadata.clear()
+        self._labels.clear()
+        self._ann = None
+        self._loaded = False
+        for item_id, vector, metadata in items:
+            self.add(item_id, vector, metadata)
+        self._dirty = True
+
+    def add_items(
+        self,
+        items: Iterable[IndexItem],
+        *,
+        dim: Optional[int] = None,
+        space: Optional[str] = None,
+        model_id: Optional[str] = None,
+    ) -> str:
+        """Append new vectors, or rebuild when the policy says so.
+
+        Returns ``"append"`` or ``"rebuild"`` so a bench can time the two
+        doors without guessing.
+
+        Full rebuild when the embedder identity changed, when any currently
+        indexed id is missing from the incoming set (a deletion), when
+        deletes would exceed :data:`DELETE_REBUILD_RATIO`, or when this
+        instance was loaded from a sidecar and cannot append (no source
+        vectors to keep the label map honest).
+        """
+        incoming: Dict[str, IndexItem] = {}
+        for item_id, vector, metadata in items:
+            incoming[str(item_id)] = (str(item_id), vector, metadata)
+
+        want_dim = self._dim if dim is None else int(dim)
+        want_space = self._space if space is None else str(space)
+        want_model = self._model_id if model_id is None else str(model_id)
+        if not self._identity_matches(want_dim, want_space, want_model):
+            self._dim = want_dim
+            self._space = want_space
+            self._model_id = want_model
+            self.rebuild(incoming.values())
+            return "rebuild"
+
+        if self._loaded:
+            self.rebuild(incoming.values())
+            return "rebuild"
+
+        current = set(self._vectors)
+        incoming_ids = set(incoming)
+        deleted = current - incoming_ids
+        if deleted:
+            ratio = len(deleted) / max(1, len(current))
+            if ratio >= DELETE_REBUILD_RATIO or not current:
+                self.rebuild(incoming.values())
+                return "rebuild"
+            # Sparse deletes: drop the gone ids and rebuild so we never
+            # leave a tombstoned hole the sidecar cannot describe.
+            self.rebuild(incoming.values())
+            return "rebuild"
+
+        new_ids = [item_id for item_id in incoming if item_id not in current]
+        if not new_ids and not self._dirty and self._ann is not None:
+            return "append"
+        for item_id in new_ids:
+            _, vector, metadata = incoming[item_id]
+            self.add(item_id, vector, metadata)
+        if self._ann is not None and new_ids and self._module is not None:
+            self._append_live(new_ids)
+            return "append"
+        self._dirty = True
+        return "append" if new_ids or self._ann is not None else "rebuild"
+
+    def _new_graph(self, module: Any, capacity: int) -> Any:
+        graph = module.Index(space=self._space, dim=self._dim)
+        graph.init_index(
+            max_elements=max(1, capacity),
+            ef_construction=self._ef_construction,
+            M=self._m,
+        )
+        return graph
+
+    def _append_live(self, new_ids: Sequence[str]) -> None:
+        """``hnswlib`` ``resize_index`` + ``add_items`` for ``new_ids`` only."""
+        module = self._module
+        graph = self._ann
+        if module is None or graph is None:
+            self._dirty = True
+            return
+        start = len(self._labels)
+        needed = start + len(new_ids)
+        try:
+            current_max = int(graph.get_max_elements())
+        except Exception:  # noqa: BLE001 — some builds expose no getter
+            current_max = start
+        if needed > current_max:
+            graph.resize_index(max(needed, current_max * 2 if current_max else needed))
+        graph.add_items(
+            [self._vectors[key] for key in new_ids],
+            list(range(start, start + len(new_ids))),
+        )
+        self._labels.extend(new_ids)
+        self._dirty = False
+
+    def _ensure_graph(self) -> Any:
+        """Build the graph if the held vectors changed (None when disabled)."""
+        module = self._module
+        if module is None:
+            return None
+        if self._ann is not None and not self._dirty:
+            return self._ann
+        labels = list(self._vectors)
+        graph = self._new_graph(module, max(len(labels), 1))
+        if labels:
+            graph.add_items(
+                [self._vectors[key] for key in labels],
+                list(range(len(labels))),
+            )
+        self._ann = graph
+        self._labels = labels
+        self._dirty = False
+        return graph
+
+    def search(
+        self,
+        query: Sequence[float],
+        top_k: int,
+        filter: Optional[Mapping[str, Any]] = None,
+    ) -> List[ScoredId]:
+        graph = self._ensure_graph()
+        if graph is None or not self._labels:
+            return []
+        floor = float("-inf")
+        if filter and filter.get("min_score") is not None:
+            try:
+                floor = float(filter["min_score"])
+            except (TypeError, ValueError):
+                floor = float("-inf")
+        wanted = max(1, min(int(top_k), len(self._labels)))
+        graph.set_ef(max(self._ef_search, wanted))
+        labels, distances = graph.knn_query([list(query)], k=wanted)
+        scored: List[ScoredId] = []
+        for label, distance in zip(labels[0], distances[0], strict=True):
+            score = 1.0 - float(distance)
+            if score < floor:
+                continue
+            scored.append((self._labels[int(label)], score))
+        return scored
+
+    def stats(self) -> Dict[str, Any]:
+        return {
+            "backend": self.backend,
+            "size": len(self._labels) if self._loaded else len(self._vectors),
+            "dim": self._dim,
+            "approx": True,
+            "exhaustive": False,
+            "available": self.available,
+            "detail": self._detail,
+            "model_id": self._model_id,
+        }
+
+    def save(self, db_path: Any, *, fingerprint: str) -> bool:
+        """Write the graph + label map beside the brain database."""
+        graph = self._ensure_graph()
+        if graph is None or not self._labels:
+            return False
+        index_path, meta_path = sidecar_paths(db_path)
+        try:
+            index_path.parent.mkdir(parents=True, exist_ok=True)
+            graph.save_index(str(index_path))
+            meta_path.write_text(
+                json.dumps(
+                    {
+                        "fingerprint": str(fingerprint),
+                        "dim": self._dim,
+                        "space": self._space,
+                        "model_id": self._model_id,
+                        "labels": self._labels,
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+        except Exception:  # noqa: BLE001 — persistence is best-effort
+            return False
+        return True
+
+    def load(self, db_path: Any, *, fingerprint: str) -> bool:
+        """Adopt a sidecar graph when it provably matches ``fingerprint``."""
+        module = self._module
+        if module is None:
+            return False
+        index_path, meta_path = sidecar_paths(db_path)
+        try:
+            meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            matches = str(meta["fingerprint"]) == str(fingerprint)
+            matches = matches and int(meta["dim"]) == self._dim
+            if meta.get("model_id") not in (None, "", self._model_id):
+                matches = False
+            labels = [str(label) for label in meta["labels"]]
+        except Exception:  # noqa: BLE001 — absent/corrupt sidecar = rebuild
+            return False
+        if not (matches and labels):
+            return False
+        try:
+            graph = module.Index(space=self._space, dim=self._dim)
+            graph.load_index(str(index_path), max_elements=len(labels))
+        except Exception:  # noqa: BLE001 — corrupt binary = rebuild
+            return False
+        self._ann = graph
+        self._labels = labels
+        self._vectors.clear()
+        self._metadata.clear()
+        self._dirty = False
+        self._loaded = True
+        return True
+
+
+__all__ = [
+    "DELETE_REBUILD_RATIO",
+    "HNSW_BACKEND",
+    "HNSW_META_SUFFIX",
+    "HNSW_SUFFIX",
+    "HNSWLIB_MODULE",
+    "HnswIndex",
+    "hnswlib_available",
+    "load_hnswlib",
+    "sidecar_paths",
+]