feat: Implement OutputManager for clean output directory structure

- Created OutputManager class to centralize all pipeline output paths
- Single run directory per execution with timestamp-based ID
- Clear hierarchy: eda/, training/, simulation/, reports/
- Removed duplicate model saving, created symlink system
- Refactored EDA modules to use OutputManager paths
- Fixed scattered output files across data/, reports/, models/
- Config saved at run root for reproducibility

Changes:
- New: scheduler/utils/output_manager.py - centralized output management
- New: rl/config.py - structured RL configuration with presets
- New: docs/CONFIGURATION.md - 5-layer config architecture docs
- New: docs/OUTPUT_REFACTORING.md - implementation status tracker
- Modified: court_scheduler_rl.py - integrated OutputManager
- Modified: src/eda_*.py - dynamic output path configuration
- Modified: PipelineConfig - removed output_dir field

Benefits:
- No scattered files or duplicate saves
- Single source of truth per run
- Easy cleanup and archival
- Reproducible runs via saved config
- Clear separation of concerns

Test: Quick demo pipeline runs end-to-end successfully
Result: outputs/runs/run_TIMESTAMP/ with complete artifacts

court_scheduler_rl.py

@@ -13,7 +13,7 @@ from datetime import date, datetime, timedelta
 from pathlib import Path
 from typing import Dict, Any, Optional, List
 import argparse
-from dataclasses import dataclass, asdict
+from dataclasses import dataclass, asdict, field
 
 import typer
 from rich.console import Console
@@ -38,36 +38,37 @@ class PipelineConfig:
     stage_mix: str = "auto"
     seed: int = 42
     
-    # RL Training
-    episodes: int = 100
-    cases_per_episode: int = 1000
-    episode_length: int = 45
-    learning_rate: float = 0.15
-    initial_epsilon: float = 0.4
-    epsilon_decay: float = 0.99
-    min_epsilon: float = 0.05
+    # RL Training - delegate to RLTrainingConfig
+    rl_training: "RLTrainingConfig" = None  # Will be set in __post_init__
     
     # Simulation
     sim_days: int = 730  # 2 years
     sim_start_date: Optional[str] = None
     policies: List[str] = None
     
-    # Output
-    output_dir: str = "data/hackathon_run"
+    # Output (no longer user-configurable - managed by OutputManager)
     generate_cause_lists: bool = True
     generate_visualizations: bool = True
     
     def __post_init__(self):
         if self.policies is None:
             self.policies = ["readiness", "rl"]
+        
+        # Import here to avoid circular dependency
+        if self.rl_training is None:
+            from rl.config import DEFAULT_RL_TRAINING_CONFIG
+            self.rl_training = DEFAULT_RL_TRAINING_CONFIG
 
 class InteractivePipeline:
     """Interactive pipeline orchestrator"""
     
-    def __init__(self, config: PipelineConfig):
+    def __init__(self, config: PipelineConfig, run_id: str = None):
         self.config = config
-        self.output_dir = Path(config.output_dir)
-        self.output_dir.mkdir(parents=True, exist_ok=True)
+        
+        from scheduler.utils.output_manager import OutputManager
+        self.output = OutputManager(run_id=run_id)
+        self.output.create_structure()
+        self.output.save_config(config)
         
     def run(self):
         """Execute complete pipeline"""
@@ -108,10 +109,17 @@ class InteractivePipeline:
         with Progress(
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
-            console=console,
-        ) as progress:
+            console=console) as progress:
             task = progress.add_task("Running EDA pipeline...", total=None)
             
+            # Configure EDA output paths
+            from src.eda_config import set_output_paths
+            set_output_paths(
+                eda_dir=self.output.eda_figures,
+                data_dir=self.output.eda_data,
+                params_dir=self.output.eda_params
+            )
+            
             from src.eda_load_clean import run_load_and_clean
             from src.eda_exploration import run_exploration
             from src.eda_parameters import run_parameter_export
@@ -129,14 +137,13 @@ class InteractivePipeline:
         console.print(f"\n[bold cyan]Step 2/7: Data Generation[/bold cyan]")
         console.print(f"  Generating {self.config.n_cases:,} cases ({self.config.start_date} to {self.config.end_date})")
         
-        cases_file = self.output_dir / "training_cases.csv"
+        cases_file = self.output.training_cases_file
         
         with Progress(
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
             BarColumn(),
-            console=console,
-        ) as progress:
+            console=console) as progress:
             task = progress.add_task("Generating cases...", total=100)
             
             from datetime import date as date_cls
@@ -159,55 +166,56 @@ class InteractivePipeline:
     def _step_3_rl_training(self):
         """Step 3: RL Agent Training"""
         console.print(f"\n[bold cyan]Step 3/7: RL Training[/bold cyan]")
-        console.print(f"  Episodes: {self.config.episodes}, Learning Rate: {self.config.learning_rate}")
+        console.print(f"  Episodes: {self.config.rl_training.episodes}, Learning Rate: {self.config.rl_training.learning_rate}")
         
-        model_file = self.output_dir / "trained_rl_agent.pkl"
+        model_file = self.output.trained_model_file
         
         with Progress(
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
             BarColumn(),
             TimeElapsedColumn(),
-            console=console,
-        ) as progress:
-            training_task = progress.add_task("Training RL agent...", total=self.config.episodes)
+            console=console) as progress:
+            training_task = progress.add_task("Training RL agent...", total=self.config.rl_training.episodes)
             
             # Import training components
             from rl.training import train_agent
             from rl.simple_agent import TabularQAgent
             import pickle
             
-            # Initialize agent
+            # Initialize agent with configured hyperparameters
+            rl_cfg = self.config.rl_training
             agent = TabularQAgent(
-                learning_rate=self.config.learning_rate,
-                epsilon=self.config.initial_epsilon,
-                discount=0.95
+                learning_rate=rl_cfg.learning_rate,
+                epsilon=rl_cfg.initial_epsilon,
+                discount=rl_cfg.discount_factor
             )
             
             # Training with progress updates
             # Note: train_agent handles its own progress internally
+            rl_cfg = self.config.rl_training
             training_stats = train_agent(
                 agent=agent,
-                episodes=self.config.episodes,
-                cases_per_episode=self.config.cases_per_episode,
-                episode_length=self.config.episode_length,
+                episodes=rl_cfg.episodes,
+                cases_per_episode=rl_cfg.cases_per_episode,
+                episode_length=rl_cfg.episode_length_days,
                 verbose=False  # Disable internal printing
             )
             
-            progress.update(training_task, completed=self.config.episodes)
+            progress.update(training_task, completed=rl_cfg.episodes)
             
             # Save trained agent
             agent.save(model_file)
             
-            # Also save to models directory for RL policy to find
-            models_dir = Path("models")
-            models_dir.mkdir(exist_ok=True)
-            standard_model_path = models_dir / "trained_rl_agent.pkl"
-            agent.save(standard_model_path)
+            # Create symlink in models/ for backwards compatibility
+            self.output.create_model_symlink()
         
         console.print(f"  [green]OK[/green] Training complete -> {model_file}")
-        console.print(f"  [green]OK[/green] Also saved to {standard_model_path}")
+        console.print(f"  [green]OK[/green] Model symlink: models/latest.pkl")
         console.print(f"  [green]OK[/green] Final epsilon: {agent.epsilon:.4f}, States explored: {len(agent.q_table)}")
