Publish EdgeEDA agent

CHANGELOG_FIXES.md

@@ -0,0 +1,244 @@
+# Changelog: Immediate and Short-term Fixes
+
+## Summary
+
+This document tracks the immediate and short-term fixes implemented based on the repository analysis.
+
+---
+
+## Immediate Fixes (Completed)
+
+### 1. ✅ Comprehensive Logging Added (`src/edgeeda/cli.py`)
+
+**Changes:**
+- Added `_setup_logging()` function to configure logging to both file and console
+- Log file created at `{out_dir}/tuning.log`
+- Added detailed logging throughout the tuning loop:
+  - Experiment start/configuration
+  - Each action proposal (variant, fidelity, knobs)
+  - Make command execution results
+  - Metadata extraction attempts
+  - Reward computation results
+  - Summary statistics at completion
+
+**Benefits:**
+- Full visibility into tuning process
+- Easy debugging of failures
+- Historical record of experiments
+
+### 2. ✅ SurrogateUCBAgent Knob Storage Fixed (`src/edgeeda/agents/surrogate_ucb.py`)
+
+**Changes:**
+- Initialize `_variant_knobs` dictionary in `__init__()` instead of lazy initialization
+- Removed `hasattr()` checks - always use `self._variant_knobs`
+- Ensures knob values are always available for promotion logic
+
+**Benefits:**
+- Prevents `AttributeError` when promoting variants
+- More reliable multi-fidelity optimization
+- Cleaner code without hasattr checks
+
+### 3. ✅ Configuration Validation Added (`src/edgeeda/config.py`)
+
+**Changes:**
+- Added `_validate_config()` function with comprehensive checks:
+  - Budget validation (total_actions > 0, max_expensive >= 0, max_expensive <= total_actions)
+  - Fidelities validation (non-empty)
+  - Knobs validation (non-empty, min < max, valid types)
+  - Reward weights validation (non-empty)
+  - Reward candidates validation (at least one list non-empty)
+
+**Benefits:**
+- Catches configuration errors early
+- Clear error messages for invalid configs
+- Prevents runtime failures from bad configs
+
+### 4. ✅ Improved Error Messages (`src/edgeeda/orfs/runner.py`)
+
+**Changes:**
+- Added `RunResult.is_success()` method
+- Added `RunResult.error_summary()` method that:
+  - Extracts error lines from stderr
+  - Falls back to last few lines if no error keywords found
+  - Provides concise error information
+
+**Benefits:**
+- Better error visibility
+- Easier debugging of failed make commands
+- Structured error information
+
+### 5. ✅ Robust Metadata Extraction (`src/edgeeda/orfs/metrics.py`)
+
+**Changes:**
+- Added logging throughout metadata search process
+- Improved `find_best_metadata_json()` with:
+  - Multiple pattern matching (exact matches first, then patterns)
+  - Better error handling for missing directories
+  - Debug logging for search process
+- Enhanced `load_json()` with:
+  - Specific exception handling
+  - Error logging for different failure modes
+
+**Benefits:**
+- More reliable metadata discovery
+  - Tries exact matches: `metadata.json`, `metrics.json`
+  - Then pattern matches: `*metadata*.json`, `*metrics*.json`
+  - Falls back to any JSON file
+- Better debugging when metadata is missing
+- Clear error messages for JSON parsing failures
+
+### 6. ✅ Retry Logic for Transient Failures (`src/edgeeda/orfs/runner.py`)
+
+**Changes:**
+- Added `max_retries` parameter to `run_make()` method
+- Implements exponential backoff (2^attempt seconds)
+- Handles:
+  - Subprocess failures (retries on non-zero return codes)
+  - Timeout exceptions
+  - General exceptions during execution
+
+**Benefits:**
+- Handles transient network/filesystem issues
+- Reduces false failures from temporary problems
+- Configurable retry behavior
+
+---
+
+## Short-term Fixes (Completed)
+
+### 7. ✅ Unit Tests for Agents (`tests/test_agents.py`)
+
+**New Test File:**
+- `test_random_search_proposes()` - Validates random search action proposals
+- `test_random_search_observe()` - Tests observe method
+- `test_successive_halving_initialization()` - Tests SH agent setup
+- `test_successive_halving_propose()` - Tests action proposals
+- `test_successive_halving_promotion()` - Tests multi-fidelity promotion
+- `test_surrogate_ucb_initialization()` - Tests SurrogateUCB setup
+- `test_surrogate_ucb_propose()` - Tests action proposals
+- `test_surrogate_ucb_observe()` - Tests observation storage
+- `test_surrogate_ucb_knob_storage()` - Tests knob storage for promotion
+- `test_surrogate_ucb_surrogate_fitting()` - Tests surrogate model fitting
+- `test_agent_action_consistency()` - Tests all agents produce valid actions
+
+**Coverage:**
+- All three agent types
+- Key agent behaviors (propose, observe, promotion)
+- Edge cases and error handling
+
+### 8. ✅ Unit Tests for Metrics (`tests/test_metrics.py`)
+
+**New Test File:**
+- `test_flatten_metrics_*()` - Tests metric flattening (simple, complex, empty, leaf values)
+- `test_coerce_float_*()` - Tests float coercion (int, float, string, invalid)
+- `test_pick_first_*()` - Tests metric key selection (found, not found, case-insensitive, multiple candidates)
+- `test_load_json_*()` - Tests JSON loading (valid, invalid, missing)
+
+**Coverage:**
+- All metrics utility functions
+- Edge cases and error conditions
+- Type coercion and matching logic
+
+### 9. ✅ Updated Dependencies (`requirements.txt`)
+
+**Changes:**
+- Added `pytest>=7.0` for running unit tests
+
+---
+
+## Testing
+
+To run the new tests:
+
+```bash
+# Install pytest if not already installed
+pip install pytest
+
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_agents.py -v
+pytest tests/test_metrics.py -v
+
+# Run with coverage
+pytest tests/ --cov=edgeeda --cov-report=html
+```
+
+---
+
+## Usage Examples
+
+### Using Logging
+
+Logs are automatically created when running `edgeeda tune`:
+```bash
+edgeeda tune --config configs/gcd_nangate45.yaml --budget 24
+# Logs written to: runs/tuning.log
+```
+
+### Using Retry Logic
+
+Retry logic is available but defaults to 0 retries. To enable:
+```python
+# In cli.py, modify run_make calls:
+rr = runner.run_make(
+    target=make_target,
+    design_config=cfg.design.design_config,
+    flow_variant=action.variant,
+    overrides={k: str(v) for k, v in action.knobs.items()},
+    timeout_sec=args.timeout,
+    max_retries=2,  # Add this parameter
+)
+```
+
+### Configuration Validation
+
+Invalid configurations now fail early with clear messages:
+```python
+# This will raise ValueError:
+cfg = load_config("invalid_config.yaml")
+# ValueError: total_actions must be > 0, got -5
+```
+
+---
+
+## Files Modified
+
+1. `src/edgeeda/cli.py` - Added logging throughout
+2. `src/edgeeda/agents/surrogate_ucb.py` - Fixed knob storage
+3. `src/edgeeda/config.py` - Added validation
+4. `src/edgeeda/orfs/runner.py` - Improved error messages, added retry logic
+5. `src/edgeeda/orfs/metrics.py` - Enhanced metadata extraction with logging
+6. `requirements.txt` - Added pytest
+7. `tests/test_agents.py` - New test file
+8. `tests/test_metrics.py` - New test file
+
+---
+
+## Next Steps
+
+### Recommended Follow-ups:
+
+1. **Run Tests**: Install pytest and verify all tests pass
+2. **Test Logging**: Run a small experiment and verify logs are created
+3. **Test Retry Logic**: Manually test retry behavior with transient failures
+4. **Validate Config**: Try invalid configs to see validation in action
+
+### Future Enhancements:
+
+- Add integration tests with mock ORFS runner
+- Add performance benchmarks
+- Add more visualization options
+- Implement parallel execution
+- Add resume from checkpoint functionality
+
+---
+
+## Notes
+
+- All changes maintain backward compatibility
+- No breaking changes to existing APIs
+- Logging can be disabled by setting log level to WARNING or ERROR
+- Retry logic defaults to 0 (no retries) to maintain current behavior
+- Tests require pytest but don't affect runtime dependencies

EXECUTE_IN_DOCKER.md

@@ -0,0 +1,117 @@
+# Execute Tests and Plots in Docker
+
+## Quick Command
+
+Since Docker is running, execute this inside your container:
+
+```bash
+cd /workspace/edgeeda-agent
+./run_all.sh
+```
+
+Or if you're on the host:
+
+```bash
+docker exec -it <CONTAINER_ID> bash -c "cd /workspace/edgeeda-agent && ./run_all.sh"
+```
+
+## What It Does
+
+1. **Runs all agent tests** - Tests RandomSearch, SuccessiveHalving, and SurrogateUCB agents
+2. **Generates comprehensive plots** - Creates visualization of your experiment data
+
+## Expected Output
+
+```
+==========================================
+EdgeEDA-Agent: Tests and Plots
+==========================================
+
+Step 1: Running Agent Tests...
+----------------------------------------
+Running agent tests...
+
+✅ RandomSearchAgent
+✅ SuccessiveHalvingAgent
+✅ SurrogateUCBAgent
+✅ Metrics Flattening
+✅ Metrics Coercion
+
+==================================================
+Results: 5/5 tests passed
+✅ All tests passed!
+
+
+Step 2: Generating Plots...
+----------------------------------------
+Loading data from runs/experiment.sqlite...
+Found 11 trials
+Successful: 3
+With rewards: 0
+Saved CSV to runs/plots/trials.csv
+Generating plots...
+Generating additional analysis plots...
+  ✓ Saved success_rate.png
+  ✓ Saved runtime_distribution.png
+  ✓ Saved return_code_distribution.png
+  ✓ Saved knob_PLACE_DENSITY.png
+  ✓ Saved knob_CORE_UTILIZATION.png
+
+✅ All plots generated in runs/plots
+
+==========================================
+Summary
+==========================================
+✅ Tests: PASSED
+✅ Plots: Generated successfully
+
+Generated files in runs/plots/:
+  - runs/plots/trials.csv (2.5K)
+  - runs/plots/success_rate.png (45K)
+  - runs/plots/runtime_distribution.png (38K)
+  - runs/plots/return_code_distribution.png (42K)
+  - runs/plots/knob_PLACE_DENSITY.png (35K)
+  - runs/plots/knob_CORE_UTILIZATION.png (36K)
+==========================================
+```
+
+## Manual Execution
+
+If you prefer to run steps separately:
+
+### Tests Only:
+```bash
+python3 run_tests_simple.py
+```
+
+### Plots Only:
+```bash
+python3 generate_plots.py --db runs/experiment.sqlite --out runs/plots
+```
+
+## View Results
+
+### Copy plots to host:
+```bash
+docker cp <CONTAINER_ID>:/workspace/edgeeda-agent/runs/plots ./runs/
+```
+
+### View in container:
+```bash
+# List generated files
+ls -lh runs/plots/
+
+# View CSV
+head runs/plots/trials.csv
+```
+
+## Troubleshooting
+
+**Issue**: "Permission denied" on run_all.sh
+**Fix**: `chmod +x run_all.sh`
+
+**Issue**: "No module named 'pandas'"
+**Solution**: Make sure you're inside Docker container where dependencies are installed
+
+**Issue**: "Database not found"
+**Solution**: Check if experiments have been run: `ls -la runs/experiment.sqlite`

LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Sam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

QUICK_START.md

