Build an Urban CityJSON Solar Retrofit Evaluator — implementation

## Build
Analyze municipal 3D city models in CityJSON format to estimate rooftop surface areas. Formulate retrofit photovoltaic panel capacity proposals for commercial district revitalization.

## User
Urban Decarbonization Planner

## Workflow
1. Load a CityJSON district model containing building geometries and height attributes.
2. Decompress transformed coordinates and identify horizontal or tilted roof surfaces.
3. Compute potential solar collector area while subtracting roof installations.
4. Generate a structured retrofit solar layout proposal with estimated annual generation.

## Interface
Interactive GIS portal featuring 3D building outlines, solar suitability color maps, and printable retrofit briefs.

## Data
Utilize open municipal CityJSON 2.0 public dataset downloads from the official CityJSON community samples repository.
Starter examples below are synthetic. They are not downloaded records.

## Source
[CityJSON](https://www.cityjson.org/specs/2.0.1/)
Extracts CityObjects of type Building, BuildingPart, and BuildingInstallation along with transform matrix and vertices array.

## Tools
langgraph, fastapi, shapely.
LangGraph manages stateful multi-step execution across spatial geometry decompression, surface filtering, and solar potential computation.
Standard reasoning API model capable of evaluating urban rooftop geometry and municipal planning rules.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Correctly unpacks integer coordinates using CityJSON transform scale and translation vectors.
- Excludes children BuildingInstallation footprints from net available roof area.
- Produces valid kilowatt-hour solar generation estimates in a structured JSON payload.

## Starter Examples
```json
[
  {
    "input": {
      "city_object_id": "bldg_comm_12",
      "type": "Building",
      "transform": {
        "scale": [
          0.001,
          0.001,
          0.001
        ],
        "translate": [
          100000,
          200000,
          0
        ]
      },
      "attributes": {
        "roofType": "flat",
        "measuredHeight": 18.5
      },
      "roof_vertices": [
        [
          0,
          0,
          18500
        ],
        [
          20000,
          0,
          18500
        ],
        [
          20000,
          15000,
          18500
        ],
        [
          0,
          15000,
          18500
        ]
      ],
      "children": [
        "chiller_unit_1"
      ]
    },
    "expected_output": {
      "city_object_id": "bldg_comm_12",
      "gross_roof_area_m2": 300,
      "deducted_installation_area_m2": 24,
      "net_solar_area_m2": 276,
      "recommended_capacity_kw": 41.4,
      "retrofit_viable": true
    }
  },
  {
    "input": {
      "city_object_id": "bldg_shed_04",
      "type": "Building",
      "transform": {
        "scale": [
          0.001,
          0.001,
          0.001
        ],
        "translate": [
          100000,
          200000,
          0
        ]
      },
      "attributes": {
        "roofType": "complex_steep",
        "measuredHeight": 4
      },
      "roof_vertices": [
        [
          0,
          0,
          4000
        ],
        [
          3000,
          0,
          6000
        ],
        [
          3000,
          3000,
          6000
        ],
        [
          0,
          3000,
          4000
        ]
      ],
      "children": []
    },
    "expected_output": {
      "city_object_id": "bldg_shed_04",
      "gross_roof_area_m2": 10.8,
      "deducted_installation_area_m2": 0,
      "net_solar_area_m2": 10.8,
      "recommended_capacity_kw": 0,
      "retrofit_viable": false
    }
  }
]
```

## Safety
Solar retrofit estimates are preliminary planning calculations. External structural load checks must be verified by a licensed engineer.
Use mock external writes. Require human review before any real deployment.