okfgraph 0.2.7__tar.gz → 0.2.12__tar.gz

{okfgraph-0.2.7 → okfgraph-0.2.12}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: okfgraph
-Version: 0.2.7
+Version: 0.2.12
 Summary: Ladybug-backed OKF knowledge graph with ONNX + Jina v5 embeddings
 License-Expression: Apache-2.0 OR MIT
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ladybug==0.20.3
-Requires-Dist: okf-embed>=0.1
+Requires-Dist: embroider<0.2,>=0.1
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-frontmatter>=1.0
 Requires-Dist: pyyaml>=6.0
@@ -44,7 +44,7 @@ model loaded**, structural diffing, scored health checks, and Obsidian-vault
 compatible wikilinks — in a single LadybugDB file.
 
 Design stance: **slim dependencies, no legacy fallbacks.** Embeddings run
-through the `okf-embed` Rust wheel (ONNX Runtime, no torch / transformers /
+through the `embroider` Rust wheel (ONNX Runtime, no torch / transformers /
 optimum anywhere). PDF conversion runs through the `bobine` Rust engine behind
 a swappable `DocumentConverter` seam. What isn't needed isn't installed.
 
@@ -54,7 +54,7 @@ a swappable `DocumentConverter` seam. What isn't needed isn't installed.
 
 | Category | Features |
 |---|---|
-| **Embeddings** | Jina v5 (`jina-embeddings-v5-text-small-retrieval`) via the `okf-embed` Rust wheel; last-token pooling, Matryoshka truncation (32–1024, default 512); omni model (`…-omni-small-retrieval`) lazy-loaded for images only |
+| **Embeddings** | Jina v5 (`jina-embeddings-v5-text-small-retrieval`) via the `embroider` Rust wheel; last-token pooling, Matryoshka truncation (32–1024, default 512); omni model (`…-omni-small-retrieval`) lazy-loaded for images only |
 | **Search** | Hybrid RRF fusion (vector + FTS) at concept and chunk granularity; `rank=none\|hub\|ppr` — including **PPR**: lexical seeds → exact Personalized PageRank, zero model load, deterministic |
 | **Read** | Body / chunks / rebuilt document / graph context, with optional **token budgets** (`max_tokens`): self first, then PPR-ranked neighbours, index-first for context |
 | **Storage** | LadybugDB `==0.20.3` (pinned — newer 0.20.x segfaults index builds): graph + vector + FTS in one file |
@@ -76,24 +76,25 @@ a swappable `DocumentConverter` seam. What isn't needed isn't installed.
 Requires Python ≥ 3.11.
 
 ```bash
-pip install "okfgraph[pdf,omni]"   # PyPI (okf-embed ships platform wheels; published)
+pip install "okfgraph[pdf,omni]"   # PyPI (embeddings come from the published `embroider` wheels)
 ```
 
-Or from source with `uv` (also builds the `okf-embed` Rust wheel from
-`rust/okf-embed` via `[tool.uv.sources]`):
+Or from source with `uv` (no Rust toolchain needed — the embedding
+engine is the external `embroider` package):
 
 ```bash
 git clone <repo> && cd OKFgraph
-uv sync                 # core: ladybug, okf-embed, onnxruntime, mordant, mcp, …
+uv sync                 # core: ladybug, embroider, onnxruntime, mordant, mcp, …
 uv sync --extra pdf     # bobine PDF converter
 uv sync --extra omni    # sentence-transformers + Pillow (image embeddings)
 uv sync --extra dev     # pytest
 ```
 
-Core dependencies are deliberately few: `ladybug==0.20.3`, `okf-embed`,
-`onnxruntime==1.29.0` (one pinned ORT binary shared by bobine + okf-embed;
-`ORT_DYLIB_PATH`-overridable), `mordant`, `mcp>=2.0`, `pydantic`, `pyyaml`,
-`numpy`, `python-frontmatter`, `fasteners`. There is no torch, no
+Core dependencies are deliberately few: `ladybug==0.20.3`, `embroider>=0.1,<0.2`
+(the shared embedding engine — github.com/opticsWolf/embroider, also used by
+bobine), `onnxruntime==1.29.0` (one pinned ORT binary shared by bobine +
+embroider; `ORT_DYLIB_PATH`-overridable), `mordant`, `mcp>=2.0`, `pydantic`,
+`pyyaml`, `numpy`, `python-frontmatter`, `fasteners`. There is no torch, no
 transformers, no optimum, no PDF stack in the core install.
 
 ---
@@ -242,7 +243,7 @@ Delta ──► Schema ──► ImageAssets ──► Purge ──► Ingest
    │                                                    (bobine seam)
    └──────────────── LadybugDB (graph + vector + FTS, one file) ──┘
                          ▲
-              Rust okf-embed (Jina v5, ORT) — tokenize, last-token
+              Rust embroider (Jina v5, ORT) — tokenize, last-token
               pool, L2-norm, Matryoshka truncate; numerics pinned
               by tests/test_parity.py
 ```
@@ -259,10 +260,14 @@ Key design decisions:
 
 - **Rust-only embeddings, fail-fast** — no Python fallback; a mid-run stack
   switch would silently mix vector spaces in one index.
+- **Lazy session init** — router construction never downloads the model or
+  builds the ONNX session; first encode opens once (thread-safe), token
+  counting uses a tokenizer-only handle, so PPR search, budgeted reads,
+  diff, and doctor stay cold.
 - **Last-token pooling** (not mean) — required by Jina v5; mean pooling
   breaks alignment with omni image embeddings.
 - **Single pinned ORT** (`onnxruntime==1.29.0`, `ORT_DYLIB_PATH`-overridable)
-  shared by bobine + okf-embed.
+  shared by bobine + embroider.
 - **Bobine is a plugin, not a dependency** — `DocumentConverter.convert()`
   is the seam; provider owns its options (`routing_mode`,
   `extract_images`); missing bobine → clear `RuntimeError`, never a silent
@@ -300,7 +305,8 @@ Key design decisions:
 ```bash
 uv run --project . pytest tests/ -q        # full suite (model loads; takes a while)
 uv run --project . pytest tests/test_ranking.py tests/test_mcp_server.py -q   # fast subset
-cd rust/okf-embed && cargo test --locked   # Rust unit tests (pure, no model)
+# Rust unit tests live in the embroider repo:
+# https://github.com/opticsWolf/embroider (cargo test --locked)
 ```
 
 Golden fixtures under `tests/fixtures/` (`ppr_graph`, `diff_a`/`diff_b`,
@@ -327,7 +333,6 @@ okfgraph/
 │   ├── tools.py           # legacy tool definitions (superseded by mcp_server)
 │   └── components/        # ranking, links, search, lint, import_, export, diff, doctor,
 │                          # embedding, converters, image_assets, delta, purge, schema, ingest
-├── rust/okf-embed/        # Jina v5 Rust loader (ort, CUDA-opportunistic) + Python wheel
 ├── skills/                # okfgraph-mcp, okfgraph-cli, okfgraph-ingest (harness-neutral source)
 ├── tests/fixtures/        # conformance corpus: ppr, diff, doctor, obsidian, bundles
 ├── docs/                  # converters, harness-integration, plan-retrieval-roundup, diagnostics…
@@ -340,8 +345,9 @@ okfgraph/
 
 ## Requirements
 
-Core (`uv sync`): `ladybug==0.20.3`, `okf-embed` (built from `rust/okf-embed`),
-`onnxruntime==1.29.0`, `mordant>=0.9`, `mcp>=2.0`, `pydantic>=2`, `pyyaml>=6`,
+Core (`uv sync`): `ladybug==0.20.3`, `embroider>=0.1,<0.2` (PyPI wheels,
+github.com/opticsWolf/embroider), `onnxruntime==1.29.0`, `mordant>=0.9`,
+`mcp>=2.0`, `pydantic>=2`, `pyyaml>=6`,
 `numpy>=1.26`, `python-frontmatter>=1`, `fasteners>=0.19`. Python ≥ 3.11.
 
 - `--extra pdf`: `bobine>=0.5` (default PDF converter).

{okfgraph-0.2.7 → okfgraph-0.2.12}/README.md

@@ -17,7 +17,7 @@ model loaded**, structural diffing, scored health checks, and Obsidian-vault
 compatible wikilinks — in a single LadybugDB file.
 
 Design stance: **slim dependencies, no legacy fallbacks.** Embeddings run
-through the `okf-embed` Rust wheel (ONNX Runtime, no torch / transformers /
+through the `embroider` Rust wheel (ONNX Runtime, no torch / transformers /
 optimum anywhere). PDF conversion runs through the `bobine` Rust engine behind
 a swappable `DocumentConverter` seam. What isn't needed isn't installed.
 
@@ -27,7 +27,7 @@ a swappable `DocumentConverter` seam. What isn't needed isn't installed.
 
 | Category | Features |
 |---|---|
-| **Embeddings** | Jina v5 (`jina-embeddings-v5-text-small-retrieval`) via the `okf-embed` Rust wheel; last-token pooling, Matryoshka truncation (32–1024, default 512); omni model (`…-omni-small-retrieval`) lazy-loaded for images only |
+| **Embeddings** | Jina v5 (`jina-embeddings-v5-text-small-retrieval`) via the `embroider` Rust wheel; last-token pooling, Matryoshka truncation (32–1024, default 512); omni model (`…-omni-small-retrieval`) lazy-loaded for images only |
 | **Search** | Hybrid RRF fusion (vector + FTS) at concept and chunk granularity; `rank=none\|hub\|ppr` — including **PPR**: lexical seeds → exact Personalized PageRank, zero model load, deterministic |
 | **Read** | Body / chunks / rebuilt document / graph context, with optional **token budgets** (`max_tokens`): self first, then PPR-ranked neighbours, index-first for context |
 | **Storage** | LadybugDB `==0.20.3` (pinned — newer 0.20.x segfaults index builds): graph + vector + FTS in one file |
@@ -49,24 +49,25 @@ a swappable `DocumentConverter` seam. What isn't needed isn't installed.
 Requires Python ≥ 3.11.
 
 ```bash
-pip install "okfgraph[pdf,omni]"   # PyPI (okf-embed ships platform wheels; published)
+pip install "okfgraph[pdf,omni]"   # PyPI (embeddings come from the published `embroider` wheels)
 ```
 
-Or from source with `uv` (also builds the `okf-embed` Rust wheel from
-`rust/okf-embed` via `[tool.uv.sources]`):
+Or from source with `uv` (no Rust toolchain needed — the embedding
+engine is the external `embroider` package):
 
 ```bash
 git clone <repo> && cd OKFgraph
-uv sync                 # core: ladybug, okf-embed, onnxruntime, mordant, mcp, …
+uv sync                 # core: ladybug, embroider, onnxruntime, mordant, mcp, …
 uv sync --extra pdf     # bobine PDF converter
 uv sync --extra omni    # sentence-transformers + Pillow (image embeddings)
 uv sync --extra dev     # pytest
 ```
 
-Core dependencies are deliberately few: `ladybug==0.20.3`, `okf-embed`,
-`onnxruntime==1.29.0` (one pinned ORT binary shared by bobine + okf-embed;
-`ORT_DYLIB_PATH`-overridable), `mordant`, `mcp>=2.0`, `pydantic`, `pyyaml`,
-`numpy`, `python-frontmatter`, `fasteners`. There is no torch, no
+Core dependencies are deliberately few: `ladybug==0.20.3`, `embroider>=0.1,<0.2`
+(the shared embedding engine — github.com/opticsWolf/embroider, also used by
+bobine), `onnxruntime==1.29.0` (one pinned ORT binary shared by bobine +
+embroider; `ORT_DYLIB_PATH`-overridable), `mordant`, `mcp>=2.0`, `pydantic`,
+`pyyaml`, `numpy`, `python-frontmatter`, `fasteners`. There is no torch, no
 transformers, no optimum, no PDF stack in the core install.
 
 ---
@@ -215,7 +216,7 @@ Delta ──► Schema ──► ImageAssets ──► Purge ──► Ingest
    │                                                    (bobine seam)
    └──────────────── LadybugDB (graph + vector + FTS, one file) ──┘
                          ▲
-              Rust okf-embed (Jina v5, ORT) — tokenize, last-token
+              Rust embroider (Jina v5, ORT) — tokenize, last-token
               pool, L2-norm, Matryoshka truncate; numerics pinned
               by tests/test_parity.py
 ```
@@ -232,10 +233,14 @@ Key design decisions:
 
 - **Rust-only embeddings, fail-fast** — no Python fallback; a mid-run stack
   switch would silently mix vector spaces in one index.
+- **Lazy session init** — router construction never downloads the model or
+  builds the ONNX session; first encode opens once (thread-safe), token
+  counting uses a tokenizer-only handle, so PPR search, budgeted reads,
+  diff, and doctor stay cold.
 - **Last-token pooling** (not mean) — required by Jina v5; mean pooling
   breaks alignment with omni image embeddings.
 - **Single pinned ORT** (`onnxruntime==1.29.0`, `ORT_DYLIB_PATH`-overridable)
-  shared by bobine + okf-embed.
+  shared by bobine + embroider.
 - **Bobine is a plugin, not a dependency** — `DocumentConverter.convert()`
   is the seam; provider owns its options (`routing_mode`,
   `extract_images`); missing bobine → clear `RuntimeError`, never a silent
@@ -273,7 +278,8 @@ Key design decisions:
 ```bash
 uv run --project . pytest tests/ -q        # full suite (model loads; takes a while)
 uv run --project . pytest tests/test_ranking.py tests/test_mcp_server.py -q   # fast subset
-cd rust/okf-embed && cargo test --locked   # Rust unit tests (pure, no model)
+# Rust unit tests live in the embroider repo:
+# https://github.com/opticsWolf/embroider (cargo test --locked)
 ```
 
 Golden fixtures under `tests/fixtures/` (`ppr_graph`, `diff_a`/`diff_b`,
@@ -300,7 +306,6 @@ okfgraph/
 │   ├── tools.py           # legacy tool definitions (superseded by mcp_server)
 │   └── components/        # ranking, links, search, lint, import_, export, diff, doctor,
 │                          # embedding, converters, image_assets, delta, purge, schema, ingest
-├── rust/okf-embed/        # Jina v5 Rust loader (ort, CUDA-opportunistic) + Python wheel
 ├── skills/                # okfgraph-mcp, okfgraph-cli, okfgraph-ingest (harness-neutral source)
 ├── tests/fixtures/        # conformance corpus: ppr, diff, doctor, obsidian, bundles
 ├── docs/                  # converters, harness-integration, plan-retrieval-roundup, diagnostics…
@@ -313,8 +318,9 @@ okfgraph/
 
 ## Requirements
 
-Core (`uv sync`): `ladybug==0.20.3`, `okf-embed` (built from `rust/okf-embed`),
-`onnxruntime==1.29.0`, `mordant>=0.9`, `mcp>=2.0`, `pydantic>=2`, `pyyaml>=6`,
+Core (`uv sync`): `ladybug==0.20.3`, `embroider>=0.1,<0.2` (PyPI wheels,
+github.com/opticsWolf/embroider), `onnxruntime==1.29.0`, `mordant>=0.9`,
+`mcp>=2.0`, `pydantic>=2`, `pyyaml>=6`,
 `numpy>=1.26`, `python-frontmatter>=1`, `fasteners>=0.19`. Python ≥ 3.11.
 
 - `--extra pdf`: `bobine>=0.5` (default PDF converter).

{okfgraph-0.2.7 → okfgraph-0.2.12}/okfgraph/components/__init__.py

@@ -13,7 +13,7 @@ stubs (``...``) until their respective phase moves the implementation over.
 from okfgraph.components.schema import SchemaManager
 from okfgraph.components.delta import DeltaDetector
 from okfgraph.components.purge import PurgeManager
-from okfgraph.components.embedding import EmbeddingEngine
+from okfgraph.components.embedding import EmbeddingEngine, LazyRustEncoder
 from okfgraph.components.image_assets import ImageAssetManager
 from okfgraph.components.search import SearchEngine
 from okfgraph.components.import_ import ImportManager, parse_source_file
@@ -37,6 +37,7 @@ __all__ = [
     "DeltaDetector",
     "PurgeManager",
     "EmbeddingEngine",
+    "LazyRustEncoder",
     "ImageAssetManager",
     "SearchEngine",
     "ImportManager",

{okfgraph-0.2.7 → okfgraph-0.2.12}/okfgraph/components/embedding.py

@@ -6,44 +6,262 @@ here. Public callers reach these via router.<method> (component bridge).
 """
 import logging
 import math
+import threading
 from pathlib import Path
 
 import mordant
 from typing import Any, Dict, List, Optional
 logger = logging.getLogger(__name__)
 
-def resolve_ort_dylib() -> Optional[str]:
-    """Point ``ORT_DYLIB_PATH`` at the pip-installed ORT build when unset.
+_ORT_MODULE_NAMES = ("onnxruntime", "onnxruntime-gpu")
 
-    Both bobine and okf-embed load ONNX Runtime dynamically; sharing one
+
+def _candidate_ort_library_names(os_name=None, sys_platform=None):
+    """Return the ORT library filenames for an OS/platform pair.
+
+    Takes explicit arguments so unit tests can cover Windows/macOS/Linux
+    from any host. Linux uses a versioned ``libonnxruntime.so.*`` glob
+    (handled by :func:`_find_runtime_in_package`); this helper returns the
+    unversioned fallback name for that platform.
+    """
+    import os
+    import sys
+    if os_name is None:
+        os_name = os.name
+    if sys_platform is None:
+        sys_platform = sys.platform
+    if os_name == "nt":
+        return ("onnxruntime.dll",)
+    if sys_platform == "darwin":
+        return ("libonnxruntime.dylib",)
+    return ("libonnxruntime.so",)
+
+
+def _find_runtime_in_package(package_dir, os_name=None, sys_platform=None):
+    """Find an ORT shared library inside a pip-installed package directory.
+
+    Returns a :class:`Path` or ``None``. Prefers versioned Linux libraries
+    (``libonnxruntime.so.*``) over the unversioned ``libonnxruntime.so``.
+    """
+    import os
+    import sys
+    if os_name is None:
+        os_name = os.name
+    if sys_platform is None:
+        sys_platform = sys.platform
+    capi_dir = Path(package_dir) / "capi"
+    if not capi_dir.is_dir():
+        return None
+    if os_name == "nt" or sys_platform == "darwin":
+        candidate = capi_dir / _candidate_ort_library_names(os_name, sys_platform)[0]
+        return candidate if candidate.is_file() else None
+    versioned = sorted(capi_dir.glob("libonnxruntime.so.*"))
+    if versioned:
+        return versioned[-1]
+    candidate = capi_dir / "libonnxruntime.so"
+    return candidate if candidate.is_file() else None
+
+
+def _configure_windows_ort_dll_directory(runtime_path) -> bool:
+    """Add the ORT ``capi`` directory to Windows DLL resolution.
+
+    Best-effort only: returns ``False`` (never raises) when unavailable.
+    """
+    import os
+    if os.name != "nt":
+        return False
+    add_dll_directory = getattr(os, "add_dll_directory", None)
+    if not callable(add_dll_directory):
+        return False
+    try:
+        add_dll_directory(str(Path(runtime_path).parent))
+        return True
+    except OSError as exc:
+        logger.debug("ORT DLL directory configuration failed: %s", exc)
+        return False
+
+
+def _warm_ort_gpu_dlls(module) -> bool:
+    """Preload NVIDIA DLLs when the installed ORT package exposes CUDA.
+
+    This mirrors bobine's GPU bootstrap: only attempt the preload when the
+    package reports a CUDA execution provider, and never let it fail
+    runtime discovery.
+    """
+    preload = getattr(module, "preload_dlls", None)
+    if not callable(preload):
+        return False
+    try:
+        providers = list(module.get_available_providers())
+    except Exception as exc:
+        logger.debug("ORT provider query failed: %s", exc)
+        return False
+    if "CUDAExecutionProvider" not in providers:
+        return False
+    try:
+        preload()
+        return True
+    except Exception as exc:
+        logger.debug("ORT GPU DLL preload failed: %s", exc)
+        return False
+
+
+def resolve_ort_dylib(*, warm_gpu: bool = True, os_name=None, sys_platform=None) -> Optional[str]:
+    """Point ``ORT_DYLIB_PATH`` at a pip-installed ORT build when unset.
+
+    Both bobine and embroider load ONNX Runtime dynamically; sharing one
     binary avoids version/CUDA drift between the two runtimes. Explicit
     user configuration always wins — this only fills the gap.
+
+    Resolution order:
+
+    1. Existing ``ORT_DYLIB_PATH``.
+    2. Pip-installed ``onnxruntime`` or ``onnxruntime-gpu`` package.
+    3. OS loader path (represented by returning ``None``).
+
+    Missing runtimes never raise here; session creation or encoding is the
+    fail-fast boundary. ``os_name``/``sys_platform`` are explicit so unit
+    tests can cover every platform from any host (patching ``os.name``
+    would break ``pathlib`` dispatch on Windows).
     """
     import os
-    if os.environ.get("ORT_DYLIB_PATH"):
-        return os.environ["ORT_DYLIB_PATH"]
-    try:
-        import onnxruntime
-        dll = Path(str(onnxruntime.__file__)).parent / "capi" / "onnxruntime.dll"
-        if dll.exists():
-            os.environ["ORT_DYLIB_PATH"] = str(dll)
-            return str(dll)
-    except ImportError:
-        pass
+    explicit = os.environ.get("ORT_DYLIB_PATH")
+    if explicit:
+        return explicit
+    for module_name in _ORT_MODULE_NAMES:
+        try:
+            module = __import__(module_name)
+        except ImportError:
+            continue
+        try:
+            package_dir = Path(str(module.__file__)).parent
+        except Exception:
+            continue
+        found = _find_runtime_in_package(package_dir, os_name, sys_platform)
+        if found is None:
+            continue
+        os.environ["ORT_DYLIB_PATH"] = str(found)
+        _configure_windows_ort_dll_directory(found)
+        if warm_gpu:
+            _warm_ort_gpu_dlls(module)
+        logger.debug("resolved ORT runtime: %s", found)
+        return str(found)
     return None
 
 
+class LazyRustEncoder:
+    """Defers the ONNX session open until the first real encode.
+
+    Router construction stays cheap: the ``embroider`` wheel import is still
+    validated eagerly (fail fast on a missing install), but ``JinaV5.open``
+    — model download + session build — waits for the first ``encode`` /
+    ``encode_batch`` / ``used_cuda`` access. Token counting uses the
+    separate lightweight ``JinaTokenizer`` handle, so budgeted reads and the
+    context-window guard stay cold too.
+
+    A failed session open is cached and re-raised: configuration errors stay
+    fail-fast (once, at first encode) instead of retrying network/model
+    acquisition on every call. Thread-safe: concurrent first encodes open
+    exactly one session.
+    """
+
+    def __init__(self, *, model_id, truncate_dim, device,
+                 session_factory, tokenizer_factory, on_open=None):
+        self._model_id = model_id
+        self._truncate_dim = truncate_dim
+        self._device = device
+        self._session_factory = session_factory
+        self._tokenizer_factory = tokenizer_factory
+        self._on_open = on_open
+        self._lock = threading.Lock()
+        self._encoder = None
+        self._encoder_error = None
+        self._open_reported = False
+        self._tokenizer = None
+
+    @property
+    def is_loaded(self) -> bool:
+        """True once the ONNX session has been opened."""
+        return self._encoder is not None
+
+    @property
+    def model_id(self) -> str:
+        return self._model_id
+
+    @property
+    def dim(self) -> int:
+        return self._truncate_dim
+
+    @property
+    def used_cuda(self) -> bool:
+        """Effective device — opens the session on first access."""
+        return bool(self._get_encoder().used_cuda)
+
+    def encode(self, text: str, task: str = "Document"):
+        return self._get_encoder().encode(text, task=task)
+
+    def encode_batch(self, texts, task: str = "Document"):
+        return self._get_encoder().encode_batch(texts, task=task)
+
+    def count_tokens(self, text: str) -> int:
+        """Exact count via the tokenizer-only handle (never opens the session)."""
+        return int(self._get_tokenizer().count_tokens(text))
+
+    def _get_encoder(self):
+        encoder = self._encoder
+        if encoder is not None:
+            return encoder
+        with self._lock:
+            if self._encoder is not None:
+                return self._encoder
+            if self._encoder_error is not None:
+                raise self._encoder_error
+            try:
+                encoder = self._session_factory()
+            except Exception as exc:
+                self._encoder_error = exc
+                raise
+            self._encoder = encoder
+            if self._on_open is not None and not self._open_reported:
+                self._open_reported = True
+                self._on_open(encoder)
+            return encoder
+
+    def _get_tokenizer(self):
+        tokenizer = self._tokenizer
+        if tokenizer is not None:
+            return tokenizer
+        with self._lock:
+            if self._tokenizer is not None:
+                return self._tokenizer
+            try:
+                tokenizer = self._tokenizer_factory()
+            except Exception as exc:
+                logger.debug("tokenizer-only open failed: %s", exc)
+                raise
+            self._tokenizer = tokenizer
+            return tokenizer
+
+    def __repr__(self) -> str:
+        state = "loaded" if self._encoder is not None else "cold"
+        return (
+            f"LazyRustEncoder({self._model_id}, "
+            f"dim={self._truncate_dim}, {state})"
+        )
+
+
 class EmbeddingEngine:
     """Owns the embedding model and chunking logic.
 
-    Text embeddings come from the Rust okf_embed wheel (Jina v5 via ORT):
+    Text embeddings come from the Rust embroider wheel (Jina v5 via ORT):
     prefixed, last-token pooled, truncated. There is no Python fallback —
     a mid-run stack switch would silently mix vector spaces in one index.
     """
 
     def __init__(self, rust_encoder, embedding_dim, device,
                  cache_dir, model_id, omni_model_id, omni,
-                 chunk_size, chunk_overlap, enable_chunking, conn):
+                 chunk_size, chunk_overlap, enable_chunking, conn,
+                 ort_dylib=None):
         self.encoder = rust_encoder
         self.embedding_dim = embedding_dim
         self.device = device
@@ -55,6 +273,7 @@ class EmbeddingEngine:
         self.chunk_overlap = chunk_overlap
         self.enable_chunking = enable_chunking
         self.conn = conn
+        self.ort_dylib = ort_dylib
 
     def _encode(self, text: str, task: str = "Document") -> List[float]:
         """Encode text with the Rust Jina v5 encoder.