README.md

metadata

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

• Week 1 — Repo scaffold + smoke test
• Week 1 — arXiv corpus ingestion (10/17 RL papers, 1,093 chunks)
• Week 1 — Baseline RAG (FAISS + bge-small + Gemini/Groq), smoke tested
• Week 2 — Eval harness + 30-question gold dataset
• Week 2 — Baseline RAG numbers (Recall@5 90%, Answer Correctness 37%)
• Week 2 — Hybrid BM25+FAISS retrieval via RRF (Answer Correctness 72%, +35 pp)
• Week 3 — Reranker (cross-encoder): +8.7 pp over v2 baseline
• Week 3 — Agentic planning loop: offline prerequisite-chain planner, 7 tests passing
• Week 3 — Full 17-paper corpus (1,789 chunks) + expanded prerequisite DAG (21 edges)
• Week 4 — Streamlit UI + HF Spaces deploy (Docker)
• 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

# 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