Upload 7 files

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angshul Majumdar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MODEL_CARD.md

@@ -0,0 +1,56 @@
+---
+language:
+- en
+license: mit
+tags:
+- rag
+- reranking
+- evidence-subset-selection
+- multi-hop-reasoning
+pipeline_tag: text-ranking
+---
+
+# Evidence-Graph Reranker: algorithm card
+
+**Type:** training-free joint selection algorithm with external pretrained neural relevance scorers. **Not** a standalone trained neural checkpoint or language generator.
+
+## Formula
+
+`score(candidate | already_selected, query) = 0.4 × minmax(relevance) + 0.5 × directed_title_link + 0.2 × query_title_match`
+
+**One rule for all six datasets.** No dataset-specific presets or facet objectives. Scores are recomputed greedily after selection; selecting an informative first passage can make a complementary follow-up passage more attractive.
+
+## Neural models (third-party weights)
+
+- `cross-encoder/ms-marco-MiniLM-L6-v2`: pretrained relevance logits for query/passage pairs, 256 WordPiece cap used in experiments.
+- `sentence-transformers/all-MiniLM-L6-v2`: cosine similarity over pretrained normalized embeddings, 128 WordPiece cap used in experiments.
+
+The code pulls these third-party weights separately from Hugging Face. The package's MIT license covers our selector code, not external pretrained weights.
+
+## Evaluation
+
+Measured complete supporting evidence coverage at k=3 passages:
+
+| Benchmark | Cross-encoder | Cross-encoder + fixed graph | Gain |
+|---|---:|---:|---:|
+| HotpotQA (600) | 60.83% | 80.50% | +19.67 pp |
+| 2WikiMultiHopQA (600) | 44.50% | 70.17% | +25.67 pp |
+| MuSiQue (300) | 19.33% | 27.00% | +7.67 pp |
+| HoVer (300) | 57.00% | 72.67% | +15.67 pp |
+| MultiHop-RAG (300) | 13.67% | 13.67% | +0.00 pp |
+| QASC (300) | 13.00% | 13.00% | +0.00 pp |
+
+
+Six datasets, four improvements and two ties at k=3. These are not the same candidate-pool protocol. HotpotQA and 2Wiki use previously computed neural model outputs and newly rerun unified graph selection, not newly recomputed forward passes. For k=2,5,8, exact timings, candidate availability, bootstrap intervals and limitations, see `results/methodology.md` and `results/six_dataset_results.csv`.
+
+## Known limitations
+
+- Direct title/body string linking works best when meaningful titles and article cross-references exist. It cannot reliably model nonlexical semantic connections without additional features, which are *not part of this released single algorithm*.
+- On QASC's untitled sentences, the graph features vanish and the method becomes ordinary neural ranking. MultiHop-RAG at k=3 is also tied with the cross-encoder.
+- Gold-containing candidate pools on some benchmarks produce an easier, conditional reranking task. The method does not repair missing supporting evidence in the initial retrieval stage.
+- **No LLM answer-quality or hallucination-reduction metric was computed.** Avoid equating recovered evidence with successful RAG generation.
+- Graph's greedy heuristic does not carry a proven submodular approximation ratio.
+
+## Reuse
+
+Install the package and run the Gradio demo. The graph-only API, `rank_with_scores`, does not download neural checkpoints. Cite the original pretrained models if using neural scoring. Verify the terms of all third-party model checkpoints and datasets.

PACKAGE_README.md