+        
+        # Store model path for simulation step
+        self.trained_model_path = model_file
     
     def _step_4_simulation(self):
         """Step 4: 2-Year Simulation"""
@@ -215,7 +223,7 @@ class InteractivePipeline:
         console.print(f"  Duration: {self.config.sim_days} days ({self.config.sim_days/365:.1f} years)")
         
         # Load cases
-        cases_file = self.output_dir / "training_cases.csv"
+        cases_file = self.output.training_cases_file
         from scheduler.data.case_generator import CaseGenerator
         cases = CaseGenerator.from_csv(cases_file)
         
@@ -227,36 +235,47 @@ class InteractivePipeline:
         for policy in self.config.policies:
             console.print(f"\n  Running {policy} policy simulation...")
             
-            policy_dir = self.output_dir / f"simulation_{policy}"
+            policy_dir = self.output.get_policy_dir(policy)
             policy_dir.mkdir(exist_ok=True)
             
+            # CRITICAL: Deep copy cases for each simulation to prevent state pollution
+            # Cases are mutated during simulation (status, hearing_count, disposal_date)
+            from copy import deepcopy
+            policy_cases = deepcopy(cases)
+            
             with Progress(
                 SpinnerColumn(),
                 TextColumn(f"[progress.description]Simulating {policy}..."),
                 BarColumn(),
-                console=console,
-            ) as progress:
+                console=console) as progress:
                 task = progress.add_task("Simulating...", total=100)
                 
                 from scheduler.simulation.engine import CourtSim, CourtSimConfig
                 
-                cfg = CourtSimConfig(
-                    start=sim_start,
-                    days=self.config.sim_days,
-                    seed=self.config.seed,
-                    policy=policy,
-                    duration_percentile="median",
-                    log_dir=policy_dir,
-                )
+                # Prepare config with RL model path if needed
+                cfg_kwargs = {
+                    "start": sim_start,
+                    "days": self.config.sim_days,
+                    "seed": self.config.seed,
+                    "policy": policy,
+                    "duration_percentile": "median",
+                    "log_dir": policy_dir,
+                }
+                
+                # Add RL agent path for RL policy
+                if policy == "rl" and hasattr(self, 'trained_model_path'):
+                    cfg_kwargs["rl_agent_path"] = self.trained_model_path
                 
-                sim = CourtSim(cfg, cases)
+                cfg = CourtSimConfig(**cfg_kwargs)
+                
+                sim = CourtSim(cfg, policy_cases)
                 result = sim.run()
                 
                 progress.update(task, completed=100)
                 
                 results[policy] = {
                     'result': result,
-                    'cases': cases,
+                    'cases': policy_cases,  # Use the deep-copied cases for this simulation
                     'sim': sim,
                     'dir': policy_dir
                 }
@@ -280,8 +299,7 @@ class InteractivePipeline:
             with Progress(
                 SpinnerColumn(),
                 TextColumn("[progress.description]{task.description}"),
-                console=console,
-            ) as progress:
+                console=console) as progress:
                 task = progress.add_task("Generating cause lists...", total=None)
                 
                 from scheduler.output.cause_list import CauseListGenerator
@@ -305,8 +323,7 @@ class InteractivePipeline:
         with Progress(
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
-            console=console,
-        ) as progress:
+            console=console) as progress:
             task = progress.add_task("Analyzing results...", total=None)
             
             # Generate comparison report
@@ -327,7 +344,7 @@ class InteractivePipeline:
         summary = self._generate_executive_summary()
         
         # Save summary
-        summary_file = self.output_dir / "EXECUTIVE_SUMMARY.md"
+        summary_file = self.output.executive_summary_file
         with open(summary_file, 'w') as f:
             f.write(summary)
         
@@ -370,17 +387,17 @@ class InteractivePipeline:
         
         console.print(Panel.fit(
             f"[bold green]Pipeline Complete![/bold green]\n\n"
-            f"Results: {self.output_dir}/\n"
+            f"Results: {self.output.run_dir}/\n"
             f"Executive Summary: {summary_file}\n"
-            f"Visualizations: {self.output_dir}/visualizations/\n"
-            f"Cause Lists: {self.output_dir}/simulation_*/cause_lists/\n\n"
+            f"Visualizations: {self.output.visualizations_dir}/\n"
+            f"Cause Lists: {self.output.simulation_dir}/*/cause_lists/\n\n"
             f"[yellow]Ready for hackathon submission![/yellow]",
             box=box.DOUBLE_EDGE
         ))
     
     def _generate_comparison_report(self):
         """Generate detailed comparison report"""
-        report_file = self.output_dir / "COMPARISON_REPORT.md"
+        report_file = self.output.comparison_report_file
         
         with open(report_file, 'w') as f:
             f.write("# Court Scheduling System - Performance Comparison\n\n")
@@ -389,7 +406,9 @@ class InteractivePipeline:
             f.write("## Configuration\n\n")
             f.write(f"- Training Cases: {self.config.n_cases:,}\n")
             f.write(f"- Simulation Period: {self.config.sim_days} days ({self.config.sim_days/365:.1f} years)\n")
-            f.write(f"- RL Episodes: {self.config.episodes}\n")
+            f.write(f"- RL Episodes: {self.config.rl_training.episodes}\n")
+            f.write(f"- RL Learning Rate: {self.config.rl_training.learning_rate}\n")
+            f.write(f"- RL Epsilon: {self.config.rl_training.initial_epsilon}\n")
             f.write(f"- Policies Compared: {', '.join(self.config.policies)}\n\n")
             
             f.write("## Results Summary\n\n")
@@ -406,7 +425,7 @@ class InteractivePipeline:
     
     def _generate_visualizations(self):
         """Generate performance visualizations"""
-        viz_dir = self.output_dir / "visualizations"
+        viz_dir = self.output.visualizations_dir
         viz_dir.mkdir(exist_ok=True)
         
         # This would generate charts comparing policies
@@ -442,7 +461,7 @@ This intelligent court scheduling system uses Reinforcement Learning to optimize
 **{disposal_rate:.1%} Case Disposal Rate** - Significantly improved case clearance
 **{result.utilization:.1%} Court Utilization** - Optimal resource allocation  
 **{result.hearings_total:,} Hearings Scheduled** - Over {self.config.sim_days} days
-**AI-Powered Decisions** - Reinforcement learning with {self.config.episodes} training episodes
+**AI-Powered Decisions** - Reinforcement learning with {self.config.rl_training.episodes} training episodes
 
 ### Technical Innovation
 
@@ -493,9 +512,15 @@ def get_interactive_config() -> PipelineConfig:
     
     # RL Training
     console.print("\n[bold]RL Training[/bold]")
+    from rl.config import RLTrainingConfig
+    
     episodes = IntPrompt.ask("Training episodes", default=100)
     learning_rate = FloatPrompt.ask("Learning rate", default=0.15)
     
+    rl_training_config = RLTrainingConfig(
+        episodes=episodes,
+        learning_rate=learning_rate)
+    
     # Simulation
     console.print("\n[bold]Simulation[/bold]")
     sim_days = IntPrompt.ask("Simulation days (730 = 2 years)", default=730)
