Build a CityJSON 2.0 Material and Surface Reflectance Auditor — implementation

## Build
Inspect 3D city models in CityJSON 2.0 format to verify surface material definitions and appearance mappings. Calculate urban surface solar reflectance indices to identify heat-island mitigation opportunities across city districts.

## User
Urban Sustainability Analyst

## Workflow
1. Load CityJSON 2.0 models containing Building objects and appearance material dictionaries.
2. Extract surface material associations, diffuse colors, and albedo properties across roof surfaces.
3. Compute average solar reflectance index for each building envelope and district cluster.
4. Generate a structured retrofit prioritization report for low-reflectance, high-heat roofs.

## Interface
Heatmap visualization showing building roof polygons colored by albedo with filterable district tables.

## Data
Utilize standard CityJSON 2.0 sample models with appearance materials or mock CityJSON files with color arrays.
Starter examples below are synthetic. They are not downloaded records.

## Source
[CityJSON](https://www.cityjson.org/specs/2.0.1/)
Extracts appearance object definitions, materials, and surface mapping indices from CityJSON 2.0 Section 6 and Section 1.

## Tools
semantic-kernel, pydantic, matplotlib.
Semantic Kernel orchestrates multi-step geospatial data queries and analytical synthesis prompts reliably.
API-based hosted LLM for reasoning across geometric materials and urban thermal guidelines.

## 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
- Extracts material properties from CityJSON appearance object dictionaries.
- Calculates solar reflectance values across building roof geometry surfaces.
- Flags roofs with solar reflectance below 0.30 as candidates for cool-roof retrofits.

## Starter Examples
```json
[
  {
    "input": {
      "city_objects": {
        "bldg-north": {
          "type": "Building",
          "geometry": [
            {
              "type": "MultiSurface",
              "material": {
                "roof": "dark_asphalt"
              }
            }
          ]
        }
      },
      "appearance": {
        "materials": [
          {
            "name": "dark_asphalt",
            "diffuseColor": [
              0.1,
              0.1,
              0.1
            ],
            "reflectance": 0.12
          }
        ]
      }
    },
    "expected_output": {
      "audited_buildings": 1,
      "cool_roof_candidates": [
        {
          "building_id": "bldg-north",
          "reflectance": 0.12,
          "recommendation": "High priority for high-albedo coating retrofit"
        }
      ]
    }
  },
  {
    "input": {
      "city_objects": {
        "bldg-south": {
          "type": "Building",
          "geometry": [
            {
              "type": "MultiSurface",
              "material": {
                "roof": "white_membrane"
              }
            }
          ]
        }
      },
      "appearance": {
        "materials": [
          {
            "name": "white_membrane",
            "diffuseColor": [
              0.85,
              0.85,
              0.85
            ],
            "reflectance": 0.75
          }
        ]
      }
    },
    "expected_output": {
      "audited_buildings": 1,
      "cool_roof_candidates": []
    }
  }
]
```

## Safety
Outputs advisory urban planning analytics; does not alter municipal building permitting statuses.
Use mock external writes. Require human review before any real deployment.