renewable-energy-potential-forecast-agent-skill

renewable-energy-potential-forecast

A research-first, framework-grounded skill that estimates rooftop-solar and small-wind generation potential for any coordinate and produces a bankable feasibility report: annual energy, capacity factor, LCOE, payback, NPV, a tiered recommendation, and a prioritized effort x impact roadmap.

---

Why this exists

Property owners and small developers cannot tell whether rooftop solar or a small wind turbine is worth it at their exact location. This skill turns a coordinate and a short site description into a defensible go/no-go estimate using standard, citable engineering models, then continuously refreshes the meteorology and policy data behind it.

It is built to be bankable, not chatty:

• Every numeric judgment is grounded in a named framework (PVWatts/PVGIS, Weibull, LCOE, NASA POWER) -- never an ad-hoc rubric.
• It prefers freshly retrieved evidence over memory, and degrades gracefully and explicitly when offline.
• The deliverable is a professional artifact (a scored report + roadmap), with quality gates enforced before anything is shown.

---

What it produces

For a site coordinate and scenario, the harness returns a Markdown report with six sections (and a machine-readable JSON twin):

1. Executive summary -- verdict + headline tier + key numbers.
2. Inputs & assumptions -- provided vs assumed (every assumption cites its framework/default).
3. Multi-dimensional score -- each dimension scored against its named framework, with evidence citations and degradation flags.
4. Findings -- strengths, risks, gaps.
5. Improvement roadmap -- prioritized actions ranked by effort x impact, with sensitivity notes.
6. Sources & limitations -- citations and graceful-degradation notes.

Each resource gets a Score (annual kWh, capacity factor, LCOE, payback, NPV) and the whole site gets a Recommendation tier:

Tier	Meaning
A	Recommended -- bankable: good resource, LCOE below grid tariff, payback <= 8 yr, policy supports export.
B	Conditional -- meets 3 of 4; one swing variable to resolve.
C	Marginal -- pursue only with an incentive or assumption change.
D	Weak -- resource insufficient (e.g. wind power density < 100 W/m^2).
REJECT	Out of scope or unscorable (e.g. > 1 MW, missing inputs).

---

Governing frameworks

All scoring is grounded in these named frameworks. The implementation lives in the tools/ package.

1. PVWatts / PVGIS photovoltaic yield -- GHI/DNI/DHI, plane-of-array transposition (Liu-Jordan isotropic; Erbs diffuse-fraction), tilt/azimuth, the PVWatts v8 loss tree (soiling, mismatch, wiring, connections, inverter, availability, degradation). -- tools/solar_model.py
2. Weibull small-wind resource -- power density = 1/2 * rho * E[v^3]; Weibull k/c (Rayleigh when only the mean is known); AEP via power-curve x pdf integration. -- tools/wind_model.py
3. Capacity factor, LCOE & simple payback -- LCOE = (CAPEX * CRF + O&M) / AEP; CRF = r(1+r)^n / ((1+r)^n - 1); simple payback = CAPEX / annual savings. -- tools/economics.py
4. Solar irradiance datasets & shading -- GHI/DNI/DHI decomposition; user-supplied shading loss applied inside the PVWatts loss tree.
5. Net-metering / feed-in policy -- country tariff and net-metering flags screened from a bundled policy table (never invented). -- tools/met_data.py
6. Performance ratio & degradation -- PR default 0.80-0.86 (PVWatts); linear 0.5%/yr degradation for lifetime NPV.

---

Architecture

renewable-energy-potential-forecast (skills/main.md + tools/harness.py)
  |
  |-- sub-evaluation-framework-selector   intake, validation, framework selection
  |-- sub-met-data-updater                NASA POWER fetch + climatology fallback + policy
  |-- sub-scoring-engine                 PVWatts/PVGIS + Weibull + economics -> tier
  |-- sub-improvement-roadmap            optimal orientation, sizing, financing, sensitivity
  |-- knowledge refresh                  tools/knowledge_updater.py -> SECOND-KNOWLEDGE-BRAIN.md
  |-- evidence + framework + challenge gates
  '-- SYNTHESIZE                         scored report + prioritized roadmap