@@ -0,0 +1,53 @@
+# Evidence-Graph Reranker
+
+An installable **single-algorithm**, training-free evidence-subset reranker for RAG.
+
+Unlike conventional independently scored query–document rerankers, it greedily selects a set of complementary passages using an explicitly directed title-reference graph. It can work with a pretrained MS MARCO MiniLM cross-encoder, a MiniLM dense encoder, or supplied relevance scores.
+
+## Install
+
+```bash
+pip install -e '.[neural]'
+```
+
+## Quick start
+
+```python
+from evidence_graph_reranker import EvidenceGraphReranker
+
+query = 'Who founded the company that released the Atlas device?'
+docs = [
+    {'title': 'Atlas device', 'text': 'The Atlas device was released by Novus Labs.'},
+    {'title': 'Novus Labs', 'text': 'Novus Labs was founded by Mira Chen.'},
+    {'title': 'Unrelated', 'text': 'A different device was invented elsewhere.'},
+]
+reranker = EvidenceGraphReranker(backend='cross-encoder', device='cpu')
+selected = reranker.rank(query, docs, k=2)
+print([(x['index'], x['title']) for x in selected])
+```
+
+**No model download:** if you have scores from an existing retriever, call `rank_with_scores(query, docs, scores, k)`. Neural scoring always happens before the unchanged fixed graph rule.
+
+## How selection works
+
+At each greedy step, every remaining candidate receives:
+
+`0.4 × per-query minmax neural relevance + 0.5 × directed link from an already selected passage + 0.2 × query/title match`
+
+The function is deterministic, has no learned parameters of its own, and does not use gold facts or answers at inference. The title feature uses an exact normalized title string, and the link feature checks whether a candidate's title appears in the body of a previously selected passage. Documents without titles simply lack these two signals and are selected by the underlying neural scores.
+
+Model checkpoints stay at their original locations:
+- `cross-encoder/ms-marco-MiniLM-L6-v2` (query+passage WordPiece max length 256)
+- `sentence-transformers/all-MiniLM-L6-v2` (dense WordPiece max length 128)
+
+## Public Hugging Face Space
+
+The repository root has `app.py`, `README.md` with Space metadata and `requirements.txt`. Upload these files to a new **Gradio Space**. Model weights download on first use. No model weights or dataset copies are redistributed in this package.
+
+## Benchmark results
+
+See `results/six_dataset_results.csv`, `MODEL_CARD.md`, and `results/methodology.md`. All six evaluations use the **identical feature extractor and greedy selector**. HotpotQA/2Wiki were reselected from cached pretrained neural logits and embeddings under the common algorithm, not rescored by rerunning the neural forward passes. This distinction is indicated in the timing report. The six benchmarks have different candidate pools and should not be pooled into a single headline accuracy number.
+
+## License
+
+MIT for this source code; external model weights and benchmark data retain their original licenses and usage terms.

README.md

@@ -1,14 +1,23 @@
 ---
 title: Evidence Graph Reranker
-emoji: 😻
-colorFrom: purple
-colorTo: yellow
+emoji: 🧩
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.31.0
-python_version: '3.12'
 app_file: app.py
 pinned: false
 license: mit
+tags:
+- rag
+- reranking
+- multi-hop-qa
+- evidence-retrieval
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Evidence-Graph Reranker — Hugging Face Space
+
+**A query-conditioned, training-free, joint evidence-subset reranker.** This Space scores query–passage pairs using the public MS MARCO MiniLM-L6 cross-encoder or all-MiniLM-L6 dense encoder, then selects passages with the **same fixed graph algorithm** evaluated on six evidence benchmarks.
+
+For installation, API examples, full six-dataset results and caveats, see [PACKAGE_README.md](PACKAGE_README.md), [MODEL_CARD.md](MODEL_CARD.md), and [results/methodology.md](results/methodology.md).
+
+**Not a new pretrained language model:** This repository provides an algorithm plus an optional Space. It downloads official neural scorer checkpoints on first use; no original model weights are redistributed.

app.py