@@ -0,0 +1,114 @@
+# Quick Start: Run Tests & Generate Plots
+
+## 🚀 One Command to Run Everything
+
+Since Docker is running, execute this **inside your Docker container**:
+
+```bash
+cd /workspace/edgeeda-agent
+./run_all.sh
+```
+
+## 📋 Step-by-Step (If you prefer)
+
+### 1. Enter Docker Container
+
+If you're on the host machine:
+```bash
+cd /Users/thalia/Desktop/EdgePPAgent/edgeeda-agent
+docker run --rm -it -v "$(pwd)":/workspace/edgeeda-agent -w /workspace/edgeeda-agent edgeeda-agent bash
+```
+
+Or if container is already running:
+```bash
+docker exec -it <CONTAINER_ID> bash
+```
+
+### 2. Run Tests
+```bash
+cd /workspace/edgeeda-agent
+python3 run_tests_simple.py
+```
+
+### 3. Generate Plots
+```bash
+python3 generate_plots.py --db runs/experiment.sqlite --out runs/plots
+```
+
+### 4. View Results
+```bash
+# List generated files
+ls -lh runs/plots/
+
+# View test results (already shown in console)
+# View plots (copy to host if needed)
+```
+
+## 📊 Expected Output
+
+### Tests:
+```
+Running agent tests...
+
+✅ RandomSearchAgent
+✅ SuccessiveHalvingAgent
+✅ SurrogateUCBAgent
+✅ Metrics Flattening
+✅ Metrics Coercion
+
+==================================================
+Results: 5/5 tests passed
+✅ All tests passed!
+```
+
+### Plots:
+```
+Loading data from runs/experiment.sqlite...
+Found 11 trials
+Successful: 3
+With rewards: 0
+Saved CSV to runs/plots/trials.csv
+Generating plots...
+  ✓ Saved success_rate.png
+  ✓ Saved runtime_distribution.png
+  ✓ Saved return_code_distribution.png
+  ✓ Saved knob_PLACE_DENSITY.png
+  ✓ Saved knob_CORE_UTILIZATION.png
+
+✅ All plots generated in runs/plots
+```
+
+## 📁 Generated Files
+
+After running, you'll have in `runs/plots/`:
+
+- **trials.csv** - Complete trial data
+- **success_rate.png** - Success rate over time
+- **runtime_distribution.png** - Runtime histogram
+- **return_code_distribution.png** - Error breakdown
+- **knob_*.png** - Knob value analysis (one per knob)
+- **learning_curve.png** - Best reward over time (if rewards exist)
+- **area_vs_wns.png** - Pareto plot (if metrics exist)
+
+## 🔧 Troubleshooting
+
+**"Permission denied" on run_all.sh:**
+```bash
+chmod +x run_all.sh
+```
+
+**"No module named 'pandas'":**
+- Make sure you're inside Docker container
+- Run: `pip3 install -e .`
+
+**"Database not found":**
+- Check: `ls -la runs/experiment.sqlite`
+- If missing, run experiments first: `edgeeda tune --config configs/gcd_nangate45.yaml --budget 5`
+
+## 💡 Pro Tip
+
+Copy plots to host machine:
+```bash
+# From host (replace CONTAINER_ID)
+docker cp <CONTAINER_ID>:/workspace/edgeeda-agent/runs/plots ./runs/
+```

README_RUN.md

@@ -0,0 +1,76 @@
+# 🎯 READY TO RUN: Tests & Plots
+
+## ✅ Everything is Ready!
+
+All scripts are created and ready to execute. Here's what to do:
+
+## 🐳 In Docker Container (Recommended)
+
+```bash
+# Navigate to project
+cd /workspace/edgeeda-agent
+
+# Run everything at once
+./run_all.sh
+```
+
+That's it! The script will:
+1. ✅ Run all agent tests
+2. ✅ Generate comprehensive plots
+3. ✅ Show summary of results
+
+## 📝 What Gets Generated
+
+### Test Results
+- Console output with ✅/❌ for each test
+- Summary: "X/Y tests passed"
+
+### Plots (in `runs/plots/`)
+- **trials.csv** - All data in CSV format
+- **success_rate.png** - How success rate improves over time
+- **runtime_distribution.png** - Histogram of how long trials take
+- **return_code_distribution.png** - Breakdown of success/failure codes
+- **knob_*.png** - Analysis of each knob's values across trials
+- **learning_curve.png** - Best reward progression (if rewards available)
+- **area_vs_wns.png** - Pareto front visualization (if metrics available)
+
+## 🔍 Quick Check
+
+Before running, verify:
+```bash
+# Check database exists
+ls -la runs/experiment.sqlite
+
+# Check scripts are executable
+ls -la run_all.sh run_tests_simple.py generate_plots.py
+```
+
+## 🚨 If Something Goes Wrong
+
+1. **"No such file or directory"**
+   - Make sure you're in `/workspace/edgeeda-agent`
+   - Check: `pwd`
+
+2. **"Permission denied"**
+   - Fix: `chmod +x run_all.sh`
+
+3. **"Module not found"**
+   - You're not in Docker - enter container first
+   - Or install: `pip3 install -e .`
+
+4. **"Database not found"**
+   - You need to run experiments first
+   - Run: `edgeeda tune --config configs/gcd_nangate45.yaml --budget 5`
+
+## 📤 Getting Results Out
+
+```bash
+# Copy plots to host (from host machine)
+docker cp <CONTAINER_ID>:/workspace/edgeeda-agent/runs/plots ./runs/
+
+# Or use shared volume if configured
+```
+
+## 🎉 That's It!
+
+Just run `./run_all.sh` in Docker and you're done!

configs/gcd_nangate45.yaml

@@ -0,0 +1,68 @@
+experiment:
+  name: "gcd_nangate45_edgebudget"
+  seed: 42
+  db_path: "runs/experiment.sqlite"
+  out_dir: "runs"
+  # ORFS flow directory (OpenROAD-flow-scripts/flow). If not set, uses env ORFS_FLOW_DIR.
+  orfs_flow_dir: null
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  # ORFS "DESIGN_CONFIG" path relative to ORFS flow dir:
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  # multi-fidelity stages (cheap -> expensive)
+  fidelities: ["synth", "place", "route"]
+  # make targets mapping (ORFS commonly supports these targets)
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "surrogate_ucb"   # random | successive_halving | surrogate_ucb
+  budget:
+    # number of total actions (each action is one ORFS make run at some fidelity)
+    total_actions: 24
+    # max actions running full expensive fidelity
+    max_expensive: 6
+
+  # knobs to tune (make VAR=value)
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.35
+      max: 0.75
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 80
+    CELL_PAD_IN_SITES_GLOBAL_PLACEMENT:
+      type: int
+      min: 0
+      max: 4
+
+reward:
+  # scalarization weights (minimize area/power, maximize timing slack -> implement as penalties)
+  weights:
+    wns: 1.0
+    area: 0.25
+    power: 0.10
+  # metric keys to try (repo will try multiple candidates)
+  keys:
+    wns_candidates:
+      - "timing__setup__wns"
+      - "timing__setup__WNS"
+      - "finish__timing__setup__wns"
+    area_candidates:
+      - "design__die__area"
+      - "finish__design__die__area"
+      - "final__design__die__area"
+    power_candidates:
+      - "power__total"
+      - "finish__power__total"
+      - "final__power__total"

configs/gcd_nangate45_sweep.yaml

@@ -0,0 +1,58 @@
+experiment:
+  name: "gcd_nangate45_sweep24_clean"
+  seed: 42
+  db_path: "runs/sweep_clean.sqlite"
+  out_dir: "runs/sweep_clean"
+  orfs_flow_dir: "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow"
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  fidelities: ["synth", "place", "route"]
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "surrogate_ucb"
+  budget:
+    total_actions: 24
+    max_expensive: 6
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.35
+      max: 0.75
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 80
+    CELL_PAD_IN_SITES_GLOBAL_PLACEMENT:
+      type: int
+      min: 0
+      max: 4
+
+reward:
+  weights:
+    wns: 1.0
+    area: 0.25
+    power: 0.10
+  keys:
+    wns_candidates:
+      - "timing__setup__wns"
+      - "timing__setup__WNS"
+      - "finish__timing__setup__wns"
+    area_candidates:
+      - "design__die__area"
+      - "finish__design__die__area"
+      - "final__design__die__area"
+    power_candidates:
+      - "power__total"
+      - "finish__power__total"
+      - "final__power__total"

configs/gcd_nangate45_sweep24_finish.yaml

@@ -0,0 +1,58 @@
+experiment:
+  name: "gcd_nangate45_sweep24_finish"
+  seed: 42
+  db_path: "runs/sweep_finish.sqlite"
+  out_dir: "runs/sweep_finish"
+  orfs_flow_dir: "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow"
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  fidelities: ["synth", "place", "route", "finish"]
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "surrogate_ucb"
+  budget:
+    total_actions: 24
+    max_expensive: 8
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.35
+      max: 0.75
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 80
+    CELL_PAD_IN_SITES_GLOBAL_PLACEMENT:
+      type: int
+      min: 0
+      max: 4
+
+reward:
+  weights:
+    wns: 1.0
+    area: 0.25
+    power: 0.10
+  keys:
+    wns_candidates:
+      - "timing__setup__wns"
+      - "timing__setup__WNS"
+      - "finish__timing__setup__wns"
+    area_candidates:
+      - "design__die__area"
+      - "finish__design__die__area"
+      - "final__design__die__area"
+    power_candidates:
+      - "power__total"
+      - "finish__power__total"
+      - "final__power__total"

configs/gcd_nangate45_sweep24_random.yaml

@@ -0,0 +1,58 @@
+experiment:
+  name: "gcd_nangate45_sweep24_random"
+  seed: 42
+  db_path: "runs/sweep_random.sqlite"
+  out_dir: "runs/sweep_random"
+  orfs_flow_dir: "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow"
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  fidelities: ["synth", "place", "route"]
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "random"
+  budget:
+    total_actions: 24
+    max_expensive: 6
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.35
+      max: 0.75
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 80
+    CELL_PAD_IN_SITES_GLOBAL_PLACEMENT:
+      type: int
+      min: 0
+      max: 4
+
+reward:
+  weights:
+    wns: 1.0
+    area: 0.25
+    power: 0.10
+  keys:
+    wns_candidates:
+      - "timing__setup__wns"
+      - "timing__setup__WNS"
+      - "finish__timing__setup__wns"
+    area_candidates:
+      - "design__die__area"
+      - "finish__design__die__area"
+      - "final__design__die__area"
+    power_candidates:
+      - "power__total"
+      - "finish__power__total"
+      - "final__power__total"

configs/gcd_nangate45_sweep24_sh.yaml

@@ -0,0 +1,58 @@
+experiment:
+  name: "gcd_nangate45_sweep24_sh"
+  seed: 42
+  db_path: "runs/sweep_sh.sqlite"
+  out_dir: "runs/sweep_sh"
+  orfs_flow_dir: "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow"
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  fidelities: ["synth", "place", "route"]
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "successive_halving"
+  budget:
+    total_actions: 24
+    max_expensive: 6
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.35
+      max: 0.75
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 80
+    CELL_PAD_IN_SITES_GLOBAL_PLACEMENT:
+      type: int
+      min: 0
+      max: 4
+
+reward:
+  weights:
+    wns: 1.0
+    area: 0.25
+    power: 0.10
+  keys:
+    wns_candidates:
+      - "timing__setup__wns"
+      - "timing__setup__WNS"
+      - "finish__timing__setup__wns"
+    area_candidates:
+      - "design__die__area"
+      - "finish__design__die__area"
+      - "final__design__die__area"
+    power_candidates:
+      - "power__total"
+      - "finish__power__total"
+      - "final__power__total"

configs/ibex_sky130hd.yaml

@@ -0,0 +1,45 @@
+experiment:
+  name: "gcd_nangate45_edgebudget"
+  seed: 7
+  db_path: "runs/experiment.sqlite"
+  out_dir: "runs"
+  orfs_flow_dir: null
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  fidelities: ["synth", "place", "route"]
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "successive_halving"
+  budget:
+    total_actions: 18
+    max_expensive: 4
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.45
+      max: 0.80
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 75
+
+reward:
+  weights:
+    wns: 1.0
+    area: 0.2
+    power: 0.1
+  keys:
+    wns_candidates: ["timing__setup__wns", "finish__timing__setup__wns"]
+    area_candidates: ["design__die__area", "finish__design__die__area"]
+    power_candidates: ["power__total", "finish__power__total"]

configs/quick_gcd.yaml

@@ -0,0 +1,54 @@
+experiment:
+  name: "quick_gcd_test"
+  seed: 42
+  db_path: "runs/quick_gcd.sqlite"
+  out_dir: "runs/quick_gcd"
+  orfs_flow_dir: "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow"
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  fidelities: ["synth"]
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "random"
+  budget:
+    total_actions: 4
+    max_expensive: 1
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.35
+      max: 0.75
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 80
+
+reward:
+  weights:
+    wns: 1.0
+    area: 0.25
+    power: 0.10
+  keys:
+    wns_candidates:
+      - "timing__setup__wns"
+      - "timing__setup__WNS"
+      - "finish__timing__setup__wns"
+    area_candidates:
+      - "design__die__area"
+      - "finish__design__die__area"
+      - "final__design__die__area"
+    power_candidates:
+      - "power__total"
+      - "finish__power__total"
+      - "final__power__total"

configs/quick_ibex.yaml

