docs: document experiment management

Author: edarchimbaud

README.md

@@ -23,10 +23,10 @@ $ export OPENAI_API_KEY=sk-...
 $ export HF_ACCESS_TOKEN=hf_
 ```
 
-Launch the evolution controller
+Launch the evolution controller (create a fresh experiment)
 
-```python
-python scripts/run_example.py
+```bash
+python scripts/run_example.py --experiment my_exp
 ```
 
 Monitor the evolution process in real‑time using the optional Streamlit dashboard:
@@ -37,6 +37,16 @@ $ streamlit run scripts/dashboard.py
 
 The dashboard uses Streamlit to visualize the evolution process and back‑test results.
 
+### Managing experiments
+
+Use the `--experiment` option to keep runs separate:
+
+```bash
+python scripts/run_example.py --experiment my_exp
+```
+
+This creates a new SQLite file `my_exp.db` under `~/.alphaevolve/`. The dashboard lists all experiments, allowing you to switch between them or delete one via the **Delete experiment** sidebar button.
+
 ---
 
 ## ⚙️ Installation
@@ -87,7 +97,7 @@ export LOCAL_MODEL_PATH=~/.cache/phi-2 # or set LOCAL_MODEL_NAME
 Run the evolution loop with the local model:
 
 ```bash
-python scripts/run_example.py
+python scripts/run_example.py --experiment my_exp
 ```
 
 ---

alphaevolve/engine.py

@@ -9,6 +9,7 @@
 
 from alphaevolve.evolution.controller import Controller
 from alphaevolve.store.sqlite import ProgramStore
+from alphaevolve.config import settings
 from examples import config as example_settings
 
 __all__ = ["AlphaEvolve", "Strategy"]
@@ -31,9 +32,18 @@ def __init__(
  initial_program_paths: list[str],
  *,
  store: ProgramStore | None = None,
+ experiment_name: str | None = None,
  ) -> None:
  self.initial_program_paths = [Path(p) for p in initial_program_paths]
- self.store = store or ProgramStore()
+ if store is not None:
+ self.store = store
+ else:
+ if experiment_name:
+ base = Path(settings.sqlite_db).expanduser()
+ db_path = base.parent / f"{experiment_name}.db"
+ self.store = ProgramStore(db_path=db_path)
+ else:
+ self.store = ProgramStore()
  metrics = (
  example_settings.BRANCH_METRICS if example_settings.MULTI_BRANCH_MUTATION else [None]
  )

scripts/dashboard.py

@@ -11,12 +11,16 @@
 * Inspect source code in expandable section
 """
 from __future__ import annotations
+import os
 import textwrap
 import streamlit as st
 import pandas as pd
 import matplotlib.pyplot as plt
 
+from pathlib import Path
+
 from alphaevolve.store.sqlite import ProgramStore
+from alphaevolve.config import settings
 from examples import config as example_config
 from alphaevolve.evaluator.backtest import (
  _load_module_from_code, # type: ignore (private helper is okay for internal app)
@@ -25,7 +29,21 @@
 )
 
 st.set_page_config(page_title="Alpha‑Evolve Dashboard", layout="wide")
-store = ProgramStore()
+
+db_dir = Path(settings.sqlite_db).expanduser().parent
+db_files = sorted(db_dir.glob("*.db"))
+experiments = [f.stem for f in db_files]
+if not experiments:
+ st.warning("No experiments found – run the controller first.")
+ st.stop()
+
+selected_exp = st.sidebar.selectbox("Experiment", experiments)
+db_path = db_dir / f"{selected_exp}.db"
+if st.sidebar.button("Delete experiment"):
+ os.remove(db_path)
+ st.experimental_rerun()
+
+store = ProgramStore(db_path)
 
 # ------------------------------------------------------------------
 # Hall of Fame table

scripts/run_example.py

@@ -1,14 +1,30 @@
+import argparse
 import asyncio
 
 from alphaevolve import AlphaEvolve
 
+parser = argparse.ArgumentParser(description="Run AlphaEvolve demo")
+parser.add_argument(
+ "--experiment",
+ type=str,
+ default=None,
+ help="Experiment name (creates or resumes a SQLite DB)",
+)
+parser.add_argument(
+ "--iterations", type=int, default=10, help="Number of evolution iterations"
+)
+args = parser.parse_args()
+
 # Initialize the system
-evolve = AlphaEvolve(initial_program_paths=["examples/sma_momentum.py"])
+evolve = AlphaEvolve(
+ initial_program_paths=["examples/sma_momentum.py"],
+ experiment_name=args.experiment,
+)
 
 
 # Run the evolution
 async def main() -> None:
- best_strategy = await evolve.run(iterations=10)
+ best_strategy = await evolve.run(iterations=args.iterations)
  print("Best strategy metrics:")
  for name, value in best_strategy.metrics.items():
  print(f" {name}: {value:.4f}")