@@ -0,0 +1,53 @@
+"""Hugging Face Space: live CPU demo for the exact fixed evidence-graph reranker."""
+import json
+import gradio as gr
+from evidence_graph_reranker import EvidenceGraphReranker
+
+_RERANKERS = {}
+EXAMPLE = [
+    {"title": "Atlas device", "text": "The Atlas device was launched by Novus Labs in 2025."},
+    {"title": "Novus Labs", "text": "Novus Labs was founded by Mira Chen in 2018."},
+    {"title": "Orion spacecraft", "text": "The Orion spacecraft is designed for space missions."},
+    {"title": "Electronics", "text": "Electronics can be manufactured in many countries."},
+]
+
+
+def demo(query, passages_json, budget, backend):
+    try:
+        docs = json.loads(passages_json)
+        if not isinstance(docs, list) or not 1 <= len(docs) <= 100:
+            raise ValueError("Enter a JSON list containing 1–100 passages.")
+        if not query.strip():
+            raise ValueError("Query cannot be empty.")
+        if backend not in _RERANKERS:
+            _RERANKERS[backend] = EvidenceGraphReranker(backend=backend, device="cpu", batch_size=16)
+        ranked = _RERANKERS[backend].rank(query, docs, k=int(budget))
+        table = [
+            [i + 1, r["index"], r["title"] or "(untitled)",
+             round(r["relevance_score"], 4), round(r["step_score"], 4),
+             round(r["directed_link_bonus"], 2)]
+            for i, r in enumerate(ranked)
+        ]
+        return table, json.dumps(ranked, indent=2, ensure_ascii=False)
+    except Exception as exc:
+        return [], json.dumps({"error": str(exc)})
+
+with gr.Blocks(title="Evidence-Graph Reranker") as app:
+    gr.Markdown("# Evidence-Graph Reranker\nTraining-free, query-conditioned **joint evidence selection** after neural relevance scoring.\n\nA passage's usefulness can rise when it completes a link from a previously selected passage. This demo uses **one fixed graph rule** for every dataset. Model weights are fetched from their original Hugging Face repositories.")
+    query = gr.Textbox(label="Query", value="Who founded the company that released the Atlas device?")
+    passages = gr.Code(label="Candidate passages (JSON array; optional title)", language="json",
+                       value=json.dumps(EXAMPLE, indent=2))
+    with gr.Row():
+        budget = gr.Slider(minimum=1, maximum=10, step=1, value=3, label="Passage budget (k)")
+        backend = gr.Dropdown(choices=["cross-encoder", "dense"], value="cross-encoder",
+                              label="Pretrained neural relevance model")
+    go = gr.Button("Select complementary evidence", variant="primary")
+    table = gr.Dataframe(headers=["Rank", "Candidate index", "Title", "Neural score", "Selection score", "Link bonus"],
+                         datatype=["number", "number", "str", "number", "number", "number"],
+                         label="Selected passages", interactive=False)
+    output = gr.Code(label="Full selection JSON", language="json")
+    go.click(demo, inputs=[query, passages, budget, backend], outputs=[table, output])
+    gr.Markdown("**Interpretation:** `selection_score` is a step-dependent heuristic, not a probability. Gold labels are never used by the selector. Reported benchmarks measure complete evidence coverage, *not* LLM-generated answer accuracy. See `MODEL_CARD.md` for protocols and caveats.")
+
+if __name__ == "__main__":
+    app.launch()

pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "evidence-graph-reranker"
+version = "0.1.0"
+description = "Training-free query-conditioned evidence subset selection using fixed directed article-title links"
+readme = "PACKAGE_README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+keywords = ["rag", "reranking", "multihop", "evidence selection", "huggingface"]
+dependencies = ["numpy>=1.23"]
+
+[project.optional-dependencies]
+neural = ["sentence-transformers>=3.0", "torch>=2.1"]
+demo = ["gradio>=4.0", "sentence-transformers>=3.0", "torch>=2.1"]
+test = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+include = ["evidence_graph_reranker*"]

requirements.txt

@@ -0,0 +1,4 @@
+numpy>=1.23
+torch>=2.1
+sentence-transformers>=3.0
+gradio>=4.0