South Sudan Administrative Geocoder - Streamlit app for hierarchical geocoding using DuckDB and Azure AI Foundry
# UNMISS HRD Geocoder
Streamlit app for the **United Nations Mission in South Sudan — Human Rights Division**: resolve free-text locations to GPS and admin boundaries, manage villages, process HRD reports, and extract locations from documents.
## Extraction pipeline
Location extraction uses a **cascading order**:
1. **Regex** — Rule-based patterns (fast, no API).
2. **Ollama** — Local LLM for gaps (optional; requires Ollama running).
3. **Azure OpenAI** — Cloud AI for remaining gaps (optional; requires Azure config).
Regex runs first; Ollama and Azure are used only where regex leaves gaps. No API keys or secrets are stored in the repo.
## Modules
| Module | Description |
|--------|-------------|
| **Geocoder** | Resolve a single location string to coordinates and admin hierarchy. |
| **Data Manager** | Batch-geocode Excel/CSV, upload GeoJSON layers, build name index. |
| **Village Manager** | Add, import, search, and edit village coordinates with auto admin boundaries. |
| **HRD Report Processor** | Upload field-office dailies; generate compiled DSRs and weekly matrices. |
| **Document Extractor** | Extract locations from unstructured text (regex → Ollama → Azure AI) and geocode. |
| **Batch Geocoder** | Batch geocode locations from tabular data; adds lat, long, payam, and county when location and state are provided. |
| **Maps** | Generate standard incident maps (bubble, hotspot) and custom maps via AI chat (optional Azure OpenAI). |
| **QC Support Notes** | Generate QC notes for HRD reports; optional regex/NLP/Ollama/OpenAI analysis and chat. |
| **System** | Settings, diagnostics, cache, and error logs. |
## Tech stack
- **Storage:** DuckDB (geospatial + cache)
- **Matching:** RapidFuzz
- **Spatial:** GeoPandas / Shapely
- **UI:** Streamlit
## Setup
1. Clone and enter the project:
```bash
git clone
cd unmiss_hrd_gis_ai
```
2. Create a virtual environment and install dependencies:
```bash
python3.11 -m venv venv
source venv/bin/activate # Windows: ve …