feat: refactor code structure for improved readability and maintainability

.gitattributes

@@ -33,3 +33,16 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/00_cover.png filter=lfs diff=lfs merge=lfs -text
+assets/01_hero_topk_vs_spectrag.gif filter=lfs diff=lfs merge=lfs -text
+assets/02_six_signals_graph_build.gif filter=lfs diff=lfs merge=lfs -text
+assets/03_spectral_coordinates.gif filter=lfs diff=lfs merge=lfs -text
+assets/04_spectral_diffusion.gif filter=lfs diff=lfs merge=lfs -text
+assets/05_token_budget_selection.gif filter=lfs diff=lfs merge=lfs -text
+assets/06_by_the_numbers.gif filter=lfs diff=lfs merge=lfs -text
+assets/chart_01_index_footprint.png filter=lfs diff=lfs merge=lfs -text
+assets/chart_02_recall_by_depth.png filter=lfs diff=lfs merge=lfs -text
+assets/chart_03_accuracy_by_question_type.png filter=lfs diff=lfs merge=lfs -text
+assets/chart_04_diversity_win_rate.png filter=lfs diff=lfs merge=lfs -text
+assets/online-offline-main-pipeline.png filter=lfs diff=lfs merge=lfs -text
+assets/SpectRAG_explainer_voiceover.mp4 filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,12 +1,47 @@
 ---
 title: SpectRAG
-emoji: 🏃
+emoji: 🐙
 colorFrom: blue
-colorTo: gray
+colorTo: indigo
 sdk: static
-pinned: false
+pinned: true
 license: mit