@@ -514,14 +539,11 @@ def get_interactive_config() -> PipelineConfig:
         n_cases=n_cases,
         start_date=start_date,
         end_date=end_date,
-        episodes=episodes,
-        learning_rate=learning_rate,
+        rl_training=rl_training_config,
         sim_days=sim_days,
         policies=policies,
-        output_dir=output_dir,
         generate_cause_lists=generate_cause_lists,
-        generate_visualizations=generate_visualizations,
-    )
+        generate_visualizations=generate_visualizations)
 
 @app.command()
 def interactive():
@@ -532,7 +554,8 @@ def interactive():
     console.print(f"\n[bold yellow]Configuration Summary:[/bold yellow]")
     console.print(f"  Cases: {config.n_cases:,}")
     console.print(f"  Period: {config.start_date} to {config.end_date}")
-    console.print(f"  RL Episodes: {config.episodes}")
+    console.print(f"  RL Episodes: {config.rl_training.episodes}")
+    console.print(f"  RL Learning Rate: {config.rl_training.learning_rate}")
     console.print(f"  Simulation: {config.sim_days} days")
     console.print(f"  Policies: {', '.join(config.policies)}")
     console.print(f"  Output: {config.output_dir}")
@@ -561,12 +584,12 @@ def quick():
     """Run quick demo with default parameters"""
     console.print("[bold blue]Quick Demo Pipeline[/bold blue]\n")
     
+    from rl.config import QUICK_DEMO_RL_CONFIG
+    
     config = PipelineConfig(
         n_cases=10000,
-        episodes=20,
-        sim_days=90,
-        output_dir="data/quick_demo",
-    )
+        rl_training=QUICK_DEMO_RL_CONFIG,
+        sim_days=90)
     
     pipeline = InteractivePipeline(config)
     pipeline.run()

docs/CONFIGURATION.md

@@ -0,0 +1,194 @@
+# Configuration Architecture
+
+## Overview
+The codebase uses a layered configuration approach separating concerns by domain and lifecycle.
+
+## Configuration Layers
+
+### 1. Domain Constants (`scheduler/data/config.py`)
+**Purpose**: Immutable domain knowledge that never changes.
+
+**Contains**:
+- `STAGES` - Legal case lifecycle stages from domain knowledge
+- `TERMINAL_STAGES` - Stages indicating case disposal
+- `CASE_TYPES` - Valid case type taxonomy
+- `CASE_TYPE_DISTRIBUTION` - Historical distribution from EDA
+- `WORKING_DAYS_PER_YEAR` - Court calendar constant (192 days)
+
+**When to use**: Values derived from legal/institutional domain that are facts, not tunable parameters.
+
+### 2. RL Training Configuration (`rl/config.py`)
+**Purpose**: Hyperparameters affecting RL agent learning behavior.
+
+**Class**: `RLTrainingConfig`
+
+**Parameters**:
+- `episodes`: Number of training episodes
+- `cases_per_episode`: Cases generated per episode
+- `episode_length_days`: Simulation horizon per episode
+- `learning_rate`: Q-learning alpha parameter
+- `discount_factor`: Q-learning gamma parameter
+- `initial_epsilon`: Starting exploration rate
+- `epsilon_decay`: Exploration decay factor
+- `min_epsilon`: Minimum exploration threshold
+
+**Presets**:
+- `DEFAULT_RL_TRAINING_CONFIG` - Standard training (100 episodes)
+- `QUICK_DEMO_RL_CONFIG` - Fast testing (20 episodes)
+
+**When to use**: Experimenting with RL training convergence and exploration strategies.
+
+### 3. Policy Configuration (`rl/config.py`)
+**Purpose**: Policy-specific filtering and prioritization behavior.
+
+**Class**: `PolicyConfig`
+
+**Parameters**:
+- `min_gap_days`: Minimum days between hearings (fairness constraint)
+- `max_gap_alert_days`: Maximum gap before triggering alerts
+- `old_case_threshold_days`: Age threshold for priority boost
+- `skip_unripe_cases`: Whether to filter unripe cases
+- `allow_old_unripe_cases`: Allow scheduling very old unripe cases
+
+**When to use**: Tuning policy filtering logic without changing core algorithm.
+
+### 4. Simulation Configuration (`scheduler/simulation/engine.py`)
+**Purpose**: Per-simulation operational parameters.
+
+**Class**: `CourtSimConfig`
+
+**Parameters**:
+- `start`: Simulation start date
+- `days`: Duration in days
+- `seed`: Random seed for reproducibility
+- `courtrooms`: Number of courtrooms to simulate
+- `daily_capacity`: Cases per courtroom per day
+- `policy`: Scheduling policy name (`fifo`, `age`, `readiness`, `rl`)
+- `duration_percentile`: EDA percentile for stage durations
+- `rl_agent_path`: Path to trained RL model (required if `policy="rl"`)
+- `log_dir`: Output directory for metrics
+
+**Validation**: `__post_init__` validates RL requirements and path types.
+
+**When to use**: Each simulation run (different policies, time periods, or capacities).
+
+### 5. Pipeline Configuration (`court_scheduler_rl.py`)
+**Purpose**: Orchestrating multi-step workflow execution.
+
+**Class**: `PipelineConfig`
+
+**Parameters**:
+- `n_cases`: Cases to generate for training
+- `start_date`/`end_date`: Training data time window
+- `rl_training`: RLTrainingConfig instance
+- `sim_days`: Simulation duration
+- `policies`: List of policies to compare
+- `output_dir`: Results output location
+- `generate_cause_lists`/`generate_visualizations`: Output options
+
+**When to use**: Running complete training→simulation→analysis workflows.
+
+## Configuration Flow
+
+```
+Pipeline Execution:
+├── PipelineConfig (workflow orchestration)
+│   ├── RLTrainingConfig (training hyperparameters)
+│   └── Data generation params
+│
+└── Per-Policy Simulation:
+    ├── CourtSimConfig (simulation settings)
+    │   └── rl_agent_path (from training output)
+    │
+    └── Policy instantiation:
+        └── PolicyConfig (policy-specific settings)
+```
+
+## Design Principles
+
+1. **Separation of Concerns**: Each config class owns one domain
+2. **Type Safety**: Dataclasses with validation in `__post_init__`
+3. **No Magic**: Explicit parameters, no hidden defaults
+4. **Immutability**: Domain constants never change
+5. **Composition**: Configs nest (PipelineConfig contains RLTrainingConfig)
+
+## Examples
+
+### Quick Demo
+```python
+from rl.config import QUICK_DEMO_RL_CONFIG
+
+config = PipelineConfig(
+    n_cases=10000,
+    rl_training=QUICK_DEMO_RL_CONFIG,  # 20 episodes
+    sim_days=90,
+    output_dir="data/quick_demo"
+)
+```
+
+### Custom Training
+```python
+from rl.config import RLTrainingConfig
+
+custom_rl = RLTrainingConfig(
+    episodes=500,
+    learning_rate=0.1,
+    initial_epsilon=0.3,
+    epsilon_decay=0.995
+)
+
+config = PipelineConfig(
+    n_cases=50000,
+    rl_training=custom_rl,
+    sim_days=730
+)
+```
+
+### Policy Tuning
+```python
+from rl.config import PolicyConfig
+
+strict_policy = PolicyConfig(
+    min_gap_days=14,  # More conservative
+    skip_unripe_cases=True,
+    allow_old_unripe_cases=False  # Strict ripeness enforcement
+)
+
+# Pass to RLPolicy
+policy = RLPolicy(agent_path=model_path, policy_config=strict_policy)
+```
+
+## Migration Guide
+
+### Adding New Configuration
+1. Determine layer (domain constant vs. tunable parameter)
+2. Add to appropriate config class
+3. Update `__post_init__` validation if needed
+4. Document in this file
+
+### Deprecating Parameters
+1. Move to config class first (keep old path working)
+2. Add deprecation warning
+3. Remove old path after one release cycle
+
+## Validation Rules
+
+All config classes validate in `__post_init__`:
+- Value ranges (0 < learning_rate ≤ 1)
+- Type consistency (convert strings to Path)
+- Cross-parameter constraints (max_gap ≥ min_gap)
+- Required file existence (rl_agent_path must exist)
+
+## Anti-Patterns
+
+**DON'T**:
+- ❌ Hardcode magic numbers in algorithms
+- ❌ Use module-level mutable globals
+- ❌ Mix domain constants with tunable parameters
+- ❌ Create "god config" with everything in one class
+
+**DO**:
+- ✓ Separate by lifecycle and ownership
+- ✓ Validate early (constructor time)
+- ✓ Use dataclasses for immutability
+- ✓ Provide sensible defaults with named presets

