Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

fix(xerj-code): preserve hybrid results on transport failures

Amakurai20e52f7763fd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e16214a95..c43df5461 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -99,6 +99,9 @@ jobs:
- name: Vetted hub manifests validate
run: python3 tools/xerj-code/tests/validate_manifest.py --hub tools/xerj-code/hub/*.json
+ - name: Hybrid retrieval transport fallback
+ run: python3 tools/xerj-code/tests/test_hybrid_fallback.py
+
# #489: this script existed, worked, and had been failing locally for three
# releases — the version footer, headline and narrative on landing/index.html
# stayed pinned to rc.15 through rc.16 and rc.17 because nothing ran it. It is
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16a4a91c7..64baa9754 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
exposes the same two parameters. Raised by @Vinz2168 from a shared-memory
agent integration where neither single mode was enough.
+### Fixed
+
+- **`xc.py --mode hybrid` keeps BM25 results when the optional vector arm has
+ a transport failure.** Connection failures, read timeouts, and interrupted
+ HTTP responses during semantic mapping discovery or search now take the
+ existing BM25-only fallback instead of aborting and discarding valid hits.
+ Primary BM25 failures still exit with an error. Standalone `--mode semantic`
+ now reports mapping/search HTTP and transport failures as errors (exit `2`)
+ instead of treating failed requests as empty search results (exit `1`).
+
## [1.0.0-rc.74] - 2026-09-08
### Added
diff --git a/tools/xerj-code/README.md b/tools/xerj-code/README.md
index c785fe981..0a52dfb6e 100644
--- a/tools/xerj-code/README.md
+++ b/tools/xerj-code/README.md
@@ -88,8 +88,19 @@ already knows, it is overhead. `SKILL.md` and
[`docs/case-studies/reference-coding/`](../../docs/case-studies/reference-coding/)
carry the measured numbers, including the cases where this loses.
+## Hybrid retrieval fallback
+
+With `--mode hybrid`, the optional vector arm falls back to the already
+retrieved BM25 passages if its mapping lookup or search has a transport error:
+connection failures, read timeouts, and interrupted HTTP responses. Prose and
+MEATL output label the fallback as `BM25 only`; `--json` keeps its existing hits
+format. A failed primary BM25 search still exits with an error. In standalone
+`--mode semantic`, mapping and search HTTP/transport failures exit `2`, rather
+than reporting no match; there are no BM25 results to fall back to.
+
## Tests
```sh
tools/xerj-code/tests/test_xc_corpus.sh # offline; local git fixtures over file://
+python3 tools/xerj-code/tests/test_hybrid_fallback.py # offline; simulated HTTP failures
```
diff --git a/tools/xerj-code/scripts/xc.py b/tools/xerj-code/scripts/xc.py
index 645b4afb0..832cc43d3 100755
--- a/tools/xerj-code/scripts/xc.py
+++ b/tools/xerj-code/scripts/xc.py
@@ -6,6 +6,7 @@ with file:line provenance, and it refuses to answer from a stale index rather
than handing back code that no longer exists.
"""
import argparse
+import http.client
import json
import os
import re
@@ -233,7 +234,7 @@ def resolve_fields(prefix):
def post(path, body, fatal=True):
- """POST a search body. With fatal=False, an HTTP error is returned, not fatal.
+ """POST a search body; fatal=False returns HTTP/transport errors as data.
The non-fatal path exists for the vector arm of hybrid retrieval: a corpus
where no index supports `semantic` must degrade to BM25, not abort.
@@ -247,12 +248,25 @@ def post(path, body, fatal=True):
with urllib.request.urlopen(req, timeout=60) as resp:
return json.load(resp)
except urllib.error.HTTPError as e:
- msg = e.read()[:200].decode(errors="replace")
if not fatal:
- return {"_xc_error": f"{e.code}: {msg}"}
+ # The status already means fallback. Reading an optional error
+ # body can itself time out or fail on an interrupted response.
+ e.close()
+ return {"_xc_error": f"{e.code}: {e.reason}"}
+ try:
+ msg = e.read()[:200].decode(errors="replace")
+ except (OSError, http.client.HTTPException) as read_error:
+ msg = f"{e.reason}; error response could not be read: {read_error}"
+ finally:
+ e.close()
die(f"search failed ({e.code}): {msg}")
- except urllib.error.URLError as e:
- die(f"cannot reach XERJ at {URL}: {e.reason}")
+ except (OSError, http.client.HTTPException) as e:
+ # URLError is an OSError; response reads can also raise socket or
+ # HTTP errors directly, without urllib wrapping them.
+ msg = f"cannot reach XERJ at {URL}: {getattr(e, 'reason', str(e))}"
+ if not fatal:
+ return {"_xc_error": msg}
+ die(msg)
def bm25_query(query, lang, fields=None):
@@ -281,7 +295,7 @@ def search(prefix, query, k, lang, highlight=False):
return post(f"{prefix}*/_search", body)
-def semantic_indices(prefix, field="body"):
+def semantic_indices(prefix, field="body", fatal=False):
"""Indices under `prefix*` whose `field` is mapped as semantic_text.
A `semantic` query against an index where the field is plain `text` does not
@@ -292,13 +306,18 @@ def semantic_indices(prefix, field="body"):
arm is aimed only at those indices.
Returns (capable, total). An unreachable or unparseable mapping yields an
- empty capable set, which degrades to BM25 rather than failing.
+ empty capable set, which degrades to BM25 rather than failing. Standalone
+ semantic retrieval uses fatal=True because it has no BM25 result to keep.
"""
req = urllib.request.Request(f"{URL}/{prefix}*/_mapping")
try:
with urllib.request.urlopen(req, timeout=30) as resp:
mapping = json.load(resp)
- except (urllib.error.HTTPError, urllib.error.URLError, ValueError):
+ except (OSError, http.client.HTTPException, ValueError) as e:
+ if isinstance(e, urllib.error.HTTPError):
+ e.close()
+ if fatal:
+ die(f"semantic mapping lookup failed at {URL}: {e}")
return [], 0
if not isinstance(mapping, dict):
return [], 0
@@ -310,14 +329,14 @@ def semantic_indices(prefix, field="body"):
return capable, len(mapping)
-def semantic_search(indices, query, k, lang, field="body"):
- """The vector arm. Returns [] on any error — the caller degrades to BM25."""
+def semantic_search(indices, query, k, lang, field="body", fatal=False):
+ """Vector search; errors are optional only when BM25 fallback is allowed."""
if not indices:
return []
q = {"semantic": {"field": field, "query": query}}
if lang:
q = {"bool": {"must": [q, {"match": {"language": lang}}]}}
- res = post(f"{','.join(indices)}/_search", {"size": k, "query": q}, fatal=False)
+ res = post(f"{','.join(indices)}/_search", {"size": k, "query": q}, fatal=fatal)
if "_xc_error" in res:
return []
return res.get("hits", {}).get("hits", [])
@@ -386,11 +405,11 @@ def hybrid_search(prefix, query, k, lang, depth=None):
"are not evidence of a match, so this is reported as a miss")
capable, total = semantic_indices(prefix)
if not capable:
- return bm[:k], (f"BM25 only — no index under '{prefix}*' maps `body` as "
- f"semantic_text, so the vector arm cannot run")
+ return bm[:k], (f"BM25 only — no usable semantic_text mapping for `body` "
+ f"could be discovered under '{prefix}*'")
sem = semantic_search(capable, query, depth, lang)
if not sem:
- return bm[:k], (f"BM25 only — the vector arm returned nothing from the "
+ return bm[:k], (f"BM25 only — vector search failed or returned no hits from the "
f"{len(capable)} semantic_text index(es)")
note = (f"hybrid RRF(k={RRF_K}) — BM25 over {total} index(es), vector over "
f"{len(capable)} of {total}")
@@ -632,8 +651,8 @@ def main():
hits, note = hybrid_search(state["prefix"], args.query, args.k, args.lang)
res = {"hits": {"hits": hits}}
elif args.mode == "semantic":
- capable, total = semantic_indices(state["prefix"])
- hits = semantic_search(capable, args.query, args.k, args.lang)
+ capable, total = semantic_indices(state["prefix"], fatal=True)
+ hits = semantic_search(capable, args.query, args.k, args.lang, fatal=True)
res = {"hits": {"hits": hits}}
note = (f"vector only over {len(capable)} of {total} index(es)" if capable
else f"no index under '{state['prefix']}*' maps `body` as semantic_text")
diff --git a/tools/xerj-code/tests/test_hybrid_fallback.py b/tools/xerj-code/tests/test_hybrid_fallback.py
new file mode 100644
index 000000000..25d8ac396
--- /dev/null
+++ b/tools/xerj-code/tests/test_hybrid_fallback.py
@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Offline regressions for optional transport failures in hybrid retrieval."""
+import contextlib
+import http.client
+import importlib.util
+import io
+import json
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+import urllib.error
+
+
+XC_PATH = Path(__file__).resolve().parents[1] / "scripts" / "xc.py"
+PREFIX = "xc-fixture"
+INDEX = PREFIX + "-1"
+
+
+def hit(name, score):
+ return {"_index": INDEX, "_id": name, "_score": score,
+ "_source": {"path": f"fixture/{name}.rs",
+ "body": f"fn parse_{name}() {{}}"}}
+
+
+BM25_HITS = [hit("alpha", 9.0), hit("beta", 7.0), hit("gamma", 5.0)]
+VECTOR_HITS = [hit("beta", 0.9), hit("delta", 0.8)]
+
+# A connection can fail while opening a request or while reading its body.
+# These are concrete urllib/http.client failures, without network or timing.
+FAILURES = (
+ ("url", lambda: urllib.error.URLError("fixture connection refused"), False),
+ ("timeout", lambda: TimeoutError("fixture read timed out"), True),
+ ("reset", lambda: ConnectionResetError("fixture connection reset"), True),
+ ("disconnect", lambda: http.client.RemoteDisconnected("fixture disconnect"), False),
+ ("incomplete", lambda: http.client.IncompleteRead(b'{"hits":', 10), True),
+)
+
+
+class BrokenResponse(io.BytesIO):
+ def __init__(self, failure):
+ super().__init__()
+ self.failure = failure
+
+ def read(self, *args):
+ raise self.failure()
+
+
+class Transport:
+ """Serve real request shapes; optionally fail one retrieval stage."""
+
+ def __init__(self, stage=None, failure=None, during_read=False, bm25=None,
+ semantic_only=False, vector=None, capable=True):
+ self.stage = stage
+ self.failure = failure
+ self.during_read = during_read
+ self.bm25 = BM25_HITS if bm25 is None else bm25
+ self.vector = VECTOR_HITS if vector is None else vector
+ self.semantic_only = semantic_only
+ self.capable = capable
+ self.calls = []
+ self.mapping_calls = 0
+
+ def __call__(self, req, timeout=None):
+ url = req.full_url
+ if "/_cat/indices/" in url:
+ stage, payload = "loaded", [{"index": INDEX}]
+ elif url.endswith("/_mapping"):
+ self.mapping_calls += 1
+ stage = "fields" if self.mapping_calls == 1 and not self.semantic_only else "mapping"
+ payload = {INDEX: {"mappings": {"properties": {
+ "body": {"type": "semantic_text" if self.capable else "text"},
+ "defs": {"type": "text"}, "title": {"type": "text"},
+ }}}}
+ elif url.endswith("/_search"):
+ body = json.loads(req.data)
+ stage = "vector" if "semantic" in body["query"] else "bm25"
+ payload = {"hits": {"hits": self.vector if stage == "vector" else self.bm25}}
+ else:
+ raise AssertionError(f"unexpected request: {url}")
+ self.calls.append(stage)
+ if stage == self.stage:
+ if self.during_read:
+ return BrokenResponse(self.failure)
+ raise self.failure()
+ return io.BytesIO(json.dumps(payload).encode())
+
+
+class HybridFallbackTests(unittest.TestCase):
+ def setUp(self):
+ spec = importlib.util.spec_from_file_location("xc_hybrid_under_test", XC_PATH)
+ self.xc = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(self.xc)
+ self.home = tempfile.TemporaryDirectory(prefix="xc-hybrid-test-")
+ self.addCleanup(self.home.cleanup)
+
+ def run_main(self, transport, flags=(), mode="hybrid"):
+ out, err = io.StringIO(), io.StringIO()
+ argv = ["xc.py", "fixture", "parse", "-k", "2", "--mode", mode, *flags]
+ state = {"corpus": "fixture", "prefix": PREFIX}
+ # Every patched process-global value is restored, including urllib and
+ # argv. A fresh field cache also keeps repeated subtests independent.
+ with patch.object(self.xc, "ROOT", self.home.name), \
+ patch.object(self.xc, "URL", "http://fixture.invalid"), \
+ patch.object(self.xc, "_FIELDS_CACHE", {}), \
+ patch.object(self.xc, "load_state", return_value=state), \
+ patch.object(self.xc, "field_report_nudge"), \
+ patch.object(self.xc.urllib.request, "urlopen", side_effect=transport), \
+ patch.object(sys, "argv", argv), \
+ contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+ code = 0
+ try:
+ self.xc.main()
+ except SystemExit as exc:
+ code = exc.code
+ return code, out.getvalue(), err.getvalue()
+
+ def assert_fallback(self, transport, flags):
+ code, out, err = self.run_main(transport, flags)
+ self.assertEqual(code, 0, err)
+ self.assertEqual(err, "")
+ if "--json" in flags:
+ self.assertEqual(json.loads(out), {"hits": {"hits": BM25_HITS[:2]}})
+ else:
+ self.assertIn("BM25 only", out)
+ self.assertNotIn("hybrid RRF", out)
+ self.assertNotIn("no index under", out)
+ self.assertLess(out.index("fixture/alpha.rs"), out.index("fixture/beta.rs"))
+ self.assertNotIn("fixture/gamma.rs", out)
+ self.assertNotIn("fixture/delta.rs", out)
+ if "--meatl" in flags:
+ self.assertTrue(out.startswith("@mode BM25 only"))
+ self.assertEqual(out.count("@ok "), 2)
+
+ def test_optional_transport_failures_keep_bm25_in_each_output_mode(self):
+ for stage in ("mapping", "vector"):
+ for name, failure, during_read in FAILURES:
+ for flags in ((), ("--json",), ("--meatl",)):
+ with self.subTest(stage=stage, failure=name, flags=flags):
+ transport = Transport(stage, failure, during_read)
+ self.assert_fallback(transport, flags)
+ self.assertEqual(transport.calls.count("bm25"), 1)
+ self.assertEqual(transport.calls.count("vector"), int(stage == "vector"))
+
+ def test_optional_http_errors_still_fall_back(self):
+ for stage in ("mapping", "vector"):
+ with self.subTest(stage=stage):
+ def failure():
+ error = urllib.error.HTTPError(
+ "http://fixture.invalid", 503, "fixture unavailable", {}, io.BytesIO(b"offline"))
+ self.addCleanup(error.close)
+ return error
+ self.assert_fallback(Transport(stage, failure), ("--json",))
+
+ def test_optional_http_error_with_unreadable_body_still_falls_back(self):
+ for name, read_failure, _ in (FAILURES[1], FAILURES[4]):
+ with self.subTest(failure=name):
+ def failure():
+ error = urllib.error.HTTPError(
+ "http://fixture.invalid", 503, "fixture unavailable", {},
+ BrokenResponse(read_failure))
+ self.addCleanup(error.close)
+ return error
+ self.assert_fallback(Transport("vector", failure), ("--json",))
+
+ def test_primary_http_error_with_unreadable_body_is_still_fatal(self):
+ for mode in ("bm25", "hybrid", "semantic"):
+ for name, read_failure, _ in (FAILURES[1], FAILURES[4]):
+ with self.subTest(mode=mode, failure=name):
+ def failure():
+ error = urllib.error.HTTPError(
+ "http://fixture.invalid", 503, "fixture unavailable", {},
+ BrokenResponse(read_failure))
+ self.addCleanup(error.close)
+ return error
+ stage = "vector" if mode == "semantic" else "bm25"
+ transport = Transport(stage, failure, semantic_only=mode == "semantic")
+ code, out, err = self.run_main(transport, ("--json",), mode)
+ self.assertEqual((code, out), (2, ""))
+ self.assertIn("search failed (503)", err)
+
+ def test_primary_transport_failures_are_fatal_without_results(self):
+ for mode in ("bm25", "hybrid"):
+ for name, failure, during_read in FAILURES:
+ with self.subTest(mode=mode, failure=name):
+ transport = Transport("bm25", failure, during_read)
+ code, out, err = self.run_main(transport, ("--json",), mode)
+ self.assertEqual(code, 2)
+ self.assertEqual(out, "")
+ self.assertIn("cannot reach XERJ", err)
+ self.assertNotIn("No passage", err)
+ self.assertNotIn("vector", transport.calls)
+
+ def test_successful_hybrid_fuses_ranks_and_caps_results(self):
+ transport = Transport()
+ code, out, err = self.run_main(transport, ("--json",))
+ self.assertEqual((code, err), (0, ""))
+ hits = json.loads(out)["hits"]["hits"]
+ self.assertEqual([h["_id"] for h in hits], ["beta", "alpha"])
+ self.assertAlmostEqual(hits[0]["_score"], 1 / 62 + 1 / 61)
+ self.assertEqual(hits[0]["_rrf_ranks"], {"0": 2, "1": 1})
+ self.assertEqual(hits[0]["_source"], BM25_HITS[1]["_source"])
+ self.assertEqual(transport.calls, ["loaded", "fields", "bm25", "mapping", "vector"])
+
+ def test_empty_bm25_never_attempts_optional_retrieval(self):
+ transport = Transport(bm25=[])
+ code, out, err = self.run_main(transport)
+ self.assertEqual((code, err), (1, ""))
+ self.assertIn("No passage", out)
+ self.assertEqual(transport.calls, ["loaded", "fields", "bm25"])
+
+ def assert_semantic_failure(self, transport, flags):
+ code, out, err = self.run_main(transport, flags, mode="semantic")
+ self.assertEqual(code, 2, (out, err))
+ self.assertEqual(out, "")
+ self.assertIn("xc:", err)
+ self.assertNotIn("No passage", err)
+ self.assertNotIn("bm25", transport.calls)
+
+ def test_standalone_semantic_transport_failures_are_fatal(self):
+ for stage in ("mapping", "vector"):
+ for name, failure, during_read in FAILURES:
+ for flags in ((), ("--json",)):
+ with self.subTest(stage=stage, failure=name, flags=flags):
+ transport = Transport(stage, failure, during_read, semantic_only=True)
+ self.assert_semantic_failure(transport, flags)
+
+ def test_standalone_semantic_http_errors_are_fatal(self):
+ for stage in ("mapping", "vector"):
+ for flags in ((), ("--json",)):
+ with self.subTest(stage=stage, flags=flags):
+ def failure():
+ error = urllib.error.HTTPError(
+ "http://fixture.invalid", 503, "fixture unavailable", {}, io.BytesIO(b"offline"))
+ self.addCleanup(error.close)
+ return error
+ self.assert_semantic_failure(Transport(stage, failure, semantic_only=True), flags)
+
+ def test_successful_standalone_semantic_preserves_vector_hits(self):
+ transport = Transport(semantic_only=True)
+ code, out, err = self.run_main(transport, ("--json",), mode="semantic")
+ self.assertEqual((code, err), (0, ""))
+ self.assertEqual(json.loads(out), {"hits": {"hits": VECTOR_HITS}})
+ self.assertEqual(transport.calls, ["loaded", "mapping", "vector"])
+
+ def test_standalone_semantic_genuine_misses_keep_exit_one(self):
+ for capable in (False, True):
+ with self.subTest(capable=capable):
+ transport = Transport(semantic_only=True, capable=capable, vector=[])
+ code, out, err = self.run_main(transport, mode="semantic")
+ self.assertEqual((code, err), (1, ""))
+ self.assertIn("No passage", out)
+ expected = ["loaded", "mapping"] + (["vector"] if capable else [])
+ self.assertEqual(transport.calls, expected)
+
+
+if __name__ == "__main__":
+ unittest.main()