Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,5 @@
+# Copy this file to `.env` and fill in your real keys.
+# `.env` is gitignored — your real keys will NEVER be pushed to GitHub.
+
+GEMINI_API_KEY=your-gemini-key-here
+GROQ_API_KEY=your-groq-key-here

.gitattributes

@@ -33,3 +33,4 @@ 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
+data/index.faiss filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,42 @@
+# Secrets
+.env
+.env.local
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual env (uv creates .venv)
+.venv/
+
+# Data — don't commit downloaded papers or raw eval results
+data/papers/
+data/eval_results*.json
+*.pkl
+
+# Pre-built index and corpus data are committed (needed for HF Spaces)
+# data/index.faiss, data/index.chunks.json, data/chunks.jsonl, data/gold_dataset.json
+
+# Notebooks
+.ipynb_checkpoints/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Claude Code personal settings (keys, permissions for this user only)
+.claude/settings.local.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build
+dist/
+build/

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,9 @@
+[
+  "tests/test_planning.py::test_known_set_truncates_chain",
+  "tests/test_planning.py::test_known_target_yields_empty_plan",
+  "tests/test_planning.py::test_rainbow_full_chain",
+  "tests/test_planning.py::test_render_text_contains_target_title",
+  "tests/test_planning.py::test_target_only_when_no_prereqs",
+  "tests/test_planning.py::test_topological_order_respects_edges",
+  "tests/test_planning.py::test_unknown_target_raises"
+]

.uv-cache/.gitignore

@@ -0,0 +1 @@
+*

.uv-cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["python", "-m", "streamlit", "run", "app.py", \
+     "--server.port=7860", \
+     "--server.address=0.0.0.0", \
+     "--server.headless=true"]

PROJECT_LOG.md

