spectrag 0.1.1

Spectral graph-augmented retrieval with token-budgeted context selection for multi-hop RAG

Documentation · Installation · Quick start · How it works · Graph view · Configuration · Benchmark · Citation

A readable, tested Python implementation of the paper SpectRAG: Weighted Chunk Graphs for Token-Budgeted Context Selection in Multi-Hop Retrieval-Augmented Generation (Sahinoglu et al., arXiv:2610.36991, PDF).

📖 Documentation: aion7891.github.io/Spect-RAG covers installation, the quick start, architecture, configuration, tuning, API reference, benchmarks and FAQ, plus interactive explainers of the method.

Highlights

Installation

pip install spectrag              # core (numpy only)
pip install "spectrag[all]"       # every extra

The latest code from main: pip install "git+https://github.com/aion7891/Spect-RAG.git".

From a clone (for development):

git clone https://github.com/aion7891/Spect-RAG.git && cd Spect-RAG
pip install -e ".[all,dev]"        # or: uv sync --all-extras

Real semantic embeddings and LLM answers use a local Ollama server: ollama pull nomic-embed-text (the paper's embedding model) and, for answers, e.g. ollama pull gemma3:4b. Without Ollama, SpectRAG uses an offline hashing embedder.

Python 3.10–3.14 are tested. There is no upper version limit; Python 3.15 is waiting for a numpy release that supports it.

Quick start

python quickstart.py

quickstart.py needs no arguments. It ingests the sample documents in examples/docs/, builds the index, and prints the context for two questions. The documents, questions and every setting are at the top of the file; set USE_OLLAMA = True for nomic embeddings and LLM answers.

Python

from spectrag import SpectRAGIngestion, SpectRAGRetrieval

# Offline, once per document set: chunk, embed, build the graph, spectral coordinates
SpectRAGIngestion("my_index").ingest("examples/docs")      # a file or a folder (.txt .md .pdf)

# Online, per question
search = SpectRAGRetrieval("my_index")
result = search.search("Which company did the co-founder of Aurora Labs join after leaving?")
print(result["context"])                # text for your LLM, grouped by source document
for chunk in result["chunks"]:          # ranked sources with their scores
    print(chunk["rank"], chunk["doc_id"], round(chunk["score"], 3), chunk["reason"])

# Optional: an answer from any LLM (any function prompt -> text)
from spectrag.utils.llm import ollama_llm
print(search.answer("Which company did the co-founder of Aurora Labs join?", ollama_llm("gemma3:4b"))["answer"])

Documents can also come from memory: SpectRAGIngestion("my_index").ingest_documents([{"doc_id": "a", "text": "..."}]).

Command line

spectrag ingest examples/docs --index my_index --set chunk_tokens=256 --set overlap_tokens=64
spectrag search "Where is Helios Energy based?" --index my_index --budget 2000
spectrag answer "Where is Helios Energy based?" --index my_index --model gemma3:4b
spectrag graph --index my_index --out graph.html --question "Where is Helios Energy based?"
spectrag info --index my_index

--set key=value changes any setting (values are read as JSON); -v prints progress.

How it works

Offline: SpectRAGIngestion (once per document set)

Online: SpectRAGRetrieval (per question)

w_{ij} = \sum_{r} \alpha_r \, w^{(r)}_{ij}

L_{sym} = I - D^{-1/2} \, W \, D^{-1/2}

s^{(t+1)} = \beta \, r + (1-\beta)\, \tilde{A}\, s^{(t)}, \qquad
\text{score} = (1-\alpha)\,\text{relevance} + \alpha\,\text{proximity}

U(c \mid C) = a\, s_c + b\,\text{Prox}(c) + c\,\text{ClusterGain}(c, C) + d\,\text{DocGain}(c, C) - \lambda\,\text{Red}(c, C),
\qquad c^{*} = \arg\max_{c} \frac{U(c \mid C)}{\ell(c)^{\rho}}, \quad \sum_{c \in C} \ell(c) \le B

Every place where the paper leaves a detail open, and what this code chose, is listed in docs/DESIGN.md (D1–D64).

Graph view

spectrag graph (or spectrag.utils.graph_view.save_graph_view) writes one self-contained HTML file, similar to Figure 5 of the paper. Chunks are drawn as nodes, starting from their spectral coordinates, and edges are coloured by their strongest signal. For a question it shows the retrieval path: seeds, chunks reached by expansion, and the selected context. Hover for a chunk's text, click to highlight its neighbours, scroll to zoom, drag to pan, and hide signals with the checkboxes. It needs no internet. Example: examples/graph_view.html (download and open it in a browser).

Configuration

Settings are a plain dict. Pass changes to SpectRAGIngestion(dir, settings), SpectRAGRetrieval(dir, settings), search(q, settings=...), or --set on the CLI. Every value is checked: a typo gets "did you mean …?", a bad value says which range is allowed. Source says whether the default comes from the paper or was chosen because the paper gives no value.

Tuning

from spectrag import SpectRAGIngestion, SpectRAGRetrieval
from spectrag.utils.evaluation import load_questions
from spectrag.utils.tuning import tune

SpectRAGIngestion("eval_index").ingest("examples/eval/docs")     # the documents the questions are about
search = SpectRAGRetrieval("eval_index")
questions = load_questions("examples/eval/questions.json")   # [{"question", "evidence": [...]}, ...]
grid = {"alpha": [0.1, 0.3, 0.5], "selector": ["spectrag", "protected_mmr"], "edge_threshold": [0.05, 0.1]}
results = tune(search, questions, grid, objective="recall", budget=4000, trials=10)
print(results[0])                                            # best settings and their scores

Graph settings (edge_threshold, graph_k, edge_weights, spectral_dims, n_clusters) are applied by search.rebuild_graph({...}) from the saved signals, so nothing is embedded again.

Your own models

Errors and logging

All errors raised on purpose subclass spectrag.SpectRAGError and the matching built-in: SettingsError (ValueError), UnknownSettingError (KeyError), IndexError_ (FileNotFoundError), EmbedderError (ConnectionError), DocumentError (ValueError), DocumentNotFoundError (FileNotFoundError), MissingPackageError (ImportError) and LLMError (ConnectionError). The CLI prints them as one spectrag: error: ... line. SpectRAG is silent by default; spectrag.enable_logging() prints one timed line per pipeline step, and enable_logging("DEBUG") one line per query.

Benchmark: MultiHopRAG

Real runs on MultiHopRAG: 609 news articles, 7,807 chunks, nomic-embed-text embeddings, a 12,000-token budget for every method. 300 questions were used only for tuning; all numbers below are on the other 1,955 test questions.

• Tuned SpectRAG beats hybrid RAG: evidence recall +0.014 (95% CI +0.007 … +0.021), Recall@10 +0.017 (+0.009 … +0.025). Its largest gain is on inference questions (0.802 vs 0.757); on comparison questions hybrid stays slightly ahead, as in the paper.
• Removing graph expansion drops evidence recall to 0.705: the graph walk is where most of the extra evidence comes from.
• Smaller tests: HyDE (60 questions): 0.760, against dense 0.807. Answers with gemma3:4b (30 questions): exact match 0.400 tuned SpectRAG, 0.333 dense, 0.267 hybrid (one answer = 0.033). LightRAG on a 4-article subset could not be compared fairly (the subset fits in the budget), and it needed about 225 s of LLM time per 1,000-word article to index.

Reproduce (needs Ollama; quick mode takes minutes, SPECTRAG_BENCH_FULL=1 runs the full version):

python benchmarks/multihoprag_benchmark.py      # index, tune, evaluate, latency
python benchmarks/mhr_llm_steps.py hyde          # and: answers
python benchmarks/mhr_report.py                 # REPORT.md and the charts
python benchmarks/ann_benchmark.py              # exact vs FAISS vs HNSW

Full results, per-type tables, ablations and the method: benchmarks/results/multihoprag/REPORT.md and docs/PROGRESS.md. The dataset (ODC-BY) is stored in benchmarks/data/multihoprag/ with checksums.

Project layout

src/spectrag/
  ingestion.py, retrieval.py         the two main classes
  config.py, validation.py           settings and their checks
  errors.py, log.py, cli.py          exceptions, logging, the spectrag command
  utils/                             one small module per step: loader, tokens, sections, units,
                                     chunker, embedder, entities, references, questions, edges*,
                                     graph, graph_build, spectral, clusters, vector_index, bm25,
                                     seeding, expansion, diffusion, selection, selectors, prompt,
                                     llm, metrics, evaluation, tuning, graph_view, store
quickstart.py                        runs with no arguments
examples/                            sample documents, a 14-document evaluation set, demo scripts
benchmarks/                          MultiHopRAG and ANN benchmarks, their data and results
tests/                               unit, integration and equivalence tests
docs/                                the paper, DESIGN.md, PROGRESS.md, PRODUCTION_READINESS.md,
                                     DEVELOPMENT_LOG.md
tools/                               validate_release.py (release checks on a real index)

Every module is short (under about 150 lines), and functions do one thing.

Testing

pytest -q          # 300+ tests, under 10 seconds, offline

The tests cover every formula against hand-computed or closed-form values (BM25, RRF, PageRank, the heat kernel against scipy.linalg.expm, the sparse eigensolver against the dense one, the paper's metrics). The fast vectorised code is checked against simple loop versions on random cases, and the full pipeline runs end to end on real documents. Live Ollama tests run when Ollama is available (SPECTRAG_LIVE_LLM=1 for the LLM test). CI runs on every pull request and on main: Linux × Python 3.10 / 3.12 / 3.14 × minimal / all extras, one macOS job (Python 3.12, all extras), and a build that installs the wheel and runs the CLI. A release tag runs two quick Linux test jobs, because the merged commit has already passed the full set.

Before a release, python tools/validate_release.py re-checks the mathematics on the real MultiHopRAG index (eigenpairs, PageRank, BM25, every selector and proximity mode) and that the benchmark reproduces. The results are in the production-readiness report.

Development status

The hardening work in docs/PROGRESS.md (Phase 7) runs in small, reviewed steps. Green = done, yellow = in review, grey = next.

flowchart LR
    errors["0.1 errors.py: every error is a SpectRAGError"] --> embedder["0.2 embedder marker and fingerprint"]
    embedder --> replace["0.3 safe index replace"] --> escape["0.4 graph view escaping"]
    classDef done fill:#d4edda,stroke:#2e7d32,color:#1b5e20
    classDef doing fill:#fff3cd,stroke:#f9a825,color:#6d4c00
    classDef todo fill:#eceff1,stroke:#90a4ae,color:#455a64
    class errors doing
    class embedder,replace,escape todo

Limitations

• An index built with a functools.partial or a callable object as its embedder cannot be opened again, and an index opened with a different embedder of the same size is not detected. Both are fixed in step 0.2.
• The default settings are not tuned (see the benchmark). Tuning on your own validation questions is recommended.
• Entity extraction is rule-based unless you pass an entity_fn; utility questions need an LLM.
• Semantic edges and the dense eigensolver are O(n²) without the scale extra.
• The benchmark is a quick-mode run on one dataset; LightRAG was only compared on a tiny subset.
• On macOS with numpy 2.2 (Python 3.10), matrix products print spurious RuntimeWarnings; the results are correct.

More: docs/DESIGN.md (every decision), docs/PROGRESS.md (the upgrade, with measurements), CHANGELOG.md.

Citation

If you use SpectRAG, please cite the paper:

@article{sahinoglu2026spectrag,
  title   = {SpectRAG: Weighted Chunk Graphs for Token-Budgeted Context Selection in
             Multi-Hop Retrieval-Augmented Generation},
  author  = {Sahinoglu, Zafer and Mohammed, Abdulazeez and Kazangirler, Buse Yaren and
             Kazangirler, Cahit Berkay},
  journal = {arXiv preprint arXiv:2610.36991},
  year    = {2026}
}

License

MIT, see LICENSE. The MultiHopRAG data in benchmarks/data/ is ODC-BY (see its SOURCE.md).