CLAUDE.md

Experiment Dashboard Visualizer

Research dashboard with experiment tracking and trace visualization.

• Live: https://huggingface.co/spaces/{HF_ORG}/dashboard
• GitHub: {github-org}/dashboard-repo
• Remotes: origin (GitHub), space (HF Space)

Updating the Website

When the user says "update the website", "sync the dashboard", or "push to the website":

1. Build the frontend:

   cd tools/visualizer/frontend && npm run build
   

2. Import experiment data (reads local files, uploads to HF dataset):

   cd tools/visualizer && python3 scripts/import_experiments.py
   

3. Sync the live Space (tells the running app to re-download data from HF):

   curl -s -X POST https://{HF_ORG}-dashboard.hf.space/api/experiments/sync
   

4. Push code to HF Space (deploys new frontend/backend code):

   cd tools/visualizer
   git add -A && git commit -m "update dashboard"
   git push origin main
   git push space main
   

Steps 1-3 sync data (experiments, summary findings, presets). Step 4 deploys code changes.

If only summary_findings.md changed (no code changes), steps 2-3 are sufficient.

Summary Findings

• Source file: {WORKSPACE}/notes/experiments/summary_findings.md
• Only the user writes this file — never edit it
• Synced to HF via import_experiments.py → served at GET /api/experiments/summary
• Shown on the Experiments page via the "Findings / Summary" button

Experiment Discovery

scripts/import_experiments.py auto-discovers all experiments in notes/experiments/, skipping old/, _templates/, and hidden directories. To hide specific experiments, add them to EXCLUDED_EXPERIMENTS in the script.

Stack

• Backend: Flask (Python), blueprints in backend/api/
• Frontend: React + TypeScript + Tailwind, built with Vite into frontend/dist/
• Data: HF datasets (RACA_DASHBOARD for experiments, RACA-VIS-PRESETS for visualizer presets)

AdaEvolve Traces

Required HuggingFace Dataset Columns

Column	Type	Purpose
iteration	int	Iteration number
island_id	int	Which island produced this solution
score	float	Current iteration score
best_score	float	Best score so far
delta	float	Change from previous iteration
adaptation_type	string	"L1_explore", "L1_exploit", "L2_migrate", "L3_meta"
exploration_intensity	float	How exploratory this iteration was
is_valid	bool	Whether solution is valid
task_id	string	Task identifier
prompt_text	string	(optional) Input prompt to model
reasoning_trace	string	(optional) Thinking/reasoning output
program_code	string	(optional) Generated/evolved code

Color Mapping

L1_explore=blue, L1_exploit=green, L2_migrate=amber, L3_meta=red, other=gray.

Adding a Preset

1. Upload dataset to HuggingFace (org: your-org)
2. Add entry to your-org/RACA-VIS-PRESETS file adaevolve_presets.json:

   {"id": "8-char-hex", "name": "Descriptive Name", "repo": "org/dataset-name", "split": "train"}
   

3. Sync: curl -X POST "https://your-org-agg-trace-visualizer.hf.space/api/presets/sync"

Naming Convention

{Task} {Model}: {Description} ({N} iter)