Metadata-Version: 2.4
Name: hydromind
Version: 4.3.3
Summary: HydroMind: An AI-powered platform for advanced hydrological modeling, analysis, and data-driven water resource management.
Author-email: Funzzz <funz@hhu.edu.cn>
License: PolyForm-Strict-1.0.0
Requires-Python: <3.15,>=3.13
Description-Content-Type: text/markdown
Requires-Dist: xarray>=2026.4.0
Requires-Dist: lightning>=2.6.1
Requires-Dist: torchmetrics>=1.9.0
Requires-Dist: numpy>=2.3.5
Requires-Dist: h5netcdf>=1.7.3
Requires-Dist: h5py>=3.15.0
Requires-Dist: scipy>=1.15.2
Requires-Dist: sqlalchemy>=2.0.40
Requires-Dist: pandas>=3.0.0
Requires-Dist: networkx>=3.4.2
Requires-Dist: streamlit>=1.62.0
Requires-Dist: altair>=6.1.0
Requires-Dist: pillow>=12.2.0
Requires-Dist: starlette>=1.0.1
Requires-Dist: uvicorn>=0.34.0
Requires-Dist: python-calamine>=0.3.2
Requires-Dist: triton; sys_platform == "linux"
Requires-Dist: pydantic>=2.12.4
Requires-Dist: psutil>=7.2.2
Requires-Dist: agno<4,>=3.0.0
Requires-Dist: anthropic>=0.72.0
Requires-Dist: google-genai>=1.53.0
Requires-Dist: openai>=2.8.1
Requires-Dist: typer>=0.20.0
Requires-Dist: uvloop>=0.22.1; sys_platform == "linux"
Requires-Dist: rich>=15.0.0
Requires-Dist: dask>=2026.3.0
Requires-Dist: tqdm>=4.67.3
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: rasterio>=1.5.0
Requires-Dist: pyproj>=3.7.2
Requires-Dist: shapely>=2.1.2
Requires-Dist: geopandas>=1.1.3
Requires-Dist: pyogrio>=0.12.1
Requires-Dist: pydeck>=0.9.2
Requires-Dist: fastapi>=0.136.3
Requires-Dist: markdown>=3.10.2
Requires-Dist: pypdf>=6.13.0
Requires-Dist: python-docx>=1.2.0
Requires-Dist: opentelemetry-sdk>=1.42.1
Requires-Dist: openinference-instrumentation-agno>=0.1.35
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: semantic-text-splitter>=0.32.0
Requires-Dist: alipay-sdk-python>=3.7.1160
Requires-Dist: httpx>=0.28.1
Provides-Extra: cpu
Requires-Dist: torch>=2.9.0; extra == "cpu"
Provides-Extra: cuda
Requires-Dist: torch>=2.9.0; extra == "cuda"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.9.0; extra == "viz"
Provides-Extra: reformer
Requires-Dist: reformer-pytorch>=1.4.4; extra == "reformer"

# HydroMind

