HBV-Lab 1.2.0__tar.gz → 1.3.0__tar.gz

{hbv_lab-1.2.0 → hbv_lab-1.3.0}/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.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     "HBVModel",

{hbv_lab-1.2.0 → hbv_lab-1.3.0}/HBV_Lab/calibration.py

@@ -1,7 +1,7 @@
 class calibration:
 
     def calibrate(self, method='Nelder-Mead', objective='NSE', iterations=100,
-                            verbose=True, plot_results=True):
+                            verbose=True, plot_results=True, progress_callback=None):
         """
         Calibrate an HBV model's parameters to optimize the objective function.
 
@@ -29,11 +29,19 @@ class calibration:
             Whether to print progress information
         plot_results : bool, default True
             Whether to plot the final results after calibration
-            
+        progress_callback : callable, optional
+            Called once per optimizer iteration as
+            ``progress_callback(iteration, total_iterations, current_value, best_value)``,
+            where the values are in human-facing objective terms (e.g. NSE). Useful for
+            driving an external progress UI (e.g. the MCP server). Exceptions raised by
+            the callback are swallowed so they cannot interrupt calibration.
+
         Returns:
         --------
         dict
-            Dictionary containing optimized parameters and performance metrics
+            Dictionary with keys ``parameters`` (optimized parameter dict),
+            ``performance`` (final metrics), ``optimization_result`` (the SciPy result),
+            and ``trajectory`` (best objective value per iteration).
         """
         import scipy.optimize as opt
         import numpy as np
@@ -154,15 +162,21 @@ class calibration:
             else:
                 raise ValueError(f"Unknown objective function: {objective}")
         
-        # Callback function to track progress
+        # Callback function to track progress.
+        # objective_function always returns a value to be MINIMIZED (for NSE/KGE it
+        # returns the negative metric), so the best-so-far starts at +inf for every
+        # objective and improves downward.
         num_iter = [0]
-        best_value = [float('inf') if objective in ['RMSE', 'MAE'] else float('-inf')]
+        best_value = [float('inf')]
         start_time = time.time()
-        
+        # Per-iteration best-so-far objective values, in human-facing terms
+        # (e.g. NSE/KGE as-is, RMSE/MAE as-is). Returned to the caller.
+        trajectory = []
+
         def callback(params):
             num_iter[0] += 1
             current_value = objective_function(params)
-            
+
             # For NSE and KGE, we're minimizing the negative value
             if objective in ['NSE', 'KGE']:
                 display_value = -current_value
@@ -170,10 +184,22 @@ class calibration:
             else:
                 display_value = current_value
                 is_better = current_value < best_value[0]
-            
+
             if is_better:
                 best_value[0] = current_value
