# Agentic HEC-RAS

**A headless, natural-language-driven, automated modelling workflow for HEC-RAS.**
**Skills + an MCP server** for [Claude Code](https://www.anthropic.com/claude-code), Codex, Hermes, or OpenClaw: describe a goal in plain language and the agent inspects, edits, runs, reads, compares and plots a HEC-RAS model — 1D, 2D or 1D/2D — without ever opening the GUI.

<p>
  <a href="https://github.com/Zhonghao1995/Agentic-HEC-RAS/actions/workflows/ci.yml"><img src="https://github.com/Zhonghao1995/Agentic-HEC-RAS/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <img src="https://img.shields.io/badge/python-3.10%2B-3776AB" alt="Python 3.10+" />
  <img src="https://img.shields.io/badge/HEC--RAS-6.x%20%7C%207.0.1-1F6FEB" alt="HEC-RAS 6.x / 7.0.1" />
  <img src="https://img.shields.io/badge/MCP-1.x%20%7C%202.x-7C3AED" alt="MCP 1.x / 2.x" />
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" />
  <img src="https://img.shields.io/badge/status-experimental-orange" alt="experimental" />
</p>

> Experimental / pre-release. One MCP server (10 tools) + 5 skills, a thin layer over
> [ras-commander](https://github.com/gpt-cmdr/ras-commander) (MIT) and h5py. Verified end to end on
> HEC's official **Muncie** 2D example with HEC-RAS 7.0.1. Sibling of
> [agentic-swmm-workflow](https://github.com/Zhonghao1995/agentic-swmm-workflow) (urban drainage) and
> [Agentic-MIKE-Plus](https://github.com/Zhonghao1995/Agentic-MIKE-Plus) (MIKE+): together they cover
> sewer network → river / 2D flood hydraulics under one agentic pattern.

## Install: just tell your agent

Paste this to your AI coding agent (Claude Code, Codex, Hermes, OpenClaw):

```text
Install "Agentic HEC-RAS" for me: an MCP server + skills to drive HEC-RAS headless.

1. Clone https://github.com/Zhonghao1995/Agentic-HEC-RAS and skim its README.
2. With Python 3.10+:
     python -m venv .venv
     .venv\Scripts\python.exe -m pip install -e .
3. Register with me (Claude Code):
     claude mcp add hec-ras -- "<abs-repo>\.venv\Scripts\python.exe" -m hecras_mcp.server
   (Codex / Hermes / OpenClaw: copy config/mcp.sample.json)
4. Copy skills/* into ~/.claude/skills/, then run scripts/smoke_test.py (should list 10 tools).
5. Tell me which tools need HEC-RAS installed (only ras_run does) and where Ras.exe was found
   (set HECRAS_EXE if it was not).
```

Two install profiles:

- **Read / compare / plot / edit files.** Cross-platform, no HEC-RAS: `pip install -e .` — everything except `ras_run`
  works on any machine that has the `.p##.hdf` results (or the project text files).
- **Run too.** Windows + [HEC-RAS](https://www.hec.usace.army.mil/software/hec-ras/download.aspx) 6.x / 7.0.1
  installed (free download, no license). `Ras.exe` is auto-detected in the default install folder, or set `HECRAS_EXE`.

## Why it matters

- **Natural-language-driven.** "Run the 2D plan with 20 % more inflow and tell me how much the downstream stage rises" — the agent copies the project, edits the `.u##`, runs `Ras.exe -c`, reads the HDF, compares, plots, and writes a manifest.
- **Fully headless.** No GUI, no COM controller: HEC-RAS's own command line (`Ras.exe -c project.prj plan.p##`) inside a copied project folder.
- **MCP-native and portable.** One server speaks the Model Context Protocol; works with Claude Code, Codex, Hermes or OpenClaw via a single config line.
- **HEC-RAS optional for reading.** Results (`.p##.hdf`), comparison and figures need only Python — teammates without HEC-RAS can still analyse.
- **Verification-first.** `ras_run` returns a QA `status` (max WSEL error, volume error %, ERROR / WARNING lines) the skills must gate on; every case ends with a sha256 manifest.
- **Small and testable.** Pure-Python contracts (boundary-table rewriting, QA classification, comparison, manifest) with a HEC-RAS-free unit-test suite in CI; add a tool or skill by dropping in a file.

## How it works

Skills (markdown playbooks) tell the agent *when and how*; the agent calls **MCP tools**; the tools call
ras-commander (project parsing, `.p##` edits, `Ras.exe -c`) and h5py (results). The server never imports
HEC-RAS itself, so it starts anywhere.

```
agent  ->  reads skills/ras-*/SKILL.md  ->  calls MCP tools  ->  ras-commander / h5py  ->  Ras.exe -c  /  .p##.hdf
```

## Tools (one server, `hec-ras`)

| Tool | Does | HEC-RAS |
|---|---|---|
| `ras_project_info` | plans (title, g##/u##, sim window, intervals, cores, results present?), geometries, flow files, boundary conditions (river/reach/RS or 2D BC line, kind, interval, n, peak) | no |
| `ras_project_copy` | copy the whole project folder (terrain / DSS refs stay valid) before any edit or run | no |
| `ras_plan_set` | simulation window, computation / output / mapping interval, cores, short id, title, description, geometry, flow file | no |
| `ras_flow_set_hydrograph` | replace or scale one boundary table (flow / stage / lateral / precipitation / gate), set QMult, change interval | no |
| `ras_run` | `Ras.exe -c` headless run + QA: status, max WSEL error, volume error %, log tail, runtime, HDF path | **yes** |
| `ras_results_summary` | run QA, volume accounting, cross-section peaks, 2D wet cells / max depth, reference lines, units | no |
| `ras_results_timeseries` | one series (cross section, reference line / point, boundary, 2D cell) with peak and timing | no |
| `ras_results_compare` | baseline vs scenario: delta peak / timing / RMSE / NSE / volume, or every cross section ranked by change | no |
| `ras_plot` | hydrograph overlay, max-WSE profile, 2D max-depth map (PNG) | no |
| `ras_manifest_write` | provenance manifest: project, plan, inputs, results, figures with sha256, run QA, edits, tool calls | no |

Five skills orchestrate them: `ras-end-to-end` (the SOP: modes, run directory, hard rules, stop rules, QA gates),
`ras-model`, `ras-runner`, `ras-results`, `ras-audit`.

**Install the skills** into any skills-aware agent (Claude Code, Codex, OpenCode, …) in one command, no clone needed:

```bash
npx skills add Zhonghao1995/Agentic-HEC-RAS      # all 5; add --list to preview, or --skill <name> for one
```

## Demo: Muncie (official 2D example, HEC-RAS 7.0.1)

Baseline vs +20 % upstream inflow, entirely through the tools (`scripts/e2e_muncie.py`): two 24-hour 1D/2D
runs of ~65 s each on 4 cores, downstream peak flow 21,000 → 25,200 cfs (+20.0 %), downstream max stage
938.7 → 940.7 ft (+2.0 ft), 2D area 4,905 → 4,997 wet cells, max depth 20.3 → 20.4 ft.

<p align="center">
  <img src="docs/figs/downstream_flow.png" alt="Downstream flow hydrograph, baseline vs +20% inflow" width="900" />
</p>
<p align="center">
  <img src="docs/figs/max_wse_profile.png" alt="Maximum water surface profile along the White River reach" width="900" />
</p>
<p align="center">
  <img src="docs/figs/max_depth_map.png" alt="Maximum depth map of the 2D Interior Area" width="600" />
</p>

Full evidence (commands, tool returns, and the honest scope boundary) is in **[docs/verification.md](docs/verification.md)**.

## Scope (v0.1) and honest boundaries

- Operates on **existing** HEC-RAS projects: inspect, edit boundaries / plan settings, run, read, compare, plot, audit.
- Building a new model (terrain, 2D mesh, cross sections, infiltration layers, structures) still needs RAS Mapper / the GUI.
- Runs need Windows + HEC-RAS. HEC-RAS 7.0.1 ships Linux compute engines (`RasUnsteady`, run via WSL) but they need
  Windows-side preprocessing; they are not wired into `ras_run` yet.
- HEC-RAS may show its *Terms and Conditions for Use* form on headless launches; `ras_run` accepts it for you
  (`accept_tcu`, default true — read the terms at hec.usace.army.mil/software/hec-ras) and kills runs after `timeout_s`.
- Gridded (DSS) precipitation and steady-flow (`.f##`) profiles are read but not edited.

## Development

```bash
pip install -e ".[dev]"
pytest                          # ~3 s, no HEC-RAS needed
python scripts/smoke_test.py    # tool discovery + real stdio MCP round-trip
python scripts/call_tool.py --list
python scripts/call_tool.py ras_results_summary "{\"hdf\": \"C:/models/Muncie/Muncie.p03.hdf\"}"
```

The tests pin the `.u##` boundary-table writer (fixed-width, touching fields, count line, CRLF), the QA
classifier, the comparison metrics, the manifest, tool discovery and the server's failure shape. Add a tool
or skill by dropping a file under `hecras_mcp/tools/` or `skills/` (auto-discovered), and ship a test with it.

## License

MIT © 2026 Zhonghao Zhang, University of Victoria. Built on ras-commander (MIT), h5py, pandas, matplotlib and the
Model Context Protocol. HEC-RAS is developed and distributed free of charge by the U.S. Army Corps of Engineers
Hydrologic Engineering Center; it is not open source and is not redistributed here.