![logo](https://bed.funzzz.top/file/pictures/1763215764988_hydromind-ai-in-hydrology.svg)

**HydroMind helps you prepare hydrological data, train and evaluate machine-learning models, make predictions, and inspect the results.** Most users work in one of two ways: open the Mind application in a browser, or use HydroMind from Python. Mind provides guided pages and charts. Python gives you direct access to data, models, and evaluation functions when you want to write code or build a repeatable analysis.

[![Version](https://img.shields.io/badge/version-3.4.0-blue.svg)](https://github.com/CMajorChords/HydroMind)
[![Python](https://img.shields.io/badge/python-3.13--3.14-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-PolyForm%20Strict%201.0.0-red.svg)](LICENSE)

[中文说明](README.zh-CN.md) · [What you can do](#what-you-can-do) · [Start with Mind](#start-with-mind) · [Start with Python](#start-with-python) · [Documentation](#documentation)

## What you can do

Suppose you have daily rainfall, temperature, and streamflow observations. HydroMind can help you organize those values with their dates, basin IDs, variable names, and units; use them to train, validate, test, or run a hydrological model; and inspect the resulting metrics, logs, trained Checkpoint, or prediction file. The same tools also support model comparison, table recognition from scanned records, watershed extraction, and deployment of a reviewed model to a trusted application. Each focused guide states the required input, the action to take, the result to expect, and the checks that still belong to you.

HydroMind performs the computation you request, but it does not choose the scientific question or certify a model for scientific or operational use. Before trusting a result, you still need to check the data source, units, missing values, time split, availability of forecast inputs, evaluation rules, and the conditions under which the model will be used. A completed task means the computation finished and its outputs are available for review. It does not by itself show that the model is hydrologically sound or transferable to another basin or period.

## Start with Mind

Mind is the browser application and the simplest place to explore HydroMind. After installation and workspace initialization, start it from the project directory:

```bash
uv run hydro mind
```

The terminal prints a local address, normally beginning with `http://localhost:8501`. Keep the terminal running, open the printed address in a browser, and choose the page that matches your task from the top navigation. Begin with the Documentation page if you are not sure where to go. Use the Modeling pages to prepare data, describe a training or prediction task, follow its progress, and inspect its outputs. Use HydroAI inside Mind when you already have a clear goal and want to request supported modeling operations in ordinary language.

Mind keeps related task settings and results together, so you can leave a long computation running and return later to inspect its state. You do not need to know Python to use these guided pages. You do, however, need to know what your variables mean and what result you expect. Mind will show missing or incompatible inputs, but it cannot infer the scientific meaning of an unexplained table or decide whether a metric supports your conclusion.

## Start with Python

Use the Python interface when you want to prepare data in a script, develop or inspect a model, evaluate predictions, or connect HydroMind to other scientific code. The example below opens a prepared NetCDF file as HydroMind data and prints the dimensions, variables, and units that should be checked before modeling:

```python
from hydromind.data import read_netcdf

data = read_netcdf("hydrodata.nc")

print(dict(data.sizes))
for name in data.data_vars:
    print(name, data[name].dims, data[name].attrs.get("units", "unit missing"))
```

The output should list the time and basin dimensions present in `hydrodata.nc`, followed by every variable, the dimensions it uses, and its unit. A missing unit is printed explicitly instead of being guessed. The [HydroData guide](docs/modeling/hydrodata.md) shows how to construct this file from checked source data, and the [Python modeling pages](docs/modeling/index.md) explain how data windows, model inputs, training, prediction, and evaluation fit together.

Direct calls to `hydromind.data`, `hydromind.model`, and `hydromind.eval` behave like ordinary Python code: your script decides what to run and what to save. When you want HydroMind to keep a submitted task, its status, and its outputs together so that Mind can display them later, use Mind or the recorded workspace operations documented in the modeling workflow.

## Install the distributed Wheel

HydroMind is installed from the protected Wheel supplied by its distributor, not by cloning this repository. Its formal build and product support target is Ubuntu 24.04 x86-64 with free-threaded CPython 3.14t, and its filename contains `cp314-cp314t-manylinux_2_34_x86_64`. The `manylinux_2_34` part states the glibc compatibility baseline; it neither identifies nor restricts the Linux distribution. Keep the Wheel at a stable absolute path, confirm that the CPU architecture and Python ABI match, and use the website account that owns the license intended for this computer.

Create a clean `uv` project and replace the example path with the absolute path of the Wheel you received:

```bash
uv init --bare --python 3.14t hydromind-workspace
cd hydromind-workspace
uv python pin 3.14t
uv add '/absolute/path/to/hydromind-customer.whl'
uv run hydro init
```

`hydro init` is an online server-authentication step, not a local configuration shortcut. It contacts the HydroMind server, prints a complete confirmation URL and a six-digit code, and waits while you sign in with the licensed account. The server checks the account, license, and computer binding; initialization continues only after you confirm the matching code within 10 minutes and the server accepts the binding. After the command finishes, start the browser application from the same workspace with `uv run hydro mind` and open the URL printed by the terminal. Every later HydroMind process must still be able to reach the official server for authorization checks, although the computer does not need another manual confirmation while its license and binding remain valid. The [HydroMind Overview](docs/overview/index.md) gives the complete compatibility, binding, expiry, and first-launch checks.

## Develop the repository from source

The commands in this section are only for contributors who are changing or testing the HydroMind repository. They do not install the customer product and do not replace the protected-Wheel and server-authentication route above. Repository development supports Python 3.13 or 3.14 on Linux, WSL, and Windows; use the dependency set that matches the development machine.

```bash
git clone https://github.com/CMajorChords/HydroMind.git
cd HydroMind
uv sync --extra cuda
uv run --no-sync hydro --help
```

Use `uv sync --extra cpu` instead when isolating CUDA dependency problems or developing on a CPU-only host. The repository's [Agent instructions](AGENTS.md) and focused validation commands own the rest of the contributor workflow; customer workspaces should continue to use the Wheel commands without `--no-sync`.

## Other ways to operate HydroMind

The `hydro` command-line program is useful for exact, repeatable workspace operations. It supports the same saved modeling work shown in Mind, but it is not a third product that beginners must learn before using the browser or Python. Start with `uv run hydro --help`, then read the relevant leaf command help before using an option. Compatible external coding Agents can follow HydroMind's Agent Skills to choose and verify these public operations. Research is a separate, optional Agent workflow for a study that must continue across conversations or become a paper; it is not required for ordinary modeling and is not another training backend.

## Documentation

| What you want to do | Read |
| --- | --- |
| Understand the product and choose Mind or Python | [HydroMind Overview](docs/overview/index.md) |
| Complete a first guided modeling task | [HydroMind Modeling](docs/modeling/index.md) |
| Train, predict, and evaluate in Python | [Train and predict with the Python interface](docs/modeling/python-workflow.md) |
| Use natural language inside Mind | [HydroAI](docs/hydroai/index.md) |
| Extract reviewed data from scanned tables | [Table recognition](docs/ocr/index.md) |
| Delineate a basin and stream network | [Watershed Extraction](docs/watershed/index.md) |
| Serve a reviewed model to a trusted application | [Deployment](docs/deployment/index.md) |
| Continue a study with a compatible external Agent | [HydroMind Research](docs/research/index.md) |
| Read explanations of hydrological modeling papers | [Scientific reading](docs/blog/index.md) |

HydroMind uses the [PolyForm Strict License 1.0.0](LICENSE). If you use it in research, cite the [repository](https://github.com/CMajorChords/HydroMind).
