aihydro-tools

aihydro-tools

Stop writing plumbing. Give AI agents real hydrological superpowers.

---

What is aihydro-tools?

aihydro-tools is the Python backbone of the AI-Hydro platform. It turns a conversation with an AI agent into real hydrological computation — watershed delineation, streamflow retrieval, signature extraction, terrain analysis, and model calibration — with full structured provenance recorded automatically at every step.

144 validated, tiered tools are exposed via the Model Context Protocol (MCP), the open standard for agent-tool communication. Any AI model that supports MCP — Claude, GPT, Gemini — can call these tools directly, without writing a single line of processing code. And because aihydro-tools is built as a community platform, any researcher can register domain-specific tools (flood frequency, sediment transport, groundwater, remote sensing) via Python entry points, extending the ecosystem without touching the core.

---

Quick Start

# Install
pip install aihydro-tools[all]

# Verify
aihydro-mcp --diagnose

# Run the server
aihydro-mcp

The AI-Hydro VS Code extension auto-detects aihydro-mcp on startup — no manual configuration needed.

---

Built-in Tools

Analysis Tools

Project, Literature & Researcher Memory

Community plugins can add further tools via the entry-point system (see below).

---

Data Sources

All data is fetched from authoritative federal sources:

• USGS NWIS — daily streamflow via dataretrieval (official USGS Python client)
• NHDPlus / NLDI — watershed delineation via pynhd
• GridMET — climate forcing via pygridmet
• 3DEP — DEM and terrain analysis via py3dep
• NLCD — land cover classification
• POLARIS — soil properties
• CAMELS-US — catchment attributes via pygeohydro

---

Memory & Provenance

AI-Hydro maintains a three-tier memory hierarchy so research context survives between conversations, sessions, and projects.

HydroSession — per-gauge state at ~/.aihydro/sessions/<gauge_id>.json. Expensive computations (watershed delineation, multi-year streamflow downloads) are done once and reused across days or weeks. Every result carries structured provenance metadata — data source, parameters, timestamp — making reproducibility a natural byproduct rather than a documentation chore.

ProjectSession — project-scoped state at ~/.aihydro/projects/<name>/project.json. Organises research across multiple gauges, topics, or datasets. Supports cross-session experiment search, a timestamped journal, and literature indexing.

ResearcherProfile — a persistent persona at ~/.aihydro/researcher.json. Built up from agent-researcher interactions over time: expertise areas, preferred models, active projects, and accumulated observations. Injected into every conversation automatically so the agent knows who it is working with.

---

Scientific Trust

AI-Hydro goes beyond computation — it records why results should be believed and what remains uncertain.

Tool Tier System

Every tool is assigned to one of three evidence tiers (machine-readable via get_tool_tier(name)):

Tier 1 tools (watershed delineation, signatures, TWI, CN, model training) fire registered post-run validators automatically. Every Tier 1 result carries:

• quality_flags — list of validator outcomes (pass/warning/fail with severity)
• _run_id — stable evidence-binding key for linking claims to specific runs

Scientific Ledger

Results become actionable knowledge through the ledger:

1. draft_claim_from_run(session_id, run_id, metric_ref) — reads the run log for any Tier 1 tool call and returns a claim template with evidence_spans pre-populated. The agent authors only the scientific interpretation.
2. add_claim(..., evidence_spans=[...]) — records the claim. EvidenceSpan ties the claim to a run, paper, or dataset with typed attribution (source_type, source_id, metric_ref).
3. promote_claim_to_registry(..., researcher_approved=True) — resolves retained evidence before promotion. It requires an eligible status, limitations, a single-use human approval record for the claim's current revision and retained evidence (channel cli_same_user: it stops unintended self-approval, not a same-user process that forges it; the researcher runs aihydro-approve <session_id> <claim_id> in a terminal; researcher_approved=True alone is refused with APPROVAL_REQUIRED), finite referenced metrics, no recorded failed checks, and matching persisted uncertainty for metric-scoped empirical or negative-result claims. An agent's uncertainty acknowledgement alone is insufficient.