The skill is two views of the same harness:

• Claude Agent Skill: markdown harness in skills/ (the Skill-tool runtime invokes the sub-skills in order).
• Standalone Python: tools/harness.py (python -m tools.harness ...) executes the identical pipeline with the real math.

---

Repository layout

.
|-- skills/                          Claude Agent Skill harness (markdown)
|   |-- main.md                      harness entry point + governing frameworks + output format
|   |-- sub-evaluation-framework-selector.md
|   |-- sub-scoring-engine.md
|   |-- sub-met-data-updater.md
|   '-- sub-improvement-roadmap.md
|-- tools/                           Real, runnable Python implementation (stdlib only)
|   |-- __init__.py
|   |-- schemas.py                   typed request/report/stage objects
|   |-- solar_model.py               Erbs / Liu-Jordan / PVWatts solar yield
|   |-- wind_model.py                Weibull + power-curve AEP
|   |-- economics.py                 LCOE / payback / NPV + IRENA defaults
|   |-- met_data.py                  NASA POWER client + climatology fallback + policy table
|   |-- scoring.py                   sub-scoring-engine wiring -> recommendation tier
|   |-- gates.py                     evidence / framework / challenge gates
|   |-- harness.py                   orchestrator + CLI
|   '-- knowledge_updater.py         SECOND-KNOWLEDGE-BRAIN crawler/updater
|-- tests/
|   |-- test_harness.py              pytest suite (11 tests)
|   |-- test-scenarios.md            scenario spec + captured offline baselines
|   '-- fixtures/*.json              6 scenario fixtures
|-- docs/
|   |-- SHARED-SCORING-SCHEMA.md     cluster-wide scoring schema
|   '-- CROSS-SKILL-WIRING.md        reuse contract for sibling skills
|-- SECOND-KNOWLEDGE-BRAIN.md        self-improving knowledge base
|-- PROJECT-detail.md                full technical spec
|-- PROJECT-DEVELOPMENT-PHASE-TRACKING.md   phase roadmap (all phases complete)
|-- CLAUDE.md                        skill index
|-- LICENSE
|-- .gitignore
'-- README.md

---

Install

Requires Python 3.9+ and no third-party dependencies (standard library only).

git clone https://github.com/dungnotnull/renewable-energy-potential-forecast-agent-skill.git
cd renewable-energy-potential-forecast-agent-skill

Optional, only for the richer domain crawl in the knowledge updater:

pip install crawl4ai   # optional; the updater falls back to stdlib fetch if absent

For the test suite (optional):

pip install pytest

---

Quickstart

Solar rooftop estimate (offline, bundled climatology)

python -m tools.harness --lat 21.0 --lon 105.85 --scenario solar \
    --roof-area 60 --tilt 21 --azimuth 0 --country VN --no-fetch

Compare solar vs small wind, JSON output

python -m tools.harness --lat 13.0 --lon 109.0 --scenario compare \
    --roof-area 80 --turbine-kw 10 --country VN --format json --out report.json

Full request via JSON

python -m tools.harness --request-json '{"latitude":35,"longitude":139,"scenario":"solar","roof_area_m2":50,"country":"JP"}'

With network access, omit --no-fetch to pull live NASA POWER monthly climatology for the coordinate.

---

CLI reference

