PACKAGE_README.md

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

pip install -e '.[neural]'

Quick start

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.