docs/OUTPUT_REFACTORING.md

@@ -0,0 +1,88 @@
+# Output Directory Refactoring - Implementation Status
+
+## Completed
+
+### 1. Created `OutputManager` class
+- **File**: `scheduler/utils/output_manager.py`
+- **Features**:
+  - Single run directory with timestamp-based ID
+  - Clean hierarchy: `eda/` `training/` `simulation/` `reports/`
+  - Property-based access to all output paths
+  - Config saved to run root for reproducibility
+
+### 2. Integrated into Pipeline
+- **File**: `court_scheduler_rl.py`
+- **Changes**:
+  - `PipelineConfig` no longer has `output_dir` field
+  - `InteractivePipeline` uses `OutputManager` instance
+  - All `self.output_dir` references replaced with `self.output.{property}`
+  - Pipeline compiles successfully
+
+## Completed Tasks
+
+### 1. Remove Duplicate Model Saving (DONE)
+- Removed duplicate model save in court_scheduler_rl.py
+- Implemented `OutputManager.create_model_symlink()` method
+- Model saved once to `outputs/runs/{run_id}/training/agent.pkl`
+- Symlink created at `models/latest.pkl`
+
+### 2. Update EDA Output Paths (DONE)
+- Modified `src/eda_config.py` with:
+  - `set_output_paths()` function to configure from OutputManager
+  - Private getter functions (`_get_run_dir()`, `_get_params_dir()`, etc.)
+  - Fallback to legacy paths when running standalone
+- Updated all EDA modules (eda_load_clean.py, eda_exploration.py, eda_parameters.py)
+- Pipeline calls `set_output_paths()` before running EDA steps
+- EDA outputs now write to `outputs/runs/{run_id}/eda/`
+
+### 3. Fix Import Errors (DONE)
+- Fixed syntax errors in EDA imports (removed parentheses from function names)
+- All modules compile without errors
+
+### 4. Test End-to-End (DONE)
+```bash
+uv run python court_scheduler_rl.py quick
+```
+
+**Status**: SUCCESS (Exit code: 0)
+- All outputs in `outputs/runs/run_20251126_055943/`
+- No scattered files
+- Models symlinked correctly at `models/latest.pkl`
+- Pipeline runs without errors
+- Clean directory structure verified with `tree` command
+
+## New Directory Structure
+
+```
+outputs/
+└── runs/
+    └── run_20251126_123456/
+        ├── config.json
+        ├── eda/
+        │   ├── figures/
+        │   ├── params/
+        │   └── data/
+        ├── training/
+        │   ├── cases.csv
+        │   ├── agent.pkl
+        │   └── stats.json
+        ├── simulation/
+        │   ├── readiness/
+        │   └── rl/
+        └── reports/
+            ├── EXECUTIVE_SUMMARY.md
+            ├── COMPARISON_REPORT.md
+            └── visualizations/
+
+models/
+└── latest.pkl -> ../outputs/runs/run_20251126_123456/training/agent.pkl
+```
+
+## Benefits Achieved
+
+1. **Single source of truth**: All run artifacts in one directory
+2. **Reproducibility**: Config saved with outputs
+3. **No duplication**: Files written once, not copied
+4. **Clear hierarchy**: Logical organization by pipeline phase
+5. **Easy cleanup**: Delete entire run directory
+6. **Version control**: Run IDs sortable by timestamp

rl/config.py