python -m tools.harness [options]

  --request-json JSON      Full ForecastRequest as a JSON string.
  --lat FLOAT              Site latitude (-90..90).
  --lon FLOAT              Site longitude (-180..180).
  --scenario {solar,wind,compare}   Resource scenario (default: solar).
  --roof-area FLOAT        Usable roof area in m^2 (solar).
  --system-kw FLOAT        DC system size in kW (solar; alternative to roof-area).
  --tilt FLOAT             Tilt in degrees (solar; default: |latitude|).
  --azimuth FLOAT          Azimuth in degrees, PVWatts convention 0=South, 90=West (solar).
  --shading-loss FLOAT     Shading loss fraction 0..0.8 (solar).
  --pr FLOAT              Performance ratio 0.5..1.0 (solar; default 0.85).
  --hub-height FLOAT       Hub height in m (wind; default: rated-kw heuristic).
  --turbine-kw FLOAT       Turbine rated power in kW (wind; required).
  --capex FLOAT            CAPEX per kW (default: IRENA regional band).
  --om FLOAT               O&M per kW per year (default: IRENA regional band).
  --discount FLOAT         Discount rate (default 0.06).
  --lifetime INT           System lifetime in years (default 25).
  --import-tariff FLOAT    Grid import tariff in currency/kWh.
  --export-tariff FLOAT    Export tariff in currency/kWh.
  --net-metering           Enable net-metering (export at retail).
  --self-consumption FLOAT Self-consumption fraction 0..1 (default 0.5).
  --country STR            ISO-3166 alpha-2 country for policy screening.
  --currency STR           Currency code (default USD).
  --validate-only          Validate the request and print the selection; do not score.
  --no-fetch               Use the bundled climatology fallback (offline).
  --format {markdown,json} Output format (default markdown).
  --out PATH               Write output to a file instead of stdout.

Key inputs

Field	Required when	Default	Source of default
latitude, longitude	always	--	--
scenario	always	solar	--
roof_area_m2 or system_kw_dc	solar / compare	derived from roof	85% utilization, 200 Wp/m^2
tilt_deg	solar / compare	abs(latitude)	latitude-tilt rule
azimuth_deg	solar / compare	0 (NH) / 180 (SH)	equator-facing
turbine_rated_kw	wind / compare	--	--
capex_per_kw, om_per_kw_year	optional	IRENA band	IRENA cost reports
tariff_import_usd_kwh	optional	policy table	net-metering/FIT policy

---

Example output

# Renewable Energy Potential Forecast

## 1. Executive summary
**Verdict (C):** Marginal: solar only with an incentive or assumption change.
solar: 14408 kWh/yr, CF 16.1%, LCOE 0.0917 USD/kWh, payback 10.2 yr

## 3. Multi-dimensional score
| Resource | Annual kWh | Capacity factor | LCOE USD/kWh | Payback yr | NPV | Tier-driving framework |
|---|---|---|---|---|---|---|
| solar | 14408 | 16.1% | 0.0917 | 10.2 | ... | PVWatts v8; PVGIS; Liu-Jordan/Klein transposition |

## 5. Improvement roadmap
| # | Action | Impact | Effort | Framework |
|---|---|---|---|---|
| 1 | Set tilt to 20 deg and azimuth to 0 deg | high | S | PVWatts/PVGIS |
| 2 | Enroll in net-metering / export scheme | high | S | Net-metering/FIT policy |
| 3 | Verify shading with on-site survey | med | M | shading/horizon |

## 6. Sources & limitations
- PVWatts v8
- PVGIS
- Liu-Jordan/Klein transposition
- Erbs 1982 diffuse fraction
- IRENA cost reports
- Limitation: Meteorology from fallback; not live reanalysis.

