---
name: "site-assessment"
description: "UNHCR/Sphere site assessment — KML + foto + 18 reference markdown + 2 PDF + web search + calcoli UNHCR/Sphere + report DOCX 17 sezioni consegnato via HTTP."
model_tier: 3
metadata:
  hermes:
    tags: [unhcr, sphere, wash, shelter, camp, assessment, refugee]
    related_skills: [sentinel-2-water, landsat-water-detection, flood-riverine]
---

# Site Assessment — Rapporto Umanitario UNHCR/Sphere 🏕️

## Scopo
Tool unificato per generare report professionali DOCX di **site assessment umanitario** con 17 sezioni standard. Unisce:
- `franz-quick-assessment` (DOCX, foto, web search)
- `site-planning` (16 reference markdown, standards UNHCR/Sphere)

## Input

| Parametro | Richiesto | Descrizione |
|-----------|-----------|-------------|
| **KML file** | Sì | Perimetro del sito da Google Earth (`.kml` o `.kmz`) |
| **Site photo** | No | Foto del terreno/paesaggio (`.jpg`, `.png`) — analizzata via vision AI |
| **Country** | Sì | Nazione del sito |
| **Region** | No | Regione/provincia del sito (per web search mirato) |
| **Site name** | No | Nome del campo/sito (default: "Assessment Site") |

## Output
- **Report DOCX** con 17 sezioni standard e calcoli UNHCR/Sphere
- Consegna via **HTTP** (porta 8088) — il metodo preferito per cross-PC

## 17 Sezioni del Report

| # | Sezione | Descrizione |
|---|---------|-------------|
| 1 | Site Name & Boundaries | Nome, coordinate, area (ha), perimetro |
| 2 | Geographical Context | Elevazione, suolo, vegetazione, clima |
| 3 | Accessibility | Strade, aeroporti, distanze |
| 4 | Demographic Context | Popolazione, famiglie, distribuzione età |
| 5 | Capacity Estimation | Persone a 35/45 m², spazio disponibile |
| 6 | Hydrography & Water | Fiumi, falda, pozzi, water points |
| 7 | Shelter | Soluzioni, materiali, spazio coperto |
| 8 | WASH | Acqua, latrine, hygiene kits |
| 9 | Health | Strutture sanitarie, malattie endemiche |
| 10 | Education | Scuole, bambini in età scolastica |
| 11 | Protection | GBV, child protection, AGD |
| 12 | CCCM | Governance, coordinamento, community engagement |
| 13 | Space Matrix | Allocazione spazi (shelter, roads, WASH, buffer...) |
| 14 | Land Use Conflict | Conflitti d'uso, HLP issues |
| 15 | Site Plan | Layout, zoning, firebreaks |
| 16 | Risks & Criticalities | Flood, slope, hazards, sicurezza |
| 17 | Recommendations | Azioni prioritarie con riferimenti standard |

## Document Ingestion
Quando l'utente invia documenti UNHCR/Sphere via Telegram (es. Public Services and Facilities.md, Safe Disposal of Solid Waste.md):
1. Salvare il file in `references/` della skill
2. Aggiornare la sezione Riferimenti qui sotto
3. Preferire nomi senza spazi: `Public-Services-and-Facilities.md`
4. Aggiornare la version history

Il `generate_site_assessment.py` ha standard UNHCR/Sphere hardcoded. I reference markdown sono **documentazione consultiva** — lo script non li parsella automaticamente. Per incorporarli, modificare lo script per leggere i file e popolare le sezioni del report.

## Workflow

### 1. Parse KML
Legge il file KML/KMZ usando `xml.etree.ElementTree`:
```python
ns = {'kml': 'http://www.opengis.net/kml/2.2'}
tree = ElementTree.parse(kml_path)
# Coord format: lon,lat,alt separated by spaces
# Handle MultiPolygon e multiple Placemark
```

### 2. Calcola Area e Coordinate
- Shoelace formula per area in gradi²
- Conversione a m²: `area_m2 = area_deg² × (111320)² × cos(lat_rad)`
- Centroide, bounding box

### 3. Elevation Profile
- Open-Elevation API: `GET https://api.open-elevation.com/api/v1/lookup?locations=lat1,lon1|...`
- Grid 10×10 per pseudo-DTM: min, max, mean elevation, slope classification
- Transect sampling (N/S/E/W a 2km dal centro)

### 4. Web Search (zona)
Cerca informazioni sulla zona:
- **Suolo/geologia**: soil type, geology, terrain
- **Ospedali**: hospitals, health facilities near
- **Malattie endemiche**: endemic diseases, malaria, cholera risk
- **Conflitto/sicurezza**: security situation, conflict
- **Demografia**: population, IDPs, refugees
- **Clima**: climate, rainfall, temperature

### 5. Analisi Foto (opzionale)
Se fornita foto del sito, la analizza via visione AI per:
- Tipo di terreno
- Copertura vegetale
- Segni di allagamento/erosione
- Infrastrutture visibili
- Condizioni generali

