docs/map/README.md

ReplicaLab Project Map

Living reference of every module, class, function, and relationship. Updated after each implementation session.

Last updated: 2026-03-07 (JDG 01-03 scoring implemented)

Module Index

File	What it covers
models.md	Data contracts — actions, observations, protocol, reward, episode state
scenarios.md	Scenario generation — templates, constraints, resources, hidden specs
agents.md	Agent policies — scientist prompt/parse/retry, lab manager feasibility/suggest/compose
validation.md	Protocol validation — deterministic checks against scenario constraints
scoring.md	Judge scoring — rigor, feasibility, fidelity
server.md	FastAPI server — REST + WebSocket endpoints, stub environment
frontend.md	React UI — dashboard, episode viewer, components
config.md	Shared constants — rounds, budget, timeouts
tests.md	Test coverage — 87 tests across 6 files

Dependency Graph

server/app.py
 ├── replicalab.config
 ├── replicalab.models
 ├── replicalab.scenarios (generate_scenario, available_scenario_families)
 └── replicalab.agents (check_feasibility, suggest_alternative, compose_lab_manager_response)

replicalab/agents/scientist_policy.py
 ├── replicalab.models (ScientistAction, ScientistObservation, Protocol, ConversationEntry)
 └── replicalab.scenarios (NormalizedScenarioPack)

replicalab/agents/lab_manager_policy.py
 ├── replicalab.models (LabManagerAction, LabManagerActionType, Protocol)
 ├── replicalab.scenarios (NormalizedScenarioPack)
 └── replicalab.utils.validation (ValidationResult, validate_protocol)

replicalab/scenarios/templates.py
 ├── replicalab.config (MAX_BUDGET, MAX_ROUNDS)
 ├── replicalab.models (ScientistObservation, LabManagerObservation)
 ├── replicalab.scenarios.{math_reasoning, ml_benchmark, finance_trading}
 └── replicalab.utils.seed (seed_rng)

replicalab/utils/validation.py
 ├── replicalab.models (Protocol)
 └── replicalab.scenarios.templates (NormalizedScenarioPack)

replicalab/scoring/
 ├── replicalab.models (Protocol, RewardBreakdown)
 ├── replicalab.scenarios (NormalizedScenarioPack, HiddenReferenceSpec)
 ├── replicalab.agents.lab_manager_policy (check_feasibility, FeasibilityCheckResult)
 └── replicalab.utils.text (element_tokens, normalize_label)

File Tree (implemented only)

replicalab/
 ├── __init__.py              (empty)
 ├── config.py                (shared constants)
 ├── models.py                (25 classes — all data contracts)
 ├── agents/
 │   ├── __init__.py          (re-exports from submodules)
 │   ├── scientist_policy.py  (AGT 01-04: prompt, formatter, parser, retry, baseline)
 │   └── lab_manager_policy.py(AGT 05-07: feasibility, suggest, compose)
 ├── scenarios/
 │   ├── __init__.py          (re-exports from templates)
 │   ├── templates.py         (NormalizedScenarioPack, generate_scenario, apply_difficulty)
 │   ├── math_reasoning.py    (2 cases: Cauchy-Schwarz, Jensen's inequality)
 │   ├── ml_benchmark.py      (2 cases: AG News TinyBERT, CIFAR-10 ResNet-18)
 │   └── finance_trading.py   (2 cases: SPY/QQQ mean-reversion, momentum futures)
 ├── scoring/
 │   ├── __init__.py          (exports score_rigor, score_feasibility, score_fidelity)
 │   ├── rigor.py             (JDG 01: structural quality + criteria coverage)
 │   ├── feasibility.py       (JDG 02: wraps FeasibilityCheckResult with partial credit)
 │   └── fidelity.py          (JDG 03: substitution-aware hidden spec alignment)
 └── utils/
     ├── seed.py              (deterministic RNG from SHA256)
     ├── text.py              (shared token matching: normalize_label, element_tokens)
     └── validation.py        (MOD 05: protocol validation, 5 checks)

server/
 └── app.py                   (FastAPI + WebSocket + _StubEnv)

frontend/
 ├── package.json             (React 19, Three.js, Framer Motion, Recharts, Tailwind)
 ├── src/
 │   ├── App.tsx              (router: /, /episode, /episode/:id)
 │   ├── types/index.ts       (TypeScript interfaces mirroring Python models)
 │   ├── lib/
 │   │   ├── api.ts           (REST + WebSocket client + mock data generators)
 │   │   ├── audio.ts         (audio utilities)
 │   │   └── utils.ts         (shared helpers)
 │   ├── components/          (15 React components)
 │   └── pages/               (DashboardPage, EpisodePage)
 └── vite.config.ts

tests/
 ├── test_config.py           (3 tests)
 ├── test_models.py           (15 tests)
 ├── test_scenarios.py        (8 tests)
 ├── test_validation.py       (13 tests)
 ├── test_scientist_policy.py (18 tests)
 ├── test_lab_manager_policy.py(13 tests)
 ├── test_reward.py           (18 tests — JDG 01-03 scoring)
 └── test_server.py           (5 tests — API endpoints)

Task Completion Status

Area	Done	Remaining	Key gaps
Models (MOD)	MOD 01-05, 09, 11-12	MOD 06	Semantic validators for impossible plans
Scenarios (SCN)	SCN 01-12	SCN 13	Booking/scheduling data model
Agents (AGT)	AGT 01-07, 11	AGT 08-10	LLM-backed scientist, model selection
Judge (JDG)	JDG 01-03	JDG 04-08	Reward composition, bonuses, penalties
Environment (ENV)	—	ENV 01-11	Entire real environment
Server (API)	API 01-04, 06 (partial)	API 05, 07-10	Replay, auth, rate limiting
Frontend (FND)	FND 01-10	—	Complete
Training (TRN)	—	TRN 01-18	Entire RL pipeline