-short_description: Spectral graph-augmented retrieval for RAG systems
+short_description: Weighted chunk graphs for multi-hop RAG context selection
+tags:
+  - rag
+  - retrieval-augmented-generation
+  - graph
+  - spectral-graph-theory
+  - multi-hop-qa
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# SpectRAG: Weighted Chunk Graphs for Token-Budgeted Context Selection in Multi-Hop RAG
+
+An interactive, visual walkthrough of **SpectRAG**. SpectRAG is a retrieval framework that replaces independent top-k ranking with **context-set selection** over a weighted chunk graph and its Laplacian spectrum.
+
+- 📄 Paper: [arXiv:2610.36991](https://arxiv.org/abs/2610.36991)
+- 🤗 Paper page: [hf.co/papers/2610.36991](https://huggingface.co/papers/2610.36991)
+- 💻 Code (MIT): [github.com/SightAndCite/SpectRAG](https://github.com/SightAndCite/SpectRAG)
+
+## Highlights (MultiHopRAG & UltraDomain)
+
+| | |
+|---|---|
+| Overall gold-evidence recall | **91.8%** (next best 76.1%) |
+| Exact match on inference questions | **95.1%** |
+| Index size vs LightRAG | **46 MB vs 274 MB** (~6× smaller) |
+| Diversity win rate (LLM judge) | **> 50% vs every baseline**, up to 72.5% |
+
+## Citation
+
+```bibtex
+@misc{sahinoglu2026spectragweightedchunkgraphs,
+      title={SpectRAG: Weighted Chunk Graphs for Token-Budgeted Context Selection in Multi-Hop Retrieval-Augmented Generation},
+      author={Zafer Sahinoglu and Abdulazeez Mohammed and Buse Yaren Kazangirler and Cahit Berkay Kazangirler},
+      year={2026},
+      eprint={2610.36991},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2610.36991},
+}
+```

assets/SpectRAG_explainer_voiceover.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aa2ddddb1d5c3ace8b8190e2aca9f22b9a33c18bdd43b045de38cc9c80b323b8
+size 9709194

assets/SpectRAG_explainer_voiceover.vtt

@@ -0,0 +1,126 @@
+WEBVTT
+
+1
+00:00:00.350 --> 00:00:01.409
+Meet SpectRAG.
+
+2
+00:00:01.409 --> 00:00:05.114
+Stop retrieving chunks, and start retrieving context.
+
+3
+00:00:06.014 --> 00:00:07.622
+Ask a multi-hop question,
+
+4
+00:00:07.622 --> 00:00:12.044
+and classic top-k retrieval grabs six near-duplicate chunks from one cluster.
+
+5
+00:00:12.044 --> 00:00:16.063
+It finds only one of the three pieces of evidence.
+
+6
+00:00:16.063 --> 00:00:18.475
+SpectRAG seeds, expands over the graph,
+
+7
+00:00:18.475 --> 00:00:21.690
+diffuses relevance, and selects a diverse, connected set.
+
+8
+00:00:21.690 --> 00:00:23.298
+Three out of three.
+
+9
+00:00:24.198 --> 00:00:27.605
+Offline, every document is split into chunks.
+
+10
+00:00:27.605 --> 00:00:31.497
+Then the chunks are connected by six signals:
+
+11
+00:00:31.497 --> 00:00:33.444
+adjacency, sections, semantic similarity,
+
+12
+00:00:33.444 --> 00:00:36.363
+shared entities, utility questions, and citations.
+
+13
+00:00:36.363 --> 00:00:39.770
+Together, they form one weighted chunk graph.
+
+14
+00:00:40.670 --> 00:00:43.093
+Now every chunk has two geometries.
+
+15
+00:00:43.093 --> 00:00:45.920
+Its embedding captures what the chunk says.
+
+16
+00:00:45.920 --> 00:00:47.132
+Its spectral coordinates,
+
+17
+00:00:47.132 --> 00:00:50.362
+from the graph Laplacian, capture where it lives.
+
+18
+00:00:50.362 --> 00:00:52.786
+Communities pull together, whatever their wording.
+
+19
+00:00:54.170 --> 00:00:56.826
+At query time, relevance diffuses along the graph.
+
+20
+00:00:56.826 --> 00:01:00.147
+Bridge chunks that never matched the query still light up.
+
+21
+00:01:00.147 --> 00:01:02.804
+That is how SpectRAG finds the missing link.
+
+22
+00:01:06.170 --> 00:01:08.187
+Instead of a fixed top-k,
+
+23
+00:01:08.187 --> 00:01:10.205
+SpectRAG fills a twelve-thousand-token budget.
+
+24
+00:01:10.205 --> 00:01:14.644
+A protected core comes first, then coverage-aware picks with no redundancy,
+
+25
+00:01:14.644 --> 00:01:18.276
+and finally a backfill, so no space is wasted.
+
+26
+00:01:20.170 --> 00:01:21.136
+The result:
+
+27
+00:01:21.136 --> 00:01:25.966
+91.8 percent gold-evidence recall, 95 percent accuracy on inference questions,
+
+28
+00:01:25.966 --> 00:01:29.830
+and an index six times smaller than LightRAG.
+
+29
+00:01:30.730 --> 00:01:31.097
+SpectRAG.
+
+30
+00:01:31.097 --> 00:01:34.776
+Retrieve a context set, not a pile of similar chunks.
+
+31
+00:01:34.776 --> 00:01:37.350
+Read the paper, and try the code.
+

index.html

@@ -1,19 +1,179 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SpectRAG · Retrieve Context, Not Chunks</title>
+<meta name="description" content="SpectRAG: weighted chunk graphs and spectral diffusion for token-budgeted context selection in multi-hop RAG.">
+<meta property="og:title" content="SpectRAG · Retrieve context, not chunks">
+<meta property="og:image" content="assets/00_cover.png">
+<style>
+  :root {
+    --bg: #050B1A; --panel: #0A1630; --edge: #1C3466; --text: #E8F1FF; --muted: #93A5C8;
+    --cyan: #4FD1FF; --green: #3DDC97; --yellow: #FFD166; --radius: 14px;
+  }
+  * { box-sizing: border-box; }
+  html { scroll-behavior: smooth; }
+  body { margin: 0; background: var(--bg); color: var(--text);
+         font: 17px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, Roboto, sans-serif; }
+  main { max-width: 980px; margin: 0 auto; padding: 0 16px 80px; }
+  a { color: var(--cyan); }
+  img, video { display: block; width: 100%; height: auto; border-radius: var(--radius);
+               border: 1px solid var(--edge); background: #000; }
+  header { text-align: center; padding: 56px 0 28px; }
+  .eyebrow { color: var(--cyan); letter-spacing: .14em; text-transform: uppercase; font-size: 13px; font-weight: 700; }
+  h1 { font-size: clamp(34px, 6vw, 58px); line-height: 1.08; margin: 10px 0 14px; letter-spacing: -.02em; }
+  h1 span { color: var(--cyan); }
+  .lede { color: var(--muted); font-size: clamp(16px, 2.2vw, 20px); max-width: 720px; margin: 0 auto; }
+  .authors { color: var(--muted); font-size: 14px; margin-top: 14px; }
+  .btns { display: flex; gap: 10px; justify-content: center; flex-wrap: wrap; margin-top: 24px; }
+  .btn { display: inline-flex; align-items: center; gap: 8px; padding: 10px 18px; border-radius: 999px;
+         border: 1px solid var(--edge); background: var(--panel); color: var(--text); text-decoration: none;
+         font-weight: 600; font-size: 15px; transition: border-color .15s, transform .15s; }
+  .btn:hover { border-color: var(--cyan); transform: translateY(-1px); }
+  .btn.primary { background: var(--cyan); color: var(--bg); border-color: var(--cyan); }
+  section { margin-top: 64px; }
+  h2 { font-size: clamp(24px, 3.4vw, 32px); margin: 0 0 6px; letter-spacing: -.01em; }
+  .sub { color: var(--muted); margin: 0 0 20px; }
+  figure { margin: 0; }
+  figcaption { color: var(--muted); font-size: 14px; text-align: center; margin-top: 10px; }
+  .quote { border-left: 3px solid var(--cyan); padding: 4px 0 4px 18px; font-size: 20px; margin: 28px 0 0; }
+  .steps { display: grid; gap: 40px; }
+  .step { display: grid; grid-template-columns: 1fr 1.35fr; gap: 24px; align-items: center; }
+  .step:nth-child(even) .txt { order: 2; }
+  .num { display: inline-grid; place-items: center; width: 30px; height: 30px; border-radius: 50%;
+         background: var(--cyan); color: var(--bg); font-weight: 800; font-size: 15px; margin-bottom: 8px; }
+  .step h3 { margin: 0 0 6px; font-size: 21px; }
+  .step p { margin: 0; color: var(--muted); }
+  .stats { display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; margin-bottom: 24px; }
+  .stat { background: var(--panel); border: 1px solid var(--edge); border-radius: var(--radius); padding: 16px; }
+  .stat b { display: block; font-size: 30px; line-height: 1.1; color: var(--cyan); }
+  .stat span { color: var(--muted); font-size: 14px; }
+  .charts { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
+  .note { background: var(--panel); border: 1px solid var(--edge); border-radius: var(--radius); padding: 18px 20px; }
+  .note ul { margin: 6px 0 0; padding-left: 20px; color: var(--muted); }
+  pre { background: var(--panel); border: 1px solid var(--edge); border-radius: var(--radius); padding: 16px;
+        overflow-x: auto; font-size: 13px; line-height: 1.5; margin: 0; }
+  .copy { margin-top: 10px; }
+  footer { margin-top: 72px; text-align: center; color: var(--muted); font-size: 14px; }
+  @media (max-width: 760px) {
+    .step { grid-template-columns: 1fr; }
+    .step:nth-child(even) .txt { order: 0; }
+    .stats { grid-template-columns: 1fr 1fr; }
+    .charts { grid-template-columns: 1fr; }
+  }
+</style>
+</head>
+<body>
+<main>
+  <header>
+    <div class="eyebrow">Multi-hop RAG · arXiv 2610.36991</div>
+    <h1>Stop retrieving chunks.<br><span>Start retrieving context.</span></h1>
+    <p class="lede">SpectRAG builds a weighted chunk graph from six evidence signals and uses its Laplacian spectrum to select a context set that is <b>relevant, diverse and connected</b>, all under a fixed token budget.</p>
+    <p class="authors">Zafer Sahinoglu · Abdulazeez Mohammed · Buse Yaren Kazangirler · Cahit Berkay Kazangirler</p>
+    <div class="btns">
+      <a class="btn primary" href="https://arxiv.org/abs/2610.36991" target="_blank" rel="noopener">📄 Paper</a>
+      <a class="btn" href="https://github.com/SightAndCite/SpectRAG" target="_blank" rel="noopener">💻 Code</a>
+      <a class="btn" href="https://huggingface.co/papers/2610.36991" target="_blank" rel="noopener">🤗 Paper page</a>
+      <a class="btn" href="#video">🎬 Watch the explainer</a>
+    </div>
+  </header>
+
+  <figure>
+    <img src="assets/01_hero_topk_vs_spectrag.gif" alt="Animation: classic top-k retrieval picks six near-duplicate chunks and finds 1 of 3 gold passages; SpectRAG seeds, expands, diffuses and selects a diverse set that finds 3 of 3.">
+    <figcaption>Same question, same 6-chunk budget. Top-k finds 1/3 of the gold evidence; SpectRAG finds 3/3. (Illustrative toy corpus.)</figcaption>
+  </figure>
+
+  <p class="quote">Top-k ranks chunks one at a time. Multi-hop questions need a <b>set</b> of chunks that works together as evidence.</p>
+
+  <section id="how">
+    <h2>How it works</h2>
+    <p class="sub">An offline pass builds the graph once; a five-stage online pass selects context for each query.</p>
+    <div class="steps">
+      <div class="step">
+        <div class="txt"><div class="num">1</div><h3>A chunk graph built from six signals</h3>
+          <p>Semantic similarity, document adjacency, section hierarchy, shared entities, LLM-generated utility questions and citations are fused into one weighted edge.</p></div>
+        <img src="assets/02_six_signals_graph_build.gif" alt="Animation: chunks from five documents are connected signal by signal into a weighted chunk graph." loading="lazy">
+      </div>
+      <div class="step">
+        <div class="txt"><div class="num">2</div><h3>Two geometries for every chunk</h3>
+          <p>The dense embedding captures what a chunk says. The 32-d spectral coordinate from the normalized Laplacian captures where it lives in the corpus.</p></div>
+        <img src="assets/03_spectral_coordinates.gif" alt="Animation: points morph from an overlapping embedding layout into well-separated spectral communities." loading="lazy">
+      </div>
+      <div class="step">
+        <div class="txt"><div class="num">3</div><h3>Relevance diffuses along the graph</h3>
+          <p>Hybrid seeds (dense + BM25 + utility questions) are expanded two hops and re-scored with spectral closeness and Personalized PageRank, so bridge evidence surfaces.</p></div>
+        <img src="assets/04_spectral_diffusion.gif" alt="Animation: relevance heat spreads from three seed nodes across a graph." loading="lazy">
+      </div>
+      <div class="step">
+        <div class="txt"><div class="num">4</div><h3>Token-budgeted selection</h3>
+          <p>A protected core, a coverage-aware tail with a precision floor, and a backfill fill a ~12k-token window, adapting to 10–15 chunks per query.</p></div>
+        <img src="assets/05_token_budget_selection.gif" alt="Animation: candidate chunks fill a 12,000-token context window; redundant and low-precision chunks are skipped." loading="lazy">
+      </div>
+    </div>
+    <figure style="margin-top:40px">
+      <img src="assets/online-offline-main-pipeline.png" alt="Full SpectRAG pipeline diagram: offline indexing and online query-time retrieval." loading="lazy">
+      <figcaption>The full pipeline: offline corpus indexing and online query-time retrieval.</figcaption>
+    </figure>
+  </section>
+
+  <section id="video">
+    <h2>Explainer video</h2>
+    <p class="sub">A 98-second narrated walkthrough. Captions are available in the player.</p>
+    <video controls preload="metadata" poster="assets/00_cover.png">
+      <source src="assets/SpectRAG_explainer_voiceover.mp4" type="video/mp4">
+      <track kind="captions" src="assets/SpectRAG_explainer_voiceover.vtt" srclang="en" label="English" default>
+    </video>
+  </section>
+
+  <section id="results">
+    <h2>Results</h2>
+    <p class="sub">MultiHopRAG (2,556 gold-answer questions) and four UltraDomain corpora, against NaiveRAG, Hybrid, HyDE and LightRAG. Every system uses the same generator.</p>
+    <div class="stats">
+      <div class="stat"><b>91.8%</b><span>overall gold-evidence recall (next best 76.1%)</span></div>
+      <div class="stat"><b>95.1%</b><span>exact match on inference questions</span></div>
+      <div class="stat"><b>~6×</b><span>smaller index than LightRAG (46 vs 274 MB)</span></div>
+      <div class="stat"><b>&gt;50%</b><span>diversity win rate vs every baseline</span></div>
+    </div>
+    <div class="charts">
+      <img src="assets/chart_02_recall_by_depth.png" alt="Line chart: recall at 2, 5, 10 and overall for five systems; SpectRAG reaches 91.8% overall." loading="lazy">
+      <img src="assets/chart_01_index_footprint.png" alt="Bar charts: index size 46 MB vs 274 MB and node counts per corpus, SpectRAG vs LightRAG." loading="lazy">
+      <img src="assets/chart_03_accuracy_by_question_type.png" alt="Dot plot: exact match by question type; SpectRAG leads on inference at 95.1%." loading="lazy">
+      <img src="assets/chart_04_diversity_win_rate.png" alt="Bar chart: SpectRAG diversity win rate above 50% against all four baselines in both configurations." loading="lazy">
+    </div>
+    <div class="note" style="margin-top:20px">
+      <b>Honest trade-offs</b>
+      <ul>
+        <li>Hybrid retrieval leads at the very top of the ranking (Recall@2, Recall@5, MRR); SpectRAG wins on breadth.</li>
+        <li>End-to-end accuracy gains are narrow (EM 71.2 vs 70.6 for the next best): better retrieval saturates with short multi-hop answers.</li>
+        <li>On unanswerable (null) questions SpectRAG is behind the vector baselines, and signal weights can need per-corpus tuning.</li>
+      </ul>
+    </div>
+  </section>
+
+  <section id="cite">
+    <h2>Citation</h2>
+<pre id="bib">@misc{sahinoglu2026spectragweightedchunkgraphs,
+      title={SpectRAG: Weighted Chunk Graphs for Token-Budgeted Context Selection in Multi-Hop Retrieval-Augmented Generation},
+      author={Zafer Sahinoglu and Abdulazeez Mohammed and Buse Yaren Kazangirler and Cahit Berkay Kazangirler},
+      year={2026},
+      eprint={2610.36991},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2610.36991},
+}</pre>
+    <button class="btn copy" type="button" id="copyBib">Copy BibTeX</button>
+  </section>
+
+  <footer>SpectRAG is open source under the MIT license · <a href="https://github.com/SightAndCite/SpectRAG">GitHub</a></footer>
+</main>
+<script>
+  document.getElementById('copyBib').addEventListener('click', async (e) => {
+    try { await navigator.clipboard.writeText(document.getElementById('bib').textContent);
+          e.target.textContent = 'Copied ✓'; }
+    catch { e.target.textContent = 'Select the text above to copy'; }
+    setTimeout(() => { e.target.textContent = 'Copy BibTeX'; }, 2000);
+  });
+</script>
+</body>
 </html>