ragx-cli 0.3.2__tar.gz → 0.3.3__tar.gz

{ragx_cli-0.3.2 → ragx_cli-0.3.3}/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `ragx-cli` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.3.3] — 2026-07-15
+
+### Added
+
+- **Early hint when the reranker model download stalls**: the huggingface_hub retry
+  loop inside the cross-encoder load can spin for minutes before failing. The first
+  retry warning now also prints a one-shot stderr pointer to the README's "Reranker on
+  restricted networks" section (manual copy, mirror, or `rerank.enabled false`).
+
 ## [0.3.2] — 2026-07-15
 
 _0.3.1 was tagged but never published — its release workflow referenced a nonexistent
@@ -95,6 +104,7 @@ Initial release: Phases 0–3 of [the plan](ragx-cli-plan.md), built and validat
   on stderr, exit codes `0` results / `1` empty / `2` error.
 - MIT license; PyPI packaging as `ragx-cli` with trusted-publishing release workflow.
 
+[0.3.3]: https://github.com/alber70g/ragx-cli/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/alber70g/ragx-cli/compare/v0.3.0...v0.3.2
 [0.3.0]: https://github.com/alber70g/ragx-cli/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/alber70g/ragx-cli/compare/v0.1.1...v0.2.0

{ragx_cli-0.3.2 → ragx_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragx-cli
-Version: 0.3.2
+Version: 0.3.3
 Summary: Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it
 Project-URL: Repository, https://github.com/alber70g/ragx-cli
 Project-URL: Issues, https://github.com/alber70g/ragx-cli/issues

{ragx_cli-0.3.2 → ragx_cli-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.3.2"
+version = "0.3.3"
 description = "Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it"
 readme = "README.md"
 license = "MIT"

{ragx_cli-0.3.2 → ragx_cli-0.3.3}/src/ragx/providers/st_reranker.py

@@ -2,10 +2,36 @@
 
 from __future__ import annotations
 
+import logging
+import sys
 from typing import Sequence
 
 from ragx.core.errors import RagxError
 
+_MANUAL_INSTALL_HINT = (
+    "downloading the reranker model from huggingface.co is failing — to install the "
+    "model manually, use a mirror, or disable reranking, see "
+    "https://github.com/alber70g/ragx-cli#reranker-on-restricted-networks-no-huggingfaceco"
+)
+
+
+class _DownloadHintHandler(logging.Handler):
+    """Emits the manual-install hint once, on the first huggingface_hub retry warning."""
+
+    def __init__(self) -> None:
+        super().__init__(level=logging.WARNING)
+        self._fired = False
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if self._fired:
+            return
+        message = record.getMessage().lower()
+        if "retry" in message or "thrown while requesting" in message:
+            self._fired = True
+            # logging drops re-entrant calls made while a record is being
+            # handled, so the hint must go to stderr directly.
+            print(f"WARNING: {_MANUAL_INSTALL_HINT}", file=sys.stderr)
+
 
 class STReranker:
     """Reranker implementing providers.base.Reranker via a sentence-transformers CrossEncoder."""
@@ -20,6 +46,9 @@ class STReranker:
                 "sentence-transformers not installed — install with: uv tool install ragx-cli --with ragx-cli[rerank]"
             ) from exc
         self.model = model
+        hint = _DownloadHintHandler()
+        hub_logger = logging.getLogger("huggingface_hub")
+        hub_logger.addHandler(hint)
         try:
             self._encoder = CrossEncoder(model)
         except Exception as exc:
@@ -30,6 +59,8 @@ class STReranker:
                 "reranking (rerank.enabled false); see README 'Reranker on restricted "
                 "networks (no huggingface.co)'"
             ) from exc
+        finally:
+            hub_logger.removeHandler(hint)
 
     def score(self, query: str, texts: Sequence[str]) -> list[float]:
         pairs = [[query, text] for text in texts]

{ragx_cli-0.3.2 → ragx_cli-0.3.3}/tests/test_providers.py

@@ -200,6 +200,42 @@ def test_make_reranker_model_load_failure_returns_none_and_warns(monkeypatch, ca
     assert "HF_ENDPOINT" in err
 
 
+def test_st_reranker_first_retry_warning_emits_manual_install_hint(monkeypatch, capsys):
+    """The first HF download-retry warning triggers a one-shot README pointer."""
+    import logging
+    import sys
+    import types
+
+    class _RetryingCrossEncoder:
+        def __init__(self, model):
+            hub_log = logging.getLogger("huggingface_hub.utils._http")
+            for _ in range(2):
+                hub_log.warning(
+                    "'_ssl.c:1015: The handshake operation timed out' thrown while "
+                    "requesting HEAD https://huggingface.co/x/resolve/main/modules.json"
+                )
+                hub_log.warning("Retrying in 1s [Retry 1/5].")
+            raise OSError("timed out")
+
+    fake = types.ModuleType("sentence_transformers")
+    fake.CrossEncoder = _RetryingCrossEncoder
+    monkeypatch.setitem(sys.modules, "sentence_transformers", fake)
+
+    from ragx.core.errors import RagxError
+    from ragx.providers.st_reranker import STReranker, _DownloadHintHandler
+
+    with pytest.raises(RagxError):
+        STReranker("BAAI/bge-reranker-v2-m3")
+
+    err = capsys.readouterr().err
+    assert err.count("install the model manually") == 1
+    assert "#reranker-on-restricted-networks" in err
+    assert not any(
+        isinstance(h, _DownloadHintHandler)
+        for h in logging.getLogger("huggingface_hub").handlers
+    )
+
+
 def test_api_key_env_resolved_and_sent(monkeypatch):
     monkeypatch.setenv("RAGX_TEST_KEY", "sk-test-123")
     cfg = _config({"embeddings": {"api_key_env": "RAGX_TEST_KEY"}})