README.md

---
title: Site Intelligence Studio
emoji: 🧭
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.50.0
python_version: '3.12'
app_file: app.py
pinned: false
---

# Site Intelligence Studio

Site Intelligence Studio is a Gradio app for architecture students and early-career architects who need to turn a site boundary into a first-pass site-analysis board pack.

The app is built for the Hugging Face Build Small Hackathon, Backyard AI track. The real user is an Indian architecture student / early-career architect who described the repetitive work of collecting climate, site context, boundary, terrain, soil, and existing-condition notes from scattered sources, then redrawing them into sheets.

## What It Does

- Draw a polygon or rectangle on an open map.
- Drop a pin and radius for approximate neighborhood context.
- Paste latitude/longitude or a Google Maps URL containing coordinates.
- Upload DXF and select detected boundary candidates.
- Upload Google Earth / GIS-style KML or KMZ boundaries.
- Upload GeoJSON boundaries.
- Upload PDF as reference-only material.
- Generate an architecture-style board preview with downloadable PNG/PDF.
- Generate climate, sun/wind, geographic context, evidence, checklist, and Markdown report outputs.
- Add Google Maps / Google Earth / OpenStreetMap reference links without using Google as the drawing engine or hidden evidence source.
- Generate a bounded Small Model Brief tab. By default this uses deterministic fallback text; set `ENABLE_SMALL_MODEL=1`, `HF_TOKEN`, and optionally `SMALL_MODEL_ID` to use a <=4B Hugging Face text model for captions/checklist wording.
- Keep soil, foundation, legal boundary, and professional decisions explicitly outside the app's authority.

## Why This Is Not Just A Chatbot

The app does deterministic work first:

- geometry normalization
- area/perimeter/centroid calculation
- DXF/KML/KMZ/GeoJSON parsing
- Open-Meteo climate summaries
- OpenStreetMap / Overpass context lookup
- Nominatim reverse-geocoding
- OpenTopoData terrain sampling
- SoilGrids preliminary topsoil signals
- evidence rows with confidence and limitations

The small-model layer is intentionally bounded. The default model id is `HuggingFaceTB/SmolLM2-360M-Instruct`, but live model generation is disabled unless environment variables are configured. If it is unavailable, the app uses deterministic fallback text. The model/fallback only rewrites evidence into captions, checklist language, and explanation. It must not invent site facts, recommend foundations, verify legal boundaries, or design the building.

## Data Sources

- Open-Meteo Forecast API for forecast/current weather.
- Open-Meteo Historical Weather API for recent historical and climate-normal-style summaries.
- OpenStreetMap and Overpass API for mapped roads, buildings, land use, water, green/open space, and amenities where available.
- OpenStreetMap Nominatim for approximate reverse-geocoded address context.
- OpenTopoData SRTM 90m API for preliminary elevation/relief/slope cues.
- SoilGrids / ISRIC for coarse preliminary topsoil texture indicators.
- Leaflet with vendored local assets for the map UI.
- User-uploaded DXF, KML/KMZ, GeoJSON, and user notes.

## Boundary Accuracy

Drawn map boundaries are approximate. Open map tiles are useful for context and rough tracing, but they are not plot-survey tools. Use CAD/DXF, KML/KMZ, GeoJSON, or survey drawings when boundary accuracy matters.

CAD boundaries are only as reliable as the uploaded drawing. Local CAD coordinates must be anchored before public map/climate data can be interpreted. Google Maps / Google Earth links are visual references only unless the user exports KML/KMZ or verifies observations on site.

## Safety Boundaries

This app is not:

- a legal boundary verifier
- a cadastral source
- a geotechnical survey
- a final foundation recommender
- a structural engineering tool
- a zoning/compliance authority
- a Revit/BIM/Autodesk Forma replacement
- a full building-design generator

The app always treats soil, foundation, legal boundary, regulation, and final design decisions as professional or site-visit verification items.

## Demo Flow For Judges

1. Click **Use Chorwad sample site**.
2. Click **Generate site-analysis board pack**.
3. Open the Presentation Board tab and inspect the PNG/PDF board.
4. Open Diagrams to check climate, sun/wind, and context graphics.
5. Open Evidence Table to see source, confidence, limitation, and verification rows.
6. Open the Report tab for the longer site-analysis workbook.
7. Repeat with a drawn polygon, KML/KMZ, GeoJSON, or DXF boundary.

## Friend Validation Plan

The real-user validation task is:

1. Use one real studio/thesis site.
2. Try either KML/KMZ, DXF, GeoJSON, or a drawn boundary.
3. Generate the board pack.
4. Mark which diagrams/text can be pasted into a sheet.
5. Mark which parts are wrong, generic, or not useful.
6. Estimate time saved compared with manual gathering.
7. Confirm whether source/confidence/uncertainty labels are understandable.
8. Provide one anonymized quote for the demo video or write-up.

## Current Limitations

- Context maps depend on OSM completeness.
- Terrain is coarse public elevation sampling, not a contour survey.
- SoilGrids is a global model signal, not plot-level geotechnical truth.
- Satellite/Earth references are manual visual-reference links, not processed satellite analysis.
- PDF uploads are reference-only.
- The app does not infer culture or demographics from coordinates.
- The app does not perform zoning, CRZ, FSI/FAR, legal, cadastral, or compliance checks.

## Run Locally

```bash
pip install -r requirements.txt
python app.py
```

Then open the local Gradio URL shown in the terminal.

## Optional Small Model Configuration

```bash
set ENABLE_SMALL_MODEL=1
set HF_TOKEN=your_huggingface_token
set SMALL_MODEL_ID=HuggingFaceTB/SmolLM2-360M-Instruct
python app.py
```

The app remains usable without these variables. Do not enable a model above the Build Small Hackathon parameter cap.