embeddings: a file-based feature check that a pod could never pass (v0.3.84)

`_is_bge_m3` keys off `sparse_linear.pt` -- the definitive signal for a
multi-vector embedder, since plain dense models do not ship one. It asked
`_resolve_repo_file`, which answers from the local disk and NEVER the
network. Right for "give me the path", wrong for "does this exist", and
the difference is invisible until the model has never been downloaded.

On a rented pod it has never been downloaded. The pod is disposable and
its cache starts empty, so the check ran before anything could satisfy
it: on every pod, every time, bge-m3 loaded through the DENSE
sentence-transformers path. The request for sparse was then refused with
a 400 telling the caller to serve the model on the coderai-embeddings
image -- which is the image it was already running on. Measured end to
end on a real A40: 379 seconds, then that.

`_repo_has_file` keeps the local answer first and, only when the file is
not on disk, asks the Hub for the repo's file LIST: metadata, no
download, cached once per process. Offline installs short-circuit on
HF_HUB_OFFLINE, a local directory is taken as the whole answer (asking
the Hub about a filesystem path would look up a stranger's model of the
same name), and any failure answers False exactly as before -- a metadata
lookup must never be able to fail a load.

Needs a coderai-embeddings rebuild: this code runs on the pod.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXRMe9ZPUQCCCtBai9uqt3

codai/__init__.py

@@ -16,7 +16,7 @@
 
 # Canonical product version for CoderAI — single source of truth. Both the API
 # metadata and the admin web UI read from here.
-__version__ = "0.3.83"
+__version__ = "0.3.84"
 __tagline__ = "Complete orchestration, distribution and escalation of remotizable advanced inference."
 
 # Configure the CUDA caching allocator BEFORE torch is imported anywhere.

codai/api/embeddings.py

@@ -352,6 +352,55 @@ def _resolve_repo_file(model_name: str, filename: str):
 _BGE_M3_TYPES = ('dense', 'sparse', 'colbert')
 
 
+#: `(model_name, filename) -> bool`, so the Hub is asked once per process.
+#: A repo's file list does not change under a running server.
+_REPO_FILE_CACHE: dict = {}
+
+
+def _repo_has_file(model_name: str, filename: str) -> bool:
+    """Does this repo contain ``filename``? Cache first, then the Hub's INDEX.
+
+    `_resolve_repo_file` answers from the local disk only, which is right for
+    "give me the path" and wrong for "does this exist" -- and the difference is
+    invisible until the model has never been downloaded.
+
+    On a RENTED POD it is never downloaded. The pod is disposable and its cache
+    starts empty, so a feature detected by the presence of a file was
+    permanently undetectable there: bge-m3 loaded through the DENSE
+    sentence-transformers path on every pod, every time, and the request for
+    sparse vectors was then refused with a message telling the caller to use
+    the image they were already using.
+
+    So when the file is not on disk, ask the Hub for the repo's file LIST --
+    metadata, no download, one call per process. Offline installs are
+    unaffected: HF_HUB_OFFLINE short-circuits it, and any failure answers False
+    exactly as before.
+    """
+    if _resolve_repo_file(model_name, filename) is not None:
+        return True
+    import os
+    if os.path.isdir(model_name):
+        return False                 # a local dir IS the whole answer
+    if str(os.environ.get("HF_HUB_OFFLINE") or "").strip().lower() in (
+            "1", "true", "yes", "on"):
+        return False
+    key = (str(model_name), str(filename))
+    hit = _REPO_FILE_CACHE.get(key)
+    if hit is not None:
+        return hit
+    found = False
+    try:
+        from huggingface_hub import list_repo_files
+        found = filename in set(list_repo_files(model_name))
+    except Exception as exc:
+        # Not reachable, gated, or not a Hub repo. Answer the way the local-only
+        # check always did rather than failing a load over a metadata lookup.
+        print(f"[embeddings] could not list files for {model_name!r} "
+              f"({type(exc).__name__}) — assuming no {filename}", flush=True)
+    _REPO_FILE_CACHE[key] = found
+    return found
+
+
 def _is_bge_m3(model_name: str, trust: bool) -> bool:
     """True if the repo is a bge-m3-style multi-vector embedder.
 
@@ -360,7 +409,10 @@ def _is_bge_m3(model_name: str, trust: bool) -> bool:
     (AutoConfig can fail to resolve in an offline/engine context, which would wrongly
     demote bge-m3 to the dense path); we only exclude vision/dual encoders, which never
     carry this head anyway."""
-    if _resolve_repo_file(model_name, 'sparse_linear.pt') is None:
+    # `_repo_has_file`, NOT `_resolve_repo_file`: on a rented pod nothing is
+    # cached when this runs, and a local-only check made multi-vector bge-m3
+    # undetectable on exactly the machines built to serve it.
+    if not _repo_has_file(model_name, 'sparse_linear.pt'):
         return False
     try:
         if _is_vision_only(model_name, trust) or _is_dual_encoder(model_name, trust):

tests/test_embedding_repo_file_detection.py

