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.
Files changed (126) hide show
  1. pvsyst_cli_mcp-0.5.0/LICENSE +21 -0
  2. pvsyst_cli_mcp-0.5.0/PKG-INFO +150 -0
  3. pvsyst_cli_mcp-0.5.0/README.md +121 -0
  4. pvsyst_cli_mcp-0.5.0/pyproject.toml +43 -0
  5. pvsyst_cli_mcp-0.5.0/setup.cfg +4 -0
  6. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/__init__.py +4 -0
  7. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/__main__.py +4 -0
  8. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/__init__.py +1 -0
  9. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/app.py +16 -0
  10. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/components.py +99 -0
  11. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/context.py +291 -0
  12. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/engineering.py +186 -0
  13. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/guidance.py +345 -0
  14. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/projects.py +306 -0
  15. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/results.py +75 -0
  16. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/schemas.py +1055 -0
  17. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/setup.py +40 -0
  18. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/simulation.py +259 -0
  19. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/storage.py +114 -0
  20. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/api/weather.py +145 -0
  21. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/__init__.py +1 -0
  22. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/battery.py +154 -0
  23. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/builder.py +480 -0
  24. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/commercial.py +200 -0
  25. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/curves.py +67 -0
  26. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/editor.py +450 -0
  27. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/generator.py +197 -0
  28. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/identity.py +67 -0
  29. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/pan.py +38 -0
  30. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/single_diode.py +767 -0
  31. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/components/store.py +1114 -0
  32. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/__init__.py +1 -0
  33. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/ac.py +223 -0
  34. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/ageing.py +230 -0
  35. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/auxiliaries.py +161 -0
  36. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/availability.py +57 -0
  37. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/dc.py +493 -0
  38. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/iam.py +261 -0
  39. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/inverter_temperature.py +105 -0
  40. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/load.py +181 -0
  41. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/mismatch.py +123 -0
  42. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/peak.py +260 -0
  43. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/power.py +222 -0
  44. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/power_factor.py +148 -0
  45. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/profiles.py +203 -0
  46. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/soiling.py +118 -0
  47. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/storage.py +823 -0
  48. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/system.py +249 -0
  49. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/tou_planner.py +259 -0
  50. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/transformer.py +103 -0
  51. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/energy/unavailability.py +233 -0
  52. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/__init__.py +1 -0
  53. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/brief.py +290 -0
  54. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/comparison.py +572 -0
  55. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/diagnostics.py +993 -0
  56. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/economics.py +1126 -0
  57. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/envelope.py +573 -0
  58. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/handoff.py +239 -0
  59. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/inputs.py +337 -0
  60. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/review.py +178 -0
  61. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/sizing.py +197 -0
  62. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/engineering/suggest.py +391 -0
  63. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/__init__.py +1 -0
  64. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/_prep.py +213 -0
  65. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/_winlaunch.py +465 -0
  66. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/_workspace_ini.py +234 -0
  67. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/cli.py +1076 -0
  68. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/dc.py +6 -0
  69. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/grid_limit.py +98 -0
  70. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/headless.py +1223 -0
  71. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/horizon.py +233 -0
  72. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/load.py +295 -0
  73. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/p50.py +175 -0
  74. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/project.py +183 -0
  75. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/native/scene.py +1174 -0
  76. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/__init__.py +1 -0
  77. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/bifacial.py +483 -0
  78. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/circuit.py +643 -0
  79. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/domes.py +194 -0
  80. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/fileio.py +105 -0
  81. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/paths.py +69 -0
  82. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/seasonal.py +153 -0
  83. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/sheds.py +217 -0
  84. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/synthesize.py +1730 -0
  85. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/template.py +541 -0
  86. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/tracking.py +339 -0
  87. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_readback.py +381 -0
  88. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_topology.py +480 -0
  89. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_updates.py +538 -0
  90. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variant_writer.py +156 -0
  91. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/project/variants.py +1098 -0
  92. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/results.py +244 -0
  93. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/__init__.py +1 -0
  94. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/author.py +1330 -0
  95. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/ground.py +352 -0
  96. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/mapping.py +1003 -0
  97. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/reader.py +308 -0
  98. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/scene/state.py +183 -0
  99. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/versions.py +35 -0
  100. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/__init__.py +1 -0
  101. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/acquisition.py +1164 -0
  102. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/csv.py +350 -0
  103. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/preparation.py +603 -0
  104. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/weather/review.py +442 -0
  105. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/__init__.py +1 -0
  106. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/batch.py +555 -0
  107. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/bess_optimize.py +807 -0
  108. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/blocks.py +202 -0
  109. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/delivery.py +382 -0
  110. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/design.py +1129 -0
  111. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/feasibility.py +377 -0
  112. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/house.py +701 -0
  113. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/optimize.py +455 -0
  114. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/report.py +845 -0
  115. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/revision.py +533 -0
  116. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/simulation.py +483 -0
  117. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/sourced_design.py +537 -0
  118. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/sourced_house.py +353 -0
  119. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/storage.py +237 -0
  120. pvsyst_cli_mcp-0.5.0/src/pvsyst_auto/workflows/utility.py +708 -0
  121. pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/PKG-INFO +150 -0
  122. pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/SOURCES.txt +124 -0
  123. pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/dependency_links.txt +1 -0
  124. pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/entry_points.txt +2 -0
  125. pvsyst_cli_mcp-0.5.0/src/pvsyst_cli_mcp.egg-info/requires.txt +6 -0
  126. 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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """Public Python adapter for installed PVsyst; no bundled simulator."""
2
+ from .native.cli import PVsystCLI, PVsystError
3
+
4
+ __all__ = ["PVsystCLI", "PVsystError"]
@@ -0,0 +1,4 @@
1
+ from .api.app import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
@@ -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)