PlantPredict GenAgent — Solar Topology Optimizer

Natural-language solar plant layout optimization on top of the PlantPredict API. This repository contains the Python core (design phases P0–P2): typed domain models, the geospatial/terrain engine, the two-tier optimizer, the PlantPredict gateway, and the LangGraph campaign agent with a human approval checkpoint. The native macOS shell (phase P3) is a separate deliverable; see DESIGN.md for the full architecture.

Quick start

uv sync

# Offline demo: structured brief, mock PlantPredict validation, auto-approve.
uv run sto run --site examples/site_demo.yaml --brief examples/brief_demo.yaml \
  --trials 60 --mock-cloud --yes --output results.json

# Natural language (requires ANTHROPIC_API_KEY):
uv run sto run --site examples/site_demo.yaml \
  -r "Optimize a 100MW layout for maximum afternoon peak output, avoiding the northern wetlands and minimizing grading work."

# Live PlantPredict validation (requires PLANTPREDICT_CLIENT_ID / PLANTPREDICT_CLIENT_SECRET):
uv run sto run --site examples/site_demo.yaml --brief examples/brief_demo.yaml --cloud

How it works

1. The design request is parsed into a typed DesignBrief (Anthropic structured outputs); ambiguous zone references become clarification questions, never guessed geometry.
2. Deterministic validation checks the brief against the site before anything is spent.
3. A campaign plan is proposed and the agent pauses at a human approval checkpoint; cloud budgets are clamped by the tenant's PlantPredict plan quota.
4. Tier 1 screens hundreds of layouts locally (pvlib clear-sky energy proxy, DEM grading estimator, parameterized LCOE) under NSGA-II multi-objective search.
5. Tier 2 validates the Pareto set on PlantPredict with bounded concurrency, retry/backoff, token refresh, and a per-run watchdog; weather always comes from the nearest PlantPredict-hosted dataset.

Campaign agent flow (LangGraph)

The graph pauses at a human checkpoint before any compute or cloud spend; a rejected plan or an invalid brief short-circuits straight to the summary.

flowchart TD
    A["User request<br/><i>&quot;Optimize a 100MW layout for afternoon peak,<br/>avoid the northern wetlands, minimize grading&quot;</i>"] --> B[parse_intent<br/>LLM structured output → DesignBrief]
    B --> C[validate_brief<br/>zones exist · capacity fits buildable area ·<br/>no unresolved clarifications]
    C -->|errors| G[summarize<br/>report what blocked the campaign]
    C -->|valid| D[plan_campaign<br/>search bounds + trials ·<br/>cloud runs capped by TenantQuota]
    D --> E{{"⏸ human approval checkpoint<br/>(LangGraph interrupt — zero spend so far)"}}
    E -->|declined| G
    E -->|approved| F[run_campaign<br/>Tier 1 screening → Tier 2 validation]
    F --> G
    G --> H([Ranked Pareto candidates + summary])

Loading

Two-tier optimization

Thousands of cheap local evaluations rank the design space; only the Pareto survivors pay for cloud simulations.

flowchart LR
    subgraph T1["Tier 1 — local screening (ms per design)"]
        direction TB
        S[NSGA-II sampler<br/>gcr · dc/ac · tracking · tilt] --> L[Row layout<br/>exclusion zones = hard constraint]
        L -->|infeasible| S
        L --> GR[Grading estimate<br/>DEM cut/fill vs slope tolerance]
        L --> EN[pvlib energy proxy<br/>clear-sky · backtracking · clipping]
        GR --> EC[LCOE model<br/>CapEx + OpEx annuity]
        EN --> EC
        EC --> S
    end
    S -->|Pareto front| T2
    subgraph T2["Tier 2 — PlantPredict validation (minutes per run)"]
        direction TB
        P[Build PowerPlant payload<br/>GCR → post spacing · DC/AC → field power] --> Q[Bounded async queue<br/>concurrency + budget from TenantQuota]
        Q --> R[Cloud simulation<br/>bankable annual energy]
        R --> W[Recalibrate window energy<br/>by validated/proxy ratio]
    end
    T2 --> OUT([Validated Pareto set])

Loading

Tier-2 cloud run (per candidate)

sequenceDiagram
    participant O as Optimizer (tier 2)
    participant G as HttpPlantPredictGateway
    participant PP as PlantPredict Cloud
    O->>G: run_energy_simulation(candidate)
    G->>PP: POST /oauth2/token (client credentials)
    PP-->>G: bearer token
    G->>PP: GET /Weather/Search (site lat/lon)
    PP-->>G: nearest hosted dataset id
    G->>PP: POST /Project → POST /Prediction (weather_id)
    G->>PP: POST /PowerPlant (topology payload)
    G->>PP: POST /Run (queue simulation)
    loop poll until Complete / Error / watchdog timeout
        G->>PP: GET /Run/Status
        Note over G: 401 → refresh token once<br/>429/5xx → exponential backoff
    end
    G->>PP: GET /ResultSummary
    PP-->>G: annual energy (MWh)
    G-->>O: SimulationResult

Loading

Development

uv run pytest

Terrain-induced effects (grading volume, slope feasibility) are tier-1-only by design; PlantPredict supplies bankable energy figures for validated candidates.