@@ -0,0 +1,347 @@
+# ResearchPath — Project Log
+
+A chronological record of decisions, work sessions, issues, and outcomes for the ResearchPath portfolio project.
+
+**Schema for each entry:**
+
+```
+## YYYY-MM-DD HH:MM — [type] Title
+**Type:** setup | decision | implementation | issue | resolution | discussion
+**Status:** in-progress | complete | blocked | reverted
+**Duration:** approx time
+
+### Context
+### Decisions
+### Actions taken
+### Issues encountered
+### Files touched
+### Outcome
+### Next
+```
+
+---
+
+## 2026-05-06 15:00 — [discussion] Project framing & scope
+
+**Type:** decision
+**Status:** complete
+**Duration:** ~30 min
+
+### Context
+Chetan (~2.5 YOE Data Scientist, Kyndryl + ex-Swiss Re, targeting top product companies) needed a portfolio project. Earlier "Agentic RAG Document Search" on his resume was copied from another GitHub — needed a genuine, defensible project.
+
+### Decisions
+- **Rejected** Underwriter Copilot (insurance) and Equity Research Analyst (SEC filings) — too generic / didn't match his preference for research-flavored work.
+- **Rejected** generic-RAG-over-papers framing — already exists (Perplexity, Elicit, Consensus); not enough differentiation.
+- **Committed**: **ResearchPath** — agentic research-onboarding companion. Killer feature: prerequisite-chain reading-path planning. Genuinely agentic (graph traversal + recursive retrieval + reasoning over user state), not RAG-with-extra-steps.
+- Demo domain: **Reinforcement Learning**. Architecture domain-agnostic.
+- Stack: Gemini 2.5 Flash Lite + Groq Llama 3.3 70B (free tiers), BAAI/bge-small-en embeddings, FAISS, LangGraph, Streamlit, RAGAS.
+- Eval-first methodology: gold dataset + ablation table is the differentiator from generic portfolios.
+
+### Outcome
+Project scope locked. 5-week plan in README.
+
+### Next
+Day 1 setup: env, deps, API keys, smoke test.
+
+---
+
+## 2026-05-06 15:20 — [setup] Day 1: Environment bootstrap
+
+**Type:** setup
+**Status:** complete
+**Duration:** ~45 min
+
+### Context
+Stand up local dev env so the agent work in Week 2+ has a working LLM substrate.
+
+### Decisions
+- Use `uv` for Python + dependency management (already installed on user's machine).
+- Default Gemini model: `gemini-2.5-flash-lite` (chosen after `gemini-2.5-flash` returned transient 503s during smoke test).
+
+### Actions taken
+- Scaffolded repo files: `.gitignore`, `.env.example`, `README.md`, `pyproject.toml`, `researchpath/__init__.py`, `researchpath/llm.py`, `scripts/smoke_test.py`.
+- `uv python install 3.12` → installed CPython 3.12.9.
+- `uv sync` → resolved 38 packages including `google-genai`, `groq`, `python-dotenv`, `rich`, `pytest`, `ruff`.
+- User created `.env` from template and pasted Gemini + Groq API keys.
+- `uv run python scripts/smoke_test.py` → both providers returned valid completions.
+
+### Issues encountered
+- **Unicode arrow `→` broke on Windows cp1252 codepage** when `rich` tried to write to stdout. Fix: removed the arrow from `scripts/smoke_test.py`. Also set `PYTHONIOENCODING=utf-8` for the run.
+- **Gemini 2.5 Flash returned 503 UNAVAILABLE (transient overload)** despite a valid key. Fix: switched default model in `researchpath/llm.py` from `gemini-2.5-flash` to `gemini-2.5-flash-lite`.
+
+### Files touched
+- Created: `.gitignore`, `.env.example`, `README.md`, `pyproject.toml`, `researchpath/__init__.py`, `researchpath/llm.py`, `scripts/smoke_test.py`, `.claude/settings.local.json`, `PROJECT_LOG.md`.
+- User-created (gitignored): `.env`.
+
+### Outcome
+Both Gemini and Groq APIs verified end-to-end. `.claude/settings.local.json` grants Bash + PowerShell auto-approval for this project (gitignored — personal preference, not committed).
+
+### Next
+Day 2: git init → arxiv corpus fetch script → download ~17 canonical RL papers → first commit.
+
+---
+
+## 2026-05-06 16:00 — [implementation] Day 2: Corpus pipeline + first commit
+
+**Type:** implementation
+**Status:** complete (with one outstanding follow-up — see "Outcome")
+**Duration:** ~75 min
+
+### Context
+Build the end-to-end corpus path: fetch canonical RL papers from arXiv → parse PDFs → chunk text into a single JSONL ready for embedding. Land everything as the first git commit.
+
+### Decisions
+- **17-paper canon** chosen across 5 eras (value-based, policy-gradient, actor-critic, model-based, RLHF). See `researchpath/corpus.py`.
+- **Streaming downloads via `requests`** instead of `arxiv` library's built-in downloader — the latter was truncating large PDFs at exact 1MB / 2MB boundaries on Windows.
+- **PDF validation step** (open with pymupdf, read page 1) gates every download; truncated files auto-deleted and retried.
+- **Chunking**: 800-char windows, 100-char overlap, sentence-boundary aware, hyphenation-aware.
+- **Accept partial corpus (10/17)** rather than grind on rate-limited retries — script is idempotent so missing papers can be picked up later.
+
+### Actions taken
+- Added deps: `arxiv`, `pymupdf`. `uv sync` resolved 5 new packages.
+- `researchpath/corpus.py` — 17-paper canon with `era` tag.
+- `scripts/fetch_corpus.py` — streaming downloader with per-paper validate-and-retry, 12s inter-request spacing, 30s backoff.
+- `researchpath/parsing.py` — PDF text extraction + sentence-boundary chunking.
+- `scripts/parse_corpus.py` — drives parsing across all valid PDFs into `data/chunks.jsonl`.
+- Ran fetcher: 10 papers landed cleanly. Deleted 3 truncated stragglers (`1801.01290`, `1911.08265`, `2301.04104`).
+- Ran parser: **1,093 chunks, 778,995 chars** across 10 papers.
+- `git init -b main` → first commit `270993c` ("Bootstrap ResearchPath: scaffold + corpus pipeline"). 13 files, 1,611 insertions.
+
+### Issues encountered
+- **arXiv HTTP 429 rate-limiting** on PDF endpoint. Tried 3s→8s→12s inter-request delays; eventually too much accumulated state on this IP. Pivoted to "accept partial corpus, document the gap" per user's `feedback_dont_grind.md`.
+- **`arxiv` library truncates large PDFs at 1MB/2MB** even on retry — buffer issue specific to its downloader. Switched to direct `requests` streaming. (Confirmed by post-hoc validation: 3 stragglers stuck at exactly 2,097,152 / 1,048,576 bytes.)
+- **Unicode `→` in console output** broke on cp1252 (already known from Day 1; reused `PYTHONIOENCODING=utf-8`).
+
+### Files touched
+- Added: `researchpath/corpus.py`, `researchpath/parsing.py`, `scripts/fetch_corpus.py`, `scripts/parse_corpus.py`.
+- Modified: `pyproject.toml` (+arxiv, +pymupdf).
+- Generated (gitignored): `data/papers/*.pdf` (10 files), `data/chunks.jsonl`.
+
+### Outcome
+End-to-end corpus path works: arxiv ID → validated PDF → chunked JSONL. Repo under git, first commit landed.
+
+**Outstanding:** 4 papers still missing — `1511.05952` (PER), `1707.06347` (PPO), `1802.01561` (IMPALA), `2106.01345` (Decision Transformer). PPO is the painful gap (canonical paper). Re-run `uv run python scripts/fetch_corpus.py` later (script is idempotent + only retries missing/invalid).
+
+### Next
+Day 3: embeddings + FAISS index over `data/chunks.jsonl`. Use `BAAI/bge-small-en-v1.5` (CPU-friendly, ~133MB, strong on academic text). Then a tiny CLI: ask question → top-k chunks → grounded Gemini answer. That's the baseline RAG to measure against.
+
+---
+
+## 2026-05-06 17:00 — [implementation] Day 3: Embeddings, FAISS index, baseline RAG
+
+**Type:** implementation
+**Status:** complete
+**Duration:** ~50 min
+
+### Context
+Stand up the first measurable RAG system: chunks → embeddings → vector search → grounded LLM answer with citations. This becomes the baseline that all future improvements (hybrid retrieval, reranker, agent planning) get measured against.
+
+### Decisions
+- **Embedding model: `BAAI/bge-small-en-v1.5`** (384 dim, ~133MB, CPU-fast, strong on academic text). Documents embedded raw; queries prefixed with the BGE-recommended retrieval instruction for measurably better results.
+- **FAISS `IndexFlatIP`** with L2-normalized embeddings — exact cosine search, fast enough for ~1k chunks. Will swap to HNSW if corpus grows past ~50k.
+- **Citation format `[arxiv_id, p<page>]`** — parseable by future eval code, human-readable in output.
+- **System prompt is strict**: only-from-sources, no speculation. Will tighten further once we have eval numbers.
+
+### Actions taken
+- Added deps: `sentence-transformers`, `faiss-cpu`, `numpy`. `uv sync` resolved 29 new packages (~330MB inc. torch CPU).
+- `researchpath/embeddings.py` — `Embedder` wrapper with separate `embed_documents` / `embed_query` (BGE wants different prefixes).
+- `researchpath/index.py` — `build_index`, `load_index`, `search`. `Hit` dataclass carries score + citation metadata.
+- `researchpath/rag.py` — `build_prompt`, `answer`. Strict system prompt enforcing citations + grounding.
+- `scripts/build_index.py` — drives end-to-end embed + persist.
+- `scripts/ask.py` — CLI for question → answer with citations. `--show-sources` flag for debugging retrieval.
+- Built index: 1,093 chunks embedded in **148s** on CPU. Persisted `data/index.faiss` + `data/index.chunks.json`.
+- **Smoke test query**: *"How does Rainbow combine multiple deep Q-learning improvements like Double DQN, Dueling networks, and prioritized replay?"*
+  - Answer correctly cited [1710.02298, p1] for Rainbow components and [1511.06581, p4] for Dueling architecture details.
+  - Listed all 6 Rainbow components accurately. No hallucination observed.
+  - 1,106 input / 196 output tokens (≈ free under Gemini quota).
+
+### Issues encountered
+- **HF Hub symlink warning on Windows** — cache-system can't use symlinks without admin/Developer Mode. Cosmetic only; cache works in degraded mode (more disk, no functional impact).
+- **`VIRTUAL_ENV` mismatch warning from uv** — leftover env var from a prior shell session pointing at a different Python. Harmless; `.venv` is used regardless.
+
+### Files touched
+- Added: `researchpath/embeddings.py`, `researchpath/index.py`, `researchpath/rag.py`, `scripts/build_index.py`, `scripts/ask.py`.
+- Modified: `pyproject.toml` (+sentence-transformers, +faiss-cpu, +numpy), `uv.lock`.
+- Generated (gitignored): `data/index.faiss`, `data/index.chunks.json`.
+
+### Outcome
+Baseline RAG is **end-to-end working** and producing high-quality, grounded, cited answers on a real RL question. This is the system we'll measure in Day 4.
+
+### Next
+Day 4: **eval harness + gold dataset.** Build ~30 (question, expected answer key, expected source citations) tuples sourced from OpenAI Spinning Up problem sets, Sutton & Barto exercises, and 3-5 hand-curated questions per major paper. Then implement metrics (citation faithfulness, retrieval recall@k, answer quality blind-rated 1-5). First numbers go into the README eval table.
+
+---
+
+## 2026-05-06 18:00 — [implementation] Day 4: Eval harness + gold dataset + baseline numbers
+
+**Type:** implementation
+**Status:** complete
+**Duration:** ~90 min
+
+### Context
+Build a rigorous eval harness before optimizing anything. Eval-first is the portfolio differentiator — ablation table beats vibes.
+
+### Decisions
+- **30-question gold dataset** across 10 indexed papers (3 per single-paper + 4 cross-paper comparison). Difficulty-stratified: 7 easy / 15 medium / 8 hard. Each example: `{id, question, expected_arxiv_ids, expected_key_claim, difficulty}`.
+- **Three metrics** (no citation faithfulness per-claim — too expensive on free tier):
+  - `retrieval_recall@k`: fraction of expected arxiv IDs found in top-k hits
+  - `citation_presence`: answer cites at least one expected paper (string check)
+  - `answer_correctness`: LLM-as-judge (Groq llama-3.3-70b), YES/NO prompt
+- **Judge model: Groq** not Gemini — Gemini free tier has 20 req/day limit (hit during initial test run). Groq handles batch eval at no cost.
+- **RAG model: Groq** for batch eval. Gemini stays as default for `scripts/ask.py` (the demo CLI). Added `--groq` flag to `run_eval.py` to toggle.
+- **Retry logic** added to `gemini_generate()` — parses retry delay from 429 error body, sleeps and retries up to 5 times.
+
+### Actions taken
+- `data/gold_dataset.json` — 30 QA triples (hand-authored from Spinning Up + paper reading).
+- `researchpath/eval.py` — `GoldExample`, `EvalResult`, `EvalSummary` dataclasses + `evaluate_example`, `summarize`, `results_to_json`.
+- `scripts/run_eval.py` — full pipeline: load index → batch retrieve + generate → judge → print table + save JSON.
+- Updated `researchpath/rag.py` — added `generate_fn` injection param + `answer_groq()` convenience wrapper.
+- Updated `researchpath/llm.py` — retry-with-backoff on Gemini 429 (parses `retryDelay` from error body).
+- Ran full 30-question eval (`--groq`). Duration: ~3.5 min. Results saved to `data/eval_results.json`.
+
+### Issues encountered
+- **Gemini 20 req/day free-tier limit** — hit on second run (smoke test + partial full run = 20 calls). Fix: route eval to Groq entirely.
+- **Retry delay detection**: Gemini's 429 body contains `retryDelay: '10s'` in the Details array. Regex extracts it; if missing, defaults to 15s sleep.
+
+### Files touched
+- Added: `data/gold_dataset.json`, `researchpath/eval.py`, `scripts/run_eval.py`.
+- Modified: `researchpath/rag.py` (generate_fn injection, answer_groq), `researchpath/llm.py` (retry logic), `README.md` (eval table row 1).
+- Generated (gitignored): `data/eval_results.json`.
+
+### Outcome
+
+**Baseline RAG numbers (Groq llama-3.3-70b, k=5, n=30):**
+
+| Metric | Value |
+|---|---|
+| Retrieval Recall@5 | **90.0%** |
+| Citation Presence | **86.7%** |
+| Answer Correctness | **36.7%** |
+| Avg Latency | **5.07s** |
+| RAG Tokens | 33,498 in / 7,000 out |
+
+**Gap analysis:** Retrieval finds the right paper in 27/30 cases — the FAISS index is working well. But answer correctness is only 37%, revealing two failure modes:
+1. **Wrong-chunk problem**: Right paper retrieved, but the specific mechanistic claim is in a chunk outside top-5 (e.g., Rainbow's 6 components, distributional RL definition). Fix: hybrid retrieval (BM25 + vector) to catch exact-term hits + smaller chunks.
+2. **Precision failure**: Right chunk retrieved, but answer paraphrases around the key claim without naming the specific mechanism (e.g., "stability" instead of "identifiability" for Dueling DQN mean subtraction). Fix: reranker + more directive prompt.
+
+Difficulty breakdown: easy=28.6%, medium=53.3%, hard=12.5% answer correctness — harder questions show compounding retrieval + precision failures.
+
+### Next
+Day 5: Optimization round 1 — implement hybrid BM25+vector retrieval and measure improvement on same 30 gold examples. Target: push Answer Correctness from 37% → 55%+.
+
+---
+
+## 2026-05-06 19:30 — [implementation] Day 5: Hybrid BM25+FAISS retrieval (RRF fusion)
+
+**Type:** implementation
+**Status:** complete
+**Duration:** ~90 min
+
+### Context
+Day 4 baseline showed Retrieval Recall@5=90% but Answer Correctness=37%. Root-cause: right paper retrieved but wrong chunks — dense embeddings de-prioritize specific technical terms ("conjugate gradient", "Polyak averaging", "identifiability") relative to surrounding context. BM25 keyword search catches exact-term hits that dense misses.
+
+### Decisions
+- **BM25Okapi** (rank-bm25 library) for sparse retrieval over the same 1,093 chunks.
+- **Reciprocal Rank Fusion** (RRF, k=60) to combine BM25 and FAISS rankings without normalizing incompatible score spaces.
+- **Stop-word filter** in tokenizer: query "What does GAE stand for?" without stop words = `['gae', 'stand', 'fundamental', 'tradeoff']` — much better signal than including "what", "does", "for", "it".
+- **fetch_k=20** from each retriever before fusion, then top-k=5 from combined candidate set.
+
+### Actions taken
+- `researchpath/retrieval.py` — `BM25Retriever`, `HybridRetriever` with RRF fusion. Stop-word list added to tokenizer.
+- `researchpath/index.py` — added `global_idx` field to `Hit` dataclass (FAISS vector position, globally unique across papers). Fixed **critical bug**: original code used `chunk_idx` (within-paper index, 0..N) as RRF dict key, causing collisions across papers with same within-paper index.
+- `scripts/ask.py` — added `--hybrid` flag.
+- `scripts/run_eval.py` — added `--hybrid` flag, fixed `Path.relative_to()` crash on relative paths.
+- Ran full hybrid eval (`--groq --hybrid`): 29/30 questions (cross_04 errored on Groq 100K daily TPD limit).
+
+### Issues encountered
+- **global_idx bug**: `chunk_idx` is per-paper, not globally unique. Two chunks from different papers with the same within-paper index collided in the RRF dict, silently corrupting results. Fixed by adding `global_idx` (FAISS position) to Hit and using it in HybridRetriever. Pre-fix: hybrid was WORSE than dense in all spot checks. Post-fix: BETTER or TIED.
+- **BM25 stop-word pollution**: Without filtering, "What does GAE manage?" matched InstructGPT appendix QA sections (had literal "What is X? A: ...") scoring 19.9. After adding stop-word filter, query tokens = `['gae', 'stand', 'fundamental', 'tradeoff', 'manage']`, GAE paper correctly ranked first.
+- **Groq 100K daily TPD**: Exhausted daily token limit on the 30th question (cross_04). n=29 eval still valid; cross_04 retry deferred.
+
+### Files touched
+- Added: `researchpath/retrieval.py`.
+- Modified: `researchpath/index.py` (+global_idx field), `scripts/ask.py` (+--hybrid), `scripts/run_eval.py` (+--hybrid, path fix), `README.md` (eval table col 2), `PROJECT_LOG.md`.
+- Generated (gitignored): results in memory only (save failed on path bug, now fixed).
+
+### Outcome
+
+**Hybrid BM25+FAISS results (Groq llama-3.3-70b, k=5, n=29):**
+
+| Metric | Baseline | Hybrid | Delta |
+|---|---|---|---|
+| Retrieval Recall@5 | 90.0% | 89.7% | -0.3 pp |
+| Citation Presence | 86.7% | 86.2% | -0.5 pp |
+| **Answer Correctness** | **36.7%** | **72.4%** | **+35.7 pp** |
+| Avg Latency | 5.07s | 4.58s | -0.5s |
+
+By difficulty: easy 100%, medium 73.3%, hard 42.9%. Hard questions remain the weak spot.
+
+**Why hybrid helped so much:** The global_idx bug fix + stop-word filter together fixed hybrid retrieval so it correctly fuses dense + sparse signals. Many questions where the right paper was retrieved but answer was wrong (dense recall=100%, correct=N in baseline) flipped to correct under hybrid because BM25 surfaced chunks with the specific technical term rather than contextual chunks about the same topic.
+
+### Next
+Retry cross_04 when Groq TPD resets (saves the 30/30 result). Then: cross-encoder reranker as column 3 in the ablation table. Target: 75%+ correctness on hard questions.
+
+---
+
+## 2026-05-07 — [implementation] Day 5 cont.: Agentic planning loop (offline prerequisite-chain planner)
+
+**Type:** implementation
+**Status:** complete
+**Duration:** ~60 min
+
+### Context
+The killer differentiator of ResearchPath over generic RAG is the prerequisite-chain reading-path planner: given a target RL paper and what the user already knows, compute the topologically-sorted chain of papers they need to read first. This module runs fully offline — no LLM calls, no API quota burned. It's the deterministic core that an LLM annotation layer will augment later.
+
+### Decisions
+- **Static prerequisite graph** as the seed: hand-curate ~10 edges covering canonical chains (DQN→Double DQN→Dueling DQN→Rainbow, TRPO→GAE, DQN→DDPG, DQN→A3C, InstructGPT→DPO). Enough to demo the killer feature; LLM-extracted edges added in a future iteration.
+- **BFS backwards** from target, stopping at `known_ids` — avoids pulling in papers the user already understands.
+- **Kahn's algorithm** for topological sort with `(year, arxiv_id)` tie-breaking — deterministic + chronologically sensible for RL literature.
+- **ReadingStep annotation**: each step carries `bridges_to` (which later papers depend on it), `concepts` (the bridging ideas), and `why` (user-facing rationale) aggregated from the static edge metadata.
+
+### Actions taken
+- `researchpath/prerequisites.py` — `Prerequisite` dataclass + `STATIC_PREREQUISITES` tuple (10 hand-curated edges) + `edges_into` / `edges_from` accessors.
+- `researchpath/planning.py` — `ReadingStep`, `ReadingPlan` dataclasses + `_bfs_backwards`, `_topo_sort` (Kahn's), `_build_step`, `plan_reading_path`. `ReadingPlan.render_text()` produces human-readable ordered list.
+- `scripts/plan.py` — CLI: `--target` (arxiv ID or tag, case-insensitive), `--known` (comma-separated), `--list`. Rich Panel output.
+- `tests/test_planning.py` — 7 pytest tests: no-prereq paper (1 step), Rainbow full chain (4 steps in order), known set truncates, known target → empty plan, topo order respects all edges, unknown target raises ValueError, render_text contains target title.
+
+### Smoke tests (pre-pytest, verified manually):
+- Rainbow (`1710.02298`, no prior knowledge): `1312.5602 → 1509.06461 → 1511.06581 → 1710.02298` ✓
+- Rainbow knowing DQN: `1509.06461 → 1511.06581 → 1710.02298` (3 steps) ✓
+- DPO (`2305.18290`) knowing InstructGPT: 1 step (DPO itself) ✓
+- DDPG (`1509.02971`): `1312.5602 → 1509.02971` (2 steps) ✓
+
+### Issues encountered
+None. BFS + Kahn's on the static graph is deterministic and small enough that correctness is straightforward to verify.
+
+### Files touched
+- Added: `researchpath/prerequisites.py`, `researchpath/planning.py`, `scripts/plan.py`, `tests/test_planning.py`.
+
+### Outcome
+7/7 pytest tests pass in 0.09s. Planning loop runs offline without any API calls. Demonstrates genuine agentic behavior (graph traversal, state-aware planning) that differentiates ResearchPath from simple RAG demos.
+
+**Sample CLI output** (`uv run python scripts/plan.py --target Rainbow`):
+```
+1. [1312.5602] DQN (2013) — Playing Atari with Deep Reinforcement Learning
+     bridges: -> 1509.06461, 1511.06581, 1710.02298
+     concepts: Q-learning, experience replay, target network
+
+2. [1509.06461] DoubleDQN (2015) — Deep Reinforcement Learning with Double Q-learning
+     bridges: -> 1511.06581, 1710.02298
+     concepts: overestimation bias, decoupled action selection/evaluation, Double Q-learning
+
+3. [1511.06581] DuelingDQN (2015) — Dueling Network Architectures for Deep Reinforcement Learning
+     bridges: -> 1710.02298
+     concepts: dueling networks
+
+4. [1710.02298] Rainbow (2017) — Rainbow: Combining Improvements in Deep Reinforcement Learning
+     bridges: <- target
+```
+
+### Next
+- Retry cross_04 when Groq TPD resets → update README hybrid result from n=29 to n=30
+- Run reranker full eval (column 3 in ablation table): `--hybrid --rerank`
+- LLM annotation layer: map free-text user background → `known_ids` set; per-step "what to focus on" rationale
+- Fetch 4 missing papers: PER (1511.05952), PPO (1707.06347), IMPALA (1802.01561), Decision Transformer (2106.01345)
+
+---

README.md

@@ -1,10 +1,148 @@
 ---
-title: Researchpath
-emoji: 🔥
-colorFrom: pink
-colorTo: pink
+title: ResearchPath
+emoji: 🗺️
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 pinned: false
+license: mit
+short_description: Agentic RL reading-path planner with grounded Q&A
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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 ~2k 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)
+- [ ] Week 4 — Hybrid v2 eval (pending Groq token reset), ablation table complete, demo video
+- [ ] Week 5 — Streamlit UI, HF Spaces deploy
+
+---
+
+## 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 (downloads ~17 PDFs from arXiv, parses, embeds — one-time ~15 min)
+uv run python scripts/fetch_corpus.py
+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
+```

app.py

@@ -0,0 +1,286 @@
+"""ResearchPath Streamlit app.
+
+Two tabs:
+  1. Reading Path  — prerequisite-chain planner (the unique agentic feature)
+  2. Ask           — grounded Q&A over the indexed RL corpus
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import streamlit as st
+
+from researchpath.corpus import CANONICAL_RL_PAPERS
+from researchpath.planning import plan_reading_path
+
+ROOT = Path(__file__).resolve().parent
+INDEX_PATH = ROOT / "data" / "index.faiss"
+
+_TAG_TO_ID = {p.tag.lower(): p.arxiv_id for p in CANONICAL_RL_PAPERS}
+_ID_TO_PAPER = {p.arxiv_id: p for p in CANONICAL_RL_PAPERS}
+_ERA_ORDER = ["value-based", "policy-gradient", "actor-critic", "model-based", "rlhf"]
+
+st.set_page_config(
+    page_title="ResearchPath",
+    page_icon="🗺️",
+    layout="wide",
+    initial_sidebar_state="collapsed",
+)
+
+# ── minimal style ──────────────────────────────────────────────────────────
+st.markdown(
+    """
+    <style>
+    .step-card {
+        background: #1e2330;
+        border-left: 4px solid #4f8ef7;
+        border-radius: 6px;
+        padding: 14px 18px;
+        margin-bottom: 12px;
+    }
+    .step-card h4 { margin: 0 0 4px 0; color: #e0e6f0; }
+    .step-card .concepts { color: #a0aec0; font-size: 0.85rem; }
+    .step-card .why { color: #cbd5e0; font-size: 0.9rem; margin-top: 6px; }
+    .tag-chip {
+        display: inline-block;
+        background: #2d3748;
+        color: #90cdf4;
+        border-radius: 12px;
+        padding: 2px 10px;
+        font-size: 0.78rem;
+        margin-right: 4px;
+    }
+    </style>
+    """,
+    unsafe_allow_html=True,
+)
+
+# ── header ─────────────────────────────────────────────────────────────────
+st.title("🗺️ ResearchPath")
+st.caption(
+    "An agentic research-onboarding companion for Reinforcement Learning. "
+    "Give it a target paper and your background; it builds a personalized, "
+    "dependency-ordered reading plan."
+)
+
+tab_plan, tab_ask = st.tabs(["📚 Reading Path", "💬 Ask a Question"])
+
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+def _resolve(token: str) -> str | None:
+    token = token.strip()
+    if token in _ID_TO_PAPER:
+        return token
+    if token.lower() in _TAG_TO_ID:
+        return _TAG_TO_ID[token.lower()]
+    return None
+
+
+def _paper_label(arxiv_id: str) -> str:
+    p = _ID_TO_PAPER[arxiv_id]
+    return f"{p.tag} ({p.year})"
+
+
+@st.cache_resource(show_spinner="Loading index and embedder…")
+def _load_retrieval():
+    """Load FAISS index + embedder once per session."""
+    from researchpath.embeddings import Embedder
+    from researchpath.index import load_index
+    from researchpath.retrieval import HybridRetriever
+
+    if not INDEX_PATH.exists():
+        return None, None, None
+    index, chunks = load_index(INDEX_PATH)
+    embedder = Embedder()
+    retriever = HybridRetriever(index, chunks, embedder)
+    return index, chunks, retriever
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# TAB 1 — Reading Path
+# ═══════════════════════════════════════════════════════════════════════════
+with tab_plan:
+    st.subheader("Build your personalized reading path")
+    st.markdown(
+        "Select a **target paper** you want to understand, then tell us what you **already know**. "
+        "ResearchPath traces the prerequisite chain and gives you a topologically-sorted reading list "
+        "with *why each paper is next*."
+    )
+
+    # Group papers by era for a nicer selectbox
+    era_groups: dict[str, list] = {era: [] for era in _ERA_ORDER}
+    for p in CANONICAL_RL_PAPERS:
+        era_groups[p.era].append(p)
+
+    paper_options = []
+    for era in _ERA_ORDER:
+        for p in era_groups[era]:
+            paper_options.append(p.arxiv_id)
+
+    def _format_option(arxiv_id: str) -> str:
+        p = _ID_TO_PAPER[arxiv_id]
+        return f"{p.tag}  —  {p.title[:60]}{'…' if len(p.title) > 60 else ''}  ({p.year})"
+
+    col_target, col_known = st.columns([1, 1])
+
+    with col_target:
+        target_id = st.selectbox(
+            "Target paper",
+            options=paper_options,
+            format_func=_format_option,
+            index=paper_options.index("1710.02298"),  # default: Rainbow
+        )
+
+    with col_known:
+        known_options = [aid for aid in paper_options if aid != target_id]
+        known_ids_raw = st.multiselect(
+            "Papers you already know (optional)",
+            options=known_options,
+            format_func=_format_option,
+            default=[],
+        )
+
+    if st.button("Generate reading path", type="primary", use_container_width=True):
+        plan = plan_reading_path(target_id, known_ids=set(known_ids_raw))
+        target_paper = _ID_TO_PAPER[target_id]
+
+        if not plan.steps:
+            st.success(f"You're already ready to read **{target_paper.tag}** directly!")
+        else:
+            st.markdown(
+                f"**{len(plan.steps)} paper(s)** to read before (and including) "
+                f"**{target_paper.tag}**, in order:"
+            )
+            for i, step in enumerate(plan.steps, 1):
+                p = step.paper
+                is_target = p.arxiv_id == target_id
+                border_color = "#f6c90e" if is_target else "#4f8ef7"
+                label = "🎯 TARGET" if is_target else f"Step {i}"
+                concepts_html = "".join(
+                    f'<span class="tag-chip">{c}</span>' for c in step.concepts
+                )
+                bridges_text = (
+                    "→ " + ", ".join(_paper_label(b) for b in step.bridges_to)
+                    if step.bridges_to
+                    else ""
+                )
+                st.markdown(
+                    f"""
+                    <div class="step-card" style="border-left-color:{border_color}">
+                        <h4>{label} &nbsp; [{p.arxiv_id}] &nbsp; <b>{p.tag}</b> &nbsp; <span style="color:#718096;font-weight:normal">({p.year})</span></h4>
+                        <div style="color:#a0aec0;font-size:0.9rem">{p.title}</div>
+                        {f'<div class="concepts" style="margin-top:8px">{concepts_html}</div>' if concepts_html else ""}
+                        {f'<div class="why">{step.why}</div>' if step.why else ""}
+                        {f'<div style="color:#718096;font-size:0.82rem;margin-top:6px">{bridges_text}</div>' if bridges_text else ""}
+                    </div>
+                    """,
+                    unsafe_allow_html=True,
+                )
+
+    with st.expander("Browse all canonical RL papers"):
+        for era in _ERA_ORDER:
+            st.markdown(f"**{era.replace('-', ' ').title()}**")
+            for p in era_groups[era]:
+                st.markdown(
+                    f"&nbsp;&nbsp;&nbsp;`{p.arxiv_id}` &nbsp; **{p.tag}** ({p.year}) — {p.title}"
+                )
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# TAB 2 — Ask a Question
+# ═══════════════════════════════════════════════════════════════════════════
+with tab_ask:
+    st.subheader("Ask anything about the RL corpus")
+    st.markdown(
+        "Every answer is grounded in the indexed papers with **`[arxiv_id, p<page>]` citations**. "
+        "No hallucination — if the corpus doesn't contain an answer, the model says so."
+    )
+
+    index_ready = INDEX_PATH.exists()
+    if not index_ready:
+        st.warning(
+            "No FAISS index found at `data/index.faiss`. "
+            "Run `uv run python scripts/build_index.py` first."
+        )
+
+    with st.form("ask_form"):
+        question = st.text_area(
+            "Your question",
+            placeholder="What is the main idea behind Proximal Policy Optimization?",
+            height=80,
+        )
+        col_k, col_mode, _ = st.columns([1, 2, 3])
+        with col_k:
+            k = st.number_input("Top-k chunks", min_value=1, max_value=20, value=5)
+        with col_mode:
+            retrieval_mode = st.selectbox(
+                "Retrieval mode",
+                ["Hybrid (BM25 + FAISS)", "Dense (FAISS only)"],
+            )
+        submitted = st.form_submit_button("Ask", type="primary", use_container_width=True)
+
+    import os
+    _gemini_key = os.environ.get("GEMINI_API_KEY", "")
+    if not _gemini_key:
+        st.info(
+            "**GEMINI_API_KEY not set** — the Ask tab needs a Gemini API key to generate answers. "
+            "Set it in your `.env` file (local) or as a Space secret (HF Spaces). "
+            "The Reading Path tab above works entirely offline with no API key."
+        )
+
+    if submitted and question.strip() and index_ready:
+        if not _gemini_key:
+            st.error("Cannot generate an answer: GEMINI_API_KEY is not set.")
+        else:
+            _, _, retriever = _load_retrieval()
+            if retriever is None:
+                st.error("Failed to load index.")
+            else:
+                with st.spinner("Retrieving and generating…"):
+                    from researchpath.rag import answer as rag_answer
+                    from researchpath.index import load_index, search
+                    from researchpath.embeddings import Embedder
+
+                    if retrieval_mode.startswith("Hybrid"):
+                        hits = retriever.search(question.strip(), k=int(k))
+                    else:
+                        index, chunks = load_index(INDEX_PATH)
+                        embedder = Embedder()
+                        hits = search(index, chunks, embedder, question.strip(), k=int(k))
+
+                    result = rag_answer(question.strip(), hits)
+
+                st.markdown("### Answer")
+                st.markdown(result.answer)
+
+                st.markdown("---")
+                col_meta1, col_meta2, col_meta3 = st.columns(3)
+                col_meta1.metric("Chunks retrieved", len(hits))
+                col_meta2.metric("Tokens in", result.llm.input_tokens or "—")
+                col_meta3.metric("Tokens out", result.llm.output_tokens or "—")
+
+                with st.expander(f"📄 Retrieved chunks ({len(hits)})"):
+                    for i, h in enumerate(hits, 1):
+                        st.markdown(
+                            f"**#{i}** &nbsp; `[{h.arxiv_id}, p{h.page}]` &nbsp; "
+                            f"score={h.score:.3f}"
+                        )
+                        st.text(h.text[:400] + ("…" if len(h.text) > 400 else ""))
+                        st.divider()
+
+    # Example questions
+    with st.expander("Example questions to try"):
+        examples = [
+            "What are the six components Rainbow combines?",
+            "How does PPO avoid the large policy update problem in TRPO?",
+            "What is the key insight behind Generalized Advantage Estimation?",
+            "How does DDPG handle continuous action spaces?",
+            "What is the DPO loss function and why does it not need a reward model?",
+            "How does A3C's asynchronous training replace experience replay?",
+        ]
+        for ex in examples:
+            st.markdown(f"- *{ex}*")

data/gold_dataset.json

@@ -0,0 +1,212 @@
+[
+  {
+    "id": "dqn_01",
+    "question": "What neural network architecture did DQN use to play Atari games, and what was the input representation?",
+    "expected_arxiv_ids": ["1312.5602"],
+    "expected_key_claim": "convolutional neural network with raw pixel input, specifically 84x84 grayscale frames with the last 4 frames stacked as input",
+    "difficulty": "easy"
+  },
+  {
+    "id": "dqn_02",
+    "question": "What is experience replay in DQN and why does it improve training stability?",
+    "expected_arxiv_ids": ["1312.5602"],
+    "expected_key_claim": "stores agent transitions in a replay buffer and samples random minibatches to break temporal correlations between consecutive updates",
+    "difficulty": "easy"
+  },
+  {
+    "id": "dqn_03",
+    "question": "What is the target network in DQN and what problem does it address?",
+    "expected_arxiv_ids": ["1312.5602"],
+    "expected_key_claim": "a separate network with periodically-copied weights used to compute stable TD targets, reducing oscillation caused by moving targets in standard Q-learning",
+    "difficulty": "medium"
+  },
+  {
+    "id": "ddqn_01",
+    "question": "What overestimation problem in standard DQN does Double DQN address?",
+    "expected_arxiv_ids": ["1509.06461"],
+    "expected_key_claim": "DQN uses the same network for both action selection and value evaluation in the max operator, causing systematic overestimation of Q-values",
+    "difficulty": "medium"
+  },
+  {
+    "id": "ddqn_02",
+    "question": "How does Double DQN decouple action selection from action evaluation?",
+    "expected_arxiv_ids": ["1509.06461"],
+    "expected_key_claim": "the online network selects the greedy action while the target network evaluates its value, preventing the same network from both choosing and scoring actions",
+    "difficulty": "medium"
+  },
+  {
+    "id": "dueling_01",
+    "question": "What are the Value and Advantage streams in the Dueling Network architecture and how are they combined?",
+    "expected_arxiv_ids": ["1511.06581"],
+    "expected_key_claim": "shared convolutional encoder splits into V(s) stream and A(s,a) stream; combined as Q(s,a) = V(s) + A(s,a) minus mean advantage for identifiability",
+    "difficulty": "medium"
+  },
+  {
+    "id": "dueling_02",
+    "question": "Why must the advantage stream be mean-subtracted in the Dueling DQN aggregation module?",
+    "expected_arxiv_ids": ["1511.06581"],
+    "expected_key_claim": "without centering, V and A are not uniquely identifiable from Q alone; subtracting the mean advantage forces V to be the state value and A to be relative advantages",
+    "difficulty": "hard"
+  },
+  {
+    "id": "rainbow_01",
+    "question": "What six algorithmic improvements does Rainbow combine?",
+    "expected_arxiv_ids": ["1710.02298"],
+    "expected_key_claim": "double Q-learning, prioritized experience replay, dueling networks, multi-step returns, distributional RL (C51), and noisy nets for exploration",
+    "difficulty": "easy"
+  },
+  {
+    "id": "rainbow_02",
+    "question": "What is distributional RL and how does Rainbow use it?",
+    "expected_arxiv_ids": ["1710.02298"],
+    "expected_key_claim": "instead of estimating expected return, distributional RL models the full probability distribution over returns; Rainbow uses C51 which represents this as a categorical distribution over fixed discrete atoms",
+    "difficulty": "hard"
+  },
+  {
+    "id": "rainbow_03",
+    "question": "What is noisy networks (NoisyNets) and how does Rainbow use it for exploration?",
+    "expected_arxiv_ids": ["1710.02298"],
+    "expected_key_claim": "replaces epsilon-greedy exploration with learned stochastic weights in the network's linear layers; noise parameters are learned by gradient descent, enabling state-dependent exploration",
+    "difficulty": "hard"
+  },
+  {
+    "id": "trpo_01",
+    "question": "What is the trust region constraint in TRPO and why is it necessary?",
+    "expected_arxiv_ids": ["1502.05477"],
+    "expected_key_claim": "constrains KL divergence between old and new policy to be below a threshold delta at each update, preventing destructively large policy changes that collapse performance",
+    "difficulty": "medium"
+  },
+  {
+    "id": "trpo_02",
+    "question": "What optimization algorithm does TRPO use to solve the constrained policy update problem?",
+    "expected_arxiv_ids": ["1502.05477"],
+    "expected_key_claim": "conjugate gradient to compute the natural policy gradient direction, then a backtracking line search to find the largest step satisfying the KL constraint",
+    "difficulty": "hard"
+  },
+  {
+    "id": "trpo_03",
+    "question": "What surrogate objective does TRPO optimize and how does it relate to the true policy objective?",
+    "expected_arxiv_ids": ["1502.05477"],
+    "expected_key_claim": "optimizes a surrogate objective using importance sampling ratios of new to old policy probabilities, which is a local approximation to the true objective guaranteed to be a lower bound within the trust region",
+    "difficulty": "hard"
+  },
+  {
+    "id": "gae_01",
+    "question": "What does GAE stand for and what fundamental tradeoff does it manage?",
+    "expected_arxiv_ids": ["1506.02438"],
+    "expected_key_claim": "Generalized Advantage Estimation; trades off bias versus variance in advantage estimates for policy gradient methods using an exponential weighting parameter lambda",
+    "difficulty": "easy"
+  },
+  {
+    "id": "gae_02",
+    "question": "How does the GAE lambda parameter interpolate between Monte Carlo and TD advantage estimates?",
+    "expected_arxiv_ids": ["1506.02438"],
+    "expected_key_claim": "lambda=0 reduces to single-step TD advantage (low variance, high bias); lambda=1 reduces to Monte Carlo return minus baseline (low bias, high variance); intermediate values exponentially weight n-step returns",
+    "difficulty": "medium"
+  },
+  {
+    "id": "a3c_01",
+    "question": "How does A3C use asynchronous parallel workers to stabilize training?",
+    "expected_arxiv_ids": ["1602.01783"],
+    "expected_key_claim": "multiple actor-learner threads each interact with independent environment copies and asynchronously send gradient updates to a shared global network, decorrelating experience without requiring a replay buffer",
+    "difficulty": "medium"
+  },
+  {
+    "id": "a3c_02",
+    "question": "What advantage function does A3C use in its policy gradient update?",
+    "expected_arxiv_ids": ["1602.01783"],
+    "expected_key_claim": "uses n-step returns as the target minus the value function V(s) as a baseline; the value network is trained simultaneously as a critic to estimate state values",
+    "difficulty": "medium"
+  },
+  {
+    "id": "a3c_03",
+    "question": "How does A3C handle both discrete and continuous action spaces?",
+    "expected_arxiv_ids": ["1602.01783"],
+    "expected_key_claim": "for discrete actions uses softmax policy; for continuous actions outputs mean and variance of a Gaussian, sampling actions from it; the same asynchronous framework applies to both",
+    "difficulty": "hard"
+  },
+  {
+    "id": "ddpg_01",
+    "question": "How does DDPG extend DQN to continuous action spaces?",
+    "expected_arxiv_ids": ["1509.02971"],
+    "expected_key_claim": "uses a deterministic actor network that outputs the exact continuous action and a critic network that evaluates Q(s,a); applies the deterministic policy gradient theorem rather than maximizing over a discrete action set",
+    "difficulty": "medium"
+  },
+  {
+    "id": "ddpg_02",
+    "question": "What exploration strategy does DDPG use for continuous action spaces?",
+    "expected_arxiv_ids": ["1509.02971"],
+    "expected_key_claim": "adds temporally-correlated Ornstein-Uhlenbeck noise to the deterministic policy output during training, encouraging exploration with smooth, momentum-based noise rather than independent Gaussian noise",
+    "difficulty": "medium"
+  },
+  {
+    "id": "ddpg_03",
+    "question": "How does DDPG update its target networks and why does this differ from DQN?",
+    "expected_arxiv_ids": ["1509.02971"],
+    "expected_key_claim": "uses soft Polyak averaging (target = tau*online + (1-tau)*target) at every step instead of hard periodic copying, providing slower and more stable target updates for continuous control",
+    "difficulty": "medium"
+  },
+  {
+    "id": "instructgpt_01",
+    "question": "What are the three training stages in InstructGPT's RLHF pipeline?",
+    "expected_arxiv_ids": ["2203.02155"],
+    "expected_key_claim": "first supervised fine-tuning on human-written demonstrations, then reward model training from pairwise human preference comparisons, then PPO policy optimization against the reward model with KL penalty",
+    "difficulty": "easy"
+  },
+  {
+    "id": "instructgpt_02",
+    "question": "What is the KL penalty term in InstructGPT's RL objective and why is it included?",
+    "expected_arxiv_ids": ["2203.02155"],
+    "expected_key_claim": "penalizes KL divergence between the RLHF policy and the original SFT policy to prevent reward hacking, maintain language quality, and avoid the policy collapsing to adversarial outputs that game the reward model",
+    "difficulty": "medium"
+  },
+  {
+    "id": "instructgpt_03",
+    "question": "How does InstructGPT collect human preference data for training the reward model?",
+    "expected_arxiv_ids": ["2203.02155"],
+    "expected_key_claim": "human labelers rank multiple model completions for the same prompt; these pairwise orderings are converted into preference pairs used to train the reward model with a cross-entropy loss",
+    "difficulty": "easy"
+  },
+  {
+    "id": "dpo_01",
+    "question": "What is the core insight of DPO that eliminates the need for explicit RL?",
+    "expected_arxiv_ids": ["2305.18290"],
+    "expected_key_claim": "shows that the optimal RLHF policy implies a closed-form reward expressible as log probability ratios between the policy and reference model; this allows directly optimizing the policy from preference data without training a separate reward model",
+    "difficulty": "hard"
+  },
+  {
+    "id": "dpo_02",
+    "question": "What is the DPO training objective and what data does it require?",
+    "expected_arxiv_ids": ["2305.18290"],
+    "expected_key_claim": "binary cross-entropy loss on preference pairs where loss increases the likelihood of preferred completions relative to rejected ones, weighted by how much the policy deviates from the reference model; requires only (prompt, chosen, rejected) triples",
+    "difficulty": "medium"
+  },
+  {
+    "id": "cross_01",
+    "question": "How do DQN and Double DQN differ in their Bellman target computation?",
+    "expected_arxiv_ids": ["1312.5602", "1509.06461"],
+    "expected_key_claim": "DQN uses the target network for both selecting and evaluating the greedy action; Double DQN uses the online network to select the action and the target network only to evaluate it, eliminating the maximization bias",
+    "difficulty": "medium"
+  },
+  {
+    "id": "cross_02",
+    "question": "What architectural innovation separates Dueling DQN from standard DQN?",
+    "expected_arxiv_ids": ["1511.06581", "1312.5602"],
+    "expected_key_claim": "Dueling DQN splits the final layers into two streams estimating state value V(s) and state-action advantages A(s,a) separately, which standard DQN does not do",
+    "difficulty": "easy"
+  },
+  {
+    "id": "cross_03",
+    "question": "How do InstructGPT and DPO differ in their approach to aligning language models with human preferences?",
+    "expected_arxiv_ids": ["2203.02155", "2305.18290"],
+    "expected_key_claim": "InstructGPT trains an explicit reward model then runs PPO against it; DPO directly optimizes the policy from preference data using a classification loss, eliminating the reward model and RL training loop entirely",
+    "difficulty": "medium"
+  },
+  {
+    "id": "cross_04",
+    "question": "How do DDPG and A3C differ in their approach to continuous control problems?",
+    "expected_arxiv_ids": ["1509.02971", "1602.01783"],
+    "expected_key_claim": "DDPG is off-policy and uses a deterministic actor-critic with experience replay; A3C is on-policy and uses asynchronous parallel workers without a replay buffer; both can handle continuous actions",
+    "difficulty": "hard"
+  }
+]

data/index.faiss

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

pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "researchpath"
+version = "0.1.0"
+description = "Agentic research onboarding companion — builds personalized reading paths into RL research."
+requires-python = ">=3.11"
+dependencies = [
+    "google-genai>=1.0.0",
+    "groq>=0.11.0",
+    "python-dotenv>=1.0.0",
+    "rich>=13.0.0",
+    "arxiv>=2.1.0",
+    "pymupdf>=1.24.0",
+    "sentence-transformers>=3.0.0",
+    "faiss-cpu>=1.8.0",
+    "numpy>=1.26.0",
+    "rank-bm25>=0.2.2",
+    "streamlit>=1.35.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.6.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["researchpath"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

requirements.txt

@@ -0,0 +1,10 @@
+google-genai>=1.0.0
+groq>=0.11.0
+python-dotenv>=1.0.0
+rich>=13.0.0
+pymupdf>=1.24.0
+sentence-transformers>=3.0.0
+faiss-cpu>=1.8.0
+numpy>=1.26.0
+rank-bm25>=0.2.2
+streamlit>=1.35.0

researchpath/__init__.py

@@ -0,0 +1,3 @@
+"""ResearchPath — agentic research onboarding companion."""
+
+__version__ = "0.1.0"

researchpath/corpus.py

@@ -0,0 +1,74 @@
+"""Canonical Reinforcement Learning paper corpus.
+
+These ~17 papers form a defensible reading-path graph from foundational
+deep RL (DQN, 2013) to modern RLHF (DPO, 2023). The agent will reason over
+their content + cross-references to build personalized reading plans.
+
+`era` tags are used as a coarse prior for prerequisite ordering — the agent
+can override based on extracted concept dependencies.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Paper:
+    arxiv_id: str
+    title: str
+    year: int
+    authors: str
+    tag: str
+    era: str  # value-based | policy-gradient | actor-critic | model-based | rlhf
+
+
+CANONICAL_RL_PAPERS: list[Paper] = [
+    # --- Value-based deep RL ---
+    Paper("1312.5602", "Playing Atari with Deep Reinforcement Learning", 2013,
+          "Mnih et al.", "DQN", "value-based"),
+    Paper("1509.06461", "Deep Reinforcement Learning with Double Q-learning", 2015,
+          "van Hasselt et al.", "Double DQN", "value-based"),
+    Paper("1511.06581", "Dueling Network Architectures for Deep Reinforcement Learning", 2016,
+          "Wang et al.", "Dueling DQN", "value-based"),
+    Paper("1511.05952", "Prioritized Experience Replay", 2015,
+          "Schaul et al.", "PER", "value-based"),
+    Paper("1710.02298", "Rainbow: Combining Improvements in Deep Reinforcement Learning", 2017,
+          "Hessel et al.", "Rainbow", "value-based"),
+
+    # --- Policy gradient / trust region ---
+    Paper("1502.05477", "Trust Region Policy Optimization", 2015,
+          "Schulman et al.", "TRPO", "policy-gradient"),
+    Paper("1506.02438",
+          "High-Dimensional Continuous Control Using Generalized Advantage Estimation", 2015,
+          "Schulman et al.", "GAE", "policy-gradient"),
+    Paper("1707.06347", "Proximal Policy Optimization Algorithms", 2017,
+          "Schulman et al.", "PPO", "policy-gradient"),
+
+    # --- Actor-critic / continuous control ---
+    Paper("1602.01783", "Asynchronous Methods for Deep Reinforcement Learning", 2016,
+          "Mnih et al.", "A3C", "actor-critic"),
+    Paper("1509.02971", "Continuous Control with Deep Reinforcement Learning", 2015,
+          "Lillicrap et al.", "DDPG", "actor-critic"),
+    Paper("1801.01290",
+          "Soft Actor-Critic: Off-Policy Maximum Entropy Deep Reinforcement Learning", 2018,
+          "Haarnoja et al.", "SAC", "actor-critic"),
+    Paper("1802.01561", "IMPALA: Scalable Distributed Deep-RL", 2018,
+          "Espeholt et al.", "IMPALA", "actor-critic"),
+
+    # --- Model-based / planning ---
+    Paper("1911.08265",
+          "Mastering Atari, Go, Chess and Shogi by Planning with a Learned Model", 2019,
+          "Schrittwieser et al.", "MuZero", "model-based"),
+    Paper("2301.04104", "Mastering Diverse Domains through World Models", 2023,
+          "Hafner et al.", "DreamerV3", "model-based"),
+
+    # --- Sequence modeling for RL ---
+    Paper("2106.01345", "Decision Transformer: Reinforcement Learning via Sequence Modeling", 2021,
+          "Chen et al.", "Decision Transformer", "model-based"),
+
+    # --- RLHF (the modern application that put RL in every product hiring conversation) ---
+    Paper("2203.02155", "Training language models to follow instructions with human feedback", 2022,
+          "Ouyang et al.", "InstructGPT", "rlhf"),
+    Paper("2305.18290", "Direct Preference Optimization: Your Language Model is Secretly a Reward Model",
+          2023, "Rafailov et al.", "DPO", "rlhf"),
+]

researchpath/embeddings.py

@@ -0,0 +1,46 @@
+"""Sentence-transformers wrapper for chunk + query embedding.
+
+Uses BAAI/bge-small-en-v1.5: 384-dim, ~133MB, CPU-fast, strong on academic text.
+Embeddings are L2-normalized so cosine similarity == inner product (lets us
+use FAISS IndexFlatIP).
+"""
+from __future__ import annotations
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+
+DEFAULT_MODEL = "BAAI/bge-small-en-v1.5"
+EMBED_DIM = 384
+
+# BGE models recommend prefixing search queries (not documents) with this
+# instruction. Improves retrieval quality measurably on academic text.
+QUERY_INSTRUCTION = "Represent this question for retrieving relevant scientific passages: "
+
+
+class Embedder:
+    def __init__(self, model_name: str = DEFAULT_MODEL):
+        self.model_name = model_name
+        self._model: SentenceTransformer | None = None
+
+    @property
+    def model(self) -> SentenceTransformer:
+        if self._model is None:
+            self._model = SentenceTransformer(self.model_name)
+        return self._model
+
+    def embed_documents(self, texts: list[str], batch_size: int = 32) -> np.ndarray:
+        return self.model.encode(
+            texts,
+            batch_size=batch_size,
+            normalize_embeddings=True,
+            show_progress_bar=True,
+            convert_to_numpy=True,
+        ).astype(np.float32)
+
+    def embed_query(self, text: str) -> np.ndarray:
+        prompt = QUERY_INSTRUCTION + text
+        vec = self.model.encode(
+            [prompt], normalize_embeddings=True, convert_to_numpy=True
+        )[0].astype(np.float32)
+        return vec

researchpath/eval.py

@@ -0,0 +1,220 @@
+"""Evaluation harness for ResearchPath baseline RAG.
+
+Metrics:
+  retrieval_recall_at_k — fraction of expected arxiv IDs found in top-k hits
+  citation_presence      — does the answer cite at least one expected paper?
+  answer_correctness     — LLM-as-judge: does answer capture the key claim?
+  latency_s              — wall-clock seconds for retrieve + generate
+  tokens_in/out          — for cost tracking
+
+Gold dataset schema (data/gold_dataset.json):
+  id, question, expected_arxiv_ids, expected_key_claim, difficulty
+"""
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from researchpath.index import Hit
+from researchpath.llm import LLMResponse, groq_generate
+from researchpath.rag import RAGAnswer
+
+
+@dataclass(frozen=True)
+class GoldExample:
+    id: str
+    question: str
+    expected_arxiv_ids: list[str]
+    expected_key_claim: str
+    difficulty: str = "medium"
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "GoldExample":
+        return cls(
+            id=d["id"],
+            question=d["question"],
+            expected_arxiv_ids=d["expected_arxiv_ids"],
+            expected_key_claim=d["expected_key_claim"],
+            difficulty=d.get("difficulty", "medium"),
+        )
+
+
+@dataclass
+class EvalResult:
+    example: GoldExample
+    hits: list[Hit]
+    rag_answer: RAGAnswer
+    retrieval_recall: float   # fraction of expected IDs in top-k
+    citation_present: bool    # answer cites >= 1 expected paper
+    answer_correct: bool      # LLM judge says key claim is captured
+    answer_correct_raw: str   # raw judge response
+    latency_s: float
+    judge_tokens_in: int = 0
+    judge_tokens_out: int = 0
+
+
+@dataclass
+class EvalSummary:
+    n: int
+    retrieval_recall_at_k: float
+    citation_presence: float
+    answer_correctness: float
+    avg_latency_s: float
+    total_rag_tokens_in: int
+    total_rag_tokens_out: int
+    total_judge_tokens_in: int
+    total_judge_tokens_out: int
+    by_difficulty: dict[str, dict] = field(default_factory=dict)
+
+    def print_table(self) -> None:
+        print("\n" + "=" * 62)
+        print(f"  Baseline RAG Eval  |  n={self.n}")
+        print("=" * 62)
+        print(f"  Retrieval Recall@5 : {self.retrieval_recall_at_k:.1%}")
+        print(f"  Citation Presence  : {self.citation_presence:.1%}")
+        print(f"  Answer Correctness : {self.answer_correctness:.1%}")
+        print(f"  Avg Latency        : {self.avg_latency_s:.2f}s")
+        print(f"  RAG Tokens         : {self.total_rag_tokens_in:,} in / {self.total_rag_tokens_out:,} out")
+        print(f"  Judge Tokens       : {self.total_judge_tokens_in:,} in / {self.total_judge_tokens_out:,} out")
+        if self.by_difficulty:
+            print("\n  By difficulty:")
+            for diff, stats in sorted(self.by_difficulty.items()):
+                print(f"    {diff:8s}: recall={stats['recall']:.1%}  correct={stats['correct']:.1%}  n={stats['n']}")
+        print("=" * 62 + "\n")
+
+
+def load_gold_dataset(path: Path) -> list[GoldExample]:
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    return [GoldExample.from_dict(d) for d in data]
+
+
+def _retrieval_recall(hits: list[Hit], expected_ids: list[str]) -> float:
+    hit_ids = {h.arxiv_id for h in hits}
+    found = sum(1 for eid in expected_ids if eid in hit_ids)
+    return found / len(expected_ids)
+
+
+def _citation_present(answer_text: str, expected_ids: list[str]) -> bool:
+    return any(eid in answer_text for eid in expected_ids)
+
+
+_JUDGE_PROMPT = """You are an evaluator. Determine whether the given Answer adequately captures the Key Claim.
+
+Key Claim: {key_claim}
+
+Answer: {answer}
+
+Does the answer capture the essence of the key claim? Reply with exactly one word: YES or NO."""
+
+
+def _judge_answer(answer_text: str, key_claim: str, model: str = "llama-3.3-70b-versatile") -> tuple[bool, str, LLMResponse]:
+    prompt = _JUDGE_PROMPT.format(key_claim=key_claim, answer=answer_text)
+    resp = groq_generate(prompt, model=model)
+    raw = resp.text.strip().upper()
+    correct = raw.startswith("YES")
+    return correct, raw, resp
+
+
+def evaluate_example(
+    example: GoldExample,
+    hits: list[Hit],
+    rag_answer: RAGAnswer,
+    latency_s: float,
+    judge_model: str = "llama-3.3-70b-versatile",
+) -> EvalResult:
+    recall = _retrieval_recall(hits, example.expected_arxiv_ids)
+    cite_ok = _citation_present(rag_answer.answer, example.expected_arxiv_ids)
+    correct, raw, judge_resp = _judge_answer(rag_answer.answer, example.expected_key_claim, model=judge_model)
+
+    return EvalResult(
+        example=example,
+        hits=hits,
+        rag_answer=rag_answer,
+        retrieval_recall=recall,
+        citation_present=cite_ok,
+        answer_correct=correct,
+        answer_correct_raw=raw,
+        latency_s=latency_s,
+        judge_tokens_in=judge_resp.input_tokens or 0,
+        judge_tokens_out=judge_resp.output_tokens or 0,
+    )
+
+
+def summarize(results: list[EvalResult]) -> EvalSummary:
+    n = len(results)
+    recall = sum(r.retrieval_recall for r in results) / n
+    cite = sum(r.citation_present for r in results) / n
+    correct = sum(r.answer_correct for r in results) / n
+    avg_lat = sum(r.latency_s for r in results) / n
+
+    rag_in = sum(r.rag_answer.llm.input_tokens or 0 for r in results)
+    rag_out = sum(r.rag_answer.llm.output_tokens or 0 for r in results)
+    judge_in = sum(r.judge_tokens_in for r in results)
+    judge_out = sum(r.judge_tokens_out for r in results)
+
+    by_diff: dict[str, dict] = {}
+    for r in results:
+        d = r.example.difficulty
+        if d not in by_diff:
+            by_diff[d] = {"n": 0, "recall_sum": 0.0, "correct_sum": 0}
+        by_diff[d]["n"] += 1
+        by_diff[d]["recall_sum"] += r.retrieval_recall
+        by_diff[d]["correct_sum"] += int(r.answer_correct)
+
+    by_diff_summary = {
+        d: {
+            "n": v["n"],
+            "recall": v["recall_sum"] / v["n"],
+            "correct": v["correct_sum"] / v["n"],
+        }
+        for d, v in by_diff.items()
+    }
+
+    return EvalSummary(
+        n=n,
+        retrieval_recall_at_k=recall,
+        citation_presence=cite,
+        answer_correctness=correct,
+        avg_latency_s=avg_lat,
+        total_rag_tokens_in=rag_in,
+        total_rag_tokens_out=rag_out,
+        total_judge_tokens_in=judge_in,
+        total_judge_tokens_out=judge_out,
+        by_difficulty=by_diff_summary,
+    )
+
+
+def results_to_json(results: list[EvalResult], summary: EvalSummary) -> dict:
+    return {
+        "summary": {
+            "n": summary.n,
+            "retrieval_recall_at_k": summary.retrieval_recall_at_k,
+            "citation_presence": summary.citation_presence,
+            "answer_correctness": summary.answer_correctness,
+            "avg_latency_s": summary.avg_latency_s,
+            "total_rag_tokens_in": summary.total_rag_tokens_in,
+            "total_rag_tokens_out": summary.total_rag_tokens_out,
+            "total_judge_tokens_in": summary.total_judge_tokens_in,
+            "total_judge_tokens_out": summary.total_judge_tokens_out,
+            "by_difficulty": summary.by_difficulty,
+        },
+        "results": [
+            {
+                "id": r.example.id,
+                "difficulty": r.example.difficulty,
+                "question": r.example.question,
+                "expected_arxiv_ids": r.example.expected_arxiv_ids,
+                "retrieved_arxiv_ids": [h.arxiv_id for h in r.hits],
+                "retrieval_recall": r.retrieval_recall,
+                "citation_present": r.citation_present,
+                "answer_correct": r.answer_correct,
+                "answer_correct_raw": r.answer_correct_raw,
+                "latency_s": r.latency_s,
+                "answer": r.rag_answer.answer,
+            }
+            for r in results
+        ],
+    }

researchpath/index.py

@@ -0,0 +1,70 @@
+"""FAISS index over chunks. Flat inner-product index — exact, fast enough for ~1k chunks."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import faiss
+import numpy as np
+
+from researchpath.embeddings import EMBED_DIM, Embedder
+
+
+@dataclass(frozen=True)
+class Hit:
+    score: float
+    arxiv_id: str
+    page: int
+    chunk_idx: int   # within-paper index (from chunk dict)
+    global_idx: int  # position in the chunks list == FAISS vector index
+    text: str
+
+
+def _chunks_path(index_path: Path) -> Path:
+    return index_path.with_suffix(".chunks.json")
+
+
+def build_index(chunks: list[dict], embedder: Embedder, out_path: Path) -> None:
+    """Embed all chunks and persist a FAISS Flat-IP index + a parallel chunks.json."""
+    texts = [c["text"] for c in chunks]
+    embs = embedder.embed_documents(texts)
+    assert embs.shape == (len(chunks), EMBED_DIM), embs.shape
+
+    index = faiss.IndexFlatIP(EMBED_DIM)
+    index.add(embs)
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    faiss.write_index(index, str(out_path))
+    with open(_chunks_path(out_path), "w", encoding="utf-8") as f:
+        json.dump(chunks, f, ensure_ascii=False)
+
+
+def load_index(path: Path) -> tuple[faiss.Index, list[dict]]:
+    index = faiss.read_index(str(path))
+    with open(_chunks_path(path), encoding="utf-8") as f:
+        chunks = json.load(f)
+    return index, chunks
+
+
+def search(
+    index: faiss.Index, chunks: list[dict], embedder: Embedder, query: str, k: int = 5
+) -> list[Hit]:
+    q = embedder.embed_query(query).reshape(1, -1)
+    scores, ids = index.search(q, k)
+    out: list[Hit] = []
+    for score, idx in zip(scores[0], ids[0]):
+        if idx == -1:
+            continue
+        c = chunks[idx]
+        out.append(
+            Hit(
+                score=float(score),
+                arxiv_id=c["arxiv_id"],
+                page=c["page"],
+                chunk_idx=c["chunk_idx"],
+                global_idx=int(idx),
+                text=c["text"],
+            )
+        )
+    return out

researchpath/llm.py

@@ -0,0 +1,82 @@
+"""Thin LLM client wrappers for Gemini and Groq.
+
+Both functions return a uniform `LLMResponse` so the rest of the project
+doesn't care which provider produced the text.
+"""
+from __future__ import annotations
+
+import os
+import re
+import time
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+_GEMINI_MAX_RETRIES = 5
+
+
+@dataclass
+class LLMResponse:
+    text: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+
+
+def _parse_retry_delay(err_str: str, default: float = 15.0) -> float:
+    m = re.search(r"retry[^0-9]*([0-9]+(?:\.[0-9]+)?)\s*s", err_str, re.IGNORECASE)
+    if m:
+        return float(m.group(1)) + 1.0
+    return default
+
+
+def gemini_generate(prompt: str, model: str = "gemini-2.5-flash-lite") -> LLMResponse:
+    from google import genai
+
+    api_key = os.environ.get("GEMINI_API_KEY")
+    if not api_key:
+        raise RuntimeError("GEMINI_API_KEY not set. Copy .env.example to .env and fill it in.")
+
+    client = genai.Client(api_key=api_key)
+
+    for attempt in range(_GEMINI_MAX_RETRIES):
+        try:
+            response = client.models.generate_content(model=model, contents=prompt)
+            usage = getattr(response, "usage_metadata", None)
+            return LLMResponse(
+                text=response.text or "",
+                model=model,
+                input_tokens=getattr(usage, "prompt_token_count", None) if usage else None,
+                output_tokens=getattr(usage, "candidates_token_count", None) if usage else None,
+            )
+        except Exception as exc:
+            err_str = str(exc)
+            if "429" in err_str or "RESOURCE_EXHAUSTED" in err_str:
+                wait = _parse_retry_delay(err_str)
+                if attempt < _GEMINI_MAX_RETRIES - 1:
+                    print(f"  [gemini 429] waiting {wait:.0f}s (attempt {attempt + 1}/{_GEMINI_MAX_RETRIES})")
+                    time.sleep(wait)
+                    continue
+            raise
+
+
+def groq_generate(prompt: str, model: str = "llama-3.3-70b-versatile") -> LLMResponse:
+    from groq import Groq
+
+    api_key = os.environ.get("GROQ_API_KEY")
+    if not api_key:
+        raise RuntimeError("GROQ_API_KEY not set. Copy .env.example to .env and fill it in.")
+
+    client = Groq(api_key=api_key)
+    completion = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return LLMResponse(
+        text=completion.choices[0].message.content or "",
+        model=model,
+        input_tokens=completion.usage.prompt_tokens,
+        output_tokens=completion.usage.completion_tokens,
+    )

researchpath/parsing.py

@@ -0,0 +1,88 @@
+"""PDF parsing + chunking for the corpus.
+
+Each chunk records the source paper, page number, and chunk index so the
+agent can later cite back to the exact location in the PDF.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterator
+
+import pymupdf
+
+
+@dataclass(frozen=True)
+class Chunk:
+    arxiv_id: str
+    page: int  # 1-indexed for citations
+    chunk_idx: int  # within the paper, 0-indexed
+    text: str
+    n_chars: int
+
+
+# Sensible defaults for academic paper RAG. ~800 chars ≈ 200 tokens, with
+# 100-char overlap so concepts spanning chunk boundaries aren't sliced.
+DEFAULT_CHUNK_CHARS = 800
+DEFAULT_OVERLAP_CHARS = 100
+
+
+def _normalize_whitespace(text: str) -> str:
+    # Collapse hyphenated line breaks ("rein-\nforcement" -> "reinforcement"),
+    # then collapse runs of whitespace.
+    text = re.sub(r"-\n", "", text)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _split_into_chunks(
+    text: str,
+    chunk_chars: int = DEFAULT_CHUNK_CHARS,
+    overlap_chars: int = DEFAULT_OVERLAP_CHARS,
+) -> list[str]:
+    if not text:
+        return []
+    if len(text) <= chunk_chars:
+        return [text]
+
+    chunks: list[str] = []
+    start = 0
+    while start < len(text):
+        end = min(start + chunk_chars, len(text))
+        # try to break at a sentence/paragraph boundary near the end
+        if end < len(text):
+            window = text[end - 100 : end]
+            for sep in (". ", "? ", "! ", "\n"):
+                idx = window.rfind(sep)
+                if idx != -1:
+                    end = end - 100 + idx + len(sep)
+                    break
+        chunks.append(text[start:end].strip())
+        if end == len(text):
+            break
+        start = max(end - overlap_chars, start + 1)
+    return [c for c in chunks if c]
+
+
+def parse_pdf(pdf_path: Path) -> Iterator[Chunk]:
+    """Yield chunks for every page of a single paper."""
+    arxiv_id = pdf_path.stem
+    chunk_idx = 0
+    with pymupdf.open(pdf_path) as doc:
+        for page_num in range(doc.page_count):
+            raw = doc[page_num].get_text()
+            text = _normalize_whitespace(raw)
+            for piece in _split_into_chunks(text):
+                yield Chunk(
+                    arxiv_id=arxiv_id,
+                    page=page_num + 1,
+                    chunk_idx=chunk_idx,
+                    text=piece,
+                    n_chars=len(piece),
+                )
+                chunk_idx += 1
+
+
+def chunk_to_dict(chunk: Chunk) -> dict:
+    return asdict(chunk)

researchpath/planning.py

@@ -0,0 +1,174 @@
+"""Reading-path planner: given a target paper + what the user already knows,
+compute a topologically-sorted prerequisite chain.
+
+Algorithm (offline, no LLM):
+  1. BFS backwards from the target through the prerequisite graph.
+  2. Stop expanding a node when it (or one of its ancestors) is in `known`.
+  3. Topologically sort the resulting subgraph (Kahn's algorithm).
+  4. Annotate each step with the bridging concepts/why from the edges that
+     connect it to nodes the reader hasn't seen yet.
+
+This is the *deterministic* core of the agentic feature. The LLM layer
+(researchpath.planner_llm — to be added when token budget allows) augments
+this skeleton by:
+  - inferring additional concept-level dependencies the static graph misses,
+  - mapping the user's free-text background ("I know basic supervised
+    learning, no RL") to a `known` set,
+  - generating a per-step "what to focus on when reading this" rationale.
+
+Even with the LLM unavailable, this module produces a defensible reading
+plan for the canonical chains.
+"""
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from dataclasses import dataclass
+
+from researchpath.corpus import CANONICAL_RL_PAPERS, Paper
+from researchpath.prerequisites import Prerequisite, edges_into
+
+_PAPER_BY_ID: dict[str, Paper] = {p.arxiv_id: p for p in CANONICAL_RL_PAPERS}
+
+
+@dataclass(frozen=True)
+class ReadingStep:
+    paper: Paper
+    bridges_to: tuple[str, ...]   # arxiv_ids this step is a prerequisite for
+    concepts: tuple[str, ...]     # concepts this step introduces (union over outgoing edges)
+    why: str                      # combined rationale across outgoing edges
+
+
+@dataclass(frozen=True)
+class ReadingPlan:
+    target_id: str
+    known_ids: frozenset[str]
+    steps: tuple[ReadingStep, ...]   # in reading order; target is the last entry
+
+    def render_text(self) -> str:
+        if not self.steps:
+            return f"You're already ready to read {self.target_id} directly."
+        lines: list[str] = []
+        for i, step in enumerate(self.steps, 1):
+            p = step.paper
+            tag = "<- target" if p.arxiv_id == self.target_id else f"-> {', '.join(step.bridges_to)}"
+            lines.append(f"{i}. [{p.arxiv_id}] {p.tag} ({p.year}) — {p.title}")
+            lines.append(f"     bridges: {tag}")
+            if step.concepts:
+                lines.append(f"     concepts: {', '.join(step.concepts)}")
+            if step.why:
+                lines.append(f"     why: {step.why}")
+            lines.append("")
+        return "\n".join(lines).rstrip()
+
+
+def _bfs_backwards(target: str, known: frozenset[str]) -> set[str]:
+    """All paper IDs the user must read to reach `target`, excluding those in `known`."""
+    if target in known:
+        return set()
+
+    needed: set[str] = {target}
+    queue: deque[str] = deque([target])
+
+    while queue:
+        node = queue.popleft()
+        for edge in edges_into(node):
+            if edge.from_id in known:
+                continue
+            if edge.from_id not in needed:
+                needed.add(edge.from_id)
+                queue.append(edge.from_id)
+    return needed
+
+
+def _topo_sort(node_set: set[str]) -> list[str]:
+    """Kahn's algorithm restricted to the prerequisite subgraph induced by node_set.
+
+    Tie-breaks on (year, arxiv_id) so the ordering is deterministic and roughly
+    chronological — which lines up with reading order in RL.
+    """
+    in_degree: dict[str, int] = defaultdict(int)
+    out_edges: dict[str, list[str]] = defaultdict(list)
+
+    for node in node_set:
+        for edge in edges_into(node):
+            if edge.from_id in node_set:
+                out_edges[edge.from_id].append(node)
+                in_degree[node] += 1
+
+    ready: list[str] = sorted(
+        [n for n in node_set if in_degree[n] == 0],
+        key=lambda nid: (_PAPER_BY_ID[nid].year, nid),
+    )
+    out: list[str] = []
+
+    while ready:
+        node = ready.pop(0)
+        out.append(node)
+        for child in out_edges.get(node, []):
+            in_degree[child] -= 1
+            if in_degree[child] == 0:
+                ready.append(child)
+        ready.sort(key=lambda nid: (_PAPER_BY_ID[nid].year, nid))
+
+    if len(out) != len(node_set):
+        raise ValueError(
+            f"Cycle in prerequisite graph; ordered {len(out)}/{len(node_set)} nodes."
+        )
+    return out
+
+
+def _build_step(paper_id: str, ordered_ids: list[str]) -> ReadingStep:
+    """Aggregate outgoing edges (paper_id -> later) into a single annotated step."""
+    paper = _PAPER_BY_ID[paper_id]
+    later = set(ordered_ids[ordered_ids.index(paper_id) + 1 :])
+
+    concepts: list[str] = []
+    bridges: list[str] = []
+    whys: list[str] = []
+    seen_concepts: set[str] = set()
+
+    for edge in _outgoing(paper_id):
+        if edge.to_id not in later:
+            continue
+        bridges.append(edge.to_id)
+        for c in edge.concepts:
+            if c not in seen_concepts:
+                concepts.append(c)
+                seen_concepts.add(c)
+        whys.append(edge.why)
+
+    why = " ".join(whys)
+    return ReadingStep(
+        paper=paper,
+        bridges_to=tuple(bridges),
+        concepts=tuple(concepts),
+        why=why,
+    )
+
+
+def _outgoing(arxiv_id: str) -> list[Prerequisite]:
+    from researchpath.prerequisites import STATIC_PREREQUISITES
+    return [e for e in STATIC_PREREQUISITES if e.from_id == arxiv_id]
+
+
+def plan_reading_path(target_id: str, known_ids: set[str] | None = None) -> ReadingPlan:
+    """Compute the prerequisite reading path for `target_id`.
+
+    Args:
+        target_id: arxiv ID of the paper the user wants to read.
+        known_ids: arxiv IDs the user already understands (BFS stops here).
+
+    Returns:
+        A ReadingPlan whose `steps` are in reading order, ending with the target.
+    """
+    if target_id not in _PAPER_BY_ID:
+        raise ValueError(f"Unknown target paper: {target_id}")
+    known = frozenset(known_ids or ())
+
+    needed = _bfs_backwards(target_id, known)
+    if not needed:
+        return ReadingPlan(target_id=target_id, known_ids=known, steps=())
+
+    ordered_ids = _topo_sort(needed)
+    steps = tuple(_build_step(pid, ordered_ids) for pid in ordered_ids)
+    return ReadingPlan(target_id=target_id, known_ids=known, steps=steps)

researchpath/prerequisites.py

@@ -0,0 +1,174 @@
+"""Hand-curated prerequisite graph for the canonical RL corpus.
+
+Each edge `(from_id, to_id)` means: to read `to_id` productively, the reader
+should already understand the ideas in `from_id`. The `concepts` field names
+the bridging idea(s); `why` is a short rationale shown to the user when the
+planner walks this edge.
+
+This is the static seed for the agentic planning loop. At runtime the agent
+augments these edges with LLM-extracted concept dependencies, but the static
+graph guarantees the planner never produces nonsense for the canonical chain
+(DQN -> Double DQN -> Dueling DQN -> Rainbow, etc.) even when the LLM is
+unavailable or rate-limited.
+
+Edge sources: the dependency chains are well-known in the RL literature and
+match how the papers cite each other (verifiable by reading the related-work
+sections of the dependent papers).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Prerequisite:
+    from_id: str   # arxiv_id of the prerequisite paper
+    to_id: str     # arxiv_id of the dependent paper
+    concepts: tuple[str, ...]  # bridging ideas
+    why: str       # short user-facing rationale
+
+
+STATIC_PREREQUISITES: tuple[Prerequisite, ...] = (
+    # --- value-based chain ---
+    Prerequisite(
+        from_id="1312.5602", to_id="1509.06461",
+        concepts=("Q-learning", "experience replay", "target network"),
+        why="Double DQN modifies the DQN max-operator. You need DQN's "
+             "Q-learning + replay + target-network setup to see what's being changed.",
+    ),
+    Prerequisite(
+        from_id="1509.06461", to_id="1511.06581",
+        concepts=("overestimation bias", "decoupled action selection/evaluation"),
+        why="Dueling builds on Double DQN's evaluation update; both share the same "
+             "training loop and Atari benchmark.",
+    ),
+    Prerequisite(
+        from_id="1312.5602", to_id="1511.06581",
+        concepts=("Q-network architecture", "Atari pipeline"),
+        why="Dueling redesigns DQN's network architecture — needed to see the original.",
+    ),
+    Prerequisite(
+        from_id="1312.5602", to_id="1511.05952",
+        concepts=("experience replay", "Q-learning"),
+        why="PER replaces DQN's uniform replay sampling with priority-weighted sampling. "
+             "The mechanism only makes sense with DQN's replay buffer as the starting point.",
+    ),
+    Prerequisite(
+        from_id="1509.06461", to_id="1710.02298",
+        concepts=("Double Q-learning",),
+        why="Rainbow includes Double Q-learning as one of its six components.",
+    ),
+    Prerequisite(
+        from_id="1511.06581", to_id="1710.02298",
+        concepts=("dueling networks",),
+        why="Rainbow includes dueling networks as one of its six components.",
+    ),
+    Prerequisite(
+        from_id="1511.05952", to_id="1710.02298",
+        concepts=("prioritized experience replay",),
+        why="Rainbow includes PER as one of its six components.",
+    ),
+    Prerequisite(
+        from_id="1312.5602", to_id="1710.02298",
+        concepts=("DQN baseline",),
+        why="Rainbow's ablations are all measured against the DQN baseline.",
+    ),
+
+    # --- policy-gradient chain ---
+    Prerequisite(
+        from_id="1502.05477", to_id="1506.02438",
+        concepts=("trust region", "policy gradient",
+                  "natural gradient via conjugate gradient"),
+        why="GAE was developed alongside TRPO and is typically paired with it. "
+             "GAE's experiments use TRPO as the policy update.",
+    ),
+    Prerequisite(
+        from_id="1502.05477", to_id="1707.06347",
+        concepts=("trust region", "clipped surrogate objective"),
+        why="PPO is explicitly 'a simpler, more stable alternative to TRPO'. "
+             "The clipped objective is only legible against the TRPO constraint it replaces.",
+    ),
+    Prerequisite(
+        from_id="1506.02438", to_id="1707.06347",
+        concepts=("generalized advantage estimation",),
+        why="PPO uses GAE for advantage estimation in all its experiments.",
+    ),
+
+    # --- actor-critic chain ---
+    Prerequisite(
+        from_id="1312.5602", to_id="1602.01783",
+        concepts=("Q-learning", "replay vs on-policy"),
+        why="A3C is positioned as a parallel-actor alternative to DQN's replay-based "
+             "training. Need to understand DQN to see why asynchrony substitutes for replay.",
+    ),
+    Prerequisite(
+        from_id="1312.5602", to_id="1509.02971",
+        concepts=("DQN target network", "off-policy Q-learning"),
+        why="DDPG is 'DQN for continuous actions' — same target-network and replay-buffer "
+             "machinery, but with a deterministic actor on top of the critic.",
+    ),
+    Prerequisite(
+        from_id="1509.02971", to_id="1801.01290",
+        concepts=("deterministic policy gradient", "actor-critic", "replay buffer"),
+        why="SAC is the maximum-entropy successor to DDPG for continuous control. "
+             "Understanding DDPG's actor-critic + replay setup is needed to see what SAC changes.",
+    ),
+    Prerequisite(
+        from_id="1602.01783", to_id="1802.01561",
+        concepts=("asynchronous actors", "on-policy gradient"),
+        why="IMPALA builds directly on A3C's parallel-actor idea but decouples "
+             "acting from learning via a learner-actor architecture and V-trace correction.",
+    ),
+
+    # --- model-based / planning chain ---
+    Prerequisite(
+        from_id="1312.5602", to_id="1911.08265",
+        concepts=("Q-values", "Atari benchmark"),
+        why="MuZero is measured against DQN-family baselines on Atari. "
+             "Its learned value function replaces the DQN Q-network.",
+    ),
+    Prerequisite(
+        from_id="1602.01783", to_id="1911.08265",
+        concepts=("policy gradient", "MCTS + neural network"),
+        why="MuZero combines MCTS search with a learned model; A3C's policy-gradient "
+             "framework is the RL substrate underneath the search.",
+    ),
+    Prerequisite(
+        from_id="1911.08265", to_id="2301.04104",
+        concepts=("world model", "latent-space planning"),
+        why="DreamerV3 is world-model RL generalized beyond board games; "
+             "MuZero's learned model + latent-space planning is the direct antecedent.",
+    ),
+
+    # --- sequence modeling for RL ---
+    Prerequisite(
+        from_id="1707.06347", to_id="2106.01345",
+        concepts=("return-conditioned policy", "offline RL"),
+        why="Decision Transformer frames offline RL as sequence modeling; "
+             "PPO is the canonical online policy-gradient baseline it's contrasted against.",
+    ),
+
+    # --- RLHF chain ---
+    Prerequisite(
+        from_id="1707.06347", to_id="2203.02155",
+        concepts=("PPO", "KL-constrained policy optimization"),
+        why="InstructGPT uses PPO as the RL optimizer in its RLHF pipeline. "
+             "The KL penalty and clipped objective are central to why it works.",
+    ),
+    Prerequisite(
+        from_id="2203.02155", to_id="2305.18290",
+        concepts=("RLHF pipeline", "reward model", "KL-constrained PPO"),
+        why="DPO is explicitly framed as 'RLHF without RL'. The InstructGPT paper "
+             "is the standard reference for the RLHF pipeline that DPO replaces.",
+    ),
+)
+
+
+def edges_into(arxiv_id: str) -> list[Prerequisite]:
+    """Direct prerequisites of `arxiv_id` (i.e. papers that should be read before it)."""
+    return [p for p in STATIC_PREREQUISITES if p.to_id == arxiv_id]
+
+
+def edges_from(arxiv_id: str) -> list[Prerequisite]:
+    """Direct dependents of `arxiv_id` (i.e. papers that build on it)."""
+    return [p for p in STATIC_PREREQUISITES if p.from_id == arxiv_id]

researchpath/rag.py

@@ -0,0 +1,74 @@
+"""Baseline RAG: retrieve top-k chunks, hand them to Gemini with strict citation rules.
+
+This is the first measurable system. Day 4 adds the eval harness so we can
+quantify how well it works before optimizing.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from collections.abc import Callable
+
+from researchpath.corpus import CANONICAL_RL_PAPERS
+from researchpath.index import Hit
+from researchpath.llm import LLMResponse, gemini_generate, groq_generate
+
+_TAG_BY_ID = {p.arxiv_id: p.tag for p in CANONICAL_RL_PAPERS}
+
+
+SYSTEM_PROMPT = """You are an expert RL research assistant. Answer the user's question using ONLY the provided source chunks. Follow these rules strictly:
+
+1. Cite every factual claim using the format [arxiv_id, p<page>], e.g. [1707.06347, p3].
+2. If the sources don't contain enough information to answer, say so explicitly. Do NOT speculate beyond the sources.
+3. Be concise. Prefer 2-4 short paragraphs over long prose.
+4. If the question is conceptual (not factual), still ground your explanation in the cited sources."""
+
+
+@dataclass(frozen=True)
+class RAGAnswer:
+    question: str
+    answer: str
+    hits: list[Hit]
+    llm: LLMResponse
+
+
+def _format_sources(hits: list[Hit]) -> str:
+    blocks: list[str] = []
+    for h in hits:
+        tag = _TAG_BY_ID.get(h.arxiv_id, "?")
+        header = f"[{h.arxiv_id}, p{h.page}]  ({tag})"
+        blocks.append(f"{header}\n{h.text}")
+    return "\n\n---\n\n".join(blocks)
+
+
+def build_prompt(question: str, hits: list[Hit]) -> str:
+    sources = _format_sources(hits)
+    return f"""{SYSTEM_PROMPT}
+
+# Sources
+
+{sources}
+
+# Question
+
+{question}
+
+# Answer
+"""
+
+
+def answer(
+    question: str,
+    hits: list[Hit],
+    model: str = "gemini-2.5-flash-lite",
+    generate_fn: Callable[..., LLMResponse] | None = None,
+) -> RAGAnswer:
+    prompt = build_prompt(question, hits)
+    fn = generate_fn or gemini_generate
+    llm = fn(prompt, model=model)
+    return RAGAnswer(question=question, answer=llm.text, hits=hits, llm=llm)
+
+
+def answer_groq(question: str, hits: list[Hit], model: str = "llama-3.3-70b-versatile") -> RAGAnswer:
+    """Groq-backed answer — use during eval to avoid Gemini rate limits."""
+    return answer(question, hits, model=model, generate_fn=groq_generate)

researchpath/retrieval.py

@@ -0,0 +1,170 @@
+"""Retrieval strategies: BM25, FAISS vector, hybrid RRF fusion, cross-encoder rerank.
+
+Hybrid retrieval is the first optimization pass over the baseline FAISS-only system.
+BM25 catches exact-term hits (e.g. "conjugate gradient", "Polyak averaging",
+"six components") that dense embeddings can miss when the query term is rare in
+the training distribution of the embedding model.
+
+Reciprocal Rank Fusion (RRF) combines rankings without needing to normalize
+incompatible score spaces (inner-product vs BM25 counts):
+    rrf(d) = sum_i  1 / (k + rank_i(d))
+where k=60 is the standard constant that dampens the impact of high ranks.
+
+The cross-encoder reranker is an over-the-top stage that scores each
+(query, chunk) pair jointly via a small transformer, replacing the bi-encoder
+similarity used for first-stage retrieval. It's slower (no caching of chunk
+embeddings) but more accurate, so we only run it on the top-N candidates from
+hybrid retrieval — cheap reranker over expensive joint scoring.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+import faiss
+import numpy as np
+from rank_bm25 import BM25Okapi
+
+from researchpath.embeddings import Embedder
+from researchpath.index import Hit
+from researchpath.index import search as faiss_search
+
+_RRF_K = 60
+DEFAULT_RERANKER_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+
+_STOP_WORDS = frozenset(
+    "a an the and or but if of in on at to for with by from is are was were be been"
+    " being have has had do does did will would could should may might shall can"
+    " it its this that these those he she they we you i me my your our their"
+    " what which who how when where why what's does it's what's that's there's"
+    " not no nor so very just also both each few more most other some such than"
+    " too very as into up out down about above after before".split()
+)
+
+
+def _tokenize(text: str) -> list[str]:
+    """Lowercase, keep hyphenated tokens, strip stop words.
+
+    Stop-word filtering is critical for BM25 over academic text: queries like
+    'What does GAE stand for' would otherwise match InstructGPT appendix QA
+    sections via 'what', 'does', 'it' rather than the actual term 'gae'.
+    """
+    tokens = re.findall(r"[a-z0-9]+(?:-[a-z0-9]+)*", text.lower())
+    return [t for t in tokens if t not in _STOP_WORDS]
+
+
+class BM25Retriever:
+    """BM25Okapi over the chunk corpus. Built in-memory from chunks list."""
+
+    def __init__(self, chunks: list[dict]) -> None:
+        self.chunks = chunks
+        tokenized = [_tokenize(c["text"]) for c in chunks]
+        self._bm25 = BM25Okapi(tokenized)
+
+    def search(self, query: str, k: int = 20) -> list[tuple[int, float]]:
+        """Return (original_chunk_list_index, bm25_score) for top-k chunks."""
+        tokens = _tokenize(query)
+        scores = self._bm25.get_scores(tokens)
+        top_idx = np.argsort(scores)[::-1][:k]
+        return [(int(i), float(scores[i])) for i in top_idx if scores[i] > 0]
+
+
+class HybridRetriever:
+    """Fuses FAISS dense search and BM25 sparse search via Reciprocal Rank Fusion."""
+
+    def __init__(
+        self,
+        index: faiss.Index,
+        chunks: list[dict],
+        embedder: Embedder,
+        fetch_k: int = 20,
+    ) -> None:
+        self.index = index
+        self.chunks = chunks
+        self.embedder = embedder
+        self.fetch_k = fetch_k
+        self._bm25 = BM25Retriever(chunks)
+
+    def search(self, query: str, k: int = 5) -> list[Hit]:
+        fetch = max(self.fetch_k, k * 4)
+
+        # --- dense retrieval: key by global_idx (FAISS vector position) ---
+        dense_hits = faiss_search(self.index, self.chunks, self.embedder, query, k=fetch)
+        dense_rank: dict[int, int] = {h.global_idx: rank for rank, h in enumerate(dense_hits)}
+
+        # --- sparse retrieval: BM25 returns (list_position, score) = (global_idx, score) ---
+        sparse_results = self._bm25.search(query, k=fetch)
+        sparse_rank: dict[int, int] = {gidx: rank for rank, (gidx, _) in enumerate(sparse_results)}
+
+        # --- RRF fusion over global_idx ---
+        candidates = set(dense_rank) | set(sparse_rank)
+        rrf: dict[int, float] = {}
+        for gidx in candidates:
+            score = 0.0
+            if gidx in dense_rank:
+                score += 1.0 / (_RRF_K + dense_rank[gidx])
+            if gidx in sparse_rank:
+                score += 1.0 / (_RRF_K + sparse_rank[gidx])
+            rrf[gidx] = score
+
+        top_k = sorted(rrf, key=rrf.__getitem__, reverse=True)[:k]
+
+        out: list[Hit] = []
+        for gidx in top_k:
+            c = self.chunks[gidx]
+            out.append(
+                Hit(
+                    score=rrf[gidx],
+                    arxiv_id=c["arxiv_id"],
+                    page=c["page"],
+                    chunk_idx=c["chunk_idx"],
+                    global_idx=gidx,
+                    text=c["text"],
+                )
+            )
+        return out
+
+
+class Reranker:
+    """Cross-encoder reranker: jointly scores (query, chunk) pairs.
+
+    Wraps any retriever (FAISS, BM25, or HybridRetriever): fetches `fetch_k`
+    candidates from the base retriever, then runs the cross-encoder on each
+    (query, chunk_text) pair to produce a final relevance score, returning
+    the top-k by reranked score.
+    """
+
+    def __init__(
+        self,
+        base_retriever: HybridRetriever,
+        model_name: str = DEFAULT_RERANKER_MODEL,
+        fetch_k: int = 20,
+    ) -> None:
+        from sentence_transformers import CrossEncoder
+
+        self.base = base_retriever
+        self.fetch_k = fetch_k
+        self._cross_encoder = CrossEncoder(model_name)
+
+    def search(self, query: str, k: int = 5) -> list[Hit]:
+        candidates = self.base.search(query, k=self.fetch_k)
+        if not candidates:
+            return []
+
+        pairs = [(query, h.text) for h in candidates]
+        scores = self._cross_encoder.predict(pairs)
+
+        ranked = sorted(zip(candidates, scores), key=lambda t: float(t[1]), reverse=True)
+        out: list[Hit] = []
+        for h, score in ranked[:k]:
+            out.append(
+                Hit(
+                    score=float(score),
+                    arxiv_id=h.arxiv_id,
+                    page=h.page,
+                    chunk_idx=h.chunk_idx,
+                    global_idx=h.global_idx,
+                    text=h.text,
+                )
+            )
+        return out

scripts/ask.py

@@ -0,0 +1,90 @@
+"""Ask a question against the indexed RL corpus.
+
+Usage:
+    uv run python scripts/ask.py "What is the main idea of PPO?"
+    uv run python scripts/ask.py --k 8 "How does Rainbow combine Double DQN and PER?"
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from researchpath.embeddings import Embedder
+from researchpath.index import load_index, search
+from researchpath.rag import answer
+from researchpath.retrieval import HybridRetriever, Reranker
+
+console = Console()
+ROOT = Path(__file__).resolve().parents[1]
+INDEX_PATH = ROOT / "data" / "index.faiss"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Ask the RL corpus a question.")
+    parser.add_argument("question", help="Question to ask.")
+    parser.add_argument("--k", type=int, default=5, help="Top-k chunks to retrieve (default: 5).")
+    parser.add_argument("--hybrid", action="store_true", help="Use BM25+FAISS hybrid retrieval.")
+    parser.add_argument("--rerank", action="store_true", help="Apply cross-encoder reranking on retrieved candidates.")
+    parser.add_argument(
+        "--show-sources",
+        action="store_true",
+        help="Print the retrieved chunks before the answer.",
+    )
+    args = parser.parse_args()
+
+    if not INDEX_PATH.exists():
+        console.print(f"[red]No index at {INDEX_PATH}. Run scripts/build_index.py first.[/red]")
+        return 1
+
+    if args.rerank:
+        mode = "hybrid+rerank (BM25+FAISS+CrossEncoder)" if args.hybrid else "dense+rerank (FAISS+CrossEncoder)"
+    else:
+        mode = "hybrid (BM25+FAISS)" if args.hybrid else "dense (FAISS)"
+    console.print(f"[bold cyan]Q:[/bold cyan] {args.question}  [dim][retrieval: {mode}][/dim]\n")
+
+    index, chunks = load_index(INDEX_PATH)
+    embedder = Embedder()
+    if args.rerank:
+        base = HybridRetriever(index, chunks, embedder) if args.hybrid else None
+        if base is None:
+            # Wrap dense FAISS in a hybrid-compatible interface for the reranker
+            base = HybridRetriever(index, chunks, embedder)
+        reranker = Reranker(base)
+        hits = reranker.search(args.question, k=args.k)
+    elif args.hybrid:
+        retriever = HybridRetriever(index, chunks, embedder)
+        hits = retriever.search(args.question, k=args.k)
+    else:
+        hits = search(index, chunks, embedder, args.question, k=args.k)
+
+    if args.show_sources:
+        for i, h in enumerate(hits, 1):
+            console.print(
+                Panel(
+                    h.text,
+                    title=f"#{i}  [{h.arxiv_id}, p{h.page}]  score={h.score:.3f}",
+                    border_style="dim",
+                )
+            )
+        console.print()
+
+    result = answer(args.question, hits)
+
+    console.print(Panel(Markdown(result.answer), title="Answer", border_style="green"))
+    console.print(
+        f"\n[dim]Retrieved {len(hits)} chunks  |  "
+        f"model: {result.llm.model}  |  "
+        f"tokens: {result.llm.input_tokens} in / {result.llm.output_tokens} out[/dim]"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/build_index.py

@@ -0,0 +1,52 @@
+"""Embed every chunk in data/chunks.jsonl and persist a FAISS index.
+
+Usage:
+    uv run python scripts/build_index.py
+"""
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from rich.console import Console
+
+from researchpath.embeddings import Embedder
+from researchpath.index import build_index
+
+console = Console()
+ROOT = Path(__file__).resolve().parents[1]
+CHUNKS_PATH = ROOT / "data" / "chunks.jsonl"
+INDEX_PATH = ROOT / "data" / "index.faiss"
+
+
+def main() -> int:
+    if not CHUNKS_PATH.exists():
+        console.print(f"[red]Missing {CHUNKS_PATH}. Run scripts/parse_corpus.py first.[/red]")
+        return 1
+
+    chunks: list[dict] = []
+    with open(CHUNKS_PATH, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                chunks.append(json.loads(line))
+
+    console.print(f"[bold]Embedding {len(chunks)} chunks with BAAI/bge-small-en-v1.5[/bold]")
+    console.print("[dim](first run downloads ~133MB model from HF Hub; subsequent runs are cached)[/dim]\n")
+
+    t0 = time.time()
+    embedder = Embedder()
+    build_index(chunks, embedder, INDEX_PATH)
+    dt = time.time() - t0
+
+    console.print(f"\n[green]Wrote {INDEX_PATH.relative_to(ROOT)} in {dt:.1f}s[/green]")
+    console.print(f"[green]Wrote {INDEX_PATH.with_suffix('.chunks.json').relative_to(ROOT)}[/green]")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/fetch_corpus.py

@@ -0,0 +1,160 @@
+"""Download canonical RL papers from arXiv into data/papers/.
+
+Idempotent: papers already on disk (with valid PDF content) are skipped.
+Truncated/corrupt PDFs are auto-deleted and retried.
+
+Uses `requests` with streaming + chunked writes — the `arxiv` library's
+built-in downloader was truncating large PDFs at power-of-2 byte boundaries
+on Windows.
+
+Usage:
+    uv run python scripts/fetch_corpus.py
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import pymupdf
+import requests
+from rich.console import Console
+from rich.table import Table
+
+from researchpath.corpus import CANONICAL_RL_PAPERS
+
+console = Console()
+DATA_DIR = Path(__file__).resolve().parents[1] / "data" / "papers"
+
+USER_AGENT = "ResearchPath/0.1.0 (mailto:chetanchowdary01@gmail.com)"
+MIN_PDF_BYTES = 50_000
+INTER_REQUEST_DELAY = 12  # arXiv asks for >=3s; PDF endpoint rate-limits harder
+MAX_ATTEMPTS = 3
+RETRY_BACKOFF_SEC = 30
+DOWNLOAD_TIMEOUT = 180
+
+
+def validate_pdf(path: Path) -> tuple[bool, str]:
+    if not path.exists():
+        return False, "file missing"
+    if path.stat().st_size < MIN_PDF_BYTES:
+        return False, f"too small ({path.stat().st_size} bytes)"
+    try:
+        with pymupdf.open(path) as doc:
+            if doc.page_count < 1:
+                return False, "0 pages"
+            _ = doc[0].get_text()
+        return True, "ok"
+    except Exception as e:
+        return False, f"parse error: {e}"
+
+
+def download_pdf(arxiv_id: str, dest: Path) -> tuple[bool, str]:
+    """Stream a single PDF from arXiv. Returns (success, message)."""
+    url = f"https://arxiv.org/pdf/{arxiv_id}.pdf"
+    headers = {"User-Agent": USER_AGENT}
+    try:
+        with requests.get(url, headers=headers, stream=True, timeout=DOWNLOAD_TIMEOUT) as r:
+            if r.status_code == 429:
+                return False, "rate limited (429)"
+            r.raise_for_status()
+            expected = int(r.headers.get("Content-Length", "0") or "0")
+            written = 0
+            with open(dest, "wb") as f:
+                for chunk in r.iter_content(chunk_size=64 * 1024):
+                    if chunk:
+                        f.write(chunk)
+                        written += len(chunk)
+            if expected and written < expected:
+                dest.unlink(missing_ok=True)
+                return False, f"truncated: {written}/{expected} bytes"
+        return True, f"ok ({written} bytes)"
+    except requests.exceptions.HTTPError as e:
+        return False, f"http {e.response.status_code}"
+    except Exception as e:
+        return False, f"network: {e}"
+
+
+def fetch_with_retry(arxiv_id: str, dest: Path) -> tuple[bool, str]:
+    for attempt in range(1, MAX_ATTEMPTS + 1):
+        ok, msg = download_pdf(arxiv_id, dest)
+        if not ok:
+            if attempt < MAX_ATTEMPTS:
+                console.print(f"  [dim]attempt {attempt}: {msg}; backing off {RETRY_BACKOFF_SEC}s[/dim]")
+                time.sleep(RETRY_BACKOFF_SEC)
+                continue
+            return False, msg
+
+        valid, vmsg = validate_pdf(dest)
+        if valid:
+            return True, msg
+        dest.unlink(missing_ok=True)
+        if attempt < MAX_ATTEMPTS:
+            console.print(f"  [dim]attempt {attempt}: invalid pdf ({vmsg}); backing off {RETRY_BACKOFF_SEC}s[/dim]")
+            time.sleep(RETRY_BACKOFF_SEC)
+    return False, "exhausted retries"
+
+
+def main() -> int:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+    n_ok = 0
+    n_skip = 0
+    n_fail = 0
+    failures: list[tuple[str, str]] = []
+
+    pending = []
+    for paper in CANONICAL_RL_PAPERS:
+        target = DATA_DIR / f"{paper.arxiv_id}.pdf"
+        if target.exists():
+            ok, reason = validate_pdf(target)
+            if ok:
+                console.print(f"[yellow]SKIP[/yellow]  {paper.arxiv_id}  ({paper.tag})")
+                n_skip += 1
+                continue
+            console.print(f"[magenta]REDO[/magenta]  {paper.arxiv_id}  ({paper.tag}) — {reason}")
+            target.unlink()
+        pending.append(paper)
+
+    if not pending:
+        console.print("\n[bold green]All papers already present and valid.[/bold green]")
+        return 0
+
+    console.print(f"\n[bold]Need to download {len(pending)} paper(s). Spacing requests by {INTER_REQUEST_DELAY}s.[/bold]\n")
+
+    for i, paper in enumerate(pending):
+        target = DATA_DIR / f"{paper.arxiv_id}.pdf"
+        console.print(f"[cyan]FETCH[/cyan] {paper.arxiv_id}  {paper.tag} - {paper.title[:60]}")
+        ok, msg = fetch_with_retry(paper.arxiv_id, target)
+        if ok:
+            console.print(f"  [green]ok[/green] {msg}")
+            n_ok += 1
+        else:
+            console.print(f"[red]FAIL[/red]  {paper.arxiv_id}: {msg}")
+            failures.append((paper.arxiv_id, msg))
+            n_fail += 1
+        # Spacing between successful papers (within retry, the backoff is already 30s)
+        if i + 1 < len(pending):
+            time.sleep(INTER_REQUEST_DELAY)
+
+    console.print()
+    table = Table(title="Corpus fetch summary")
+    table.add_column("Outcome", style="bold")
+    table.add_column("Count", justify="right")
+    table.add_row("[green]Downloaded[/green]", str(n_ok))
+    table.add_row("[yellow]Skipped (already valid)[/yellow]", str(n_skip))
+    table.add_row("[red]Failed[/red]", str(n_fail))
+    console.print(table)
+
+    if failures:
+        console.print("\n[bold red]Failures (re-run later to retry):[/bold red]")
+        for arxiv_id, err in failures:
+            console.print(f"  {arxiv_id}: {err}")
+
+    return 0 if n_fail == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/parse_corpus.py

@@ -0,0 +1,67 @@
+"""Parse every valid PDF in data/papers/ into a single chunks JSONL.
+
+Output: data/chunks.jsonl  (one chunk per line, ready for embedding)
+
+Usage:
+    uv run python scripts/parse_corpus.py
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from rich.console import Console
+from rich.table import Table
+
+from researchpath.corpus import CANONICAL_RL_PAPERS
+from researchpath.parsing import chunk_to_dict, parse_pdf
+
+console = Console()
+ROOT = Path(__file__).resolve().parents[1]
+PAPERS_DIR = ROOT / "data" / "papers"
+CHUNKS_PATH = ROOT / "data" / "chunks.jsonl"
+
+
+def main() -> int:
+    by_id = {p.arxiv_id: p for p in CANONICAL_RL_PAPERS}
+
+    pdfs = sorted(PAPERS_DIR.glob("*.pdf"))
+    if not pdfs:
+        console.print("[red]No PDFs found in data/papers/. Run fetch_corpus.py first.[/red]")
+        return 1
+
+    table = Table(title="Parse summary")
+    table.add_column("Paper", style="bold")
+    table.add_column("Tag")
+    table.add_column("Chunks", justify="right")
+    table.add_column("Chars", justify="right")
+
+    total_chunks = 0
+    total_chars = 0
+
+    with open(CHUNKS_PATH, "w", encoding="utf-8") as out:
+        for pdf in pdfs:
+            paper_meta = by_id.get(pdf.stem)
+            tag = paper_meta.tag if paper_meta else "?"
+            n = 0
+            chars = 0
+            for chunk in parse_pdf(pdf):
+                out.write(json.dumps(chunk_to_dict(chunk), ensure_ascii=False) + "\n")
+                n += 1
+                chars += chunk.n_chars
+            table.add_row(pdf.stem, tag, str(n), f"{chars:,}")
+            total_chunks += n
+            total_chars += chars
+
+    console.print(table)
+    console.print(
+        f"\n[bold green]Wrote {total_chunks} chunks ({total_chars:,} chars) to {CHUNKS_PATH.relative_to(ROOT)}[/bold green]"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/plan.py

@@ -0,0 +1,85 @@
+"""Compute a prerequisite reading path for a target RL paper.
+
+Usage:
+    uv run python scripts/plan.py --target 1710.02298                   # plan for Rainbow, no prior knowledge
+    uv run python scripts/plan.py --target 1710.02298 --known 1312.5602  # already know DQN
+    uv run python scripts/plan.py --target 1710.02298 --known DQN,A3C   # use tags or arxiv IDs
+    uv run python scripts/plan.py --list                                # list all canonical papers
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from rich.console import Console
+from rich.panel import Panel
+
+from researchpath.corpus import CANONICAL_RL_PAPERS
+from researchpath.planning import plan_reading_path
+
+console = Console()
+_TAG_TO_ID = {p.tag.lower(): p.arxiv_id for p in CANONICAL_RL_PAPERS}
+_ID_TO_PAPER = {p.arxiv_id: p for p in CANONICAL_RL_PAPERS}
+
+
+def _resolve(token: str) -> str:
+    """Accept either an arxiv ID or a paper tag (case-insensitive)."""
+    token = token.strip()
+    if token in _ID_TO_PAPER:
+        return token
+    if token.lower() in _TAG_TO_ID:
+        return _TAG_TO_ID[token.lower()]
+    raise SystemExit(f"Unknown paper: {token!r}. Use --list to see options.")
+
+
+def _list_papers() -> None:
+    console.print("[bold cyan]Canonical RL papers:[/bold cyan]\n")
+    for p in CANONICAL_RL_PAPERS:
+        console.print(f"  [{p.arxiv_id}]  [bold]{p.tag:20s}[/bold]  ({p.year})  {p.title}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan a prerequisite reading path.")
+    parser.add_argument("--target", help="arxiv ID or tag of the paper you want to read.")
+    parser.add_argument(
+        "--known",
+        default="",
+        help="Comma-separated arxiv IDs or tags you already understand (default: none).",
+    )
+    parser.add_argument("--list", action="store_true", help="List all canonical papers.")
+    args = parser.parse_args()
+
+    if args.list:
+        _list_papers()
+        return 0
+
+    if not args.target:
+        parser.error("--target is required (or pass --list).")
+
+    target_id = _resolve(args.target)
+    known_ids = {_resolve(t) for t in args.known.split(",") if t.strip()}
+
+    plan = plan_reading_path(target_id, known_ids=known_ids)
+    target = _ID_TO_PAPER[target_id]
+
+    header = f"Reading path for [{target.arxiv_id}] {target.tag} — {target.title}"
+    if known_ids:
+        known_tags = ", ".join(sorted(_ID_TO_PAPER[k].tag for k in known_ids))
+        header += f"\nAssuming you already know: {known_tags}"
+
+    console.print(Panel(header, border_style="cyan"))
+    console.print()
+    console.print(plan.render_text())
+    console.print()
+    console.print(
+        f"[dim]{len(plan.steps)} step(s). Static prerequisite graph; "
+        f"add LLM-extracted concept dependencies in a future iteration.[/dim]"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/run_eval.py

@@ -0,0 +1,224 @@
+"""Run the full eval harness against the RAG system.
+
+Usage:
+    uv run python scripts/run_eval.py --groq               # FAISS-only, Groq LLM
+    uv run python scripts/run_eval.py --groq --hybrid      # BM25+FAISS fusion
+    uv run python scripts/run_eval.py --groq --limit 5     # quick smoke test
+    uv run python scripts/run_eval.py --out data/eval_results_hybrid.json --groq --hybrid
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+from rich.table import Table
+
+from researchpath.embeddings import Embedder
+from researchpath.eval import (
+    EvalResult,
+    evaluate_example,
+    load_gold_dataset,
+    results_to_json,
+    summarize,
+)
+from researchpath.index import load_index, search
+from researchpath.rag import answer as rag_answer, answer_groq
+from researchpath.retrieval import HybridRetriever, Reranker
+
+console = Console()
+ROOT = Path(__file__).resolve().parents[1]
+INDEX_PATH = ROOT / "data" / "index.faiss"
+GOLD_PATH = ROOT / "data" / "gold_dataset.json"
+DEFAULT_OUT = ROOT / "data" / "eval_results.json"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Evaluate baseline RAG against gold dataset.")
+    parser.add_argument("--k", type=int, default=5, help="Top-k chunks to retrieve (default: 5).")
+    parser.add_argument("--limit", type=int, default=None, help="Evaluate only first N examples (for quick tests).")
+    parser.add_argument("--out", type=str, default=str(DEFAULT_OUT), help="Output JSON path.")
+    parser.add_argument("--groq", action="store_true", help="Use Groq for RAG generation (avoids Gemini rate limits).")
+    parser.add_argument("--hybrid", action="store_true", help="Use BM25+FAISS hybrid retrieval (RRF fusion).")
+    parser.add_argument("--rerank", action="store_true", help="Apply cross-encoder reranking on top of retrieval.")
+    parser.add_argument("--resume", action="store_true", help="Skip examples already in --out file (for retrying after rate limits).")
+    args = parser.parse_args()
+
+    if not INDEX_PATH.exists():
+        console.print(f"[red]No index at {INDEX_PATH}. Run scripts/build_index.py first.[/red]")
+        return 1
+    if not GOLD_PATH.exists():
+        console.print(f"[red]No gold dataset at {GOLD_PATH}.[/red]")
+        return 1
+
+    examples = load_gold_dataset(GOLD_PATH)
+    if args.limit:
+        examples = examples[: args.limit]
+
+    completed_ids: set[str] = set()
+    if args.resume:
+        out_path_check = Path(args.out) if Path(args.out).is_absolute() else ROOT / args.out
+        if out_path_check.exists():
+            try:
+                with open(out_path_check, encoding="utf-8") as f:
+                    prior = json.load(f)
+                completed_ids = {r["id"] for r in prior.get("results", [])}
+                console.print(f"[yellow]Resuming: skipping {len(completed_ids)} already-evaluated examples.[/yellow]")
+            except Exception:
+                pass
+        examples = [e for e in examples if e.id not in completed_ids]
+
+    rag_fn = answer_groq if args.groq else rag_answer
+    rag_provider = "Groq / llama-3.3-70b" if args.groq else "Gemini / gemini-2.5-flash-lite"
+    if args.rerank:
+        retrieval_mode = "BM25+FAISS+CrossEncoder rerank" if args.hybrid else "FAISS+CrossEncoder rerank"
+    else:
+        retrieval_mode = "BM25+FAISS (RRF)" if args.hybrid else "FAISS dense"
+
+    console.print(f"\n[bold cyan]ResearchPath Eval Harness[/bold cyan]")
+    console.print(f"  Gold examples : {len(examples)}")
+    console.print(f"  Retrieval     : {retrieval_mode}  k={args.k}")
+    console.print(f"  RAG provider  : {rag_provider}")
+    console.print(f"  Judge         : Groq / llama-3.3-70b")
+    console.print(f"  Index         : {INDEX_PATH.relative_to(ROOT)}")
+    console.print()
+
+    console.print("[dim]Loading index and embedder...[/dim]")
+    index, chunks = load_index(INDEX_PATH)
+    embedder = Embedder()
+    hybrid = HybridRetriever(index, chunks, embedder) if args.hybrid or args.rerank else None
+    if args.rerank:
+        console.print("[dim]Loading cross-encoder reranker (first run downloads ~80MB)...[/dim]")
+        reranker = Reranker(hybrid)
+    else:
+        reranker = None
+    console.print("[green]Ready.[/green]\n")
+
+    results: list[EvalResult] = []
+    failures: list[str] = []
+    out_path = Path(args.out) if Path(args.out).is_absolute() else ROOT / args.out
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    prior_results: list[dict] = []
+    if args.resume and out_path.exists():
+        try:
+            with open(out_path, encoding="utf-8") as f:
+                prior_results = json.load(f).get("results", [])
+        except Exception:
+            prior_results = []
+
+    def _save_partial() -> None:
+        if not results and not prior_results:
+            return
+        partial_summary = summarize(results) if results else None
+        partial_payload = (
+            results_to_json(results, partial_summary)
+            if partial_summary
+            else {"summary": {}, "results": []}
+        )
+        # Merge resumed prior results with new ones (prior first, preserves order)
+        if prior_results:
+            new_ids = {r["id"] for r in partial_payload["results"]}
+            merged = [r for r in prior_results if r["id"] not in new_ids] + partial_payload["results"]
+            partial_payload["results"] = merged
+            partial_payload["summary"]["n"] = len(merged)
+        with open(out_path, "w", encoding="utf-8") as f:
+            json.dump(partial_payload, f, indent=2, ensure_ascii=False)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        TimeElapsedColumn(),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Evaluating...", total=len(examples))
+
+        for ex in examples:
+            progress.update(task, description=f"[cyan]{ex.id}[/cyan] — {ex.question[:55]}...")
+            try:
+                t0 = time.time()
+                if reranker:
+                    hits = reranker.search(ex.question, k=args.k)
+                elif hybrid:
+                    hits = hybrid.search(ex.question, k=args.k)
+                else:
+                    hits = search(index, chunks, embedder, ex.question, k=args.k)
+                ra = rag_fn(ex.question, hits)
+                latency = time.time() - t0
+                if not args.groq:
+                    time.sleep(3)  # stay under Gemini's 20 RPM free-tier ceiling
+
+                result = evaluate_example(ex, hits, ra, latency)
+                results.append(result)
+                _save_partial()  # checkpoint after every example so 429s don't lose work
+
+                status = "[green]OK[/green]" if result.answer_correct else "[yellow]MISS[/yellow]"
+                recall_str = f"recall={result.retrieval_recall:.0%}"
+                progress.console.print(
+                    f"  {status}  {ex.id:20s}  {recall_str}  cite={'Y' if result.citation_present else 'N'}  "
+                    f"correct={'Y' if result.answer_correct else 'N'}  {latency:.1f}s"
+                )
+            except Exception as exc:
+                failures.append(f"{ex.id}: {exc}")
+                progress.console.print(f"  [red]ERR[/red]  {ex.id}: {exc}")
+
+            progress.advance(task)
+
+    if not results:
+        console.print("[red]No results collected — check errors above.[/red]")
+        return 1
+
+    summary = summarize(results)
+    summary.print_table()
+
+    payload = results_to_json(results, summary)
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+    try:
+        display_path = out_path.relative_to(ROOT)
+    except ValueError:
+        display_path = out_path
+    console.print(f"[green]Saved detailed results to {display_path}[/green]")
+
+    if failures:
+        console.print(f"\n[red]{len(failures)} example(s) failed:[/red]")
+        for msg in failures:
+            console.print(f"  {msg}")
+
+    _print_failures_table(results, console)
+    return 0
+
+
+def _print_failures_table(results: list[EvalResult], console: Console) -> None:
+    misses = [r for r in results if not r.answer_correct]
+    if not misses:
+        console.print("[bold green]All examples answered correctly.[/bold green]")
+        return
+
+    console.print(f"\n[bold yellow]Incorrect answers ({len(misses)}/{len(results)}):[/bold yellow]")
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan", width=22)
+    table.add_column("Difficulty", width=8)
+    table.add_column("Recall", width=7)
+    table.add_column("Cite", width=5)
+    table.add_column("Expected key claim (truncated)", width=55)
+
+    for r in misses:
+        table.add_row(
+            r.example.id,
+            r.example.difficulty,
+            f"{r.retrieval_recall:.0%}",
+            "Y" if r.citation_present else "N",
+            r.example.expected_key_claim[:55],
+        )
+    console.print(table)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/smoke_test.py

@@ -0,0 +1,54 @@
+"""Day 1 smoke test: verify both Gemini and Groq API keys work end-to-end.
+
+Usage:
+    uv run python scripts/smoke_test.py
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Make `researchpath` importable when running this file directly.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from rich.console import Console
+
+from researchpath.llm import gemini_generate, groq_generate
+
+console = Console()
+
+PROMPT = "In one sentence, what is policy gradient in reinforcement learning?"
+
+
+def run_provider(name: str, fn) -> bool:
+    console.print(f"[bold cyan]Testing {name}...[/bold cyan]")
+    try:
+        result = fn(PROMPT)
+        console.print(f"[green]OK[/green] {name} ({result.model}):")
+        console.print(f"  {result.text.strip()}")
+        if result.input_tokens is not None:
+            console.print(
+                f"  [dim]tokens: {result.input_tokens} in / {result.output_tokens} out[/dim]"
+            )
+        console.print()
+        return True
+    except Exception as e:
+        console.print(f"[red]FAIL {name}:[/red] {e}\n")
+        return False
+
+
+def main() -> int:
+    console.print("[bold]ResearchPath smoke test[/bold]\n")
+    results = [
+        run_provider("Gemini", gemini_generate),
+        run_provider("Groq", groq_generate),
+    ]
+    if all(results):
+        console.print("[bold green]All providers working. You're ready for Day 2.[/bold green]")
+        return 0
+    console.print("[bold red]One or more providers failed. Fix and re-run.[/bold red]")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_planning.py

@@ -0,0 +1,67 @@
+"""Tests for the prerequisite reading-path planner.
+
+Run: uv run pytest tests/test_planning.py
+"""
+from __future__ import annotations
+
+import pytest
+
+from researchpath.planning import plan_reading_path
+from researchpath.prerequisites import STATIC_PREREQUISITES
+
+
+def test_target_only_when_no_prereqs():
+    """A paper with no incoming edges should yield a one-step plan (just itself)."""
+    plan = plan_reading_path("1312.5602")  # DQN — no prereqs in the graph
+    assert len(plan.steps) == 1
+    assert plan.steps[0].paper.arxiv_id == "1312.5602"
+
+
+def test_rainbow_full_chain():
+    """Rainbow with no prior knowledge requires DQN, Double DQN, PER, Dueling DQN, Rainbow.
+
+    PER was added to the corpus and is one of Rainbow's six components, so it appears
+    between Double DQN and Dueling DQN (year 2015 vs 2016 topo tie-break).
+    """
+    plan = plan_reading_path("1710.02298")
+    ids_in_order = [s.paper.arxiv_id for s in plan.steps]
+    assert ids_in_order == ["1312.5602", "1509.06461", "1511.05952", "1511.06581", "1710.02298"]
+
+
+def test_known_set_truncates_chain():
+    """Knowing DQN should drop it from the Rainbow plan."""
+    plan = plan_reading_path("1710.02298", known_ids={"1312.5602"})
+    ids = {s.paper.arxiv_id for s in plan.steps}
+    assert "1312.5602" not in ids
+    assert "1710.02298" in ids
+    # Double DQN, PER, Dueling DQN, Rainbow remain (PER now in corpus as Rainbow component)
+    assert len(plan.steps) == 4
+
+
+def test_known_target_yields_empty_plan():
+    """If the target is already 'known', no reading is needed."""
+    plan = plan_reading_path("1710.02298", known_ids={"1710.02298"})
+    assert plan.steps == ()
+
+
+def test_topological_order_respects_edges():
+    """For every edge (A -> B), A must appear before B in the plan."""
+    plan = plan_reading_path("1710.02298")
+    positions = {s.paper.arxiv_id: i for i, s in enumerate(plan.steps)}
+    for edge in STATIC_PREREQUISITES:
+        if edge.from_id in positions and edge.to_id in positions:
+            assert positions[edge.from_id] < positions[edge.to_id], (
+                f"{edge.from_id} should precede {edge.to_id}"
+            )
+
+
+def test_unknown_target_raises():
+    with pytest.raises(ValueError):
+        plan_reading_path("9999.99999")
+
+
+def test_render_text_contains_target_title():
+    plan = plan_reading_path("1710.02298")
+    text = plan.render_text()
+    assert "Rainbow" in text
+    assert "1710.02298" in text