README.md

---
title: ResearchPath
emoji: 🗺️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit
short_description: Agentic RL reading-path planner with grounded Q&A
---

# ResearchPath

> An agentic research-onboarding companion. Give it a target paper and your background; it builds a personalized, dependency-ordered reading plan with grounded explanations.
>
> **Demo domain:** Reinforcement Learning. **Architecture:** domain-agnostic.

---

## The problem

Getting into a new research field is brutal. You open the SOTA paper, it assumes 8 prior concepts. You read those papers, they assume 5 more. Existing tools (Perplexity, Elicit, Consensus) retrieve papers but don't *plan* — they don't tell you what order to read things in *based on your specific background*.

## What ResearchPath does

Input:
- A target paper or topic (e.g., *"PPO"*)
- Your current background (e.g., *"basic supervised ML, calculus, no RL"*)

Output:
1. **Prerequisite reading plan** — a topologically-sorted reading list of foundational papers, with a "why this is next" justification grounded in the dependency chain
2. **Concept genealogy** — how each key concept evolved across the chain
3. **Notation glossary** — reconciles symbols across papers (X in paper A = θ in paper B)
4. **Grounded Q&A** — ask follow-ups, every claim cites a specific paper section
5. *(Stretch)* **Open problems surfacer** — clusters "Future Work" sections from recent papers in the subfield

## Why this is genuinely agentic (not RAG-with-extra-steps)

The reading-path builder is a real planning problem:

```
read(target_paper) → extract assumed prerequisites
  for each prerequisite:
    if user_knows(prereq): skip
    else: retrieve canonical paper for prereq → recurse
build dependency DAG → topologically sort → generate bridge explanations
```

Graph traversal + recursive retrieval + reasoning over user state. Not "embed query, return top-5 chunks."

---

## Evaluation

Eval is the differentiator. Every change ships with numbers.

**Gold dataset:** 30 hand-authored (question, expected source, key claim) triples across 10 canonical RL papers. Difficulty-stratified: 7 easy / 15 medium / 8 hard. Questions adapted from OpenAI Spinning Up, Sutton & Barto concepts, and paper-specific mechanism questions.

### v1 — 10-paper corpus (1,093 chunks)

| Metric | Baseline RAG | + Hybrid Retrieval |
|---|---|---|
| Retrieval Recall@5 | **90.0%** | **89.7%** |
| Citation Presence | **86.7%** | **86.2%** |
| Answer Correctness | **36.7%** | **72.4%** |
| Avg Latency (s) | **5.07** | **4.58** |
| RAG Tokens (in/out) | **33,498 / 7,000** | **31,439 / 6,905** |

*Hybrid BM25+FAISS via RRF fusion (n=29). Answer Correctness nearly doubled (+35.7 pp) with no latency regression — driven by hybrid correctly surfacing in-paper chunks that dense embeddings de-prioritized.*

### v2 — Full 17-paper corpus (1,789 chunks)

Corpus expanded to all 17 canonical RL papers (PER, PPO, SAC, IMPALA, MuZero, DreamerV3, Decision Transformer added). Prerequisite graph updated with 11 new edges.

| Metric | Baseline RAG | + Hybrid Retrieval | + Reranker |
|---|---|---|---|
| Retrieval Recall@5 | **84.0%** | pending | **83.3%** |
| Citation Presence | **80.0%** | pending | **83.3%** |
| Answer Correctness | **48.0%** | pending | **56.7%** |
| Avg Latency (s) | **4.63** | pending | **5.13** |
| RAG Tokens (in/out) | **27,027 / 6,336** | pending | **31,579 / 11,215** |

*v2 baseline n=25 (5 skipped, Groq 100k TPD hit). Reranker: BM25+FAISS+CrossEncoder, n=30. Hybrid v2 pending token reset. Reranker adds +8.7 pp over v2 baseline; larger corpus raises baseline from 37% → 48% even without retrieval improvements.*

---

## Stack

| Layer | Choice | Why |
|---|---|---|
| Planning LLM | Gemini 2.5 Flash Lite (free tier) | Strong reasoning, generous free quota |
| Fast LLM | Groq Llama 3.3 70B (free) | Fast inference for inner-loop retrieval |
| Embeddings | BAAI/bge-small-en-v1.5 | CPU-friendly, strong on academic text, free |
| Vector store | FAISS IndexFlatIP | Local, free, exact cosine, fast at ~5k chunks |
| Retrieval | BM25 + FAISS via RRF + CrossEncoder rerank | Three tiers, each measurably better |
| Agent framework | Static DAG + BFS + Kahn's topo sort | Deterministic planning, no LLM cost |
| UI | Streamlit | Demo-grade, ships fast |
| Eval | Custom harness + LLM-as-judge | Citation recall, answer correctness, latency |
| Deploy | Hugging Face Spaces | Free public URL |

---

## Status

- [x] Week 1 — Repo scaffold + smoke test
- [x] Week 1 — arXiv corpus ingestion (10/17 RL papers, 1,093 chunks)
- [x] Week 1 — Baseline RAG (FAISS + bge-small + Gemini/Groq), smoke tested
- [x] Week 2 — Eval harness + 30-question gold dataset
- [x] Week 2 — Baseline RAG numbers (Recall@5 90%, Answer Correctness 37%)
- [x] Week 2 — Hybrid BM25+FAISS retrieval via RRF (Answer Correctness 72%, +35 pp)
- [x] Week 3 — Reranker (cross-encoder): +8.7 pp over v2 baseline
- [x] Week 3 — Agentic planning loop: offline prerequisite-chain planner, 7 tests passing
- [x] Week 3 — Full 17-paper corpus (1,789 chunks) + expanded prerequisite DAG (21 edges)
- [x] Week 4 — Streamlit UI + HF Spaces deploy (Docker)
- [x] Week 4 — Tier 1 corpus expansion: Sutton & Barto, RLHF Book, CS224R, 5 web tutorials → **5,531 chunks**
- [ ] Week 4 — Hybrid v2 eval (pending Groq token reset), ablation table complete, demo video

---

## Local development

```powershell
# 1. Install uv (one-time): https://astral.sh/uv
# 2. Sync dependencies
uv sync

# 3. Set up env
copy .env.example .env
# Fill in GEMINI_API_KEY and GROQ_API_KEY in .env

# 4. Run smoke test
uv run python scripts/smoke_test.py

# 5. Build corpus — three sources (one-time, ~25 min total)
# 5a. Research papers (17 arXiv PDFs)
uv run python scripts/fetch_corpus.py
# 5b. Textbooks + course notes (Sutton & Barto, RLHF Book, CS224R)
uv run python scripts/fetch_pdfs.py
# 5c. Web tutorials (Spinning Up, Lilian Weng, HF blog)
uv run python scripts/fetch_web_sources.py
# 5d. Parse all sources → embed → FAISS index (5,531 chunks)
uv run python scripts/parse_corpus.py
uv run python scripts/build_index.py

# 6. Ask a question
uv run python scripts/ask.py "What is the key idea behind PPO?"
uv run python scripts/ask.py --hybrid --rerank "How does Rainbow combine Double DQN and PER?"

# 7. Get a reading plan
uv run python scripts/plan.py --target PPO
uv run python scripts/plan.py --target Rainbow --known DQN

# 8. Run the full eval
uv run python scripts/run_eval.py --groq --hybrid
```