New registry entries fingerprint retained records. Missing/changed evidence and unverifiable legacy snapshots are flagged for review by check_registry_staleness. Promotion reports record integrity separately from unverified scope alignment, method validity and claim-text alignment. See the evidence contract for supported references, uncertainty fields, migration behavior and remaining scientific limits.

The extension's research panels consume the versioned persisted snapshot through the connected MCP backend.

Verified Knowledge

Built-in knowledge entries can be marked verified: true in the YAML registry (e.g., metric.kge, variable.streamflow, dataset.usgs_nwis). Verified entries require scientific_justification — not just overrides + override_reason — in workspace override files, ensuring overrides of peer-reviewed conventions are deliberate and documented.

Retrieve all verified entries programmatically:

from ai_hydro.knowledge.loader import get_verified_knowledge
verified = get_verified_knowledge()  # {"variables": [...], "metrics": [...], "datasets": [...]}

---

Quality Assurance

Automatic Post-Run Validation

Tier 1 tools fire registered validators automatically (no agent action needed). Currently active wiring:

• extract_hydrological_signatures → check_water_balance_consistency
• fetch_streamflow_data → check_unit_consistency (expected: m³/s)

Validators never raise — failures appear in quality_flags without crashing the tool. Register additional validators via:

from ai_hydro.mcp.enforcement import register_post_validator
register_post_validator("my_tool", my_validator_fn, lambda sid: {"session_id": sid})

aihydro-bench

A deterministic fixture benchmark suite (bench/tasks.yaml, ~26 tasks) verifies every core computation path without live network calls. Tasks span all tiers:

• Group A–C: validators, compute functions, and their edge cases
• Group D–G: ledger gates, knowledge registry guards, conflict resolution
• Group H–J: enforcement layer, verified namespace, claim coupling (draft → add)

Run it:

pytest tests/test_bench.py -m bench -v       # fast fixture suite (no network)
pytest tests/test_bench.py -m bench_live -v  # live USGS calls (nightly CI only)

---

Extending with Plugins

aihydro-tools is a platform, not a closed product. Any researcher can package domain knowledge as a plugin and make it immediately available to every AI agent that uses AI-Hydro — flood frequency analysis, sediment transport, groundwater modelling, remote sensing workflows, or anything else the core doesn't yet cover.

Entry-point plugins load into the same process with full access to HydroSession and cached data:

# In your package's pyproject.toml
[project.entry-points."aihydro.tools"]
my_tool = "my_package.tools:my_tool_function"

Install the package, restart the server, and the tool is automatically discovered — no changes to the core required.

Standalone MCP servers let you build fully independent toolkits with their own dependencies, registered alongside the core ai-hydro server.

See the Plugin Guide for complete walkthroughs of both paths, the data contract, and session integration.

---

Use as a Python Library

You don't need an AI agent to benefit from aihydro-tools. Every tool is a regular Python function — import and call directly in scripts, notebooks, or pipelines:

from ai_hydro.analysis.watershed import delineate_watershed
from ai_hydro.data.streamflow import fetch_streamflow_data
from ai_hydro.analysis.signatures import extract_hydrological_signatures

# Delineate a watershed
ws = delineate_watershed("01031500")
print(f"Watershed area: {ws.data['area_km2']} km2")

# Fetch streamflow
sf = fetch_streamflow_data("01031500", start_date="2015-01-01", end_date="2024-12-31")
print(f"Records: {len(sf.data['dates'])} days")

# Extract signatures
sigs = extract_hydrological_signatures("01031500")
print(f"Baseflow index: {sigs.data['baseflow_index']}")

All functions return HydroResult objects with .data (dict) and .meta (provenance metadata).

---

Installation Details

Extras

