hydroreopllm 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. hydroreopllm-0.1.0/LICENSE +28 -0
  2. hydroreopllm-0.1.0/MANIFEST.in +8 -0
  3. hydroreopllm-0.1.0/PKG-INFO +109 -0
  4. hydroreopllm-0.1.0/README.md +76 -0
  5. hydroreopllm-0.1.0/README.zh-TW.md +76 -0
  6. hydroreopllm-0.1.0/THIRD_PARTY_NOTICES.md +28 -0
  7. hydroreopllm-0.1.0/environment/hydrocnhs-core.json +29 -0
  8. hydroreopllm-0.1.0/environment/requirements-bundled.txt +12 -0
  9. hydroreopllm-0.1.0/examples/daily_offline/README.md +31 -0
  10. hydroreopllm-0.1.0/examples/daily_offline/cascade.json +114 -0
  11. hydroreopllm-0.1.0/examples/daily_offline/cascade.yaml +29 -0
  12. hydroreopllm-0.1.0/examples/daily_offline/operator.txt +1 -0
  13. hydroreopllm-0.1.0/examples/daily_offline/single.json +66 -0
  14. hydroreopllm-0.1.0/examples/daily_offline/single.mosart.yaml +17 -0
  15. hydroreopllm-0.1.0/examples/daily_offline/single.yaml +17 -0
  16. hydroreopllm-0.1.0/examples/llm_reservoir_abm.py +4 -0
  17. hydroreopllm-0.1.0/examples/multiple_reservoirs/README.md +29 -0
  18. hydroreopllm-0.1.0/examples/multiple_reservoirs/agents.llm.yaml +28 -0
  19. hydroreopllm-0.1.0/examples/multiple_reservoirs/agents.mosart.yaml +18 -0
  20. hydroreopllm-0.1.0/examples/multiple_reservoirs/agents.rule.yaml +20 -0
  21. hydroreopllm-0.1.0/examples/multiple_reservoirs/auditors.yaml +3 -0
  22. hydroreopllm-0.1.0/examples/multiple_reservoirs/experiment.llm.yaml +20 -0
  23. hydroreopllm-0.1.0/examples/multiple_reservoirs/experiment.mosart.yaml +15 -0
  24. hydroreopllm-0.1.0/examples/multiple_reservoirs/experiment.yaml +20 -0
  25. hydroreopllm-0.1.0/examples/multiple_reservoirs/extensions/__init__.py +48 -0
  26. hydroreopllm-0.1.0/examples/multiple_reservoirs/forcing.csv +11 -0
  27. hydroreopllm-0.1.0/examples/multiple_reservoirs/hydrology.yaml +12 -0
  28. hydroreopllm-0.1.0/examples/multiple_reservoirs/information.yaml +2 -0
  29. hydroreopllm-0.1.0/examples/multiple_reservoirs/knowledge/guidance.json +12 -0
  30. hydroreopllm-0.1.0/examples/multiple_reservoirs/models.yaml +31 -0
  31. hydroreopllm-0.1.0/examples/multiple_reservoirs/prompts/operator.txt +4 -0
  32. hydroreopllm-0.1.0/examples/multiple_reservoirs/prompts/system.txt +2 -0
  33. hydroreopllm-0.1.0/examples/multiple_reservoirs/reference_a.csv +366 -0
  34. hydroreopllm-0.1.0/examples/multiple_reservoirs/reference_b.csv +366 -0
  35. hydroreopllm-0.1.0/examples/multiple_reservoirs/reservoirs.yaml +40 -0
  36. hydroreopllm-0.1.0/examples/multiple_reservoirs/statistics_a.json +31 -0
  37. hydroreopllm-0.1.0/examples/multiple_reservoirs/statistics_b.json +31 -0
  38. hydroreopllm-0.1.0/examples/multiple_reservoirs/synthetic_catchments.yaml +72 -0
  39. hydroreopllm-0.1.0/examples/rules/hanasaki/__init__.py +40 -0
  40. hydroreopllm-0.1.0/examples/rules/mosart_urban/README.md +35 -0
  41. hydroreopllm-0.1.0/examples/rules/mosart_urban/__init__.py +251 -0
  42. hydroreopllm-0.1.0/licenses/HydroCNHS-BSD-3-Clause.txt +28 -0
  43. hydroreopllm-0.1.0/pyproject.toml +93 -0
  44. hydroreopllm-0.1.0/scripts/package_build.py +20 -0
  45. hydroreopllm-0.1.0/scripts/verify_mosart_rule.py +159 -0
  46. hydroreopllm-0.1.0/setup.cfg +4 -0
  47. hydroreopllm-0.1.0/src/hydrocnhs/Config_logging.yaml +36 -0
  48. hydroreopllm-0.1.0/src/hydrocnhs/__init__.py +23 -0
  49. hydroreopllm-0.1.0/src/hydrocnhs/abm.py +62 -0
  50. hydroreopllm-0.1.0/src/hydrocnhs/abm_script.py +108 -0
  51. hydroreopllm-0.1.0/src/hydrocnhs/calibration/__init__.py +43 -0
  52. hydroreopllm-0.1.0/src/hydrocnhs/calibration/convertor.py +314 -0
  53. hydroreopllm-0.1.0/src/hydrocnhs/calibration/ga_deap.py +593 -0
  54. hydroreopllm-0.1.0/src/hydrocnhs/data_collector.py +139 -0
  55. hydroreopllm-0.1.0/src/hydrocnhs/hydrocnhs.py +893 -0
  56. hydroreopllm-0.1.0/src/hydrocnhs/indicators.py +407 -0
  57. hydroreopllm-0.1.0/src/hydrocnhs/model_builder.py +494 -0
  58. hydroreopllm-0.1.0/src/hydrocnhs/rainfall_runoff_model/__init__.py +0 -0
  59. hydroreopllm-0.1.0/src/hydrocnhs/rainfall_runoff_model/abcd.py +223 -0
  60. hydroreopllm-0.1.0/src/hydrocnhs/rainfall_runoff_model/groundwater.py +110 -0
  61. hydroreopllm-0.1.0/src/hydrocnhs/rainfall_runoff_model/gwlf.py +429 -0
  62. hydroreopllm-0.1.0/src/hydrocnhs/rainfall_runoff_model/gwlf_hourly.py +290 -0
  63. hydroreopllm-0.1.0/src/hydrocnhs/rainfall_runoff_model/pet_hamon.py +60 -0
  64. hydroreopllm-0.1.0/src/hydrocnhs/routing.py +305 -0
  65. hydroreopllm-0.1.0/src/hydrocnhs/util.py +1143 -0
  66. hydroreopllm-0.1.0/src/hydrocnhs/visual.py +321 -0
  67. hydroreopllm-0.1.0/src/hydrocnhs/water_quality_model/__init__.py +0 -0
  68. hydroreopllm-0.1.0/src/hydrocnhs/water_quality_model/sediment.py +384 -0
  69. hydroreopllm-0.1.0/src/hydroreopllm.egg-info/PKG-INFO +109 -0
  70. hydroreopllm-0.1.0/src/hydroreopllm.egg-info/SOURCES.txt +120 -0
  71. hydroreopllm-0.1.0/src/hydroreopllm.egg-info/dependency_links.txt +1 -0
  72. hydroreopllm-0.1.0/src/hydroreopllm.egg-info/entry_points.txt +3 -0
  73. hydroreopllm-0.1.0/src/hydroreopllm.egg-info/requires.txt +24 -0
  74. hydroreopllm-0.1.0/src/hydroreopllm.egg-info/top_level.txt +2 -0
  75. hydroreopllm-0.1.0/src/llm_reservoir_agent/__init__.py +33 -0
  76. hydroreopllm-0.1.0/src/llm_reservoir_agent/agent.py +392 -0
  77. hydroreopllm-0.1.0/src/llm_reservoir_agent/agent_configuration.py +116 -0
  78. hydroreopllm-0.1.0/src/llm_reservoir_agent/audit.py +435 -0
  79. hydroreopllm-0.1.0/src/llm_reservoir_agent/auditor.py +449 -0
  80. hydroreopllm-0.1.0/src/llm_reservoir_agent/balance.py +141 -0
  81. hydroreopllm-0.1.0/src/llm_reservoir_agent/benchmark.py +371 -0
  82. hydroreopllm-0.1.0/src/llm_reservoir_agent/benchmark_config.py +176 -0
  83. hydroreopllm-0.1.0/src/llm_reservoir_agent/case.py +369 -0
  84. hydroreopllm-0.1.0/src/llm_reservoir_agent/configuration.py +186 -0
  85. hydroreopllm-0.1.0/src/llm_reservoir_agent/configured_audit.py +118 -0
  86. hydroreopllm-0.1.0/src/llm_reservoir_agent/configured_backend.py +1028 -0
  87. hydroreopllm-0.1.0/src/llm_reservoir_agent/context.py +228 -0
  88. hydroreopllm-0.1.0/src/llm_reservoir_agent/contracts.py +256 -0
  89. hydroreopllm-0.1.0/src/llm_reservoir_agent/coupled.py +530 -0
  90. hydroreopllm-0.1.0/src/llm_reservoir_agent/downstream.py +357 -0
  91. hydroreopllm-0.1.0/src/llm_reservoir_agent/experiment.py +553 -0
  92. hydroreopllm-0.1.0/src/llm_reservoir_agent/extensions.py +101 -0
  93. hydroreopllm-0.1.0/src/llm_reservoir_agent/information.py +718 -0
  94. hydroreopllm-0.1.0/src/llm_reservoir_agent/information_runtime.py +130 -0
  95. hydroreopllm-0.1.0/src/llm_reservoir_agent/information_verification.py +166 -0
  96. hydroreopllm-0.1.0/src/llm_reservoir_agent/interval_network.py +123 -0
  97. hydroreopllm-0.1.0/src/llm_reservoir_agent/interval_weather.py +234 -0
  98. hydroreopllm-0.1.0/src/llm_reservoir_agent/network.py +501 -0
  99. hydroreopllm-0.1.0/src/llm_reservoir_agent/outcome.py +155 -0
  100. hydroreopllm-0.1.0/src/llm_reservoir_agent/passive.py +260 -0
  101. hydroreopllm-0.1.0/src/llm_reservoir_agent/physics.py +256 -0
  102. hydroreopllm-0.1.0/src/llm_reservoir_agent/plugins/__init__.py +9 -0
  103. hydroreopllm-0.1.0/src/llm_reservoir_agent/policies.py +92 -0
  104. hydroreopllm-0.1.0/src/llm_reservoir_agent/policy_adapter.py +375 -0
  105. hydroreopllm-0.1.0/src/llm_reservoir_agent/prompt.py +417 -0
  106. hydroreopllm-0.1.0/src/llm_reservoir_agent/providers.py +380 -0
  107. hydroreopllm-0.1.0/src/llm_reservoir_agent/reach_validation.py +298 -0
  108. hydroreopllm-0.1.0/src/llm_reservoir_agent/recovery.py +437 -0
  109. hydroreopllm-0.1.0/src/llm_reservoir_agent/rule_based.py +133 -0
  110. hydroreopllm-0.1.0/src/llm_reservoir_agent/runtime.py +31 -0
  111. hydroreopllm-0.1.0/src/llm_reservoir_agent/temporal_output.py +250 -0
  112. hydroreopllm-0.1.0/src/llm_reservoir_agent/time_axis.py +134 -0
  113. hydroreopllm-0.1.0/src/llm_reservoir_agent/time_config.py +59 -0
  114. hydroreopllm-0.1.0/src/llm_reservoir_agent/trace.py +693 -0
  115. hydroreopllm-0.1.0/src/llm_reservoir_agent/verification.py +792 -0
  116. hydroreopllm-0.1.0/src/llm_reservoir_agent/weather.py +249 -0
  117. hydroreopllm-0.1.0/src/llm_reservoir_agent/workflow.py +877 -0
  118. hydroreopllm-0.1.0/third_party/hydrocnhs/LICENSE +28 -0
  119. hydroreopllm-0.1.0/third_party/hydrocnhs/SOURCE.json +138 -0
  120. hydroreopllm-0.1.0/third_party/hydrocnhs/patches/gwlf-groundwater-diagnostics.patch +134 -0
  121. hydroreopllm-0.1.0/third_party/hydrocnhs/patches/visual-indicator-api.patch +14 -0
  122. hydroreopllm-0.1.0/third_party/hydrocnhs/upstream-pyproject.toml +41 -0
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, HydroReOpLLM contributors
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,8 @@
1
+ include scripts/package_build.py
2
+ include scripts/verify_mosart_rule.py
3
+ include README.zh-TW.md
4
+ include THIRD_PARTY_NOTICES.md
5
+ include licenses/*
6
+ include environment/requirements-bundled.txt
7
+ # The full test suite and its fixtures live in the repository.
8
+ prune tests
@@ -0,0 +1,109 @@
1
+ Metadata-Version: 2.4
2
+ Name: hydroreopllm
3
+ Version: 0.1.0
4
+ Summary: HydroReOpLLM: configurable reservoir operations coupled with HydroCNHS
5
+ License-Expression: BSD-3-Clause
6
+ Project-URL: Repository, https://github.com/WenyuChiou/HydroReOpLLM
7
+ Project-URL: Documentation, https://wenyuchiou.github.io/HydroReOpLLM/
8
+ Requires-Python: >=3.12
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ License-File: licenses/HydroCNHS-BSD-3-Clause.txt
12
+ Requires-Dist: joblib
13
+ Requires-Dist: matplotlib
14
+ Requires-Dist: numpy
15
+ Requires-Dist: pandas
16
+ Requires-Dist: ruamel.yaml
17
+ Requires-Dist: scipy
18
+ Requires-Dist: scikit-learn
19
+ Requires-Dist: tqdm
20
+ Requires-Dist: PyYAML>=6
21
+ Requires-Dist: deap
22
+ Provides-Extra: hydrocnhs
23
+ Provides-Extra: test
24
+ Requires-Dist: pytest>=8; extra == "test"
25
+ Requires-Dist: pytest-subtests; extra == "test"
26
+ Requires-Dist: setuptools>=77.0.3; extra == "test"
27
+ Provides-Extra: docs
28
+ Requires-Dist: mkdocs==1.6.1; extra == "docs"
29
+ Provides-Extra: gis
30
+ Requires-Dist: shapely<3,>=2; extra == "gis"
31
+ Requires-Dist: pyproj<4,>=3; extra == "gis"
32
+ Dynamic: license-file
33
+
34
+ # HydroReOpLLM
35
+
36
+ [User manual](https://wenyuchiou.github.io/HydroReOpLLM/) · [繁體中文使用手冊](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/docs/README.zh-TW.md) · [繁體中文首頁](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/README.zh-TW.md)
37
+
38
+ HydroReOpLLM simulates reservoir operations from time series of local inflow or weather forcing. A reservoir operator proposes a release. The physical model applies storage and release limits, routes water downstream, and records the decision and water balance for each time step. Operators can use a rule, a prescribed action, or an LLM with local operating guidance.
39
+
40
+ ## Install the Python package
41
+
42
+ In a Python 3.12 virtual environment, install the package from GitHub:
43
+
44
+ ```sh
45
+ python -m pip install "hydroreopllm @ git+https://github.com/WenyuChiou/HydroReOpLLM.git"
46
+ ```
47
+
48
+ After a version is published to PyPI, use `python -m pip install hydroreopllm`. To run the installed examples, start in a new directory:
49
+
50
+ ```sh
51
+ python -c "import shutil, sysconfig; from pathlib import Path; shutil.copytree(Path(sysconfig.get_path('data')) / 'share/llm-reservoir-agent/examples', 'examples')"
52
+ reservoir-experiment run examples/daily_offline/single.yaml
53
+ reservoir-experiment verify runs/daily-single --require-offline
54
+ ```
55
+
56
+ ## Install from a clone
57
+
58
+ Use Git and Python 3.12. The first installation downloads the Python dependencies.
59
+
60
+ ```sh
61
+ git clone https://github.com/WenyuChiou/HydroReOpLLM.git
62
+ cd HydroReOpLLM
63
+ ```
64
+
65
+ On Windows PowerShell:
66
+
67
+ ```powershell
68
+ py -3.12 -m venv .venv
69
+ .\.venv\Scripts\python.exe -m pip install -c environment/requirements-bundled.txt .
70
+ ```
71
+
72
+ On macOS or Linux:
73
+
74
+ ```sh
75
+ python3.12 -m venv .venv
76
+ .venv/bin/python -m pip install -c environment/requirements-bundled.txt .
77
+ ```
78
+
79
+ ## Run a reservoir and check the output
80
+
81
+ From the repository root, use the Python executable in the environment you just created. On Windows:
82
+
83
+ ```powershell
84
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow check examples/daily_offline/single.yaml
85
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow run examples/daily_offline/single.yaml
86
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow verify runs/daily-single --require-offline
87
+ ```
88
+
89
+ On macOS or Linux, use `.venv/bin/python` in those three commands. This example simulates one synthetic reservoir for four days with a prescribed release of 1 m³/s. It needs no model service or API key. The run creates `runs/daily-single/` on your machine. Choose a fresh `output` directory in the YAML before repeating a run.
90
+
91
+ ## Examples and tests in the Git checkout
92
+
93
+ - [Documentation index on GitHub](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/docs/README.md)
94
+ - [Runnable notebook for the four-day example](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/tutorials/offline_synthetic.ipynb)
95
+ - [Daily reservoir and cascade](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/examples/daily_offline/README.md)
96
+ - [Two independently operated reservoirs with weather-driven inflows](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/examples/multiple_reservoirs/README.md)
97
+ - [Daily, hourly and fixed time steps](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/examples/time_scales/README.md)
98
+ - [Starting a case from a template](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/templates/prepared/README.md)
99
+
100
+ To run the tests, use the same virtual environment and install the test extra. On Windows:
101
+
102
+ ```powershell
103
+ .\.venv\Scripts\python.exe -m pip install -c environment/requirements-bundled.txt ".[test]"
104
+ .\.venv\Scripts\python.exe -m pytest -q
105
+ ```
106
+
107
+ ## License
108
+
109
+ HydroReOpLLM is distributed under the [BSD 3-Clause License](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/LICENSE). The bundled HydroCNHS source retains the [BSD 3-Clause notice from Chung-Yi Lin](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/licenses/HydroCNHS-BSD-3-Clause.txt). See the [source attribution and patch history](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/THIRD_PARTY_NOTICES.md).
@@ -0,0 +1,76 @@
1
+ # HydroReOpLLM
2
+
3
+ [User manual](https://wenyuchiou.github.io/HydroReOpLLM/) · [繁體中文使用手冊](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/docs/README.zh-TW.md) · [繁體中文首頁](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/README.zh-TW.md)
4
+
5
+ HydroReOpLLM simulates reservoir operations from time series of local inflow or weather forcing. A reservoir operator proposes a release. The physical model applies storage and release limits, routes water downstream, and records the decision and water balance for each time step. Operators can use a rule, a prescribed action, or an LLM with local operating guidance.
6
+
7
+ ## Install the Python package
8
+
9
+ In a Python 3.12 virtual environment, install the package from GitHub:
10
+
11
+ ```sh
12
+ python -m pip install "hydroreopllm @ git+https://github.com/WenyuChiou/HydroReOpLLM.git"
13
+ ```
14
+
15
+ After a version is published to PyPI, use `python -m pip install hydroreopllm`. To run the installed examples, start in a new directory:
16
+
17
+ ```sh
18
+ python -c "import shutil, sysconfig; from pathlib import Path; shutil.copytree(Path(sysconfig.get_path('data')) / 'share/llm-reservoir-agent/examples', 'examples')"
19
+ reservoir-experiment run examples/daily_offline/single.yaml
20
+ reservoir-experiment verify runs/daily-single --require-offline
21
+ ```
22
+
23
+ ## Install from a clone
24
+
25
+ Use Git and Python 3.12. The first installation downloads the Python dependencies.
26
+
27
+ ```sh
28
+ git clone https://github.com/WenyuChiou/HydroReOpLLM.git
29
+ cd HydroReOpLLM
30
+ ```
31
+
32
+ On Windows PowerShell:
33
+
34
+ ```powershell
35
+ py -3.12 -m venv .venv
36
+ .\.venv\Scripts\python.exe -m pip install -c environment/requirements-bundled.txt .
37
+ ```
38
+
39
+ On macOS or Linux:
40
+
41
+ ```sh
42
+ python3.12 -m venv .venv
43
+ .venv/bin/python -m pip install -c environment/requirements-bundled.txt .
44
+ ```
45
+
46
+ ## Run a reservoir and check the output
47
+
48
+ From the repository root, use the Python executable in the environment you just created. On Windows:
49
+
50
+ ```powershell
51
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow check examples/daily_offline/single.yaml
52
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow run examples/daily_offline/single.yaml
53
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow verify runs/daily-single --require-offline
54
+ ```
55
+
56
+ On macOS or Linux, use `.venv/bin/python` in those three commands. This example simulates one synthetic reservoir for four days with a prescribed release of 1 m³/s. It needs no model service or API key. The run creates `runs/daily-single/` on your machine. Choose a fresh `output` directory in the YAML before repeating a run.
57
+
58
+ ## Examples and tests in the Git checkout
59
+
60
+ - [Documentation index on GitHub](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/docs/README.md)
61
+ - [Runnable notebook for the four-day example](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/tutorials/offline_synthetic.ipynb)
62
+ - [Daily reservoir and cascade](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/examples/daily_offline/README.md)
63
+ - [Two independently operated reservoirs with weather-driven inflows](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/examples/multiple_reservoirs/README.md)
64
+ - [Daily, hourly and fixed time steps](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/examples/time_scales/README.md)
65
+ - [Starting a case from a template](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/templates/prepared/README.md)
66
+
67
+ To run the tests, use the same virtual environment and install the test extra. On Windows:
68
+
69
+ ```powershell
70
+ .\.venv\Scripts\python.exe -m pip install -c environment/requirements-bundled.txt ".[test]"
71
+ .\.venv\Scripts\python.exe -m pytest -q
72
+ ```
73
+
74
+ ## License
75
+
76
+ HydroReOpLLM is distributed under the [BSD 3-Clause License](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/LICENSE). The bundled HydroCNHS source retains the [BSD 3-Clause notice from Chung-Yi Lin](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/licenses/HydroCNHS-BSD-3-Clause.txt). See the [source attribution and patch history](https://github.com/WenyuChiou/HydroReOpLLM/blob/main/THIRD_PARTY_NOTICES.md).
@@ -0,0 +1,76 @@
1
+ # HydroReOpLLM
2
+
3
+ [繁體中文使用手冊](docs/README.zh-TW.md) · [English manual](docs/README.md) · [English](README.md)
4
+
5
+ HydroReOpLLM 使用局部入流或氣象時間序列模擬水庫操作。每個時間步先由操作策略提出放流量,再由物理模型套用庫容與放流限制,將水量往下游演算,並記錄決策和水量平衡。操作策略可採用規則、指定放流量,或讀取本地操作指引的 LLM。
6
+
7
+ ## 安裝 Python 套件
8
+
9
+ 在 Python 3.12 虛擬環境中,可直接從 GitHub 安裝套件。
10
+
11
+ ```sh
12
+ python -m pip install "hydroreopllm @ git+https://github.com/WenyuChiou/HydroReOpLLM.git"
13
+ ```
14
+
15
+ 版本發布至 PyPI 後,可用 `python -m pip install hydroreopllm` 安裝。若要執行套件內附範例,請在新的資料夾執行以下指令。
16
+
17
+ ```sh
18
+ python -c "import shutil, sysconfig; from pathlib import Path; shutil.copytree(Path(sysconfig.get_path('data')) / 'share/llm-reservoir-agent/examples', 'examples')"
19
+ reservoir-experiment run examples/daily_offline/single.yaml
20
+ reservoir-experiment verify runs/daily-single --require-offline
21
+ ```
22
+
23
+ ## 下載與安裝
24
+
25
+ 需要 Git 和 Python 3.12。首次安裝會下載 Python 相依套件。
26
+
27
+ ```sh
28
+ git clone https://github.com/WenyuChiou/HydroReOpLLM.git
29
+ cd HydroReOpLLM
30
+ ```
31
+
32
+ Windows PowerShell:
33
+
34
+ ```powershell
35
+ py -3.12 -m venv .venv
36
+ .\.venv\Scripts\python.exe -m pip install -c environment/requirements-bundled.txt .
37
+ ```
38
+
39
+ macOS 或 Linux:
40
+
41
+ ```sh
42
+ python3.12 -m venv .venv
43
+ .venv/bin/python -m pip install -c environment/requirements-bundled.txt .
44
+ ```
45
+
46
+ ## 執行單庫範例並驗證輸出
47
+
48
+ 在倉庫根目錄,使用剛建立的虛擬環境。Windows 指令如下。
49
+
50
+ ```powershell
51
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow check examples/daily_offline/single.yaml
52
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow run examples/daily_offline/single.yaml
53
+ .\.venv\Scripts\python.exe -m llm_reservoir_agent.workflow verify runs/daily-single --require-offline
54
+ ```
55
+
56
+ macOS 或 Linux 將上述三條指令的執行檔換成 `.venv/bin/python`。這個範例用一座合成水庫模擬四天,指定放流量為每秒 1 立方公尺,無須模型服務或 API 金鑰。結果寫入本機的 `runs/daily-single/`。重跑前請在 YAML 設定中指定新的 `output` 目錄。
57
+
58
+ ## Git 專案內的範例與測試
59
+
60
+ - [使用手冊與範例驗證](docs/README.zh-TW.md)
61
+ - [可直接執行的四天合成水庫教學筆記本](tutorials/offline_synthetic.ipynb)
62
+ - [每日單庫與串聯水庫](examples/daily_offline/README.md)
63
+ - [兩座獨立操作的水庫與氣象驅動入流](examples/multiple_reservoirs/README.md)
64
+ - [逐日、逐時和固定時間步](examples/time_scales/README.md)
65
+ - [從模板建立案例](templates/prepared/README.md)
66
+
67
+ 要執行測試,請在同一虛擬環境安裝測試依賴。Windows 指令如下。
68
+
69
+ ```powershell
70
+ .\.venv\Scripts\python.exe -m pip install -c environment/requirements-bundled.txt ".[test]"
71
+ .\.venv\Scripts\python.exe -m pytest -q
72
+ ```
73
+
74
+ ## 授權
75
+
76
+ HydroReOpLLM 採用 [BSD 三條款授權](LICENSE)。隨附的 HydroCNHS 保留 [Chung-Yi Lin 的 BSD 三條款授權聲明](licenses/HydroCNHS-BSD-3-Clause.txt)。[來源與修改記錄](THIRD_PARTY_NOTICES.md)
@@ -0,0 +1,28 @@
1
+ # Source attribution
2
+
3
+ The versioned contract shape is adapted from `src/hydrocnhs/policy/contracts.py`
4
+ in WenyuChiou/HydroCNHS candidate commit `fde3baf8fb0de6bdc3650a10a490a74a327d25e1`.
5
+ The candidate extension is separate from the accepted HydroCNHS core pin.
6
+ HydroCNHS is by Chung-Yi Lin; its BSD 3-Clause notice is preserved in
7
+ `licenses/HydroCNHS-BSD-3-Clause.txt`.
8
+
9
+ The bundled HydroCNHS source retains its upstream commit in
10
+ [`third_party/hydrocnhs/SOURCE.json`](third_party/hydrocnhs/SOURCE.json).
11
+ A local patch updates five metric calls in `Visual.plot_reg` to the existing
12
+ `Indicator.get_*` methods. The manifest records both the original and installed
13
+ file hashes and the versioned
14
+ [`visual-indicator-api.patch`](third_party/hydrocnhs/patches/visual-indicator-api.patch).
15
+ This plotting correction leaves hydrological calculations unchanged.
16
+
17
+ The versioned `gwlf-groundwater-diagnostics.patch` adds explicit BF0/B0 cold-start
18
+ options and optional daily GWLF diagnostics, with worker-result collection in
19
+ `Model.run`. Original daily defaults, arithmetic and restart fields are preserved
20
+ and checked against a pre-extension numerical oracle. The source manifest retains
21
+ both upstream and installed hashes. The new `groundwater.py` and experimental
22
+ hourly kernel are local extensions, not unmodified upstream GWLF.
23
+
24
+ The flood-control rule in `examples/rules/mosart_urban/` independently implements
25
+ the reservoir equations and annual storage snapshot from RiverAI-Project/MOSART-Urban,
26
+ commit `7883c5cac62e8c0c585fbafbb1045118cad2dd42`. The implementation records
27
+ the upstream source hash. The optional parity check in `scripts/verify_mosart_rule.py`
28
+ requires a separately obtained copy of that upstream source.
@@ -0,0 +1,29 @@
1
+ {
2
+ "hydrocnhs_commit": "fdd5097a3fcabb312c6c3739efc71da2d67c47da",
3
+ "normalization": "CRLF to LF only",
4
+ "files": [
5
+ {
6
+ "path": "hydrocnhs.py",
7
+ "normalized_sha256": "30818c8c6a29a54d05c13f4f1c1aca029a041bf26cf3fd7bc0614bc3ea53c44f"
8
+ },
9
+ {
10
+ "path": "routing.py",
11
+ "normalized_sha256": "088e0b1f928030bc38a991cb369b7109e753350cc399e8b646197bdb0d97d1db"
12
+ },
13
+ {
14
+ "path": "util.py",
15
+ "normalized_sha256": "26a150cff2733496f9bc5205696f4e80c2bea7bd9e47e5a34fd41393c1b5a05a"
16
+ },
17
+ {
18
+ "path": "abm.py",
19
+ "normalized_sha256": "b348391cc14ea4feb12de6d88be3a7647c34c27ddce66556661fa97898128275"
20
+ },
21
+ {
22
+ "path": "data_collector.py",
23
+ "normalized_sha256": "cccd72962d75a60880125e380623e6094a14abd2f696c35b5ef280c416569f9f"
24
+ }
25
+ ],
26
+ "local_extensions": [
27
+ "gwlf-groundwater-diagnostics.v1"
28
+ ]
29
+ }
@@ -0,0 +1,12 @@
1
+ # Tested direct scientific dependency constraints, Python 3.12.14 on Windows.
2
+ # HydroCNHS source is bundled. Its upstream revision is recorded in hydrocnhs-core.json.
3
+ numpy==2.5.1
4
+ pandas==3.0.5
5
+ scipy==1.18.0
6
+ joblib==1.5.3
7
+ ruamel.yaml==0.19.1
8
+ tqdm==4.70.0
9
+ deap==1.4.4
10
+ PyYAML==6.0.3
11
+ scikit-learn==1.9.0
12
+ matplotlib==3.11.1
@@ -0,0 +1,31 @@
1
+ # Daily offline examples
2
+
3
+ `single.yaml` and `cascade.yaml` are complete four-day synthetic fixtures for the
4
+ existing `reservoir-experiment` CLI. Copy this entire folder when moving them.
5
+ They include Leap Day, one-day routing delays and independent reservoir state.
6
+ They do not require an API key, Ollama or a model download.
7
+
8
+ `single.mosart.yaml` selects the shared [MOSART-Urban flood-control
9
+ rule](../rules/mosart_urban/README.md) using the same synthetic physical case.
10
+
11
+ From the repository root:
12
+
13
+ ```shell
14
+ reservoir-experiment check examples/daily_offline/single.yaml
15
+ reservoir-experiment run examples/daily_offline/single.yaml
16
+ reservoir-experiment verify runs/daily-single
17
+ reservoir-experiment check examples/daily_offline/cascade.yaml
18
+ reservoir-experiment run examples/daily_offline/cascade.yaml
19
+ reservoir-experiment verify runs/daily-cascade
20
+ ```
21
+
22
+ Choose a new output directory before repeating a run. The JSON inputs contain
23
+ local inflows (m³/s), storage (m³), release limits (m³/s), a Daily duration of
24
+ 86,400 s and dimensionless routing weights. Both start with 1,000,000 m³ in each
25
+ reservoir. All requested releases are 1 m³/s. Final single-reservoir storage is
26
+ 1,345,600 m³; the cascade's final storages are 1,345,600, 1,086,400 and
27
+ 1,086,400 m³. Routing retains one release interval per edge at the final decision.
28
+
29
+ Read the [configuration guide](https://wenyuchiou.github.io/HydroReOpLLM/CONFIGURATION.html) before replacing these
30
+ invented inputs or selecting a live provider. These fixtures prove software
31
+ contracts, not hydrological calibration or operating-policy skill.
@@ -0,0 +1,114 @@
1
+ {
2
+ "schema_version": "llm-reservoir-network-case.v1",
3
+ "data_kind": "synthetic_fixture",
4
+ "network": {
5
+ "schema_version": "llm-reservoir-network.v2",
6
+ "data_kind": "synthetic_fixture",
7
+ "start_date": "2020-02-28",
8
+ "reservoirs": {
9
+ "Lake_1": {
10
+ "inflow_node": "local_1",
11
+ "physical": {
12
+ "reservoir_id": "Lake_1",
13
+ "capacity_m3": 2000000.0,
14
+ "dead_storage_m3": 0.0,
15
+ "initial_storage_m3": 1000000.0,
16
+ "minimum_release_cms": 0.0,
17
+ "maximum_release_cms": 10.0,
18
+ "dt_seconds": 86400.0
19
+ }
20
+ },
21
+ "Lake_2": {
22
+ "inflow_node": "local_2",
23
+ "physical": {
24
+ "reservoir_id": "Lake_2",
25
+ "capacity_m3": 2000000.0,
26
+ "dead_storage_m3": 0.0,
27
+ "initial_storage_m3": 1000000.0,
28
+ "minimum_release_cms": 0.0,
29
+ "maximum_release_cms": 10.0,
30
+ "dt_seconds": 86400.0
31
+ }
32
+ },
33
+ "Lake_3": {
34
+ "inflow_node": "local_3",
35
+ "physical": {
36
+ "reservoir_id": "Lake_3",
37
+ "capacity_m3": 2000000.0,
38
+ "dead_storage_m3": 0.0,
39
+ "initial_storage_m3": 1000000.0,
40
+ "minimum_release_cms": 0.0,
41
+ "maximum_release_cms": 10.0,
42
+ "dt_seconds": 86400.0
43
+ }
44
+ }
45
+ },
46
+ "connections": [
47
+ {
48
+ "source": "Lake_1",
49
+ "target": "local_2",
50
+ "unit_hydrograph": [
51
+ 0.0,
52
+ 1.0
53
+ ]
54
+ },
55
+ {
56
+ "source": "Lake_2",
57
+ "target": "local_3",
58
+ "unit_hydrograph": [
59
+ 0.0,
60
+ 1.0
61
+ ]
62
+ },
63
+ {
64
+ "source": "Lake_3",
65
+ "target": "outlet",
66
+ "unit_hydrograph": [
67
+ 0.0,
68
+ 1.0
69
+ ]
70
+ }
71
+ ],
72
+ "outlets": [
73
+ "outlet"
74
+ ]
75
+ },
76
+ "inflow_records": [
77
+ {
78
+ "date": "2020-02-28",
79
+ "local_inflow_cms": {
80
+ "local_1": 2.0,
81
+ "local_2": 0.5,
82
+ "local_3": 0.5,
83
+ "outlet": 0.0
84
+ }
85
+ },
86
+ {
87
+ "date": "2020-02-29",
88
+ "local_inflow_cms": {
89
+ "local_1": 2.0,
90
+ "local_2": 0.5,
91
+ "local_3": 0.5,
92
+ "outlet": 0.0
93
+ }
94
+ },
95
+ {
96
+ "date": "2020-03-01",
97
+ "local_inflow_cms": {
98
+ "local_1": 2.0,
99
+ "local_2": 0.5,
100
+ "local_3": 0.5,
101
+ "outlet": 0.0
102
+ }
103
+ },
104
+ {
105
+ "date": "2020-03-02",
106
+ "local_inflow_cms": {
107
+ "local_1": 2.0,
108
+ "local_2": 0.5,
109
+ "local_3": 0.5,
110
+ "outlet": 0.0
111
+ }
112
+ }
113
+ ]
114
+ }
@@ -0,0 +1,29 @@
1
+ # Complete synthetic Daily example; no API key, Ollama or model request.
2
+ schema_version: llm-reservoir-experiment.v1
3
+ case: cascade.json # Prepared local inflows and physical network.
4
+ run_id: daily-cascade # Trace identity, not a reservoir name.
5
+ output: ../../runs/daily-cascade # Must not exist; choose a fresh path for another run.
6
+ max_calls: 0 # This offline fixture makes zero model requests.
7
+ auditors:
8
+ feasible_release:
9
+ type: release_bounds
10
+ version: "1"
11
+ agents:
12
+ operator_1:
13
+ reservoir: Lake_1 # Exact physical network key.
14
+ mode: offline # A deterministic action fixture, not an LLM.
15
+ release_cms: 1.0 # Requested controlled flow in m3/s.
16
+ prompt: operator.txt # Same contract used when changing to an LLM profile.
17
+ auditors: [feasible_release]
18
+ operator_2:
19
+ reservoir: Lake_2 # Exact physical network key.
20
+ mode: offline # A deterministic action fixture, not an LLM.
21
+ release_cms: 1.0 # Requested controlled flow in m3/s.
22
+ prompt: operator.txt # Same contract used when changing to an LLM profile.
23
+ auditors: [feasible_release]
24
+ operator_3:
25
+ reservoir: Lake_3 # Exact physical network key.
26
+ mode: offline # A deterministic action fixture, not an LLM.
27
+ release_cms: 1.0 # Requested controlled flow in m3/s.
28
+ prompt: operator.txt # Same contract used when changing to an LLM profile.
29
+ auditors: [feasible_release]
@@ -0,0 +1 @@
1
+ $observation
@@ -0,0 +1,66 @@
1
+ {
2
+ "schema_version": "llm-reservoir-network-case.v1",
3
+ "data_kind": "synthetic_fixture",
4
+ "network": {
5
+ "schema_version": "llm-reservoir-network.v2",
6
+ "data_kind": "synthetic_fixture",
7
+ "start_date": "2020-02-28",
8
+ "reservoirs": {
9
+ "Lake_1": {
10
+ "inflow_node": "local_1",
11
+ "physical": {
12
+ "reservoir_id": "Lake_1",
13
+ "capacity_m3": 2000000.0,
14
+ "dead_storage_m3": 0.0,
15
+ "initial_storage_m3": 1000000.0,
16
+ "minimum_release_cms": 0.0,
17
+ "maximum_release_cms": 10.0,
18
+ "dt_seconds": 86400.0
19
+ }
20
+ }
21
+ },
22
+ "connections": [
23
+ {
24
+ "source": "Lake_1",
25
+ "target": "outlet",
26
+ "unit_hydrograph": [
27
+ 0.0,
28
+ 1.0
29
+ ]
30
+ }
31
+ ],
32
+ "outlets": [
33
+ "outlet"
34
+ ]
35
+ },
36
+ "inflow_records": [
37
+ {
38
+ "date": "2020-02-28",
39
+ "local_inflow_cms": {
40
+ "local_1": 2.0,
41
+ "outlet": 0.0
42
+ }
43
+ },
44
+ {
45
+ "date": "2020-02-29",
46
+ "local_inflow_cms": {
47
+ "local_1": 2.0,
48
+ "outlet": 0.0
49
+ }
50
+ },
51
+ {
52
+ "date": "2020-03-01",
53
+ "local_inflow_cms": {
54
+ "local_1": 2.0,
55
+ "outlet": 0.0
56
+ }
57
+ },
58
+ {
59
+ "date": "2020-03-02",
60
+ "local_inflow_cms": {
61
+ "local_1": 2.0,
62
+ "outlet": 0.0
63
+ }
64
+ }
65
+ ]
66
+ }
@@ -0,0 +1,17 @@
1
+ # Source-aligned flood-control rule using the same synthetic single-reservoir case.
2
+ schema_version: llm-reservoir-experiment.v2
3
+ case: single.json
4
+ run_id: daily-single-mosart
5
+ output: ../../runs/daily-single-mosart
6
+ max_calls: 0
7
+ extensions:
8
+ mosart_urban: ../rules/mosart_urban/__init__.py
9
+ agents:
10
+ operator_1:
11
+ reservoir_id: Lake_1
12
+ type: rule_based
13
+ rule: mosart_urban
14
+ rule_parameters:
15
+ purpose: flood_control
16
+ alpha: 0.85
17
+ mean_inflow_cms: 2.0 # Explicit teaching mean, m3/s.
@@ -0,0 +1,17 @@
1
+ # Complete synthetic Daily example; no API key, Ollama or model request.
2
+ schema_version: llm-reservoir-experiment.v1
3
+ case: single.json # Prepared local inflows and physical network.
4
+ run_id: daily-single # Trace identity, not a reservoir name.
5
+ output: ../../runs/daily-single # Must not exist; choose a fresh path for another run.
6
+ max_calls: 0 # This offline fixture makes zero model requests.
7
+ auditors:
8
+ feasible_release:
9
+ type: release_bounds
10
+ version: "1"
11
+ agents:
12
+ operator_1:
13
+ reservoir: Lake_1 # Exact physical network key.
14
+ mode: offline # A deterministic action fixture, not an LLM.
15
+ release_cms: 1.0 # Requested controlled flow in m3/s.
16
+ prompt: operator.txt # Same contract used when changing to an LLM profile.
17
+ auditors: [feasible_release]
@@ -0,0 +1,4 @@
1
+ """HydroCNHS native registration of neutral reservoir agents."""
2
+ from llm_reservoir_agent.agent import LLMReservoirAgent
3
+
4
+ __all__ = ["LLMReservoirAgent"]