+"""A feature detected by a FILE must be detectable before the file is there.
+
+`_is_bge_m3` keys off `sparse_linear.pt` — the definitive signal that a repo is
+a multi-vector embedder, since plain dense models do not ship one. It asked
+`_resolve_repo_file`, which answers from the local disk and never the network.
+
+That is correct for "give me the path" and wrong for "does this exist", and the
+difference is invisible until the model has never been downloaded.
+
+On a RENTED POD it has never been downloaded. The pod is disposable and its
+cache starts empty, so on every pod, every time, bge-m3 loaded through the
+DENSE sentence-transformers path — and the request for sparse was then refused
+with a message telling the caller to serve the model on the coderai-embeddings
+image, which is the image it was already running on.
+
+Measured end to end on a real A40: 379 s, then HTTP 400 saying exactly that.
+"""
+
+import pathlib
+import sys
+
+import pytest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from codai.api import embeddings as emb                        # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def _clear_cache():
+    emb._REPO_FILE_CACHE.clear()
+    yield
+    emb._REPO_FILE_CACHE.clear()
+
+
+@pytest.fixture
+def no_local(monkeypatch):
+    """Nothing in the cache — a freshly rented pod."""
+    monkeypatch.setattr(emb, "_resolve_repo_file", lambda *a, **k: None)
+
+
+def _hub(monkeypatch, files, calls=None):
+    import huggingface_hub
+
+    def _list(repo, *a, **k):
+        if calls is not None:
+            calls.append(repo)
+        return list(files)
+    monkeypatch.setattr(huggingface_hub, "list_repo_files", _list, raising=False)
+
+
+# ------------------------------------------------------ the cold pod case #
+def test_the_head_is_found_on_a_pod_with_an_empty_cache(monkeypatch, no_local):
+    """THE regression. Nothing on disk, and the repo does carry the head."""
+    _hub(monkeypatch, ["config.json", "sparse_linear.pt", "colbert_linear.pt"])
+    assert emb._repo_has_file("BAAI/bge-m3", "sparse_linear.pt") is True
+    assert emb._is_bge_m3("BAAI/bge-m3", False) is True
+
+
+def test_a_plain_dense_repo_is_still_dense(monkeypatch, no_local):
+    _hub(monkeypatch, ["config.json", "model.safetensors"])
+    assert emb._repo_has_file("some/plain-bert", "sparse_linear.pt") is False
+    assert emb._is_bge_m3("some/plain-bert", False) is False
+
+
+# --------------------------------------------------- what must not change #
+def test_a_cached_file_needs_no_hub_call(monkeypatch):
+    """The local answer still wins, and costs nothing."""
+    monkeypatch.setattr(emb, "_resolve_repo_file", lambda *a, **k: "/cache/x.pt")
+    calls = []
+    _hub(monkeypatch, [], calls)
+    assert emb._repo_has_file("BAAI/bge-m3", "sparse_linear.pt") is True
+    assert calls == []
+
+
+def test_a_local_directory_is_the_whole_answer(monkeypatch, tmp_path):
+    """A path on disk is not a Hub repo: asking the Hub about it would look up
+    someone else's model of the same name."""
+    calls = []
+    _hub(monkeypatch, ["sparse_linear.pt"], calls)
+    monkeypatch.setattr(emb, "_resolve_repo_file", lambda *a, **k: None)
+    assert emb._repo_has_file(str(tmp_path), "sparse_linear.pt") is False
+    assert calls == []
+
+
+def test_offline_installs_never_reach_the_network(monkeypatch, no_local):
+    calls = []
+    _hub(monkeypatch, ["sparse_linear.pt"], calls)
+    for val in ("1", "true", "YES", "on"):
+        emb._REPO_FILE_CACHE.clear()
+        monkeypatch.setenv("HF_HUB_OFFLINE", val)
+        assert emb._repo_has_file("BAAI/bge-m3", "sparse_linear.pt") is False
+    assert calls == []
+
+
+def test_an_unreachable_hub_answers_the_way_it_always_did(monkeypatch, no_local):
+    """A metadata lookup must never be able to fail a load."""
+    import huggingface_hub
+
+    def _boom(*a, **k):
+        raise OSError("no route to host")
+    monkeypatch.setattr(huggingface_hub, "list_repo_files", _boom, raising=False)
+    assert emb._repo_has_file("BAAI/bge-m3", "sparse_linear.pt") is False
+    assert emb._is_bge_m3("BAAI/bge-m3", False) is False
+
+
+def test_the_hub_is_asked_once_per_repo(monkeypatch, no_local):
+    """A repo's file list does not change under a running server, and this sits
+    on the load path of every embedding request."""
+    calls = []
+    _hub(monkeypatch, ["sparse_linear.pt"], calls)
+    for _ in range(5):
+        assert emb._repo_has_file("BAAI/bge-m3", "sparse_linear.pt") is True
+    assert len(calls) == 1
+
+
+def test_a_negative_answer_is_cached_too(monkeypatch, no_local):
+    calls = []
+    _hub(monkeypatch, ["config.json"], calls)
+    for _ in range(4):
+        assert emb._repo_has_file("some/plain", "sparse_linear.pt") is False
+    assert len(calls) == 1
+
+
+def test_two_repos_are_cached_separately(monkeypatch, no_local):
+    import huggingface_hub
+    monkeypatch.setattr(
+        huggingface_hub, "list_repo_files",
+        lambda repo, *a, **k: (["sparse_linear.pt"] if "bge-m3" in repo
+                               else ["config.json"]), raising=False)
+    assert emb._repo_has_file("BAAI/bge-m3", "sparse_linear.pt") is True
+    assert emb._repo_has_file("other/model", "sparse_linear.pt") is False
+
+
+def test_the_detector_uses_the_existence_check_not_the_path_one():
+    """Pin the distinction, because the two read almost the same at the call
+    site and only one of them works on a pod."""
+    src = (ROOT / "codai/api/embeddings.py").read_text()
+    blk = src.split("def _is_bge_m3")[1].split("\ndef ")[0]
+    assert "_repo_has_file(" in blk
+    assert "_resolve_repo_file(" not in blk