Install only what you need:

PATH Troubleshooting

If aihydro-mcp is not found after install, pip placed it outside your PATH:

Universal fallback: python -m ai_hydro.mcp works regardless of PATH. The AI-Hydro extension auto-detects both the console script and the module fallback.

---

Extending with Plugins

AI-Hydro uses Python entry points for a clean plugin system. Community packages can contribute any of four capability layers without modifying the core:

Example: add a custom tool

# my_hydro_pkg/tools.py
from ai_hydro.core.types import HydroResult, HydroMeta, DataSource

def compute_soil_moisture(session_id: str, workspace_dir: str = None) -> dict:
    """Estimate soil moisture from session forcing data."""
    # ... your computation ...
    result = HydroResult(data={...}, meta=HydroMeta(tool="compute_soil_moisture", ...))
    return result.to_dict()

# pyproject.toml
[project.entry-points."aihydro.tools"]
compute_soil_moisture = "my_hydro_pkg.tools:compute_soil_moisture"

After pip install my-hydro-pkg, the tool appears automatically in list_available_tools() on the next MCP server restart — no changes to aihydro-tools required.

Example: add a knowledge card

[project.entry-points."aihydro.knowledge"]
my_lib = "my_hydro_pkg.knowledge:get_refs_dir"

where get_refs_dir() returns a Path to a directory of *.json cards (same schema as the built-in cards in ai_hydro/knowledge/library_refs/).

Example: add a workflow skill

[project.entry-points."aihydro.skills"]
my_skills = "my_hydro_pkg.skills:get_skills_dir"

where get_skills_dir() returns a Path to a directory of *.md skill files (YAML frontmatter + markdown body). Skills appear in list_skills() and are loadable via load_skill(name).

Example: advertise a CLI

[project.entry-points."aihydro.clis"]
my_tool = "my_hydro_pkg.aihydro.cli_descriptor:descriptor"

where descriptor() returns {name, binary, description, help_subcommand}. The CLI appears in list_relevant_clis().

See the Plugin Guide for full walkthroughs.

---

Contributing

The most impactful contributions to AI-Hydro are new domain tools — knowledge that currently lives in papers and custom scripts, packaged so any AI agent can use it. High-priority areas include flood frequency analysis, sediment transport, groundwater modelling, remote sensing workflows (MODIS, Landsat, SAR), snow hydrology, and water quality.

You don't need to fork the core. Write a Python package, register an entry point, publish to PyPI. That's it.

• Contributing Guide — Development setup, code style, testing
• Plugin Guide — Step-by-step walkthroughs for both contribution paths

---

Citation

If you use aihydro-tools in your research, please cite:

@software{aihydro_tools_2026,
  title   = {aihydro-tools: Python MCP Server for AI-Automated
             Hydrological Research},
  author  = {Galib, Mohammad and Merwade, Venkatesh},
  year    = {2026},
  version = {1.6.0},
  doi     = {10.5281/zenodo.19597589},
  url     = {https://doi.org/10.5281/zenodo.19597589}
}

For the VS Code extension, cite:

@software{aihydro_extension_2026,
  title   = {AI-Hydro: An Open Platform for End-to-End AI-Automated
             Hydrological Research (VS Code Extension)},
  author  = {Galib, Mohammad and Merwade, Venkatesh},
  year    = {2026},
  version = {0.1.3},
  doi     = {10.5281/zenodo.19597664},
  url     = {https://doi.org/10.5281/zenodo.19597664}
}

---

Links

• Documentation: ai-hydro.github.io/AI-Hydro
• AI-Hydro Extension: github.com/AI-Hydro/AI-Hydro
• PyPI: pypi.org/project/aihydro-tools
• YouTube: AI-Hydro Channel
• X / Twitter: @aihydro
• Issues: github.com/AI-Hydro/aihydro-tools/issues

---

License

Apache 2.0 © 2026 Mohammad Galib