Plugin Overview¶

AI-Hydro is a platform, not a closed product. The most impactful contributions are new domain tools and knowledge layers that make trusted hydrology workflows usable by AI agents.

If you want to contribute a plugin, start here, then continue to the full Contributing Guide.

Three Plugin Paths¶

Priority Contribution Areas¶

The best contributions are the ones that map cleanly onto AI-Hydro's current architecture and can be exposed as reliable tools or knowledge cards.

Strong candidates for tool plugins or standalone servers¶

• Flood frequency analysis — L-moments, GEV fitting, return period estimation
• Groundwater — well analysis, aquifer characterisation, recharge estimation
• Water quality — nutrient loading, temperature modelling, DO
• Snow hydrology — SWE retrieval, melt modelling, snowpack depletion curves
• Hydraulic modelling — 1D/2D flood mapping, HEC-RAS integration
• Remote sensing workflows — hydrology-relevant retrievals that can be wrapped into clear computational steps

Strong candidates for knowledge plugins¶

• swmmio
• hecras
• nlmod
• oggm
• snowpack
• pywr

What makes a contribution especially valuable¶

• It wraps a method that researchers already trust but agents cannot yet use reliably.
• It has clear inputs, outputs, units, and provenance expectations.
• It reduces repeated data wrangling or brittle script glue.
• It helps agents use existing domain libraries correctly.

Getting Started¶

→ Paths B/C: Entry-Point & Knowledge Plugins — fastest to implement, recommended for single tools or library reference cards
→ Path A: Standalone MCP Server — for full toolkits with heavy dependencies
→ Data Contract — HydroResult / HydroMeta spec all tools must follow

Plugin Discovery¶

Tool plugins (aihydro.tools)¶

Entry-point tool plugins are discovered automatically when the aihydro-mcp server starts:

# ai_hydro/mcp/registry.py
from importlib.metadata import entry_points

def discover_tools():
    for ep in entry_points(group="aihydro.tools"):
        tool_fn = ep.load()
        mcp.tool()(tool_fn)  # registers with FastMCP

Install a community package → restart the server → the tool appears in list_available_tools(). No changes to the core required.

Knowledge plugins (aihydro.knowledge)¶

Knowledge plugins contribute library reference cards — structured JSON files covering field-name gotchas, API quirks, unit conventions, and copy-paste patterns for a specific library. These feed the get_library_reference tool.

# ai_hydro/mcp/registry.py
def discover_knowledge():
    for ep in entry_points(group="aihydro.knowledge"):
        get_dir = ep.load()
        ref_dir = get_dir()   # returns pathlib.Path to *.json files

A knowledge plugin exports one function that returns a Path to a directory of JSON reference files:

from pathlib import Path

def get_refs_dir() -> Path:
    return Path(__file__).parent / "library_refs"

Register it in pyproject.toml:

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

Each JSON file in library_refs/ follows the schema used by the built-in cards:

{
  "library": "vic_model",
  "version_tested": "5.x",
  "purpose": "Variable Infiltration Capacity macroscale hydrological model",
  "field_mappings": {
    "run_vic": {
      "forcing_param": "path to meteorological forcing files (NetCDF)",
      "note": "Forcing files must have vars: prec, tmax, tmin, wind"
    }
  },
  "gotchas": [
    "VIC outputs are in local time — convert to UTC before merging with NWIS data.",
    "State files are binary — do not try to read them as text."
  ],
  "common_patterns": {
    "run_with_forcings": "from vic import VIC\nmodel = VIC(params_file='params.nc')\nmodel.run(forcings_dir='./forcings/', start='2000-01-01', end='2020-12-31')"
  }
}

Install the plugin → restart the server → get_library_reference("vic_model") returns the card. The agent can call this before writing any script that uses the library.