TreeRAG: Hierarchical Agentic Retrieval over Genomics Quality Management Documents

Navigate a document collection, retain evidence across documents, and revisit unexplored branches when the evidence is incomplete.

TreeRAG studies retrieval over native folder, document, section, and passage hierarchies. An open-weight LLM scores branches and reads evidence; a bounded controller manages memory, local reading, and a corpus-wide search frontier.

Overview · Getting started · Reproduction · Custom corpora · Configuration · Layout · Citation

Overview

Large informational collections contain answers distributed across sections, tables, and documents. TreeRAG builds recursive summaries while retaining the collection's existing structure, then searches that hierarchy at query time.

1. Rank and descend. Score visible branches using their summaries and previews.
2. Read and retain. Gather passages and choose passage, section, or document scope.
3. Check evidence. Assess whether retained material covers the question.
4. Recover. Visit a promising unexplored branch when more evidence is needed.
5. Answer with references. Synthesize the retained evidence within search budgets.

The archived evaluated implementation and the modular package remain separately versioned; their results and safeguards are not interchangeable.

Signal boundary. TreeRAG does not use a dense-vector index to select evidence. Its controller also uses lexical frontier seeding. The archived evaluated runner contains optional embedding-based ordering of names in over-wide previews, with a lexical fallback; the retained logs do not establish whether embedding calls succeeded. The modular package disables that auxiliary embedding step by default. Consequently, the archived experiment should not be described as strictly agent-only or proven vector-free. See architecture and implementation provenance.

Getting started

Install and test without a model

Use Python 3.11 or 3.12 and uv:

git clone https://github.com/asharma391/tree-rag.git
cd tree-rag
uv sync --frozen
uv run pytest -q
uv run treerag --help

The default installation includes query, test, and saved-result evaluation dependencies. Document-building dependencies are installed only with --extra build. The synthetic tests require neither private data nor a model endpoint. The committed public tree is approximately 29 MB. Source installation without uv:

python -m pip install -e '.[build,test]'

Query the committed tree

Configure an Ollama-compatible endpoint with the chosen model available. The reported model is gpt-oss:120b, which requires substantial compute; an existing approved remote deployment is suitable. A different model is an unmeasured setting.

export TREERAG_OLLAMA_URL=http://127.0.0.1:11434
export TREERAG_MODEL=gpt-oss:120b
uv run treerag "Which developments are compared across multiple reports?" \
  --tree data/multihop_rag_demo/corpus_tree.json --mode thorough

The CLI emits JSON containing the answer, source references, runtime, model calls, and mode. For progress during a query, use:

uv run ./scripts/query_single_question.sh "Your question"

See remote compute for persistent sessions and a generic SSH tunnel. No institutional account is needed to use the public corpus.

Reproducing the public study

Recompute saved-result metrics without model calls

The frozen question sample, answers, full TreeRAG report, and pinned official evaluator are included. Follow the exact command in the experiment guide. Every new evaluation writes a new output; released results remain unchanged.

Regenerate answers with evaluated-v0

export TREERAG_OLLAMA_URL=http://127.0.0.1:11434
export TREERAG_MODEL=gpt-oss:120b
uv run --extra build ./scripts/run_multihop_benchmark.sh

This runs the archived controller with corrected missing-only resume scheduling on the frozen 200-question sample and creates a timestamped report. It requires many model calls. It does not run all 2,556 questions. The modular CLI and archived benchmark are distinct implementations; the reported results belong to evaluated-v0.

Rebuild the public hierarchy

export TREERAG_CACHE_DIR="$PWD/work/public-tree-$(date -u +%Y%m%dT%H%M%SZ)"
uv run --extra build ./scripts/build_tree.sh

This materializes the public articles, then parses and summarizes them. The committed demonstration tree stays unchanged. The recorded full build required 19,976 model calls and 49,401 seconds. Preserve the frozen sample when downloading data; see the experiment guide for dataset provenance and rerun limitations.

Custom corpora

The release builder accepts a document directory and a separate cache location:

export TREERAG_DOCS_ROOT=/absolute/path/to/documents
export TREERAG_CACHE_DIR=/absolute/path/to/new/tree-cache
uv run --extra build python scripts/build_tree.py
uv run treerag "Your question" --tree "$TREERAG_CACHE_DIR/corpus_tree.json"

Keep original folder organization where it conveys useful structure. Run the corpus, cache, inference endpoint, and outputs within the approved data boundary. Never mix restricted and public caches. Data policy

Configuration

Setting	Purpose
TREERAG_OLLAMA_URL	Model endpoint; defaults to http://127.0.0.1:11434
TREERAG_MODEL	Routing and answer model; defaults to gpt-oss:120b
TREERAG_TREE_PATH	Tree path for the modular package
--mode thorough	Primary modular configuration with larger budgets
--mode quick	Lower-budget modular sensitivity setting
TREERAG_BENCHMARK_REPORT	Explicit archived-run checkpoint to resume

See configuration source, example environment, and presets. Time budgets are cooperative checks between requests, not preemptive wall-clock deadlines.

Repository layout

src/treerag/               modular controller, typed configuration, CLI
scripts/                   query, build, and benchmark entry points
configs/                   quick and thorough environment presets
data/multihop_rag_demo/    committed public hierarchy
experiments/multihop_rag/ public sample, controls, outputs, official evaluator
reference/evaluated_v0/   archived evaluated source and provenance hashes
docs/                      architecture and deployment guidance
tests/                     offline unit, traversal, and artifact tests

Next steps

Current research gaps include human evaluation and inter-rater agreement, equal-budget comparisons, an evaluated embedding-disabled variant, and broader public benchmark coverage. These are open work, not completed results.

Acknowledgements

The project grew from work in Genome Informatics at the Ontario Institute for Cancer Research by Arjun Sharma, Jochen Weile, Kayla Marsh, and Mélanie Courtot, with support from the University of Toronto Data Sciences Institute and the Government of Ontario.

Source code is GPL-3.0-or-later. MultiHop-RAG data is ODC-BY; see the dataset card.

Citation

Software metadata is in CITATION.cff. A publication citation will be added once available; the unpublished manuscript is not included here.