@@ -0,0 +1,94 @@
+"""RL training configuration and hyperparameters.
+
+This module contains all configurable parameters for RL agent training,
+separate from domain constants and simulation settings.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RLTrainingConfig:
+    """Configuration for RL agent training.
+    
+    Hyperparameters that affect learning behavior and convergence.
+    """
+    # Training episodes
+    episodes: int = 100
+    cases_per_episode: int = 1000
+    episode_length_days: int = 60
+    
+    # Q-learning hyperparameters
+    learning_rate: float = 0.15
+    discount_factor: float = 0.95
+    
+    # Exploration strategy
+    initial_epsilon: float = 0.4
+    epsilon_decay: float = 0.99
+    min_epsilon: float = 0.05
+    
+    # Training data generation
+    training_seed: int = 42
+    stage_mix_auto: bool = True  # Use EDA-derived stage distribution
+    
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if not (0.0 < self.learning_rate <= 1.0):
+            raise ValueError(f"learning_rate must be in (0, 1], got {self.learning_rate}")
+        
+        if not (0.0 <= self.discount_factor <= 1.0):
+            raise ValueError(f"discount_factor must be in [0, 1], got {self.discount_factor}")
+        
+        if not (0.0 <= self.initial_epsilon <= 1.0):
+            raise ValueError(f"initial_epsilon must be in [0, 1], got {self.initial_epsilon}")
+        
+        if self.episodes < 1:
+            raise ValueError(f"episodes must be >= 1, got {self.episodes}")
+        
+        if self.cases_per_episode < 1:
+            raise ValueError(f"cases_per_episode must be >= 1, got {self.cases_per_episode}")
+
+
+@dataclass
+class PolicyConfig:
+    """Configuration for scheduling policy behavior.
+    
+    Settings that affect how policies prioritize and filter cases.
+    """
+    # Minimum gap between hearings (days)
+    min_gap_days: int = 7  # From MIN_GAP_BETWEEN_HEARINGS in config.py
+    
+    # Maximum gap before alert (days)
+    max_gap_alert_days: int = 90  # From MAX_GAP_WITHOUT_ALERT
+    
+    # Old case threshold for priority boost (days)
+    old_case_threshold_days: int = 180
+    
+    # Ripeness filtering
+    skip_unripe_cases: bool = True
+    allow_old_unripe_cases: bool = True  # Allow scheduling if age > old_case_threshold
+    
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if self.min_gap_days < 0:
+            raise ValueError(f"min_gap_days must be >= 0, got {self.min_gap_days}")
+        
+        if self.max_gap_alert_days < self.min_gap_days:
+            raise ValueError(
+                f"max_gap_alert_days ({self.max_gap_alert_days}) must be >= "
+                f"min_gap_days ({self.min_gap_days})"
+            )
+
+
+# Default configurations
+DEFAULT_RL_TRAINING_CONFIG = RLTrainingConfig()
+DEFAULT_POLICY_CONFIG = PolicyConfig()
+
+# Quick demo configuration (for testing)
+QUICK_DEMO_RL_CONFIG = RLTrainingConfig(
+    episodes=20,
+    cases_per_episode=1000,
+    episode_length_days=45,
+    learning_rate=0.15,
+    initial_epsilon=0.4,
+)

scheduler/utils/output_manager.py

@@ -0,0 +1,160 @@
+"""Centralized output directory management.
+
+Provides clean, hierarchical output structure for all pipeline artifacts.
+No scattered files, no duplicate saves, single source of truth per run.
+"""
+
+from pathlib import Path
+from datetime import datetime
+from typing import Optional
+import json
+from dataclasses import asdict
+
+
+class OutputManager:
+    """Manages all output paths for a pipeline run.
+    
+    Design principles:
+    - Single run directory contains ALL artifacts
+    - No copying/moving files between directories
+    - Clear hierarchy: eda/ training/ simulation/ reports/
+    - Run ID is timestamp-based for sorting
+    - Config saved at root for reproducibility
+    """
+    
+    def __init__(self, run_id: Optional[str] = None, base_dir: Optional[Path] = None):
+        """Initialize output manager for a pipeline run.
+        
+        Args:
+            run_id: Unique run identifier (default: timestamp)
+            base_dir: Base directory for all outputs (default: outputs/runs)
+        """
+        self.run_id = run_id or f"run_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+        
+        # Base paths
+        project_root = Path(__file__).parent.parent.parent
+        self.base_dir = base_dir or (project_root / "outputs" / "runs")
+        self.run_dir = self.base_dir / self.run_id
+        
+        # Primary output directories
+        self.eda_dir = self.run_dir / "eda"
+        self.training_dir = self.run_dir / "training"
+        self.simulation_dir = self.run_dir / "simulation"
+        self.reports_dir = self.run_dir / "reports"
+        
+        # EDA subdirectories
+        self.eda_figures = self.eda_dir / "figures"
+        self.eda_params = self.eda_dir / "params"
+        self.eda_data = self.eda_dir / "data"
+        
+        # Reports subdirectories
+        self.visualizations_dir = self.reports_dir / "visualizations"
+        
+    def create_structure(self):
+        """Create all output directories."""
+        for dir_path in [
+            self.run_dir,
+            self.eda_dir,
+            self.eda_figures,
+            self.eda_params,
+            self.eda_data,
+            self.training_dir,
+            self.simulation_dir,
+            self.reports_dir,
+            self.visualizations_dir,
+        ]:
+            dir_path.mkdir(parents=True, exist_ok=True)
+    
+    def save_config(self, config):
+        """Save pipeline configuration to run directory.
+        
+        Args:
+            config: PipelineConfig or any dataclass
+        """
+        config_path = self.run_dir / "config.json"
+        with open(config_path, 'w') as f:
+            # Handle nested dataclasses (like rl_training)
+            config_dict = asdict(config) if hasattr(config, '__dataclass_fields__') else config
+            json.dump(config_dict, f, indent=2, default=str)
+    
+    def get_policy_dir(self, policy_name: str) -> Path:
+        """Get simulation directory for a specific policy.
+        
+        Args:
+            policy_name: Policy name (e.g., 'readiness', 'rl')
+            
+        Returns:
+            Path to policy simulation directory
+        """
+        policy_dir = self.simulation_dir / policy_name
+        policy_dir.mkdir(parents=True, exist_ok=True)
+        return policy_dir
+    
+    def get_cause_list_dir(self, policy_name: str) -> Path:
+        """Get cause list directory for a policy.
+        
+        Args:
+            policy_name: Policy name
+            
+        Returns:
+            Path to cause list directory
+        """
+        cause_list_dir = self.get_policy_dir(policy_name) / "cause_lists"
+        cause_list_dir.mkdir(parents=True, exist_ok=True)
+        return cause_list_dir
+    
+    @property
+    def training_cases_file(self) -> Path:
+        """Path to generated training cases CSV."""
+        return self.training_dir / "cases.csv"
+    
+    @property
+    def trained_model_file(self) -> Path:
+        """Path to trained RL agent model."""
+        return self.training_dir / "agent.pkl"
+    
+    @property
+    def training_stats_file(self) -> Path:
+        """Path to training statistics JSON."""
+        return self.training_dir / "stats.json"
+    
+    @property
+    def executive_summary_file(self) -> Path:
+        """Path to executive summary markdown."""
+        return self.reports_dir / "EXECUTIVE_SUMMARY.md"
+    
+    @property
+    def comparison_report_file(self) -> Path:
+        """Path to comparison report markdown."""
+        return self.reports_dir / "COMPARISON_REPORT.md"
+    
+    def create_model_symlink(self, alias: str = "latest"):
+        """Create symlink in models/ directory pointing to trained model.
+        
+        Args:
+            alias: Symlink name (e.g., 'latest', 'v1.0')
+        """
+        project_root = self.run_dir.parent.parent.parent
+        models_dir = project_root / "models"
+        models_dir.mkdir(exist_ok=True)
+        
+        symlink_path = models_dir / f"{alias}.pkl"
+        target = self.trained_model_file
+        
+        # Remove existing symlink if present
+        if symlink_path.exists() or symlink_path.is_symlink():
+            symlink_path.unlink()
+        
+        # Create symlink (use absolute path for cross-directory links)
+        try:
+            symlink_path.symlink_to(target.resolve())
+        except (OSError, NotImplementedError):
+            # Fallback: copy file if symlinks not supported (Windows without dev mode)
+            import shutil
+            shutil.copy2(target, symlink_path)
+    
+    def __str__(self) -> str:
+        return f"OutputManager(run_id='{self.run_id}', run_dir='{self.run_dir}')"
+    
+    def __repr__(self) -> str:
+        return self.__str__()

src/eda_config.py

@@ -8,27 +8,80 @@ from pathlib import Path
 # -------------------------------------------------------------------
 # Paths and versioning
 # -------------------------------------------------------------------
-DATA_DIR = Path("Data")
+# Project root (repo root) = parent of src/
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+DATA_DIR = PROJECT_ROOT / "Data"
 DUCKDB_FILE = DATA_DIR / "court_data.duckdb"
 CASES_FILE = DATA_DIR / "ISDMHack_Cases_WPfinal.csv"
 HEAR_FILE = DATA_DIR / "ISDMHack_Hear.csv"
 
-REPORTS_DIR = Path("reports")
+# Default paths (used when EDA is run standalone)
+REPORTS_DIR = PROJECT_ROOT / "reports"
 FIGURES_DIR = REPORTS_DIR / "figures"
-FIGURES_DIR.mkdir(parents=True, exist_ok=True)
 
 VERSION = "v0.4.0"
 RUN_TS = datetime.now().strftime("%Y%m%d_%H%M%S")
 
-RUN_DIR = FIGURES_DIR / f"{VERSION}_{RUN_TS}"
-RUN_DIR.mkdir(parents=True, exist_ok=True)
+# These will be set by set_output_paths() when running from pipeline
+RUN_DIR = None
+PARAMS_DIR = None
+CASES_CLEAN_PARQUET = None
+HEARINGS_CLEAN_PARQUET = None
+
+
+def set_output_paths(eda_dir: Path, data_dir: Path, params_dir: Path):
+    """Configure output paths from OutputManager.
+    
+    Call this from pipeline before running EDA modules.
+    When not called, falls back to legacy reports/figures/ structure.
+    """
+    global RUN_DIR, PARAMS_DIR, CASES_CLEAN_PARQUET, HEARINGS_CLEAN_PARQUET
+    RUN_DIR = eda_dir
+    PARAMS_DIR = params_dir
+    CASES_CLEAN_PARQUET = data_dir / "cases_clean.parquet"
+    HEARINGS_CLEAN_PARQUET = data_dir / "hearings_clean.parquet"
+    
+    # Ensure directories exist
+    RUN_DIR.mkdir(parents=True, exist_ok=True)
+    PARAMS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _get_run_dir() -> Path:
+    """Get RUN_DIR, creating default if not set."""
+    global RUN_DIR
+    if RUN_DIR is None:
+        # Standalone mode: use legacy versioned directory
+        FIGURES_DIR.mkdir(parents=True, exist_ok=True)
+        RUN_DIR = FIGURES_DIR / f"{VERSION}_{RUN_TS}"
+        RUN_DIR.mkdir(parents=True, exist_ok=True)
+    return RUN_DIR
+
+
+def _get_params_dir() -> Path:
+    """Get PARAMS_DIR, creating default if not set."""
+    global PARAMS_DIR
+    if PARAMS_DIR is None:
+        run_dir = _get_run_dir()
+        PARAMS_DIR = run_dir / "params"
+        PARAMS_DIR.mkdir(parents=True, exist_ok=True)
+    return PARAMS_DIR
+
 
-PARAMS_DIR = RUN_DIR / "params"
-PARAMS_DIR.mkdir(parents=True, exist_ok=True)
+def _get_cases_parquet() -> Path:
+    """Get CASES_CLEAN_PARQUET path."""
+    global CASES_CLEAN_PARQUET
+    if CASES_CLEAN_PARQUET is None:
+        CASES_CLEAN_PARQUET = _get_run_dir() / "cases_clean.parquet"
+    return CASES_CLEAN_PARQUET
 
-# cleaned data outputs
-CASES_CLEAN_PARQUET = RUN_DIR / "cases_clean.parquet"
-HEARINGS_CLEAN_PARQUET = RUN_DIR / "hearings_clean.parquet"
+
+def _get_hearings_parquet() -> Path:
+    """Get HEARINGS_CLEAN_PARQUET path."""
+    global HEARINGS_CLEAN_PARQUET
+    if HEARINGS_CLEAN_PARQUET is None:
+        HEARINGS_CLEAN_PARQUET = _get_run_dir() / "hearings_clean.parquet"
+    return HEARINGS_CLEAN_PARQUET
 
 # -------------------------------------------------------------------
 # Null tokens and canonicalisation
@@ -37,21 +90,31 @@ NULL_TOKENS = ["", "NULL", "Null", "null", "NA", "N/A", "na", "NaN", "nan", "-",
 
 
 def copy_to_versioned(filename: str) -> None:
-    """Copy a file from FIGURES_DIR to RUN_DIR for versioned snapshots."""
-    src = FIGURES_DIR / filename
-    dst = RUN_DIR / filename
-    try:
-        if src.exists():
-            shutil.copyfile(src, dst)
-    except Exception as e:
-        print(f"[WARN] Versioned copy failed for {filename}: {e}")
+    """Deprecated: No longer needed with OutputManager."""
+    pass
 
 
 def write_metadata(meta: dict) -> None:
     """Write run metadata into RUN_DIR/metadata.json."""
-    meta_path = RUN_DIR / "metadata.json"
+    run_dir = _get_run_dir()
+    meta_path = run_dir / "metadata.json"
     try:
         with open(meta_path, "w", encoding="utf-8") as f:
             json.dump(meta, f, indent=2, default=str)
     except Exception as e:
         print(f"[WARN] Metadata export error: {e}")
+
+
+def safe_write_figure(fig, filename: str) -> None:
+    """Write plotly figure to EDA figures directory.
+    
+    Args:
+        fig: Plotly figure object
+        filename: HTML filename (e.g., "1_case_type_distribution.html")
+    """
+    run_dir = _get_run_dir()
+    output_path = run_dir / filename
+    try:
+        fig.write_html(str(output_path))
+    except Exception as e:
+        raise RuntimeError(f"Failed to write {filename} to {output_path}: {e}")

src/eda_exploration.py

@@ -13,7 +13,7 @@ Inputs:
 - Cleaned Parquet from eda_load_clean.
 
 Outputs:
-- Interactive HTML plots in FIGURES_DIR and versioned copies in RUN_DIR.
+- Interactive HTML plots in FIGURES_DIR and versioned copies in _get_run_dir().
 - Some CSV summaries (e.g., stage_duration.csv, transitions.csv, monthly_anomalies.csv).
 """
 