**Challenge (devil's advocate):** If GHI/wind were 20% lower or CAPEX 20% higher,
payback rises to ~15.3 yr, which may drop the tier by one level.

---

Knowledge base refresh

The self-improving SECOND-KNOWLEDGE-BRAIN.md is grown by tools/knowledge_updater.py: ArXiv (categories physics.ao-ph, eess.SY) plus an optional crawl4ai / stdlib scan of authoritative domains (nrel.gov, globalwindatlas.info, irena.org, re.jrc.ec.europa.eu). Entries are scored by recency + relevance and deduplicated by a sha1 hash of URL/DOI.

python tools/knowledge_updater.py --check-stale        # cron gate: stale=true/false
python tools/knowledge_updater.py --dry-run            # preview new entries (no write)
python tools/knowledge_updater.py --since 2026-01-01   # live append to the brain
python tools/knowledge_updater.py --no-domain-crawl   # ArXiv only

Recommended schedule: weekly cron, gated on --check-stale. The updater degrades gracefully: if the network is unavailable it logs and leaves the brain unchanged.

---

Tests

pytest -q

11 regression tests across the 6 documented scenarios plus cross-cutting checks (scope refusal, missing-input intake, graceful degradation, output-format structure, schema round-trip). The suite runs fully offline against the bundled climatology fallback, so results are deterministic and resource-free.

Scenario	Fixture	Offline baseline
1 Solar rooftop (Hanoi)	scenario1_solar_rooftop.json	tier C, 14408 kWh/yr, CF 0.161
2 Compare solar vs wind (Mekong)	scenario2_compare_rural.json	solar beats wind on CF & LCOE
3 Shading reduces yield (HCMC)	scenario3_shading.json	-30% shading -> ~30% lower kWh
4 Tariff / net-metering change	scenario4_tariff_change.json	net-metering halves payback
5 Optimal orientation (Tokyo)	scenario5_optimal_orientation.json	tilt 30 deg, azimuth 0 (south)
6 Weak wind resource (HCMC)	scenario6_weak_wind.json	PD 46 W/m^2, tier D, recommend against

See tests/test-scenarios.md for the full expected-vs-actual capture.

---

Quality gates

Three gates run before any deliverable is emitted (tools/gates.py):

• Evidence gate -- every material claim traces to a cited source or a computed step; degraded data is flagged, never hidden.
• Framework gate -- every assumption cites a framework; no ad-hoc rubric is permitted.
• Challenge gate -- a devil's-advocate pass with sensitivity analysis is on record before output.

A failed evidence or framework gate fails the run; a weak challenge gate appends a limitation rather than blocking (the challenge is informative).

---

Scope & limitations

In scope: distributed systems up to 1 MW -- residential and small-commercial rooftop PV and small wind.

Out of scope (returned as a scoped referral, never a half-estimate): utility-scale plants, grid-interconnection studies, structural/roof-load certification, and offshore wind.

Honest modeling caveats:

• Solar uses a monthly-average-day isotropic model (Liu-Jordan / Erbs), not a full hourly TMY/Perez simulation. This is a deliberate trade-off that keeps the tool keyless and offline-capable. It is framed as a bankable estimate, not an interconnection-grade study.
• Meteorology defaults to a conservative bundled climatology when NASA POWER is unreachable; this is always flagged in the report (met.degraded = true).
• Tariffs and policy are never invented -- unknown regions yield policy_known = false and ask the user.

---

Cross-skill reuse

This skill is part of the science-industry cluster. To avoid duplicated logic across sibling skills:

• docs/SHARED-SCORING-SCHEMA.md defines the canonical Score / Recommendation / Assumption objects, the tier table, and the gate semantics.
• docs/CROSS-SKILL-WIRING.md is the reuse contract: import tools.schemas, tools.gates, tools.economics, tools.met_data; swap the domain physics; keep the tier semantics.

---

Contributing

Contributions are welcome. Please keep the framework-grounded contract:

1. Every numeric result must trace to a named framework or a cited source.
2. Every default must be recorded in an Assumption with its framework.
3. New scenarios must come with a fixture under tests/fixtures/ and a regression assertion in tests/test_harness.py.
4. Do not bypass the quality gates.

Run pytest -q before opening a pull request.

---

Acknowledgements

• NREL PVWatts and NSRDB for the photovoltaic yield model.
• EU Joint Research Centre PVGIS for European solar resource data.
• Global Wind Atlas and NASA POWER for meteorological data.
• IRENA for renewable cost reference bands.
• Erbs et al. (1982), Liu & Jordan (1963), and Klein (1977) for the transposition and diffuse-fraction correlations.

---

License

Released under the MIT License. See LICENSE.