okfgraph 0.2.7__tar.gz → 0.2.11__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: okfgraph
-Version: 0.2.7
+Version: 0.2.11
 Summary: Ladybug-backed OKF knowledge graph with ONNX + Jina v5 embeddings
 License-Expression: Apache-2.0 OR MIT
 Requires-Python: >=3.11
@@ -259,6 +259,10 @@ 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)

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

@@ -232,6 +232,10 @@ 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)

{okfgraph-0.2.7 → okfgraph-0.2.11}/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.11}/okfgraph/components/embedding.py

@@ -6,33 +6,250 @@ 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")
+
+
+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 okf-embed 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 ``okf-embed`` 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.
 
@@ -43,7 +260,8 @@ class EmbeddingEngine:
 
     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.

{okfgraph-0.2.7 → okfgraph-0.2.11}/okfgraph/router.py

@@ -106,6 +106,8 @@ class OKFRouter:
         omni_model_id: str = "jinaai/jina-embeddings-v5-omni-small-retrieval",
         embedding_dim: int = 512,
         cache_dir: Optional[str] = None,
+        model_path: Optional[str] = None,
+        tokenizer_path: Optional[str] = None,
         device: str = "cpu",
         allow_remote_images: bool = False,
         allowed_image_domains: Optional[List[str]] = None,
@@ -124,6 +126,10 @@ class OKFRouter:
             omni_model_id: HuggingFace ID of the Jina v5 omni model (images).
             embedding_dim: Truncated Matryoshka dimension (<= 1024).
             cache_dir: Model cache directory (defaults per-platform).
+            model_path: Explicit local ONNX file (with `tokenizer_path`);
+                skips every download — air-gapped / reproducible installs.
+                An external-data sidecar must sit next to this file.
+            tokenizer_path: Explicit local `tokenizer.json` (with `model_path`).
             device: "cpu" (CUDA is opportunistic inside the Rust loader).
             allow_remote_images: Whether http(s) image URLs may be fetched.
             allowed_image_domains: Domain allowlist for remote images.
@@ -186,7 +192,10 @@ class OKFRouter:
         # Text embeddings: Rust okf_embed wheel (Jina v5 via ORT). No Python
         # fallback — a mid-run stack switch would silently mix vector spaces
         # in one index.
-        from okfgraph.components.embedding import resolve_ort_dylib
+        from okfgraph.components.embedding import LazyRustEncoder, resolve_ort_dylib
+        # Resolve first: the native module loads ORT dynamically, so the
+        # shared runtime choice must be fixed before importing it.
+        self.ort_dylib = resolve_ort_dylib()
         try:
             import okf_embed
         except ImportError:
@@ -194,24 +203,77 @@ class OKFRouter:
                 "the okf-embed wheel is required for text embeddings: "
                 "build rust/okf-embed (maturin build --release) and install it"
             ) from None
-        resolve_ort_dylib()
         # The Rust crate knows auto/cpu/cuda; map torch-style aliases.
+        # Validate eagerly so a bad device still fails at construction —
+        # the session itself opens lazily on first encode (see below).
         rust_device = {"mps": "auto"}.get(device, device)