### 6. Calcoli UNHCR/Sphere
Carica i reference markdown e calcola:

| Standard | Calcolo | Riferimento |
|----------|---------|-------------|
| Capacità 35 m²/p | `area_m2 * 0.7 / 35` | UNHCR §2.1 |
| Capacità 45 m²/p | `area_m2 * 0.7 / 45` | UNHCR §2.1 |
| Acqua L/giorno | `pop * 20` | Sphere Ch.2 |
| Latrine (emergenza) | `pop / 20` | Sphere §2.4 |
| Latrine (protracted) | `pop / 5` | UNHCR §4.3 |
| Docce | `pop / 50` | Sphere §2.4 |
| Rubbsh container | `pop / 50` | MSF PHE §3.1 |
| Refuse pit | `pop / 500` | UNHCR §4.3 |
| Health centre | `pop / 20000` | UNHCR §5.1 |
| Scuole | `pop / 5000` | UNHCR §5.2 |
| Distrib. centre | `pop / 5000` | UNHCR §5.2 |
| Shelter (3.5 m²) | `pop * 3.5` | UNHCR-SHELTER |
| Firebreaks | ogni 300m | UNHCR §2.2 |

### 7. Generazione DOCX
Crea il report usando `python-docx` con:
- **Copertina**: nome sito, coordinate, data
- **17 sezioni**: ognuna con tabelle, calcoli e riferimenti
- **Foto** embeddata (se fornita)
- **Calcoli numerici** con citazioni standard obbligatorie
- **Note esplicative** per assunzioni e scelte di standard

### 8. Consegna via HTTP (download)
```bash
python3 -m http.server 8088 --directory ~/.hermes/generated --bind 0.0.0.0 &
# URL: http://<ip>:8088/nome-report.docx
# Per kill: pkill -f 'http.server.*8088'
```

### 9. Upload da Tonfang → ProBook
```bash
python3 ~/.hermes/scripts/upload_server.py 9090 &
# Browser: http://<ip>:9090/
# Curl:   curl -F "file=@file.tif" http://<ip>:9090/upload
# Per kill: pkill -f "upload_server"
# Dettagli: references/upload-server.md
```

## Citazioni Obbligatorie
I valori numerici DEVONO avere riferimento tra parentesi:
```
Latrine: 749 (Sphere §2.4 / UNHCR CCCM §4.3)
Acqua: 300 m³/giorno a 20 L/p/d (Sphere Ch.2)
Capacità: 14,976 persone a 35 m²/p (UNHCR §2.1)
```

## Riferimenti (20 file — 18 markdown + 2 PDF)
I file con spazi nel nome (`Safe Disposal of Solid Waste.md`, `Public Services and Facilities.md`) sono gestiti correttamente — Hermes li apre senza problemi.
Caricati da `references/`:
- `unhcr-standards.md` — capacità, layout, site selection
- `sphere-standards.md` — minimum standards multisettoriali
- `wash-standards.md` — acqua, latrine, igiene
- `shelter-standards.md` — soluzioni, materiali, tipologie
- `protection-guidelines.md` — GBV, child protection, AGD
- `cccm-guidelines.md` — governance, coordinamento, camp management
- `settlement-typologies.md` — tipologie di insediamento
- `community-infrastructure-catalogue.md` — facility catalogue
- `circulation-networks.md` — strade, gerarchia, connettività
- `public-facilities-services.md` — health, education, market (vecchio rif.)
- `Public Services and Facilities.md` — **NUOVO** documento UNHCR completo: health, education, market, community centres, women's facilities (38KB)
- `solid-waste-disposal.md` — rifiuti, landfill (vecchio rif.)
- `Safe Disposal of Solid Waste.md` — **NUOVO** UNHCR GTH: linee guida smaltimento rifiuti in contesti umanitari (11KB, 5 capitoli + 8 annexes)
- `nature-based-solutions.md` — NBS, green infra
- `communal-open-space.md` — spazi aperti comunitari
- `ecompendium-wash-water.md` — WASH water compendium
- `wash-technologies-compendium.md` — water supply tech specs
- `unhcr-settlement-terminology-2026.md` — terminologia aggiornata

## Script Python
Il generatore DOCX è in `scripts/generate_site_assessment.py`.
Richiede: `python-docx`, `requests`, Pillow per foto.

## Version History
| Versione | Data | Modifiche |
|----------|------|-----------|
| v1.0 | 12 June 2026 | Merge da franz-quick-assessment + site-planning. KML, foto, web search, 16 reference markdown, calcoli UNHCR/Sphere, DOCX 17 sezioni, HTTP delivery. |
| v1.1 | 12 June 2026 | +2 reference: Public Services and Facilities.md (UNHCR completo), Safe Disposal of Solid Waste.md (UNHCR GTH). Totale 18 riferimenti. |
| v1.2 | 12 June 2026 | +upload-server.md (upload reversa Tonfang→ProBook con script upload_server.py). Delivery section aggiunta alla workflow. |