@@ -25,19 +25,19 @@ import plotly.graph_objects as go
 import plotly.io as pio
 import polars as pl
 from src.eda_config import (
-    CASES_CLEAN_PARQUET,
+    _get_cases_parquet,
     FIGURES_DIR,
-    HEARINGS_CLEAN_PARQUET,
-    RUN_DIR,
-    copy_to_versioned,
+    _get_hearings_parquet,
+    _get_run_dir,
+    safe_write_figure,
 )
 
 pio.renderers.default = "browser"
 
 
 def load_cleaned():
-    cases = pl.read_parquet(CASES_CLEAN_PARQUET)
-    hearings = pl.read_parquet(HEARINGS_CLEAN_PARQUET)
+    cases = pl.read_parquet(_get_cases_parquet())
+    hearings = pl.read_parquet(_get_hearings_parquet())
     print("Loaded cleaned data for exploration")
     print("Cases:", cases.shape, "Hearings:", hearings.shape)
     return cases, hearings
@@ -58,9 +58,7 @@ def run_exploration() -> None:
         title="Case Type Distribution",
     )
     fig1.update_layout(showlegend=False, xaxis_title="Case Type", yaxis_title="Number of Cases")
-    f1 = "1_case_type_distribution.html"
-    fig1.write_html(str(FIGURES_DIR / f1))
-    copy_to_versioned(f1)
+    safe_write_figure(fig1, "1_case_type_distribution.html")
 
     # --------------------------------------------------
     # 2. Filing Trends by Year
@@ -73,8 +71,7 @@ def run_exploration() -> None:
         fig2.update_traces(line_color="royalblue")
         fig2.update_layout(xaxis=dict(rangeslider=dict(visible=True)))
         f2 = "2_cases_filed_by_year.html"
-        fig2.write_html(str(FIGURES_DIR / f2))
-        copy_to_versioned(f2)
+        safe_write_figure(fig2, f2)
 
     # --------------------------------------------------
     # 3. Disposal Duration Distribution
