add Agents.md

Author: mmaelicke

AGENTS.md

@@ -0,0 +1,35 @@
+# Simulation Evaluation Tool
+
+## Purpose
+Containerized Python tool for evaluating hydrological simulation performance against observed data using standard metrics (NSE, KGE, R², MSE, RMSE).
+
+## Key Components
+- **Python Core** (`src/`): Data loading, metric calculation, output generation
+- **Svelte Report App** (`src/report/`): Interactive HTML reports with visualizations  
+- **Docker Setup**: Containerized execution following tool-spec standard
+- **Input Data**: CAMELS-DE hydrological catchment data (CSV/Parquet)
+
+## Workflow
+1. Load simulation/observation data from `/in/` using wildcard patterns
+2. Calculate performance metrics for each catchment
+3. Generate CSV/JSON metrics summary
+4. Build interactive HTML report with time series plots
+
+## Technologies
+- **Backend**: Python (pandas, numpy, scipy, sklearn)
+- **Frontend**: SvelteKit, TypeScript, Plotly.js, Tailwind CSS
+- **Containerization**: Docker with tool-spec compliance
+- **Data Processing**: Supports CSV/Parquet, flexible column mapping
+
+## Key Files
+- `run.py`: Main entrypoint and orchestration
+- `evaluation.py`: Core metric calculations (NSE, KGE, etc.)
+- `outputs.py`: Report generation and data compression
+- `tool.yml`: Tool specification and parameter definitions
+- `src/report/`: Svelte application for interactive visualization
+
+## Development Notes
+- Uses json2args for parameter parsing from `/in/input.json`
+- Supports both separate and combined observation/simulation files
+- Generates compressed datasets for web visualization
+- Follows tool-spec container structure (`/in`, `/out`, `/src`)