Repository navigation
v0.5.0
pvsyst-cli-mcp v0.5.0
C&I PV+BESS Economics & Sizing, Zero-Template Li-ion BTR & 3-Voltage OND Synthesis, One-Shot Feasibility Study, and CI/PyPI Readiness
Highlights
1. C&I PV+BESS Economics, TOU PowerShift Planner & Hybrid Sizing Optimizer
- Two-part demand-charge tariffs (
tariff.demand_charge): supports monthly maximum-demand billing (demand), transformer contract-capacity billing (capacity), and automatic side-by-side comparison (compare) with recommended billing mode, baseline vs. post-PV/BESS peak shaving, and annual demand-charge savings. - Mid-life battery replacement & sensitivity tornado: models mid-life BESS pack replacement (
battery_replacement_year,battery_replacement_cost_ratio/battery_replacement_cost) and deterministic one-at-a-time sensitivity sweeps (tariff,capex,yield,degradation) sorted by NPV swing. - Interactive Plotly report upgrades (
pvsyst_generate_report): adds monthly peak-demand shaving comparison, financial sensitivity tornado, and 2D BESS sizing NPV heatmap + Pareto frontier charts (in both Chinese and English). - TOU →
PowerShift48-slot planner (pvsyst_plan_tou_storage_schedule): converts arbitrary TOU tariff schedules into 1- or 2-cycle/day PVsystPowerShift48 half-hour slots with minimum arbitrage spread guard and usable-energy power capping, returning drop-inGridStorageUpdates. - Two-stage hybrid PV+BESS sizing optimizer (
pvsyst_optimize_bess_sizing):- Stage 1: fast pure-Python grid sweep over
bess_kwh × pcs_kw × strategy(self_consumption,tou_arbitrage,peak_shaving) producing ranked candidates, 2D NPV heatmap, and CAPEX-vs-NPV Pareto frontier. - Stage 2 (optional): reconciles the top-K candidates via real
PVsystCLI8760-hour simulations (verify_top_k, guarded bydry_run=True+confirm=True).
- Stage 1: fast pure-Python grid sweep over
2. Zero-Template Li-ion .BTR, 3-Voltage .OND, and Optional .PAN Refit (Verified on PVsyst 8.1.7)
- Zero-template Li-ion
.BTRsynthesis (pvsyst_build_sourced_component(component_type="BTR")): synthesizesLFPandNMCLi-ion battery definitions directly from datasheet parameters, enforcing PVsyst 8.1.7 per-cell voltage, internal resistance (≤ 40 mV/cell @ I10),AlphaSOC, andCapaCourantvalidation rules. - 3-voltage efficiency curve
.ONDsynthesis & editing: supportsFlags=$1560,VNomEff,EfficMaxV,EfficEuroV, andProfilPIOV1..V3in both zero-template synthesis andpvsyst_update_componentcurve updates (preserving full backward compatibility for single-voltage.ONDfiles). - Optional
.PANsingle-diode auto-refit: passingrefit_single_diode=Trueonpvsyst_update_componentrecomputesRShunt,Rp_0,Rp_Exp,RSerie,Gamma, andmuGammafrom updated STC specs (refit_single_diode=Falsedefault preserves 100% legacy behavior).
3. One-Shot Feasibility Study, Runtime Resilience & MCP Discovery
- One-shot feasibility study orchestrator (
pvsyst_run_feasibility_study): chains inline zero-template component synthesis, simulation or existing CSV reuse, loss diagnostics, TOU schedule generation, hybrid BESS sizing, two-part economics + sensitivity, and interactive Plotly HTML report generation in one guarded workflow (dry_run=Truedefault,confirm=Truerequired for execution). PVsystCLItransient abort retry: automatically retries transient startup/mid-check aborts (PVSYST_CLI_TRANSIENT_RETRIES, default1) while never retrying license, syntax, model, or timeout failures.- Dynamic MCP Resources & Prompts:
- 3 new read-only workspace resources:
pvsyst://workspace/projects,pvsyst://workspace/components,pvsyst://workspace/results(5 resources total). - 2 new workflow prompts:
ci_bess_feasibility_studyandoptimize_bess_sizing(6 prompts total).
- 3 new read-only workspace resources:
4. Upstream Hardening (PRs #194–#221) & CI / PyPI Readiness
- Includes all reliability fixes from PRs #194–#221 (regular-cadence timestamp enforcement in economics/report, self-consumption yield alignment, primary scenario promotion, OND curve floor scaling, near-shading loss diagnostics, batch parameter wiring, asymmetric MPPT guards, and strict
dry_runguidance). - Upgraded GitHub Actions CI to Node 24-native majors (
actions/checkout@v7,actions/setup-python@v7,actions/upload-artifact@v7,actions/download-artifact@v8) and fixed tag release uploads to avoid duplicate drafts. - Added PyPI OIDC Trusted Publishing workflow (
.github/workflows/publish-pypi.yml) and completepyproject.tomlpackage metadata.
Tool Surface & Verification
- MCP surface: 46 default tools (
43 → 46:+pvsyst_plan_tou_storage_schedule,+pvsyst_optimize_bess_sizing,+pvsyst_run_feasibility_study), 75 total tools (PVSYST_TOOL_GROUPS=all), 5 resources, 6 prompts. - Offline CI & unit tests:
scripts/ci_checks.py31/31 OK (0 skips) +scripts/run_tests.py --suite unit447/447 OK (0 skips). - Live
PVsystCLI 8.1.7verification: 0 warnings across full 8760-hour runs covering refitted.PAN+ edited 3-voltage.ONDand zero-template LFP.BTR+ TOUPowerShift48-slot storage.