@@ -89,8 +86,7 @@ def run_exploration() -> None:
         )
         fig3.update_layout(xaxis_title="Days", yaxis_title="Cases")
         f3 = "3_disposal_time_distribution.html"
-        fig3.write_html(str(FIGURES_DIR / f3))
-        copy_to_versioned(f3)
+        safe_write_figure(fig3, f3)
 
     # --------------------------------------------------
     # 4. Hearings vs Disposal Time
@@ -106,8 +102,7 @@ def run_exploration() -> None:
         )
         fig4.update_traces(marker=dict(size=6, opacity=0.7))
         f4 = "4_hearings_vs_disposal.html"
-        fig4.write_html(str(FIGURES_DIR / f4))
-        copy_to_versioned(f4)
+        safe_write_figure(fig4, f4)
 
     # --------------------------------------------------
     # 5. Boxplot by Case Type
@@ -121,8 +116,7 @@ def run_exploration() -> None:
     )
     fig5.update_layout(showlegend=False)
     f5 = "5_box_disposal_by_type.html"
-    fig5.write_html(str(FIGURES_DIR / f5))
-    copy_to_versioned(f5)
+    safe_write_figure(fig5, f5)
 
     # --------------------------------------------------
     # 6. Stage Frequency
@@ -139,8 +133,7 @@ def run_exploration() -> None:
         )
         fig6.update_layout(showlegend=False, xaxis_title="Stage", yaxis_title="Count")
         f6 = "6_stage_frequency.html"
-        fig6.write_html(str(FIGURES_DIR / f6))
-        copy_to_versioned(f6)
+        safe_write_figure(fig6, f6)
 
     # --------------------------------------------------
     # 7. Gap median by case type
@@ -154,8 +147,7 @@ def run_exploration() -> None:
             title="Median Hearing Gap by Case Type",
         )
         fg = "9_gap_median_by_type.html"
-        fig_gap.write_html(str(FIGURES_DIR / fg))
-        copy_to_versioned(fg)
+        safe_write_figure(fig_gap, fg)
 
     # --------------------------------------------------
     # 8. Stage transitions & bottleneck plot
@@ -219,7 +211,7 @@ def run_exploration() -> None:
             <= pl.col("STAGE_TO").map_elements(lambda s: order_idx.get(s, 10))
         ).sort("N", descending=True)
 
-        transitions.write_csv(RUN_DIR / "transitions.csv")
+        transitions.write_csv(str(_get_run_dir() / "transitions.csv"))
 
         runs = (
             h_stage.with_columns(
@@ -256,7 +248,7 @@ def run_exploration() -> None:
             )
             .sort("RUN_MEDIAN_DAYS", descending=True)
         )
-        stage_duration.write_csv(RUN_DIR / "stage_duration.csv")
+        stage_duration.write_csv(str(_get_run_dir() / "stage_duration.csv"))
 
         # Sankey
         try:
@@ -284,8 +276,7 @@ def run_exploration() -> None:
             )
             sankey.update_layout(title_text="Stage Transition Sankey (Ordered)")
             f10 = "10_stage_transition_sankey.html"
-            sankey.write_html(str(FIGURES_DIR / f10))
-            copy_to_versioned(f10)
+            safe_write_figure(sankey, f10)
         except Exception as e:
             print("Sankey error:", e)
 
@@ -301,8 +292,7 @@ def run_exploration() -> None:
                 title="Stage Bottleneck Impact (Median Days x Runs)",
             )
             fb = "15_bottleneck_impact.html"
-            fig_b.write_html(str(FIGURES_DIR / fb))
-            copy_to_versioned(fb)
+            safe_write_figure(fig_b, fb)
         except Exception as e:
             print("Bottleneck plot error:", e)
 
@@ -321,7 +311,7 @@ def run_exploration() -> None:
             .with_columns(pl.date(pl.col("Y"), pl.col("M"), pl.lit(1)).alias("YM"))
         )
         monthly_listings = m_hear.group_by("YM").agg(pl.len().alias("N_HEARINGS")).sort("YM")
-        monthly_listings.write_csv(RUN_DIR / "monthly_hearings.csv")
+        monthly_listings.write_csv(str(_get_run_dir() / "monthly_hearings.csv"))
 
         try:
             fig_m = px.line(
@@ -332,8 +322,7 @@ def run_exploration() -> None:
             )
             fig_m.update_layout(yaxis=dict(tickformat=",d"))
             fm = "11_monthly_hearings.html"
-            fig_m.write_html(str(FIGURES_DIR / fm))
-            copy_to_versioned(fm)
+            safe_write_figure(fig_m, fm)
         except Exception as e:
             print("Monthly listings error:", e)
 
@@ -380,12 +369,11 @@ def run_exploration() -> None:
                 yaxis=dict(tickformat=",d"),
             )
             fw = "11b_monthly_waterfall.html"
-            fig_w.write_html(str(FIGURES_DIR / fw))
-            copy_to_versioned(fw)
+            safe_write_figure(fig_w, fw)
 
             ml_pd_out = ml_pd.copy()
             ml_pd_out["YM"] = ml_pd_out["YM"].astype(str)
-            ml_pd_out.to_csv(RUN_DIR / "monthly_anomalies.csv", index=False)
+            ml_pd_out.to_csv(str(_get_run_dir() / "monthly_anomalies.csv"), index=False)
         except Exception as e:
             print("Monthly waterfall error:", e)
 
@@ -420,8 +408,7 @@ def run_exploration() -> None:
                 xaxis={"categoryorder": "total descending"}, yaxis=dict(tickformat=",d")
             )
             fj = "12_judge_day_load.html"
-            fig_j.write_html(str(FIGURES_DIR / fj))
-            copy_to_versioned(fj)
+            safe_write_figure(fig_j, fj)
         except Exception as e:
             print("Judge workload error:", e)
 
@@ -447,8 +434,7 @@ def run_exploration() -> None:
                 xaxis={"categoryorder": "total descending"}, yaxis=dict(tickformat=",d")
             )
             fc = "12b_court_day_load.html"
-            fig_court.write_html(str(FIGURES_DIR / fc))
-            copy_to_versioned(fc)
+            safe_write_figure(fig_court, fc)
         except Exception as e:
             print("Court workload error:", e)
 
@@ -488,7 +474,7 @@ def run_exploration() -> None:
             .with_columns((pl.col("N") / pl.col("N").sum().over("CASE_TYPE")).alias("SHARE"))
             .sort(["CASE_TYPE", "SHARE"], descending=[False, True])
         )
-        tag_share.write_csv(RUN_DIR / "purpose_tag_shares.csv")
+        tag_share.write_csv(str(_get_run_dir() / "purpose_tag_shares.csv"))
         try:
             fig_t = px.bar(
                 tag_share.to_pandas(),
@@ -499,8 +485,7 @@ def run_exploration() -> None:
                 barmode="stack",
             )
             ft = "14_purpose_tag_shares.html"
-            fig_t.write_html(str(FIGURES_DIR / ft))
-            copy_to_versioned(ft)
+            safe_write_figure(fig_t, ft)
         except Exception as e:
             print("Purpose shares error:", e)
 

src/eda_load_clean.py