-        self.encoder = okf_embed.JinaV5.open(
-            model_id,
+        if rust_device not in ("auto", "cpu", "cuda"):
+            raise ValueError(
+                f"device must be 'auto', 'cpu' or 'cuda', got '{device}'"
+            )
+        if (model_path is None) != (tokenizer_path is None):
+            raise ValueError(
+                "model_path and tokenizer_path must be given together "
+                "(explicit local files skip all downloads)"
+            )
+        explicit_files = model_path is not None
+        if explicit_files:
+            for label, path in (
+                ("model_path", model_path),
+                ("tokenizer_path", tokenizer_path),
+            ):
+                if not Path(path).is_file():
+                    raise FileNotFoundError(
+                        f"{label} not found: {path} "
+                        "(explicit paths skip all downloads)"
+                    )
+            logger.debug("using explicit model files: %s", model_path)
+
+        def _report_encoder_open(encoder) -> None:
+            logger.info(
+                "text embeddings: %s dim=%d cuda=%s",
+                model_id, embedding_dim, encoder.used_cuda,
+            )
+            if device == "cuda" and not encoder.used_cuda:
+                logger.warning(
+                    "CUDA requested but the loaded ONNX Runtime has no CUDA execution "
+                    "provider — running on CPU. Install onnxruntime-gpu for acceleration."
+                )
+
+        # Text embeddings: Rust okf_embed wheel (Jina v5 via ORT). No Python
+        # fallback — a mid-run stack switch would silently mix vector spaces
+        # in one index. The wheel import above stays fail-fast; the session
+        # open is lazy so model-free commands (PPR search, budgeted reads,
+        # diff, doctor) never pay model-download/session-build costs.
+        if explicit_files:
+            session_factory = lambda: okf_embed.JinaV5.open_files(
+                str(model_path),
+                str(tokenizer_path),
+                truncate_dim=embedding_dim,
+                device=rust_device,
+            )
+            tokenizer_factory = lambda: okf_embed.JinaTokenizer.open_files(
+                str(tokenizer_path),
+            )
+        else:
+            session_factory = lambda: okf_embed.JinaV5.open(
+                model_id,
+                truncate_dim=embedding_dim,
+                device=rust_device,
+                cache_dir=cache_dir,
+            )
+            tokenizer_factory = lambda: okf_embed.JinaTokenizer.open(
+                model_id,
+                cache_dir=cache_dir,
+            )
+        self.encoder = LazyRustEncoder(
+            model_id=model_id,
             truncate_dim=embedding_dim,
             device=rust_device,
-            cache_dir=cache_dir,
+            session_factory=session_factory,
+            tokenizer_factory=tokenizer_factory,
+            on_open=_report_encoder_open,
         )
-        logger.info(
-            "text embeddings: %s dim=%d cuda=%s",
-            model_id, embedding_dim, self.encoder.used_cuda,
-        )
-        if device == "cuda" and not self.encoder.used_cuda:
-            logger.warning(
-                "CUDA requested but the loaded ONNX Runtime has no CUDA execution "
-                "provider — running on CPU. Install onnxruntime-gpu for acceleration."
-            )
 
         # ── Component wiring (Phase 1-3 refactor) ───────────────────
         # The facade owns the resources (conn, encoder, lock) and injects
@@ -232,7 +294,7 @@ class OKFRouter:
             self.encoder, self.embedding_dim,
             self.device, self.cache_dir, self.model_id, self.omni_model_id,
             self._omni, self.chunk_size, self.chunk_overlap, self.enable_chunking,
-            self.conn,
+            self.conn, self.ort_dylib,
         )
         self.image_mgr = ImageAssetManager(
             self.conn, self.embed_engine, self.schema_mgr,

{okfgraph-0.2.7 → okfgraph-0.2.11}/okfgraph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: okfgraph
-Version: 0.2.7
+Version: 0.2.11
 Summary: Ladybug-backed OKF knowledge graph with ONNX + Jina v5 embeddings
 License-Expression: Apache-2.0 OR MIT
 Requires-Python: >=3.11
@@ -259,6 +259,10 @@ 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)

{okfgraph-0.2.7 → okfgraph-0.2.11}/okfgraph.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ tests/test_delta.py
 tests/test_diff.py
 tests/test_directory_hash.py
 tests/test_doctor.py
+tests/test_explicit_files.py
 tests/test_export_compliance.py
 tests/test_gpu_integration.py
 tests/test_graph_enrichment.py
@@ -48,12 +49,14 @@ tests/test_images.py
 tests/test_ingest.py
 tests/test_ingest_tool.py
 tests/test_integration.py
+tests/test_lazy_encoder.py
 tests/test_lint.py
 tests/test_logging.py
 tests/test_mcp_server.py
 tests/test_models.py
 tests/test_obsidian.py
 tests/test_okf_ingest_tool.py
+tests/test_ort.py
 tests/test_packaging.py
 tests/test_parity.py
 tests/test_pdf_e2e.py

