pyragx 0.0.1

Website · Documentation · PyPI · Paper (coming soon)

ragX is an open-source, training-free agentic retrieval framework. On millions of documents, single-shot RAG misses the evidence a question does not name. ragX names it: an agent ranks and reads passages, a chain of sub-questions resolves each hop, and one call answers with exact path:line citations. It works with any LLM.

from ragx import RagX

rag = RagX("./docs")
answer = rag.ask("Who founded the university the author of Harbor Light attended?")

print(answer.text)      # Thomas Wren
print(answer.sources)   # ['ashford_university.md:1-5', 'thomas_wren.md:1-5']

News

• 2026-10-20 · ragX 0.0.1 is on PyPI: pip install pyragx. All seven variants of the paper's method, BM25 and dense, fused and reranked ranking, a command line and an OpenAI-compatible server.
• 2026-10-20 · The website and the documentation are live.
• Coming soon · The paper, ragX: Agentic Retrieval at Scale, on arXiv.

Why ragX

A question such as "Who is the spouse of the actor who plays Jarvis in Iron Man?" names Iron Man and Jarvis, but not Paul Bettany, whose article holds the answer. On all of Wikipedia that passage ranks 146,602th for the question itself, so single-shot retrieval cannot reach it. As a corpus grows, single-shot retrieval loses such unnamed evidence about four times faster than named evidence.

ragX reaches it through two separate routes, then composes once:

1. Forage loop. An agent RANKs the corpus and READs passages for up to ten turns. It writes each query after reading, so a query can name what the question never did.
2. Slot chain. The question becomes up to four sub-questions with #N slots; each hop is retrieved with the earlier answers filled in.
3. Compose. One call answers over the read passages, the hop passages, the other surfaced ones and, in the full method, the question's own top 48.

Results

Benchmarked on nested samples of Wikipedia from 240K to 21M passages, with 27 language models on five QA datasets, against single-shot retrieval, ReAct, Self-Ask, IRCoT, DCI-Agent-Lite and Search-R1:

With BM25 alone, ragX beats every dense single-shot baseline at 21M passages. The paper is coming soon.

Install

pip install pyragx                 # ragx-lexical: BM25, no embedding index, no GPU
pip install "pyragx[dense]"        # every variant (dense, fused and reranked ranking)

The PyPI name is pyragx; you import ragx and run the ragx command.

Set a key for any provider (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, ...), point vllm: at your own server, or run a local Hugging Face model with pyragx[local].

Variants

rag = RagX("./docs", variant="ragx-rerank", model="openai:gpt-4o-mini")

Command line and server

ragx ask "Whom did the founder of Ashford University marry?" -c ./docs -v ragx-fused
ragx search "Ashford University founder" -c ./docs        # retrieval only, no LLM
ragx serve ./docs --port 8000                              # OpenAI-compatible /v1/chat/completions

Documentation

The full documentation is at ctrl-gaurav.github.io/ragX/docs: how ragX works, variants, models and providers, the Python API and every configuration option.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md.

Citation

The paper, ragX: Agentic Retrieval at Scale, is coming soon. Until then, please cite the software:

@software{srivastava2026ragx,
  author  = {Srivastava, Gaurav},
  title   = {ragX: Agentic Retrieval at Scale},
  year    = {2026},
  url     = {https://github.com/ctrl-gaurav/ragX},
  version = {0.0.1}
}

License

Apache 2.0