Add RunConfig & GUI for interactive pipeline execution

[oh-da]

Summary

Refactors the pipeline to support both CLI and GUI execution modes by introducing a RunConfig dataclass that fully describes a single pipeline run. Adds a new desktop GUI application (app/run_model_gui.py) with native file pickers, auto-detection of input files from directories, and comprehensive run logging.

Key Changes

Core Pipeline Refactoring

• RunConfig dataclass: Encapsulates all run parameters (input files, output directory, skip flags, metadata like run_by and remarks)
  • Includes validation (validate()) and property accessors for output directories
  • Auto-normalizes paths and generates run IDs with timestamps
• Dependency check gating: Moved check_and_install_dependencies() behind if __name__ == "__main__" guard so importing the module (e.g., by the GUI) doesn't block on interactive input
• Input file hints & auto-detection: New INPUT_FILE_HINTS dict and resolve_inputs_from_directory() function enable scanning a folder for expected files by extension and name patterns
• Pipeline entry point: New run_pipeline(config) function (visible in truncated section) replaces direct script execution, accepting a RunConfig instead of global constants
• Per-run logging: Pipeline now attaches a file handler to write logs to run_<timestamp>.log inside the output directory

GUI Application (app/run_model_gui.py)

• Desktop window via pywebview (native OS rendering + file dialogs)
• Two input modes:
  • Directory mode: Pick a folder, auto-detect all input files by name/extension
  • File mode: Pick each input individually with native "Browse…" dialogs
• Run metadata: Fields for operator name (run_by) and free-text remarks
• Options panel: Checkboxes for skip_demand_data, skip_spatial_layers, skip_demographics, run_mc_distribution
• Live log streaming: Polls pipeline state every 1s, displays log output in real-time
• Run manifest: After completion, displays results summary (hub counts by tier) and lists all output files with "Open" buttons
• Background execution: Pipeline runs in a daemon thread; UI remains responsive

GUI Frontend (app/gui/)

• index.html: Form layout with sections for run details, input selection, options, and output directory
• app.js: Event handlers for file/folder pickers, directory scanning, run submission, and result rendering
• style.css: Clean, modern UI with cards, buttons, status indicators, and a dark-themed log viewer

Run Logging

• run_log.json: Machine-readable manifest recording:
  • Run ID, timestamps, duration, operator, remarks
  • Input file paths with sizes, modification times, and SHA-256 checksums
  • Configuration flags and output file list
  • Results summary (total hubs, hubs by tier) and success/error status
• run_.log: Streaming text log of all pipeline output

Pipeline Integration

• CompleteHubPipeline.__init__() now accepts optional RunConfig; defaults to default_run_config() for CLI behavior
• All data loading steps (step_1_load_all_data(), etc.) now read from self.config instead of global constants
• Demand file resolution updated to prefer configured file, fall back to legacy paths
• Intermediate and final outputs written to self.config.processed_dir and self.config.results_dir

Documentation

• app/RUN_MODEL_GUI.md: User guide covering installation, running the GUI, input file conventions, and output structure
• README.md: Added section on interactive GUI with quick-start instructions

Notable Implementation Details

• File auto-detection algorithm: Scores candidates by matching hint keywords in filename stem; prefers more specific names (e.g., "nodes") before generic ones (e.g., "lines")
• Backward compatibility: CLI usage unchanged; running python scripts/run_complete_pipeline.py still works with default paths
• Thread-safe logging: GUI uses a lock to safely append log lines from the pipeline thread
• Manifest on failure: Run

https://claude.ai/code/session_01DccAxW3N1TXdepCKsTJfnF