@@ -0,0 +1,45 @@
+experiment:
+  name: "quick_ibex_test"
+  seed: 7
+  db_path: "runs/quick_ibex.sqlite"
+  out_dir: "runs/quick_ibex"
+  orfs_flow_dir: "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow"
+
+design:
+  platform: "nangate45"
+  design: "gcd"
+  design_config: "./designs/nangate45/gcd/config.mk"
+
+flow:
+  fidelities: ["synth"]
+  targets:
+    synth: "synth"
+    place: "place"
+    route: "route"
+    finish: "finish"
+    metadata: "metadata"
+
+tuning:
+  agent: "successive_halving"
+  budget:
+    total_actions: 4
+    max_expensive: 1
+  knobs:
+    PLACE_DENSITY:
+      type: float
+      min: 0.45
+      max: 0.80
+    CORE_UTILIZATION:
+      type: int
+      min: 35
+      max: 75
+
+reward:
+  weights:
+    wns: 1.0
+    area: 0.2
+    power: 0.1
+  keys:
+    wns_candidates: ["timing__setup__wns", "finish__timing__setup__wns"]
+    area_candidates: ["design__die__area", "finish__design__die__area"]
+    power_candidates: ["power__total", "finish__power__total"]

docker/Dockerfile

@@ -0,0 +1,16 @@
+# Uses ORFS official image, then installs this package.
+FROM openroad/orfs:latest
+
+# Ensure python tooling exists
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3-pip python3-venv git \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace/edgeeda-agent
+COPY . /workspace/edgeeda-agent
+
+RUN pip3 install --upgrade pip \
+ && pip3 install -e .
+
+# Default: start a shell so you can run edgeeda commands easily.
+CMD ["/bin/bash"]

docker/run_orfs_edgeeda.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Runs the container and mounts this repo so outputs persist.
+docker run --rm -it \
+  -v "$(pwd)":/workspace/edgeeda-agent \
+  -w /workspace/edgeeda-agent \
+  edgeeda-agent bash

pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "edgeeda"
+version = "0.1.0"
+description = "Agentic multi-fidelity PPA tuning for OpenROAD-flow-scripts (ORFS)"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+  "pyyaml>=6.0",
+  "numpy>=1.23",
+  "pandas>=2.0",
+  "tqdm>=4.66",
+  "scikit-learn>=1.3",
+]
+
+[project.scripts]
+edgeeda = "edgeeda.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

requirements.txt

@@ -0,0 +1,7 @@
+pyyaml>=6.0
+numpy>=1.23
+pandas>=2.0
+tqdm>=4.66
+scikit-learn>=1.3
+pytest>=7.0
+huggingface_hub>=0.20

scripts/generate_pareto_plot.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import pandas as pd
+import sqlite3
+
+
+WNS_KEYS = [
+    "timing__setup__wns",
+    "timing__setup__WNS",
+    "finish__timing__setup__wns",
+    "timing__setup__ws",
+    "finish__timing__setup__ws",
+    "route__timing__setup__ws",
+    "cts__timing__setup__ws",
+    "detailedplace__timing__setup__ws",
+    "floorplan__timing__setup__ws",
+    "globalplace__timing__setup__ws",
+    "globalroute__timing__setup__ws",
+    "placeopt__timing__setup__ws",
+]
+
+AREA_KEYS = [
+    "finish__design__die__area",
+    "globalroute__design__die__area",
+    "placeopt__design__die__area",
+    "detailedplace__design__die__area",
+    "floorplan__design__die__area",
+    "design__die__area",
+]
+
+
+def pick_first(metrics: dict, keys: list[str]) -> float | None:
+    for k in keys:
+        if k in metrics:
+            try:
+                return float(metrics[k])
+            except Exception:
+                return None
+    lower = {kk.lower(): kk for kk in metrics.keys()}
+    for k in keys:
+        kk = lower.get(k.lower())
+        if kk:
+            try:
+                return float(metrics[kk])
+            except Exception:
+                return None
+    return None
+
+
+def load_metrics(mj: str | None) -> dict | None:
+    if not mj:
+        return None
+    try:
+        return json.loads(mj)
+    except Exception:
+        return None
+
+
+def main() -> None:
+    import argparse
+
+    p = argparse.ArgumentParser(description="Generate Pareto scatter (area vs WNS)")
+    p.add_argument("--db", default="runs/sweep_finish.sqlite", help="SQLite database path")
+    p.add_argument("--out", default="runs/sweep_finish/plots/pareto_area_vs_wns", help="Output path without extension")
+    args = p.parse_args()
+
+    con = sqlite3.connect(args.db)
+    df = pd.read_sql_query("SELECT * FROM trials", con)
+    con.close()
+
+    rows = []
+    for _, row in df.iterrows():
+        metrics = load_metrics(row.get("metrics_json"))
+        if not metrics:
+            continue
+        wns = pick_first(metrics, WNS_KEYS)
+        area = pick_first(metrics, AREA_KEYS)
+        if wns is None or area is None:
+            continue
+        rows.append({"wns": wns, "area": area, "fidelity": row.get("fidelity", "unknown")})
+
+    if not rows:
+        print("No points with both WNS and area found.")
+        return
+
+    plot_df = pd.DataFrame(rows)
+    colors = {
+        "synth": "#999999",
+        "place": "#4B8BBE",
+        "route": "#306998",
+        "finish": "#E07B39",
+        "unknown": "#666666",
+    }
+    markers = {
+        "synth": "o",
+        "place": "s",
+        "route": "^",
+        "finish": "D",
+        "unknown": "o",
+    }
+
+    fig, ax = plt.subplots(figsize=(6.4, 4.6))
+    for fid, group in plot_df.groupby("fidelity"):
+        ax.scatter(
+            group["area"],
+            group["wns"],
+            label=fid,
+            color=colors.get(fid, "#666666"),
+            marker=markers.get(fid, "o"),
+            alpha=0.75,
+            edgecolors="none",
+        )
+
+    ax.axhline(0.0, color="#333333", linewidth=0.8, linestyle="--")
+    ax.set_xlabel("Die area (um^2)")
+    ax.set_ylabel("WNS (ns)")
+    ax.set_title("Area vs WNS (Pareto scatter)")
+    ax.legend(frameon=False, fontsize=8, loc="best")
+    fig.tight_layout()
+
+    out_base = Path(args.out)
+    out_base.parent.mkdir(parents=True, exist_ok=True)
+    fig.savefig(out_base.with_suffix(".png"), dpi=300)
+    fig.savefig(out_base.with_suffix(".pdf"))
+    plt.close(fig)
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_quick_plots.py

@@ -0,0 +1,76 @@
+from edgeeda.viz import export_trials
+import pandas as pd, matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt, os, glob, json
+
+out='runs/plots_quick'
+os.makedirs(out, exist_ok=True)
+
+# Load trials
+df = export_trials('runs/experiment.sqlite')
+print('rows:', len(df))
+print('columns:', list(df.columns))
+
+# Basic runtime histogram
+runtimes = pd.to_numeric(df['runtime_sec'], errors='coerce').dropna()
+if not runtimes.empty:
+    plt.figure(); runtimes.hist(bins=10)
+    plt.xlabel('runtime_sec'); plt.tight_layout(); plt.savefig(os.path.join(out,'runtime_hist.png'), dpi=200); plt.close()
+    print('wrote runtime_hist.png')
+else:
+    print('no runtime data to plot')
+
+# return_code counts
+plt.figure(); df['return_code'].value_counts().plot(kind='bar')
+plt.xlabel('return_code'); plt.tight_layout(); plt.savefig(os.path.join(out,'return_code_counts.png'), dpi=200); plt.close()
+print('wrote return_code_counts.png')
+
+# metadata availability
+has_meta = df['metadata_path'].fillna('').apply(lambda x: bool(str(x).strip()))
+plt.figure(); has_meta.value_counts().plot(kind='bar'); plt.xticks([0,1],['no metadata','has metadata']); plt.tight_layout(); plt.savefig(os.path.join(out,'metadata_counts.png'), dpi=200); plt.close()
+print('wrote metadata_counts.png')
+
+# learning curve from reward, if present
+if 'reward' in df.columns:
+    r = pd.to_numeric(df['reward'], errors='coerce').dropna()
+    if not r.empty:
+        df2 = df.copy()
+        df2['reward'] = pd.to_numeric(df2['reward'], errors='coerce')
+        df2 = df2.dropna(subset=['reward']).sort_values('id')
+        best = df2['reward'].cummax()
+        plt.figure(); plt.plot(df2['id'].values, best.values)
+        plt.xlabel('trial id'); plt.ylabel('best reward so far'); plt.tight_layout(); plt.savefig(os.path.join(out,'learning_curve.png'), dpi=200); plt.close()
+        print('wrote learning_curve.png')
+    else:
+        print('no rewards to plot')
+else:
+    print('reward column missing')
+
+# area vs wns if metrics present
+areas=[]; wnss=[]
+for _, r in df.iterrows():
+    mj = r.get('metrics') or r.get('metrics_json') or r.get('metrics_json')
+    if not mj:
+        continue
+    if isinstance(mj, str):
+        try:
+            m = json.loads(mj)
+        except Exception:
+            continue
+    else:
+        m = mj
+    a = m.get('design__die__area') or m.get('finish__design__die__area')
+    w = m.get('timing__setup__wns') or m.get('finish__timing__setup__wns')
+    if a is None or w is None:
+        continue
+    try:
+        areas.append(float(a)); wnss.append(float(w))
+    except Exception:
+        pass
+if areas:
+    plt.figure(); plt.scatter(areas, wnss); plt.xlabel('die area'); plt.ylabel('WNS'); plt.tight_layout(); plt.savefig(os.path.join(out,'area_vs_wns.png'), dpi=200); plt.close()
+    print('wrote area_vs_wns.png')
+else:
+    print('no area/wns metrics to plot')
+
+print('files:', glob.glob(out+'/*'))

scripts/publish_hf.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from huggingface_hub import HfApi, upload_file, upload_folder
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="Publish EdgeEDA agent to Hugging Face Hub")
+    p.add_argument("--repo-id", required=True, help="Repo id, e.g. org/name or user/name")
+    p.add_argument("--repo-type", default="model", choices=["model", "dataset", "space"])
+    p.add_argument("--private", action="store_true", help="Create a private repo")
+    p.add_argument("--token", default=None, help="HF token (or set HF_TOKEN)")
+    p.add_argument("--commit-message", default="Add EdgeEDA agent", help="Commit message")
+    args = p.parse_args()
+
+    token = args.token or os.environ.get("HF_TOKEN")
+    if not token:
+        raise SystemExit("Missing HF token. Provide --token or set HF_TOKEN.")
+
+    api = HfApi(token=token)
+    api.create_repo(
+        repo_id=args.repo_id,
+        repo_type=args.repo_type,
+        private=args.private,
+        exist_ok=True,
+    )
+
+    root = Path(__file__).resolve().parents[1]
+    readme_hf = root / "README_HF.md"
+    if not readme_hf.exists():
+        raise SystemExit(f"Missing {readme_hf}")
+
+    upload_file(
+        path_or_fileobj=str(readme_hf),
+        path_in_repo="README.md",
+        repo_id=args.repo_id,
+        repo_type=args.repo_type,
+        token=token,
+        commit_message=args.commit_message,
+    )
+
+    allow_patterns = [
+        "src/**",
+        "configs/**",
+        "scripts/**",
+        "docker/**",
+        "LICENSE",
+        "pyproject.toml",
+        "setup.py",
+        "requirements.txt",
+        "README_RUN.md",
+        "QUICK_START.md",
+        "EXECUTE_IN_DOCKER.md",
+        "CHANGELOG_FIXES.md",
+    ]
+    ignore_patterns = [
+        "OpenROAD-flow-scripts/**",
+        "runs/**",
+        "IEEE_EdgeEDA_Agent_ISVLSI/**",
+        "build/**",
+        "**/__pycache__/**",
+        "**/*.pyc",
+        "**/*.sqlite",
+        "**/*.png",
+        "**/*.pdf",
+        "**/*.log",
+        "README.md",
+        "README_HF.md",
+        "UNKNOWN.egg-info/**",
+        "src/edgeeda.egg-info/**",
+        "*.egg-info/**",
+    ]
+
+    upload_folder(
+        folder_path=str(root),
+        repo_id=args.repo_id,
+        repo_type=args.repo_type,
+        token=token,
+        commit_message=args.commit_message,
+        allow_patterns=allow_patterns,
+        ignore_patterns=ignore_patterns,
+    )
+
+
+if __name__ == "__main__":
+    main()

