pvsyst-cli-mcp 0.5.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.
- pvsyst_cli_mcp-0.5.0/LICENSE +21 -0
- pvsyst_cli_mcp-0.5.0/PKG-INFO +150 -0
- pvsyst_cli_mcp-0.5.0/README.md +121 -0
- pvsyst_cli_mcp-0.5.0/pyproject.toml +43 -0
- pvsyst_cli_mcp-0.5.0/setup.cfg +4 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/__init__.py +4 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/__main__.py +4 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/app.py +16 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/components.py +99 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/context.py +291 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/engineering.py +186 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/guidance.py +345 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/projects.py +306 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/results.py +75 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/schemas.py +1055 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/setup.py +40 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/simulation.py +259 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/storage.py +114 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/weather.py +145 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/battery.py +154 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/builder.py +480 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/commercial.py +200 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/curves.py +67 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/editor.py +450 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/generator.py +197 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/identity.py +67 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/pan.py +38 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/single_diode.py +767 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/store.py +1114 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/ac.py +223 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/ageing.py +230 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/auxiliaries.py +161 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/availability.py +57 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/dc.py +493 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/iam.py +261 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/inverter_temperature.py +105 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/load.py +181 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/mismatch.py +123 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/peak.py +260 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/power.py +222 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/power_factor.py +148 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/profiles.py +203 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/soiling.py +118 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/storage.py +823 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/system.py +249 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/tou_planner.py +259 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/transformer.py +103 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/unavailability.py +233 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/brief.py +290 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/comparison.py +572 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/diagnostics.py +993 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/economics.py +1126 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/envelope.py +573 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/handoff.py +239 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/inputs.py +337 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/review.py +178 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/sizing.py +197 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/suggest.py +391 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/_prep.py +213 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/_winlaunch.py +465 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/_workspace_ini.py +234 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/cli.py +1076 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/dc.py +6 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/grid_limit.py +98 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/headless.py +1223 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/horizon.py +233 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/load.py +295 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/p50.py +175 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/project.py +183 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/scene.py +1174 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/bifacial.py +483 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/circuit.py +643 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/domes.py +194 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/fileio.py +105 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/paths.py +69 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/seasonal.py +153 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/sheds.py +217 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/synthesize.py +1730 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/template.py +541 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/tracking.py +339 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_readback.py +381 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_topology.py +480 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_updates.py +538 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_writer.py +156 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variants.py +1098 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/results.py +244 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/author.py +1330 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/ground.py +352 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/mapping.py +1003 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/reader.py +308 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/state.py +183 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/versions.py +35 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/acquisition.py +1164 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/csv.py +350 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/preparation.py +603 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/review.py +442 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/__init__.py +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/batch.py +555 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/bess_optimize.py +807 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/blocks.py +202 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/delivery.py +382 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/design.py +1129 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/feasibility.py +377 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/house.py +701 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/optimize.py +455 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/report.py +845 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/revision.py +533 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/simulation.py +483 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/sourced_design.py +537 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/sourced_house.py +353 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/storage.py +237 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/utility.py +708 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/PKG-INFO +150 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/SOURCES.txt +124 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/dependency_links.txt +1 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/entry_points.txt +2 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/requires.txt +6 -0
- pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Anonymousnake
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pvsyst-cli-mcp
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Workspace-scoped MCP server and Python engineering adapter for installed PVsyst 8 software (PV/BESS sizing, TOU & two-part demand economics, zero-template components, 3D shading, and Plotly reports)
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/Anonymousnake/pvsyst-cli-mcp
|
|
7
|
+
Project-URL: Repository, https://github.com/Anonymousnake/pvsyst-cli-mcp
|
|
8
|
+
Project-URL: Issues, https://github.com/Anonymousnake/pvsyst-cli-mcp/issues
|
|
9
|
+
Project-URL: Releases, https://github.com/Anonymousnake/pvsyst-cli-mcp/releases
|
|
10
|
+
Keywords: pvsyst,solar,photovoltaic,bess,energy-storage,mcp,simulation,renewable-energy
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: mcp<3.0,>=2.0
|
|
25
|
+
Requires-Dist: pydantic<3.0,>=2.0
|
|
26
|
+
Requires-Dist: plotly<7.0,>=5.18
|
|
27
|
+
Requires-Dist: tzdata>=2025.2; sys_platform == "win32"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# PVsyst CLI MCP
|
|
31
|
+
|
|
32
|
+
**English** | [简体中文](README.zh-CN.md)
|
|
33
|
+
|
|
34
|
+
Local MCP server and Python adapter for driving an installed copy of PVsyst 8 on Windows. It wraps `PVsystCLI.exe` for simulations, weather conversion, and license checks, and provides headless parsers, zero-template synthesizers, diagnostics, TOU economics, bounded auto-optimization, and interactive Plotly HTML reporting across `.PRJ`, `.VCx`, `.PAN`, `.OND`, `.BTR`, `.GEN`, `.SIT`, and 3D `.pvc2` shading scenes.
|
|
35
|
+
|
|
36
|
+
You need your own PVsyst installation and license on the host machine.
|
|
37
|
+
|
|
38
|
+
## Common workflows
|
|
39
|
+
|
|
40
|
+
| What you want to do | Main entry point | Guide |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| Run a zero-template fixed-plane or utility ground sheds/tracker PV design (mono/bifacial, finite 3D `site_polygon` + `obstacles` + `base_slope_deg`, optional auto-sizing) | `pvsyst_simulate_design`, `pvsyst_suggest_sizing` | [Single-design inputs](docs/single-design-inputs.md) |
|
|
43
|
+
| Filter workspace/builtin components by electrical specs or synthesize custom `.PAN`/`.OND` (single- or 3-voltage) / Li-ion `.BTR` directly from datasheets (or refit `.PAN` single-diode params on STC edits) | `pvsyst_list_components`, `pvsyst_build_sourced_component`, `pvsyst_update_component` | [Sourced components](docs/sourced-components.md) |
|
|
44
|
+
| Fetch hourly or TMY weather (`Open-Meteo ERA5`, `PVGIS v5.3 TMY`, `NASA POWER`) and optionally chain into `.SIT`/`.MET` preparation | `pvsyst_resolve_location`, `pvsyst_acquire_weather`, `pvsyst_prepare_weather` | [Weather preparation](docs/weather-preparation.md) |
|
|
45
|
+
| Run a parametric sweep (tilt, pitch, albedo, soiling, grid limit) in one CLI call and rank results | `pvsyst_run_batch_sweep` | [Tool reference](docs/tool-reference.md) |
|
|
46
|
+
| Audit completed simulation CSVs (+ optional `.VC0` attribution) and run a bounded Diagnose → Patch → Re-simulate loop on cloned variants | `pvsyst_diagnose_results`, `pvsyst_optimize_variant` | [Tool reference](docs/tool-reference.md) |
|
|
47
|
+
| Plan TOU 2-charge/2-discharge `PowerShift` 48-slot schedules & run two-stage hybrid PV+BESS sizing optimization (fast grid sweep + optional Stage 2 PVsystCLI verification) | `pvsyst_plan_tou_storage_schedule`, `pvsyst_optimize_bess_sizing` | [Tool reference](docs/tool-reference.md) |
|
|
48
|
+
| Evaluate fixed, TOU, and two-part demand-charge tariffs, battery replacement, sensitivity tornadoes, 25-year cashflows, LCOE, NPV, IRR, and payback | `pvsyst_evaluate_economics` | [Tool reference](docs/tool-reference.md) |
|
|
49
|
+
| Run a one-shot end-to-end PV/PV+BESS feasibility study (synthesis → simulation/reuse → diagnostics → BESS sizing → economics → interactive Plotly HTML report) | `pvsyst_run_feasibility_study`, `pvsyst_generate_report`, `pvsyst_export_engineering_delivery` | [Engineering delivery](docs/engineering-delivery.md) |
|
|
50
|
+
| Build a 3D house + obstacles scene, bind roof orientations, and run annual shading (`linear` or `module_layout`) | `pvsyst_run_house_task` | [House task](docs/native-house-task.md) |
|
|
51
|
+
| Prepare hourly or sub-hourly (`5/10/15/30 min`) weather and evaluate AC-coupled storage | `pvsyst_prepare_weather`, `pvsyst_create_grid_storage_system`, `pvsyst_run_simulation` | [Storage engineering](docs/engineering-storage.md) |
|
|
52
|
+
| Inspect an existing project, apply an isolated revision, or diff multiple scenarios | `pvsyst_project_handoff`, `pvsyst_run_engineering_task`, `pvsyst_compare_engineering_scenarios` | [Scenario comparison](docs/engineering-scenarios.md) |
|
|
53
|
+
| Check feasibility briefs or block assembly (requires `expert`) | `pvsyst_review_engineering_brief`, `pvsyst_prepare_block_project` | [Brief review](docs/engineering-brief.md) |
|
|
54
|
+
|
|
55
|
+
By default the server registers **46 core tools across 8 default groups**. `PVSYST_TOOL_GROUPS` is an explicit group list: setting `admin` or `expert` alone replaces the defaults and exposes only that group. Set `PVSYST_TOOL_GROUPS=all` to expose all **75 tools**; to keep the defaults and add `expert`, use `setup,projects,components,weather,storage,simulation,results,engineering,expert`. For migrating from `v0.1.0`, see [Upgrading from v0.1.0](docs/tool-reference.md#upgrading-from-v010).
|
|
56
|
+
|
|
57
|
+
## Installation
|
|
58
|
+
|
|
59
|
+
Requirements:
|
|
60
|
+
- Windows with Python 3.10+
|
|
61
|
+
- Installed `PVsystCLI.exe` (tested against 8.0.6, 8.1.6 rev49278, and 8.1.7 rev49382)
|
|
62
|
+
- Optional legacy GUI mode only (`scene_import_method="gui"`): PVsyst 8.1.6/8.1.7 GUI in Chinese locale at 96 DPI (100% display scaling); 3D house scenes, obstacles, `module_layout`, and DC cabling run headlessly without driving the desktop GUI by default
|
|
63
|
+
|
|
64
|
+
From the repository root:
|
|
65
|
+
|
|
66
|
+
```powershell
|
|
67
|
+
py -m venv .venv
|
|
68
|
+
.\.venv\Scripts\python.exe -m pip install -e .
|
|
69
|
+
$env:PVSYST_CLI = 'C:\Program Files\PVsyst8.1.7\PVsystCLI.exe'
|
|
70
|
+
$env:PVSYST_WORKSPACE = 'C:\path\to\PVsyst8.1_Data'
|
|
71
|
+
.\.venv\Scripts\python.exe -m pvsyst_auto
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Dependencies (`mcp` 2.x, `pydantic` 2.x, `plotly` for interactive HTML reports, and `tzdata` for Windows IANA timezones) are declared in `pyproject.toml`. Running `pip install -r requirements.txt` installs the same editable package; use `pip install .` for a regular install.
|
|
75
|
+
|
|
76
|
+
## MCP client configuration
|
|
77
|
+
|
|
78
|
+
Point your MCP client at the virtualenv Python executable. Launching via `-m pvsyst_auto` (or the installed `pvsyst-mcp` console script) does not depend on the working directory:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"mcpServers": {
|
|
83
|
+
"pvsyst": {
|
|
84
|
+
"command": "C:/path/to/pvsyst-cli-mcp/.venv/Scripts/python.exe",
|
|
85
|
+
"args": ["-m", "pvsyst_auto"],
|
|
86
|
+
"env": {
|
|
87
|
+
"PVSYST_CLI": "C:/Program Files/PVsyst8.1.7/PVsystCLI.exe",
|
|
88
|
+
"PVSYST_WORKSPACE": "C:/path/to/PVsyst8.1_Data"
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`pvsyst_mcp_server.py` at the repo root is kept as a thin wrapper so older client configs still boot. Restart your MCP client after changing environment variables or pulling code updates.
|
|
96
|
+
|
|
97
|
+
Once connected, the server exposes MCP protocol `instructions`, 6 built-in workflow prompts (`design_fixed_or_utility_pv`, `design_rooftop_3d_pv`, `design_pv_with_storage`, `diagnose_and_optimize_simulation`, `ci_bess_feasibility_study`, `optimize_bess_sizing`), and 5 on-demand resources (`pvsyst://guide/workflows`, `pvsyst://guide/variables`, `pvsyst://workspace/projects`, `pvsyst://workspace/components`, `pvsyst://workspace/results`). Run `pvsyst_capabilities` and `pvsyst_license_info` first to confirm CLI flags and remaining license quota (note that PVsyst tracks CLI and GUI licenses separately; license mutation commands remain opt-in under `admin`).
|
|
98
|
+
|
|
99
|
+
### Filtering exposed tool groups
|
|
100
|
+
|
|
101
|
+
By default (when `PVSYST_TOOL_GROUPS` is unset), the server exposes only the **46 core workflow tools** (`setup`, `projects`, `components`, `weather`, `storage`, `simulation`, `results`, `engineering`) so LLM context stays compact. Set `PVSYST_TOOL_GROUPS` in `env` to customize; an explicit list replaces the defaults:
|
|
102
|
+
|
|
103
|
+
- `"PVSYST_TOOL_GROUPS": "all"` exposes all **75 tools** (the 8 default groups plus `admin` and `expert`).
|
|
104
|
+
- `"PVSYST_TOOL_GROUPS": "setup,projects,components,weather,storage,simulation,results,engineering,expert"` keeps the defaults and adds `expert` (71 tools).
|
|
105
|
+
- `"PVSYST_TOOL_GROUPS": "setup,engineering,results"` exposes only those 14 tools.
|
|
106
|
+
- Valid group keys (case-sensitive): `setup`, `projects`, `components`, `weather`, `storage`, `simulation`, `results`, `engineering`, `admin`, `expert` (or `all`). Unknown, empty, or duplicate group names raise an error at startup so typos fail fast.
|
|
107
|
+
|
|
108
|
+
## Understanding task statuses
|
|
109
|
+
|
|
110
|
+
High-level workflow tools return structured status fields so callers can tell the difference between a dry-run check, a file edit, and an actual PVsyst simulation:
|
|
111
|
+
|
|
112
|
+
| Status / Flag | What it means |
|
|
113
|
+
|---|---|
|
|
114
|
+
| `ready` | Dry-run preflight passed; no files were written and PVsyst did not run |
|
|
115
|
+
| `prepared` | Project or input files were written to disk, but no simulation has run yet |
|
|
116
|
+
| `stage=completed` + `native_consumption_verified=true` | PVsyst ran the simulation and output checks (calendar, columns, units) passed |
|
|
117
|
+
| `needs_review` | Simulation or preparation finished, but there are caveats to check (e.g. template-inherited fields, weather time-shift warnings, or missing engineering citations) |
|
|
118
|
+
| `blocked` / `failed` | Preconditions or execution failed; check `issues` and any retained working files before retrying under a new output name |
|
|
119
|
+
|
|
120
|
+
## Package layout
|
|
121
|
+
|
|
122
|
+
```text
|
|
123
|
+
src/pvsyst_auto/
|
|
124
|
+
├── api/ # MCP server setup, protocol guidance (prompts/resources), strict validation, 8 tool modules
|
|
125
|
+
├── workflows/ # End-to-end pipelines (design, utility 3D, batch sweep, optimize loop, house tasks, Plotly HTML report, ZIP delivery)
|
|
126
|
+
├── engineering/ # Sizing assistant, physics diagnostics, financial/TOU economics, handoff, brief checks, scenario comparison
|
|
127
|
+
├── project/ # .PRJ/.VCx parsing, zero-template synthesizer, pvBiFacial, circuits, templates, and orientations
|
|
128
|
+
├── components/ # .PAN/.OND/.BTR/.GEN store + mtime index cache, allowlisted editors, single-diode/Mode-1 datasheet synthesis
|
|
129
|
+
├── scene/ # PVCollada (.pvc2) 3D house mesh & finite 3D ground polygon clipper/shading builder
|
|
130
|
+
├── energy/ # Load profiles, AC-coupled battery storage, loss scalars, and power factor / grid limits
|
|
131
|
+
├── weather/ # Open-Meteo ERA5, PVGIS v5.3 TMY & NASA POWER downloaders, sub-hourly CSV & .SIT/.MET conversion
|
|
132
|
+
├── native/ # Subprocess wrapper for PVsystCLI.exe, headless 3D pvShading/module_layout emitter, and legacy Win32 bridge
|
|
133
|
+
└── results.py # Result CSV parser and hourly/sub-hourly aggregation
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
See [architecture.md](docs/architecture.md) for module responsibilities and old-to-new import paths, and [native-entry-map.md](docs/native-entry-map.md) for the support matrix across PVsyst features.
|
|
137
|
+
|
|
138
|
+
To use the CLI wrapper directly from Python:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from pvsyst_auto import PVsystCLI, PVsystError
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Development & tests
|
|
145
|
+
|
|
146
|
+
Integration and unit test suites live under `tests/integration/` and `tests/unit/`. See the [testing and release guide](docs/testing-and-release.md) for split test slices, CI verification, and release builds. Opt-in real-PVsyst tests live under `tests/e2e/`.
|
|
147
|
+
|
|
148
|
+
## License
|
|
149
|
+
|
|
150
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# PVsyst CLI MCP
|
|
2
|
+
|
|
3
|
+
**English** | [简体中文](README.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
Local MCP server and Python adapter for driving an installed copy of PVsyst 8 on Windows. It wraps `PVsystCLI.exe` for simulations, weather conversion, and license checks, and provides headless parsers, zero-template synthesizers, diagnostics, TOU economics, bounded auto-optimization, and interactive Plotly HTML reporting across `.PRJ`, `.VCx`, `.PAN`, `.OND`, `.BTR`, `.GEN`, `.SIT`, and 3D `.pvc2` shading scenes.
|
|
6
|
+
|
|
7
|
+
You need your own PVsyst installation and license on the host machine.
|
|
8
|
+
|
|
9
|
+
## Common workflows
|
|
10
|
+
|
|
11
|
+
| What you want to do | Main entry point | Guide |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Run a zero-template fixed-plane or utility ground sheds/tracker PV design (mono/bifacial, finite 3D `site_polygon` + `obstacles` + `base_slope_deg`, optional auto-sizing) | `pvsyst_simulate_design`, `pvsyst_suggest_sizing` | [Single-design inputs](docs/single-design-inputs.md) |
|
|
14
|
+
| Filter workspace/builtin components by electrical specs or synthesize custom `.PAN`/`.OND` (single- or 3-voltage) / Li-ion `.BTR` directly from datasheets (or refit `.PAN` single-diode params on STC edits) | `pvsyst_list_components`, `pvsyst_build_sourced_component`, `pvsyst_update_component` | [Sourced components](docs/sourced-components.md) |
|
|
15
|
+
| Fetch hourly or TMY weather (`Open-Meteo ERA5`, `PVGIS v5.3 TMY`, `NASA POWER`) and optionally chain into `.SIT`/`.MET` preparation | `pvsyst_resolve_location`, `pvsyst_acquire_weather`, `pvsyst_prepare_weather` | [Weather preparation](docs/weather-preparation.md) |
|
|
16
|
+
| Run a parametric sweep (tilt, pitch, albedo, soiling, grid limit) in one CLI call and rank results | `pvsyst_run_batch_sweep` | [Tool reference](docs/tool-reference.md) |
|
|
17
|
+
| Audit completed simulation CSVs (+ optional `.VC0` attribution) and run a bounded Diagnose → Patch → Re-simulate loop on cloned variants | `pvsyst_diagnose_results`, `pvsyst_optimize_variant` | [Tool reference](docs/tool-reference.md) |
|
|
18
|
+
| Plan TOU 2-charge/2-discharge `PowerShift` 48-slot schedules & run two-stage hybrid PV+BESS sizing optimization (fast grid sweep + optional Stage 2 PVsystCLI verification) | `pvsyst_plan_tou_storage_schedule`, `pvsyst_optimize_bess_sizing` | [Tool reference](docs/tool-reference.md) |
|
|
19
|
+
| Evaluate fixed, TOU, and two-part demand-charge tariffs, battery replacement, sensitivity tornadoes, 25-year cashflows, LCOE, NPV, IRR, and payback | `pvsyst_evaluate_economics` | [Tool reference](docs/tool-reference.md) |
|
|
20
|
+
| Run a one-shot end-to-end PV/PV+BESS feasibility study (synthesis → simulation/reuse → diagnostics → BESS sizing → economics → interactive Plotly HTML report) | `pvsyst_run_feasibility_study`, `pvsyst_generate_report`, `pvsyst_export_engineering_delivery` | [Engineering delivery](docs/engineering-delivery.md) |
|
|
21
|
+
| Build a 3D house + obstacles scene, bind roof orientations, and run annual shading (`linear` or `module_layout`) | `pvsyst_run_house_task` | [House task](docs/native-house-task.md) |
|
|
22
|
+
| Prepare hourly or sub-hourly (`5/10/15/30 min`) weather and evaluate AC-coupled storage | `pvsyst_prepare_weather`, `pvsyst_create_grid_storage_system`, `pvsyst_run_simulation` | [Storage engineering](docs/engineering-storage.md) |
|
|
23
|
+
| Inspect an existing project, apply an isolated revision, or diff multiple scenarios | `pvsyst_project_handoff`, `pvsyst_run_engineering_task`, `pvsyst_compare_engineering_scenarios` | [Scenario comparison](docs/engineering-scenarios.md) |
|
|
24
|
+
| Check feasibility briefs or block assembly (requires `expert`) | `pvsyst_review_engineering_brief`, `pvsyst_prepare_block_project` | [Brief review](docs/engineering-brief.md) |
|
|
25
|
+
|
|
26
|
+
By default the server registers **46 core tools across 8 default groups**. `PVSYST_TOOL_GROUPS` is an explicit group list: setting `admin` or `expert` alone replaces the defaults and exposes only that group. Set `PVSYST_TOOL_GROUPS=all` to expose all **75 tools**; to keep the defaults and add `expert`, use `setup,projects,components,weather,storage,simulation,results,engineering,expert`. For migrating from `v0.1.0`, see [Upgrading from v0.1.0](docs/tool-reference.md#upgrading-from-v010).
|
|
27
|
+
|
|
28
|
+
## Installation
|
|
29
|
+
|
|
30
|
+
Requirements:
|
|
31
|
+
- Windows with Python 3.10+
|
|
32
|
+
- Installed `PVsystCLI.exe` (tested against 8.0.6, 8.1.6 rev49278, and 8.1.7 rev49382)
|
|
33
|
+
- Optional legacy GUI mode only (`scene_import_method="gui"`): PVsyst 8.1.6/8.1.7 GUI in Chinese locale at 96 DPI (100% display scaling); 3D house scenes, obstacles, `module_layout`, and DC cabling run headlessly without driving the desktop GUI by default
|
|
34
|
+
|
|
35
|
+
From the repository root:
|
|
36
|
+
|
|
37
|
+
```powershell
|
|
38
|
+
py -m venv .venv
|
|
39
|
+
.\.venv\Scripts\python.exe -m pip install -e .
|
|
40
|
+
$env:PVSYST_CLI = 'C:\Program Files\PVsyst8.1.7\PVsystCLI.exe'
|
|
41
|
+
$env:PVSYST_WORKSPACE = 'C:\path\to\PVsyst8.1_Data'
|
|
42
|
+
.\.venv\Scripts\python.exe -m pvsyst_auto
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Dependencies (`mcp` 2.x, `pydantic` 2.x, `plotly` for interactive HTML reports, and `tzdata` for Windows IANA timezones) are declared in `pyproject.toml`. Running `pip install -r requirements.txt` installs the same editable package; use `pip install .` for a regular install.
|
|
46
|
+
|
|
47
|
+
## MCP client configuration
|
|
48
|
+
|
|
49
|
+
Point your MCP client at the virtualenv Python executable. Launching via `-m pvsyst_auto` (or the installed `pvsyst-mcp` console script) does not depend on the working directory:
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"mcpServers": {
|
|
54
|
+
"pvsyst": {
|
|
55
|
+
"command": "C:/path/to/pvsyst-cli-mcp/.venv/Scripts/python.exe",
|
|
56
|
+
"args": ["-m", "pvsyst_auto"],
|
|
57
|
+
"env": {
|
|
58
|
+
"PVSYST_CLI": "C:/Program Files/PVsyst8.1.7/PVsystCLI.exe",
|
|
59
|
+
"PVSYST_WORKSPACE": "C:/path/to/PVsyst8.1_Data"
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`pvsyst_mcp_server.py` at the repo root is kept as a thin wrapper so older client configs still boot. Restart your MCP client after changing environment variables or pulling code updates.
|
|
67
|
+
|
|
68
|
+
Once connected, the server exposes MCP protocol `instructions`, 6 built-in workflow prompts (`design_fixed_or_utility_pv`, `design_rooftop_3d_pv`, `design_pv_with_storage`, `diagnose_and_optimize_simulation`, `ci_bess_feasibility_study`, `optimize_bess_sizing`), and 5 on-demand resources (`pvsyst://guide/workflows`, `pvsyst://guide/variables`, `pvsyst://workspace/projects`, `pvsyst://workspace/components`, `pvsyst://workspace/results`). Run `pvsyst_capabilities` and `pvsyst_license_info` first to confirm CLI flags and remaining license quota (note that PVsyst tracks CLI and GUI licenses separately; license mutation commands remain opt-in under `admin`).
|
|
69
|
+
|
|
70
|
+
### Filtering exposed tool groups
|
|
71
|
+
|
|
72
|
+
By default (when `PVSYST_TOOL_GROUPS` is unset), the server exposes only the **46 core workflow tools** (`setup`, `projects`, `components`, `weather`, `storage`, `simulation`, `results`, `engineering`) so LLM context stays compact. Set `PVSYST_TOOL_GROUPS` in `env` to customize; an explicit list replaces the defaults:
|
|
73
|
+
|
|
74
|
+
- `"PVSYST_TOOL_GROUPS": "all"` exposes all **75 tools** (the 8 default groups plus `admin` and `expert`).
|
|
75
|
+
- `"PVSYST_TOOL_GROUPS": "setup,projects,components,weather,storage,simulation,results,engineering,expert"` keeps the defaults and adds `expert` (71 tools).
|
|
76
|
+
- `"PVSYST_TOOL_GROUPS": "setup,engineering,results"` exposes only those 14 tools.
|
|
77
|
+
- Valid group keys (case-sensitive): `setup`, `projects`, `components`, `weather`, `storage`, `simulation`, `results`, `engineering`, `admin`, `expert` (or `all`). Unknown, empty, or duplicate group names raise an error at startup so typos fail fast.
|
|
78
|
+
|
|
79
|
+
## Understanding task statuses
|
|
80
|
+
|
|
81
|
+
High-level workflow tools return structured status fields so callers can tell the difference between a dry-run check, a file edit, and an actual PVsyst simulation:
|
|
82
|
+
|
|
83
|
+
| Status / Flag | What it means |
|
|
84
|
+
|---|---|
|
|
85
|
+
| `ready` | Dry-run preflight passed; no files were written and PVsyst did not run |
|
|
86
|
+
| `prepared` | Project or input files were written to disk, but no simulation has run yet |
|
|
87
|
+
| `stage=completed` + `native_consumption_verified=true` | PVsyst ran the simulation and output checks (calendar, columns, units) passed |
|
|
88
|
+
| `needs_review` | Simulation or preparation finished, but there are caveats to check (e.g. template-inherited fields, weather time-shift warnings, or missing engineering citations) |
|
|
89
|
+
| `blocked` / `failed` | Preconditions or execution failed; check `issues` and any retained working files before retrying under a new output name |
|
|
90
|
+
|
|
91
|
+
## Package layout
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
src/pvsyst_auto/
|
|
95
|
+
├── api/ # MCP server setup, protocol guidance (prompts/resources), strict validation, 8 tool modules
|
|
96
|
+
├── workflows/ # End-to-end pipelines (design, utility 3D, batch sweep, optimize loop, house tasks, Plotly HTML report, ZIP delivery)
|
|
97
|
+
├── engineering/ # Sizing assistant, physics diagnostics, financial/TOU economics, handoff, brief checks, scenario comparison
|
|
98
|
+
├── project/ # .PRJ/.VCx parsing, zero-template synthesizer, pvBiFacial, circuits, templates, and orientations
|
|
99
|
+
├── components/ # .PAN/.OND/.BTR/.GEN store + mtime index cache, allowlisted editors, single-diode/Mode-1 datasheet synthesis
|
|
100
|
+
├── scene/ # PVCollada (.pvc2) 3D house mesh & finite 3D ground polygon clipper/shading builder
|
|
101
|
+
├── energy/ # Load profiles, AC-coupled battery storage, loss scalars, and power factor / grid limits
|
|
102
|
+
├── weather/ # Open-Meteo ERA5, PVGIS v5.3 TMY & NASA POWER downloaders, sub-hourly CSV & .SIT/.MET conversion
|
|
103
|
+
├── native/ # Subprocess wrapper for PVsystCLI.exe, headless 3D pvShading/module_layout emitter, and legacy Win32 bridge
|
|
104
|
+
└── results.py # Result CSV parser and hourly/sub-hourly aggregation
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
See [architecture.md](docs/architecture.md) for module responsibilities and old-to-new import paths, and [native-entry-map.md](docs/native-entry-map.md) for the support matrix across PVsyst features.
|
|
108
|
+
|
|
109
|
+
To use the CLI wrapper directly from Python:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
from pvsyst_auto import PVsystCLI, PVsystError
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Development & tests
|
|
116
|
+
|
|
117
|
+
Integration and unit test suites live under `tests/integration/` and `tests/unit/`. See the [testing and release guide](docs/testing-and-release.md) for split test slices, CI verification, and release builds. Opt-in real-PVsyst tests live under `tests/e2e/`.
|
|
118
|
+
|
|
119
|
+
## License
|
|
120
|
+
|
|
121
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "pvsyst-cli-mcp"
|
|
7
|
+
version = "0.5.0"
|
|
8
|
+
description = "Workspace-scoped MCP server and Python engineering adapter for installed PVsyst 8 software (PV/BESS sizing, TOU & two-part demand economics, zero-template components, 3D shading, and Plotly reports)"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = {text = "MIT"}
|
|
12
|
+
keywords = ["pvsyst", "solar", "photovoltaic", "bess", "energy-storage", "mcp", "simulation", "renewable-energy"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 4 - Beta",
|
|
15
|
+
"Intended Audience :: Science/Research",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Operating System :: Microsoft :: Windows",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Topic :: Scientific/Engineering",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"mcp>=2.0,<3.0",
|
|
27
|
+
"pydantic>=2.0,<3.0",
|
|
28
|
+
"plotly>=5.18,<7.0",
|
|
29
|
+
"tzdata>=2025.2; sys_platform == 'win32'",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
pvsyst-mcp = "pvsyst_auto.api.app:main"
|
|
34
|
+
|
|
35
|
+
[project.urls]
|
|
36
|
+
Homepage = "https://github.com/Anonymousnake/pvsyst-cli-mcp"
|
|
37
|
+
Repository = "https://github.com/Anonymousnake/pvsyst-cli-mcp"
|
|
38
|
+
Issues = "https://github.com/Anonymousnake/pvsyst-cli-mcp/issues"
|
|
39
|
+
Releases = "https://github.com/Anonymousnake/pvsyst-cli-mcp/releases"
|
|
40
|
+
|
|
41
|
+
[tool.setuptools.packages.find]
|
|
42
|
+
where = ["src"]
|
|
43
|
+
include = ["pvsyst_auto*"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""PVsyst api operations."""
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""Compose selected tool groups and launch the stdio server."""
|
|
2
|
+
from importlib import import_module
|
|
3
|
+
|
|
4
|
+
from .context import (ACTIVE_TOOL_GROUPS, ACTIVE_TOOL_NAMES, STRICT_ARGUMENT_TOOLS,
|
|
5
|
+
_strict_arguments, create_mcp_server, import_modules_for_groups, mcp)
|
|
6
|
+
|
|
7
|
+
for module in import_modules_for_groups(ACTIVE_TOOL_GROUPS):
|
|
8
|
+
import_module(f".{module}", __package__)
|
|
9
|
+
|
|
10
|
+
_expected_strict = set(STRICT_ARGUMENT_TOOLS) & ACTIVE_TOOL_NAMES
|
|
11
|
+
if set(_strict_arguments) != _expected_strict:
|
|
12
|
+
raise RuntimeError(f"Unregistered strict entry points: {sorted(_expected_strict - set(_strict_arguments))}")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def main():
|
|
16
|
+
mcp.run(transport="stdio")
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
"""Components MCP operations; native and domain behavior stays in the existing modules."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from typing import Annotated, Literal
|
|
5
|
+
from pydantic import Field, StrictBool, StrictInt, StrictStr
|
|
6
|
+
from pvsyst_auto.components.builder import build_sourced_component
|
|
7
|
+
from pvsyst_auto.api.schemas import SourceDeclarationRequest, SourceTextRequest, StrictNum
|
|
8
|
+
from pvsyst_auto.api.context import categorized_tool, component_call, components
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@categorized_tool()
|
|
12
|
+
def pvsyst_list_components(component_type: str, library: str = "workspace",
|
|
13
|
+
query: str = "", offset: StrictInt = 0, limit: StrictInt = 100,
|
|
14
|
+
min_power_w: StrictNum | None = None,
|
|
15
|
+
max_power_w: StrictNum | None = None,
|
|
16
|
+
bifacial: StrictBool | None = None,
|
|
17
|
+
min_system_voltage_v: StrictNum | None = None,
|
|
18
|
+
min_mppt: StrictInt | None = None,
|
|
19
|
+
manufacturer: StrictStr | None = None) -> dict:
|
|
20
|
+
"""List PAN, OND, BTR, GEN or REV loose files in workspace or installed DataRO with
|
|
21
|
+
optional electrical filtering (power range, bifaciality, system voltage, MPPT count,
|
|
22
|
+
manufacturer) backed by an mtime-keyed metadata cache."""
|
|
23
|
+
return components().list(
|
|
24
|
+
component_type, library, query, offset, limit,
|
|
25
|
+
min_power_w=min_power_w, max_power_w=max_power_w,
|
|
26
|
+
bifacial=bifacial, min_system_voltage_v=min_system_voltage_v,
|
|
27
|
+
min_mppt=min_mppt, manufacturer=manufacturer,
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
@categorized_tool()
|
|
31
|
+
def pvsyst_get_component(component_type: str, filename: str,
|
|
32
|
+
library: str = "workspace", offset: StrictInt = 0,
|
|
33
|
+
limit: StrictInt = 100, include_curve_csv: StrictBool = False) -> dict:
|
|
34
|
+
"""Read paged UTF-8 text, editable scalar allowlist, SHA-256, OND/BTR curves,
|
|
35
|
+
commercial fields, and remarks for a PAN, OND, BTR, GEN, or REV component."""
|
|
36
|
+
return component_call("inspect", component_type, filename, library, offset, limit, include_curve_csv)
|
|
37
|
+
|
|
38
|
+
@categorized_tool()
|
|
39
|
+
def pvsyst_validate_component(component_type: str, filename: str,
|
|
40
|
+
library: str = "workspace") -> dict:
|
|
41
|
+
"""Validate structure, required fields, and numeric bounds of a component file."""
|
|
42
|
+
return component_call("validate", component_type, filename, library)
|
|
43
|
+
|
|
44
|
+
@categorized_tool()
|
|
45
|
+
def pvsyst_create_component(component_type: str, filename: str, content: str) -> dict:
|
|
46
|
+
"""Create a new PAN, OND, BTR, GEN, or REV file in the workspace from UTF-8 PVObject_ text."""
|
|
47
|
+
return component_call("create", component_type, filename, content)
|
|
48
|
+
|
|
49
|
+
@categorized_tool()
|
|
50
|
+
def pvsyst_update_component(component_type: str, filename: str,
|
|
51
|
+
updates: dict[str, str],
|
|
52
|
+
expected_sha256: str | None = None, dry_run: StrictBool = False,
|
|
53
|
+
curve_updates: dict[str, list[list[StrictNum]]] | None = None,
|
|
54
|
+
use_file_curve: StrictBool = False,
|
|
55
|
+
commercial_updates: dict[str, str] | None = None,
|
|
56
|
+
remarks: list[str] | None = None,
|
|
57
|
+
curve_csv: dict[str, str] | None = None,
|
|
58
|
+
refit_single_diode: StrictBool = False) -> dict:
|
|
59
|
+
"""Update allowlisted scalar fields, commercial metadata, remarks (up to 5 lines),
|
|
60
|
+
or Mode 1 OND (single- or 3-voltage ProfilPIOV1..3) / BTR curve tables (4..256 points
|
|
61
|
+
via curve_updates or curve_csv) in a workspace component with SHA-256 optimistic locking
|
|
62
|
+
and automatic backup. Set refit_single_diode=true on PAN STC edits to refit single-diode params."""
|
|
63
|
+
return component_call("update", component_type, filename, updates,
|
|
64
|
+
expected_sha256, dry_run, curve_updates, use_file_curve,
|
|
65
|
+
commercial_updates, remarks, curve_csv, refit_single_diode)
|
|
66
|
+
|
|
67
|
+
@categorized_tool()
|
|
68
|
+
def pvsyst_compare_components(component_type: str, first: str, second: str,
|
|
69
|
+
second_library: str = "workspace") -> dict:
|
|
70
|
+
"""Compare two same-type components by text diff or binary SHA-256."""
|
|
71
|
+
return component_call("compare", component_type, first, second, second_library)
|
|
72
|
+
|
|
73
|
+
@categorized_tool()
|
|
74
|
+
def pvsyst_project_components(project: str, variant: str) -> dict:
|
|
75
|
+
"""List PAN, OND, BTR, and GEN references used by a project variant."""
|
|
76
|
+
return component_call("dependencies", project, variant)
|
|
77
|
+
|
|
78
|
+
@categorized_tool()
|
|
79
|
+
def pvsyst_build_sourced_component(
|
|
80
|
+
component_type: Literal["PAN", "OND", "BTR"], new_name: StrictStr,
|
|
81
|
+
manufacturer: StrictStr, model: StrictStr,
|
|
82
|
+
sources: Annotated[dict[str, SourceTextRequest], Field(min_length=1, max_length=16)],
|
|
83
|
+
declarations: Annotated[list[SourceDeclarationRequest], Field(min_length=1, max_length=32)],
|
|
84
|
+
template_name: StrictStr | None = None,
|
|
85
|
+
chemistry: Literal["LFP", "NMC"] = "LFP",
|
|
86
|
+
source_library: Literal["workspace", "builtin"] = "workspace", dry_run: StrictBool = True,
|
|
87
|
+
acknowledge_inherited_model: StrictBool = False) -> dict:
|
|
88
|
+
"""Build a new user-defined PAN, OND, or Li-ion BTR from cited datasheet values: either derived
|
|
89
|
+
from a template (template_name set) or synthesized zero-template with single-diode / single- or
|
|
90
|
+
3-voltage Mode-1 OND / Li-ion LFP-NMC BTR derivation (template_name omitted). Requires
|
|
91
|
+
acknowledge_inherited_model=true when dry_run=false."""
|
|
92
|
+
return build_sourced_component(
|
|
93
|
+
components(), component_type=component_type, template_name=template_name, new_name=new_name,
|
|
94
|
+
manufacturer=manufacturer, model=model,
|
|
95
|
+
sources={key: entry.model_dump(exclude_none=True) for key, entry in sources.items()},
|
|
96
|
+
declarations=[entry.model_dump(exclude_none=True) for entry in declarations],
|
|
97
|
+
chemistry=chemistry,
|
|
98
|
+
source_library=source_library, dry_run=dry_run,
|
|
99
|
+
acknowledge_inherited_model=acknowledge_inherited_model)
|