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.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
fix(xerj-code): preserve hybrid results on transport failures
Amakurai20e52f7763fd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex e16214a95..c43df5461 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -99,6 +99,9 @@ jobs:- name: Vetted hub manifests validaterun: 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 isdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.0exposes the same two parameters. Raised by @Vinz2168 from a shared-memoryagent 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### Addeddiff --git a/tools/xerj-code/README.md b/tools/xerj-code/README.mdindex 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```shtools/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.pyindex 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 ratherthan handing back code that no longer exists."""import argparse+import http.clientimport jsonimport osimport 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 corpuswhere 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 [], 0if 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 capableelse 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.pynew file mode 100644index 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()