scripts/run_experiment.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CFG="${1:-configs/gcd_nangate45.yaml}"
+BUDGET="${2:-24}"
+
+edgeeda tune --config "$CFG" --budget "$BUDGET"
+edgeeda analyze --db runs/experiment.sqlite --out runs/plots

scripts/setup_orfs.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Optional helper if you want a local ORFS clone.
+# Usage:
+#   bash scripts/setup_orfs.sh /path/to/install
+DEST="${1:-$HOME/orfs}"
+if [ -d "$DEST/OpenROAD-flow-scripts" ]; then
+  echo "[setup] ORFS already exists at $DEST/OpenROAD-flow-scripts"
+  exit 0
+fi
+
+mkdir -p "$DEST"
+cd "$DEST"
+git clone https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts.git
+echo "[setup] ORFS cloned. Set:"
+echo "  export ORFS_FLOW_DIR=$DEST/OpenROAD-flow-scripts/flow"

scripts/summarize_sh001_results.py

@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""Summarize sh001_29b345d42a results and generate paper-ready plots."""
+from __future__ import annotations
+
+import csv
+import math
+import re
+from collections import Counter
+from pathlib import Path
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+RESULT_DIR = Path(
+    "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow/results/nangate45/gcd/sh001_29b345d42a"
+)
+REPORT_DIR = Path(
+    "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow/reports/nangate45/gcd/sh001_29b345d42a"
+)
+LOG_DIR = Path(
+    "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/OpenROAD-flow-scripts/flow/logs/nangate45/gcd/sh001_29b345d42a"
+)
+DEF_PATH = RESULT_DIR / "6_final.def"
+V_PATH = RESULT_DIR / "6_final.v"
+MEM_PATH = RESULT_DIR / "mem.json"
+FINISH_RPT_PATH = REPORT_DIR / "6_finish.rpt"
+REPORT_LOG_PATH = LOG_DIR / "6_report.log"
+OUT_FIG_DIR = Path(
+    "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/IEEE_EdgeEDA_Agent_ISVLSI/figures"
+)
+OUT_CSV = Path(
+    "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/runs/sh001_29b345d42a_summary.csv"
+)
+OUT_TEX = Path(
+    "/Users/thalia/Desktop/EdgePPAgent/edgeeda-agent/IEEE_EdgeEDA_Agent_ISVLSI/gcd_sh001_results_table.tex"
+)
+
+
+def parse_def_metrics(def_text: str) -> dict:
+    metrics = {}
+    units_match = re.search(r"^UNITS\s+DISTANCE\s+MICRONS\s+(\d+)\s*;", def_text, re.M)
+    die_match = re.search(r"^DIEAREA\s*\(\s*(\d+)\s+(\d+)\s*\)\s*\(\s*(\d+)\s+(\d+)\s*\)\s*;", def_text, re.M)
+    comp_match = re.search(r"^COMPONENTS\s+(\d+)\s*;", def_text, re.M)
+    pin_match = re.search(r"^PINS\s+(\d+)\s*;", def_text, re.M)
+    net_match = re.search(r"^NETS\s+(\d+)\s*;", def_text, re.M)
+    row_count = len(re.findall(r"^ROW\s+", def_text, re.M))
+
+    if units_match:
+        metrics["units_per_micron"] = int(units_match.group(1))
+    if die_match:
+        x0, y0, x1, y1 = map(int, die_match.groups())
+        metrics["die_x0"] = x0
+        metrics["die_y0"] = y0
+        metrics["die_x1"] = x1
+        metrics["die_y1"] = y1
+    if comp_match:
+        metrics["components"] = int(comp_match.group(1))
+    if pin_match:
+        metrics["pins"] = int(pin_match.group(1))
+    if net_match:
+        metrics["nets"] = int(net_match.group(1))
+    metrics["rows"] = row_count
+
+    if "units_per_micron" in metrics and "die_x1" in metrics:
+        units = metrics["units_per_micron"]
+        width = (metrics["die_x1"] - metrics["die_x0"]) / units
+        height = (metrics["die_y1"] - metrics["die_y0"]) / units
+        metrics["die_width_um"] = width
+        metrics["die_height_um"] = height
+        metrics["die_area_um2"] = width * height
+
+    return metrics
+
+
+def parse_def_cell_counts(def_text: str) -> Counter:
+    comp_match = re.search(r"^COMPONENTS\s+\d+\s*;\n(.*?)\nEND COMPONENTS", def_text, re.S | re.M)
+    if not comp_match:
+        return Counter()
+    section = comp_match.group(1)
+    counts = Counter()
+    for line in section.splitlines():
+        line = line.strip()
+        if not line.startswith("-"):
+            continue
+        parts = line.split()
+        if len(parts) >= 3:
+            counts[parts[2]] += 1
+    return counts
+
+
+def parse_netlist_cell_counts(v_text: str) -> Counter:
+    pattern = re.compile(r"^\s*([A-Za-z_][\w$]*)\s+([A-Za-z_][\w$]*)\s*\(", re.M)
+    counts = Counter()
+    for cell, _inst in pattern.findall(v_text):
+        if cell in {"module", "endmodule", "input", "output", "wire", "reg", "assign", "always"}:
+            continue
+        counts[cell] += 1
+    return counts
+
+
+def parse_finish_rpt(text: str) -> dict:
+    metrics = {}
+    if not text:
+        return metrics
+    tns_match = re.search(r"tns max\s+([+-]?\d+(?:\.\d+)?)", text)
+    wns_match = re.search(r"wns max\s+([+-]?\d+(?:\.\d+)?)", text)
+    worst_match = re.search(r"worst slack max\s+([+-]?\d+(?:\.\d+)?)", text)
+    period_match = re.search(r"period_min\s*=\s*([0-9.]+)\s+fmax\s*=\s*([0-9.]+)", text)
+
+    if tns_match:
+        metrics["tns_ns"] = float(tns_match.group(1))
+    if wns_match:
+        metrics["wns_ns"] = float(wns_match.group(1))
+    if worst_match:
+        metrics["worst_slack_ns"] = float(worst_match.group(1))
+    if period_match:
+        metrics["clock_period_ns"] = float(period_match.group(1))
+        metrics["clock_fmax_mhz"] = float(period_match.group(2))
+    return metrics
+
+
+def parse_report_log(text: str) -> dict:
+    metrics = {}
+    if not text:
+        return metrics
+    design_match = re.search(r"Design area\s+([0-9.]+)\s+um\^2\s+([0-9.]+)% utilization", text)
+    power_match = re.search(r"Total power\s*:\s*([0-9.eE+-]+)\s*W", text)
+    ir_avg_match = re.search(r"Average IR drop\s*:\s*([0-9.eE+-]+)\s*V", text)
+    ir_worst_match = re.search(r"Worstcase IR drop:\s*([0-9.eE+-]+)\s*V", text)
+    ir_pct_match = re.search(r"Percentage drop\s*:\s*([0-9.eE+-]+)\s*%", text)
+    total_cells_match = re.search(r"^\s*Total\s+(\d+)\s+([0-9.]+)\s*$", text, re.M)
+
+    if design_match:
+        metrics["design_area_um2"] = float(design_match.group(1))
+        metrics["design_utilization_pct"] = float(design_match.group(2))
+    if power_match:
+        metrics["total_power_w"] = float(power_match.group(1))
+    if ir_avg_match:
+        metrics["ir_drop_avg_v"] = float(ir_avg_match.group(1))
+    if ir_worst_match:
+        metrics["ir_drop_worst_v"] = float(ir_worst_match.group(1))
+    if ir_pct_match:
+        metrics["ir_drop_pct"] = float(ir_pct_match.group(1))
+    if total_cells_match:
+        metrics["cell_total_count"] = int(total_cells_match.group(1))
+        metrics["cell_total_area_um2"] = float(total_cells_match.group(2))
+    return metrics
+
+
+def classify_cells(counts: Counter) -> dict:
+    categories = {
+        "filler": 0,
+        "tap": 0,
+        "sequential": 0,
+        "combinational": 0,
+        "other": 0,
+    }
+    for cell, count in counts.items():
+        ucell = cell.upper()
+        if "FILL" in ucell:
+            categories["filler"] += count
+        elif "TAP" in ucell:
+            categories["tap"] += count
+        elif "DFF" in ucell or "LATCH" in ucell:
+            categories["sequential"] += count
+        elif re.match(r"[A-Z]+\d+_X\d+", ucell) or any(k in ucell for k in ["NAND", "NOR", "AOI", "OAI", "INV", "BUF", "XOR", "XNOR"]):
+            categories["combinational"] += count
+        else:
+            categories["other"] += count
+    return categories
+
+
+def write_summary_csv(metrics: dict, def_counts: Counter, v_counts: Counter, categories: dict) -> None:
+    OUT_CSV.parent.mkdir(parents=True, exist_ok=True)
+    with OUT_CSV.open("w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["metric", "value"])
+        for key in [
+            "components",
+            "pins",
+            "nets",
+            "rows",
+            "units_per_micron",
+            "die_width_um",
+            "die_height_um",
+            "die_area_um2",
+            "tns_ns",
+            "wns_ns",
+            "worst_slack_ns",
+            "clock_period_ns",
+            "clock_fmax_mhz",
+            "design_area_um2",
+            "design_utilization_pct",
+            "total_power_w",
+            "ir_drop_avg_v",
+            "ir_drop_worst_v",
+            "ir_drop_pct",
+            "cell_total_count",
+            "cell_total_area_um2",
+        ]:
+            if key in metrics:
+                writer.writerow([key, metrics[key]])
+        writer.writerow(["def_instance_total", sum(def_counts.values())])
+        writer.writerow(["netlist_instance_total", sum(v_counts.values())])
+        for k, v in categories.items():
+            writer.writerow([f"category_{k}", v])
+
+
+def write_latex_table(metrics: dict, def_counts: Counter, categories: dict) -> None:
+    OUT_TEX.parent.mkdir(parents=True, exist_ok=True)
+    total = sum(def_counts.values())
+    def pct(x):
+        return 0.0 if total == 0 else (100.0 * x / total)
+    def fmt_num(value, fmt: str) -> str:
+        try:
+            return format(float(value), fmt)
+        except (TypeError, ValueError):
+            return "n/a"
+
+    die_width = fmt_num(metrics.get("die_width_um"), ".3f")
+    die_height = fmt_num(metrics.get("die_height_um"), ".3f")
+    die_area = fmt_num(metrics.get("die_area_um2"), ".2f")
+    wns = fmt_num(metrics.get("wns_ns"), ".3f")
+    tns = fmt_num(metrics.get("tns_ns"), ".3f")
+    worst_slack = fmt_num(metrics.get("worst_slack_ns"), ".3f")
+    period = fmt_num(metrics.get("clock_period_ns"), ".3f")
+    fmax = fmt_num(metrics.get("clock_fmax_mhz"), ".2f")
+    design_area = fmt_num(metrics.get("design_area_um2"), ".2f")
+    util = fmt_num(metrics.get("design_utilization_pct"), ".1f")
+    power_w = metrics.get("total_power_w")
+    power_mw = fmt_num(power_w * 1e3 if power_w is not None else None, ".3f")
+    ir_avg = fmt_num(metrics.get("ir_drop_avg_v"), ".4f")
+    ir_worst = fmt_num(metrics.get("ir_drop_worst_v"), ".4f")
+    ir_pct = fmt_num(metrics.get("ir_drop_pct"), ".2f")
+
+    lines = [
+        r"\\begin{table}[t]",
+        r"\\caption{Post-route summary for \texttt{nangate45/gcd/sh001\_29b345d42a}.}",
+        r"\\label{tab:postroute_sh001}",
+        r"\\centering",
+        r"\\small",
+        r"\\begin{tabular}{@{}ll@{}}",
+        r"\\toprule",
+        r"Metric & Value \\",
+        r"\\midrule",
+        f"Components & {metrics.get('components', 'n/a')} \\\\",
+        f"Pins / nets & {metrics.get('pins', 'n/a')} / {metrics.get('nets', 'n/a')} \\\\",
+        f"Rows & {metrics.get('rows', 'n/a')} \\\\",
+        rf"Die size ($\mu m$) & {die_width} $\times$ {die_height} \\",
+        rf"Die area ($\mu m^2$) & {die_area} \\",
+        f"WNS / TNS / worst (ns) & {wns} / {tns} / {worst_slack} \\\\",
+        f"Clock period / fmax & {period} ns / {fmax} MHz \\\\",
+        rf"Design area / util & {design_area} $\mu m^2$ / {util}\% \\",
+        f"Total power & {power_mw} mW \\\\",
+        rf"IR drop avg / worst / \% & {ir_avg} / {ir_worst} / {ir_pct} \\",
+        f"Filler / tap cells & {categories['filler']} ({pct(categories['filler']):.1f}\\%) / {categories['tap']} ({pct(categories['tap']):.1f}\\%) \\\\",
+        f"Sequential / combinational & {categories['sequential']} ({pct(categories['sequential']):.1f}\\%) / {categories['combinational']} ({pct(categories['combinational']):.1f}\\%) \\\\",
+        r"\\bottomrule",
+        r"\\end{tabular}",
+        r"\\end{table}",
+        "",
+    ]
+    OUT_TEX.write_text("\n".join(lines))
+
+
+def plot_top_cell_types(def_counts: Counter) -> None:
+    OUT_FIG_DIR.mkdir(parents=True, exist_ok=True)
+    top = def_counts.most_common(10)
+    labels = [k for k, _ in top]
+    values = [v for _k, v in top]
+    fig, ax = plt.subplots(figsize=(7.2, 4.2))
+    bars = ax.bar(labels, values, color="#4B8BBE")
+    ax.set_ylabel("Instance count")
+    ax.set_title("Top cell types (post-route DEF)")
+    ax.tick_params(axis="x", rotation=45, labelsize=8)
+    for bar, value in zip(bars, values):
+        ax.text(bar.get_x() + bar.get_width() / 2, bar.get_height(), str(value), ha="center", va="bottom", fontsize=7)
+    fig.tight_layout()
+    for ext in ("png", "pdf"):
+        fig.savefig(OUT_FIG_DIR / f"gcd_sh001_celltype_top10.{ext}", dpi=300)
+    plt.close(fig)
+
+
+def plot_category_pie(categories: dict) -> None:
+    OUT_FIG_DIR.mkdir(parents=True, exist_ok=True)
+    labels = ["Combinational", "Sequential", "Filler", "Tap", "Other"]
+    values = [
+        categories["combinational"],
+        categories["sequential"],
+        categories["filler"],
+        categories["tap"],
+        categories["other"],
+    ]
+    fig, ax = plt.subplots(figsize=(5.0, 4.2))
+    ax.pie(values, labels=labels, autopct=lambda p: f"{p:.1f}%" if p > 0 else "")
+    ax.set_title("Cell category mix (post-route DEF)")
+    fig.tight_layout()
+    for ext in ("png", "pdf"):
+        fig.savefig(OUT_FIG_DIR / f"gcd_sh001_celltype_categories.{ext}", dpi=300)
+    plt.close(fig)
+
+
+def main() -> None:
+    def_text = DEF_PATH.read_text()
+    v_text = V_PATH.read_text()
+
+    metrics = parse_def_metrics(def_text)
+    finish_metrics = parse_finish_rpt(FINISH_RPT_PATH.read_text() if FINISH_RPT_PATH.exists() else "")
+    report_metrics = parse_report_log(REPORT_LOG_PATH.read_text() if REPORT_LOG_PATH.exists() else "")
+    metrics.update(finish_metrics)
+    metrics.update(report_metrics)
+    def_counts = parse_def_cell_counts(def_text)
+    v_counts = parse_netlist_cell_counts(v_text)
+    categories = classify_cells(def_counts)
+
+    write_summary_csv(metrics, def_counts, v_counts, categories)
+    write_latex_table(metrics, def_counts, categories)
+    plot_top_cell_types(def_counts)
+    plot_category_pie(categories)
+
+
+if __name__ == "__main__":
+    main()

setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

src/edgeeda/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["cli", "config", "reward", "store", "viz"]
+__version__ = "0.1.0"

src/edgeeda/agents/__init__.py

@@ -0,0 +1,11 @@
+from edgeeda.agents.base import Agent
+from edgeeda.agents.random_search import RandomSearchAgent
+from edgeeda.agents.successive_halving import SuccessiveHalvingAgent
+from edgeeda.agents.surrogate_ucb import SurrogateUCBAgent
+
+__all__ = [
+    "Agent",
+    "RandomSearchAgent",
+    "SuccessiveHalvingAgent",
+    "SurrogateUCBAgent",
+]

src/edgeeda/agents/base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+
+@dataclass
+class Action:
+    variant: str
+    fidelity: str
+    knobs: Dict[str, Any]
+
+
+class Agent:
+    def propose(self) -> Action:
+        raise NotImplementedError
+
+    def observe(
+        self,
+        action: Action,
+        ok: bool,
+        reward: Optional[float],
+        metrics_flat: Optional[Dict[str, Any]],
+    ) -> None:
+        raise NotImplementedError

src/edgeeda/agents/random_search.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import itertools
+import random
+from typing import Any, Dict, Optional
+
+from edgeeda.agents.base import Action, Agent
+from edgeeda.config import Config
+from edgeeda.utils import sanitize_variant_prefix, stable_hash
+
+
+class RandomSearchAgent(Agent):
+    def __init__(self, cfg: Config):
+        self.cfg = cfg
+        self.counter = 0
+        self.variant_prefix = sanitize_variant_prefix(cfg.experiment.name)
+
+    def _sample_knobs(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {}
+        for name, spec in self.cfg.tuning.knobs.items():
+            if spec.type == "int":
+                out[name] = random.randint(int(spec.min), int(spec.max))
+            else:
+                out[name] = float(spec.min) + random.random() * (float(spec.max) - float(spec.min))
+                out[name] = round(out[name], 3)
+        return out
+
+    def propose(self) -> Action:
+        self.counter += 1
+        knobs = self._sample_knobs()
+        variant = f"{self.variant_prefix}_t{self.counter:05d}_{stable_hash(str(knobs))}"
+        fidelity = self.cfg.flow.fidelities[0]  # always start cheap
+        return Action(variant=variant, fidelity=fidelity, knobs=knobs)
+
+    def observe(self, action: Action, ok: bool, reward: Optional[float], metrics_flat: Optional[Dict[str, Any]]) -> None:
+        # Random agent doesn't adapt.
+        return

src/edgeeda/agents/successive_halving.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from edgeeda.agents.base import Action, Agent
+from edgeeda.config import Config
+from edgeeda.utils import sanitize_variant_prefix, stable_hash
+
+
+@dataclass
+class Candidate:
+    variant: str
+    knobs: Dict[str, Any]
+    stage_idx: int
+    last_reward: Optional[float]
+
+
+class SuccessiveHalvingAgent(Agent):
+    """
+    Simple multi-fidelity baseline:
+      - sample a pool
+      - evaluate at fidelity0
+      - keep top fraction
+      - promote to next fidelity
+    """
+
+    def __init__(self, cfg: Config, pool_size: int = 12, eta: float = 0.5):
+        self.cfg = cfg
+        self.pool_size = pool_size
+        self.eta = eta
+        self.stage_names = cfg.flow.fidelities
+        self.variant_prefix = sanitize_variant_prefix(cfg.experiment.name)
+        self.pool: List[Candidate] = []
+        self._init_pool()
+        self._queue: List[Action] = []
+        self._rebuild_queue()
+
+    def _sample_knobs(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {}
+        for name, spec in self.cfg.tuning.knobs.items():
+            if spec.type == "int":
+                out[name] = random.randint(int(spec.min), int(spec.max))
+            else:
+                out[name] = float(spec.min) + random.random() * (float(spec.max) - float(spec.min))
+                out[name] = round(out[name], 3)
+        return out
+
+    def _init_pool(self):
+        self.pool = []
+        for i in range(self.pool_size):
+            knobs = self._sample_knobs()
+            variant = f"{self.variant_prefix}_sh{i:03d}_{stable_hash(str(knobs))}"
+            self.pool.append(Candidate(variant=variant, knobs=knobs, stage_idx=0, last_reward=None))
+
+    def _rebuild_queue(self):
+        self._queue = []
+        for c in self.pool:
+            self._queue.append(Action(variant=c.variant, fidelity=self.stage_names[c.stage_idx], knobs=c.knobs))
+
+    def propose(self) -> Action:
+        if not self._queue:
+            # promote
+            self._promote()
+            self._rebuild_queue()
+        return self._queue.pop(0)
+
+    def _promote(self):
+        # group by stage idx
+        max_stage = max(c.stage_idx for c in self.pool)
+        if max_stage >= len(self.stage_names) - 1:
+            # already at final stage; resample fresh pool to continue
+            self._init_pool()
+            return
+
+        # keep top fraction among candidates at current max stage
+        current = [c for c in self.pool if c.stage_idx == max_stage]
+        # if rewards missing, treat as very bad
+        current.sort(key=lambda c: float("-inf") if c.last_reward is None else c.last_reward, reverse=True)
+        k = max(1, int(len(current) * self.eta))
+        survivors = current[:k]
+
+        # promote survivors to next stage; others replaced with new randoms at stage 0
+        promoted = []
+        for c in survivors:
+            promoted.append(Candidate(c.variant, c.knobs, c.stage_idx + 1, None))
+
+        fresh_needed = self.pool_size - len(promoted)
+        fresh = []
+        for i in range(fresh_needed):
+            knobs = self._sample_knobs()
+            variant = f"{self.variant_prefix}_shR{i:03d}_{stable_hash(str(knobs))}"
+            fresh.append(Candidate(variant=variant, knobs=knobs, stage_idx=0, last_reward=None))
+
+        self.pool = promoted + fresh
+
+    def observe(self, action: Action, ok: bool, reward: Optional[float], metrics_flat: Optional[Dict[str, Any]]) -> None:
+        for c in self.pool:
+            if c.variant == action.variant and self.stage_names[c.stage_idx] == action.fidelity:
+                c.last_reward = reward if ok else None
+                return

src/edgeeda/agents/surrogate_ucb.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+from sklearn.ensemble import ExtraTreesRegressor
+
+from edgeeda.agents.base import Action, Agent
+from edgeeda.config import Config
+from edgeeda.utils import sanitize_variant_prefix, stable_hash
+
+
+@dataclass
+class Obs:
+    x: np.ndarray
+    y: float
+    fidelity: str
+    variant: str
+
+
+class SurrogateUCBAgent(Agent):
+    """
+    Agentic tuner:
+      - Generates candidates (random)
+      - Fits a lightweight surrogate (ExtraTrees) on observed rewards (for a given fidelity)
+      - Chooses next action via UCB: mean + kappa * std (std estimated across trees)
+
+    Multi-fidelity policy:
+      - Always start at cheapest fidelity for new variants
+      - Promote a subset to next fidelity when budget allows
+    """
+
+    def __init__(self, cfg: Config, kappa: float = 1.0, init_random: int = 6):
+        self.cfg = cfg
+        self.kappa = kappa
+        self.init_random = init_random
+        self.stage_names = cfg.flow.fidelities
+        self.knob_names = list(cfg.tuning.knobs.keys())
+        self.variant_prefix = sanitize_variant_prefix(cfg.experiment.name)
+
+        self.obs: List[Obs] = []
+        self.variant_stage: Dict[str, int] = {}
+        self._variant_knobs: Dict[str, Dict[str, Any]] = {}  # Initialize knob storage
+        self.counter = 0
+
+    def _encode(self, knobs: Dict[str, Any]) -> np.ndarray:
+        xs = []
+        for name in self.knob_names:
+            spec = self.cfg.tuning.knobs[name]
+            v = float(knobs[name])
+            # normalize to [0,1]
+            xs.append((v - float(spec.min)) / max(1e-9, (float(spec.max) - float(spec.min))))
+        return np.array(xs, dtype=np.float32)
+
+    def _sample_knobs(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {}
+        for name, spec in self.cfg.tuning.knobs.items():
+            if spec.type == "int":
+                out[name] = random.randint(int(spec.min), int(spec.max))
+            else:
+                out[name] = float(spec.min) + random.random() * (float(spec.max) - float(spec.min))
+                out[name] = round(out[name], 3)
+        return out
+
+    def _fit_surrogate(self, fidelity: str) -> Optional[ExtraTreesRegressor]:
+        data = [o for o in self.obs if o.fidelity == fidelity]
+        if len(data) < max(5, self.init_random):
+            return None
+        X = np.stack([o.x for o in data], axis=0)
+        y = np.array([o.y for o in data], dtype=np.float32)
+        model = ExtraTreesRegressor(
+            n_estimators=128,
+            random_state=0,
+            min_samples_leaf=2,
+            n_jobs=-1,
+        )
+        model.fit(X, y)
+        return model
+
+    def _predict_ucb(self, model: ExtraTreesRegressor, Xcand: np.ndarray) -> np.ndarray:
+        # estimate mean/std across trees
+        preds = np.stack([t.predict(Xcand) for t in model.estimators_], axis=0)
+        mu = preds.mean(axis=0)
+        sd = preds.std(axis=0)
+        return mu + self.kappa * sd
+
+    def propose(self) -> Action:
+        self.counter += 1
+
+        # With some probability, promote an existing promising variant to next fidelity
+        promotable = [v for v, st in self.variant_stage.items() if st < len(self.stage_names) - 1]
+        if promotable and random.random() < 0.35:
+            # promote best observed (by latest reward) among promotable at current stage
+            best_v = None
+            best_y = float("-inf")
+            for v in promotable:
+                st = self.variant_stage[v]
+                fid = self.stage_names[st]
+                # best reward observed for this variant at its current fidelity
+                ys = [o.y for o in self.obs if o.fidelity == fid and o.variant == v]
+                if ys:
+                    y = max(ys)
+                    if y > best_y:
+                        best_y = y
+                        best_v = v
+            if best_v is not None:
+                st = self.variant_stage[best_v] + 1
+                self.variant_stage[best_v] = st
+                # knobs are encoded in variant hash, but store explicitly:
+                # easiest: resample from history by matching stable_hash prefix is messy;
+                # we instead keep a variant->knobs cache.
+                # If missing, fallback random.
+                knobs = self._variant_knobs.get(best_v, self._sample_knobs())
+                return Action(variant=best_v, fidelity=self.stage_names[st], knobs=knobs)
+
+        # Otherwise: propose a new variant at cheapest fidelity
+        knobs = self._sample_knobs()
+        x = self._encode(knobs)
+
+        fid0 = self.stage_names[0]
+        model = self._fit_surrogate(fid0)
+
+        if model is not None:
+            # do a small candidate search and pick best UCB
+            cands = []
+            Xc = []
+            for _ in range(32):
+                kk = self._sample_knobs()
+                cands.append(kk)
+                Xc.append(self._encode(kk))
+            Xc = np.stack(Xc, axis=0)
+            ucb = self._predict_ucb(model, Xc)
+            best_i = int(np.argmax(ucb))
+            knobs = cands[best_i]
+
+        variant = f"{self.variant_prefix}_u{self.counter:05d}_{stable_hash(str(knobs))}"
+        self.variant_stage[variant] = 0
+        self._variant_knobs[variant] = knobs
+        return Action(variant=variant, fidelity=fid0, knobs=knobs)
+
+    def observe(self, action: Action, ok: bool, reward: Optional[float], metrics_flat: Optional[Dict[str, Any]]) -> None:
+        if ok and reward is not None:
+            x = self._encode(action.knobs)
+            self.obs.append(Obs(x=x, y=float(reward), fidelity=action.fidelity, variant=action.variant))
+        # keep knobs cache
+        self._variant_knobs[action.variant] = action.knobs

src/edgeeda/cli.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from typing import Any, Dict, Optional
+
+from tqdm import tqdm
+
+from edgeeda.config import load_config, Config
+from edgeeda.utils import seed_everything, ensure_dir
+from edgeeda.store import TrialStore, TrialRecord
+from edgeeda.orfs.runner import ORFSRunner
+from edgeeda.orfs.metrics import find_best_metadata_json, load_json
+from edgeeda.reward import compute_reward
+from edgeeda.viz import export_trials, make_plots
+
+from edgeeda.agents.random_search import RandomSearchAgent
+from edgeeda.agents.successive_halving import SuccessiveHalvingAgent
+from edgeeda.agents.surrogate_ucb import SurrogateUCBAgent
+
+
+AGENTS = {
+    "random": RandomSearchAgent,
+    "successive_halving": SuccessiveHalvingAgent,
+    "surrogate_ucb": SurrogateUCBAgent,
+}
+
+
+def _select_agent(cfg: Config):
+    name = cfg.tuning.agent
+    if name not in AGENTS:
+        raise ValueError(f"Unknown agent: {name}. Choose from {list(AGENTS.keys())}")
+    return AGENTS[name](cfg)
+
+
+def _setup_logging(cfg: Config) -> None:
+    """Setup logging to both file and console."""
+    log_dir = cfg.experiment.out_dir
+    ensure_dir(log_dir)
+    log_file = os.path.join(log_dir, "tuning.log")
+    
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        handlers=[
+            logging.FileHandler(log_file),
+            logging.StreamHandler()
+        ]
+    )
+    logging.info(f"Logging initialized. Log file: {log_file}")
+
+
+def cmd_tune(args: argparse.Namespace) -> None:
+    cfg = load_config(args.config)
+    if args.budget is not None:
+        cfg.tuning.budget.total_actions = int(args.budget)
+
+    seed_everything(cfg.experiment.seed)
+    ensure_dir(cfg.experiment.out_dir)
+    _setup_logging(cfg)
+
+    logging.info(f"Starting tuning experiment: {cfg.experiment.name}")
+    logging.info(f"Agent: {cfg.tuning.agent}, Budget: {cfg.tuning.budget.total_actions} actions")
+    logging.info(f"Platform: {cfg.design.platform}, Design: {cfg.design.design}")
+
+    orfs_flow_dir = cfg.experiment.orfs_flow_dir or os.environ.get("ORFS_FLOW_DIR")
+    if not orfs_flow_dir:
+        raise RuntimeError("ORFS flow dir missing. Set experiment.orfs_flow_dir or export ORFS_FLOW_DIR=/path/to/ORFS/flow")
+
+    logging.info(f"ORFS flow directory: {orfs_flow_dir}")
+
+    runner = ORFSRunner(orfs_flow_dir)
+    store = TrialStore(cfg.experiment.db_path)
+    agent = _select_agent(cfg)
+
+    expensive_set = set(cfg.flow.fidelities[-1:])  # last stage treated as expensive
+    expensive_used = 0
+
+    for i in tqdm(range(cfg.tuning.budget.total_actions), desc="actions"):
+        action = agent.propose()
+        fidelity = action.fidelity
+
+        # enforce max expensive budget
+        if fidelity in expensive_set and expensive_used >= cfg.tuning.budget.max_expensive:
+            # downgrade to cheaper stage
+            fidelity = cfg.flow.fidelities[0]
+            action = type(action)(variant=action.variant, fidelity=fidelity, knobs=action.knobs)
+
+        make_target = cfg.flow.targets.get(fidelity, fidelity)
+        logging.info(f"Action {i+1}/{cfg.tuning.budget.total_actions}: variant={action.variant}, "
+                    f"fidelity={action.fidelity}, knobs={action.knobs}")
+        
+        # run ORFS make
+        logging.debug(f"Running: {make_target} for variant {action.variant}")
+        rr = runner.run_make(
+            target=make_target,
+            design_config=cfg.design.design_config,
+            flow_variant=action.variant,
+            overrides={k: str(v) for k, v in action.knobs.items()},
+            timeout_sec=args.timeout,
+        )
+
+        ok = (rr.return_code == 0)
+        if not ok:
+            logging.warning(f"Trial {i+1} failed: variant={action.variant}, return_code={rr.return_code}")
+            logging.debug(f"Command: {rr.cmd}")
+            if rr.stderr:
+                logging.debug(f"Stderr (last 500 chars): {rr.stderr[-500:]}")
+        else:
+            logging.info(f"Trial {i+1} succeeded: variant={action.variant}, runtime={rr.runtime_sec:.2f}s")
+
+        if fidelity in expensive_set:
+            expensive_used += 1
+
+        # always try to generate metadata JSON (avoid triggering full-flow when not needed)
+        meta_target = (
+            cfg.flow.targets.get("metadata_generate")
+            or cfg.flow.targets.get("metadata-generate")
+            or cfg.flow.targets.get("metadata", "metadata")
+        )
+        if meta_target == "metadata":
+            meta_target = "metadata-generate"
+        logging.debug(f"Generating metadata for variant {action.variant} using target={meta_target}")
+        meta_result = runner.run_make(
+            target=meta_target,
+            design_config=cfg.design.design_config,
+            flow_variant=action.variant,
+            overrides={},
+            timeout_sec=args.timeout,
+        )
+        if meta_result.return_code != 0:
+            logging.warning(f"Metadata generation failed for variant {action.variant}: return_code={meta_result.return_code}")
+
+        meta_path = find_best_metadata_json(
+            orfs_flow_dir=orfs_flow_dir,
+            platform=cfg.design.platform,
+            design=cfg.design.design,
+            variant=action.variant,
+        )
+
+        reward = None
+        flat = None
+
+        if meta_path:
+            logging.debug(f"Found metadata at: {meta_path}")
+            try:
+                mobj = load_json(meta_path)
+                reward, comps, flat = compute_reward(
+                    metrics_obj=mobj,
+                    wns_candidates=cfg.reward.wns_candidates,
+                    area_candidates=cfg.reward.area_candidates,
+                    power_candidates=cfg.reward.power_candidates,
+                    weights=cfg.reward.weights,
+                )
+                if reward is not None:
+                    logging.info(f"Computed reward for variant {action.variant}: {reward:.4f} "
+                               f"(WNS={comps.wns}, area={comps.area}, power={comps.power})")
+                else:
+                    logging.warning(f"Reward computation returned None for variant {action.variant}")
+            except Exception as e:
+                logging.error(f"Failed to compute reward for variant {action.variant}: {e}", exc_info=True)
+                ok = False
+        else:
+            logging.warning(f"Metadata not found for variant {action.variant} at "
+                          f"reports/{cfg.design.platform}/{cfg.design.design}/{action.variant}/")
+
+        store.add(
+            TrialRecord(
+                exp_name=cfg.experiment.name,
+                platform=cfg.design.platform,
+                design=cfg.design.design,
+                variant=action.variant,
+                fidelity=action.fidelity,
+                knobs=action.knobs,
+                make_cmd=rr.cmd,
+                return_code=rr.return_code,
+                runtime_sec=rr.runtime_sec,
+                reward=reward,
+                metrics=flat,
+                metadata_path=meta_path,
+            )
+        )
+
+        agent.observe(action, ok=ok, reward=reward, metrics_flat=flat)
+
+    store.close()
+
+    # Export summary
+    logging.info("Exporting trial summary...")
+    df = export_trials(cfg.experiment.db_path)
+    out_csv = os.path.join(cfg.experiment.out_dir, "summary.csv")
+    df.to_csv(out_csv, index=False)
+    
+    # Log summary statistics
+    total_trials = len(df)
+    successful = len(df[df['return_code'] == 0])
+    with_rewards = len(df[df['reward'].notna()])
+    logging.info(f"Experiment complete: {total_trials} trials, {successful} successful, {with_rewards} with rewards")
+    
+    print(f"[done] wrote {out_csv}")
+
+
+def cmd_analyze(args: argparse.Namespace) -> None:
+    df = export_trials(args.db)
+    ensure_dir(args.out)
+    df.to_csv(os.path.join(args.out, "trials.csv"), index=False)
+    make_plots(df, args.out)
+    print(f"[done] wrote plots to {args.out}")
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="edgeeda")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_tune = sub.add_parser("tune", help="Run agentic tuning loop on ORFS")
+    p_tune.add_argument("--config", required=True, help="YAML config")
+    p_tune.add_argument("--budget", type=int, default=None, help="Override total_actions")
+    p_tune.add_argument("--timeout", type=int, default=None, help="Timeout per make run (sec)")
+    p_tune.set_defaults(func=cmd_tune)
+
+    p_an = sub.add_parser("analyze", help="Export CSV + plots")
+    p_an.add_argument("--db", required=True, help="SQLite db path")
+    p_an.add_argument("--out", required=True, help="Output directory for plots")
+    p_an.set_defaults(func=cmd_analyze)
+
+    args = p.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

src/edgeeda/config.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+
+@dataclass
+class KnobSpec:
+    type: str  # "int" | "float"
+    min: float
+    max: float
+
+
+@dataclass
+class RewardSpec:
+    weights: Dict[str, float]
+    wns_candidates: List[str]
+    area_candidates: List[str]
+    power_candidates: List[str]
+
+
+@dataclass
+class BudgetSpec:
+    total_actions: int
+    max_expensive: int
+
+
+@dataclass
+class ExperimentSpec:
+    name: str
+    seed: int
+    db_path: str
+    out_dir: str
+    orfs_flow_dir: Optional[str]
+
+
+@dataclass
+class DesignSpec:
+    platform: str
+    design: str
+    design_config: str  # relative to ORFS flow dir
+
+
+@dataclass
+class FlowSpec:
+    fidelities: List[str]
+    targets: Dict[str, str]
+
+
+@dataclass
+class TuningSpec:
+    agent: str
+    budget: BudgetSpec
+    knobs: Dict[str, KnobSpec]
+
+
+@dataclass
+class Config:
+    experiment: ExperimentSpec
+    design: DesignSpec
+    flow: FlowSpec
+    tuning: TuningSpec
+    reward: RewardSpec
+
+
+def load_config(path: str) -> Config:
+    with open(path, "r", encoding="utf-8") as f:
+        d = yaml.safe_load(f)
+
+    exp = d["experiment"]
+    design = d["design"]
+    flow = d["flow"]
+    tuning = d["tuning"]
+    reward = d["reward"]
+
+    knobs: Dict[str, KnobSpec] = {}
+    for k, ks in tuning["knobs"].items():
+        knobs[k] = KnobSpec(
+            type=str(ks["type"]),
+            min=float(ks["min"]),
+            max=float(ks["max"]),
+        )
+
+    cfg = Config(
+        experiment=ExperimentSpec(
+            name=str(exp["name"]),
+            seed=int(exp.get("seed", 0)),
+            db_path=str(exp.get("db_path", "runs/experiment.sqlite")),
+            out_dir=str(exp.get("out_dir", "runs")),
+            orfs_flow_dir=exp.get("orfs_flow_dir", None),
+        ),
+        design=DesignSpec(
+            platform=str(design["platform"]),
+            design=str(design["design"]),
+            design_config=str(design["design_config"]),
+        ),
+        flow=FlowSpec(
+            fidelities=list(flow["fidelities"]),
+            targets=dict(flow["targets"]),
+        ),
+        tuning=TuningSpec(
+            agent=str(tuning["agent"]),
+            budget=BudgetSpec(
+                total_actions=int(tuning["budget"]["total_actions"]),
+                max_expensive=int(tuning["budget"]["max_expensive"]),
+            ),
+            knobs=knobs,
+        ),
+        reward=RewardSpec(
+            weights=dict(reward["weights"]),
+            wns_candidates=list(reward["keys"]["wns_candidates"]),
+            area_candidates=list(reward["keys"]["area_candidates"]),
+            power_candidates=list(reward["keys"]["power_candidates"]),
+        ),
+    )
+    
+    # Validate configuration
+    _validate_config(cfg)
+    
+    return cfg
+
+
+def _validate_config(cfg: Config) -> None:
+    """Validate configuration values."""
+    # Validate budget
+    if cfg.tuning.budget.total_actions <= 0:
+        raise ValueError(f"total_actions must be > 0, got {cfg.tuning.budget.total_actions}")
+    if cfg.tuning.budget.max_expensive < 0:
+        raise ValueError(f"max_expensive must be >= 0, got {cfg.tuning.budget.max_expensive}")
+    if cfg.tuning.budget.max_expensive > cfg.tuning.budget.total_actions:
+        raise ValueError(
+            f"max_expensive ({cfg.tuning.budget.max_expensive}) cannot exceed "
+            f"total_actions ({cfg.tuning.budget.total_actions})"
+        )
+    
+    # Validate fidelities
+    if not cfg.flow.fidelities:
+        raise ValueError("flow.fidelities cannot be empty")
+    
+    # Validate knobs
+    if not cfg.tuning.knobs:
+        raise ValueError("tuning.knobs cannot be empty")
+    
+    for name, spec in cfg.tuning.knobs.items():
+        if spec.min >= spec.max:
+            raise ValueError(f"Knob {name}: min ({spec.min}) must be < max ({spec.max})")
+        if spec.type not in ("int", "float"):
+            raise ValueError(f"Knob {name}: type must be 'int' or 'float', got '{spec.type}'")
+    
+    # Validate reward weights
+    if not cfg.reward.weights:
+        raise ValueError("reward.weights cannot be empty")
+    
+    # Validate reward candidates
+    if not cfg.reward.wns_candidates and not cfg.reward.area_candidates and not cfg.reward.power_candidates:
+        raise ValueError("At least one reward candidate list must be non-empty")
+    
+    # Note: design_config validation happens later when ORFS dir is known

src/edgeeda/orfs/__init__.py

@@ -0,0 +1 @@
+__all__ = ["runner", "metrics"]

src/edgeeda/orfs/metrics.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import glob
+import gzip
+import json
+import logging
+import os
+from typing import Any, Dict, Optional, Tuple, List
+
+
+def _list_json_files(dir_path: str):
+    if not os.path.isdir(dir_path):
+        return []
+    out = []
+    for fn in os.listdir(dir_path):
+        if fn.endswith(".json"):
+            out.append(os.path.join(dir_path, fn))
+    return out
+
+
+def _list_json_and_gz_files(dir_path: str) -> List[str]:
+    """Return .json and .json.gz files in directory (non-recursive)."""
+    if not os.path.isdir(dir_path):
+        return []
+    out: List[str] = []
+    for fn in os.listdir(dir_path):
+        if fn.endswith(".json") or fn.endswith(".json.gz"):
+            out.append(os.path.join(dir_path, fn))
+    return out
+
+
+def find_best_metadata_json(
+    orfs_flow_dir: str,
+    platform: str,
+    design: str,
+    variant: str,
+) -> Optional[str]:
+    """
+    ORFS convention:
+      reports/<platform>/<design>/<FLOW_VARIANT>/
+    We search for likely metadata / metrics files and pick most recently modified.
+    
+    Tries multiple patterns in order of preference:
+    1. Exact matches: metadata.json, metrics.json
+    2. Pattern matches: *metadata*.json, *metrics*.json
+    3. Fallback: any .json file
+    """
+    base = os.path.join(orfs_flow_dir, "reports", platform, design, variant)
+    
+    if not os.path.exists(base):
+        logging.debug(f"Reports directory does not exist: {base}")
+        return None
+    
+    if not os.path.isdir(base):
+        logging.warning(f"Reports path exists but is not a directory: {base}")
+        return None
+    
+    # Try multiple patterns, searching recursively so nested report dirs are found
+    patterns = [
+        "**/metadata.json",
+        "**/metrics.json",
+        "**/*metadata*.json",
+        "**/*metrics*.json",
+        "**/*final*.json",
+        "**/*report*.json",
+        "**/*results*.json",
+    ]
+
+    candidates: List[str] = []
+    for pattern in patterns:
+        matches = glob.glob(os.path.join(base, pattern), recursive=True)
+        if matches:
+            candidates.extend(matches)
+            logging.debug(f"Found {len(matches)} files matching pattern '{pattern}' under {base}")
+            break  # Prefer the first matching pattern set
+    
+    # Fallback: any .json or .json.gz file in the dir (non-recursive)
+    if not candidates:
+        candidates = _list_json_and_gz_files(base)
+        if candidates:
+            logging.debug(f"Using fallback: found {len(candidates)} JSON(/gz) files in {base}")
+    
+    if not candidates:
+        logging.warning(f"No JSON files found in {base}")
+        return None
+    
+    # If still empty, try searching one level up or across siblings
+    if not candidates:
+        parent = os.path.dirname(base)
+        siblings = glob.glob(os.path.join(parent, "**/*.json"), recursive=True)
+        if siblings:
+            candidates = siblings
+            logging.debug(f"Fallback: found {len(siblings)} JSON files under {parent}")
+
+    if not candidates:
+        logging.warning(f"No JSON files found in {base} or nearby")
+        return None
+
+    # Sort by modification time (most recent first)
+    candidates.sort(key=lambda p: os.path.getmtime(p), reverse=True)
+    selected = candidates[0]
+    logging.debug(f"Selected metadata file: {selected} (from {len(candidates)} candidates)")
+    return selected
+
+
+def load_json(path: str) -> Dict[str, Any]:
+    """Load JSON file with error handling."""
+    try:
+        if path.endswith('.gz') or path.endswith('.json.gz'):
+            with gzip.open(path, 'rt', encoding='utf-8') as f:
+                return json.load(f)
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        logging.warning(f"Failed to parse JSON from {path}: {e}. Trying lenient read.")
+        # Try a lenient read: read file and attempt to find JSON-like substring
+        try:
+            if path.endswith('.gz') or path.endswith('.json.gz'):
+                with gzip.open(path, 'rt', encoding='utf-8', errors='ignore') as f:
+                    txt = f.read()
+            else:
+                with open(path, 'r', encoding='utf-8', errors='ignore') as f:
+                    txt = f.read()
+            # attempt to locate first JSON object within text
+            start = txt.find('{')
+            end = txt.rfind('}')
+            if start != -1 and end != -1 and end > start:
+                snippet = txt[start:end+1]
+                return json.loads(snippet)
+        except Exception as e2:
+            logging.error(f"Lenient parse failed for {path}: {e2}")
+        raise
+    except FileNotFoundError:
+        logging.error(f"JSON file not found: {path}")
+        raise
+    except Exception as e:
+        logging.error(f"Unexpected error loading JSON from {path}: {e}")
+        raise
+
+
+def flatten_metrics(obj: Any, prefix: str = "") -> Dict[str, Any]:
+    """
+    Flattens nested dicts into key paths joined by '__'.
+    Keeps non-dict leaf values.
+    """
+    out: Dict[str, Any] = {}
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            kk = f"{prefix}__{k}" if prefix else str(k)
+            out.update(flatten_metrics(v, kk))
+    else:
+        out[prefix] = obj
+    return out
+
+
+def coerce_float(x: Any) -> Optional[float]:
+    if x is None:
+        return None
+    if isinstance(x, (int, float)):
+        return float(x)
+    if isinstance(x, str):
+        try:
+            return float(x)
+        except ValueError:
+            return None
+    return None
+
+
+def pick_first(metrics_flat: Dict[str, Any], keys: list[str]) -> Optional[float]:
+    for k in keys:
+        if k in metrics_flat:
+            v = coerce_float(metrics_flat[k])
+            if v is not None:
+                return v
+    # also try case-insensitive match
+    lower = {kk.lower(): kk for kk in metrics_flat.keys()}
+    for k in keys:
+        kk = lower.get(k.lower())
+        if kk:
+            v = coerce_float(metrics_flat[kk])
+            if v is not None:
+                return v
+    return None

src/edgeeda/orfs/runner.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import os
+import shutil
+import shlex
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+from edgeeda.utils import ensure_dir
+
+
+@dataclass
+class RunResult:
+    return_code: int
+    runtime_sec: float
+    cmd: str
+    stdout: str
+    stderr: str
+    
+    def is_success(self) -> bool:
+        """Check if the run was successful."""
+        return self.return_code == 0
+    
+    def error_summary(self, max_lines: int = 5) -> str:
+        """Extract key error information from stderr."""
+        if self.is_success():
+            return "Success"
+        
+        lines = self.stderr.split('\n')
+        # Find lines with error keywords
+        error_lines = [
+            l for l in lines 
+            if any(kw in l.lower() for kw in ['error', 'fatal', 'failed', 'exception'])
+        ]
+        
+        if error_lines:
+            return '\n'.join(error_lines[-max_lines:])
+        
+        # Fallback: last few lines of stderr
+        if lines:
+            return '\n'.join(lines[-max_lines:])
+        
+        return f"Command failed with return code {self.return_code}"
+
+
+class ORFSRunner:
+    """
+    Minimal ORFS interface:
+      - Runs `make <target> DESIGN_CONFIG=... FLOW_VARIANT=... VAR=...`
+      - Uses ORFS_FLOW_DIR (OpenROAD-flow-scripts/flow) as working directory.
+    """
+
+    def __init__(self, orfs_flow_dir: str):
+        self.flow_dir = os.path.abspath(orfs_flow_dir)
+        if not os.path.isdir(self.flow_dir):
+            raise FileNotFoundError(f"ORFS flow dir not found: {self.flow_dir}")
+        self._openroad_fallback = os.path.abspath(
+            os.path.join(self.flow_dir, "..", "tools", "install", "OpenROAD", "bin", "openroad")
+        )
+        self._opensta_fallback = os.path.abspath(
+            os.path.join(self.flow_dir, "..", "tools", "install", "OpenROAD", "bin", "sta")
+        )
+        self._yosys_fallback = os.path.abspath(
+            os.path.join(self.flow_dir, "..", "tools", "install", "yosys", "bin", "yosys")
+        )
+
+    def _build_env(self) -> Dict[str, str]:
+        env = os.environ.copy()
+        openroad_exe = env.get("OPENROAD_EXE")
+        if not openroad_exe or not os.path.isfile(openroad_exe) or not os.access(openroad_exe, os.X_OK):
+            if os.path.isfile(self._openroad_fallback) and os.access(self._openroad_fallback, os.X_OK):
+                env["OPENROAD_EXE"] = self._openroad_fallback
+            else:
+                found = shutil.which("openroad")
+                if found:
+                    env["OPENROAD_EXE"] = found
+        opensta_exe = env.get("OPENSTA_EXE")
+        if not opensta_exe or not os.path.isfile(opensta_exe) or not os.access(opensta_exe, os.X_OK):
+            if os.path.isfile(self._opensta_fallback) and os.access(self._opensta_fallback, os.X_OK):
+                env["OPENSTA_EXE"] = self._opensta_fallback
+            else:
+                found = shutil.which("sta")
+                if found:
+                    env["OPENSTA_EXE"] = found
+        yosys_exe = env.get("YOSYS_EXE")
+        if not yosys_exe or not os.path.isfile(yosys_exe) or not os.access(yosys_exe, os.X_OK):
+            if os.path.isfile(self._yosys_fallback) and os.access(self._yosys_fallback, os.X_OK):
+                env["YOSYS_EXE"] = self._yosys_fallback
+            else:
+                found = shutil.which("yosys")
+                if found:
+                    env["YOSYS_EXE"] = found
+        return env
+
+    def run_make(
+        self,
+        target: str,
+        design_config: str,
+        flow_variant: str,
+        overrides: Dict[str, str],
+        timeout_sec: Optional[int] = None,
+        extra_make_args: Optional[List[str]] = None,
+        max_retries: int = 0,
+    ) -> RunResult:
+        """
+        Run make command with optional retry logic.
+        
+        Args:
+            target: Make target (e.g., 'synth', 'place', 'route')
+            design_config: Design configuration path
+            flow_variant: Flow variant identifier
+            overrides: Dictionary of make variable overrides
+            timeout_sec: Timeout in seconds
+            extra_make_args: Additional make arguments
+            max_retries: Maximum number of retries for transient failures
+        
+        Returns:
+            RunResult with command execution details
+        """
+        extra_make_args = extra_make_args or []
+        # Build make command
+        cmd_list = [
+            "make",
+            target,
+            f"DESIGN_CONFIG={design_config}",
+            f"FLOW_VARIANT={flow_variant}",
+        ]
+        for k, v in overrides.items():
+            cmd_list.append(f"{k}={v}")
+        cmd_list += extra_make_args
+
+        cmd_str = " ".join(shlex.quote(x) for x in cmd_list)
+
+        # Retry logic for transient failures
+        last_result = None
+        for attempt in range(max_retries + 1):
+            t0 = time.time()
+            try:
+                env = self._build_env()
+                p = subprocess.run(
+                    cmd_list,
+                    cwd=self.flow_dir,
+                    capture_output=True,
+                    text=True,
+                    timeout=timeout_sec,
+                    env=env,
+                )
+                dt = time.time() - t0
+                result = RunResult(
+                    return_code=p.returncode,
+                    runtime_sec=dt,
+                    cmd=cmd_str,
+                    stdout=p.stdout[-20000:],  # keep tail
+                    stderr=p.stderr[-20000:],
+                )
+                
+                # If successful or no more retries, return
+                if result.is_success() or attempt >= max_retries:
+                    return result
+                
+                last_result = result
+                
+                # Exponential backoff before retry
+                if attempt < max_retries:
+                    wait_time = 2 ** attempt
+                    time.sleep(wait_time)
+                    
+            except subprocess.TimeoutExpired:
+                dt = time.time() - t0
+                result = RunResult(
+                    return_code=124,  # Standard timeout exit code
+                    runtime_sec=dt,
+                    cmd=cmd_str,
+                    stdout="",
+                    stderr=f"Command timed out after {timeout_sec} seconds",
+                )
+                if attempt >= max_retries:
+                    return result
+                last_result = result
+                if attempt < max_retries:
+                    time.sleep(2 ** attempt)
+            except Exception as e:
+                dt = time.time() - t0
+                result = RunResult(
+                    return_code=1,
+                    runtime_sec=dt,
+                    cmd=cmd_str,
+                    stdout="",
+                    stderr=f"Exception during execution: {str(e)}",
+                )
+                if attempt >= max_retries:
+                    return result
+                last_result = result
+                if attempt < max_retries:
+                    time.sleep(2 ** attempt)
+        
+        return last_result

src/edgeeda/reward.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+from edgeeda.orfs.metrics import flatten_metrics, pick_first
+
+
+@dataclass
+class RewardComponents:
+    wns: Optional[float]
+    area: Optional[float]
+    power: Optional[float]
+
+
+def compute_reward(
+    metrics_obj: Dict[str, Any],
+    wns_candidates: list[str],
+    area_candidates: list[str],
+    power_candidates: list[str],
+    weights: Dict[str, float],
+) -> Tuple[Optional[float], RewardComponents, Dict[str, Any]]:
+    """
+    Reward convention:
+      - Want larger WNS (less negative / more positive)
+      - Want smaller area, smaller power
+    Scalar reward = w_wns * WNS  - w_area * log(area) - w_power * log(power)
+    (log makes it less sensitive across designs)
+    """
+    flat = flatten_metrics(metrics_obj)
+
+    wns = pick_first(flat, wns_candidates)
+    if wns is None:
+        fallback_wns = [
+            "timing__setup__ws",
+            "finish__timing__setup__ws",
+            "route__timing__setup__ws",
+            "cts__timing__setup__ws",
+            "detailedplace__timing__setup__ws",
+            "floorplan__timing__setup__ws",
+            "globalplace__timing__setup__ws",
+            "globalroute__timing__setup__ws",
+            "placeopt__timing__setup__ws",
+        ]
+        wns = pick_first(flat, fallback_wns)
+    area = pick_first(flat, area_candidates)
+    if area is None:
+        fallback_area = [
+            "synth__design__instance__area__stdcell",
+            "floorplan__design__instance__area__stdcell",
+            "globalplace__design__instance__area__stdcell",
+            "detailedplace__design__instance__area__stdcell",
+            "cts__design__instance__area__stdcell",
+            "finish__design__instance__area__stdcell",
+            "floorplan__design__die__area",
+            "placeopt__design__die__area",
+            "detailedplace__design__die__area",
+            "cts__design__die__area",
+            "globalroute__design__die__area",
+            "finish__design__die__area",
+        ]
+        area = pick_first(flat, fallback_area)
+    power = pick_first(flat, power_candidates)
+
+    if wns is None and area is None and power is None:
+        return None, RewardComponents(None, None, None), flat
+
+    import math
+
+    w_wns = float(weights.get("wns", 1.0))
+    w_area = float(weights.get("area", 0.0))
+    w_power = float(weights.get("power", 0.0))
+
+    # Robustify logs
+    area_term = 0.0 if area is None else math.log(max(area, 1e-9))
+    power_term = 0.0 if power is None else math.log(max(power, 1e-9))
+    wns_term = 0.0 if wns is None else wns
+
+    reward = (w_wns * wns_term) - (w_area * area_term) - (w_power * power_term)
+    return reward, RewardComponents(wns, area, power), flat

src/edgeeda/store.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, Optional
+
+from edgeeda.utils import ensure_dir, now_ts
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS trials (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  exp_name TEXT NOT NULL,
+  platform TEXT NOT NULL,
+  design TEXT NOT NULL,
+  variant TEXT NOT NULL,
+  fidelity TEXT NOT NULL,
+
+  knobs_json TEXT NOT NULL,
+  make_cmd TEXT NOT NULL,
+  return_code INTEGER NOT NULL,
+  runtime_sec REAL NOT NULL,
+
+  reward REAL,
+  metrics_json TEXT,
+  metadata_path TEXT,
+
+  created_ts REAL NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_trials_exp ON trials(exp_name);
+CREATE INDEX IF NOT EXISTS idx_trials_variant ON trials(platform, design, variant);
+"""
+
+
+@dataclass
+class TrialRecord:
+    exp_name: str
+    platform: str
+    design: str
+    variant: str
+    fidelity: str
+    knobs: Dict[str, Any]
+    make_cmd: str
+    return_code: int
+    runtime_sec: float
+    reward: Optional[float]
+    metrics: Optional[Dict[str, Any]]
+    metadata_path: Optional[str]
+
+
+class TrialStore:
+    def __init__(self, db_path: str):
+        ensure_dir(db_path.rsplit("/", 1)[0] if "/" in db_path else ".")
+        self.conn = sqlite3.connect(db_path)
+        self.conn.execute("PRAGMA journal_mode=WAL;")
+        self.conn.executescript(SCHEMA)
+        self.conn.commit()
+
+    def add(self, r: TrialRecord) -> None:
+        self.conn.execute(
+            """
+            INSERT INTO trials(
+              exp_name, platform, design, variant, fidelity,
+              knobs_json, make_cmd, return_code, runtime_sec,
+              reward, metrics_json, metadata_path, created_ts
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                r.exp_name,
+                r.platform,
+                r.design,
+                r.variant,
+                r.fidelity,
+                json.dumps(r.knobs, sort_keys=True),
+                r.make_cmd,
+                int(r.return_code),
+                float(r.runtime_sec),
+                None if r.reward is None else float(r.reward),
+                None if r.metrics is None else json.dumps(r.metrics),
+                r.metadata_path,
+                now_ts(),
+            ),
+        )
+        self.conn.commit()
+
+    def fetch_all(self, exp_name: str):
+        cur = self.conn.execute(
+            "SELECT exp_name, platform, design, variant, fidelity, knobs_json, make_cmd, return_code, runtime_sec, reward, metrics_json, metadata_path, created_ts FROM trials WHERE exp_name=? ORDER BY id ASC",
+            (exp_name,),
+        )
+        return cur.fetchall()
+
+    def close(self) -> None:
+        self.conn.close()

src/edgeeda/utils.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+import time
+import random
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Optional
+
+import numpy as np
+
+
+def now_ts() -> float:
+    return time.time()
+
+
+def seed_everything(seed: int) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    os.environ["PYTHONHASHSEED"] = str(seed)
+
+
+def ensure_dir(path: str) -> None:
+    os.makedirs(path, exist_ok=True)
+
+
+def clamp(x: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, x))
+
+
+def stable_hash(s: str) -> str:
+    # Short stable tag for filenames/variants
+    import hashlib
+    return hashlib.sha1(s.encode("utf-8")).hexdigest()[:10]
+
+
+def sanitize_variant_prefix(name: str, max_len: int = 24) -> str:
+    safe = re.sub(r"[^A-Za-z0-9_]+", "_", name).strip("_")
+    if not safe:
+        safe = "run"
+    if max_len > 0 and len(safe) > max_len:
+        safe = safe[:max_len]
+    return safe
+
+
+@dataclass(frozen=True)
+class TrialKey:
+    exp_name: str
+    platform: str
+    design: str
+    variant: str
+    fidelity: str

src/edgeeda/viz.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+import json
+import sqlite3
+from typing import Any, Dict
+
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from edgeeda.utils import ensure_dir
+
+
+def export_trials(db_path: str) -> pd.DataFrame:
+    con = sqlite3.connect(db_path)
+    df = pd.read_sql_query("SELECT * FROM trials", con)
+    con.close()
+    return df
+
+
+def make_plots(df: pd.DataFrame, out_dir: str) -> None:
+    ensure_dir(out_dir)
+
+    # Learning curve: best reward over time
+    df2 = df.copy()
+    df2["reward"] = pd.to_numeric(df2["reward"], errors="coerce")
+    df2 = df2.dropna(subset=["reward"]).sort_values("id")
+    if not df2.empty:
+        best = df2["reward"].cummax()
+        plt.figure()
+        plt.plot(df2["id"].values, best.values)
+        plt.xlabel("trial id")
+        plt.ylabel("best reward so far")
+        plt.tight_layout()
+        plt.savefig(os.path.join(out_dir, "learning_curve.png"), dpi=200)
+        plt.close()
+
+    # Pareto-ish scatter: area vs wns from metrics_json if available
+    areas, wnss = [], []
+    for _, r in df.iterrows():
+        mj = r.get("metrics_json")
+        if not isinstance(mj, str) or not mj:
+            continue
+        try:
+            m = json.loads(mj)
+        except Exception:
+            continue
+        # try common keys (flattened already stored by runner)
+        a = m.get("design__die__area") or m.get("finish__design__die__area")
+        w = m.get("timing__setup__wns") or m.get("finish__timing__setup__wns")
+        if a is None or w is None:
+            continue
+        try:
+            areas.append(float(a)); wnss.append(float(w))
+        except Exception:
+            pass
+
+    if areas:
+        plt.figure()
+        plt.scatter(areas, wnss)
+        plt.xlabel("die area")
+        plt.ylabel("WNS")
+        plt.tight_layout()
+        plt.savefig(os.path.join(out_dir, "area_vs_wns.png"), dpi=200)
+        plt.close()