fix examples

Author: soodoku

examples/README.md

@@ -6,16 +6,16 @@ This directory provides a complete demonstration suite for **allocator v1.0** us
 
 ```bash
 # 1. Basic API introduction (1-2 seconds)
-cd scripts && uv run python quick_start.py
+uv run python examples/scripts/quick_start.py
 
 # 2. Real-world performance analysis (5-10 seconds)
-uv run python real_world_workflow.py
+uv run python examples/scripts/real_world_workflow.py
 
 # 3. Generate comprehensive visualizations (30-60 seconds)
-uv run python algorithm_comparison.py
+uv run python examples/scripts/algorithm_comparison.py
 
 # View results
-open ../outputs/latest/comparisons/reports/executive_summary.html
+open examples/outputs/latest/comparisons/reports/executive_summary.html
 ```
 
 ## 📁 Directory Structure
@@ -74,23 +74,23 @@ examples/
 
 ### 1. Quick API Introduction
 ```bash
-cd scripts && uv run python quick_start.py
+uv run python examples/scripts/quick_start.py
 ```
 - **Purpose:** Learn basic allocator functionality
 - **Runtime:** 1-2 seconds
 - **Output:** Console demonstration of clustering, routing, assignment
 
 ### 2. Real-World Performance Analysis  
 ```bash
-cd scripts && uv run python real_world_workflow.py
+uv run python examples/scripts/real_world_workflow.py
 ```
 - **Purpose:** Production performance validation
 - **Runtime:** 5-10 seconds
 - **Output:** Performance metrics using actual city data
 
 ### 3. Comprehensive Visualization Generation
 ```bash  
-cd scripts && uv run python algorithm_comparison.py
+uv run python examples/scripts/algorithm_comparison.py
 ```
 - **Purpose:** Research, reporting, executive presentations
 - **Runtime:** 30-60 seconds
@@ -102,6 +102,9 @@ cd scripts && uv run python algorithm_comparison.py
 - 📄 **HTML reports:** Executive summaries, detailed analysis
 - 🔧 **JSON summaries:** Machine-readable performance metrics
 
+**💾 Intermediate File Preservation:**
+All generated outputs (PNG charts, CSV data, HTML reports) are automatically preserved in timestamped directories under `examples/outputs/YYYY-MM-DD_HH-MM/` with organized structure by city and analysis type. This ensures all intermediate analysis files are retained for review, comparison, and further processing.
+
 ## 📊 Example Outputs
 
 ### Performance Metrics (typical results)
@@ -177,19 +180,19 @@ All dependencies are defined in `../../pyproject.toml`:
 ### Development & Testing
 ```bash
 # Quick validation (1-2 seconds)
-uv run python quick_start.py
+uv run python examples/scripts/quick_start.py
 
 # Performance testing (5-10 seconds)  
-uv run python real_world_workflow.py
+uv run python examples/scripts/real_world_workflow.py
 ```
 
 ### Production Analysis
 ```bash
 # Comprehensive reporting (30-60 seconds)
-uv run python algorithm_comparison.py
+uv run python examples/scripts/algorithm_comparison.py
 
 # Custom CLI workflows
-uv run allocator cluster kmeans inputs/delhi-roads-1k.csv --n-clusters 7 --output results.csv
+uv run allocator cluster kmeans examples/inputs/delhi-roads-1k.csv --n-clusters 7 --output results.csv
 ```
 
 ### Large-Scale Deployment
@@ -222,7 +225,7 @@ route = allocator.shortest_path(points.head(10), method='ortools')
 #!/bin/bash
 # Production batch processing
 for city in delhi chonburi; do
-    allocator cluster kmeans inputs/${city}-roads-1k.csv \
+    allocator cluster kmeans examples/inputs/${city}-roads-1k.csv \
         --n-clusters 5 \
         --output results/${city}_zones.csv
 done
@@ -232,7 +235,7 @@ done
 ```python
 # Load analysis results for dashboard
 import json
-with open('outputs/latest/comparisons/data/analysis_summary.json') as f:
+with open('examples/outputs/latest/comparisons/data/analysis_summary.json') as f:
     metrics = json.load(f)
 
 # Display in web dashboard, monitoring system, etc.
@@ -250,9 +253,9 @@ This demonstration suite validates:
 
 ## 📝 Next Steps
 
-1. **Explore:** Run `quick_start.py` to understand basic functionality
-2. **Validate:** Use `real_world_workflow.py` for performance insights  
-3. **Generate:** Create professional reports with `algorithm_comparison.py`
+1. **Explore:** Run `uv run python examples/scripts/quick_start.py` to understand basic functionality
+2. **Validate:** Use `uv run python examples/scripts/real_world_workflow.py` for performance insights  
+3. **Generate:** Create professional reports with `uv run python examples/scripts/algorithm_comparison.py`
 4. **Customize:** Modify scripts for your specific datasets and requirements
 5. **Scale:** Implement in production systems using CLI or Python API
 

examples/README_WORKFLOWS.md

@@ -0,0 +1,52 @@
+# Allocator Analysis Run - 2025-12-01 12:57
+
+## 📁 Directory Structure
+
+```
+2025-12-01_12-57/
+├── delhi/
+│   ├── clustering/
+│   │   ├── data/           # CSV files with clustering results
+│   │   ├── visualizations/ # PNG performance charts  
+│   │   └── reports/        # HTML detailed analysis
+│   ├── routing/
+│   │   ├── data/           # TSP solution CSV files
+│   │   ├── visualizations/ # Route performance charts
+│   │   └── reports/        # HTML routing analysis
+│   └── assignments/        # (Future: assignment analysis)
+├── chonburi/
+│   └── [same structure as delhi]
+└── comparisons/
+    ├── data/               # Cross-city comparison data
+    ├── visualizations/     # Comparison charts
+    └── reports/            # Executive summary report
+```
+
+## 🎯 Key Files
+
+- **Executive Summary:** `comparisons/reports/executive_summary.html`
+- **City Reports:** `[city]/[analysis]/reports/[city]_[analysis]_report.html`
+- **Performance Data:** `comparisons/data/analysis_summary.json`
+- **Visualizations:** `[city]/[analysis]/visualizations/*.png`
+
+## 📊 Analysis Overview
+
+This run analyzed road network data for Delhi, India and Chonburi, Thailand using:
+
+- **Clustering:** K-means with euclidean and haversine distance methods
+- **Routing:** TSP optimization using OR-Tools  
+- **Distance Methods:** Comparative analysis of calculation methods
+
+## 🚀 Next Steps
+
+1. View executive summary for high-level insights
+2. Review city-specific reports for detailed analysis
+3. Use CSV data files for further processing
+4. Scale analysis to larger datasets or additional cities
+
+## 🔗 Links
+
+- [Executive Summary](comparisons/reports/executive_summary.html)
+- [Delhi Analysis](delhi/)  
+- [Chonburi Analysis](chonburi/)
+- [Source Code](../scripts/)