-            
+
+            # Best objective so far, in human-facing terms
+            best_display = -best_value[0] if objective in ['NSE', 'KGE'] else best_value[0]
+            trajectory.append(best_display)
+
+            # Optional external progress hook (e.g. for an MCP/agent UI).
+            # Kept defensive: a misbehaving callback must not break calibration.
+            if progress_callback is not None:
+                try:
+                    progress_callback(num_iter[0], iterations, display_value, best_display)
+                except Exception:
+                    pass
+
             if verbose and num_iter[0] % max(1, iterations // 10) == 0:
                 elapsed = time.time() - start_time
                 print(f"Iteration {num_iter[0]}/{iterations}, "
@@ -238,7 +264,8 @@ class calibration:
             return {
                 'parameters': optimized_params,
                 'performance': self.performance_metrics,
-                'optimization_result': result
+                'optimization_result': result,
+                'trajectory': trajectory
             }
             
         except Exception as e:

{hbv_lab-1.2.0 → hbv_lab-1.3.0}/HBV_Lab/mcp_server.py

@@ -27,7 +27,7 @@ import matplotlib
 
 matplotlib.use("Agg")  # headless: no GUI needed on a server
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.fastmcp import FastMCP, Context
 
 from . import HBVModel, __version__
 
@@ -68,6 +68,20 @@ def _find_group(model: HBVModel, name: str) -> str | None:
     return None
 
 
+def _downsample(seq, n: int = 20) -> list:
+    """At most ``n`` evenly-spaced rounded points from ``seq`` (keeps first and last).
+
+    Keeps the calibration trajectory compact in the tool result regardless of how many
+    iterations ran.
+    """
+    seq = [round(float(v), 4) for v in seq]
+    if len(seq) <= n:
+        return seq
+    step = (len(seq) - 1) / (n - 1)
+    idx = sorted({int(round(k * step)) for k in range(n)})
+    return [seq[i] for i in idx]
+
+
 # --- tools --------------------------------------------------------------------
 @mcp.tool()
 def create_model(name: str = "") -> dict:
@@ -210,35 +224,87 @@ def run_model(model_id: str) -> dict:
 
 
 @mcp.tool()
-def calibrate(
+async def calibrate(
     model_id: str,
     objective: str = "NSE",
     method: str = "Nelder-Mead",
     iterations: int = 1000,
+    ctx: Context = None,
 ) -> dict:
     """Calibrate the model to observed discharge (requires obs data loaded).
 
     ``objective`` is one of NSE / KGE / RMSE / MAE. ``method`` defaults to the
     gradient-free 'Nelder-Mead' (recommended for HBV's piecewise objective).
-    Returns the optimized parameters and final performance metrics.
+
+    Progress: while running, the server emits MCP progress notifications each
+    optimizer iteration (visible in clients that surface them).
+
+    Incremental use: each call continues from the model's *current* parameters, so an
+    agent can call calibrate repeatedly with a small ``iterations`` budget (e.g. 50),
+    inspect the improving metric and ``objective_trajectory`` between calls, and decide
+    whether to keep going, widen parameter ranges, or switch objective.
+
+    Returns the optimized parameters, final metrics, optimizer status, and the
+    best-objective-per-iteration trajectory (downsampled).
     """
+    import asyncio
+
     model = _get(model_id)
-    model.calibrate(
-        method=method,
-        objective=objective,
-        iterations=iterations,
-        verbose=False,
-        plot_results=False,
+    loop = asyncio.get_running_loop()
+    updates: asyncio.Queue = asyncio.Queue()
+
+    def progress_cb(i, total, current, best):
+        # Runs in the worker thread — hand the update back to the event loop safely.
+        loop.call_soon_threadsafe(updates.put_nowait, (i, total, current, best))
+
+    async def report(i, total, current, best):
+        if ctx is None:
+            return
+        try:
+            await ctx.report_progress(i, total)
+            await ctx.info(
+                f"calibrate iter {i}/{total}: {objective}={current:.4f} (best {best:.4f})"
+            )
+        except Exception:
+            pass
+
+    # Run the (blocking) calibration in a worker thread so we can stream progress.
+    task = asyncio.create_task(
+        asyncio.to_thread(
+            model.calibrate,
+            method=method,
+            objective=objective,
+            iterations=iterations,
+            verbose=False,
+            plot_results=False,
+            progress_callback=progress_cb,
+        )
     )
+    while not task.done():
+        try:
+            i, total, current, best = await asyncio.wait_for(updates.get(), timeout=0.25)
+            await report(i, total, current, best)
+        except asyncio.TimeoutError:
+            pass
+    while not updates.empty():  # flush any stragglers
+        await report(*updates.get_nowait())
+    out = await task  # re-raises any error from the worker thread
+
+    result = out["optimization_result"]
+    traj = out.get("trajectory", [])
     return {
         "model_id": model_id,
         "objective": objective,
         "method": method,
+        "n_iterations": int(getattr(result, "nit", len(traj))),
+        "success": bool(getattr(result, "success", True)),
+        "message": str(getattr(result, "message", "")),
         "optimized_parameters": {
             group: {name: round(info["default"], 6) for name, info in params.items()}
             for group, params in model.params.items()
         },
         "performance_metrics": _metrics(model),
+        "objective_trajectory": _downsample(traj, 20),
     }
 
 

{hbv_lab-1.2.0 → hbv_lab-1.3.0}/HBV_Lab.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: HBV_Lab
-Version: 1.2.0
+Version: 1.3.0
 Summary: An intuitive, object-oriented and user-friendly Python implementation of a lumped conceptual HBV hydrological model for educational and research purposes.
 Home-page: https://github.com/abdallaox/HBV_python_implementation
 Author: Abdalla Mohammed
@@ -257,6 +257,13 @@ run → calibrate → plot*. Model state is kept server-side (each tool takes a
 series are passed by **file path**, not through the agent's context — tools return compact metrics and
 output-file paths.
 
+**Calibration progress & agent steering.** `calibrate` emits MCP progress notifications every
+optimizer iteration (clients that surface them show a live progress/log view), and its result
+includes the optimizer status and the best-objective-per-iteration `objective_trajectory`. Because
+each call continues from the model's *current* parameters, an agent can also calibrate incrementally
+— call `calibrate` with a small `iterations` budget, inspect the improving metric, and decide whether
+to keep going, widen ranges, or switch objective between rounds.
+
 ## Inputs & outputs
 
 **Inputs** (daily, consistent units): precipitation (mm), air temperature (°C) and potential

{hbv_lab-1.2.0 → hbv_lab-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: HBV_Lab
-Version: 1.2.0
+Version: 1.3.0
 Summary: An intuitive, object-oriented and user-friendly Python implementation of a lumped conceptual HBV hydrological model for educational and research purposes.
 Home-page: https://github.com/abdallaox/HBV_python_implementation
 Author: Abdalla Mohammed
@@ -257,6 +257,13 @@ run → calibrate → plot*. Model state is kept server-side (each tool takes a
 series are passed by **file path**, not through the agent's context — tools return compact metrics and
 output-file paths.
 
+**Calibration progress & agent steering.** `calibrate` emits MCP progress notifications every
+optimizer iteration (clients that surface them show a live progress/log view), and its result
+includes the optimizer status and the best-objective-per-iteration `objective_trajectory`. Because
+each call continues from the model's *current* parameters, an agent can also calibrate incrementally
+— call `calibrate` with a small `iterations` budget, inspect the improving metric, and decide whether
+to keep going, widen ranges, or switch objective between rounds.
+
 ## Inputs & outputs
 
 **Inputs** (daily, consistent units): precipitation (mm), air temperature (°C) and potential

{hbv_lab-1.2.0 → hbv_lab-1.3.0}/README.md

@@ -216,6 +216,13 @@ run → calibrate → plot*. Model state is kept server-side (each tool takes a
 series are passed by **file path**, not through the agent's context — tools return compact metrics and
 output-file paths.
 
+**Calibration progress & agent steering.** `calibrate` emits MCP progress notifications every
+optimizer iteration (clients that surface them show a live progress/log view), and its result
+includes the optimizer status and the best-objective-per-iteration `objective_trajectory`. Because
+each call continues from the model's *current* parameters, an agent can also calibrate incrementally
+— call `calibrate` with a small `iterations` budget, inspect the improving metric, and decide whether
+to keep going, widen ranges, or switch objective between rounds.
+
 ## Inputs & outputs
 
 **Inputs** (daily, consistent units): precipitation (mm), air temperature (°C) and potential

{hbv_lab-1.2.0 → hbv_lab-1.3.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as f:
 
 setup(
     name='HBV_Lab',
-    version='1.2.0',
+    version='1.3.0',
     packages=find_packages(include=['HBV_Lab', 'HBV_Lab.*']),
     install_requires=[
         'numpy',