feat: add recursive experiment directory parsing with OUTDATED filtering

- Update experiment parser to recursively search all subdirectories
- Automatically filter out directories containing "OUTDATED" (case-insensitive)
- Improve documentation with flexible directory structure examples
- Add comprehensive test coverage for OUTDATED directory exclusion

Author: PaulHax

README.md

@@ -28,9 +28,20 @@ uvx align-browser ./experiment-data --host 0.0.0.0
 uvx align-browser ./experiment-data --build-only
 ```
 
-### Expected Directory Structure
+### Directory Structure
 
-The experiments directory should be the root containing pipeline directories (e.g., `pipeline_baseline`, `pipeline_random`), not an individual pipeline directory.
+The build system supports **flexible directory structures** and will recursively search for valid experiment directories at any depth. You can point it to any directory containing experiment data, regardless of how it's organized.
+
+#### Required Files Per Experiment
+
+Each experiment directory must contain:
+
+- `.hydra/config.yaml` - Hydra configuration file
+- `input_output.json` - Experiment input/output data
+- `scores.json` - Scoring results
+- `timing.json` - Timing information
+
+**Example Structure:**
 
 ```
 experiments/
@@ -49,15 +60,17 @@ experiments/
     └── ...
 ```
 
-The build.py script will search for:
+#### Automatic Filtering
+
+The build system will automatically:
 
-- Pipeline directories at the root level
-- KDMA experiment directories within each pipeline (identified by presence of `input_output.json`)
-- Required files: `.hydra/config.yaml`, `input_output.json`
+- **Recursively search** through all subdirectories
+- **Skip directories** containing `OUTDATED` in their path (case-insensitive)
+- **Only process directories** that contain all required files
 
 ### Sharing Results
 
-The browser application stores the current selection state in the URL, making it easy to share specific views:
+The browser application stores the current selection state in the URL so you can:
 
 - **Share a specific scenario**: URLs automatically update when you select different pipelines, KDMAs, or experiments
 - **Bookmark results**: Save URLs to return to specific experiment comparisons
@@ -78,7 +91,7 @@ For active development of the HTML/CSS/JavaScript:
 
 ```bash
 # Development mode: edit files in align-browser-site/ directory directly
-uv run align-browser ./experiment-data/phase2_june --dev
+uv run align-browser --dev ./experiment-data/phase2_june
 ```
 
 Edit align-browser-site/index.html, align-browser-site/app.js, align-browser-site/style.css and refresh browser to see changes immediately.

align_browser/experiment_parser.py

@@ -9,6 +9,10 @@ def parse_experiments_directory(experiments_root: Path) -> List[ExperimentData]:
     """
     Parse the experiments directory structure and return a list of ExperimentData.
 
+    Recursively searches through the directory structure to find all directories
+    that contain the required experiment files (input_output.json, scores.json,
+    timing.json, and .hydra/config.yaml).
+
     Args:
         experiments_root: Path to the root experiments directory
 
@@ -17,26 +21,27 @@ def parse_experiments_directory(experiments_root: Path) -> List[ExperimentData]:
     """
     experiments = []
 
-    for pipeline_dir in experiments_root.iterdir():
-        if not pipeline_dir.is_dir():
+    # Recursively find all directories that have required experiment files
+    for experiment_dir in experiments_root.rglob("*"):
+        if not experiment_dir.is_dir():
             continue
 
-        for experiment_dir in pipeline_dir.glob("*"):
-            if not experiment_dir.is_dir():
-                continue
+        # Skip directories containing "OUTDATED" in their path
+        if "OUTDATED" in str(experiment_dir).upper():
+            continue
 
-            # Check if directory has all required files
-            if not ExperimentData.has_required_files(experiment_dir):
-                continue
+        # Check if directory has all required files
+        if not ExperimentData.has_required_files(experiment_dir):
+            continue
 
-            try:
-                # Load experiment data using Pydantic models
-                experiment = ExperimentData.from_directory(experiment_dir)
-                experiments.append(experiment)
+        try:
+            # Load experiment data using Pydantic models
+            experiment = ExperimentData.from_directory(experiment_dir)
+            experiments.append(experiment)
 
-            except Exception as e:
-                print(f"Error processing {experiment_dir}: {e}")
-                continue
+        except Exception as e:
+            print(f"Error processing {experiment_dir}: {e}")
+            continue
 
     return experiments
 

align_browser/test_experiment_parser.py

@@ -266,6 +266,63 @@ def test_parse_experiments_directory():
         assert experiments[0].key == "pipeline_random_llama3.3-70b_affiliation-0.5"
 
 
+def test_parse_experiments_directory_excludes_outdated():
+    """Test that parse_experiments_directory correctly excludes OUTDATED directories."""
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+
+        # Create experiments structure
+        experiments_root = temp_path / "experiments"
+        experiments_root.mkdir()
+
+        # Create a valid experiment directory
+        pipeline_dir = experiments_root / "pipeline_test"
+        pipeline_dir.mkdir()
+
+        valid_experiment = pipeline_dir / "affiliation-0.5"
+        valid_experiment.mkdir()
+        hydra_dir = valid_experiment / ".hydra"
+        hydra_dir.mkdir()
+
+        # Create required files for valid experiment
+        config_data = create_sample_config_data()
+        with open(hydra_dir / "config.yaml", "w") as f:
+            yaml.dump(config_data, f)
+        with open(valid_experiment / "input_output.json", "w") as f:
+            json.dump(create_sample_input_output_data(), f)
+        with open(valid_experiment / "scores.json", "w") as f:
+            json.dump(create_sample_scores_data(), f)
+        with open(valid_experiment / "timing.json", "w") as f:
+            json.dump(create_sample_timing_data(), f)
+
+        # Create OUTDATED experiment directory with all required files
+        outdated_experiment = pipeline_dir / "OUTDATED-affiliation-0.5"
+        outdated_experiment.mkdir()
+        outdated_hydra_dir = outdated_experiment / ".hydra"
+        outdated_hydra_dir.mkdir()
+
+        # Create required files for OUTDATED experiment (same structure)
+        with open(outdated_hydra_dir / "config.yaml", "w") as f:
+            yaml.dump(config_data, f)
+        with open(outdated_experiment / "input_output.json", "w") as f:
+            json.dump(create_sample_input_output_data(), f)
+        with open(outdated_experiment / "scores.json", "w") as f:
+            json.dump(create_sample_scores_data(), f)
+        with open(outdated_experiment / "timing.json", "w") as f:
+            json.dump(create_sample_timing_data(), f)
+
+        # Test parsing - should only find the valid experiment, not the OUTDATED one
+        experiments = parse_experiments_directory(experiments_root)
+        assert len(experiments) == 1, f"Expected 1 experiment, found {len(experiments)}"
+        assert experiments[0].key == "pipeline_random_llama3.3-70b_affiliation-0.5"
+
+        # Verify the OUTDATED experiment was actually excluded
+        experiment_paths = [str(exp.experiment_path) for exp in experiments]
+        assert not any("OUTDATED" in path for path in experiment_paths), (
+            f"OUTDATED experiment was not filtered out: {experiment_paths}"
+        )
+
+
 def test_build_manifest_from_experiments():
     """Test building manifest from experiments."""
     with tempfile.TemporaryDirectory() as temp_dir: