HBV-Lab 1.4.0__tar.gz → 1.4.2__tar.gz

{hbv_lab-1.4.0 → hbv_lab-1.4.2}/HBV_Lab/__init__.py

@@ -24,7 +24,7 @@ from .soil import soil_routine
 from .response import response_routine_two_tanks
 from .routing import route_with_maxbas
 
-__version__ = "1.4.0"
+__version__ = "1.4.2"
 
 __all__ = [
     "HBVModel",

{hbv_lab-1.4.0 → hbv_lab-1.4.2}/HBV_Lab/mcp_server.py

@@ -140,6 +140,12 @@ def load_data(
     optional but required for calibration, uncertainty analysis and performance
     metrics. Dates use ``date_format`` (e.g. '%Y%m%d' for 19810101). ``warmup_end`` /
     ``start_date`` / ``end_date`` are optional date filters (same format).
+
+    Potential ET may be given as a full daily series OR as exactly 12 values (monthly
+    means, the HBV-light convention) — in the latter case it is **expanded to a daily
+    series automatically**. The return reports ``pet_handling`` so you know which path
+    was taken, plus a ``data_quality`` summary (valid/missing counts and min/max per
+    column) so you don't have to open the file to sanity-check the inputs.
     """
     import pandas as pd
 
@@ -151,6 +157,9 @@ def load_data(
     else:
         df = pd.read_csv(file_path)
 
+    # PET in the raw file: 12 non-NaN values => monthly means (will be expanded daily)
+    raw_pet_valid = int(df[pet_column].notna().sum()) if pet_column in df.columns else 0
+
     model.load_data(
         data=df,
         date_column=date_column,
@@ -163,6 +172,36 @@ def load_data(
         start_date=(start_date or None),
         end_date=(end_date or None),
     )
+
+    # Per-column data-quality summary over the loaded (filtered) window
+    data_quality = {}
+    col_map = {
+        "precipitation": precip_column,
+        "temperature": temp_column,
+        "potential_et": pet_column,
+        "observed_discharge": (obs_q_column or None),
+    }
+    for label, col in col_map.items():
+        if col and col in model.data.columns:
+            s = model.data[col]
+            has = bool(s.notna().any())
+            data_quality[label] = {
+                "valid": int(s.notna().sum()),
+                "missing": int(s.isna().sum()),
+                "pct_missing": round(float(s.isna().mean() * 100), 1),
+                "min": round(float(s.min()), 3) if has else None,
+                "max": round(float(s.max()), 3) if has else None,
+            }
+
+    # How PET was interpreted
+    pet_in_data = pet_column in model.data.columns
+    if raw_pet_valid == 12:
+        pet_handling = "expanded_from_12_monthly_means"
+    elif pet_in_data and bool(model.data[pet_column].notna().all()):
+        pet_handling = "daily_series"
+    else:
+        pet_handling = "sparse_or_missing"
+
     return {
         "model_id": model_id,
         "n_timesteps": int(len(model.data)),
@@ -170,6 +209,8 @@ def load_data(
         "end_date": str(model.end_date),
         "time_step": model.time_step,
         "has_observed_discharge": bool(obs_q_column),
+        "pet_handling": pet_handling,
+        "data_quality": data_quality,
     }
 
 
@@ -372,10 +413,12 @@ async def calibrate(
     elif "iteration" in message.lower() or "maxiter" in message.lower():
         status = "hit_iteration_budget"
         guidance = (
-            "Hit the iteration budget; still improving - call calibrate again to "
-            "continue (it resumes from the current parameters)."
+            "Used the full iteration budget and the objective is still improving - "
+            "call calibrate again to continue (it resumes from the current parameters)."
             if still_improving
-            else "Hit the iteration budget but the objective has plateaued; likely converged."
+            else "Used the full iteration budget and the objective has plateaued "
+            "(improvement < 1e-3 over recent iterations); further iterations are "
+            "unlikely to help much. Stop here, or widen ranges if parameters are at_bound."
         )
     else:
         status, guidance = "failed", f"Optimizer stopped without converging: {message}"
@@ -416,15 +459,23 @@ def evaluate_uncertainty(
     objective: str = "NSE",
     save_best: int = 10,
     seed: int = 42,
+    output_file: str = "",
 ) -> dict:
     """Monte-Carlo uncertainty analysis (requires obs data loaded).
 
-    Samples the parameter ranges ``n_runs`` times and keeps the ``save_best`` runs.
-    Returns the best vs. current performance; full prediction intervals stay in the
-    model and can be persisted with save_results.
+    Samples the parameter ranges ``n_runs`` times and keeps the ``save_best`` runs, then
+    forms a 95% prediction band from them. Returns diagnostics: the 95% band
+    ``coverage`` (fraction of observations inside the band), ``mean_band_width``, and the
+    per-parameter posterior **quantiles** (p5/p25/p50/p75/p95) across the best sets.
+
+    If ``output_file`` is given, the full **per-timestep prediction band** is written to
+    that CSV (Date, Observed, Calibrated, BestRun, Q5, Q95) — this is the band itself,
+    ready to plot. Sampling is uniform over the parameter ranges (this is parameter, not
+    predictive, uncertainty).
     """
     model = _get(model_id)
     import numpy as np
+    import pandas as pd
 
     out = model.evaluate_uncertainty(
         n_runs=n_runs,
@@ -448,17 +499,36 @@ def evaluate_uncertainty(
     else:
         coverage_95 = mean_band_width = None
 
-    # Per-parameter posterior ranges across the best parameter sets
+    # Per-parameter posterior quantiles across the best parameter sets
     posterior: dict = {}
     for s in out["best_parameter_sets"]:
         for params in s["parameters"].values():
             for name, info in params.items():
-                posterior.setdefault(name, []).append(info["default"])
-    posterior_ranges = {
-        name: {"min": round(float(min(v)), 4), "max": round(float(max(v)), 4)}
+                posterior.setdefault(name, []).append(float(info["default"]))
+    parameter_posteriors = {
+        name: {f"p{p}": round(float(np.percentile(v, p)), 4) for p in (5, 25, 50, 75, 95)}
         for name, v in posterior.items()
     }
 
+    # Optionally write the per-timestep prediction band to CSV
+    band_file = None
+    if output_file:
+        band = pd.DataFrame()
+        if "dates" in df.columns:
+            band["Date"] = df["dates"].values
+        band["Observed"] = df["observed"].values
+        if "original" in df.columns:
+            band["Calibrated"] = df["original"].values
+        if "best_1" in df.columns:
+            band["BestRun"] = df["best_1"].values
+        band["Q5"] = df["q5"].values
+        band["Q95"] = df["q95"].values
+        out_dir = os.path.dirname(output_file)
+        if out_dir:
+            os.makedirs(out_dir, exist_ok=True)
+        band.to_csv(output_file, index=False)
+        band_file = os.path.abspath(output_file)
+
     return {
         "model_id": model_id,
         "objective": objective,
@@ -468,7 +538,9 @@ def evaluate_uncertainty(
         "current_performance": round(float(out["original_performance"]), 4),
         "coverage_95": coverage_95,          # fraction of observations inside the 95% band
         "mean_band_width": mean_band_width,  # mean (q95 - q5), mm/day
-        "parameter_posterior_ranges": posterior_ranges,
+        "parameter_posteriors": parameter_posteriors,  # p5/p25/p50/p75/p95 per parameter
+        "band_file": band_file,              # per-timestep band CSV, if output_file given
+        "uncertainty_type": "parameter",     # uniform parameter sampling (not predictive)
     }
 
 

{hbv_lab-1.4.0 → hbv_lab-1.4.2/HBV_Lab.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: HBV_Lab
-Version: 1.4.0
-Summary: An intuitive, object-oriented and user-friendly Python implementation of a lumped conceptual HBV hydrological model for educational and research purposes.
+Version: 1.4.2
+Summary: An agentic, object-oriented Python implementation of a lumped conceptual HBV hydrological model — with calibration, uncertainty analysis, and a built-in MCP server that lets AI agents drive the workflow.
 Home-page: https://github.com/abdallaox/HBV_python_implementation
 Author: Abdalla Mohammed
 Author-email: abdalla.mohammed.ox@gmail.com
 License: MIT
-Keywords: hydrology HBV-model rainfall-runoff hydrological-modelling
+Keywords: hydrology HBV-model rainfall-runoff hydrological-modelling MCP model-context-protocol agent agentic LLM
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -39,9 +39,9 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# HBV_Lab
+# HBV_Lab — an agentic HBV hydrological model with an MCP server
 
-**An intuitive, object-oriented Python implementation of a lumped conceptual HBV rainfall–runoff model, with built-in calibration and uncertainty analysis.**
+**An intuitive, object-oriented Python implementation of a lumped conceptual HBV rainfall–runoff model — with built-in calibration and uncertainty analysis, and a Model Context Protocol (MCP) server that lets AI agents drive the whole workflow.**
 
 [![PyPI version](https://img.shields.io/pypi/v/HBV_Lab.svg)](https://pypi.org/project/HBV_Lab/)
 [![Python versions](https://img.shields.io/pypi/pyversions/HBV_Lab.svg)](https://pypi.org/project/HBV_Lab/)
@@ -59,6 +59,11 @@ full model is wrapped in a single `HBVModel` object that handles data loading, s
 calibration, uncertainty analysis, plotting, and persistence. It is well suited to research
 prototyping, method development, and hydrology education.
 
+**It is also agent-ready:** a built-in [MCP](https://modelcontextprotocol.io/) server exposes the
+model as tools, so an AI agent (Claude Code, Claude Desktop, or any MCP client) can build, calibrate,
+validate and run uncertainty analysis on HBV models through natural language — see
+[Use it as an MCP server](#use-it-as-an-mcp-server-for-ai-agents).
+
 > **Scope at a glance:** lumped (single-cell, spatially averaged) · conceptual · daily time step ·
 > requires precipitation, temperature and potential evapotranspiration as input · 14 calibratable
 > parameters. Please read [Scope, Assumptions & Limitations](#scope-assumptions--limitations) before
@@ -68,6 +73,8 @@ prototyping, method development, and hydrology education.
 
 ## Features
 
+- **Agent-ready MCP server** — drive the full *create → load → calibrate → validate → uncertainty*
+  workflow from an AI agent over stdio or HTTP, with live calibration progress and structured results.
 - **Complete HBV structure** — snow, soil, groundwater response (two reservoirs, three runoff
   components) and `MAXBAS` triangular routing.
 - **Object-oriented API** — one `HBVModel` object holds data, parameters, states and results.
@@ -197,6 +204,12 @@ Install once:
 pip install "HBV_Lab[mcp]"
 ```
 
+> **Upgrading:** stop/close the MCP client (and any running `hbv-mcp` process) **before**
+> upgrading — a running server holds `hbv-mcp.exe` open on Windows, so an in-place
+> `pip install -U` can fail with a file-lock error. After upgrading, **fully restart the
+> client** (or remove and re-add the server) so it re-discovers the tool list; clients fetch
+> tools only once per connection, so upgrading mid-session leaves them showing the old tools.
+
 #### Option A — local (stdio)
 
 No need to start anything yourself; the agent runs `hbv-mcp` for you. Just add it to your client's
@@ -271,9 +284,16 @@ inspect the improving metric, and decide whether to keep going, widen ranges (vi
 model), `load_data` the validation window on the clone, and `run_model` — the calibrated parameters
 carry over with no manual transfer. `compare_models` tabulates calibration vs. validation metrics.
 
+**Transparent data loading.** `load_data` reports `pet_handling` (e.g.
+`expanded_from_12_monthly_means` when PET is supplied as 12 monthly means — the HBV-light convention —
+and auto-expanded to daily) and a per-column `data_quality` summary (valid/missing counts, min/max), so
+an agent can sanity-check the forcing without opening the file.
+
 **Richer uncertainty.** `evaluate_uncertainty` returns the 95% prediction-band **coverage** (fraction
-of observations inside the band), **mean band width**, and per-parameter **posterior ranges**, not
-just the best/current objective.
+of observations inside the band), **mean band width**, and per-parameter posterior **quantiles**
+(p5/p25/p50/p75/p95). Pass `output_file` to write the full **per-timestep prediction band**
+(Date, Observed, Calibrated, BestRun, Q5, Q95) to CSV, ready to plot. (Sampling is uniform over the
+parameter ranges — parameter, not predictive, uncertainty.)
 
 ## Inputs & outputs