|
| 1 | +"""Best-effort background fetches for the embedding subsystem (issue #169). |
| 2 | +
|
| 3 | +Non-blocking helpers the model lifecycle uses when it engages the download-free |
| 4 | +fallback: kick off the package install (PACKAGE_ABSENT) or the model-weight |
| 5 | +download (MODEL_FILES_ABSENT) in a detached subprocess so the current session |
| 6 | +serves fallback embeddings immediately and the neural model becomes available |
| 7 | +for the NEXT session — the "no first-run cliff" behaviour of #169. |
| 8 | +
|
| 9 | +Both helpers honour ``CORTEX_EMBEDDING_ZERO_DOWNLOAD``: when set, no network |
| 10 | +fetch is started at all (sandboxed / offline / test use). All failures are |
| 11 | +swallowed — a background fetch that cannot start must never affect the caller. |
| 12 | +
|
| 13 | +Pure I/O (subprocess). Infrastructure layer. |
| 14 | +""" |
| 15 | + |
| 16 | +from __future__ import annotations |
| 17 | + |
| 18 | +import logging |
| 19 | +import os |
| 20 | + |
| 21 | +logger = logging.getLogger(__name__) |
| 22 | + |
| 23 | + |
| 24 | +def zero_download_requested() -> bool: |
| 25 | + """Whether the operator opted out of any embedding network fetch (#169). |
| 26 | +
|
| 27 | + source: opt-in env contract — ``CORTEX_EMBEDDING_ZERO_DOWNLOAD`` in |
| 28 | + {``1``, ``true``} suppresses both the background package install and the |
| 29 | + background model download, forcing pure download-free operation. |
| 30 | + """ |
| 31 | + return os.environ.get("CORTEX_EMBEDDING_ZERO_DOWNLOAD", "").lower() in ("1", "true") |
| 32 | + |
| 33 | + |
| 34 | +def _spawn_detached(cmd: list[str], what: str) -> None: |
| 35 | + """Start ``cmd`` as a detached, output-suppressed subprocess; swallow errors.""" |
| 36 | + import subprocess |
| 37 | + |
| 38 | + try: |
| 39 | + subprocess.Popen( |
| 40 | + cmd, |
| 41 | + stdout=subprocess.DEVNULL, |
| 42 | + stderr=subprocess.DEVNULL, |
| 43 | + start_new_session=True, |
| 44 | + ) |
| 45 | + logger.info("Background %s started", what) |
| 46 | + except Exception as exc: |
| 47 | + logger.debug("Background %s failed to start: %s", what, exc) |
| 48 | + |
| 49 | + |
| 50 | +def trigger_background_install() -> None: |
| 51 | + """Install sentence-transformers in the background (PACKAGE_ABSENT). |
| 52 | +
|
| 53 | + Next session will have the package and a real model. No-op under |
| 54 | + ``CORTEX_EMBEDDING_ZERO_DOWNLOAD``. |
| 55 | + """ |
| 56 | + if zero_download_requested(): |
| 57 | + return |
| 58 | + import sys |
| 59 | + |
| 60 | + target = os.environ.get("CLAUDE_PLUGIN_DATA", "") |
| 61 | + if target: |
| 62 | + target = os.path.join(target, "deps") |
| 63 | + cmd = [ |
| 64 | + sys.executable, |
| 65 | + "-m", |
| 66 | + "pip", |
| 67 | + "install", |
| 68 | + "-q", |
| 69 | + "sentence-transformers>=2.2.0,<4.0.0", |
| 70 | + ] |
| 71 | + if target: |
| 72 | + cmd.extend(["--target", target]) |
| 73 | + _spawn_detached(cmd, "install of sentence-transformers") |
| 74 | + |
| 75 | + |
| 76 | +def trigger_background_model_download( |
| 77 | + model_name: str, revision: str | None, cache_folder: str | None |
| 78 | +) -> None: |
| 79 | + """Download the embedding model weights in the background (MODEL_FILES_ABSENT). |
| 80 | +
|
| 81 | + Populates the local HF cache so the NEXT session loads the neural model. |
| 82 | + No-op under ``CORTEX_EMBEDDING_ZERO_DOWNLOAD``. The child imports |
| 83 | + sentence-transformers itself; a failure (offline) is silently dropped — |
| 84 | + this session already serves fallback. |
| 85 | + """ |
| 86 | + if zero_download_requested(): |
| 87 | + return |
| 88 | + import sys |
| 89 | + |
| 90 | + # The child constructs the model once to force the download into the cache. |
| 91 | + prog = ( |
| 92 | + "import sys\n" |
| 93 | + "from sentence_transformers import SentenceTransformer\n" |
| 94 | + "name, rev, cf = sys.argv[1], sys.argv[2] or None, sys.argv[3] or None\n" |
| 95 | + "SentenceTransformer(name, revision=rev, cache_folder=cf)\n" |
| 96 | + ) |
| 97 | + cmd = [sys.executable, "-c", prog, model_name, revision or "", cache_folder or ""] |
| 98 | + _spawn_detached(cmd, f"download of embedding model {model_name}") |
0 commit comments