@@ -13,9 +13,9 @@ from datetime import timedelta
 import polars as pl
 import duckdb
 from src.eda_config import (
-    CASES_CLEAN_PARQUET,
+    _get_cases_parquet,
     DUCKDB_FILE,
-    HEARINGS_CLEAN_PARQUET,
+    _get_hearings_parquet,
     NULL_TOKENS,
     RUN_TS,
     VERSION,
@@ -224,10 +224,10 @@ def clean_and_augment(
 
 
 def save_clean(cases: pl.DataFrame, hearings: pl.DataFrame) -> None:
-    cases.write_parquet(CASES_CLEAN_PARQUET)
-    hearings.write_parquet(HEARINGS_CLEAN_PARQUET)
-    print(f"Saved cleaned cases -> {CASES_CLEAN_PARQUET}")
-    print(f"Saved cleaned hearings -> {HEARINGS_CLEAN_PARQUET}")
+    cases.write_parquet(str(_get_cases_parquet()))
+    hearings.write_parquet(str(_get_hearings_parquet()))
+    print(f"Saved cleaned cases -> {str(_get_cases_parquet())}")
+    print(f"Saved cleaned hearings -> {str(_get_hearings_parquet())}")
 
     meta = {
         "version": VERSION,

src/eda_parameters.py

@@ -8,7 +8,7 @@ Responsibilities:
 - Entropy of stage transitions (predictability).
 - Case-type summary stats (disposal, hearing counts, gaps).
 - Readiness score and alert flags per case.
-- Export JSON/CSV parameter files into PARAMS_DIR.
+- Export JSON/CSV parameter files into _get_params_dir().
 """
 
 import json
@@ -16,15 +16,15 @@ from datetime import timedelta
 
 import polars as pl
 from src.eda_config import (
-    CASES_CLEAN_PARQUET,
-    HEARINGS_CLEAN_PARQUET,
-    PARAMS_DIR,
+    _get_cases_parquet,
+    _get_hearings_parquet,
+    _get_params_dir,
 )
 
 
 def load_cleaned():
-    cases = pl.read_parquet(CASES_CLEAN_PARQUET)
-    hearings = pl.read_parquet(HEARINGS_CLEAN_PARQUET)
+    cases = pl.read_parquet(_get_cases_parquet())
+    hearings = pl.read_parquet(_get_hearings_parquet())
     return cases, hearings
 
 
@@ -94,14 +94,14 @@ def extract_parameters() -> None:
             <= pl.col("STAGE_TO").map_elements(lambda s: order_idx.get(s, 10))
         ).sort("N", descending=True)
 
-        transitions.write_csv(PARAMS_DIR / "stage_transitions.csv")
+        transitions.write_csv(str(_get_params_dir() / "stage_transitions.csv"))
 
         # Probabilities per STAGE_FROM
         row_tot = transitions.group_by("STAGE_FROM").agg(pl.col("N").sum().alias("row_n"))
         trans_probs = transitions.join(row_tot, on="STAGE_FROM").with_columns(
             (pl.col("N") / pl.col("row_n")).alias("p")
         )
-        trans_probs.write_csv(PARAMS_DIR / "stage_transition_probs.csv")
+        trans_probs.write_csv(str(_get_params_dir() / "stage_transition_probs.csv"))
 
         # Entropy of transitions
         ent = (
@@ -109,7 +109,7 @@ def extract_parameters() -> None:
             .agg((-(pl.col("p") * pl.col("p").log()).sum()).alias("entropy"))
             .sort("entropy", descending=True)
         )
-        ent.write_csv(PARAMS_DIR / "stage_transition_entropy.csv")
+        ent.write_csv(str(_get_params_dir() / "stage_transition_entropy.csv"))
 
         # Stage residence (runs)
         runs = (
@@ -147,7 +147,7 @@ def extract_parameters() -> None:
             )
             .sort("RUN_MEDIAN_DAYS", descending=True)
         )
-        stage_duration.write_csv(PARAMS_DIR / "stage_duration.csv")
+        stage_duration.write_csv(str(_get_params_dir() / "stage_duration.csv"))
 
     # --------------------------------------------------
     # 2. Court capacity (cases per courtroom per day)
@@ -169,13 +169,13 @@ def extract_parameters() -> None:
             )
             .sort("slots_median", descending=True)
         )
-        cap_stats.write_csv(PARAMS_DIR / "court_capacity_stats.csv")
+        cap_stats.write_csv(str(_get_params_dir() / "court_capacity_stats.csv"))
         # simple global aggregate
         capacity_stats = {
             "slots_median_global": float(cap["heard_count"].median()),
             "slots_p90_global": float(cap["heard_count"].quantile(0.9)),
         }
-        with open(PARAMS_DIR / "court_capacity_global.json", "w") as f:
+        with open(str(_get_params_dir() / "court_capacity_global.json"), "w") as f:
             json.dump(capacity_stats, f, indent=2)
 
     # --------------------------------------------------
@@ -245,7 +245,7 @@ def extract_parameters() -> None:
             )
             .sort(["Remappedstages", "casetype"])
         )
-        outcome_stage.write_csv(PARAMS_DIR / "adjournment_proxies.csv")
+        outcome_stage.write_csv(str(_get_params_dir() / "adjournment_proxies.csv"))
 
     # --------------------------------------------------
     # 4. Case-type summary and correlations
@@ -263,13 +263,13 @@ def extract_parameters() -> None:
         )
         .sort("n_cases", descending=True)
     )
-    by_type.write_csv(PARAMS_DIR / "case_type_summary.csv")
+    by_type.write_csv(str(_get_params_dir() / "case_type_summary.csv"))
 
     # Correlations for a quick diagnostic
     corr_cols = ["DISPOSALTIME_ADJ", "N_HEARINGS", "GAP_MEDIAN"]
     corr_df = cases.select(corr_cols).to_pandas()
     corr = corr_df.corr(method="spearman")
-    corr.to_csv(PARAMS_DIR / "correlations_spearman.csv")
+    corr.to_csv(str(_get_params_dir() / "correlations_spearman.csv"))
 
     # --------------------------------------------------
     # 5. Readiness score and alerts
@@ -364,7 +364,7 @@ def extract_parameters() -> None:
         "ALERT_LONG_GAP",
     ]
     feature_cols_existing = [c for c in feature_cols if c in cases.columns]
-    cases.select(feature_cols_existing).write_csv(PARAMS_DIR / "cases_features.csv")
+    cases.select(feature_cols_existing).write_csv(str(_get_params_dir() / "cases_features.csv"))
 
     # Simple age funnel
     if {"DATE_FILED", "DECISION_DATE"}.issubset(cases.columns):
@@ -388,12 +388,12 @@ def extract_parameters() -> None:
             .agg(pl.len().alias("N"))
             .sort("AGE_BUCKET")
         )
-        age_funnel.write_csv(PARAMS_DIR / "age_funnel.csv")
+        age_funnel.write_csv(str(_get_params_dir() / "age_funnel.csv"))
 
 
 def run_parameter_export() -> None:
     extract_parameters()
-    print("Parameter extraction complete. Files in:", PARAMS_DIR.resolve())
+    print("Parameter extraction complete. Files in:", _get_params_dir().resolve())
 
 
 if __name__ == "__main__":