{okfgraph-0.2.7 → okfgraph-0.2.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "okfgraph"
-version = "0.2.7"
+version = "0.2.11"
 description = "Ladybug-backed OKF knowledge graph with ONNX + Jina v5 embeddings"
 readme = "README.md"
 requires-python = ">=3.11"

okfgraph-0.2.11/tests/test_explicit_files.py

@@ -0,0 +1,147 @@
+"""Explicit local model-file tests — no downloads, no ORT session.
+
+Validation (pairing, existence) fires at router construction. Routing to
+`open_files` vs `open` is proven with a stubbed `okf_embed` module; numeric
+equivalence of the two acquisition paths is pinned in test_rust_backend.py.
+"""
+
+import sys
+import types
+
+import pytest
+
+from okfgraph.router import OKFRouter
+
+
+def _stub_embed(monkeypatch, calls):
+    class _Session:
+        def __init__(self, via):
+            self.via = via
+            self.used_cuda = False
+
+        def encode(self, text, task="Document"):
+            calls["encode"] += 1
+            return [float(len(text))]
+
+        def encode_batch(self, texts, task="Document"):
+            return [self.encode(t, task=task) for t in texts]
+
+    class _Tokenizer:
+        def __init__(self, via):
+            self.via = via
+
+        def count_tokens(self, text):
+            return len(text.split())
+
+    stub = types.SimpleNamespace(
+        JinaV5=types.SimpleNamespace(
+            open=lambda *a, **k: (_ for _ in ()).throw(
+                AssertionError(f"unexpected open: {a} {k}")
+            ),
+            open_files=lambda onnx, tok, **k: (
+                calls["open_files"].append((onnx, tok, k)),
+                _Session("files"),
+            )[1],
+        ),
+        JinaTokenizer=types.SimpleNamespace(
+            open=lambda *a, **k: (_ for _ in ()).throw(
+                AssertionError(f"unexpected tokenizer open: {a} {k}")
+            ),
+            open_files=lambda tok: (
+                calls["tok_files"].append(tok),
+                _Tokenizer("files"),
+            )[1],
+        ),
+        MAX_LENGTH=8192,
+    )
+    monkeypatch.setitem(sys.modules, "okf_embed", stub)
+    return stub
+
+
+def _router(tmp_path, **kwargs):
+    return OKFRouter(
+        db_path=str(tmp_path / "explicit.db"),
+        bundle_root=str(tmp_path),
+        device="cpu",
+        **kwargs,
+    )
+
+
+def test_paths_must_be_given_together(tmp_path):
+    with pytest.raises(ValueError, match="must be given together"):
+        _router(tmp_path, model_path="model.onnx")
+    with pytest.raises(ValueError, match="must be given together"):
+        _router(tmp_path, tokenizer_path="tokenizer.json")
+
+
+def test_missing_files_fail_fast(tmp_path):
+    with pytest.raises(FileNotFoundError, match="model_path not found"):
+        _router(
+            tmp_path,
+            model_path=str(tmp_path / "nope.onnx"),
+            tokenizer_path=str(tmp_path / "tok.json"),
+        )
+
+
+def test_encode_routes_to_open_files(tmp_path, monkeypatch):
+    calls = {"open_files": [], "tok_files": [], "encode": 0}
+    _stub_embed(monkeypatch, calls)
+    onnx = tmp_path / "model.onnx"
+    tok = tmp_path / "tokenizer.json"
+    onnx.write_bytes(b"fake")
+    tok.write_text("{}", encoding="utf-8")
+
+    router = _router(tmp_path, model_path=str(onnx), tokenizer_path=str(tok))
+    try:
+        assert router.encoder.is_loaded is False
+        assert router.embed_engine._encode("hi") == [2.0]
+        assert router.embed_engine.count_tokens("one two") == 2
+    finally:
+        router.close()
+
+    assert calls["open_files"] == [
+        (str(onnx), str(tok), {"truncate_dim": 512, "device": "cpu"})
+    ]
+    assert calls["tok_files"] == [str(tok)]
+    assert calls["encode"] == 1
+
+
+def test_default_path_still_uses_open(tmp_path, monkeypatch):
+    import okf_embed as real_embed
+
+    opened = {}
+
+    class _Session:
+        used_cuda = False
+
+        def encode(self, text, task="Document"):
+            return [1.0]
+
+        def encode_batch(self, texts, task="Document"):
+            return [[1.0] for _ in texts]
+
+    stub = types.SimpleNamespace(
+        JinaV5=types.SimpleNamespace(
+            open=lambda *a, **k: (opened.setdefault("open", (a, k)), _Session())[1],
+            open_files=lambda *a, **k: (_ for _ in ()).throw(
+                AssertionError("open_files must not be used by default")
+            ),
+        ),
+        JinaTokenizer=types.SimpleNamespace(
+            open=lambda *a, **k: types.SimpleNamespace(
+                count_tokens=lambda t: 1
+            ),
+            open_files=lambda *a, **k: (_ for _ in ()).throw(
+                AssertionError("tokenizer open_files must not be used by default")
+            ),
+        ),
+        MAX_LENGTH=real_embed.MAX_LENGTH,
+    )
+    monkeypatch.setitem(sys.modules, "okf_embed", stub)
+
+    router = _router(tmp_path)
+    try:
+        assert router.embed_engine._encode("hi") == [1.0]
+    finally:
+        router.close()
+    assert opened["open"][1]["device"] == "cpu"

{okfgraph-0.2.7 → okfgraph-0.2.11}/tests/test_gpu_integration.py

@@ -165,13 +165,17 @@ class TestGPUInitialization:
 
     @pytest.mark.skipif(_has_onnxruntime_gpu(), reason="onnxruntime-gpu is installed")
     def test_no_gpu_runtime_warns_on_cuda_request(self, tmp_dir, capsys):
-        """When the loaded ORT has no CUDA EP and device='cuda', warn on stderr."""
+        """When the loaded ORT has no CUDA EP and device='cuda', the first
+        encode warns on stderr and falls back to CPU (the session now opens
+        lazily, so construction alone stays silent)."""
         r = OKFRouter(
             db_path=str(Path(tmp_dir) / "test_no_gpu.db"),
             bundle_root=tmp_dir,
             embedding_dim=512,
             device="cuda",
         )
+        assert r.encoder.is_loaded is False
+        _ = r.embed_engine._encode("warmup", task="Document")
         assert r.encoder.used_cuda is False
         assert "CUDA" in capsys.readouterr().err
         r.close()