Deploy to Spaces (Final Clean)

.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+ENV/
+env/
+.venv/
+
+# Node
+node_modules/
+.next/
+out/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Data files (keep structure, not data)
+*.parquet
+*.duckdb
+*.duckdb.wal
+
+# Large data files and binaries (downloaded at build time)
+backend/data/embeddings.json
+backend/data/*.geojson
+backend/data/*.gz
+backend/data/*.xlsx
+backend/data/global/airports/airports_global.csv
+backend/data/*.gpkg
+backend/data/osm/
+backend/data/overture/
+backend/data/kontur/
+backend/data/hdx/
+backend/data/base/
+backend/data/inec/
+backend/data/temp/
+backend/data/climate/
+backend/data/ms_buildings/
+backend/data/stri/
+backend/data/socioeconomic/
+backend/data/terrain/
+backend/data/worldbank/
+
+# Logs
+*.log
+npm-debug.log*
+
+# Build
+dist/
+build/
+*.egg-info/

ARCHITECTURE.md

@@ -0,0 +1,426 @@
+# GeoQuery Architecture
+
+## System Overview
+
+GeoQuery is a **Territorial Intelligence Platform** that combines Large Language Models (LLMs) with geospatial analysis to enable natural language querying of geographic datasets. The system translates conversational queries into SQL, executes spatial operations, and presents results through interactive maps and data visualizations.
+
+### Design Philosophy
+
+1. **Natural Language First**: Users interact through conversational queries, not SQL or GIS interfaces
+2. **Dynamic Data Discovery**: No fixed schema—the system adapts to any GeoJSON dataset added to the catalog
+3. **Streaming Intelligence**: Real-time thought processes and incremental results via Server-Sent Events
+4. **Spatial Native**: PostGIS-compatible spatial operations in DuckDB for performant geospatial analysis
+5. **Visual by Default**: Automatic map visualization, choropleth generation, and data presentation
+
+---
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Frontend                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │  ChatPanel   │  │  MapViewer   │  │ DataExplorer │     │
+│  │  (React)     │  │  (Leaflet)   │  │   (Table)    │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+│         │                  │                  │             │
+│         └──────────────────┴──────────────────┘             │
+│                           │ (SSE/HTTP)                       │
+└───────────────────────────┼─────────────────────────────────┘
+                            │
+┌───────────────────────────┼─────────────────────────────────┐
+│                      API Layer                               │
+│  ┌──────────────────────────────────────────────────┐       │
+│  │         FastAPI Endpoints                         │       │
+│  │  /api/chat (SSE) │ /api/catalog │ /api/schema    │       │
+│  └──────────────────────────────────────────────────┘       │
+│                           │                                  │
+└───────────────────────────┼─────────────────────────────────┘
+                            │
+┌───────────────────────────┼─────────────────────────────────┐
+│                     Service Layer                            │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │ QueryExecutor│  │   LLMGateway │  │  GeoEngine   │      │
+│  │              │  │   (Gemini)   │  │   (DuckDB)   │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │ DataCatalog  │  │SemanticSearch│  │ SessionStore │      │
+│  │ (Embeddings) │  │  (Vectors)   │  │   (Layers)   │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+└─────────────────────────────────────────────────────────────┘
+                            │
+┌───────────────────────────┼─────────────────────────────────┐
+│                      Data Layer                              │
+│  ┌──────────────┐  ┌─────���────────┐  ┌──────────────┐      │
+│  │ catalog.json │  │  GeoJSON     │  │ embeddings   │      │
+│  │  (Metadata)  │  │  (Datasets)  │  │   (.npy)     │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│  ┌──────────────────────────────────────────────────┐      │
+│  │         DuckDB In-Memory Database                 │      │
+│  │  (Spatial Tables, Temporary Layers, Indexes)     │      │
+│  └──────────────────────────────────────────────────┘      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Components
+
+### 1. Frontend (Next.js + React)
+
+**Location**: `frontend/src/`
+
+The frontend is a single-page application built with Next.js that provides:
+- **ChatPanel**: Conversational interface with streaming responses
+- **MapViewer**: Interactive Leaflet map with layer management
+- **DataExplorer**: Tabular data view with export capabilities
+
+**Key Technologies**:
+- Next.js 14 (App Router)
+- React 18 with hooks
+- Leaflet for map rendering
+- Server-Sent Events (SSE) for streaming
+- dnd-kit for drag-and-drop layer reordering
+
+### 2. API Layer (FastAPI)
+
+**Location**: `backend/api/`
+
+RESTful API with streaming support:
+- **`/api/chat`** (POST): Main query endpoint with SSE streaming
+- **`/api/catalog`** (GET): Returns available datasets
+- **`/api/schema`** (GET): Returns database schema
+
+**Key Technologies**:
+- FastAPI for async HTTP
+- Starlette for SSE streaming
+- CORS middleware for cross-origin requests
+
+### 3. Service Layer
+
+#### QueryExecutor (`backend/services/executor.py`)
+Orchestrates the entire query pipeline:
+1. Intent detection
+2. Data discovery
+3. SQL generation
+4. Query execution
+5. Response formatting
+6. Explanation generation
+
+#### LLMGateway (`backend/core/llm_gateway.py`)
+Interfaces with Gemini API:
+- Intent detection with thinking
+- Text-to-SQL generation
+- Natural language explanations
+- Layer naming and styling
+- Error correction
+- Streaming support
+
+#### GeoEngine (`backend/core/geo_engine.py`)
+Manages spatial database:
+- DuckDB connection with Spatial extension
+- Lazy table loading from GeoJSON
+- SQL query execution
+- Result formatting to GeoJSON
+- Temporary layer registration
+
+#### DataCatalog (`backend/core/data_catalog.py`)
+Dataset discovery system:
+- Loads `catalog.json` metadata
+- Generates table summaries for LLM context
+- Provides schema information
+- Manages dataset metadata
+
+#### SemanticSearch (`backend/core/semantic_search.py`)
+Vector-based dataset discovery:
+- Generates embeddings for dataset descriptions
+- Performs cosine similarity search
+- Returns top-k relevant datasets
+- Scales to large catalogs (100+ datasets)
+
+#### SessionStore (`backend/core/session_store.py`)
+User session management:
+- Tracks created map layers per session
+- Enables spatial operations on user layers
+- Maintains layer metadata
+
+### 4. Data Layer
+
+#### Catalog System (`backend/data/catalog.json`)
+Central metadata registry:
+- Dataset paths and descriptions
+- Semantic descriptions for AI discovery
+- Categories and tags
+- Schema information
+- Data provenance
+
+#### GeoJSON Datasets (`backend/data/`)
+Organized by source:
+- `osm/` - OpenStreetMap data (roads, buildings, POI)
+- `admin/` - Administrative boundaries (HDX)
+- `global/` - Global datasets (Kontur, Natural Earth)
+- `socioeconomic/` - World Bank, MPI data
+- `stri/` - STRI GIS Portal datasets
+
+#### Vector Embeddings (`backend/data/embeddings.npy`)
+Sentence transformer embeddings for semantic search
+
+---
+
+## Data Flow: User Query to Response
+
+### Step 1: User Input
+```
+User: "Show me hospitals in Panama City"
+```
+
+### Step 2: Frontend → Backend
+```
+POST /api/chat
+{
+  "message": "Show me hospitals in Panama City",
+  "history": []
+}
+```
+
+### Step 3: Intent Detection (LLM)
+```python
+# QueryExecutor calls LLMGateway.detect_intent()
+intent = await llm.detect_intent(query, history)
+# Returns: "MAP_REQUEST"
+```
+
+### Step 4: Semantic Discovery
+```python
+# SemanticSearch finds relevant tables
+candidates = semantic_search.search_table_names(query, top_k=15)
+# Returns: ["panama_healthsites_geojson", "osm_amenities", ...]
+```
+
+### Step 5: Table Schema Retrieval
+```python
+# GeoEngine loads relevant tables
+geo_engine.ensure_table_loaded("panama_healthsites_geojson")
+schema = geo_engine.get_table_schemas()
+# Returns: "Table: panama_healthsites_geojson\nColumns: name, amenity, geom..."
+```
+
+### Step 6: SQL Generation (LLM)
+```python
+# LLMGateway generates SQL
+sql = await llm.generate_analytical_sql(query, schema, history)
+# Returns: "SELECT name, amenity, geom FROM panama_healthsites_geojson 
+#           WHERE amenity = 'hospital' AND ST_Intersects(geom, ...)"
+```
+
+### Step 7: Query Execution
+```python
+# GeoEngine executes spatial query
+geojson = geo_engine.execute_spatial_query(sql)
+# Returns: GeoJSON with 45 hospital features
+```
+
+### Step 8: Response Formatting
+```python
+# Add layer metadata, generate name, configure visualization
+layer_info = await llm.generate_layer_name(query, sql)
+# Returns: {"name": "Hospitals in Panama City", "emoji": "🏥", "pointStyle": "icon"}
+
+geojson = format_geojson_layer(query, geojson, features, 
+                                layer_info["name"], 
+                                layer_info["emoji"],
+                                layer_info["pointStyle"])
+```
+
+### Step 9: Explanation Generation (Streaming)
+```python
+# LLMGateway generates explanation with streaming
+async for chunk in llm.stream_explanation(query, sql, data_summary, history):
+    if chunk["type"] == "thought":
+        # Stream thinking process to frontend
+    elif chunk["type"] == "content":
+        # Stream actual response text
+```
+
+### Step 10: Frontend Rendering
+- ChatPanel displays streamed explanation
+- MapViewer renders GeoJSON layer with hospital icons
+- DataExplorer shows tabular data
+
+---
+
+## Key Design Decisions
+
+### 1. Why DuckDB Instead of PostgreSQL?
+
+**Chosen**: DuckDB with Spatial extension
+
+**Rationale**:
+- **Zero Configuration**: Embedded database, no separate server
+- **Fast Analytics**: Columnar storage optimized for analytical queries
+- **Spatial Support**: Full PostGIS compatibility via spatial extension
+- **GeoJSON Native**: Direct GeoJSON import/export
+- **Lightweight**: Perfect for development and small deployments
+
+**Trade-off**: Limited concurrency compared to PostgreSQL (acceptable for our use case)
+
+### 2. Why Semantic Search for Dataset Discovery?
+
+**Chosen**: Sentence transformer embeddings + cosine similarity
+
+**Rationale**:
+- **Scalability**: Works with 100+ datasets without overwhelming LLM context
+- **Accuracy**: Better matches than keyword search
+- **Token Efficiency**: Only sends relevant table schemas to LLM
+
+**Example**:
+- Query: "Where can I find doctors?"
+- Semantic search finds: `panama_healthsites_geojson` (closest match)
+- LLM then generates SQL using only relevant schema
+
+### 3. Why Server-Sent Events for Streaming?
+
+**Chosen**: SSE instead of WebSockets
+
+**Rationale**:
+- **Simpler Protocol**: One-way communication (server → client)
+- **HTTP Compatible**: Works through firewalls and proxies
+- **Auto Reconnect**: Built-in browser support
+- **Event Types**: Named events for different message types
+
+**Trade-off**: No client → server streaming (not needed for our use case)
+
+### 4. Why Lazy Table Loading?
+
+**Chosen**: Load GeoJSON only when needed
+
+**Rationale**:
+- **Fast Startup**: Don't load all datasets on initialization
+- **Memory Efficient**: Only keep active tables in memory
+- **Flexible**: Easy to add new datasets without restart
+
+**Implementation**:
+```python
+def ensure_table_loaded(self, table_name: str) -> bool:
+    if table_name not in self.loaded_tables:
+        self.load_geojson_to_table(table_name)
+    return table_name in self.loaded_tables
+```
+
+### 5. Why Choropleth Auto-Detection?
+
+**Chosen**: Automatic choropleth configuration based on data
+
+**Rationale**:
+- **User Friendly**: No manual configuration needed
+- **Intelligent**: Prioritizes meaningful columns (population, area, density)
+- **Adaptive**: Works with any numeric column
+
+**Logic**:
+1. Find numeric columns
+2. Prioritize keywords (population, area, count)
+3. Check value variance (skip if all same)
+4. Enable choropleth with appropriate scale (linear/log)
+
+---
+
+##Error Handling & Resilience
+
+### SQL Error Correction
+When a generated SQL query fails:
+1. Extract error message
+2. Send to LLM with original query and schema
+3. LLM generates corrected SQL
+4. Execute repaired query
+5. If still fails, return error to user
+
+### Data Unavailable Handling
+When requested data doesn't exist:
+1. LLM returns special error marker: `-- ERROR: DATA_UNAVAILABLE`
+2. System extracts "Requested" and "Available" from response
+3. Returns helpful message to user with alternatives
+
+### Missing Tables
+- Catalog lists all datasets but not all loaded
+- Lazy loading attempts to load on demand
+- If file missing, logs warning and continues
+
+---
+
+## Performance Considerations
+
+### Query Optimization
+- **Spatial Indexes**: DuckDB automatically indexes geometry columns
+- **Top-K Limits**: Large result sets limited to prevent memory issues
+- **Lazy Evaluation**: Stream results when possible
+
+### Embedding Cache
+- Embeddings pre-computed and stored in `.npy` file
+- Only regenerated when catalog changes
+- Fast cosine similarity via NumPy vectorization
+
+### Frontend Rendering
+- **Layer Virtualization**: Large point datasets use circle markers for performance
+- **Choropleth Colors**: Pre-computed color palettes
+- **Lazy Map Loading**: Only render visible layers
+
+---
+
+## Security Considerations
+
+### LLM Prompt Injection
+- **Mitigation**: Clear separation of user query and system instructions
+- **Validation**: SQL parsing and column name verification
+- **Sandboxing**: Read-only queries (no INSERT/UPDATE/DELETE)
+
+### API Access
+- **CORS**: Configured allowed origins
+- **Rate Limiting**: Can be added via middleware (not currently implemented)
+- **Authentication**: Not implemented (suitable for internal/demo deployments)
+
+### Data Privacy
+- No user data stored (stateless queries)
+- Session layers stored in-memory only
+- No query logging by default
+
+---
+
+## Scalability Path
+
+### Current Limitations
+- **Single Process**: No horizontal scaling
+- **In-Memory Database**: Limited by RAM
+- **No Caching**: Repeated queries re-execute
+
+### Future Enhancements
+1. **Add PostgreSQL/PostGIS**: For production deployments with persistence
+2. **Redis Cache**: Cache query results and embeddings
+3. **Load Balancer**: Multiple FastAPI instances
+4. **Background Workers**: Async data ingestion with Celery
+5. **CDN**: Serve GeoJSON datasets from cloud storage
+
+---
+
+## Technology Choices Summary
+
+| Component | Technology | Why? |
+|-----------|-----------|------|
+| **Backend Language** | Python 3.11+ | Rich geospatial ecosystem, LLM SDKs |
+| **Web Framework** | FastAPI | Async support, OpenAPI docs, SSE |
+| **Database** | DuckDB | Embedded, fast analytics, spatial support |
+| **LLM** | Google Gemini | Thinking mode, streaming, JSON output |
+| **Frontend Framework** | Next.js 14 | React, SSR, App Router, TypeScript |
+| **Map Library** | Leaflet | Lightweight, flexible, plugin ecosystem |
+| **Embeddings** | sentence-transformers | Multilingual, semantic similarity |
+| **Data Format** | GeoJSON | Standard, human-readable, LLM-friendly |
+
+---
+
+## Next Steps
+
+For detailed information on specific components:
+- [Backend Services](docs/backend/CORE_SERVICES.md)
+- [API Reference](docs/backend/API_ENDPOINTS.md)
+- [Frontend Components](docs/frontend/COMPONENTS.md)
+- [Data Flow](docs/DATA_FLOW.md)
+- [Setup Guide](SETUP.md)

DEPLOYMENT.md

@@ -0,0 +1,58 @@
+# Deployment Guide
+
+This guide describes how to deploy the GeoQuery platform for public access.
+
+## Strategy
+We use a **single-container** approach where the backend (FastAPI) serves the frontend (Next.js) as static files. This simplifies deployment to PaaS providers like Railway, Render, or Hugging Face Spaces.
+
+### Architecture
+- **Build Stage**: Node.js builder compiles the Next.js frontend into static HTML/CSS/JS (`frontend/out`).
+- **Runtime Stage**: Python 3.11 image installs backend dependencies.
+- **Serving**: FastAPI mounts the static build at `/` and serves the API at `/api`.
+- **Data**: Geospatial data (`backend/data`) is included in the image (~2GB).
+
+## Prerequisites
+- Docker
+- ~5GB Free disk space (for image build)
+- 4GB+ RAM on host machine (for DuckDB in-memory analytics)
+
+## Local Build & Run
+```bash
+# Build the image
+docker build -t geoquery .
+
+# Run the container (Mapping 7860 to 7860 to match standard Space config)
+docker run -p 7860:7860 -e GEMINI_API_KEY=your_key_here geoquery
+```
+
+## Hosting Options (Getting a Public URL)
+
+To share this demo with others, you need to host the Docker container on a cloud provider.
+
+### Option A: Hugging Face Spaces (Easiest & Free)
+This will give you a public URL like `https://huggingface.co/spaces/username/geoquery`.
+
+1. **Create Space**: Go to [huggingface.co/spaces](https://huggingface.co/spaces) -> "Create new Space".
+   - SDK: **Docker**
+   - Template: **Blank**
+2. **Push Code**:
+   ```bash
+   git remote add space https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME
+   git push space main
+   ```
+3. **Configure Secrets**: In the Space "Settings" tab, add a "Repository Secret" named `GEMINI_API_KEY` with your key.
+
+### Option B: Railway / Render
+1. Connect your GitHub repository.
+2. Railway/Render will detect the `Dockerfile`.
+3. Set the environment variable `GEMINI_API_KEY`.
+4. Detailed output will be available at a URL like `https://geoquery-production.up.railway.app`.
+
+### Option C: Google Cloud Run
+1. Build: `gcloud builds submit --tag gcr.io/PROJECT_ID/geoquery`
+2. Deploy: `gcloud run deploy geoquery --image gcr.io/PROJECT_ID/geoquery --platform managed`
+
+
+## Notes
+- **Data Persistence**: The current setup uses read-only data baked into the image. User uploads will be lost on restart unless a volume is mounted to `/app/backend/data/custom`.
+- **Memory Usage**: DuckDB processes data in-memory. For large queries, ensure the host has sufficient RAM.

Dockerfile

@@ -0,0 +1,58 @@
+# ==========================================
+# Stage 1: Build Frontend (Next.js)
+# ==========================================
+FROM node:20-alpine AS frontend
+WORKDIR /app
+
+# Install dependencies
+COPY frontend/package*.json ./
+RUN npm ci
+
+# Copy source code
+COPY frontend/ ./
+
+# Configure for static export
+ENV NEXT_PUBLIC_API_URL=/api/v1
+# Run build (creates /app/out)
+RUN npm run build
+
+# ==========================================
+# Stage 2: Runtime (Python + FastAPI)
+# ==========================================
+FROM python:3.11-slim
+
+# Create a non-root user (Recommended for HF Spaces)
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+# Install system dependencies (as root before switching user)
+USER root
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    libgeos-dev \
+    && rm -rf /var/lib/apt/lists/*
+USER user
+
+# Install Python dependencies
+COPY --chown=user backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy download script and execute data fetch
+COPY backend/scripts/download_hdx_panama.py backend/scripts/
+RUN python backend/scripts/download_hdx_panama.py
+
+# Copy Backend Code
+COPY --chown=user backend/ backend/
+
+# Copy Built Frontend to Backend Static Directory
+# ensure strict permissions
+COPY --from=frontend --chown=user /app/out /app/backend/static
+
+# Expose port 7860 (Standard for HF Spaces)
+EXPOSE 7860
+
+# Run Application
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,277 @@
+---
+title: GeoQuery
+emoji: 🌍
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+app_port: 7860
+---
+
+# GeoQuery
+ 🌍🤖
+
+**Territorial Intelligence Platform** - Natural language interface for geospatial data analysis powered by LLMs and DuckDB Spatial.
+
+![Status](https://img.shields.io/badge/Status-Active-success) ![Python](https://img.shields.io/badge/Python-3.11+-blue) ![Next.js](https://img.shields.io/badge/Next.js-15-black) ![License](https://img.shields.io/badge/License-MIT-green)
+
+---
+
+## ✨ What is GeoQuery?
+
+GeoQuery transforms geographic data analysis by combining **Large Language Models** with **spatial databases**. Simply ask questions in natural language and get instant maps, charts, and insights.
+
+**Example**: *"Show me hospitals in Panama City"* → Interactive map with 45 hospital locations, automatically styled with 🏥 icons.
+
+### Key Capabilities
+
+- 🗣️ **Conversational Queries** - Natural language instead of SQL or GIS interfaces
+- 🗺️ **Auto-Visualization** - Smart choropleth maps, point markers, and heatmaps
+- 📊 **Dynamic Charts** - Automatic bar, pie, and line chart generation
+- 🔍 **Semantic Discovery** - Finds relevant datasets from 100+ options using AI embeddings
+- 🧩 **Multi-Step Analysis** - Complex queries automatically decomposed and executed
+- 💡 **Thinking Transparency** - See the LLM's reasoning process in real-time
+- 🎨 **Custom Point Styles** - Icon markers for POI, circle points for large datasets
+
+---
+
+## 🎬 Quick Demo
+
+### Try These Queries
+
+| Query | What You Get |
+|-------|--------------|
+| "Show me all provinces colored by area" | Choropleth map with size-based gradient |
+| "Where are the universities?" | Point map with 🎓 icons |
+| "Compare hospital count vs school count by province" | Multi-step analysis with side-by-side bar charts |
+| "Show intersections in David as circle points" | 1,288 traffic intersections as simple colored circles |
+| "Population density in Veraguas" | H3 hexagon heatmap (33K cells) |
+
+---
+
+## 🏗️ Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Frontend (Next.js)                    │
+│   Chat Interface  │  Leaflet Maps  │  Data Explorer     │
+└────────────────────────┬─────────────────────────────────┘
+                         │ (SSE Streaming)
+┌────────────────────────┴─────────────────────────────────┐
+│                  Backend (FastAPI)                       │
+│  Intent Detection → Semantic Search → SQL Generation     │
+│         ↓                ↓                  ↓             │
+│    Gemini LLM    DataCatalog (Embeddings) DuckDB Spatial │
+└──────────────────────────────────────────────────────────┘
+```
+
+It supports dynamic dataset discovery via semantic embeddings + LLM-generated spatial SQL.
+
+📖 **[Detailed Architecture](ARCHITECTURE.md)**
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Python 3.11+**
+- **Node.js 18+**
+- **Google AI API Key** ([Get one free](https://aistudio.google.com/app/apikey))
+
+### Installation
+
+```bash
+# 1. Clone repository
+git clone https://github.com/GerardCB/GeoQuery.git
+cd GeoQuery
+
+# 2. Backend setup
+cd backend
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e .
+
+# 3. Configure API key
+export GEMINI_API_KEY="your-api-key-here"
+
+# 4. Start backend
+uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
+
+# 5. Frontend setup (new terminal)
+cd frontend
+npm install
+npm run dev
+```
+
+### 🎉 Done!
+
+Open **http://localhost:3000** and start querying!
+
+📘 **[Detailed Setup Guide](SETUP.md)**
+
+---
+
+## 📂 Project Structure
+
+```
+GeoQuery/
+├── backend/
+│   ├── api/                    # FastAPI endpoints
+│   │   └── endpoints/          # /chat, /catalog, /schema
+│   ├── core/                   # Core services
+│   │   ├── llm_gateway.py      # Gemini API integration
+│   │   ├── geo_engine.py       # DuckDB Spatial wrapper
+│   │   ├── semantic_search.py  # Embedding-based discovery
+│   │   ├── data_catalog.py     # Dataset metadata management
+│   │   ├── query_planner.py    # Multi-step query orchestration
+│   │   └── prompts.py          # LLM system instructions
+│   ├── services/               # Business logic
+│   │   ├── executor.py         # Query pipeline orchestrator
+│   │   └── response_formatter.py # GeoJSON/chart formatting
+│   ├── data/                   # Datasets and metadata
+│   │   ├── catalog.json        # Dataset registry
+│   │   ├── embeddings.npy      # Vector embeddings
+│   │   ├── osm/                # OpenStreetMap data
+│   │   ├── admin/              # Administrative boundaries
+│   │   ├── global/             # Global datasets (Kontur, etc.)
+│   │   └── socioeconomic/      # World Bank, poverty data
+│   └── scripts/                # Data ingestion scripts
+│       ├── download_geofabrik.py
+│       ├── download_hdx_panama.py
+│       └── stri_catalog_scraper.py
+├── frontend/
+│   └── src/
+│       ├── app/                # Next.js App Router pages
+│       └── components/
+│           ├── ChatPanel.tsx   # Chat interface with SSE
+│           ├── MapViewer.tsx   # Leaflet map with layers
+│           └── DataExplorer.tsx # Tabular data view
+└── docs/                       # Technical documentation
+    ├── backend/                # Backend deep-dives
+    ├── frontend/               # Frontend architecture
+    └── data/                   # Data system docs
+```
+
+---
+
+## 🔧 Technology Stack
+
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| **LLM** | Google Gemini 2.0 | Intent detection, SQL generation, explanations |
+| **Backend** | Python 3.11 + FastAPI | Async HTTP server with SSE streaming |
+| **Database** | DuckDB with Spatial | In-memory spatial analytics |
+| **Frontend** | Next.js 15 + React 18 | Server-side rendering + interactive UI |
+| **Maps** | Leaflet 1.9 | Interactive web maps |
+| **Embeddings** | sentence-transformers | Semantic dataset search |
+| **Data** | GeoJSON + Parquet | Standardized geospatial formats |
+
+---
+
+## 📊 Available Datasets
+
+GeoQuery currently includes 100+ datasets across multiple categories:
+
+### Administrative
+- Panama provinces, districts, corregimientos (HDX 2021)
+- Comarca boundaries
+- Electoral districts
+
+### Infrastructure
+- Roads and highways (OpenStreetMap)
+- Hospitals and health facilities (986 locations)
+- Universities and schools (200+ institutions)
+- Airports, ports, power plants
+
+### Socioeconomic
+- World Bank development indicators
+- Multidimensional poverty index (MPI)
+- Population density (Kontur H3 hexagons - 33K cells)
+
+### Natural Environment
+- Protected areas (STRI GIS Portal)
+- Forest cover and land use
+- Rivers and water bodies
+
+📖 **[Full Dataset List](docs/data/DATASET_SOURCES.md)** | **[Adding New Data](docs/backend/SCRIPTS.md)**
+
+---
+
+## 💡 How It Works
+
+1. **User Query**: "Show me hospitals in Panama City"
+2. **Intent Detection**: LLM classifies as MAP_REQUEST
+3. **Semantic Search**: Finds `panama_healthsites_geojson` via embeddings
+4. **SQL Generation**: LLM creates: `SELECT name, geom FROM panama_healthsites_geojson WHERE ST_Intersects(geom, (SELECT geom FROM pan_admin2 WHERE adm2_name = 'Panamá'))`
+5. **Execution**: DuckDB Spatial runs query → 45 features
+6. **Visualization**: Auto-styled map with 🏥 icons
+7. **Explanation**: LLM streams natural language summary
+
+**Streaming**: See the LLM's thinking process in real-time via Server-Sent Events.
+
+📖 **[Detailed Data Flow](docs/DATA_FLOW.md)** | **[LLM Integration](docs/backend/LLM_INTEGRATION.md)**
+
+---
+
+## 🗺️ Advanced Features
+
+### Choropleth Maps
+Automatically detects numeric columns and creates color gradients:
+- **Linear scale**: For area, count
+- **Logarithmic scale**: For population, density
+
+### Point Visualization Modes
+- **Icon markers** 🏥🎓⛪: For categorical POI (<500 points)
+- **Circle points** ⭕: For large datasets like intersections (>500 points)
+
+### Spatial Operations
+- Intersection: "Find hospitals within protected areas"
+- Difference: "Show me areas outside national parks"
+- Buffer: "Show 5km radius around hospitals"
+
+### Multi-Step Queries
+Complex questions automatically decomposed:
+- "Compare population density with hospital coverage by province"
+  1. Calculate population per province
+  2. Count hospitals per province
+  3. Compute ratios
+  4. Generate comparison chart
+
+---
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| **[ARCHITECTURE.md](ARCHITECTURE.md)** | System design, components, decisions |
+| **[SETUP.md](SETUP.md)** | Development environment setup |
+| **[docs/backend/CORE_SERVICES.md](docs/backend/CORE_SERVICES.md)** | Backend services reference |
+| **[docs/backend/API_ENDPOINTS.md](docs/backend/API_ENDPOINTS.md)** | API endpoint documentation |
+| **[docs/frontend/COMPONENTS.md](docs/frontend/COMPONENTS.md)** | React component architecture |
+| **[docs/DATA_FLOW.md](docs/DATA_FLOW.md)** | End-to-end request walkthrough |
+
+---
+
+## 📄 License
+
+MIT License - see **[LICENSE](LICENSE)** for details.
+
+---
+
+## 🙏 Acknowledgments
+
+**Data Sources**:
+- [OpenStreetMap](https://www.openstreetmap.org/) - Infrastructure and POI data
+- [Humanitarian Data Exchange (HDX)](https://data.humdata.org/) - Administrative boundaries
+- [World Bank Open Data](https://data.worldbank.org/) - Socioeconomic indicators
+- [Kontur Population Dataset](https://data.humdata.org/organization/kontur) - H3 population grid
+- [STRI GIS Portal](https://stridata-si.opendata.arcgis.com/) - Environmental datasets
+
+**Technologies**:
+- [Google Gemini](https://ai.google.dev/) - LLM API
+- [DuckDB](https://duckdb.org/) - Fast in-process analytics
+- [Leaflet](https://leafletjs.com/) - Interactive maps
+- [Next.js](https://nextjs.org/) - React framework
+

SETUP.md

@@ -0,0 +1,455 @@
+# GeoQuery Setup Guide
+
+Complete guide for setting up the GeoQuery development environment.
+
+---
+
+## Prerequisites
+
+### Required Software
+
+| Requirement | Minimum Version | Purpose |
+|------------|----------------|---------|
+| **Python** | 3.11+ | Backend runtime |
+| **Node.js** | 18+ | Frontend runtime |
+| **npm** | 9+ | Package management |
+| **Git** | 2.0+ | Version control |
+
+### API Keys
+
+- **Google AI API Key (Gemini)**: Required for LLM functionality
+  - Get one free at: https://aistudio.google.com/app/apikey
+  - Free tier: 15 requests/minute, 1500/day
+
+### System Requirements
+
+- **RAM**: 4GB minimum, 8GB recommended (for DuckDB in-memory database)
+- **Disk**: 2GB for datasets
+- **OS**: macOS, Linux, or Windows (WSL recommended)
+
+---
+
+## Installation
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/GerardCB/GeoQuery.git
+cd GeoQuery
+```
+
+### 2. Backend Setup
+
+#### Create Virtual Environment
+
+```bash
+cd backend
+python3 -m venv venv
+```
+
+#### Activate Virtual Environment
+
+**macOS/Linux**:
+```bash
+source venv/bin/activate
+```
+
+**Windows** (PowerShell):
+```powershell
+venv\Scripts\Activate.ps1
+```
+
+**Windows** (CMD):
+```cmd
+venv\Scripts\activate.bat
+```
+
+#### Install Dependencies
+
+```bash
+pip install --upgrade pip
+pip install -e .
+```
+
+This installs the package in editable mode, including all dependencies from `setup.py`.
+
+**Key Dependencies**:
+- `fastapi` - Web framework
+- `uvicorn` - ASGI server
+- `duckdb` - Embedded database
+- `geopandas` - Geospatial data processing
+- `sentence-transformers` - Embeddings
+- `google-generativeai` - Gemini SDK
+
+#### Configure Environment Variables
+
+Create `.env` file in `backend/` directory:
+
+```bash
+# Required
+GEMINI_API_KEY=your-api-key-here
+
+# Optional (defaults shown)
+PORT=8000
+HOST=0.0.0.0
+LOG_LEVEL=INFO
+```
+
+**Alternative**: Export directly in terminal:
+
+```bash
+export GEMINI_API_KEY="your-api-key-here"
+```
+
+**Windows**:
+```powershell
+$env:GEMINI_API_KEY="your-api-key-here"
+```
+
+#### Verify Backend Installation
+
+```bash
+python -c "import backend; print('Backend installed successfully')"
+```
+
+### 3. Frontend Setup
+
+```bash
+cd ../frontend  # From backend directory
+npm install
+```
+
+**Key Dependencies**:
+- `next` - React framework
+- `react` - UI library
+- `leaflet` - Map library
+- `react-leaflet` - React bindings for Leaflet
+- `@dnd-kit/core` - Drag and drop
+
+#### Configure Frontend (Optional)
+
+Edit `frontend/.env.local` if backend is not on default port:
+
+```bash
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+---
+
+## Running Locally
+
+### Start Backend
+
+From `backend/` directory with venv activated:
+
+```bash
+uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+**Flags**:
+- `--reload`: Auto-restart on code changes
+- `--host 0.0.0.0`: Allow external connections
+- `--port 8000`: Port number
+
+**Expected Output**:
+```
+INFO:     Uvicorn running on http://0.0.0.0:8000
+INFO:     Application startup complete.
+```
+
+**Verify**:
+- Open http://localhost:8000/docs  → Should show FastAPI Swagger UI
+- Check http://localhost:8000/api/catalog → Should return GeoJSON catalog
+
+### Start Frontend
+
+From `frontend/` directory:
+
+```bash
+npm run dev
+```
+
+**Expected Output**:
+```
+▲ Next.js 15.1.3
+- Local:        http://localhost:3000
+- Ready in 2.1s
+```
+
+**Verify**:
+- Open http://localhost:3000 → Should show GeoQuery chat interface
+
+---
+
+## Database Setup
+
+### DuckDB Initialization
+
+**Automatic**: Database is created in-memory on first query.
+
+**Manual Test**:
+
+```python
+from backend.core.geo_engine import get_geo_engine
+
+engine = get_geo_engine()
+print(f"Loaded tables: {list(engine.loaded_tables.keys())}")
+```
+
+### Load Initial Datasets
+
+Datasets are loaded lazily (on-demand). To pre-load common datasets:
+
+```python
+from backend.core.geo_engine import get_geo_engine
+
+engine = get_geo_engine()
+engine.ensure_table_loaded("pan_admin1")  # Provinces
+engine.ensure_table_loaded("panama_healthsites_geojson")  # Hospitals
+```
+
+### Generate Embeddings
+
+Required for semantic search:
+
+```bash
+cd backend
+python -c "from backend.core.semantic_search import get_semantic_search; get_semantic_search()"
+```
+
+This generates `backend/data/embeddings.npy` (cached for future use).
+
+---
+
+## Directory Structure After Setup
+
+```
+GeoQuery/
+├── backend/
+│   ├── venv/                   # Virtual environment (created)
+│   ├── .env                    # Environment variables (created)
+│   ├── data/
+│   │   ├── embeddings.npy      # Generated embeddings (created)
+│   │   ├── catalog.json        # Dataset registry (existing)
+│   │   └── osm/                # GeoJSON datasets (existing)
+│   └── <source files>
+├── frontend/
+│   ├── node_modules/           # npm packages (created)
+│   ├── .next/                  # Build output (created)
+│   └── <source files>
+└── <other files>
+```
+
+---
+
+## Common Issues & Troubleshooting
+
+### Backend Issues
+
+#### Issue: "ModuleNotFoundError: No module named 'backend'"
+
+**Cause**: Virtual environment not activated or package not installed.
+
+**Solution**:
+```bash
+source venv/bin/activate  # Activate venv
+pip install -e .          # Install package
+```
+
+#### Issue: "duckdb.IOException: No files found that match the pattern"
+
+**Cause**: GeoJSON file missing or incorrect path in catalog.json.
+
+**Solution**:
+1. Check file exists: `ls backend/data/osm/hospitals.geojson`
+2. Verify path in `catalog.json`
+3. Download missing data: `python backend/scripts/download_geofabrik.py`
+
+#### Issue: "google.api_core.exceptions.PermissionDenied: API key not valid"
+
+**Cause**: Invalid or missing GEMINI_API_KEY.
+
+**Solution**:
+```bash
+export GEMINI_API_KEY="your-actual-api-key"
+# Restart backend
+```
+
+#### Issue: "Module 'sentence_transformers' has no attribute 'SentenceTransformer'"
+
+**Cause**: Corrupted installation.
+
+**Solution**:
+```bash
+pip uninstall sentence-transformers
+pip install sentence-transformers --no-cache-dir
+```
+
+### Frontend Issues
+
+#### Issue: "Error: Cannot find module 'next'"
+
+**Cause**: npm packages not installed.
+
+**Solution**:
+```bash
+cd frontend
+rm -rf node_modules package-lock.json
+npm install
+```
+
+#### Issue: "Failed to fetch from localhost:8000"
+
+**Cause**: Backend not running or CORS issue.
+
+**Solution**:
+1. Verify backend is running: `curl http://localhost:8000/api/catalog`
+2. Check CORS settings in `backend/main.py`
+3. Verify `NEXT_PUBLIC_API_URL` in frontend `.env.local`
+
+#### Issue: "Map tiles not loading"
+
+**Cause**: Network issue or ad blocker.
+
+**Solution**:
+1. Check internet connection
+2. Disable ad blocker for localhost
+3. Alternative tile server in `MapViewer.tsx`:
+   ```typescript
+   url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+   ```
+
+### General Issues
+
+#### Issue: Port 8000 already in use
+
+**Solution**:
+```bash
+# Find process using port
+lsof -ti:8000
+
+# Kill process
+kill -9 $(lsof -ti:8000)
+
+# Or use different port
+uvicorn backend.main:app --port 8001
+```
+
+#### Issue: Out of memory errors
+
+**Cause**: Loading too many large datasets.
+
+**Solution**:
+1. Reduce dataset size (filter before loading)
+2. Increase system RAM
+3. Use query limits: `LIMIT 10000`
+
+---
+
+## Development Workflow
+
+### Code Changes
+
+**Backend**:
+- Python files auto-reload with `--reload` flag
+- Changes in `core/`, `services/`, `api/` take effect immediately
+
+**Frontend**:
+- Hot Module Replacement (HMR) enabled
+- Changes in `components/`, `app/` reload automatically
+
+### Adding New Datasets
+
+1. **Add GeoJSON file** to appropriate directory (e.g., `backend/data/osm/`)
+
+2. **Update catalog.json**:
+   ```json
+   "my_new_dataset": {
+     "path": "osm/my_new_dataset.geojson",
+     "description": "Description for display",
+     "semantic_description": "Detailed description for AI",
+     "categories": ["infrastructure"],
+     "tags": ["roads", "transport"]
+   }
+   ```
+
+3. **Regenerate embeddings**:
+   ```bash
+   rm backend/data/embeddings.npy
+   python -c "from backend.core.semantic_search import get_semantic_search; get_semantic_search()"
+   ```
+
+4. **Test**: Query for the new dataset
+
+See [docs/backend/SCRIPTS.md](docs/backend/SCRIPTS.md) for data ingestion scripts.
+
+### Testing API Endpoints
+
+**Using curl**:
+```bash
+# Get catalog
+curl http://localhost:8000/api/catalog
+
+# Query chat endpoint
+curl -X POST http://localhost:8000/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Show me provinces", "history": []}'
+```
+
+**Using Swagger UI**:
+- Open http://localhost:8000/docs
+- Try endpoints interactively
+
+---
+
+## Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GEMINI_API_KEY` | ✅ Yes | - | Google AI API key |
+| `PORT` | ❌ No | 8000 | Backend server port |
+| `HOST` | ❌ No | 0.0.0.0 | Backend host |
+| `LOG_LEVEL` | ❌ No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `DATABASE_PATH` | ❌ No | :memory: | DuckDB database path (use for persistence) |
+
+---
+
+## IDE Setup
+
+### VS Code
+
+**Recommended Extensions**:
+- Python (`ms-python.python`)
+- Pylance (`ms-python.vscode-pylance`)
+- ESLint (`dbaeumer.vscode-eslint`)
+- Prettier (`esbenp.prettier-vscode`)
+
+**Settings** (`.vscode/settings.json`):
+```json
+{
+  "python.defaultInterpreterPath": "./backend/venv/bin/python",
+  "python.linting.enabled": true,
+  "python.formatting.provider": "black",
+  "editor.formatOnSave": true,
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}
+```
+
+### PyCharm
+
+1. **Set Python Interpreter**: Settings → Project → Python Interpreter → Add → Existing Environment → `backend/venv/bin/python`
+2. **Enable FastAPI**: Settings → Languages & Frameworks → FastAPI
+3. **Configure Run**: Run → Edit Configurations → Add → Python → Script path: `backend/main.py`
+
+---
+
+## Next Steps
+
+- ✅ **Verify installation** by running a test query
+- 📖 **Read [ARCHITECTURE.md](../ARCHITECTURE.md)** to understand the system
+- 🔧 **Explore [docs/backend/CORE_SERVICES.md](docs/backend/CORE_SERVICES.md)** for component details
+- 📊 **Review [docs/data/DATASET_SOURCES.md](docs/data/DATASET_SOURCES.md)** for available data
+
+

backend/api/api.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+from backend.api.endpoints import chat, schema, catalog
+
+api_router = APIRouter()
+api_router.include_router(chat.router, prefix="/chat", tags=["chat"])
+api_router.include_router(schema.router, prefix="/schema", tags=["schema"])
+api_router.include_router(catalog.router, prefix="/catalog", tags=["catalog"])
+

backend/api/endpoints/catalog.py

@@ -0,0 +1,235 @@
+"""
+Catalog Management Endpoints
+
+Provides API for viewing and enriching the data catalog.
+"""
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from pydantic import BaseModel
+from typing import List, Optional, Dict, Any
+
+router = APIRouter()
+
+
+class CatalogStatsResponse(BaseModel):
+    total_datasets: int
+    enriched_datasets: int
+    by_category: Dict[str, int]
+    by_tag: Dict[str, int]
+
+
+class TableMetadataResponse(BaseModel):
+    name: str
+    path: str
+    description: str
+    semantic_description: Optional[str]
+    tags: List[str]
+    data_type: str
+    columns: List[str]
+    row_count: Optional[int]
+    category: str
+    last_indexed: Optional[str]
+    last_enriched: Optional[str]
+
+
+class EnrichmentRequest(BaseModel):
+    table_names: Optional[List[str]] = None  # None = all tables
+    force_refresh: bool = False
+
+
+class EnrichmentResponse(BaseModel):
+    status: str
+    message: str
+    tables_queued: int
+
+
+@router.get("/stats", response_model=CatalogStatsResponse)
+async def get_catalog_stats():
+    """Get statistics about the data catalog."""
+    from backend.core.data_catalog import get_data_catalog
+    
+    catalog = get_data_catalog()
+    stats = catalog.get_stats()
+    
+    return CatalogStatsResponse(
+        total_datasets=stats["total_datasets"],
+        enriched_datasets=stats.get("enriched_datasets", 0),
+        by_category=stats["by_category"],
+        by_tag=stats["by_tag"]
+    )
+
+
+@router.get("/tables", response_model=List[TableMetadataResponse])
+async def list_catalog_tables():
+    """List all tables in the catalog with their metadata."""
+    from backend.core.data_catalog import get_data_catalog
+    
+    catalog = get_data_catalog()
+    tables = []
+    
+    for name, meta in catalog.catalog.items():
+        tables.append(TableMetadataResponse(
+            name=name,
+            path=meta.get("path", ""),
+            description=meta.get("description", ""),
+            semantic_description=meta.get("semantic_description"),
+            tags=meta.get("tags", []),
+            data_type=meta.get("data_type", "static"),
+            columns=meta.get("columns", []),
+            row_count=meta.get("row_count"),
+            category=meta.get("category", "unknown"),
+            last_indexed=meta.get("last_indexed"),
+            last_enriched=meta.get("last_enriched")
+        ))
+    
+    return tables
+
+
+@router.get("/tables/{table_name}", response_model=TableMetadataResponse)
+async def get_table_metadata(table_name: str):
+    """Get metadata for a specific table."""
+    from backend.core.data_catalog import get_data_catalog
+    
+    catalog = get_data_catalog()
+    meta = catalog.get_table_metadata(table_name)
+    
+    if not meta:
+        raise HTTPException(status_code=404, detail=f"Table '{table_name}' not found")
+    
+    return TableMetadataResponse(
+        name=table_name,
+        path=meta.get("path", ""),
+        description=meta.get("description", ""),
+        semantic_description=meta.get("semantic_description"),
+        tags=meta.get("tags", []),
+        data_type=meta.get("data_type", "static"),
+        columns=meta.get("columns", []),
+        row_count=meta.get("row_count"),
+        category=meta.get("category", "unknown"),
+        last_indexed=meta.get("last_indexed"),
+        last_enriched=meta.get("last_enriched")
+    )
+
+
+@router.post("/enrich", response_model=EnrichmentResponse)
+async def enrich_catalog(request: EnrichmentRequest, background_tasks: BackgroundTasks):
+    """
+    Trigger LLM enrichment for catalog tables.
+    
+    Enrichment generates semantic descriptions and refined tags.
+    Runs in the background to avoid blocking.
+    """
+    from backend.core.data_catalog import get_data_catalog
+    
+    catalog = get_data_catalog()
+    
+    if request.table_names:
+        # Validate table names
+        invalid = [t for t in request.table_names if t not in catalog.catalog]
+        if invalid:
+            raise HTTPException(
+                status_code=400, 
+                detail=f"Unknown tables: {invalid}"
+            )
+        tables_to_enrich = request.table_names
+    else:
+        tables_to_enrich = list(catalog.catalog.keys())
+    
+    # Queue enrichment in background
+    async def run_enrichment():
+        for table_name in tables_to_enrich:
+            await catalog.enrich_table(table_name, request.force_refresh)
+    
+    background_tasks.add_task(run_enrichment)
+    
+    return EnrichmentResponse(
+        status="queued",
+        message=f"Enrichment started for {len(tables_to_enrich)} tables",
+        tables_queued=len(tables_to_enrich)
+    )
+
+
+@router.post("/enrich/{table_name}")
+async def enrich_single_table(table_name: str, force: bool = False):
+    """
+    Immediately enrich a single table (synchronous).
+    
+    Use for testing or when you need the result right away.
+    """
+    from backend.core.data_catalog import get_data_catalog
+    
+    catalog = get_data_catalog()
+    
+    if table_name not in catalog.catalog:
+        raise HTTPException(status_code=404, detail=f"Table '{table_name}' not found")
+    
+    success = await catalog.enrich_table(table_name, force)
+    
+    if success:
+        meta = catalog.get_table_metadata(table_name)
+        return {
+            "status": "success",
+            "table": table_name,
+            "semantic_description": meta.get("semantic_description"),
+            "tags": meta.get("tags", [])
+        }
+    else:
+        raise HTTPException(status_code=500, detail=f"Failed to enrich table '{table_name}'")
+
+
+@router.get("/search")
+async def search_tables(query: str, top_k: int = 10):
+    """
+    Search for tables using semantic search.
+    
+    Returns the most relevant tables for a natural language query.
+    """
+    from backend.core.semantic_search import get_semantic_search
+    from backend.core.data_catalog import get_data_catalog
+    
+    semantic = get_semantic_search()
+    catalog = get_data_catalog()
+    
+    results = semantic.search(query, top_k=top_k)
+    
+    response = []
+    for table_name, score in results:
+        meta = catalog.get_table_metadata(table_name)
+        if meta:
+            response.append({
+                "table": table_name,
+                "score": round(score, 4),
+                "description": meta.get("semantic_description") or meta.get("description"),
+                "tags": meta.get("tags", [])
+            })
+    
+    return {"query": query, "results": response}
+
+
+@router.post("/rebuild-embeddings")
+async def rebuild_embeddings():
+    """
+    Rebuild all semantic search embeddings from current catalog.
+    
+    Use after bulk enrichment or catalog updates.
+    """
+    from backend.core.semantic_search import get_semantic_search
+    from backend.core.data_catalog import get_data_catalog
+    
+    semantic = get_semantic_search()
+    catalog = get_data_catalog()
+    
+    # Force re-embed all tables
+    count = 0
+    for table_name, metadata in catalog.catalog.items():
+        if semantic.embed_table(table_name, metadata):
+            count += 1
+    
+    semantic._save_embeddings()
+    
+    return {
+        "status": "success",
+        "message": f"Rebuilt embeddings for {count} tables",
+        "total_embeddings": len(semantic.embeddings)
+    }
+

backend/api/endpoints/chat.py

@@ -0,0 +1,90 @@
+from fastapi import APIRouter
+from pydantic import BaseModel
+from typing import Optional
+from backend.services.executor import QueryExecutor
+
+router = APIRouter()
+
+
+class MessageHistory(BaseModel):
+    role: str  # "user" or "assistant"
+    content: str
+
+
+class ChatRequest(BaseModel):
+    message: str
+    history: list[MessageHistory] = []
+
+
+class ChartData(BaseModel):
+    type: str  # 'bar', 'line', 'pie', 'donut'
+    title: Optional[str] = None
+    data: list[dict] = []
+    xKey: Optional[str] = None
+    yKey: Optional[str] = None
+    lines: Optional[list[dict]] = None
+
+
+class ChatResponse(BaseModel):
+    response: str
+    sql_query: Optional[str] = None
+    geojson: Optional[dict] = None
+    data_citations: list[str] = []
+    intent: Optional[str] = None
+    chart_data: Optional[ChartData] = None  # NEW: For STAT_QUERY responses
+
+
+@router.post("/", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+    """
+    Main chat endpoint that handles conversation with context.
+    Routes to appropriate handler based on detected intent.
+    """
+    executor = QueryExecutor()
+    
+    # Convert history to dict format for the executor
+    history = [{"role": h.role, "content": h.content} for h in request.history]
+    
+    # Process the query with full context
+    result = await executor.process_query_with_context(
+        query=request.message,
+        history=history
+    )
+    
+    return ChatResponse(
+        response=result.get("response", "I processed your request."),
+        sql_query=result.get("sql_query"),
+        geojson=result.get("geojson"),
+        data_citations=result.get("data_citations", []),
+        intent=result.get("intent"),
+        chart_data=result.get("chart_data"),
+        raw_data=result.get("raw_data")
+    )
+
+
+from sse_starlette.sse import EventSourceResponse
+import json
+import asyncio
+
+@router.post("/stream")
+async def chat_stream(request: ChatRequest):
+    """
+    Streaming chat endpoint that returns Server-Sent Events (SSE).
+    """
+    executor = QueryExecutor()
+    history = [{"role": h.role, "content": h.content} for h in request.history]
+
+    async def event_generator():
+        try:
+            # Delegate entirely to the executor's streaming process
+            async for event in executor.process_query_stream(request.message, history):
+                yield event
+
+        except Exception as e:
+            print(f"Stream error: {e}")
+            yield {
+                "event": "chunk", 
+                "data": json.dumps({"type": "text", "content": f"\n\nError: {str(e)}"})
+            }
+
+    return EventSourceResponse(event_generator())

backend/api/endpoints/schema.py

@@ -0,0 +1,84 @@
+"""
+Schema endpoint - Provides data catalog information to users.
+Shows available tables, columns, and data descriptions.
+"""
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+from typing import Optional, List, Any
+from backend.core.data_catalog import get_data_catalog
+
+router = APIRouter()
+
+
+class ColumnInfo(BaseModel):
+    name: str
+    type: str
+    description: Optional[str] = None
+
+
+class TableInfo(BaseModel):
+    name: str
+    description: str
+    row_count: int
+    columns: List[ColumnInfo]
+
+
+class SchemaResponse(BaseModel):
+    tables: List[TableInfo]
+    last_updated: str
+    data_source: str
+
+
+@router.get("/", response_model=SchemaResponse)
+async def get_schema():
+    """
+    Returns the dynamic data catalog with all available tables and their schemas.
+    """
+    catalog = get_data_catalog()
+    tables = []
+    
+    for table_name, meta in catalog.catalog.items():
+        # Map catalog columns to Schema columns
+        # Catalog columns are just a list of strings usually
+        cols = []
+        raw_cols = meta.get("columns", [])
+        
+        # Helper to guess type
+        def guess_type(col_name):
+            if col_name == "geom": return "geometry"
+            if "id" in col_name: return "integer"
+            if "name" in col_name: return "text"
+            return "text" # Default
+            
+        for col in raw_cols:
+            cols.append(ColumnInfo(
+                name=col, 
+                type=guess_type(col),
+                description=None
+            ))
+            
+        tables.append(TableInfo(
+            name=table_name,
+            description=meta.get("semantic_description") or meta.get("description", ""),
+            row_count=meta.get("row_count") or 0,
+            columns=cols
+        ))
+    
+    return SchemaResponse(
+        tables=tables,
+        last_updated="Dynamic",
+        data_source="GeoQuery Data Catalog (OSM, Overture, HDX, INEC)"
+    )
+
+
+@router.get("/tables")
+async def list_tables():
+    """
+    Returns a simple list of available table names.
+    """
+    catalog = get_data_catalog()
+    return {
+        "tables": list(catalog.catalog.keys()),
+        "count": len(catalog.catalog)
+    }

backend/core/catalog_enricher.py

@@ -0,0 +1,221 @@
+"""
+Catalog Enricher Service
+
+Automatically generates rich metadata for datasets using LLM.
+Enhances table descriptions and tags for better semantic search.
+"""
+
+import logging
+from typing import Dict, List, Any, Optional
+from backend.core.llm_gateway import LLMGateway
+
+logger = logging.getLogger(__name__)
+
+
+# Prompt for generating semantic descriptions
+DESCRIPTION_PROMPT = """Generate a concise 2-3 sentence description for this geographic dataset.
+
+Table Name: {table_name}
+Category: {category}
+Columns: {columns}
+Sample Column Values: {sample_values}
+Row Count: {row_count}
+
+Focus on:
+1. What geographic entities it contains (districts, health facilities, roads, etc.)
+2. The geographic scope (Panama, specific province, etc.)
+3. Common use cases (administrative analysis, health coverage, etc.)
+
+Return ONLY the description, no formatting or labels."""
+
+# Prompt for generating/refining tags
+TAG_PROMPT = """Suggest 5-8 relevant tags for this geographic dataset.
+
+Table Name: {table_name}
+Description: {description}
+Columns: {columns}
+Current Tags: {current_tags}
+
+Rules:
+1. Tags should be lowercase, single words or hyphenated
+2. Include domain tags (health, education, infrastructure)
+3. Include geographic tags (administrative, boundaries, points)
+4. Include data type tags (census, osm, government)
+
+Return ONLY a JSON array of strings, e.g. ["health", "facilities", "infrastructure"]"""
+
+
+class CatalogEnricher:
+    """
+    Enriches catalog metadata with LLM-generated descriptions and tags.
+    
+    Can be run on-demand for new datasets or batch-run for existing ones.
+    """
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(CatalogEnricher, cls).__new__(cls)
+            cls._instance.initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        if self.initialized:
+            return
+            
+        self.llm = LLMGateway()
+        self.initialized = True
+    
+    async def generate_description(
+        self, 
+        table_name: str, 
+        metadata: Dict[str, Any],
+        sample_values: Optional[Dict[str, str]] = None
+    ) -> str:
+        """
+        Generate a semantic description for a dataset using LLM.
+        
+        Args:
+            table_name: Name of the table
+            metadata: Catalog metadata dict
+            sample_values: Optional dict of column -> sample value
+            
+        Returns:
+            Generated description string
+        """
+        columns = metadata.get("columns", [])
+        category = metadata.get("category", "unknown")
+        row_count = metadata.get("row_count", "unknown")
+        
+        # Format sample values
+        sample_str = "Not available"
+        if sample_values:
+            sample_str = ", ".join(f"{k}: {v}" for k, v in list(sample_values.items())[:5])
+        
+        prompt = DESCRIPTION_PROMPT.format(
+            table_name=table_name,
+            category=category,
+            columns=", ".join(columns[:15]),  # Limit columns
+            sample_values=sample_str,
+            row_count=row_count
+        )
+        
+        try:
+            response = await self.llm.generate_response(prompt)
+            description = response.strip()
+            
+            # Basic validation
+            if len(description) < 20 or len(description) > 500:
+                logger.warning(f"Generated description for {table_name} seems unusual: {len(description)} chars")
+            
+            return description
+            
+        except Exception as e:
+            logger.error(f"Failed to generate description for {table_name}: {e}")
+            return metadata.get("description", f"Geographic data from {category}")
+    
+    async def generate_tags(
+        self, 
+        table_name: str, 
+        metadata: Dict[str, Any]
+    ) -> List[str]:
+        """
+        Generate or refine tags for a dataset using LLM.
+        
+        Args:
+            table_name: Name of the table
+            metadata: Catalog metadata dict
+            
+        Returns:
+            List of tag strings
+        """
+        columns = metadata.get("columns", [])
+        description = metadata.get("semantic_description") or metadata.get("description", "")
+        current_tags = metadata.get("tags", [])
+        
+        prompt = TAG_PROMPT.format(
+            table_name=table_name,
+            description=description,
+            columns=", ".join(columns[:15]),
+            current_tags=current_tags
+        )
+        
+        try:
+            import json
+            response = await self.llm.generate_response(prompt)
+            
+            # Parse JSON array
+            response = response.strip()
+            if response.startswith("```"):
+                response = response.split("```")[1]
+                if response.startswith("json"):
+                    response = response[4:]
+            
+            tags = json.loads(response)
+            
+            if isinstance(tags, list):
+                # Validate and clean tags
+                clean_tags = []
+                for tag in tags:
+                    if isinstance(tag, str):
+                        tag = tag.lower().strip()
+                        if 2 <= len(tag) <= 30:
+                            clean_tags.append(tag)
+                
+                return clean_tags
+            
+        except Exception as e:
+            logger.error(f"Failed to generate tags for {table_name}: {e}")
+        
+        return current_tags
+    
+    async def enrich_table(
+        self, 
+        table_name: str, 
+        metadata: Dict[str, Any],
+        sample_values: Optional[Dict[str, str]] = None,
+        force_refresh: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Fully enrich a table's metadata with description and tags.
+        
+        Args:
+            table_name: Name of the table
+            metadata: Current catalog metadata
+            sample_values: Optional sample data for context
+            force_refresh: If True, regenerate even if already enriched
+            
+        Returns:
+            Updated metadata dict
+        """
+        updated = metadata.copy()
+        
+        # Generate description if missing or forced
+        if force_refresh or not metadata.get("semantic_description"):
+            logger.info(f"Generating semantic description for {table_name}...")
+            description = await self.generate_description(table_name, metadata, sample_values)
+            updated["semantic_description"] = description
+        
+        # Generate/refine tags (always, to improve quality)
+        if force_refresh or len(metadata.get("tags", [])) < 3:
+            logger.info(f"Generating tags for {table_name}...")
+            tags = await self.generate_tags(table_name, updated)
+            # Merge with existing, deduplicate
+            existing_tags = set(metadata.get("tags", []))
+            new_tags = set(tags)
+            updated["tags"] = list(existing_tags | new_tags)
+        
+        return updated
+
+
+# Singleton accessor
+_catalog_enricher: Optional[CatalogEnricher] = None
+
+
+def get_catalog_enricher() -> CatalogEnricher:
+    """Get the singleton catalog enricher instance."""
+    global _catalog_enricher
+    if _catalog_enricher is None:
+        _catalog_enricher = CatalogEnricher()
+    return _catalog_enricher

backend/core/data_catalog.py

@@ -0,0 +1,445 @@
+"""
+Data Catalog Service
+
+Manages metadata for all datasets available in the platform.
+Supports semantic search integration for scalable discovery.
+"""
+
+import json
+import duckdb
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Tag inference rules for auto-tagging datasets
+TAG_RULES = {
+    # Keywords in table name -> tags
+    "health": ["health", "facilities", "infrastructure"],
+    "hospital": ["health", "facilities", "medical"],
+    "clinic": ["health", "facilities", "medical"],
+    "school": ["education", "facilities", "infrastructure"],
+    "university": ["education", "facilities", "higher-education"],
+    "education": ["education", "facilities"],
+    "road": ["transportation", "infrastructure", "roads"],
+    "street": ["transportation", "infrastructure", "roads"],
+    "highway": ["transportation", "infrastructure", "roads"],
+    "airport": ["transportation", "infrastructure", "aviation"],
+    "port": ["transportation", "infrastructure", "maritime"],
+    "population": ["demographics", "census", "population"],
+    "census": ["demographics", "census", "statistics"],
+    "admin": ["administrative", "boundaries", "government"],
+    "district": ["administrative", "boundaries"],
+    "province": ["administrative", "boundaries"],
+    "corregimiento": ["administrative", "boundaries"],
+    "park": ["recreation", "green-space", "amenities"],
+    "water": ["hydrology", "natural-resources"],
+    "river": ["hydrology", "water"],
+    "forest": ["environment", "natural-resources", "land-cover"],
+    "building": ["infrastructure", "built-environment"],
+    "poi": ["points-of-interest", "amenities"],
+}
+
+
+class DataCatalog:
+    """
+    Singleton service managing dataset metadata.
+    
+    Features:
+    - Auto-discovery of GeoJSON files in data directories
+    - Schema inference from first record
+    - Auto-tagging based on naming conventions
+    - Integration with semantic search for scalable discovery
+    """
+    
+    _instance = None
+    
+    DATA_DIR = Path(__file__).parent.parent / "data"
+    CATALOG_FILE = DATA_DIR / "catalog.json"
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(DataCatalog, cls).__new__(cls)
+            cls._instance.initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if self.initialized:
+            return
+            
+        self.catalog: Dict[str, Any] = {}
+        self.load_catalog()
+        self.scan_and_update()
+        self._init_semantic_search()
+        self.initialized = True
+
+    def load_catalog(self):
+        """Load catalog from JSON file."""
+        if self.CATALOG_FILE.exists():
+            try:
+                with open(self.CATALOG_FILE, 'r') as f:
+                    self.catalog = json.load(f)
+            except Exception as e:
+                logger.error(f"Failed to load catalog: {e}")
+                self.catalog = {}
+        else:
+            self.catalog = {}
+
+    def save_catalog(self):
+        """Save catalog to JSON file."""
+        try:
+            with open(self.CATALOG_FILE, 'w') as f:
+                json.dump(self.catalog, f, indent=2)
+        except Exception as e:
+            logger.error(f"Failed to save catalog: {e}")
+
+    def _infer_tags(self, table_name: str, columns: List[str]) -> List[str]:
+        """Auto-generate tags based on table name and columns."""
+        tags = set()
+        name_lower = table_name.lower()
+        
+        # Check table name against rules
+        for keyword, keyword_tags in TAG_RULES.items():
+            if keyword in name_lower:
+                tags.update(keyword_tags)
+        
+        # Check columns for additional hints
+        columns_lower = [c.lower() for c in columns]
+        if any('pop' in c for c in columns_lower):
+            tags.add("population")
+        if any('area' in c for c in columns_lower):
+            tags.add("geographic")
+        if 'geom' in columns_lower or 'geometry' in columns_lower:
+            tags.add("spatial")
+        
+        return list(tags)
+
+    def _infer_data_type(self, category: str, table_name: str) -> str:
+        """Infer data type (static, semi-static, realtime)."""
+        # Base admin data is static
+        if category == "base":
+            return "static"
+        
+        # OSM data is semi-static (updated periodically)
+        if category == "osm":
+            return "semi-static"
+        
+        # HDX humanitarian data - varies
+        if category == "hdx":
+            return "semi-static"
+        
+        # Census data is static
+        if "census" in table_name.lower():
+            return "static"
+        
+        return "static"
+
+    def scan_and_update(self):
+        """Scan data directories and update catalog with new files."""
+        logger.info("Scanning data directories...")
+        
+        # Define directories to scan
+        subdirs = ['base', 'osm', 'inec', 'hdx', 'custom', 'overture', 'ms_buildings']
+        
+        # Temporary connection for schema inference
+        con = duckdb.connect(':memory:')
+        con.install_extension('spatial')
+        con.load_extension('spatial')
+        
+        updated = False
+        
+        for subdir in subdirs:
+            dir_path = self.DATA_DIR / subdir
+            if not dir_path.exists():
+                continue
+                
+            # Scan for both .geojson and .geojson.gz
+            for file_path in list(dir_path.glob('**/*.geojson')) + list(dir_path.glob('**/*.geojson.gz')):
+                table_name = file_path.name.replace('.geojson.gz', '').replace('.geojson', '').lower().replace('-', '_').replace(' ', '_')
+                
+                # Check if file path changed (file moved/renamed)
+                existing = self.catalog.get(table_name)
+                rel_path = str(file_path.relative_to(self.DATA_DIR))
+                
+                if existing and existing.get('path') == rel_path:
+                    # Already indexed with same path, skip unless missing new fields
+                    if 'tags' in existing and 'data_type' in existing:
+                        continue
+                
+                try:
+                    logger.info(f"Indexing {table_name}...")
+                    
+                    # Read first row to get columns
+                    query = f"SELECT * FROM ST_Read('{file_path}') LIMIT 1"
+                    df = con.execute(query).fetchdf()
+                    columns = list(df.columns)
+                    
+                    # Count rows (for metadata)
+                    row_count_query = f"SELECT COUNT(*) FROM ST_Read('{file_path}')"
+                    row_count = con.execute(row_count_query).fetchone()[0]
+                    
+                    # Auto-generate tags
+                    tags = self._infer_tags(table_name, columns)
+                    
+                    # Infer data type
+                    data_type = self._infer_data_type(subdir, table_name)
+                    
+                    # Build catalog entry
+                    self.catalog[table_name] = {
+                        "path": rel_path,
+                        "description": f"Data from {subdir}/{file_path.name}",
+                        "semantic_description": None,  # LLM-generated on demand
+                        "tags": tags,
+                        "data_type": data_type,
+                        "update_frequency": None,
+                        "columns": columns,
+                        "row_count": row_count,
+                        "category": subdir,
+                        "format": "geojson",
+                        "last_indexed": datetime.now().isoformat()
+                    }
+                    updated = True
+                    
+                except Exception as e:
+                    logger.warning(f"Failed to index {file_path}: {e}")
+        
+        con.close()
+        
+        if updated:
+            self.save_catalog()
+            logger.info("Catalog updated.")
+
+    def _init_semantic_search(self):
+        """Initialize semantic search with current catalog."""
+        try:
+            from backend.core.semantic_search import get_semantic_search
+            semantic = get_semantic_search()
+            
+            # Embed all tables
+            new_embeddings = semantic.embed_all_tables(self.catalog)
+            if new_embeddings > 0:
+                logger.info(f"Created {new_embeddings} new semantic embeddings.")
+        except Exception as e:
+            logger.warning(f"Semantic search initialization failed: {e}")
+
+    def get_table_metadata(self, table_name: str) -> Optional[Dict]:
+        """Get metadata for a specific table."""
+        return self.catalog.get(table_name)
+
+    def get_all_table_summaries(self) -> str:
+        """
+        Returns a concise summary of all tables.
+        
+        WARNING: This can be very large with many datasets.
+        Prefer using semantic_search.search() for discovery.
+        """
+        summary = "Available Data Tables:\n"
+        
+        # Group by category
+        by_category: Dict[str, List] = {}
+        for name, meta in self.catalog.items():
+            cat = meta.get('category', 'other')
+            if cat not in by_category:
+                by_category[cat] = []
+            by_category[cat].append((name, meta))
+            
+        for cat, items in by_category.items():
+            summary += f"\n## {cat.upper()}\n"
+            for name, meta in items:
+                desc = meta.get('semantic_description') or meta.get('description', 'No description')
+                tags = meta.get('tags', [])
+                tag_str = f" [{', '.join(tags[:3])}]" if tags else ""
+                summary += f"- {name}: {desc}{tag_str}\n"
+                
+        return summary
+
+    def get_summaries_for_tables(self, table_names: List[str]) -> str:
+        """
+        Get summaries only for specified tables.
+        
+        Used after semantic pre-filtering to build focused LLM context.
+        """
+        summary = "Relevant Data Tables:\n\n"
+        
+        for name in table_names:
+            meta = self.catalog.get(name)
+            if not meta:
+                continue
+            
+            desc = meta.get('semantic_description') or meta.get('description', 'No description')
+            tags = meta.get('tags', [])
+            columns = meta.get('columns', [])[:10]  # Limit columns
+            row_count = meta.get('row_count', 'unknown')
+            
+            summary += f"### {name}\n"
+            summary += f"Description: {desc}\n"
+            if tags:
+                summary += f"Tags: {', '.join(tags)}\n"
+            summary += f"Columns: {', '.join(columns)}\n"
+            summary += f"Rows: {row_count}\n\n"
+        
+        return summary
+
+    def get_specific_table_schemas(self, table_names: List[str]) -> str:
+        """Returns detailed schema for specific tables."""
+        output = ""
+        for name in table_names:
+            meta = self.catalog.get(name)
+            if not meta:
+                continue
+                
+            output += f"### {name}\n"
+            output += f"Description: {meta.get('description')}\n"
+            output += "Columns: " + ", ".join(meta.get('columns', [])) + "\n\n"
+        return output
+
+    def get_file_path(self, table_name: str) -> Optional[Path]:
+        """Get absolute path for a table's data file."""
+        meta = self.catalog.get(table_name)
+        if meta and 'path' in meta:
+            return self.DATA_DIR / meta['path']
+        return None
+
+    def get_tables_by_tag(self, tag: str) -> List[str]:
+        """Get all table names that have a specific tag."""
+        return [
+            name for name, meta in self.catalog.items()
+            if tag in meta.get('tags', [])
+        ]
+
+    def get_tables_by_category(self, category: str) -> List[str]:
+        """Get all table names in a specific category."""
+        return [
+            name for name, meta in self.catalog.items()
+            if meta.get('category') == category
+        ]
+
+    def get_stats(self) -> dict:
+        """Return statistics about the catalog."""
+        categories = {}
+        tags = {}
+        enriched_count = 0
+        
+        for meta in self.catalog.values():
+            cat = meta.get('category', 'other')
+            categories[cat] = categories.get(cat, 0) + 1
+            
+            if meta.get('semantic_description'):
+                enriched_count += 1
+            
+            for tag in meta.get('tags', []):
+                tags[tag] = tags.get(tag, 0) + 1
+        
+        return {
+            "total_datasets": len(self.catalog),
+            "enriched_datasets": enriched_count,
+            "by_category": categories,
+            "by_tag": dict(sorted(tags.items(), key=lambda x: -x[1])[:20]),
+            "catalog_file": str(self.CATALOG_FILE)
+        }
+
+    async def enrich_table(self, table_name: str, force_refresh: bool = False) -> bool:
+        """
+        Enrich a single table with LLM-generated metadata.
+        
+        Returns True if enrichment was successful.
+        """
+        if table_name not in self.catalog:
+            logger.warning(f"Table {table_name} not found in catalog")
+            return False
+        
+        metadata = self.catalog[table_name]
+        
+        # Skip if already enriched (unless forced)
+        if not force_refresh and metadata.get('semantic_description'):
+            logger.info(f"Table {table_name} already enriched, skipping")
+            return True
+        
+        try:
+            from backend.core.catalog_enricher import get_catalog_enricher
+            enricher = get_catalog_enricher()
+            
+            # Get sample values for context
+            sample_values = await self._get_sample_values(table_name)
+            
+            # Enrich
+            enriched = await enricher.enrich_table(table_name, metadata, sample_values, force_refresh)
+            
+            # Update catalog
+            enriched['last_enriched'] = datetime.now().isoformat()
+            self.catalog[table_name] = enriched
+            self.save_catalog()
+            
+            # Re-embed with new description
+            self._update_embedding(table_name, enriched)
+            
+            logger.info(f"Successfully enriched {table_name}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to enrich {table_name}: {e}")
+            return False
+
+    async def enrich_all_tables(self, force_refresh: bool = False) -> Dict[str, bool]:
+        """
+        Enrich all tables in the catalog.
+        
+        Returns dict of table_name -> success status.
+        """
+        results = {}
+        
+        for table_name in self.catalog.keys():
+            success = await self.enrich_table(table_name, force_refresh)
+            results[table_name] = success
+        
+        return results
+
+    async def _get_sample_values(self, table_name: str) -> Optional[Dict[str, str]]:
+        """Get sample values from a table for enrichment context."""
+        try:
+            from backend.core.geo_engine import get_geo_engine
+            geo_engine = get_geo_engine()
+            
+            # Ensure table is loaded
+            geo_engine.ensure_table_loaded(table_name)
+            
+            # Get one row
+            result = geo_engine.con.execute(f"SELECT * FROM {table_name} LIMIT 1").fetchdf()
+            
+            if len(result) > 0:
+                sample = {}
+                for col in result.columns:
+                    if col != 'geom':
+                        val = result[col].iloc[0]
+                        if val is not None:
+                            sample[col] = str(val)[:50]  # Limit value length
+                return sample
+            
+        except Exception as e:
+            logger.debug(f"Could not get sample values for {table_name}: {e}")
+        
+        return None
+
+    def _update_embedding(self, table_name: str, metadata: Dict[str, Any]) -> None:
+        """Update semantic search embedding for a table."""
+        try:
+            from backend.core.semantic_search import get_semantic_search
+            semantic = get_semantic_search()
+            semantic.embed_table(table_name, metadata)
+            semantic._save_embeddings()
+        except Exception as e:
+            logger.warning(f"Could not update embedding for {table_name}: {e}")
+
+
+_data_catalog = None
+
+
+def get_data_catalog() -> DataCatalog:
+    """Get the singleton data catalog instance."""
+    global _data_catalog
+    if _data_catalog is None:
+        _data_catalog = DataCatalog()
+    return _data_catalog

backend/core/database.py

@@ -0,0 +1,34 @@
+from sqlmodel import SQLModel, create_engine
+from sqlmodel.ext.asyncio.session import AsyncSession
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import NullPool
+import os
+
+# Using local Postgres.app
+# Format: postgresql+asyncpg://user:password@host/dbname
+# Postgres.app usually defaults to the current user with no password
+user = os.getenv("USER", "postgres")
+DATABASE_URL = f"postgresql+asyncpg://{user}:@localhost/geoquery"
+
+engine = create_engine(
+    DATABASE_URL,
+    echo=True, 
+    future=True,
+    poolclass=NullPool  # Disable pooling for asyncpg if needed, or adjust
+)
+
+# Async Engine for AsyncPG
+from sqlalchemy.ext.asyncio import create_async_engine
+async_engine = create_async_engine(DATABASE_URL, echo=True, future=True)
+
+async def get_session() -> AsyncSession:
+    async_session = sessionmaker(
+        async_engine, class_=AsyncSession, expire_on_commit=False
+    )
+    async with async_session() as session:
+        yield session
+
+async def init_db():
+    async with async_engine.begin() as conn:
+        # await conn.run_sync(SQLModel.metadata.drop_all)
+        await conn.run_sync(SQLModel.metadata.create_all)

backend/core/geo_engine.py

@@ -0,0 +1,244 @@
+import duckdb
+import json
+import logging
+import os
+from typing import Dict, Any, Optional, List
+from backend.core.data_catalog import get_data_catalog
+
+logger = logging.getLogger(__name__)
+
+class GeoEngine:
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(GeoEngine, cls).__new__(cls)
+            cls._instance.initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if self.initialized:
+            return
+        
+        logger.info("Initializing GeoEngine (DuckDB)...")
+        try:
+            self.con = duckdb.connect(database=':memory:')
+            self.con.install_extension('spatial')
+            self.con.load_extension('spatial')
+            logger.info("GeoEngine initialized with Spatial extension.")
+        except Exception as e:
+            logger.error(f"Failed to initialize GeoEngine: {e}")
+            raise e
+            
+        self.layers = {} # layer_id -> table_name
+        self.catalog = get_data_catalog()
+        self.base_tables_loaded = False
+        self.initialized = True
+        
+        # Automatically load base tables
+        self.initialize_base_tables()
+
+    def initialize_base_tables(self):
+        """
+        Load essential administrative boundary files into DuckDB tables.
+        """
+        if self.base_tables_loaded:
+            return
+            
+        logger.info("Loading base tables into DuckDB...")
+        
+        # Load core admin tables from catalog
+        # We look for tables starting with 'pan_admin' in the 'base' category
+        base_tables = [
+            name for name, meta in self.catalog.catalog.items() 
+            if meta.get('category') == 'base'
+        ]
+        
+        for table_name in base_tables:
+            self.ensure_table_loaded(table_name)
+            
+        self.base_tables_loaded = True
+        logger.info("Base tables loaded.")
+
+    def ensure_table_loaded(self, table_name: str) -> bool:
+        """
+        Ensure a table is loaded in DuckDB. If not, load it from the catalog.
+        Returns True if successful, False otherwise.
+        """
+        # Check if already loaded
+        try:
+            self.con.execute(f"DESCRIBE {table_name}")
+            return True
+        except:
+            pass # Not loaded
+            
+        # Look up in catalog
+        file_path = self.catalog.get_file_path(table_name)
+        if not file_path or not file_path.exists():
+            logger.warning(f"Table {table_name} not found in catalog or file missing.")
+            return False
+            
+        try:
+            logger.info(f"Lazy loading table: {table_name}")
+            self.con.execute(f"CREATE OR REPLACE TABLE {table_name} AS SELECT * FROM ST_Read('{file_path}')")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to load {table_name}: {e}")
+            return False
+
+    def get_table_schemas(self) -> str:
+        """
+        Get schema of currently loaded tables for LLM context.
+        """
+        result = "Currently Loaded Tables:\n\n"
+        
+        try:
+            # Get all tables
+            tables = self.con.execute("SHOW TABLES").fetchall()
+            for table in tables:
+                table_name = table[0]
+                try:
+                    columns = self.con.execute(f"DESCRIBE {table_name}").fetchall()
+                    row_count = self.con.execute(f"SELECT COUNT(*) FROM {table_name}").fetchone()[0]
+                    
+                    result += f"### {table_name} ({row_count} rows)\n"
+                    result += "Columns:\n"
+                    
+                    for col in columns:
+                        col_name, col_type = col[0], col[1]
+                        if col_name == 'geom':
+                            result += f"  - geom: GEOMETRY (spatial data)\n"
+                        else:
+                            result += f"  - {col_name}: {col_type}\n"
+                    result += "\n"
+                except:
+                    pass
+        except Exception as e:
+            logger.error(f"Error getting schemas: {e}")
+            
+        return result
+
+    def get_table_list(self) -> List[str]:
+        """Return list of all available table names."""
+        tables = list(self.BASE_TABLES.keys())
+        tables.extend(self.layers.values())
+        return tables
+
+    def register_layer(self, layer_id: str, geojson: Dict[str, Any]) -> str:
+        """
+        Registers a GeoJSON object as a table in DuckDB.
+        Returns the table name.
+        """
+        table_name = f"layer_{layer_id.replace('-', '_')}"
+        
+        # If table exists, drop it
+        self.con.execute(f"DROP TABLE IF EXISTS {table_name}")
+        
+        # DuckDB can read JSON objects directly via read_json_auto? 
+        # Easier to dump to string and read from memory or temporary file.
+        # For in-memory, we can use binding or just simple JSON text.
+        
+        # Strategy: Create a table with a JSON column, then unpack?
+        # Better: ST_Read can read from a file. 
+        # Using python objects directly with DuckDB replacement scan is possible but complex for nested GeoJSON.
+        
+        # Simplest: Write to temp file, load with ST_Read.
+        try:
+            import tempfile
+            import os
+            
+            def json_serial(obj):
+                """JSON serializer for objects not serializable by default json code"""
+                if hasattr(obj, 'isoformat'):
+                    return obj.isoformat()
+                raise TypeError (f"Type {type(obj)} not serializable")
+
+            with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as tmp:
+                json.dump(geojson, tmp, default=json_serial)
+                tmp_path = tmp.name
+                
+            self.con.execute(f"CREATE TABLE {table_name} AS SELECT * FROM ST_Read('{tmp_path}')")
+            os.unlink(tmp_path)
+            
+            self.layers[layer_id] = table_name
+            logger.info(f"Registered layer {layer_id} as table {table_name}")
+            return table_name
+            
+        except Exception as e:
+            logger.error(f"Error registering layer {layer_id}: {e}")
+            raise e
+
+    def execute_spatial_query(self, sql: str) -> Dict[str, Any]:
+        """
+        Executes a SQL query and returns the result as a GeoJSON FeatureCollection.
+        Expects the query to return a geometry column.
+        """
+        try:
+            logger.info(f"Executing Spatial SQL: {sql}")
+            
+            # Use ST_AsGeoJSON to format the geometry column
+            # We assume the user/LLM selects *
+            # We need to wrap the user query to convert to GeoJSON format
+            
+            # The query usually returns rows. We need to aggregate to FeatureCollection.
+            # DuckDB Spatial doesn't automagically output FeatureCollection structure.
+            # But the 'geojson' driver for ST_Read works. ST_AsGeoJSON works on geometries.
+            
+            # Approach: Create a temporary table from the result, then export?
+            # Or fetch as Python objects.
+            
+            self.con.execute(f"CREATE OR REPLACE TEMP TABLE query_result AS {sql}")
+            
+            # Check columns to find geometry
+            columns = self.con.execute("DESCRIBE query_result").fetchall()
+            geom_col = next((c[0] for c in columns if c[0] in ['geom', 'geometry']), None)
+            
+            if not geom_col and 'geometry' not in [c[0] for c in columns]:
+                # Maybe the user didn't select geometry?
+                pass
+
+            # Construct GeoJSON manually from rows
+            # Select ST_AsGeoJSON(geom), * EXCLUDE (geom)
+            
+            other_cols = [c[0] for c in columns if c[0] != geom_col]
+            other_cols_select = ", ".join(other_cols) if other_cols else ""
+            
+            select_clause = f"ST_AsGeoJSON({geom_col})"
+            if other_cols_select:
+                select_clause += f", {other_cols_select}"
+            
+            rows = self.con.execute(f"SELECT {select_clause} FROM query_result").fetchall()
+            
+            features = []
+            for row in rows:
+                geometry = json.loads(row[0])
+                properties = {}
+                for i, col_name in enumerate(other_cols):
+                    properties[col_name] = row[i+1]
+                
+                features.append({
+                    "type": "Feature",
+                    "geometry": geometry,
+                    "properties": properties
+                })
+                
+            return {
+                "type": "FeatureCollection",
+                "features": features,
+                "properties": {} 
+            }
+
+        except Exception as e:
+            logger.error(f"Spatial query failed: {e}")
+            raise e
+
+    def get_table_name(self, layer_id: str) -> Optional[str]:
+        return self.layers.get(layer_id)
+
+_geo_engine = None
+
+def get_geo_engine() -> GeoEngine:
+    global _geo_engine
+    if _geo_engine is None:
+        _geo_engine = GeoEngine()
+    return _geo_engine

backend/core/llm_gateway.py

@@ -0,0 +1,500 @@
+import os
+import asyncio
+import json
+from google import genai
+from google.genai import types
+from dotenv import load_dotenv
+
+from backend.core.prompts import (
+    SYSTEM_INSTRUCTION,
+    INTENT_DETECTION_PROMPT,
+    DATA_DISCOVERY_PROMPT,
+    SQL_GENERATION_PROMPT,
+    EXPLANATION_PROMPT,
+    SPATIAL_SQL_PROMPT,
+    SPATIAL_SQL_PROMPT,
+    SQL_CORRECTION_PROMPT,
+    LAYER_NAME_PROMPT
+)
+
+class LLMGateway:
+    def __init__(self, model_name: str = "gemini-3-flash-preview"):
+        # Load environment variables if not already loaded
+        load_dotenv()
+        
+        self.api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+        if not self.api_key:
+            print("WARNING: GEMINI_API_KEY/GOOGLE_API_KEY not found. LLM features will not work.")
+            self.client = None
+        else:
+            # Explicitly setting the environment variable for the SDK if it's not set
+            if "GEMINI_API_KEY" not in os.environ and self.api_key:
+                 os.environ["GEMINI_API_KEY"] = self.api_key
+            
+            # The SDK automatically picks up GEMINI_API_KEY
+            self.client = genai.Client()
+        
+        self.model = model_name 
+
+    def _build_contents_from_history(self, history: list[dict], current_message: str) -> list:
+        """
+        Converts conversation history to the format expected by the Gemini API.
+        History format: [{"role": "user"|"assistant", "content": "..."}]
+        """
+        contents = []
+        for msg in history:
+            # Map 'assistant' to 'model' for Gemini API
+            role = "model" if msg["role"] == "assistant" else "user"
+            contents.append(
+                types.Content(
+                    role=role,
+                    parts=[types.Part.from_text(text=msg["content"])]
+                )
+            )
+        
+        # Add the current message
+        contents.append(
+            types.Content(
+                role="user",
+                parts=[types.Part.from_text(text=current_message)]
+            )
+        )
+        return contents
+
+    async def generate_response_stream(self, user_query: str, history: list[dict] = None):
+        """
+        Generates a streaming response using conversation history for context.
+        Yields chunks of text and thought summaries.
+        """
+        if not self.client:
+            yield "I couldn't generate a response because the API key is missing."
+            return
+        
+        if history is None:
+            history = []
+        
+        try:
+            contents = self._build_contents_from_history(history, user_query)
+            
+            # Enable thinking mode for general chat as well
+            config = types.GenerateContentConfig(
+                system_instruction=SYSTEM_INSTRUCTION,
+                thinking_config=types.ThinkingConfig(
+                    include_thoughts=True  # Enable thought summaries
+                )
+            )
+            
+            stream = await asyncio.to_thread(
+                self.client.models.generate_content_stream,
+                model=self.model,
+                contents=contents,
+                config=config,
+            )
+
+            for chunk in stream:
+                 for part in chunk.candidates[0].content.parts:
+                    if part.thought:
+                         yield {"type": "thought", "content": part.text}
+                    elif part.text:
+                         yield {"type": "content", "text": part.text}
+
+        except Exception as e:
+            print(f"Error calling Gemini stream: {e}")
+            yield f"Error: {str(e)}"
+
+    async def generate_response(self, user_query: str, history: list[dict] = None) -> str:
+        """
+        Generates a response using conversation history for context.
+        """
+        if not self.client:
+            return "I couldn't generate a response because the API key is missing."
+        
+        if history is None:
+            history = []
+        
+        try:
+            contents = self._build_contents_from_history(history, user_query)
+            
+            config = types.GenerateContentConfig(
+                system_instruction=SYSTEM_INSTRUCTION,
+            )
+            
+            response = await asyncio.to_thread(
+                self.client.models.generate_content,
+                model=self.model,
+                contents=contents,
+                config=config,
+            )
+            return response.text
+        except Exception as e:
+            print(f"Error calling Gemini: {e}")
+            return f"I encountered an error: {e}" 
+
+    async def detect_intent(self, user_query: str, history: list[dict] = None) -> str:
+        """
+        Detects the intent of the user's query using Gemini thinking mode.
+        Returns: GENERAL_CHAT, DATA_QUERY, MAP_REQUEST, SPATIAL_OP, or STAT_QUERY
+        """
+        if not self.client:
+            return "GENERAL_CHAT"
+        
+        intent_prompt = INTENT_DETECTION_PROMPT.format(user_query=user_query)
+
+        try:
+            # Use thinking mode for better intent classification
+            config = types.GenerateContentConfig(
+                thinking_config=types.ThinkingConfig(
+                    thinking_level="medium"  # Balanced thinking for intent detection
+                )
+            )
+            
+            response = await asyncio.to_thread(
+                self.client.models.generate_content,
+                model=self.model,
+                contents=intent_prompt,
+                config=config,
+            )
+            intent = response.text.strip().upper()
+            
+            # Validate the intent
+            if intent in ["GENERAL_CHAT", "DATA_QUERY", "MAP_REQUEST", "SPATIAL_OP", "STAT_QUERY"]:
+                return intent
+            
+            # Default fallback
+            return "GENERAL_CHAT"
+        except Exception as e:
+            print(f"Error detecting intent: {e}")
+            return "GENERAL_CHAT"
+
+    async def stream_intent(self, user_query: str, history: list[dict] = None):
+        """
+        Streams intent detection, yielding thoughts.
+        """
+        if not self.client:
+            yield {"type": "error", "text": "API Key missing"}
+            return
+        
+        intent_prompt = INTENT_DETECTION_PROMPT.format(user_query=user_query)
+
+        try:
+            config = types.GenerateContentConfig(
+                thinking_config=types.ThinkingConfig(
+                    thinking_level="medium",
+                    include_thoughts=True
+                )
+            )
+            
+            stream = await asyncio.to_thread(
+                self.client.models.generate_content_stream,
+                model=self.model,
+                contents=intent_prompt,
+                config=config,
+            )
+            
+            for chunk in stream:
+                 for part in chunk.candidates[0].content.parts:
+                    if part.thought:
+                         yield {"type": "thought", "text": part.text}
+                    elif part.text:
+                         yield {"type": "content", "text": part.text}
+
+        except Exception as e:
+            print(f"Error detecting intent: {e}")
+            yield {"type": "error", "text": str(e)}
+
+    # Legacy generate_sql removed.
+
+    async def identify_relevant_tables(self, user_query: str, table_summaries: str) -> list[str]:
+        """
+        Identifies which tables are relevant for the user's query from the catalog summary.
+        Returns a JSON list of table names.
+        """
+        if not self.client:
+            return []
+            
+        prompt = DATA_DISCOVERY_PROMPT.format(user_query=user_query, table_summaries=table_summaries)
+        
+        try:
+            config = types.GenerateContentConfig(
+                response_mime_type="application/json"
+            )
+            
+            response = await asyncio.to_thread(
+                self.client.models.generate_content,
+                model=self.model,
+                contents=prompt,
+                config=config,
+            )
+            
+            text = response.text.replace("```json", "").replace("```", "").strip()
+            tables = json.loads(text)
+            return tables if isinstance(tables, list) else []
+            
+        except Exception as e:
+            print(f"Error identifying tables: {e}")
+            return []
+
+    async def generate_analytical_sql(self, user_query: str, table_schema: str, history: list[dict] = None) -> str:
+        """
+        Generates a DuckDB SQL query for analytical/statistical questions about geographic data.
+        This is the core of the text-to-SQL system.
+        """
+        if not self.client:
+            return "-- Error: API Key missing"
+
+        prompt = SQL_GENERATION_PROMPT.format(table_schema=table_schema, user_query=user_query)
+
+        try:
+            # Use thinking mode for complex SQL generation
+            config = types.GenerateContentConfig(
+                temperature=1,
+                thinking_config=types.ThinkingConfig(
+                    thinking_level="high"  # Maximum reasoning for SQL generation
+                )
+            )
+
+            response = await asyncio.wait_for(
+                asyncio.to_thread(
+                    self.client.models.generate_content,
+                    model=self.model,
+                    contents=prompt,
+                    config=config,
+                ),
+                timeout=120.0
+            )
+            
+            sql = response.text.replace("```sql", "").replace("```", "").strip()
+            
+            # Basic validation: must start with SELECT
+            if not sql.upper().strip().startswith("SELECT") and "-- ERROR" not in sql:
+                print(f"Warning: Generated SQL doesn't start with SELECT: {sql[:100]}")
+                if "SELECT" in sql.upper():
+                    start_idx = sql.upper().find("SELECT")
+                    sql = sql[start_idx:]
+            
+            return sql
+
+        except asyncio.TimeoutError:
+            print("Gemini API call timed out after 30 seconds")
+            return "-- Error: API call timed out. Please try again."
+        except Exception as e:
+            print(f"Error calling Gemini for analytical SQL: {e}")
+            return f"-- Error generating SQL: {str(e)}"
+
+    async def stream_analytical_sql(self, user_query: str, table_schema: str, history: list[dict] = None):
+        """
+        Streams the generation of DuckDB SQL, yielding thoughts and chunks.
+        """
+        if not self.client:
+            yield {"type": "error", "text": "API Key missing"}
+            return
+
+        prompt = SQL_GENERATION_PROMPT.format(table_schema=table_schema, user_query=user_query)
+
+        try:
+            config = types.GenerateContentConfig(
+                temperature=1,
+                thinking_config=types.ThinkingConfig(
+                    thinking_level="high",
+                    include_thoughts=True
+                )
+            )
+
+            stream = await asyncio.to_thread(
+                self.client.models.generate_content_stream,
+                model=self.model,
+                contents=prompt,
+                config=config,
+            )
+
+            for chunk in stream:
+                for part in chunk.candidates[0].content.parts:
+                    if part.thought:
+                        yield {"type": "thought", "text": part.text}
+                    elif part.text:
+                        yield {"type": "content", "text": part.text}
+
+        except Exception as e:
+            print(f"Error streaming SQL: {e}")
+            yield {"type": "error", "text": str(e)}
+
+    async def stream_explanation(self, user_query: str, sql_query: str, data_summary: str, history: list[dict] = None):
+        """
+        Streams the explanation.
+        """
+        if not self.client:
+            yield {"type": "error", "text": "API Key missing"}
+            return
+
+        # Build context from history if available
+        context_str = ""
+        if history:
+            context_str = "Previous conversation context:\n"
+            for msg in history[-4:]:  # Last 4 messages for context
+                context_str += f"- {msg['role']}: {msg['content'][:100]}...\n"
+
+        prompt = EXPLANATION_PROMPT.format(context_str=context_str, user_query=user_query, sql_query=sql_query, data_summary=data_summary)
+        
+        try:
+            config = types.GenerateContentConfig(
+                system_instruction=SYSTEM_INSTRUCTION,
+                thinking_config=types.ThinkingConfig(
+                    thinking_level="low",
+                    include_thoughts=True
+                )
+            )
+            
+            stream = await asyncio.to_thread(
+                self.client.models.generate_content_stream,
+                model=self.model,
+                contents=prompt,
+                config=config,
+            )
+
+            for chunk in stream:
+                for part in chunk.candidates[0].content.parts:
+                    if part.thought:
+                        yield {"type": "thought", "text": part.text}
+                    elif part.text:
+                        yield {"type": "content", "text": part.text}
+
+        except Exception as e:
+            print(f"Error generating explanation: {e}")
+            yield {"type": "error", "text": str(e)}
+
+    async def generate_explanation(self, user_query: str, sql_query: str, data_summary: str, history: list[dict] = None) -> str:
+        """
+        Explains the results of the query to the user, maintaining conversation context.
+        """
+        if not self.client:
+            return "I couldn't generate an explanation because the API key is missing."
+
+        # Build context from history if available
+        context_str = ""
+        if history:
+            context_str = "Previous conversation context:\n"
+            for msg in history[-4:]:  # Last 4 messages for context
+                context_str += f"- {msg['role']}: {msg['content'][:100]}...\n"
+
+        prompt = EXPLANATION_PROMPT.format(context_str=context_str, user_query=user_query, sql_query=sql_query, data_summary=data_summary)
+        
+        try:
+            config = types.GenerateContentConfig(
+                system_instruction=SYSTEM_INSTRUCTION,
+                thinking_config=types.ThinkingConfig(
+                    thinking_level="low"  # Fast response for explanations
+                )
+            )
+            
+            response = await asyncio.to_thread(
+                self.client.models.generate_content,
+                model=self.model,
+                contents=prompt,
+                config=config,
+            )
+            return response.text
+        except Exception as e:
+            print(f"Error generating explanation: {e}")
+            return "Here are the results from the query."
+
+    async def generate_spatial_sql(self, user_query: str, layer_context: str, history: list[dict] = None) -> str:
+        """
+        Generates a DuckDB Spatial SQL query for geometric operations on layers.
+        """
+        if not self.client:
+            return "-- Error: API Key missing"
+
+        prompt = SPATIAL_SQL_PROMPT.format(layer_context=layer_context, user_query=user_query)
+        
+        try:
+            config = types.GenerateContentConfig(
+                temperature=1, 
+            )
+
+            # Add timeout to prevent indefinite hangs
+            response = await asyncio.wait_for(
+                asyncio.to_thread(
+                    self.client.models.generate_content,
+                    model=self.model,
+                    contents=prompt,
+                    config=config,
+                ),
+                timeout=120.0
+            )
+            
+            sql = response.text.replace("```sql", "").replace("```", "").strip()
+            return sql
+
+        except asyncio.TimeoutError:
+            print("Gemini API call timed out after 30 seconds")
+            return "-- Error: API call timed out. Please try again."
+        except Exception as e:
+            print(f"Error calling Gemini: {e}")
+            return f"-- Error generating SQL: {str(e)}"
+            
+    async def correct_sql(self, user_query: str, incorrect_sql: str, error_message: str, schema_context: str) -> str:
+        """
+        Corrects a failed SQL query based on the error message.
+        """
+        if not self.client:
+            return "-- Error: API Key missing"
+
+        prompt = SQL_CORRECTION_PROMPT.format(
+            error_message=error_message, 
+            incorrect_sql=incorrect_sql, 
+            user_query=user_query, 
+            schema_context=schema_context
+        )
+
+        try:
+            config = types.GenerateContentConfig(
+                temperature=1,
+            )
+
+            response = await asyncio.to_thread(
+                self.client.models.generate_content,
+                model=self.model,
+                contents=prompt,
+                config=config,
+            )
+            
+            sql = response.text.replace("```sql", "").replace("```", "").strip()
+            return sql
+
+        except Exception as e:
+            print(f"Error correcting SQL: {e}")
+            return incorrect_sql
+    
+    async def generate_layer_name(self, user_query: str, sql_query: str) -> dict:
+        """
+        Generates a short, descriptive name, emoji, and point style for a map layer.
+        Returns: {"name": str, "emoji": str, "pointStyle": str | None}
+        """
+        if not self.client:
+            return {"name": "New Layer", "emoji": "📍", "pointStyle": None}
+
+        prompt = LAYER_NAME_PROMPT.format(user_query=user_query, sql_query=sql_query)
+
+        try:
+            config = types.GenerateContentConfig(
+                temperature=1,
+                response_mime_type="application/json"
+            )
+
+            # Use simple generate content (not streaming)
+            response = await asyncio.to_thread(
+                self.client.models.generate_content,
+                model=self.model,
+                contents=prompt,
+                config=config,
+            )
+            
+            result = json.loads(response.text)
+            return {
+                "name": result.get("name", "Map Layer"),
+                "emoji": result.get("emoji", "📍"),
+                "pointStyle": result.get("pointStyle", None)
+            }
+        except Exception as e:
+            print(f"Error generating layer name: {e}")
+            return {"name": "Map Layer", "emoji": "📍", "pointStyle": None}

backend/core/prompts.py

@@ -0,0 +1,279 @@
+"""
+Centralized storage for all LLM system instructions and prompt templates.
+"""
+
+SYSTEM_INSTRUCTION = """You are GeoQuery, an advanced Territorial Intelligence Agent capable of analyzing diverse geographic datasets.
+
+## Your Capabilities
+You are not limited to a fixed schema. You have a **Dynamic Metadata Catalog** that allows you to discover and query any dataset ingested into the system.
+- **Administrative Data**: Provinces, districts, corregimientos (always available).
+- **Dynamic Data**: You can query *any* table present in the database (e.g., population, health, infrastructure, biodiversity).
+- **Spatial Analysis**: You can perform complex spatial joins, intersections, and aggregations using PostGIS/DuckDB Spatial functions.
+
+## Output Guidelines
+1. **Be Data-Driven**: Base your answers strictly on the results of the SQL queries.
+2. **Be Visual**:
+   - Use **Choropleth Maps** (color gradients) for comparisons/densities.
+   - Use **Point Maps** for locating specific facilities or events.
+   - Use **Charts** (Bar, Pie, Line) for statistical summaries.
+3. **Be Transparent**:
+   - Always **Explain** your reasoning.
+   - **Cite** the specific table names used (e.g., "Source: `osm/universities.geojson`").
+   - If data is missing *after* checking the catalog, explain clearly what is available vs. what is missing.
+
+## Interaction Style
+- Professional, concise, and helpful.
+- "Thinking" is enabled: Use your internal thought process to plan complex queries before generating SQL.
+- If a query fails, self-correct by analyzing the error message.
+"""
+
+INTENT_DETECTION_PROMPT = """Analyze this user query and determine the best output type.
+
+User Query: "{user_query}"
+
+THINK STEP BY STEP:
+1. What is the user asking for?
+2. Does this require geographic visualization (map)?
+3. Does this require a chart/graph?
+4. Is this a general question or conversation?
+
+Then respond with ONLY ONE of these exact words:
+- GENERAL_CHAT: General question, greeting, or conversational message
+- DATA_QUERY: Wants textual information or data that should be shown on a map
+- MAP_REQUEST: Wants to SEE or VISUALIZE geographic data on a map (show, display, plot, color, compare regions)
+- SPATIAL_OP: Geometric operation between layers (Intersection, Buffer, Union, Difference)
+- STAT_QUERY: EXPLICITLY asks for a CHART or GRAPH (bar chart, pie chart, line graph)
+
+Key rules:
+- "color by", "compare regions", "show largest/smallest" → MAP_REQUEST (for choropleth)
+- "show me provinces", "display districts" → MAP_REQUEST
+- "create a chart", "bar graph" → STAT_QUERY
+- Questions about data availability → GENERAL_CHAT
+
+Respond with only the intent category, nothing else."""
+
+DATA_DISCOVERY_PROMPT = """You are a Data Discovery Agent. Convert the user's request into a list of relevant table names from the available data.
+        
+User Request: "{user_query}"
+
+Available Data Tables:
+{table_summaries}
+
+Rules:
+1. Return ONLY a valid JSON list of strings, e.g. ["table1", "table2"].
+2. Select tables that might contain the answer. 
+3. If asking for "colleges" or "education", include 'universities', 'schools', etc.
+4. If asking for "health", include 'hospitals'.
+5. Always include 'admin1', 'admin2', 'admin3' if the query involves regions.
+6. If no specific table matches, return empty list [].
+"""
+
+SQL_GENERATION_PROMPT = """You are a DuckDB SQL expert for geographic data analysis. Generate a valid DuckDB SQL query for the following request.
+
+{table_schema}
+
+### CRITICAL - Data Availability:
+✅ You may ONLY query the tables listed above.
+❌ Do NOT invent table names or column names.
+
+**If the requested data is NOT in the schema above, IMMEDIATELY return this exact response and STOP:**
+-- ERROR: DATA_UNAVAILABLE
+-- Requested: [what the user asked for]
+-- Available: [list the tables you DO have]
+
+**Do NOT keep thinking or try alternative approaches. Just return the error and stop.**
+
+### User Request: "{user_query}"
+
+### Rules:
+1. Return ONLY the SQL query. No explanation, no markdown formatting.
+2. Use DuckDB syntax (ILIKE for case-insensitive matching).
+3. ALWAYS include 'geom' in SELECT for map visualization.
+4. For "top N" or "largest" queries, use ORDER BY ... DESC LIMIT N.
+5. For "per group" queries, use window functions.
+6. Do NOT add LIMIT unless the user explicitly asks for a specific count (e.g., "top 10", "first 5"). Return all matching rows by default.
+7. NEVER invent columns that don't exist.
+
+### Special Datasets:
+- **Population/Demographics**: Use `kontur_population` (H3 hexagons). 
+  - Columns: `population`, `geom`.
+  - Query: `SELECT population, geom FROM kontur_population ...`
+  - Visualization: The system detects the `population` column and automatically renders a heatmap (choropleth).
+  - Note: This dataset is large (33k hexagons). If querying the entire country, use `LIMIT 40000` to ensure full coverage, or filter by specific province/district.
+
+### Example Queries:
+
+-- Largest provinces by area
+SELECT adm1_name, area_sqkm, geom FROM admin1 ORDER BY area_sqkm DESC LIMIT 10
+
+-- Population Density Heatmap for a Region (e.g., Veraguas)
+SELECT population, geom FROM kontur_population 
+WHERE ST_Intersects(geom, (SELECT geom FROM pan_admin1 WHERE adm1_name = 'Veraguas'))
+LIMIT 5000
+
+-- Largest district in each province
+SELECT adm1_name, adm2_name, area_sqkm, geom FROM (
+    SELECT *, ROW_NUMBER() OVER (PARTITION BY adm1_name ORDER BY area_sqkm DESC) as rn
+    FROM admin2
+) WHERE rn = 1
+
+Now generate the SQL for the user's request:"""
+
+EXPLANATION_PROMPT = """Explain the results of this data query to the user.
+
+{context_str}
+
+User Question: "{user_query}"
+SQL Query Used: {sql_query}
+Data Result Summary: {data_summary}
+
+Instructions:
+1. Keep your response concise and helpful
+2. Only describe data that was ACTUALLY returned in the query results
+3. The available metrics include: area (area_sqkm), population (kontur_population), names, and geographic codes
+4. If the user asked for data that doesn't exist, explain that clearly
+5. Cite: "Administrative boundary data from HDX/INEC, 2021" or "Population data from Kontur, 2022"
+6. Speak as GeoQuery, the platform itself
+"""
+
+SPATIAL_SQL_PROMPT = """You are a GIS expert using DuckDB Spatial. Generate a valid SQL query for the following request.
+
+Available Data:
+{layer_context}
+
+User Request: "{user_query}"
+
+Rules:
+1. Return ONLY the SQL query. No markdown formatting, no explanation.
+2. Use DuckDB Spatial functions (ST_Difference, ST_Intersection, ST_Union, ST_Buffer, ST_Within, ST_Contains).
+3. The geometry column is named 'geom'. Use 'geom' for all spatial functions.
+4. CRITICAL: Use ONLY the EXACT table names shown above in your FROM clause.
+   - Base tables are shown with their schema (e.g., panama_healthsites_geojson)
+   - User-created layers are shown as "Layer N: Name (Table: layer_xxxxx)"
+5. IMPORTANT: For operations that aggregate geometries (ST_Union), use CTE pattern, NOT scalar subqueries:
+   CORRECT (CTE pattern):
+   ```sql
+   WITH layer_b_union AS (SELECT ST_Union(geom) as geom FROM layer_b)
+   SELECT a.*, ST_Difference(a.geom, b.geom) as geom FROM layer_a a, layer_b_union b
+   ```
+   WRONG (scalar subquery - causes syntax errors):
+   ```sql
+   SELECT ST_Difference(geom, (SELECT ST_Union(geom) FROM layer_b)) FROM layer_a
+   ```
+6. For containment queries (points within polygons), use ST_Within(points.geom, polygons.geom).
+7. Handle joins properly (e.g., CROSS JOIN or comma-join for combining with CTEs).
+8. IMPORTANT: Preserve 'name' properties if possible.
+9. OUTPUT: SELECT with geom column included.
+"""
+
+SQL_CORRECTION_PROMPT = """You are a DuckDB SQL expert. Your previous query failed to execute. Fix it.
+
+### Error Message:
+{error_message}
+
+### Failed SQL:
+{incorrect_sql}
+
+### User Request:
+"{user_query}"
+
+### Database Schema:
+{schema_context}
+
+### Rules:
+1. Fix the error described in the message (e.g., column ambiguity, missing column, syntax error).
+2. Return ONLY the valid SQL query. No explanation.
+3. Keep the query logic consistent with the User Request.
+4. Ensure 'geom' is selected for map visualization if needed.
+"""
+
+LAYER_NAME_PROMPT = """You are a helpful assistant generating a short, descriptive name for a map layer.
+
+User Request: "{user_query}"
+SQL Query: "{sql_query}"
+
+Rules:
+1. Return a VALID JSON object with three keys: "name", "emoji", and "pointStyle".
+2. "name": A short descriptive name (1-4 words).
+3. "emoji": A single emoji representing the data content (e.g., "🏥" for hospitals, "🎓" for schools, "👥" for population).
+4. "pointStyle": Determines how POINT geometries should be rendered on the map (ONLY applies to Point geometry types):
+   - "icon": Use for specific, categorical points of interest (hospitals, schools, parks, landmarks)
+     * Best for: Small to medium point datasets (<500 points)
+     * Best for: When each point represents a distinct, identifiable feature
+     * The emoji will be displayed on the map as the marker icon
+   - "circle": Use for large point datasets
+     * Best for: Large point datasets (>500 points) like street intersections, sensor locations
+     * Renders as simple colored circles for better performance
+   - NOTE: For polygon data (H3 hexagons, administrative boundaries), the system automatically uses choropleth rendering (colored polygons). Do NOT set pointStyle for polygon data.
+5. Examples:
+   {{"name": "Schools in Panama", "emoji": "🏫", "pointStyle": "icon"}}
+   {{"name": "Population Density", "emoji": "👥", "pointStyle": null}}  # H3 hexagons are POLYGONS, not points
+   {{"name": "National Parks", "emoji": "🌲", "pointStyle": "icon"}}
+   {{"name": "Street Intersections", "emoji": "🚦", "pointStyle": "circle"}}
+6. Do NOT return markdown formatting (no ```json). Just the raw JSON string.
+
+"""
+
+QUERY_PLANNING_PROMPT = """You are a Query Planning Agent. Decompose this complex query into atomic execution steps.
+
+User Query: "{user_query}"
+
+Available Tables:
+{available_tables}
+
+TASK: Break down this query into sequential steps that can be executed independently.
+
+RULES:
+1. Each step should query a SINGLE dataset or combine results from previous steps.
+2. Steps that don't depend on each other can run in parallel.
+3. The final step should combine/compare results if needed.
+4. Use ONLY the table names listed above.
+
+Return a JSON object with this structure:
+{{
+  "steps": [
+    {{
+      "type": "data_query" | "aggregation" | "comparison" | "spatial_join" | "combine",
+      "description": "Human-readable description of this step",
+      "tables": ["table_name"],
+      "sql_hint": "Optional SQL pattern or hint",
+      "depends_on": [],
+      "result_name": "descriptive_name_for_result"
+    }}
+  ],
+  "combination_logic": "How to combine the step results for the final answer"
+}}
+
+EXAMPLE for "Compare hospital count vs school count by province":
+{{
+  "steps": [
+    {{
+      "type": "aggregation",
+      "description": "Count hospitals per province",
+      "tables": ["panama_healthsites_geojson", "pan_admin1"],
+      "sql_hint": "SELECT province, COUNT(*) as hospital_count FROM ... GROUP BY province",
+      "depends_on": [],
+      "result_name": "hospitals_by_province"
+    }},
+    {{
+      "type": "aggregation", 
+      "description": "Count schools per province",
+      "tables": ["schools", "pan_admin1"],
+      "sql_hint": "SELECT province, COUNT(*) as school_count FROM ... GROUP BY province",
+      "depends_on": [],
+      "result_name": "schools_by_province"
+    }},
+    {{
+      "type": "combine",
+      "description": "Join hospital and school counts by province for comparison",
+      "tables": [],
+      "sql_hint": "JOIN hospitals_by_province h ON schools_by_province s ON h.province = s.province",
+      "depends_on": ["hospitals_by_province", "schools_by_province"],
+      "result_name": "comparison_result"
+    }}
+  ],
+  "combination_logic": "Display side-by-side comparison with bar chart showing both counts per province"
+}}
+
+Now decompose the user's query. Return ONLY the JSON, no markdown formatting.
+"""

backend/core/query_planner.py

@@ -0,0 +1,291 @@
+"""
+Multi-Step Query Planner
+
+Detects complex queries that require multiple datasets or operations,
+decomposes them into atomic steps, and orchestrates execution.
+"""
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class StepType(Enum):
+    """Types of query steps."""
+    DATA_QUERY = "data_query"      # Simple data retrieval
+    AGGREGATION = "aggregation"    # COUNT, SUM, GROUP BY
+    COMPARISON = "comparison"      # Comparing results from previous steps
+    SPATIAL_JOIN = "spatial_join"  # Joining datasets spatially
+    COMBINE = "combine"            # Merge/combine step results
+
+
+@dataclass
+class QueryStep:
+    """A single atomic step in a query plan."""
+    step_id: str
+    step_type: StepType
+    description: str
+    tables_needed: List[str]
+    sql_template: Optional[str] = None
+    depends_on: List[str] = field(default_factory=list)
+    result_name: str = ""  # Name for intermediate result
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "step_id": self.step_id,
+            "step_type": self.step_type.value,
+            "description": self.description,
+            "tables_needed": self.tables_needed,
+            "sql_template": self.sql_template,
+            "depends_on": self.depends_on,
+            "result_name": self.result_name
+        }
+
+
+@dataclass 
+class QueryPlan:
+    """Complete execution plan for a complex query."""
+    original_query: str
+    is_complex: bool
+    steps: List[QueryStep] = field(default_factory=list)
+    parallel_groups: List[List[str]] = field(default_factory=list)  # Steps that can run in parallel
+    final_combination_logic: str = ""
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "original_query": self.original_query,
+            "is_complex": self.is_complex,
+            "steps": [s.to_dict() for s in self.steps],
+            "parallel_groups": self.parallel_groups,
+            "final_combination_logic": self.final_combination_logic
+        }
+
+
+class QueryPlanner:
+    """
+    Multi-step query planning service.
+    
+    Analyzes queries to determine complexity and decomposes
+    complex queries into executable atomic steps.
+    """
+    
+    _instance = None
+    
+    # Keywords that often indicate multi-step queries
+    COMPLEXITY_INDICATORS = [
+        "compare", "comparison", "versus", "vs",
+        "more than", "less than", "higher than", "lower than",
+        "both", "and also", "as well as",
+        "ratio", "percentage", "proportion",
+        "correlation", "relationship between",
+        "combine", "merge", "together with",
+        "relative to", "compared to",
+        "difference between", "gap between"
+    ]
+    
+    # Keywords indicating multiple distinct data types
+    MULTI_DOMAIN_KEYWORDS = {
+        "health": ["hospital", "clinic", "healthcare", "health", "medical"],
+        "education": ["school", "university", "education", "college", "student"],
+        "infrastructure": ["road", "bridge", "infrastructure", "building"],
+        "environment": ["forest", "water", "environment", "park", "protected"],
+        "population": ["population", "demographic", "census", "people", "resident"]
+    }
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(QueryPlanner, cls).__new__(cls)
+            cls._instance.initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        if self.initialized:
+            return
+        self.initialized = True
+    
+    def detect_complexity(self, query: str) -> Dict[str, Any]:
+        """
+        Analyze a query to determine if it requires multi-step planning.
+        
+        Returns:
+            {
+                "is_complex": bool,
+                "reason": str,
+                "detected_domains": List[str],
+                "complexity_indicators": List[str]
+            }
+        """
+        query_lower = query.lower()
+        
+        # Check for complexity indicators
+        found_indicators = [
+            ind for ind in self.COMPLEXITY_INDICATORS 
+            if ind in query_lower
+        ]
+        
+        # Check for multiple data domains
+        found_domains = []
+        for domain, keywords in self.MULTI_DOMAIN_KEYWORDS.items():
+            if any(kw in query_lower for kw in keywords):
+                found_domains.append(domain)
+        
+        # Determine complexity
+        is_complex = (
+            len(found_indicators) > 0 and len(found_domains) >= 2
+        ) or (
+            len(found_domains) >= 3
+        ) or (
+            any(x in query_lower for x in ["compare", "ratio", "correlation", "versus", " vs "])
+            and len(found_domains) >= 2
+        )
+        
+        reason = ""
+        if is_complex:
+            if len(found_domains) >= 2:
+                reason = f"Query involves multiple data domains: {', '.join(found_domains)}"
+            if found_indicators:
+                reason += f". Contains comparison/aggregation keywords: {', '.join(found_indicators[:3])}"
+        
+        return {
+            "is_complex": is_complex,
+            "reason": reason,
+            "detected_domains": found_domains,
+            "complexity_indicators": found_indicators
+        }
+    
+    async def plan_query(
+        self, 
+        query: str, 
+        available_tables: List[str],
+        llm_gateway
+    ) -> QueryPlan:
+        """
+        Create an execution plan for a complex query.
+        
+        Uses LLM to decompose the query into atomic steps.
+        """
+        from backend.core.prompts import QUERY_PLANNING_PROMPT
+        
+        # Build table context
+        table_list = "\n".join(f"- {t}" for t in available_tables)
+        
+        prompt = QUERY_PLANNING_PROMPT.format(
+            user_query=query,
+            available_tables=table_list
+        )
+        
+        try:
+            response = await llm_gateway.generate_response(prompt, [])
+            
+            # Parse JSON response
+            response_clean = response.strip()
+            if response_clean.startswith("```json"):
+                response_clean = response_clean[7:]
+            if response_clean.startswith("```"):
+                response_clean = response_clean[3:]
+            if response_clean.endswith("```"):
+                response_clean = response_clean[:-3]
+            
+            plan_data = json.loads(response_clean.strip())
+            
+            # Convert to QueryPlan
+            steps = []
+            for i, step_data in enumerate(plan_data.get("steps", [])):
+                step = QueryStep(
+                    step_id=f"step_{i+1}",
+                    step_type=StepType(step_data.get("type", "data_query")),
+                    description=step_data.get("description", ""),
+                    tables_needed=step_data.get("tables", []),
+                    sql_template=step_data.get("sql_hint", None),
+                    depends_on=step_data.get("depends_on", []),
+                    result_name=step_data.get("result_name", f"result_{i+1}")
+                )
+                steps.append(step)
+            
+            # Determine parallel groups (steps with no dependencies can run together)
+            parallel_groups = self._compute_parallel_groups(steps)
+            
+            return QueryPlan(
+                original_query=query,
+                is_complex=True,
+                steps=steps,
+                parallel_groups=parallel_groups,
+                final_combination_logic=plan_data.get("combination_logic", "")
+            )
+            
+        except Exception as e:
+            logger.error(f"Query planning failed: {e}")
+            # Return single-step fallback
+            return QueryPlan(
+                original_query=query,
+                is_complex=False,
+                steps=[],
+                parallel_groups=[],
+                final_combination_logic=""
+            )
+    
+    def _compute_parallel_groups(self, steps: List[QueryStep]) -> List[List[str]]:
+        """
+        Compute which steps can be executed in parallel.
+        
+        Steps with no dependencies (or only completed dependencies) 
+        can run together.
+        """
+        if not steps:
+            return []
+        
+        groups = []
+        executed = set()
+        remaining = {s.step_id: s for s in steps}
+        
+        while remaining:
+            # Find steps whose dependencies are all satisfied
+            ready = [
+                step_id for step_id, step in remaining.items()
+                if all(dep in executed for dep in step.depends_on)
+            ]
+            
+            if not ready:
+                # Avoid infinite loop - add remaining as sequential
+                ready = list(remaining.keys())[:1]
+            
+            groups.append(ready)
+            
+            for step_id in ready:
+                executed.add(step_id)
+                del remaining[step_id]
+        
+        return groups
+    
+    def create_simple_plan(self, query: str) -> QueryPlan:
+        """Create a simple single-step plan for non-complex queries."""
+        return QueryPlan(
+            original_query=query,
+            is_complex=False,
+            steps=[
+                QueryStep(
+                    step_id="step_1",
+                    step_type=StepType.DATA_QUERY,
+                    description="Execute query directly",
+                    tables_needed=[],
+                    depends_on=[]
+                )
+            ],
+            parallel_groups=[["step_1"]]
+        )
+
+
+# Singleton accessor
+_query_planner: Optional[QueryPlanner] = None
+
+
+def get_query_planner() -> QueryPlanner:
+    """Get the singleton query planner instance."""
+    global _query_planner
+    if _query_planner is None:
+        _query_planner = QueryPlanner()
+    return _query_planner

backend/core/semantic_search.py

@@ -0,0 +1,259 @@
+"""
+Semantic Search Service for Dataset Discovery
+
+Uses Gemini embeddings to find relevant datasets from a query,
+enabling scalable discovery across 250+ datasets without context overflow.
+"""
+
+import json
+import logging
+import numpy as np
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+from google import genai
+from google.genai import types
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticSearch:
+    """
+    Embedding-based semantic search for dataset discovery.
+    
+    Embeds dataset metadata (name, description, tags, columns) and
+    finds the most relevant datasets for a user query using cosine similarity.
+    """
+    
+    _instance = None
+    EMBEDDINGS_FILE = Path(__file__).parent.parent / "data" / "embeddings.json"
+    EMBEDDING_MODEL = "models/text-embedding-004"
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(SemanticSearch, cls).__new__(cls)
+            cls._instance.initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        if self.initialized:
+            return
+        
+        self.embeddings: Dict[str, List[float]] = {}
+        self.metadata_cache: Dict[str, str] = {}  # table_name -> embedded text
+        
+        # Initialize Gemini client
+        api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+        if api_key:
+            self.client = genai.Client()
+        else:
+            self.client = None
+            logger.warning("No API key found. Semantic search will use fallback keyword matching.")
+        
+        self._load_embeddings()
+        self.initialized = True
+    
+    def _load_embeddings(self) -> None:
+        """Load cached embeddings from disk."""
+        if self.EMBEDDINGS_FILE.exists():
+            try:
+                with open(self.EMBEDDINGS_FILE, 'r') as f:
+                    data = json.load(f)
+                    self.embeddings = data.get("embeddings", {})
+                    self.metadata_cache = data.get("metadata", {})
+                logger.info(f"Loaded {len(self.embeddings)} cached embeddings.")
+            except Exception as e:
+                logger.error(f"Failed to load embeddings: {e}")
+                self.embeddings = {}
+                self.metadata_cache = {}
+    
+    def _save_embeddings(self) -> None:
+        """Save embeddings cache to disk."""
+        try:
+            self.EMBEDDINGS_FILE.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.EMBEDDINGS_FILE, 'w') as f:
+                json.dump({
+                    "embeddings": self.embeddings,
+                    "metadata": self.metadata_cache
+                }, f)
+            logger.info(f"Saved {len(self.embeddings)} embeddings to cache.")
+        except Exception as e:
+            logger.error(f"Failed to save embeddings: {e}")
+    
+    def _build_embedding_text(self, table_name: str, metadata: dict) -> str:
+        """Build text representation of a table for embedding."""
+        parts = [f"Table: {table_name}"]
+        
+        # Description (prefer semantic if available)
+        desc = metadata.get("semantic_description") or metadata.get("description", "")
+        if desc:
+            parts.append(f"Description: {desc}")
+        
+        # Tags
+        tags = metadata.get("tags", [])
+        if tags:
+            parts.append(f"Tags: {', '.join(tags)}")
+        
+        # Category
+        category = metadata.get("category", "")
+        if category:
+            parts.append(f"Category: {category}")
+        
+        # Key columns (limit to first 15 for embedding efficiency)
+        columns = metadata.get("columns", [])
+        # Filter out generic columns
+        meaningful_cols = [c for c in columns[:15] if c not in ['geom', 'geometry', 'id', 'fid']]
+        if meaningful_cols:
+            parts.append(f"Columns: {', '.join(meaningful_cols)}")
+        
+        # Data type
+        data_type = metadata.get("data_type", "static")
+        parts.append(f"Data type: {data_type}")
+        
+        return ". ".join(parts)
+    
+    def _embed_text(self, text: str) -> Optional[List[float]]:
+        """Get embedding for a text string."""
+        if not self.client:
+            return None
+        
+        try:
+            result = self.client.models.embed_content(
+                model=self.EMBEDDING_MODEL,
+                contents=text  # Note: 'contents' not 'content'
+            )
+            return result.embeddings[0].values
+        except Exception as e:
+            logger.error(f"Embedding failed: {e}")
+            return None
+    
+    def _cosine_similarity(self, a: List[float], b: List[float]) -> float:
+        """Compute cosine similarity between two vectors."""
+        a_np = np.array(a)
+        b_np = np.array(b)
+        
+        dot_product = np.dot(a_np, b_np)
+        norm_a = np.linalg.norm(a_np)
+        norm_b = np.linalg.norm(b_np)
+        
+        if norm_a == 0 or norm_b == 0:
+            return 0.0
+        
+        return float(dot_product / (norm_a * norm_b))
+    
+    def embed_table(self, table_name: str, metadata: dict) -> bool:
+        """
+        Embed a table's metadata for semantic search.
+        
+        Returns True if embedding was successful or already cached.
+        """
+        text = self._build_embedding_text(table_name, metadata)
+        
+        # Check if already embedded with same text
+        if table_name in self.metadata_cache and self.metadata_cache[table_name] == text:
+            return True
+        
+        embedding = self._embed_text(text)
+        if embedding:
+            self.embeddings[table_name] = embedding
+            self.metadata_cache[table_name] = text
+            return True
+        
+        return False
+    
+    def embed_all_tables(self, catalog: Dict[str, dict]) -> int:
+        """
+        Embed all tables in the catalog.
+        
+        Returns number of newly embedded tables.
+        """
+        new_count = 0
+        
+        for table_name, metadata in catalog.items():
+            text = self._build_embedding_text(table_name, metadata)
+            
+            # Skip if already embedded with same text
+            if table_name in self.metadata_cache and self.metadata_cache[table_name] == text:
+                continue
+            
+            if self.embed_table(table_name, metadata):
+                new_count += 1
+        
+        if new_count > 0:
+            self._save_embeddings()
+            logger.info(f"Embedded {new_count} new tables.")
+        
+        return new_count
+    
+    def search(self, query: str, top_k: int = 15) -> List[Tuple[str, float]]:
+        """
+        Find the most relevant tables for a query.
+        
+        Returns list of (table_name, similarity_score) tuples, sorted by relevance.
+        """
+        if not self.embeddings:
+            logger.warning("No embeddings available. Returning empty results.")
+            return []
+        
+        # Embed the query
+        query_embedding = self._embed_text(query)
+        
+        if not query_embedding:
+            # Fallback to keyword matching
+            return self._keyword_fallback(query, top_k)
+        
+        # Compute similarities
+        scores = []
+        for table_name, table_embedding in self.embeddings.items():
+            score = self._cosine_similarity(query_embedding, table_embedding)
+            scores.append((table_name, score))
+        
+        # Sort by similarity (descending)
+        scores.sort(key=lambda x: -x[1])
+        
+        return scores[:top_k]
+    
+    def search_table_names(self, query: str, top_k: int = 15) -> List[str]:
+        """Convenience method that returns just table names."""
+        results = self.search(query, top_k)
+        return [name for name, _ in results]
+    
+    def _keyword_fallback(self, query: str, top_k: int) -> List[Tuple[str, float]]:
+        """
+        Simple keyword matching fallback when embeddings unavailable.
+        """
+        query_terms = query.lower().split()
+        scores = []
+        
+        for table_name, text in self.metadata_cache.items():
+            text_lower = text.lower()
+            score = sum(1 for term in query_terms if term in text_lower)
+            if score > 0:
+                scores.append((table_name, score / len(query_terms)))
+        
+        scores.sort(key=lambda x: -x[1])
+        return scores[:top_k]
+    
+    def get_stats(self) -> dict:
+        """Return statistics about the semantic search index."""
+        return {
+            "total_tables": len(self.embeddings),
+            "cache_file": str(self.EMBEDDINGS_FILE),
+            "cache_exists": self.EMBEDDINGS_FILE.exists(),
+            "client_available": self.client is not None
+        }
+
+
+# Singleton accessor
+_semantic_search: Optional[SemanticSearch] = None
+
+
+def get_semantic_search() -> SemanticSearch:
+    """Get the singleton semantic search instance."""
+    global _semantic_search
+    if _semantic_search is None:
+        _semantic_search = SemanticSearch()
+    return _semantic_search

backend/core/session_store.py

@@ -0,0 +1,179 @@
+"""
+Session Store Service
+
+Thread-safe session-scoped storage for user layers and context.
+Replaces global SESSION_LAYERS with per-session isolation.
+"""
+
+import logging
+import threading
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Any
+
+
+logger = logging.getLogger(__name__)
+
+
+class SessionStore:
+    """
+    Thread-safe session-scoped storage with TTL expiration.
+    
+    Each session maintains its own:
+    - layers: Map layers created by the user
+    - context: Optional conversation context
+    
+    Sessions expire after configurable TTL (default 2 hours).
+    """
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(SessionStore, cls).__new__(cls)
+            cls._instance.initialized = False
+        return cls._instance
+    
+    def __init__(self, ttl_hours: int = 2, max_layers_per_session: int = 15):
+        if self.initialized:
+            return
+        
+        self._sessions: Dict[str, dict] = {}
+        self._lock = threading.Lock()
+        self.ttl = timedelta(hours=ttl_hours)
+        self.max_layers = max_layers_per_session
+        self.initialized = True
+        
+        logger.info(f"SessionStore initialized with TTL={ttl_hours}h, max_layers={max_layers_per_session}")
+    
+    def _get_or_create_session(self, session_id: str) -> dict:
+        """Get existing session or create new one."""
+        if session_id not in self._sessions:
+            self._sessions[session_id] = {
+                "layers": [],
+                "created": datetime.now(),
+                "accessed": datetime.now()
+            }
+        return self._sessions[session_id]
+    
+    def get_layers(self, session_id: str) -> List[dict]:
+        """Get all layers for a session."""
+        with self._lock:
+            session = self._get_or_create_session(session_id)
+            session["accessed"] = datetime.now()
+            return session["layers"].copy()
+    
+    def add_layer(self, session_id: str, layer: dict) -> None:
+        """
+        Add a layer to a session.
+        
+        Enforces max_layers limit by removing oldest layers.
+        """
+        with self._lock:
+            session = self._get_or_create_session(session_id)
+            session["layers"].append(layer)
+            session["accessed"] = datetime.now()
+            
+            # Enforce layer limit
+            while len(session["layers"]) > self.max_layers:
+                removed = session["layers"].pop(0)
+                logger.debug(f"Session {session_id[:8]}: removed oldest layer {removed.get('name', 'unknown')}")
+    
+    def update_layer(self, session_id: str, layer_id: str, updates: dict) -> bool:
+        """
+        Update an existing layer in a session.
+        
+        Returns True if layer was found and updated.
+        """
+        with self._lock:
+            session = self._sessions.get(session_id)
+            if not session:
+                return False
+            
+            for layer in session["layers"]:
+                if layer.get("id") == layer_id:
+                    layer.update(updates)
+                    session["accessed"] = datetime.now()
+                    return True
+            
+            return False
+    
+    def remove_layer(self, session_id: str, layer_id: str) -> bool:
+        """
+        Remove a layer from a session.
+        
+        Returns True if layer was found and removed.
+        """
+        with self._lock:
+            session = self._sessions.get(session_id)
+            if not session:
+                return False
+            
+            original_len = len(session["layers"])
+            session["layers"] = [l for l in session["layers"] if l.get("id") != layer_id]
+            session["accessed"] = datetime.now()
+            
+            return len(session["layers"]) < original_len
+    
+    def clear_session(self, session_id: str) -> None:
+        """Clear all data for a session."""
+        with self._lock:
+            if session_id in self._sessions:
+                del self._sessions[session_id]
+    
+    def get_layer_by_index(self, session_id: str, index: int) -> Optional[dict]:
+        """Get a specific layer by 1-based index (for user references like 'Layer 1')."""
+        with self._lock:
+            session = self._sessions.get(session_id)
+            if not session:
+                return None
+            
+            layers = session["layers"]
+            if 1 <= index <= len(layers):
+                return layers[index - 1].copy()
+            
+            return None
+    
+    def cleanup_expired(self) -> int:
+        """
+        Remove sessions older than TTL.
+        
+        Returns number of expired sessions removed.
+        """
+        with self._lock:
+            now = datetime.now()
+            expired = [
+                sid for sid, data in self._sessions.items()
+                if now - data.get("accessed", data["created"]) > self.ttl
+            ]
+            
+            for sid in expired:
+                del self._sessions[sid]
+            
+            if expired:
+                logger.info(f"Cleaned up {len(expired)} expired sessions.")
+            
+            return len(expired)
+    
+    def get_stats(self) -> dict:
+        """Return statistics about active sessions."""
+        with self._lock:
+            total_layers = sum(len(s["layers"]) for s in self._sessions.values())
+            
+            return {
+                "active_sessions": len(self._sessions),
+                "total_layers": total_layers,
+                "ttl_hours": self.ttl.total_seconds() / 3600,
+                "max_layers_per_session": self.max_layers
+            }
+
+
+# Singleton accessor
+_session_store: Optional[SessionStore] = None
+
+
+def get_session_store() -> SessionStore:
+    """Get the singleton session store instance."""
+    global _session_store
+    if _session_store is None:
+        _session_store = SessionStore()
+    return _session_store

backend/data/catalog.json

@@ -0,0 +1,1290 @@
+{
+  "pan_admin3": {
+    "path": "base/pan_admin3.geojson",
+    "description": "Data from base/pan_admin3.geojson",
+    "semantic_description": "This dataset contains the third-level administrative boundaries (corregimientos) of Panama, including their hierarchical relationships to districts and provinces. It provides nationwide coverage of 594 territorial units, making it essential for localized demographic analysis, regional planning, and mapping public service distribution.",
+    "tags": [
+      "administrative",
+      "government",
+      "geographic",
+      "spatial",
+      "boundaries"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "adm3_name",
+      "adm3_name1",
+      "adm3_name2",
+      "adm3_name3",
+      "adm3_pcode",
+      "adm2_name",
+      "adm2_name1",
+      "adm2_name2",
+      "adm2_name3",
+      "adm2_pcode",
+      "adm1_name",
+      "adm1_name1",
+      "adm1_name2",
+      "adm1_name3",
+      "adm1_pcode",
+      "adm0_name",
+      "adm0_name1",
+      "adm0_name2",
+      "adm0_name3",
+      "adm0_pcode",
+      "valid_on",
+      "valid_to",
+      "area_sqkm",
+      "version",
+      "lang",
+      "lang1",
+      "lang2",
+      "lang3",
+      "adm3_ref_name",
+      "center_lat",
+      "center_lon",
+      "geom"
+    ],
+    "row_count": 594,
+    "category": "base",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:16.691836",
+    "last_enriched": "2026-01-09T16:36:08.469629"
+  },
+  "pan_adminpoints": {
+    "path": "base/pan_adminpoints.geojson",
+    "description": "Data from base/pan_adminpoints.geojson",
+    "semantic_description": "This dataset provides point locations for administrative centers across Panama, covering hierarchical levels from the national capital down to sub-district seats. It includes geographic coordinates and standardized naming conventions, making it a foundational tool for territorial planning and administrative spatial analysis.",
+    "tags": [
+      "administrative",
+      "points-of-interest",
+      "amenities",
+      "government",
+      "spatial",
+      "boundaries"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "admin_level",
+      "name",
+      "name1",
+      "name2",
+      "name3",
+      "x_coord",
+      "y_coord",
+      "adm4_name",
+      "adm4_name1",
+      "adm4_name2",
+      "adm4_name3",
+      "adm4_pcode",
+      "adm3_name",
+      "adm3_name1",
+      "adm3_name2",
+      "adm3_name3",
+      "adm3_pcode",
+      "adm2_name",
+      "adm2_name1",
+      "adm2_name2",
+      "adm2_name3",
+      "adm2_pcode",
+      "adm1_name",
+      "adm1_name1",
+      "adm1_name2",
+      "adm1_name3",
+      "adm1_pcode",
+      "adm0_name",
+      "adm0_name1",
+      "adm0_name2",
+      "adm0_name3",
+      "adm0_pcode",
+      "valid_on",
+      "valid_to",
+      "version",
+      "lang",
+      "lang1",
+      "lang2",
+      "lang3",
+      "geom"
+    ],
+    "row_count": 684,
+    "category": "base",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:16.764000",
+    "last_enriched": "2026-01-09T16:36:12.240069"
+  },
+  "pan_admin2": {
+    "path": "base/pan_admin2.geojson",
+    "description": "Data from base/pan_admin2.geojson",
+    "semantic_description": "This dataset comprises the second-level administrative boundaries for Panama, specifically representing the country's 76 districts. It includes standardized names and hierarchical P-codes for districts, provinces, and the national level to ensure data interoperability. This base layer is primarily used for administrative mapping, regional statistical analysis, and territorial planning.",
+    "tags": [
+      "administrative",
+      "government",
+      "geographic",
+      "spatial",
+      "boundaries"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "adm2_name",
+      "adm2_name1",
+      "adm2_name2",
+      "adm2_name3",
+      "adm2_pcode",
+      "adm1_name",
+      "adm1_name1",
+      "adm1_name2",
+      "adm1_name3",
+      "adm1_pcode",
+      "adm0_name",
+      "adm0_name1",
+      "adm0_name2",
+      "adm0_name3",
+      "adm0_pcode",
+      "valid_on",
+      "valid_to",
+      "area_sqkm",
+      "version",
+      "lang",
+      "lang1",
+      "lang2",
+      "lang3",
+      "adm2_ref_name",
+      "center_lat",
+      "center_lon",
+      "geom"
+    ],
+    "row_count": 76,
+    "category": "base",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:17.560205",
+    "last_enriched": "2026-01-09T16:36:16.456717"
+  },
+  "pan_admin0": {
+    "path": "base/pan_admin0.geojson",
+    "description": "Data from base/pan_admin0.geojson",
+    "semantic_description": "This dataset defines the national boundary of Panama, representing the country's primary administrative level (ADM0). It is typically used as a foundational layer for national-level spatial analysis, cartographic visualizations, and as a reference for countrywide area calculations and statistical aggregation.",
+    "tags": [
+      "administrative",
+      "government",
+      "geographic",
+      "spatial",
+      "boundaries"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "iso2",
+      "iso3",
+      "adm0_name",
+      "adm0_name1",
+      "adm0_name2",
+      "adm0_name3",
+      "adm0_pcode",
+      "valid_on",
+      "valid_to",
+      "version",
+      "area_sqkm",
+      "lang",
+      "lang1",
+      "lang2",
+      "lang3",
+      "adm0_ref_name",
+      "center_lat",
+      "center_lon",
+      "geom"
+    ],
+    "row_count": 1,
+    "category": "base",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:18.159865",
+    "last_enriched": "2026-01-09T16:36:18.989777"
+  },
+  "pan_admin1": {
+    "path": "base/pan_admin1.geojson",
+    "description": "Data from base/pan_admin1.geojson",
+    "semantic_description": "This dataset defines the 13 primary administrative divisions of Panama, including its provinces and major indigenous territories. It provides standardized names, area measurements, and codes necessary for nationwide spatial analysis and regional reporting. The layer serves as a foundational component for administrative mapping and aggregating statistical data at the provincial level.",
+    "tags": [
+      "administrative",
+      "government",
+      "geographic",
+      "spatial",
+      "boundaries"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "adm1_name",
+      "adm1_name1",
+      "adm1_name2",
+      "adm1_name3",
+      "adm1_pcode",
+      "adm0_name",
+      "adm0_name1",
+      "adm0_name2",
+      "adm0_name3",
+      "adm0_pcode",
+      "valid_on",
+      "valid_to",
+      "area_sqkm",
+      "version",
+      "lang",
+      "lang1",
+      "lang2",
+      "lang3",
+      "adm1_ref_name",
+      "center_lat",
+      "center_lon",
+      "geom"
+    ],
+    "row_count": 13,
+    "category": "base",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:18.936257",
+    "last_enriched": "2026-01-09T16:36:22.439266"
+  },
+  "pan_adminlines": {
+    "path": "base/pan_adminlines.geojson",
+    "description": "Data from base/pan_adminlines.geojson",
+    "semantic_description": "This dataset contains the linear administrative boundaries of Panama across various hierarchical levels, including province and district borders identified by standard P-codes. It serves as a foundational spatial layer for delineating jurisdictional limits and performing territorial analysis. The data is primarily used for cartographic visualization and spatial joins that require precise border definitions for administrative planning.",
+    "tags": [
+      "administrative",
+      "spatial",
+      "boundaries",
+      "government"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "adm_level",
+      "name",
+      "valid_on",
+      "valid_to",
+      "version",
+      "right_pcod",
+      "left_pcod",
+      "geom"
+    ],
+    "row_count": 2338,
+    "category": "base",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:19.846930",
+    "last_enriched": "2026-01-09T16:36:26.375260"
+  },
+  "universities": {
+    "path": "osm/universities.geojson",
+    "description": "Data from osm/universities.geojson",
+    "semantic_description": "This dataset identifies 62 higher education institutions across Panama, including attributes for names, operators, and facility types. It is designed for spatial analysis of educational coverage, urban infrastructure planning, and socio-economic research.",
+    "tags": [
+      "higher-education",
+      "education",
+      "infrastructure",
+      "osm",
+      "spatial",
+      "facilities",
+      "points",
+      "panama"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "name",
+      "osm_id",
+      "feature_type",
+      "operator",
+      "education_type",
+      "icon",
+      "geom"
+    ],
+    "row_count": 62,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:19.856764",
+    "last_enriched": "2026-01-09T16:36:33.114270"
+  },
+  "panama_healthsites_geojson": {
+    "path": "hdx/health_facilities/panama-healthsites-geojson.geojson",
+    "description": "Data from hdx/panama-healthsites-geojson.geojson",
+    "semantic_description": "This dataset provides location and attribute data for 986 health facilities across Panama, including hospitals, laboratories, and clinics sourced from OpenStreetMap. It includes detailed information on operational status, bed capacity, and staffing levels, making it suitable for analyzing health infrastructure distribution and healthcare accessibility mapping.",
+    "tags": [
+      "health",
+      "facilities",
+      "geographic",
+      "spatial",
+      "infrastructure"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "osm_type",
+      "completeness",
+      "amenity",
+      "healthcare",
+      "name",
+      "operator",
+      "source",
+      "speciality",
+      "operator_type",
+      "operational_status",
+      "opening_hours",
+      "beds",
+      "staff_doctors",
+      "staff_nurses",
+      "health_amenity_type",
+      "dispensing",
+      "wheelchair",
+      "emergency",
+      "insurance",
+      "water_source",
+      "electricity",
+      "is_in_health_area",
+      "is_in_health_zone",
+      "url",
+      "addr_housenumber",
+      "addr_street",
+      "addr_postcode",
+      "addr_city",
+      "changeset_id",
+      "changeset_version",
+      "changeset_timestamp",
+      "uuid",
+      "geom"
+    ],
+    "row_count": 986,
+    "category": "hdx",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:20.039814",
+    "last_enriched": "2026-01-09T16:35:58.888442"
+  },
+  "panama_healthsites_hxl_geojson": {
+    "path": "hdx/health_facilities/panama-healthsites-hxl-geojson.geojson",
+    "description": "Data from hdx/panama-healthsites-hxl-geojson.geojson",
+    "semantic_description": "This dataset comprises 986 health facilities across Panama, detailing hospitals, clinics, and laboratories with information on capacity, specialties, and operational status. It is designed for analyzing healthcare accessibility, resource distribution, and infrastructure coverage at a national level.",
+    "tags": [
+      "health",
+      "facilities",
+      "geographic",
+      "spatial",
+      "infrastructure"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "osm_type",
+      "completeness",
+      "#loc+amenity",
+      "#meta+healthcare",
+      "#loc +name",
+      "#meta +operator",
+      "#geo+bounds+url",
+      "#meta +speciality",
+      "#meta +operator_type",
+      "#contact +phone",
+      "#status+operational_status",
+      "#access +hours",
+      "#capacity +beds",
+      "#capacity +staff",
+      "#meta +health_amenity_type",
+      "#meta+dispensing",
+      "#meta+wheelchair",
+      "#meta+emergency",
+      "#meta+insurance",
+      "#meta+water_source",
+      "#meta+electricity",
+      "#meta+is_in_health_area",
+      "#meta+is_in_health_zone",
+      "#contact +url",
+      "addr_housenumber",
+      "addr_street",
+      "addr_postcode",
+      "addr_city",
+      "changeset_id",
+      "changeset_version",
+      "changeset_timestamp",
+      "#meta +id",
+      "geom"
+    ],
+    "row_count": 986,
+    "category": "hdx",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T16:15:20.152069",
+    "last_enriched": "2026-01-09T16:36:36.834369"
+  },
+  "kontur_population": {
+    "description": "Population density grid for Panama at 400m H3 hexagon resolution. Based on GHSL, Facebook HRSL, and Microsoft Buildings data.",
+    "tags": [
+      "population",
+      "density",
+      "panama",
+      "h3",
+      "hexagon",
+      "kontur",
+      "demographics"
+    ],
+    "data_type": "vector",
+    "geometry_type": "polygon",
+    "semantic_description": "Population count per 400m H3 hexagonal grid cell. Use for population density analysis, demographic studies, and urban/rural classification.",
+    "path": "kontur/kontur_population_EPSG4326.gpkg",
+    "columns": [
+      "h3",
+      "population",
+      "geom"
+    ],
+    "row_count": 33114
+  },
+  "osm_roads": {
+    "description": "OpenStreetMap Road network with classification for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "roads"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/roads.geojson"
+  },
+  "osm_pois": {
+    "description": "OpenStreetMap Points of interest (restaurants, shops, etc.) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "pois"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/pois.geojson"
+  },
+  "osm_pois_areas": {
+    "description": "OpenStreetMap POI areas (larger venues) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "pois areas"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/pois_areas.geojson"
+  },
+  "osm_buildings": {
+    "description": "OpenStreetMap Building footprints for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "buildings"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/buildings.geojson"
+  },
+  "osm_landuse": {
+    "description": "OpenStreetMap Land use zones (residential, commercial, etc.) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "landuse"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/landuse.geojson"
+  },
+  "osm_natural_points": {
+    "description": "OpenStreetMap Natural features (trees, peaks) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "natural points"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/natural_points.geojson"
+  },
+  "osm_natural_areas": {
+    "description": "OpenStreetMap Natural areas (forests, parks) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "natural areas"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/natural_areas.geojson"
+  },
+  "osm_water_areas": {
+    "description": "OpenStreetMap Water bodies (lakes, reservoirs) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "water areas"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/water_areas.geojson"
+  },
+  "osm_waterways": {
+    "description": "OpenStreetMap Rivers and streams for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "waterways"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/waterways.geojson"
+  },
+  "osm_railways": {
+    "description": "OpenStreetMap Railway lines for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "railways"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/railways.geojson"
+  },
+  "osm_traffic": {
+    "description": "OpenStreetMap Traffic infrastructure (signals, crossings) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "traffic"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/traffic.geojson"
+  },
+  "osm_traffic_areas": {
+    "description": "OpenStreetMap Traffic areas (parking lots) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "traffic areas"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/traffic_areas.geojson"
+  },
+  "osm_transport": {
+    "description": "OpenStreetMap Transport points (bus stops, stations) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "transport"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/transport.geojson"
+  },
+  "osm_transport_areas": {
+    "description": "OpenStreetMap Transport areas (airports, ports) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "transport areas"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/transport_areas.geojson"
+  },
+  "osm_places": {
+    "description": "OpenStreetMap Place names (cities, towns, villages) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "places"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/places.geojson"
+  },
+  "osm_places_areas": {
+    "description": "OpenStreetMap Place areas for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "places areas"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/places_areas.geojson"
+  },
+  "osm_places_of_worship": {
+    "description": "OpenStreetMap Places of worship for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "places of worship"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/places_of_worship.geojson"
+  },
+  "osm_places_of_worship_areas": {
+    "description": "OpenStreetMap Places of worship (buildings) for Panama",
+    "tags": [
+      "osm",
+      "panama",
+      "places of worship areas"
+    ],
+    "data_type": "vector",
+    "geometry_type": "auto",
+    "path": "osm/places_of_worship_areas.geojson"
+  },
+  "roads": {
+    "path": "osm/roads.geojson",
+    "description": "Data from osm/roads.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial",
+      "infrastructure",
+      "roads",
+      "transportation"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "ref",
+      "oneway",
+      "maxspeed",
+      "layer",
+      "bridge",
+      "tunnel",
+      "geom"
+    ],
+    "row_count": 118464,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:18:59.409660"
+  },
+  "places_of_worship_areas": {
+    "path": "osm/places_of_worship_areas.geojson",
+    "description": "Data from osm/places_of_worship_areas.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 694,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:18:59.460933"
+  },
+  "transport": {
+    "path": "osm/transport.geojson",
+    "description": "Data from osm/transport.geojson",
+    "semantic_description": null,
+    "tags": [
+      "maritime",
+      "spatial",
+      "infrastructure",
+      "transportation"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 1891,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:18:59.506892"
+  },
+  "pois_areas": {
+    "path": "osm/pois_areas.geojson",
+    "description": "Data from osm/pois_areas.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial",
+      "points-of-interest",
+      "amenities"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 11583,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:00.011175"
+  },
+  "railways": {
+    "path": "osm/railways.geojson",
+    "description": "Data from osm/railways.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "layer",
+      "bridge",
+      "tunnel",
+      "geom"
+    ],
+    "row_count": 296,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:00.034635"
+  },
+  "pois": {
+    "path": "osm/pois.geojson",
+    "description": "Data from osm/pois.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial",
+      "points-of-interest",
+      "amenities"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 11129,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:00.261571"
+  },
+  "natural_points": {
+    "path": "osm/natural_points.geojson",
+    "description": "Data from osm/natural_points.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial",
+      "points-of-interest",
+      "amenities"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 6500,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:00.395667"
+  },
+  "traffic": {
+    "path": "osm/traffic.geojson",
+    "description": "Data from osm/traffic.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 5902,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:00.509922"
+  },
+  "traffic_areas": {
+    "path": "osm/traffic_areas.geojson",
+    "description": "Data from osm/traffic_areas.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 3403,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:00.682898"
+  },
+  "buildings": {
+    "path": "osm/buildings.geojson",
+    "description": "Data from osm/buildings.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial",
+      "built-environment",
+      "infrastructure"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "type",
+      "geom"
+    ],
+    "row_count": 233936,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:08.488004"
+  },
+  "places": {
+    "path": "osm/places.geojson",
+    "description": "Data from osm/places.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial",
+      "population"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "population",
+      "name",
+      "geom"
+    ],
+    "row_count": 3683,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:08.594144"
+  },
+  "places_of_worship": {
+    "path": "osm/places_of_worship.geojson",
+    "description": "Data from osm/places_of_worship.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 228,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:08.609384"
+  },
+  "natural_areas": {
+    "path": "osm/natural_areas.geojson",
+    "description": "Data from osm/natural_areas.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 434,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:08.673965"
+  },
+  "waterways": {
+    "path": "osm/waterways.geojson",
+    "description": "Data from osm/waterways.geojson",
+    "semantic_description": null,
+    "tags": [
+      "natural-resources",
+      "spatial",
+      "hydrology"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "width",
+      "name",
+      "geom"
+    ],
+    "row_count": 15532,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:10.791546"
+  },
+  "water_areas": {
+    "path": "osm/water_areas.geojson",
+    "description": "Data from osm/water_areas.geojson",
+    "semantic_description": null,
+    "tags": [
+      "natural-resources",
+      "spatial",
+      "hydrology"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 3733,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:12.941528"
+  },
+  "landuse": {
+    "path": "osm/landuse.geojson",
+    "description": "Data from osm/landuse.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 16075,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:15.893984"
+  },
+  "transport_areas": {
+    "path": "osm/transport_areas.geojson",
+    "description": "Data from osm/transport_areas.geojson",
+    "semantic_description": null,
+    "tags": [
+      "maritime",
+      "spatial",
+      "infrastructure",
+      "transportation"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "name",
+      "geom"
+    ],
+    "row_count": 196,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:15.917475"
+  },
+  "places_areas": {
+    "path": "osm/places_areas.geojson",
+    "description": "Data from osm/places_areas.geojson",
+    "semantic_description": null,
+    "tags": [
+      "spatial",
+      "population"
+    ],
+    "data_type": "semi-static",
+    "update_frequency": null,
+    "columns": [
+      "osm_id",
+      "code",
+      "fclass",
+      "population",
+      "name",
+      "geom"
+    ],
+    "row_count": 239,
+    "category": "osm",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:19:16.220819"
+  },
+  "overture_places": {
+    "path": "overture/overture_places.geojson",
+    "description": "Points of Interest from Overture Maps (Places theme)",
+    "semantic_description": "Comprehensive list of businesses and landmarks with names and categories. Use this for finding specific amenities, shops, or named locations.",
+    "tags": [
+      "overture",
+      "places",
+      "poi",
+      "businesses",
+      "landmarks",
+      "spatial",
+      "panama"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "id",
+      "version",
+      "sources",
+      "names",
+      "categories",
+      "basic_category",
+      "taxonomy",
+      "confidence",
+      "websites",
+      "socials",
+      "emails",
+      "phones",
+      "brand",
+      "addresses",
+      "operating_status",
+      "geom"
+    ],
+    "row_count": 33362,
+    "category": "overture",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:37:03.188928"
+  },
+  "overture_roads": {
+    "path": "overture/overture_roads.geojson",
+    "description": "Road network segments from Overture Maps",
+    "semantic_description": "Road network segments including highways, streets, and paths. Contains road names and classification.",
+    "tags": [
+      "overture",
+      "roads",
+      "transportation",
+      "infrastructure",
+      "spatial",
+      "panama"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "id",
+      "version",
+      "sources",
+      "subtype",
+      "class",
+      "names",
+      "connectors",
+      "routes",
+      "subclass_rules",
+      "access_restrictions",
+      "level_rules",
+      "destinations",
+      "prohibited_transitions",
+      "rail_flags",
+      "road_surface",
+      "road_flags",
+      "speed_limits",
+      "width_rules",
+      "subclass",
+      "geom"
+    ],
+    "row_count": 179610,
+    "category": "overture",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:37:18.729125"
+  },
+  "overture_buildings": {
+    "path": "overture/overture_buildings.geojson",
+    "description": "Building footprints from Overture Maps",
+    "semantic_description": "Building footprints including Microsoft and OSM data. Useful for urban density, infrastructure planning, and built-environment analysis.",
+    "tags": [
+      "overture",
+      "buildings",
+      "footprints",
+      "infrastructure",
+      "spatial",
+      "panama"
+    ],
+    "data_type": "static",
+    "update_frequency": null,
+    "columns": [
+      "id",
+      "version",
+      "sources",
+      "level",
+      "subtype",
+      "class",
+      "height",
+      "names",
+      "has_parts",
+      "is_underground",
+      "num_floors",
+      "min_height",
+      "min_floor",
+      "num_floors_underground",
+      "facade_color",
+      "facade_material",
+      "roof_material",
+      "roof_shape",
+      "roof_direction",
+      "roof_orientation",
+      "roof_color",
+      "roof_height",
+      "geom"
+    ],
+    "row_count": 1888314,
+    "category": "overture",
+    "format": "geojson",
+    "last_indexed": "2026-01-09T18:38:50.416300"
+  },
+  "panama_weather_stations": {
+    "path": "climate/weather_stations.geojson",
+    "description": "Major weather stations in Panama with average temperature and rainfall data.",
+    "semantic_description": "This dataset contains the locations of major weather stations in Panama (Tocumen, David, Bocas del Toro, etc.). It includes attributes for average annual temperature (Celsius), annual rainfall (mm), and elevation. Use this for analyzing climatic differences across the country.",
+    "tags": [
+      "climate",
+      "weather",
+      "temperature",
+      "rainfall",
+      "stations"
+    ],
+    "data_type": "static",
+    "category": "climate",
+    "format": "geojson"
+  },
+  "panama_terrain_features": {
+    "path": "terrain/simplified_terrain.geojson",
+    "description": "Simplifed terrain features including major peaks and mountain ranges.",
+    "semantic_description": "A simplified dataset showing major terrain features of Panama, including Volc\u00e1n Bar\u00fa (highest peak) and the Central Cordillera. Contains points for peaks and lines for ranges, with elevation attributes.",
+    "tags": [
+      "terrain",
+      "elevation",
+      "mountains",
+      "volcano",
+      "geography"
+    ],
+    "data_type": "static",
+    "category": "climate",
+    "format": "geojson"
+  },
+  "panama_national_indicators": {
+    "path": "socioeconomic/panama_national_indicators.geojson",
+    "description": "National socio-economic indicators from World Bank (2000-2024)",
+    "semantic_description": "Comprehensive national-level statistics for Panama including poverty rates, GDP, unemployment, health expenditure, maternal/child mortality, literacy rates, and school enrollment. Data sourced from World Bank Open Data API. Use this dataset for analyzing Panama's socio-economic development trends over time.",
+    "tags": [
+      "socioeconomic",
+      "worldbank",
+      "poverty",
+      "gdp",
+      "employment",
+      "health",
+      "education",
+      "national",
+      "panama"
+    ],
+    "data_type": "static",
+    "category": "socioeconomic",
+    "format": "geojson"
+  },
+  "province_socioeconomic": {
+    "path": "socioeconomic/province_socioeconomic.geojson",
+    "description": "Province-level socioeconomic indicators for Panama (2023)",
+    "semantic_description": "Socioeconomic data at the province level including Multidimensional Poverty Index (MPI), population from Censo 2023, average income, and disability rates. Shows dramatic geographic inequality: Ng\u00e4be-Bugl\u00e9 comarca has 93.4% poverty vs 15% in Panam\u00e1 province. Use for analyzing regional disparities in poverty, development, and demographics.",
+    "tags": [
+      "socioeconomic",
+      "poverty",
+      "mpi",
+      "census",
+      "province",
+      "admin1",
+      "demographics",
+      "inequality",
+      "panama"
+    ],
+    "data_type": "static",
+    "category": "socioeconomic",
+    "format": "geojson"
+  },
+  "panama_airports": {
+    "path": "global/airports/panama_airports.geojson",
+    "description": "Panama airports from OurAirports global database (91 airports)",
+    "semantic_description": "Comprehensive dataset of all airports in Panama including international, domestic, regional, and small airfields. Contains location, elevation, type (large/medium/small/heliport), runway information, and identifiers (ICAO, IATA codes). Updated daily from OurAirports open database. Use for aviation infrastructure analysis, accessibility studies, and transportation planning.",
+    "tags": [
+      "infrastructure",
+      "transportation",
+      "airports",
+      "aviation",
+      "panama",
+      "ourairports"
+    ],
+    "data_type": "static",
+    "category": "infrastructure",
+    "format": "geojson",
+    "source": "OurAirports (davidmegginson/ourairports-data)",
+    "license": "Public Domain"
+  },
+  "censo_2023": {
+    "path": "censo/censo_2023_enriched.csv",
+    "description": "Panama Census 2023: Demographics & Housing (Corregimiento Level)",
+    "semantic_description": "Detailed dataset from the 2023 National Census of Population and Housing (Part I & II). Contains granular data at the Corregimiento level (Admin 3) covering: housing types, water access, sanitation, electricity sources, internet/computer access, education levels, and population demographics. Enriched with 'adm3_pcode' to enable spatial joining with 'pan_admin3'. Use for demographic analysis, infrastructure planning, and social program targeting.",
+    "tags": [
+      "census",
+      "demographics",
+      "housing",
+      "population",
+      "water",
+      "electricity",
+      "education",
+      "panama",
+      "2023"
+    ],
+    "data_type": "static",
+    "category": "socioeconomic",
+    "format": "csv",
+    "columns": [
+      "adm3_pcode",
+      "cod_corr",
+      "nomb_prov",
+      "nomb_dist",
+      "nomb_corr",
+      "v1_tipo_vivienda__individual_permanente",
+      "v8_abastecimiento_de_agua__acueducto_publico_del_idaan",
+      "p13_acceso_internet__si",
+      "p3_edad_digitos__total"
+    ]
+  }
+}

backend/data/catalog_schema.json

@@ -0,0 +1,145 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "GeoQuery Data Catalog Entry",
+    "description": "Schema for dataset metadata in the GeoQuery platform catalog",
+    "type": "object",
+    "required": [
+        "path",
+        "columns",
+        "category",
+        "format"
+    ],
+    "properties": {
+        "path": {
+            "type": "string",
+            "description": "Relative path to the data file from the data directory"
+        },
+        "description": {
+            "type": "string",
+            "description": "Auto-generated basic description (e.g., 'Data from hdx/health.geojson')"
+        },
+        "semantic_description": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "LLM-generated rich description explaining the dataset's contents and use cases"
+        },
+        "tags": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "description": "Searchable tags for categorization (e.g., ['health', 'facilities', 'infrastructure'])"
+        },
+        "data_type": {
+            "type": "string",
+            "enum": [
+                "static",
+                "semi-static",
+                "realtime"
+            ],
+            "description": "How frequently the data changes",
+            "default": "static"
+        },
+        "update_frequency": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "enum": [
+                null,
+                "yearly",
+                "monthly",
+                "weekly",
+                "daily",
+                "hourly",
+                "realtime"
+            ],
+            "description": "Expected update frequency for the dataset"
+        },
+        "columns": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "description": "List of column names in the dataset"
+        },
+        "row_count": {
+            "type": [
+                "integer",
+                "null"
+            ],
+            "description": "Number of features/rows in the dataset"
+        },
+        "category": {
+            "type": "string",
+            "description": "Source category (base, osm, hdx, inec, custom)"
+        },
+        "format": {
+            "type": "string",
+            "enum": [
+                "geojson",
+                "shapefile",
+                "geoparquet",
+                "csv"
+            ],
+            "description": "File format of the source data"
+        },
+        "geometry_type": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "enum": [
+                null,
+                "Point",
+                "MultiPoint",
+                "LineString",
+                "MultiLineString",
+                "Polygon",
+                "MultiPolygon"
+            ],
+            "description": "Type of geometries in the dataset"
+        },
+        "bbox": {
+            "type": [
+                "array",
+                "null"
+            ],
+            "items": {
+                "type": "number"
+            },
+            "minItems": 4,
+            "maxItems": 4,
+            "description": "Bounding box [minLon, minLat, maxLon, maxLat]"
+        },
+        "source": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "Original source of the data (e.g., 'OpenStreetMap', 'INEC Census 2023')"
+        },
+        "license": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "Data license (e.g., 'ODbL', 'CC-BY-4.0', 'Public Domain')"
+        },
+        "last_indexed": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO timestamp when the dataset was last indexed"
+        },
+        "last_enriched": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "format": "date-time",
+            "description": "ISO timestamp when LLM enrichment was last run"
+        }
+    }
+}

backend/data/global/airports/panama_airports.geojson

@@ -0,0 +1,98 @@
+{
+"type": "FeatureCollection",
+"name": "panama_airports",
+"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:OGC:1.3:CRS84" } },
+"features": [
+{ "type": "Feature", "properties": { "id": 308731, "ident": "CZJ", "type": "small_airport", "name": "Corazón de Jesús Airport", "latitude_deg": 9.44686, "longitude_deg": -78.575678, "elevation_ft": 8.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Tupile", "scheduled_service": "no", "icao_code": null, "iata_code": "CZJ", "gps_code": "MPCJ", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Coraz%C3%B3n_de_Jes%C3%BAs_Airport", "keywords": "Narganá, Usdup" }, "geometry": { "type": "Point", "coordinates": [ -78.575678, 9.44686 ] } },
+{ "type": "Feature", "properties": { "id": 309162, "ident": "GHE", "type": "small_airport", "name": "Garachiné Airport", "latitude_deg": 8.0644, "longitude_deg": -78.3673, "elevation_ft": 42.0, "continent": "SA", "iso_country": "PA", "iso_region": "PA-5", "municipality": "Garachiné", "scheduled_service": "no", "icao_code": null, "iata_code": "GHE", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Garachin%C3%A9_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.3673, 8.0644 ] } },
+{ "type": "Feature", "properties": { "id": 316549, "ident": "IVI", "type": "small_airport", "name": "Viveros Island Airport", "latitude_deg": 8.4693, "longitude_deg": -79.0016, "elevation_ft": 100.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Isla Viveros", "scheduled_service": "no", "icao_code": null, "iata_code": "IVI", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.0016, 8.4693 ] } },
+{ "type": "Feature", "properties": { "id": 5323, "ident": "MP01", "type": "small_airport", "name": "Finca Ceiba Airport", "latitude_deg": 8.3549995422363281, "longitude_deg": -82.836402893066406, "elevation_ft": 52.0, "continent": null, "iso_country": "PA", "iso_region": "PA-4", "municipality": "Finca Jaguá", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MP01", "local_code": "MP01", "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.836402893066406, 8.354999542236328 ] } },
+{ "type": "Feature", "properties": { "id": 5324, "ident": "MP02", "type": "small_airport", "name": "Finca 45 Airport", "latitude_deg": 9.543330192565918, "longitude_deg": -82.733802795410156, "elevation_ft": 56.0, "continent": null, "iso_country": "PA", "iso_region": "PA-1", "municipality": "Dos Caños", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MP02", "local_code": "MP02", "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.733802795410156, 9.543330192565918 ] } },
+{ "type": "Feature", "properties": { "id": 5325, "ident": "MP03", "type": "small_airport", "name": "La Cabezona Airport", "latitude_deg": 8.3457, "longitude_deg": -82.5042, "elevation_ft": 31.0, "continent": null, "iso_country": "PA", "iso_region": "PA-4", "municipality": "Guarumal", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPCB", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "MP03" }, "geometry": { "type": "Point", "coordinates": [ -82.5042, 8.3457 ] } },
+{ "type": "Feature", "properties": { "id": 5326, "ident": "MP17", "type": "small_airport", "name": "Finca 67 Airport", "latitude_deg": 9.4344100952148438, "longitude_deg": -82.499099731445312, "elevation_ft": 30.0, "continent": null, "iso_country": "PA", "iso_region": "PA-1", "municipality": "Changuinola", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MP17", "local_code": "MP17", "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.499099731445312, 9.434410095214844 ] } },
+{ "type": "Feature", "properties": { "id": 5327, "ident": "MP18", "type": "small_airport", "name": "Guillermo Palm Jaén Airport", "latitude_deg": 8.50383, "longitude_deg": -80.360298, "elevation_ft": 282.0, "continent": null, "iso_country": "PA", "iso_region": "PA-2", "municipality": "Penonomé", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPPN", "local_code": null, "home_link": "https://aerodromo-guillermo-palm-jaen.negocio.site/", "wikipedia_link": null, "keywords": "MP18" }, "geometry": { "type": "Point", "coordinates": [ -80.360298, 8.50383 ] } },
+{ "type": "Feature", "properties": { "id": 5330, "ident": "MP21", "type": "small_airport", "name": "Alvaro Berroa Airport", "latitude_deg": 8.7703895568847656, "longitude_deg": -82.664398193359375, "elevation_ft": 5000.0, "continent": null, "iso_country": "PA", "iso_region": "PA-4", "municipality": "Nueva California", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MP21", "local_code": "MP21", "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.664398193359375, 8.770389556884766 ] } },
+{ "type": "Feature", "properties": { "id": 5331, "ident": "MP22", "type": "small_airport", "name": "Ingenio Santa Rosa Airport", "latitude_deg": 8.1952199935913086, "longitude_deg": -80.658699035644531, "elevation_ft": 109.0, "continent": null, "iso_country": "PA", "iso_region": "PA-2", "municipality": "Ingenio Santa Rosa", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MP22", "local_code": "MP22", "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.658699035644531, 8.195219993591309 ] } },
+{ "type": "Feature", "properties": { "id": 5332, "ident": "MP23", "type": "small_airport", "name": "Capt. Alex H. Bosquez Airport", "latitude_deg": 9.16628, "longitude_deg": -79.545205, "elevation_ft": 394.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Calzada Larga", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPCL", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Calzada_Larga_Airport", "keywords": "MP23" }, "geometry": { "type": "Point", "coordinates": [ -79.545205, 9.16628 ] } },
+{ "type": "Feature", "properties": { "id": 5333, "ident": "MP24", "type": "small_airport", "name": "Captain Krish E. Persaud Airport", "latitude_deg": 8.58846, "longitude_deg": -79.889702, "elevation_ft": 141.0, "continent": null, "iso_country": "PA", "iso_region": "PA-10", "municipality": "Chame", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPCM", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Chame_Airport", "keywords": "Chame Airfield #1, MP24" }, "geometry": { "type": "Point", "coordinates": [ -79.889702, 8.58846 ] } },
+{ "type": "Feature", "properties": { "id": 5334, "ident": "MP26", "type": "small_airport", "name": "Punta Cocos Airport", "latitude_deg": 8.22485, "longitude_deg": -78.904404, "elevation_ft": 66.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Punta Cocos", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPPU", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "MP26" }, "geometry": { "type": "Point", "coordinates": [ -78.904404, 8.22485 ] } },
+{ "type": "Feature", "properties": { "id": 5335, "ident": "MP27", "type": "small_airport", "name": "Deborah Airport", "latitude_deg": 9.51614, "longitude_deg": -82.595497, "elevation_ft": 20.0, "continent": null, "iso_country": "PA", "iso_region": "PA-1", "municipality": "Guabito", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MP27", "local_code": "MP27", "home_link": null, "wikipedia_link": null, "keywords": "Guabito California" }, "geometry": { "type": "Point", "coordinates": [ -82.595497, 9.51614 ] } },
+{ "type": "Feature", "properties": { "id": 515607, "ident": "MPAG", "type": "small_airport", "name": "El Aguila Airstrip", "latitude_deg": 8.37168, "longitude_deg": -80.351676, "elevation_ft": 75.0, "continent": null, "iso_country": "PA", "iso_region": "PA-2", "municipality": "El Aguila", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPAG", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.351676, 8.37168 ] } },
+{ "type": "Feature", "properties": { "id": 4786, "ident": "MPBO", "type": "medium_airport", "name": "Bocas del Toro International Airport", "latitude_deg": 9.34085, "longitude_deg": -82.250801, "elevation_ft": 10.0, "continent": null, "iso_country": "PA", "iso_region": "PA-1", "municipality": "Isla Colón", "scheduled_service": "yes", "icao_code": "MPBO", "iata_code": "BOC", "gps_code": "MPBO", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Bocas_del_Toro_%22Isla_Colón%22_International_Airport", "keywords": "Jose Ezequiel Hall" }, "geometry": { "type": "Point", "coordinates": [ -82.250801, 9.34085 ] } },
+{ "type": "Feature", "properties": { "id": 4787, "ident": "MPCE", "type": "medium_airport", "name": "Alonso Valderrama Airport", "latitude_deg": 7.98784, "longitude_deg": -80.409837, "elevation_ft": 33.0, "continent": null, "iso_country": "PA", "iso_region": "PA-6", "municipality": "Chitré", "scheduled_service": "yes", "icao_code": "MPCE", "iata_code": "CTD", "gps_code": "MPCE", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Chitré_Alonso_Valderrama_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.409837, 7.98784 ] } },
+{ "type": "Feature", "properties": { "id": 4788, "ident": "MPCH", "type": "medium_airport", "name": "Changuinola Captain Manuel Niño International Airport", "latitude_deg": 9.458962, "longitude_deg": -82.515062, "elevation_ft": 19.0, "continent": null, "iso_country": "PA", "iso_region": "PA-1", "municipality": "Changuinola", "scheduled_service": "yes", "icao_code": "MPCH", "iata_code": "CHX", "gps_code": "MPCH", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Changuinola_%22Capit%C3%A1n_Manuel_Ni%C3%B1o%22_International_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.515062, 9.458962 ] } },
+{ "type": "Feature", "properties": { "id": 4789, "ident": "MPDA", "type": "medium_airport", "name": "Enrique Malek International Airport", "latitude_deg": 8.391, "longitude_deg": -82.434998, "elevation_ft": 89.0, "continent": null, "iso_country": "PA", "iso_region": "PA-4", "municipality": "David", "scheduled_service": "yes", "icao_code": "MPDA", "iata_code": "DAV", "gps_code": "MPDA", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Enrique_Malek_International_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.434998, 8.391 ] } },
+{ "type": "Feature", "properties": { "id": 4790, "ident": "MPEJ", "type": "medium_airport", "name": "Enrique Adolfo Jimenez Airport", "latitude_deg": 9.35664, "longitude_deg": -79.867401, "elevation_ft": 25.0, "continent": null, "iso_country": "PA", "iso_region": "PA-3", "municipality": "Colón", "scheduled_service": "yes", "icao_code": "MPEJ", "iata_code": "ONX", "gps_code": "MPEJ", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Enrique_Adolfo_Jim%C3%A9nez_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.867401, 9.35664 ] } },
+{ "type": "Feature", "properties": { "id": 525236, "ident": "MPFE", "type": "small_airport", "name": "Fernando Eleta Airport", "latitude_deg": 8.411389, "longitude_deg": -79.111115, "elevation_ft": 311.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Pedro de Cocal", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPFE", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/en:Fernando%20Eleta%20Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.111115, 8.411389 ] } },
+{ "type": "Feature", "properties": { "id": 42190, "ident": "MPFS", "type": "small_airport", "name": "Fort Sherman Airport", "latitude_deg": 9.3650903701782244, "longitude_deg": -79.949798583984375, "elevation_ft": 10.0, "continent": null, "iso_country": "PA", "iso_region": "PA-3", "municipality": "Fort Sherman", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPFS", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.949798583984375, 9.365090370178224 ] } },
+{ "type": "Feature", "properties": { "id": 30768, "ident": "MPHO", "type": "small_airport", "name": "Panamá Pacífico International Airport", "latitude_deg": 8.91479, "longitude_deg": -79.599602, "elevation_ft": 52.0, "continent": null, "iso_country": "PA", "iso_region": "PA-10", "municipality": "Panamá City", "scheduled_service": "yes", "icao_code": null, "iata_code": "BLB", "gps_code": "MPPA", "local_code": null, "home_link": "http://www.panamapacifico.com/", "wikipedia_link": "https://en.wikipedia.org/wiki/Panam%C3%A1_Pac%C3%ADfico_International_Airport", "keywords": "HOW, Howard Air Force Base, Panama Pacifico" }, "geometry": { "type": "Point", "coordinates": [ -79.599602, 8.91479 ] } },
+{ "type": "Feature", "properties": { "id": 316555, "ident": "MPI", "type": "small_airport", "name": "Mamitupu Airport", "latitude_deg": 9.1851, "longitude_deg": -77.9841, "elevation_ft": 25.0, "continent": "SA", "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Mamitupu", "scheduled_service": "no", "icao_code": null, "iata_code": "MPI", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Mamitupu_Airport", "keywords": "Mamitupo" }, "geometry": { "type": "Point", "coordinates": [ -77.9841, 9.1851 ] } },
+{ "type": "Feature", "properties": { "id": 31937, "ident": "MPJE", "type": "small_airport", "name": "Jaqué Airport", "latitude_deg": 7.51778, "longitude_deg": -78.157204, "elevation_ft": 29.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "Jaqué", "scheduled_service": "no", "icao_code": "MPJE", "iata_code": "JQE", "gps_code": "MPJE", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Jaqué_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.157204, 7.51778 ] } },
+{ "type": "Feature", "properties": { "id": 346902, "ident": "MPMC", "type": "small_airport", "name": "Chame Mayor Airport", "latitude_deg": 8.591418, "longitude_deg": -79.869189, "elevation_ft": 79.0, "continent": null, "iso_country": "PA", "iso_region": "PA-10", "municipality": "Chame", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPMC", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.869189, 8.591418 ] } },
+{ "type": "Feature", "properties": { "id": 4791, "ident": "MPMG", "type": "medium_airport", "name": "Marcos A. Gelabert International Airport", "latitude_deg": 8.97334, "longitude_deg": -79.555603, "elevation_ft": 31.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Albrook", "scheduled_service": "yes", "icao_code": "MPMG", "iata_code": "PAC", "gps_code": "MPMG", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Albrook_%22Marcos_A._Gelabert%22_International_Airport", "keywords": "Balboa. Albrook AFS. MPLB" }, "geometry": { "type": "Point", "coordinates": [ -79.555603, 8.97334 ] } },
+{ "type": "Feature", "properties": { "id": 31939, "ident": "MPNU", "type": "small_airport", "name": "Augusto Vergara Airport", "latitude_deg": 7.8575, "longitude_deg": -80.276167, "elevation_ft": 49.0, "continent": null, "iso_country": "PA", "iso_region": "PA-7", "municipality": "Los Santos", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPGU", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Augusto_Vergara_Airport", "keywords": "Guararé" }, "geometry": { "type": "Point", "coordinates": [ -80.276167, 7.8575 ] } },
+{ "type": "Feature", "properties": { "id": 42197, "ident": "MPOA", "type": "small_airport", "name": "Puerto Obaldía Airport", "latitude_deg": 8.668813, "longitude_deg": -77.417399, "elevation_ft": 223.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Puerto Obaldía", "scheduled_service": "no", "icao_code": "MPOA", "iata_code": "PUE", "gps_code": "MPOA", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Puerto_Obaldia_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.417399, 8.668813 ] } },
+{ "type": "Feature", "properties": { "id": 346878, "ident": "MPPD", "type": "small_airport", "name": "Capt. J. Montenegro Airport", "latitude_deg": 7.534801, "longitude_deg": -80.043347, "elevation_ft": 148.0, "continent": null, "iso_country": "PA", "iso_region": "PA-7", "municipality": "Pedasí", "scheduled_service": "yes", "icao_code": null, "iata_code": "PDM", "gps_code": "MPPD", "local_code": null, "home_link": null, "wikipedia_link": "https://es.wikipedia.org/wiki/Aeropuerto_Capit%C3%A1n_Justiniano_Montenegro", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.043347, 7.534801 ] } },
+{ "type": "Feature", "properties": { "id": 515602, "ident": "MPPT", "type": "small_airport", "name": "Punta Patiño Airstrip", "latitude_deg": 8.252816, "longitude_deg": -78.278618, "elevation_ft": 10.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "Punta Patiño", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPPT", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Punta_Pati%C3%B1o_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.278618, 8.252816 ] } },
+{ "type": "Feature", "properties": { "id": 4792, "ident": "MPSA", "type": "medium_airport", "name": "Ruben Cantu Airport", "latitude_deg": 8.0855998992919922, "longitude_deg": -80.945297241210938, "elevation_ft": 272.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Santiago", "scheduled_service": "no", "icao_code": "MPSA", "iata_code": "SYP", "gps_code": "MPSA", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Ruben_Cantu_Airport", "keywords": "Santiago" }, "geometry": { "type": "Point", "coordinates": [ -80.945297241210938, 8.085599899291992 ] } },
+{ "type": "Feature", "properties": { "id": 31940, "ident": "MPSM", "type": "small_airport", "name": "Scarlett Martinez International Airport", "latitude_deg": 8.3758802413940003, "longitude_deg": -80.127899169922003, "elevation_ft": 105.0, "continent": null, "iso_country": "PA", "iso_region": "PA-2", "municipality": "Río Hato", "scheduled_service": "yes", "icao_code": "MPSM", "iata_code": "RIH", "gps_code": "MPSM", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/R%C3%ADo_Hato_Airport", "keywords": "MPRH, Río Hato Army Air Base, Captain Scarlett Martinez" }, "geometry": { "type": "Point", "coordinates": [ -80.127899169922003, 8.375880241394 ] } },
+{ "type": "Feature", "properties": { "id": 4793, "ident": "MPTO", "type": "large_airport", "name": "Tocumen International Airport", "latitude_deg": 9.07136, "longitude_deg": -79.383499, "elevation_ft": 135.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Tocumen", "scheduled_service": "yes", "icao_code": "MPTO", "iata_code": "PTY", "gps_code": "MPTO", "local_code": null, "home_link": "https://www.tocumenpanama.aero/", "wikipedia_link": "https://en.wikipedia.org/wiki/Tocumen_International_Airport", "keywords": "La Joya No 1" }, "geometry": { "type": "Point", "coordinates": [ -79.383499, 9.07136 ] } },
+{ "type": "Feature", "properties": { "id": 42187, "ident": "MPVR", "type": "small_airport", "name": "El Porvenir Airport", "latitude_deg": 9.559212, "longitude_deg": -78.946631, "elevation_ft": 17.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "El Porvenir", "scheduled_service": "no", "icao_code": "MPVR", "iata_code": "PVE", "gps_code": "MPVR", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/El_Porvenir_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.946631, 9.559212 ] } },
+{ "type": "Feature", "properties": { "id": 32008, "ident": "MPWN", "type": "small_airport", "name": "Wannukandi Airport", "latitude_deg": 9.273476, "longitude_deg": -78.139848, "elevation_ft": 6.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "San Blas", "scheduled_service": "no", "icao_code": "MPWN", "iata_code": "NBL", "gps_code": "MPWN", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Wannukandi_Airport", "keywords": "San Blas Airport" }, "geometry": { "type": "Point", "coordinates": [ -78.139848, 9.273476 ] } },
+{ "type": "Feature", "properties": { "id": 4794, "ident": "MPZL", "type": "small_airport", "name": "Finca 32 Airport", "latitude_deg": 9.4270896911621094, "longitude_deg": -82.562698364257812, "elevation_ft": 23.0, "continent": null, "iso_country": "PA", "iso_region": "PA-1", "municipality": "La Dalia", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPZL", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.562698364257812, 9.427089691162109 ] } },
+{ "type": "Feature", "properties": { "id": 315194, "ident": "OGM", "type": "small_airport", "name": "Ogobsucum Airport", "latitude_deg": 9.1383, "longitude_deg": -77.93385, "elevation_ft": 13.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Ustupu", "scheduled_service": "no", "icao_code": null, "iata_code": "OGM", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Ustupu-Ogobsucum_Airport", "keywords": "Ogobsucun, Ogubsucum, Ogubsucun, Ustupo" }, "geometry": { "type": "Point", "coordinates": [ -77.93385, 9.1383 ] } },
+{ "type": "Feature", "properties": { "id": 42182, "ident": "PA-0001", "type": "small_airport", "name": "Achutupu Airport", "latitude_deg": 9.188481, "longitude_deg": -77.994153, "elevation_ft": 10.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Mamitupu", "scheduled_service": "no", "icao_code": null, "iata_code": "ACU", "gps_code": "MPAC", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Achutupo_Airport", "keywords": "Achutupo" }, "geometry": { "type": "Point", "coordinates": [ -77.994153, 9.188481 ] } },
+{ "type": "Feature", "properties": { "id": 42183, "ident": "PA-0002", "type": "small_airport", "name": "Aguadulce Airport", "latitude_deg": 8.2516498565673828, "longitude_deg": -80.565399169921875, "elevation_ft": 104.0, "continent": null, "iso_country": "PA", "iso_region": "PA-2", "municipality": "Aguadulce", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.565399169921875, 8.251649856567383 ] } },
+{ "type": "Feature", "properties": { "id": 42184, "ident": "PA-0003", "type": "small_airport", "name": "Ailigandí Airport", "latitude_deg": 9.2226, "longitude_deg": -78.0236, "elevation_ft": 55.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Isla Lorenzo Bello", "scheduled_service": "no", "icao_code": null, "iata_code": "AIL", "gps_code": "MPAI", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Ailigandí_Airport", "keywords": "Ailigandi, Alligandi" }, "geometry": { "type": "Point", "coordinates": [ -78.0236, 9.2226 ] } },
+{ "type": "Feature", "properties": { "id": 42185, "ident": "PA-0004", "type": "small_airport", "name": "Cartí Airport", "latitude_deg": 9.452863, "longitude_deg": -78.978917, "elevation_ft": 6.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Cartí Islands", "scheduled_service": "no", "icao_code": null, "iata_code": "CTE", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Cart%C3%AD_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.978917, 9.452863 ] } },
+{ "type": "Feature", "properties": { "id": 42186, "ident": "PA-0005", "type": "small_airport", "name": "Corazón de Jesús Airport", "latitude_deg": 9.0172195434570312, "longitude_deg": -77.980697631835938, "elevation_ft": 1008.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "Nurna", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.980697631835938, 9.017219543457031 ] } },
+{ "type": "Feature", "properties": { "id": 42188, "ident": "PA-0006", "type": "small_airport", "name": "Finca Blanco Airport", "latitude_deg": 8.389832, "longitude_deg": -82.870847, "elevation_ft": 72.0, "continent": null, "iso_country": "PA", "iso_region": "PA-4", "municipality": "Finca Blanco", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.870847, 8.389832 ] } },
+{ "type": "Feature", "properties": { "id": 42189, "ident": "PA-0007", "type": "small_airport", "name": "Finca Fátima Airport", "latitude_deg": 8.388027, "longitude_deg": -82.748509, "elevation_ft": 26.0, "continent": null, "iso_country": "PA", "iso_region": "PA-4", "municipality": "Finca Fátima", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.748509, 8.388027 ] } },
+{ "type": "Feature", "properties": { "id": 42191, "ident": "PA-0008", "type": "small_airport", "name": "La Joya Airport", "latitude_deg": 9.1385602951049805, "longitude_deg": -79.240196228027344, "elevation_ft": 96.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "La Joya", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.240196228027344, 9.13856029510498 ] } },
+{ "type": "Feature", "properties": { "id": 42192, "ident": "PA-0009", "type": "small_airport", "name": "La Plantación Airport", "latitude_deg": 7.6628899574279794, "longitude_deg": -81.006103515625, "elevation_ft": 21.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "La Plantación", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -81.006103515625, 7.662889957427979 ] } },
+{ "type": "Feature", "properties": { "id": 42193, "ident": "PA-0010", "type": "small_airport", "name": "Mandinga Airport", "latitude_deg": 9.454635, "longitude_deg": -79.086507, "elevation_ft": 38.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Mandinga", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.086507, 9.454635 ] } },
+{ "type": "Feature", "properties": { "id": 42194, "ident": "PA-0011", "type": "small_airport", "name": "Mulatupo Airport", "latitude_deg": 8.945487, "longitude_deg": -77.733486, "elevation_ft": 15.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Mulatupo", "scheduled_service": "no", "icao_code": null, "iata_code": "MPP", "gps_code": "MPMU", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Mulatupo_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.733486, 8.945487 ] } },
+{ "type": "Feature", "properties": { "id": 42195, "ident": "PA-0012", "type": "closed", "name": "Narganá Airport", "latitude_deg": 9.444659, "longitude_deg": -78.588896, "elevation_ft": 7.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Tupile", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "NGN, Corazón de Jesús" }, "geometry": { "type": "Point", "coordinates": [ -78.588896, 9.444659 ] } },
+{ "type": "Feature", "properties": { "id": 42196, "ident": "PA-0013", "type": "small_airport", "name": "Playón Chico Airport", "latitude_deg": 9.30692, "longitude_deg": -78.235273, "elevation_ft": 18.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Ukupseni", "scheduled_service": "no", "icao_code": null, "iata_code": "PYC", "gps_code": "MPPH", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Play%C3%B3n_Chico_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.235273, 9.30692 ] } },
+{ "type": "Feature", "properties": { "id": 42198, "ident": "PA-0014", "type": "small_airport", "name": "Río Azúcar Airport", "latitude_deg": 9.4247, "longitude_deg": -78.6269, "elevation_ft": 12.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Río Azúcar", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.6269, 9.4247 ] } },
+{ "type": "Feature", "properties": { "id": 42199, "ident": "PA-0015", "type": "small_airport", "name": "Rio Sidra Airport", "latitude_deg": 9.3167896270751953, "longitude_deg": -79.282997131347656, "elevation_ft": 2719.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Rio Sidra", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.282997131347656, 9.316789627075195 ] } },
+{ "type": "Feature", "properties": { "id": 42200, "ident": "PA-0016", "type": "small_airport", "name": "Río Tigre Airport", "latitude_deg": 9.2508802413940447, "longitude_deg": -78.498703002929688, "elevation_ft": 1095.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Río Tigre", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.498703002929688, 9.250880241394045 ] } },
+{ "type": "Feature", "properties": { "id": 42201, "ident": "PA-0017", "type": "small_airport", "name": "San Miguel Airport", "latitude_deg": 8.456507, "longitude_deg": -78.934214, "elevation_ft": 70.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Isla del Rey", "scheduled_service": "no", "icao_code": null, "iata_code": "NMG", "gps_code": "MPMI", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/San_Miguel_Airport,_Panama", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.934214, 8.456507 ] } },
+{ "type": "Feature", "properties": { "id": 42202, "ident": "PA-0018", "type": "small_airport", "name": "Tubualá Airport", "latitude_deg": 8.918601, "longitude_deg": -77.709182, "elevation_ft": 20.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Coetupo", "scheduled_service": "no", "icao_code": null, "iata_code": "TUW", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Tubual%C3%A1_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.709182, 8.918601 ] } },
+{ "type": "Feature", "properties": { "id": 42203, "ident": "PA-0019", "type": "small_airport", "name": "Tupile Airport", "latitude_deg": 9.2465801239013672, "longitude_deg": -78.362503051757812, "elevation_ft": 1374.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Tupile", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.362503051757812, 9.246580123901367 ] } },
+{ "type": "Feature", "properties": { "id": 342550, "ident": "PA-0020", "type": "small_airport", "name": "Coral Lodge Airport", "latitude_deg": 9.55488, "longitude_deg": -79.13786, "elevation_ft": 20.0, "continent": null, "iso_country": "PA", "iso_region": "PA-3", "municipality": "Santa Isabel", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.13786, 9.55488 ] } },
+{ "type": "Feature", "properties": { "id": 42205, "ident": "PA-0021", "type": "closed", "name": "Ailigandí North Airport", "latitude_deg": 9.23903, "longitude_deg": -78.03922, "elevation_ft": 19.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Ailigandí", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.03922, 9.23903 ] } },
+{ "type": "Feature", "properties": { "id": 42206, "ident": "PA-0022", "type": "small_airport", "name": "Yaviza Airport", "latitude_deg": 8.1528, "longitude_deg": -77.687, "elevation_ft": 75.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "Yaviza", "scheduled_service": "no", "icao_code": null, "iata_code": "PYV", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Yaviza_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.687, 8.1528 ] } },
+{ "type": "Feature", "properties": { "id": 315017, "ident": "PA-0023", "type": "closed", "name": "Isla Tigre Airstrip", "latitude_deg": 9.4339, "longitude_deg": -78.5235, "elevation_ft": 7.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Mamartupu", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.5235, 9.4339 ] } },
+{ "type": "Feature", "properties": { "id": 316550, "ident": "PA-0024", "type": "small_airport", "name": "Coiba Airport", "latitude_deg": 7.5068, "longitude_deg": -81.6981, "elevation_ft": 255.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Isla de Coiba", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -81.6981, 7.5068 ] } },
+{ "type": "Feature", "properties": { "id": 316551, "ident": "PA-0025", "type": "small_airport", "name": "Arenas Airport", "latitude_deg": 7.3713, "longitude_deg": -80.846, "elevation_ft": 85.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Arenas", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPAR", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.846, 7.3713 ] } },
+{ "type": "Feature", "properties": { "id": 316553, "ident": "PA-0026", "type": "small_airport", "name": "Tonosí Airport", "latitude_deg": 7.4148, "longitude_deg": -80.4466, "elevation_ft": 55.0, "continent": null, "iso_country": "PA", "iso_region": "PA-7", "municipality": "Tonosí", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.4466, 7.4148 ] } },
+{ "type": "Feature", "properties": { "id": 316554, "ident": "PA-0027", "type": "small_airport", "name": "Candelaria Airport", "latitude_deg": 7.7326, "longitude_deg": -80.1403, "elevation_ft": 65.0, "continent": null, "iso_country": "PA", "iso_region": "PA-7", "municipality": "La Candelaria", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.1403, 7.7326 ] } },
+{ "type": "Feature", "properties": { "id": 342551, "ident": "PA-0028", "type": "small_airport", "name": "Nusatupo Airport", "latitude_deg": 9.43392, "longitude_deg": -78.83173, "elevation_ft": 18.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Nusatupo", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.83173, 9.43392 ] } },
+{ "type": "Feature", "properties": { "id": 342552, "ident": "PA-0029", "type": "small_airport", "name": "Wannukandi Airport", "latitude_deg": 9.273166, "longitude_deg": -78.139873, "elevation_ft": 13.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Wannukandi", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.139873, 9.273166 ] } },
+{ "type": "Feature", "properties": { "id": 342553, "ident": "PA-0030", "type": "small_airport", "name": "Mansukun Airport", "latitude_deg": 9.05011, "longitude_deg": -77.80985, "elevation_ft": 10.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Mansukum", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.80985, 9.05011 ] } },
+{ "type": "Feature", "properties": { "id": 342554, "ident": "PA-0031", "type": "closed", "name": "Napakanti Airport", "latitude_deg": 9.012796, "longitude_deg": -77.802531, "elevation_ft": 66.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Napakanti", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.802531, 9.012796 ] } },
+{ "type": "Feature", "properties": { "id": 342555, "ident": "PA-0032", "type": "small_airport", "name": "Caledonia Airport", "latitude_deg": 8.90201, "longitude_deg": -77.69286, "elevation_ft": 3.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Suletupu", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPCA", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.69286, 8.90201 ] } },
+{ "type": "Feature", "properties": { "id": 430649, "ident": "PA-0033", "type": "heliport", "name": "Soloy Heliport", "latitude_deg": 8.4831, "longitude_deg": -82.0816, "elevation_ft": 424.0, "continent": null, "iso_country": "PA", "iso_region": "PA-NB", "municipality": "Soloy", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.0816, 8.4831 ] } },
+{ "type": "Feature", "properties": { "id": 505196, "ident": "PA-0034", "type": "closed", "name": "Aidirgandí Airport", "latitude_deg": 9.35515, "longitude_deg": -78.34587, "elevation_ft": 23.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Aidirgandí", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.34587, 9.35515 ] } },
+{ "type": "Feature", "properties": { "id": 505212, "ident": "PA-0035", "type": "closed", "name": "Ingenio Las Cabras Airstrip", "latitude_deg": 7.90044, "longitude_deg": -80.540391, "elevation_ft": 112.0, "continent": null, "iso_country": "PA", "iso_region": "PA-6", "municipality": "Las Cabras", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.540391, 7.90044 ] } },
+{ "type": "Feature", "properties": { "id": 506050, "ident": "PA-0036", "type": "closed", "name": "Punta Hermosa Airstrip", "latitude_deg": 7.527853, "longitude_deg": -81.849575, "elevation_ft": 250.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Isla de Coiba", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -81.849575, 7.527853 ] } },
+{ "type": "Feature", "properties": { "id": 506051, "ident": "PA-0037", "type": "small_airport", "name": "Coibito Landing Airstrip", "latitude_deg": 7.639068, "longitude_deg": -81.702433, "elevation_ft": null, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Isla Rancheria", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -81.702433, 7.639068 ] } },
+{ "type": "Feature", "properties": { "id": 506052, "ident": "PA-0038", "type": "small_airport", "name": "Pixvae Airstrip", "latitude_deg": 7.841248, "longitude_deg": -81.567301, "elevation_ft": 56.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Pixvae", "scheduled_service": "yes", "icao_code": null, "iata_code": null, "gps_code": "MPPX", "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "Pixbae, Pifa, Piba, Pejibaye" }, "geometry": { "type": "Point", "coordinates": [ -81.567301, 7.841248 ] } },
+{ "type": "Feature", "properties": { "id": 506053, "ident": "PA-0039", "type": "closed", "name": "Filipinas Airstrip", "latitude_deg": 7.728211, "longitude_deg": -81.262396, "elevation_ft": 59.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Carrizal", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -81.262396, 7.728211 ] } },
+{ "type": "Feature", "properties": { "id": 506054, "ident": "PA-0040", "type": "closed", "name": "La Providencia Airstrip", "latitude_deg": 7.8878, "longitude_deg": -80.978748, "elevation_ft": 121.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Ponuga", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.978748, 7.8878 ] } },
+{ "type": "Feature", "properties": { "id": 506055, "ident": "PA-0041", "type": "closed", "name": "Limones Airstrip", "latitude_deg": 7.619267, "longitude_deg": -80.946937, "elevation_ft": 141.0, "continent": null, "iso_country": "PA", "iso_region": "PA-9", "municipality": "Limones", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -80.946937, 7.619267 ] } },
+{ "type": "Feature", "properties": { "id": 5322, "ident": "PA-0042", "type": "closed", "name": "Pedasí Airport", "latitude_deg": 7.55688, "longitude_deg": -80.0233, "elevation_ft": 16.0, "continent": null, "iso_country": "PA", "iso_region": "PA-7", "municipality": "Pedasí", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "PDM, Capt Justiniano Montenegro, MP00" }, "geometry": { "type": "Point", "coordinates": [ -80.0233, 7.55688 ] } },
+{ "type": "Feature", "properties": { "id": 32164, "ident": "PA-0043", "type": "closed", "name": "Captain Ramon Xatruch Airport", "latitude_deg": 8.40667, "longitude_deg": -78.141701, "elevation_ft": 30.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "La Palma", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "MPLP, MPLP, PLP" }, "geometry": { "type": "Point", "coordinates": [ -78.141701, 8.40667 ] } },
+{ "type": "Feature", "properties": { "id": 315016, "ident": "PA-0044", "type": "closed", "name": "Tupile Airport", "latitude_deg": 9.45, "longitude_deg": -78.566667, "elevation_ft": 5.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Isla Tupile", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "TUE" }, "geometry": { "type": "Point", "coordinates": [ -78.566667, 9.45 ] } },
+{ "type": "Feature", "properties": { "id": 30640, "ident": "PA-AML", "type": "small_airport", "name": "Puerto Armuelles Airport", "latitude_deg": 8.267667, "longitude_deg": -82.864537, "elevation_ft": 42.0, "continent": null, "iso_country": "PA", "iso_region": "PA-4", "municipality": "Puerto Armuelles", "scheduled_service": "no", "icao_code": null, "iata_code": "AML", "gps_code": null, "local_code": null, "home_link": "https://visitpuertoarmuelles.com/airport-update-for-puerto-armuelles", "wikipedia_link": null, "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -82.864537, 8.267667 ] } },
+{ "type": "Feature", "properties": { "id": 35194, "ident": "PA-BFQ", "type": "small_airport", "name": "Bahia Piña Airport", "latitude_deg": 7.58737, "longitude_deg": -78.179939, "elevation_ft": 14.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "Puerto Piña", "scheduled_service": "yes", "icao_code": null, "iata_code": "BFQ", "gps_code": "MPPI", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Bah%C3%ADa_Pi%C3%B1a_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.179939, 7.58737 ] } },
+{ "type": "Feature", "properties": { "id": 35196, "ident": "PA-ELE", "type": "small_airport", "name": "EL Real Airport", "latitude_deg": 8.107235, "longitude_deg": -77.725545, "elevation_ft": 65.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "El Real de Santa María", "scheduled_service": "no", "icao_code": null, "iata_code": "ELE", "gps_code": "MPRE", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/El_Real_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -77.725545, 8.107235 ] } },
+{ "type": "Feature", "properties": { "id": 42181, "ident": "PA-MRF", "type": "small_airport", "name": "Miraflores Airport", "latitude_deg": 8.338889, "longitude_deg": -78.131944, "elevation_ft": 32.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "Miraflores", "scheduled_service": "no", "icao_code": null, "iata_code": null, "gps_code": "MPMF", "local_code": "MRF", "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Miraflores_Airport,_Dari%C3%A9n", "keywords": "MPSE" }, "geometry": { "type": "Point", "coordinates": [ -78.131944, 8.338889 ] } },
+{ "type": "Feature", "properties": { "id": 35195, "ident": "PA-OTD", "type": "small_airport", "name": "Raul Arias Espinoza Airport", "latitude_deg": 8.62876, "longitude_deg": -79.034698, "elevation_ft": 43.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Contadora Island", "scheduled_service": "yes", "icao_code": null, "iata_code": "OTD", "gps_code": "MPRA", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Contadora_Airport", "keywords": "Contadora Airport" }, "geometry": { "type": "Point", "coordinates": [ -79.034698, 8.62876 ] } },
+{ "type": "Feature", "properties": { "id": 35197, "ident": "PA-SAX", "type": "small_airport", "name": "Sambú Airport", "latitude_deg": 8.026279, "longitude_deg": -78.209555, "elevation_ft": 32.0, "continent": null, "iso_country": "PA", "iso_region": "PA-5", "municipality": "Boca de Sábalo", "scheduled_service": "no", "icao_code": null, "iata_code": "SAX", "gps_code": "MPSB", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Sambú_Airport", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -78.209555, 8.026279 ] } },
+{ "type": "Feature", "properties": { "id": 316552, "ident": "SIC", "type": "small_airport", "name": "San José Island Airport", "latitude_deg": 8.2622, "longitude_deg": -79.078, "elevation_ft": 150.0, "continent": null, "iso_country": "PA", "iso_region": "PA-8", "municipality": "Las Perlas", "scheduled_service": "no", "icao_code": null, "iata_code": "SIC", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/San_José_Airport_(Las_Perlas)", "keywords": null }, "geometry": { "type": "Point", "coordinates": [ -79.078, 8.2622 ] } },
+{ "type": "Feature", "properties": { "id": 315014, "ident": "TJC", "type": "small_airport", "name": "Ticantiquí Airport", "latitude_deg": 9.4185, "longitude_deg": -78.4896, "elevation_ft": 17.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Ticantiquí", "scheduled_service": "no", "icao_code": null, "iata_code": "TJC", "gps_code": null, "local_code": null, "home_link": null, "wikipedia_link": null, "keywords": "Tikantiki" }, "geometry": { "type": "Point", "coordinates": [ -78.4896, 9.4185 ] } },
+{ "type": "Feature", "properties": { "id": 315193, "ident": "UTU", "type": "small_airport", "name": "Ustupu Airport", "latitude_deg": 9.1283, "longitude_deg": -77.9337, "elevation_ft": 9.0, "continent": null, "iso_country": "PA", "iso_region": "PA-GY", "municipality": "Ustupu", "scheduled_service": "no", "icao_code": null, "iata_code": "UTU", "gps_code": "MPUP", "local_code": null, "home_link": null, "wikipedia_link": "https://en.wikipedia.org/wiki/Ustupo_Airport", "keywords": "Ustupo" }, "geometry": { "type": "Point", "coordinates": [ -77.9337, 9.1283 ] } }
+]
+}

backend/main.py

@@ -0,0 +1,68 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from pathlib import Path
+import os
+
+from backend.core.database import init_db
+from backend.api.api import api_router
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    try:
+        await init_db()
+    except Exception as e:
+        print(f"WARNING: Database initialization failed. Running in MOCK mode. Error: {e}")
+    yield
+    # Shutdown
+
+app = FastAPI(
+    title="GeoQuery API", 
+    description="Geospatial Analysis Agent API", 
+    version="0.1.0",
+    lifespan=lifespan
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"], # Allow all for dev
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(api_router, prefix="/api/v1")
+
+# Serve static files (Frontend)
+static_dir = Path(__file__).parent / "static"
+
+if static_dir.exists():
+    app.mount("/_next", StaticFiles(directory=static_dir / "_next"), name="next")
+    # app.mount("/assets", StaticFiles(directory=static_dir / "assets"), name="assets") # Standard Next.js Output might not use this top-level
+    
+    @app.get("/{full_path:path}")
+    async def serve_frontend(full_path: str):
+        # API requests are already handled by include_router above (because specific routes take precedence? No, order matters).
+        # Wait, explicit routes define earlier take precedence. 
+        # But include_router adds routes. 
+        # A catch-all route /{full_path:path} will capture everything NOT matched by previous routes.
+        # Since api_router is included first (implicitly? No, verify order).
+        # FastAPI router priority: First declared wins.
+        # So app.include_router MUST be before this catch-all. It is.
+        
+        file_path = static_dir / full_path
+        if file_path.exists() and file_path.is_file():
+            return FileResponse(file_path)
+            
+        # Fallback to index.html for SPA routing
+        index_path = static_dir / "index.html"
+        if index_path.exists():
+            return FileResponse(index_path)
+        return {"error": "Frontend not found"}
+else:
+    @app.get("/")
+    def read_root():
+        return {"message": "GeoQuery API is running (Frontend not built)"}

backend/pyproject.toml

@@ -0,0 +1,31 @@
+[tool.poetry]
+name = "geoquery-backend"
+version = "0.1.0"
+description = "Backend for GeoQuery AI Platform"
+authors = ["Admin <admin@geoquery.com>"]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+fastapi = "^0.109.0"
+uvicorn = "^0.27.0"
+sqlmodel = "^0.0.14"
+asyncpg = "^0.29.0"
+geoalchemy2 = "^0.14.3"
+python-multipart = "^0.0.6"
+httpx = "^0.26.0"
+duckdb = "^1.1.0"
+pandas = "^2.0.0"
+google-genai = "^0.1.0"
+google-generativeai = "^0.3.0"
+sentence-transformers = "^2.2.0"
+scikit-learn = "^1.3.0"
+numpy = "^1.26.0"
+python-dotenv = "^1.0.0"
+shapely = "^2.0.0"
+
+[tool.poetry.dev-dependencies]
+pytest = "^8.0.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

backend/requirements.txt

@@ -0,0 +1,18 @@
+fastapi>=0.109.0
+uvicorn>=0.27.0
+sqlmodel>=0.0.14
+asyncpg>=0.29.0
+geoalchemy2>=0.14.3
+python-multipart>=0.0.6
+httpx>=0.26.0
+duckdb>=1.1.0
+pandas>=2.0.0
+google-genai>=0.1.0
+google-generativeai>=0.3.0
+sentence-transformers>=2.2.0
+scikit-learn>=1.3.0
+numpy>=1.26.0
+python-dotenv>=1.0.0
+shapely>=2.0.0
+geopandas>=0.14.0
+requests>=2.31.0

backend/scripts/create_province_layer.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+Create province-level socio-economic layer for Panama
+Uses known data from research (MPI, Census highlights) joined to admin boundaries
+"""
+
+import geopandas as gpd
+import pandas as pd
+from pathlib import Path
+import logging
+import json
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+BASE_DIR = DATA_DIR / "base"
+OUTPUT_DIR = DATA_DIR / "socioeconomic"
+
+# Province-level data from MPI and Census research
+# Sources: INEC MPI 2017, Censo 2023 highlights, World Bank Poverty Assessment
+PROVINCE_DATA = {
+    "Bocas del Toro": {
+        "mpi_poverty_pct": 75.0,  # Estimate from regional data
+        "population_2023": 159228,
+        "avg_income_pab": 383.14,
+        "disability_rate": 3.21
+    },
+    "Coclé": {
+        "mpi_poverty_pct": 35.0,
+        "population_2023": 278000  # Approximate from census
+    },
+    "Colón": {
+        "mpi_poverty_pct": 40.0,
+        "population_2023": 283000
+    },
+    "Chiriquí": {
+        "mpi_poverty_pct": 30.0,
+        "population_2023": 498000
+    },
+    "Darién": {
+        "mpi_poverty_pct": 65.0,
+        "population_2023": 57000
+    },
+    "Herrera": {
+        "mpi_poverty_pct": 25.0,
+        "population_2023": 123000
+    },
+    "Los Santos": {
+        "mpi_poverty_pct": 22.0,
+        "population_2023": 97000
+    },
+    "Panamá": {
+        "mpi_poverty_pct": 15.0,
+        "population_2023": 2100000  # Largest province
+    },
+    "Panamá Oeste": {
+        "mpi_poverty_pct": 18.0,
+        "population_2023": 550000
+    },
+    "Veraguas": {
+        "mpi_poverty_pct": 45.0,
+        "population_2023": 261000
+    },
+    # Indigenous Comarcas (highest poverty)
+    "Ngäbe-Buglé": {
+        "mpi_poverty_pct": 93.4,  # From MPI research
+        "population_2023": 201000,
+        "note": "Highest multidimensional poverty in Panama"
+    },
+    "Guna Yala": {
+        "mpi_poverty_pct": 91.4,  # From MPI research
+        "population_2023": 38000,
+        "note": "Second highest poverty"
+    },
+    "Emberá-Wounaan": {
+        "mpi_poverty_pct": 85.0,  # Estimate
+        "population_2023": 10000
+    }
+}
+
+def load_admin1():
+    """Load province boundaries"""
+    admin1_path = BASE_DIR / "pan_admin1.geojson"
+    gdf = gpd.read_file(admin1_path)
+    logger.info(f"Loaded {len(gdf)} province boundaries")
+    return gdf
+
+def create_province_layer():
+    """Create GeoJSON with province-level socioeconomic data"""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # Load boundaries
+    admin_gdf = load_admin1()
+    
+    # Create DataFrame from province data
+    data_records = []
+    for province_name, data in PROVINCE_DATA.items():
+        record = {"province_name": province_name, **data}
+        data_records.append(record)
+    
+    data_df = pd.DataFrame(data_records)
+    logger.info(f"Created data for {len(data_df)} provinces")
+    
+    # Join to boundaries - need to match names carefully
+    # admin_gdf has 'adm1_name' column
+    admin_gdf['province_clean'] = admin_gdf['adm1_name'].str.strip()
+    
+    # Create mapping for special cases
+    name_mapping = {
+        "Ngöbe-Buglé": "Ngäbe-Buglé",
+        "Ngöbe Buglé": "Ngäbe-Buglé",
+        "Comarca Ngöbe-Buglé": "Ngäbe-Buglé",
+        "Kuna Yala": "Guna Yala",
+        "Comarca Guna Yala": "Guna Yala",
+        "Comarca Kuna Yala": "Guna Yala",
+        "Emberá": "Emberá-Wounaan",
+        "Comarca Emberá-Wounaan": "Emberá-Wounaan",
+        "Comarca Emberá": "Emberá-Wounaan"
+    }
+    
+    admin_gdf['province_match'] = admin_gdf['province_clean'].replace(name_mapping)
+    
+    # Merge
+    merged_gdf = admin_gdf.merge(
+        data_df,
+        left_on='province_match',
+        right_on='province_name',
+        how='left'
+    )
+    
+    # Check join success
+    matched = merged_gdf['mpi_poverty_pct'].notna().sum()
+    logger.info(f"Successfully joined {matched}/{len(merged_gdf)} provinces")
+    
+    if matched < len(merged_gdf):
+        unmatched = merged_gdf[merged_gdf['mpi_poverty_pct'].isna()]['adm1_name'].tolist()
+        logger.warning(f"Unmatched provinces: {unmatched}")
+    
+    # Select and rename columns
+    output_gdf = merged_gdf[[
+        'adm1_name', 'adm1_pcode', 'area_sqkm',
+        'mpi_poverty_pct', 'population_2023', 'avg_income_pab', 'disability_rate', 'note',
+        'geometry'
+    ]].copy()
+    
+    # Save as GeoJSON
+    output_file = OUTPUT_DIR / "province_socioeconomic.geojson"
+    output_gdf.to_file(output_file, driver='GeoJSON')
+    
+    logger.info(f"Created province layer: {output_file}")
+    logger.info(f"  - {matched} provinces with MPI data")
+    logger.info(f"  - {output_gdf['population_2023'].notna().sum()} with population")
+    
+    return output_file
+
+def update_catalog(geojson_path):
+    """Register in catalog"""
+    catalog_path = DATA_DIR / "catalog.json"
+    
+    with open(catalog_path, 'r') as f:
+        catalog = json.load(f)
+    
+    catalog["province_socioeconomic"] = {
+        "path": str(geojson_path.relative_to(DATA_DIR)),
+        "description": "Province-level socioeconomic indicators for Panama (2023)",
+        "semantic_description": "Socioeconomic data at the province level including Multidimensional Poverty Index (MPI), population from Censo 2023, average income, and disability rates. Shows dramatic geographic inequality: Ngäbe-Buglé comarca has 93.4% poverty vs 15% in Panamá province. Use for analyzing regional disparities in poverty, development, and demographics.",
+        "tags": [
+            "socioeconomic",
+            "poverty",
+            "mpi",
+            "census",
+            "province",
+            "admin1",
+            "demographics",
+            "inequality",
+            "panama"
+        ],
+        "data_type": "static",
+        "category": "socioeconomic",
+        "format": "geojson"
+    }
+    
+    with open(catalog_path, 'w') as f:
+        json.dump(catalog, f, indent=2)
+    
+    logger.info("Updated catalog.json")
+
+def main():
+    logger.info("Creating province socioeconomic layer...")
+    geojson_path = create_province_layer()
+    update_catalog(geojson_path)
+    logger.info("Complete!")
+
+if __name__ == "__main__":
+    main()

backend/scripts/download_geofabrik.py

@@ -0,0 +1,192 @@
+"""
+Panama Data Ingestion - Phase A: OpenStreetMap via Geofabrik
+
+Downloads pre-packaged OSM data for Panama as shapefiles and converts to GeoJSON.
+Data source: https://download.geofabrik.de/central-america.html
+"""
+
+import os
+import sys
+import zipfile
+import requests
+import subprocess
+from pathlib import Path
+
+# Panama Geofabrik URL
+GEOFABRIK_URL = "https://download.geofabrik.de/central-america/panama-latest-free.shp.zip"
+
+# Output directories
+DATA_DIR = Path(__file__).parent.parent / "data"
+OSM_DIR = DATA_DIR / "osm"
+TEMP_DIR = DATA_DIR / "temp"
+
+# OSM layers to extract
+OSM_LAYERS = [
+    ("gis_osm_roads_free_1", "roads", "Road network with classification"),
+    ("gis_osm_pois_free_1", "pois", "Points of interest (restaurants, shops, etc.)"),
+    ("gis_osm_pois_a_free_1", "pois_areas", "POI areas (larger venues)"),
+    ("gis_osm_buildings_a_free_1", "buildings", "Building footprints"),
+    ("gis_osm_landuse_a_free_1", "landuse", "Land use zones (residential, commercial, etc.)"),
+    ("gis_osm_natural_free_1", "natural_points", "Natural features (trees, peaks)"),
+    ("gis_osm_natural_a_free_1", "natural_areas", "Natural areas (forests, parks)"),
+    ("gis_osm_water_a_free_1", "water_areas", "Water bodies (lakes, reservoirs)"),
+    ("gis_osm_waterways_free_1", "waterways", "Rivers and streams"),
+    ("gis_osm_railways_free_1", "railways", "Railway lines"),
+    ("gis_osm_traffic_free_1", "traffic", "Traffic infrastructure (signals, crossings)"),
+    ("gis_osm_traffic_a_free_1", "traffic_areas", "Traffic areas (parking lots)"),
+    ("gis_osm_transport_free_1", "transport", "Transport points (bus stops, stations)"),
+    ("gis_osm_transport_a_free_1", "transport_areas", "Transport areas (airports, ports)"),
+    ("gis_osm_places_free_1", "places", "Place names (cities, towns, villages)"),
+    ("gis_osm_places_a_free_1", "places_areas", "Place areas"),
+    ("gis_osm_pofw_free_1", "places_of_worship", "Places of worship"),
+    ("gis_osm_pofw_a_free_1", "places_of_worship_areas", "Places of worship (buildings)"),
+]
+
+
+def download_file(url: str, dest: Path) -> bool:
+    """Download a file with progress indication."""
+    print(f"📥 Downloading {url}...")
+    
+    try:
+        response = requests.get(url, stream=True)
+        response.raise_for_status()
+        
+        total_size = int(response.headers.get('content-length', 0))
+        downloaded = 0
+        
+        with open(dest, 'wb') as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+                downloaded += len(chunk)
+                if total_size > 0:
+                    pct = (downloaded / total_size) * 100
+                    print(f"\r  Progress: {pct:.1f}% ({downloaded // 1024 // 1024}MB)", end="")
+        
+        print(f"\n✅ Downloaded to {dest}")
+        return True
+        
+    except Exception as e:
+        print(f"❌ Download failed: {e}")
+        return False
+
+
+def convert_shp_to_geojson(shp_path: Path, geojson_path: Path) -> bool:
+    """Convert shapefile to GeoJSON using ogr2ogr."""
+    try:
+        cmd = [
+            "ogr2ogr", 
+            "-f", "GeoJSON",
+            "-t_srs", "EPSG:4326",  # Ensure WGS84
+            str(geojson_path),
+            str(shp_path)
+        ]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        
+        if result.returncode == 0:
+            return True
+        else:
+            print(f"  ogr2ogr error: {result.stderr}")
+            return False
+            
+    except FileNotFoundError:
+        print("⚠️  ogr2ogr not found. Please install GDAL:")
+        print("   brew install gdal  # macOS")
+        print("   apt install gdal-bin  # Ubuntu")
+        return False
+
+
+def extract_and_convert():
+    """Extract shapefiles from zip and convert to GeoJSON."""
+    
+    # Ensure directories exist
+    OSM_DIR.mkdir(parents=True, exist_ok=True)
+    TEMP_DIR.mkdir(parents=True, exist_ok=True)
+    
+    zip_path = TEMP_DIR / "panama-osm.zip"
+    
+    # Download if not exists
+    if not zip_path.exists():
+        if not download_file(GEOFABRIK_URL, zip_path):
+            return False
+    else:
+        print(f"📦 Using cached {zip_path}")
+    
+    # Extract
+    print(f"📂 Extracting to {TEMP_DIR}...")
+    with zipfile.ZipFile(zip_path, 'r') as zf:
+        zf.extractall(TEMP_DIR)
+    
+    # Convert each layer
+    converted = 0
+    for shp_name, output_name, description in OSM_LAYERS:
+        shp_path = TEMP_DIR / f"{shp_name}.shp"
+        geojson_path = OSM_DIR / f"{output_name}.geojson"
+        
+        if not shp_path.exists():
+            print(f"⏭️  Skipping {shp_name} (not in download)")
+            continue
+        
+        print(f"🔄 Converting {shp_name} → {output_name}.geojson...")
+        
+        if convert_shp_to_geojson(shp_path, geojson_path):
+            # Get file size
+            size_mb = geojson_path.stat().st_size / 1024 / 1024
+            print(f"  ✅ Created {geojson_path.name} ({size_mb:.1f}MB)")
+            converted += 1
+        else:
+            print(f"  ❌ Failed to convert {shp_name}")
+    
+    print(f"\n🎉 Converted {converted}/{len(OSM_LAYERS)} OSM layers")
+    return converted > 0
+
+
+def register_in_catalog():
+    """Register OSM datasets in the catalog."""
+    import json
+    
+    catalog_path = DATA_DIR / "catalog.json"
+    
+    if catalog_path.exists():
+        with open(catalog_path) as f:
+            catalog = json.load(f)
+    else:
+        catalog = {}
+    
+    for shp_name, output_name, description in OSM_LAYERS:
+        geojson_path = OSM_DIR / f"{output_name}.geojson"
+        
+        if not geojson_path.exists():
+            continue
+        
+        # Create catalog entry
+        table_name = f"osm_{output_name}"
+        rel_path = f"osm/{output_name}.geojson"
+        
+        catalog[table_name] = {
+            "source_file": rel_path,
+            "source_type": "geojson",
+            "description": f"OpenStreetMap {description} for Panama",
+            "tags": ["osm", "panama", output_name.replace("_", " ")],
+            "data_type": "vector",
+            "geometry_type": "auto"  # Will be detected on load
+        }
+        
+        print(f"📝 Registered {table_name}")
+    
+    with open(catalog_path, 'w') as f:
+        json.dump(catalog, f, indent=2)
+    
+    print(f"✅ Updated catalog with OSM datasets")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("🗺️  Panama OSM Data Ingestion (Geofabrik)")
+    print("=" * 60)
+    
+    if extract_and_convert():
+        register_in_catalog()
+        print("\n🚀 OSM data ready! Restart the backend to load new datasets.")
+    else:
+        print("\n❌ Ingestion failed")
+        sys.exit(1)

backend/scripts/download_global_datasets.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Download global geo-referenced datasets for Panama
+- OurAirports: Global airport database
+- WRI Global Power Plant Database
+- Other infrastructure datasets
+"""
+
+import requests
+import pandas as pd
+import geopandas as gpd
+from pathlib import Path
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data" / "global"
+
+# Dataset URLs
+DATASETS = {
+    "airports": {
+        "url": "https://davidmegginson.github.io/ourairports-data/airports.csv",
+        "description": "OurAirports - Global airport database"
+    },
+    "power_plants": {
+        "url": "https://wri-dataportal-prod.s3.amazonaws.com/manual/global_power_plant_database_v_1_3/global_power_plant_database.csv",
+        "description": "WRI Global Power Plant Database v1.3"
+    }
+}
+
+def download_airports():
+    """Download and process OurAir ports data for Panama"""
+    logger.info("Downloading OurAirports global database...")
+    
+    url = DATASETS["airports"]["url"]
+    response = requests.get(url)
+    response.raise_for_status()
+    
+    # Save raw CSV
+    output_dir = DATA_DIR / "airports"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    csv_path = output_dir / "airports_global.csv"
+    with open(csv_path, 'wb') as f:
+        f.write(response.content)
+    
+    logger.info(f"Saved raw airports data: {csv_path}")
+    
+    # Filter for Panama (iso_country = PA)
+    df = pd.read_csv(csv_path)
+    panama_df = df[df['iso_country'] == 'PA'].copy()
+    
+    logger.info(f"Found {len(panama_df)} airports in Panama")
+    
+    # Convert to GeoDataFrame
+    gdf = gpd.GeoDataFrame(
+        panama_df,
+        geometry=gpd.points_from_xy(panama_df.longitude_deg, panama_df.latitude_deg),
+        crs="EPSG:4326"
+    )
+    
+    # Save as GeoJSON
+    geojson_path = output_dir / "panama_airports.geojson"
+    gdf.to_file(geojson_path, driver='GeoJSON')
+    
+    logger.info(f"Created GeoJSON: {geojson_path}")
+    return geojson_path, len(gdf)
+
+def download_power_plants():
+    """Download and process WRI Global Power Plant Database for Panama"""
+    logger.info("Downloading WRI Global Power Plant Database...")
+    
+    url = DATASETS["power_plants"]["url"]
+    response = requests.get(url)
+    response.raise_for_status()
+    
+    # Save raw CSV
+    output_dir = DATA_DIR / "power_plants"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    csv_path = output_dir / "power_plants_global.csv"
+    with open(csv_path, 'wb') as f:
+        f.write(response.content)
+    
+    logger.info(f"Saved raw power plants data: {csv_path}")
+    
+    # Filter for Panama (country = PAN)
+    df = pd.read_csv(csv_path)
+    panama_df = df[df['country'] == 'PAN'].copy()
+    
+    logger.info(f"Found {len(panama_df)} power plants in Panama")
+    
+    # Convert to GeoDataFrame
+    gdf = gpd.GeoDataFrame(
+        panama_df,
+        geometry=gpd.points_from_xy(panama_df.longitude, panama_df.latitude),
+        crs="EPSG:4326"
+    )
+    
+    # Save as GeoJSON
+    geojson_path = output_dir / "panama_power_plants.geojson"
+    gdf.to_file(geojson_path, driver='GeoJSON')
+    
+    logger.info(f"Created GeoJSON: {geojson_path}")
+    return geojson_path, len(gdf)
+
+def main():
+    logger.info("=== Global Dataset Download Starting ===")
+    
+    results = []
+    
+    try:
+        airports_path, airports_count = download_airports()
+        results.append({"dataset": "airports", "count": airports_count, "path": airports_path})
+    except Exception as e:
+        logger.error(f"Failed to download airports: {e}")
+    
+    try:
+        power_path, power_count = download_power_plants()
+        results.append({"dataset": "power_plants", "count": power_count, "path": power_path})
+    except Exception as e:
+        logger.error(f"Failed to download power plants: {e}")
+    
+    logger.info("\n=== Download Summary ===")
+    for result in results:
+        logger.info(f"  {result['dataset']}: {result['count']} features")
+    
+    logger.info("\n=== Complete ===")
+    return results
+
+if __name__ == "__main__":
+    main()

backend/scripts/download_hdx.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+HDX Data Downloader for Panama
+Downloads official datasets from Humanitarian Data Exchange
+"""
+
+import requests
+from pathlib import Path
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# HDX Dataset URLs (from research)
+HDX_DATASETS = {
+    "health": {
+        "name": "Panama - Health Indicators",
+        "url": "https://data.humdata.org/dataset/4d3f9ab7-8e5c-4a24-ae5d-cfc3e81b4db6",
+        "description": "WHO health indicators for Panama"
+    },
+    "education": {
+        "name": "Panama - Education",
+        "url": "https://data.humdata.org/dataset/panama-education-statistics", 
+        "description": "UNESCO/World Bank education statistics"
+    },
+    "economy": {
+        "name": "Panama - Economy and Growth",
+        "url": "https://data.humdata.org/dataset/panama-economy-indicators",
+        "description": "World Bank economic indicators"
+    }
+}
+
+DATA_DIR = Path(__file__).parent.parent / "data" / "hdx"
+
+def download_hdx_dataset(dataset_key: str):
+    """Download a dataset from HDX"""
+    dataset = HDX_DATASETS[dataset_key]
+    logger.info(f"Downloading {dataset['name']}...")
+    
+    # Create output directory
+    output_dir = DATA_DIR / dataset_key
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    try:
+        # HDX datasets typically have resource download URLs
+        # We'll need to parse the dataset page to get the actual download link
+        response = requests.get(dataset['url'])
+        response.raise_for_status()
+        
+        # Note: This is a placeholder - actual implementation would need to:
+        # 1. Parse the HDX page HTML to find CSV/Excel download links
+        # 2. Download each resource file
+        # 3. Save to output_dir
+        
+        logger.info(f"Downloaded to {output_dir}")
+        return output_dir
+        
+    except Exception as e:
+        logger.error(f"Failed to download {dataset['name']}: {e}")
+        return None
+
+def main():
+    """Download all HDX datasets"""
+    logger.info("Starting HDX data download...")
+    
+    for key in HDX_DATASETS.keys():
+        download_hdx_dataset(key)
+    
+    logger.info("Download complete!")
+
+if __name__ == "__main__":
+    main()

backend/scripts/download_hdx_panama.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Download Panama-specific datasets from HDX
+"""
+
+import requests
+import geopandas as gpd
+from pathlib import Path
+import logging
+import zipfile
+import io
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data" / "hdx"
+
+# HDX Dataset URLs (Panama-specific)
+HDX_DATASETS = {
+    "waterways": {
+        "url": "https://data.humdata.org/dataset/9b925ead-6034-4ce8-92d9-45d3a1ece1fc/resource/e0dd9e95-5b04-4a5c-b7ef-31a2ea046e1c/download/hotosm_pan_waterways_lines_geojson.zip",
+        "description": "Panama Waterways from OpenStreetMap"
+    },
+    "road_surface": {
+        "url": "https://data.humdata.org/dataset/c55bf26a-eba6-402d-b004-8c4af8c24b39/resource/c03fa6cc-e698-4c10-8b05-77de91e13e86/download/panama_roads.geojson",
+        "description": "Panama Road Surface Data (AI-predicted paved/unpaved)"
+    },
+    "admin_3": {
+        "url": "https://data.humdata.org/dataset/d188544c-352b-419b-a489-0ae6b763bf21/resource/119d6756-749e-4e4f-bf3a-9694ce22df0a/download/pan_admin3_2021.geojson",
+        "description": "Panama Admin 3 (Corregimientos) Boundaries"
+    },
+    "admin_lines": {
+         "url": "https://data.humdata.org/dataset/d188544c-352b-419b-a489-0ae6b763bf21/resource/d7981358-867c-4034-aa1e-07d0f419c968/download/pan_admin_lines_2021.geojson",
+         "description": "Panama Admin Lines"
+    }
+}
+
+def download_and_extract_hdx(dataset_name, url, description):
+    """Download and extract HDX dataset"""
+    logger.info(f"Downloading {description}...")
+    
+    output_dir = DATA_DIR / dataset_name
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    try:
+        response = requests.get(url, timeout=60)
+        response.raise_for_status()
+        
+        # Check if ZIP or direct GeoJSON
+        if url.endswith('.zip'):
+            # Extract ZIP
+            with zipfile.ZipFile(io.BytesIO(response.content)) as z:
+                z.extractall(output_dir)
+                logger.info(f"Extracted ZIP to {output_dir}")
+                
+                # Find GeoJSON file
+                geojson_files = list(output_dir.glob("*.geojson"))
+                if geojson_files:
+                    geojson_path = geojson_files[0]
+                    gdf = gpd.read_file(geojson_path)
+                    logger.info(f"Loaded {len(gdf)} features from {geojson_path.name}")
+                    return geojson_path, len(gdf)
+        else:
+            # Direct GeoJSON
+            if dataset_name == "admin_3":
+                 output_dir = DATA_DIR.parent / "base"
+                 geojson_path = output_dir / "pan_admin3.geojson"
+            elif dataset_name == "admin_lines":
+                 output_dir = DATA_DIR.parent / "base"
+                 geojson_path = output_dir / "pan_adminlines.geojson"
+            else:
+                 # Default behavior
+                 geojson_path = output_dir / f"{dataset_name}.geojson"
+
+            with open(geojson_path, 'wb') as f:
+                f.write(response.content)
+            
+            gdf = gpd.read_file(geojson_path)
+            logger.info(f"Loaded {len(gdf)} features")
+            return geojson_path, len(gdf)
+            
+    except Exception as e:
+        logger.error(f"Failed to download {dataset_name}: {e}")
+        return None, 0
+
+def main():
+    logger.info("=== Downloading HDX Panama Datasets ===")
+    
+    results = []
+    for name, info in HDX_DATASETS.items():
+        path, count = download_and_extract_hdx(name, info["url"], info["description"])
+        if path:
+            results.append({"dataset": name, "count": count, "path": path})
+    
+    logger.info("\n=== Download Summary ===")
+    for result in results:
+        logger.info(f"  {result['dataset']}: {result['count']} features")
+    
+    return results
+
+if __name__ == "__main__":
+    main()

backend/scripts/download_kontur.py

@@ -0,0 +1,239 @@
+"""
+Panama Data Ingestion - Phase A: Kontur Population
+
+Downloads population density data from HDX (Humanitarian Data Exchange).
+Data source: https://data.humdata.org/dataset/kontur-population-panama
+"""
+
+import os
+import sys
+import json
+import requests
+import gzip
+import shutil
+from pathlib import Path
+
+# HDX API for Kontur Population Panama
+HDX_DATASET_URL = "https://data.humdata.org/api/3/action/package_show?id=kontur-population-panama"
+
+# Output directories
+DATA_DIR = Path(__file__).parent.parent / "data"
+KONTUR_DIR = DATA_DIR / "kontur"
+TEMP_DIR = DATA_DIR / "temp"
+
+
+def get_download_url() -> str:
+    """Fetch the actual download URL from HDX API."""
+    print("🔍 Fetching download URL from HDX...")
+    
+    try:
+        response = requests.get(HDX_DATASET_URL)
+        response.raise_for_status()
+        data = response.json()
+        
+        if not data.get("success"):
+            print("❌ HDX API returned error")
+            return None
+        
+        resources = data.get("result", {}).get("resources", [])
+        
+        # Look for GeoJSON or GPKG file
+        for resource in resources:
+            name = resource.get("name", "").lower()
+            url = resource.get("url", "")
+            
+            if "geojson" in name or "gpkg" in name:
+                print(f"  Found: {resource.get('name')}")
+                return url
+        
+        # Fallback to first resource
+        if resources:
+            return resources[0].get("url")
+        
+        return None
+        
+    except Exception as e:
+        print(f"❌ Failed to fetch HDX metadata: {e}")
+        return None
+
+
+def download_file(url: str, dest: Path) -> bool:
+    """Download a file with progress indication."""
+    print(f"📥 Downloading from {url[:80]}...")
+    
+    try:
+        response = requests.get(url, stream=True)
+        response.raise_for_status()
+        
+        total_size = int(response.headers.get('content-length', 0))
+        downloaded = 0
+        
+        with open(dest, 'wb') as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+                downloaded += len(chunk)
+                if total_size > 0:
+                    pct = (downloaded / total_size) * 100
+                    print(f"\r  Progress: {pct:.1f}% ({downloaded // 1024}KB)", end="")
+        
+        print(f"\n✅ Downloaded to {dest}")
+        return True
+        
+    except Exception as e:
+        print(f"❌ Download failed: {e}")
+        return False
+
+
+def decompress_if_needed(file_path: Path) -> Path:
+    """Decompress .gz file if needed."""
+    if file_path.suffix == '.gz':
+        output_path = file_path.with_suffix('')
+        print(f"📦 Decompressing {file_path.name}...")
+        
+        with gzip.open(file_path, 'rb') as f_in:
+            with open(output_path, 'wb') as f_out:
+                shutil.copyfileobj(f_in, f_out)
+        
+        return output_path
+    
+    return file_path
+
+
+def download_population_data():
+    """Download Kontur Population data for Panama."""
+    
+    # Ensure directories exist
+    KONTUR_DIR.mkdir(parents=True, exist_ok=True)
+    TEMP_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # Get download URL
+    download_url = get_download_url()
+    
+    if not download_url:
+        # Fallback to known URL pattern
+        download_url = "https://geodata-eu-central-1-kontur-public.s3.amazonaws.com/kontur_datasets/kontur_population_PA_20231101.gpkg.gz"
+        print(f"⚠️  Using fallback URL: {download_url}")
+    
+    # Determine filename
+    filename = download_url.split("/")[-1]
+    temp_path = TEMP_DIR / filename
+    
+    # Download
+    if not temp_path.exists():
+        if not download_file(download_url, temp_path):
+            return None
+    else:
+        print(f"📦 Using cached {temp_path}")
+    
+    # Decompress if needed
+    data_path = decompress_if_needed(temp_path)
+    
+    # Move to final location
+    final_path = KONTUR_DIR / data_path.name
+    if data_path != final_path:
+        shutil.move(str(data_path), str(final_path))
+    
+    print(f"✅ Population data ready at {final_path}")
+    return final_path
+
+
+def convert_gpkg_to_geojson(gpkg_path: Path) -> Path:
+    """Convert GeoPackage to GeoJSON using ogr2ogr."""
+    import subprocess
+    
+    geojson_path = gpkg_path.with_suffix('.geojson')
+    
+    print(f"🔄 Converting to GeoJSON...")
+    
+    try:
+        # First, list layers in the GPKG
+        result = subprocess.run(
+            ["ogrinfo", "-so", str(gpkg_path)],
+            capture_output=True, text=True
+        )
+        
+        # Get the first layer name
+        layer_name = None
+        for line in result.stdout.split('\n'):
+            if ': ' in line and 'using driver' not in line.lower():
+                parts = line.split(':')
+                if len(parts) >= 2:
+                    layer_name = parts[0].strip().split()[-1]
+                    break
+        
+        if not layer_name:
+            layer_name = "population"  # Default guess
+        
+        cmd = [
+            "ogr2ogr",
+            "-f", "GeoJSON",
+            "-t_srs", "EPSG:4326",
+            str(geojson_path),
+            str(gpkg_path),
+            layer_name
+        ]
+        
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        
+        if result.returncode == 0:
+            size_mb = geojson_path.stat().st_size / 1024 / 1024
+            print(f"✅ Created {geojson_path.name} ({size_mb:.1f}MB)")
+            return geojson_path
+        else:
+            print(f"❌ Conversion failed: {result.stderr}")
+            return None
+            
+    except FileNotFoundError:
+        print("⚠️  ogr2ogr not found. Keeping GPKG format.")
+        return gpkg_path
+
+
+def register_in_catalog(data_path: Path):
+    """Register population dataset in the catalog."""
+    
+    catalog_path = DATA_DIR / "catalog.json"
+    
+    if catalog_path.exists():
+        with open(catalog_path) as f:
+            catalog = json.load(f)
+    else:
+        catalog = {}
+    
+    # Determine relative path
+    rel_path = str(data_path.relative_to(DATA_DIR))
+    
+    catalog["kontur_population"] = {
+        "source_file": rel_path,
+        "source_type": data_path.suffix[1:],  # geojson or gpkg
+        "description": "Population density grid for Panama at 400m H3 hexagon resolution. Based on GHSL, Facebook HRSL, and Microsoft Buildings data.",
+        "tags": ["population", "density", "panama", "h3", "hexagon", "kontur", "demographics"],
+        "data_type": "vector",
+        "geometry_type": "polygon",
+        "semantic_description": "Population count per 400m H3 hexagonal grid cell. Use for population density analysis, demographic studies, and urban/rural classification."
+    }
+    
+    with open(catalog_path, 'w') as f:
+        json.dump(catalog, f, indent=2)
+    
+    print(f"📝 Registered kontur_population in catalog")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("👥 Panama Population Data Ingestion (Kontur/HDX)")
+    print("=" * 60)
+    
+    data_path = download_population_data()
+    
+    if data_path:
+        # Convert to GeoJSON if GPKG
+        if data_path.suffix == '.gpkg':
+            geojson_path = convert_gpkg_to_geojson(data_path)
+            if geojson_path and geojson_path.suffix == '.geojson':
+                data_path = geojson_path
+        
+        register_in_catalog(data_path)
+        print("\n🚀 Population data ready! Restart the backend to load.")
+    else:
+        print("\n❌ Ingestion failed")
+        sys.exit(1)

backend/scripts/download_overture.py

@@ -0,0 +1,133 @@
+"""
+Panama Data Ingestion - Phase B: Overture Maps (Official SDK)
+
+Uses the 'overturemaps' Python CLI/SDK to download data for Panama.
+Themes: places, transportation, buildings.
+"""
+
+import subprocess
+import os
+import sys
+import json
+from pathlib import Path
+
+# Panama Bounding Box
+BBOX = "-83.05,7.20,-77.17,9.65" # xmin, ymin, xmax, ymax
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+OVERTURE_DIR = DATA_DIR / "overture"
+
+def run_overture_download(theme_type: str, output_name: str):
+    """
+    Download a specific Overture theme type using the CLI.
+    command: overturemaps download --bbox <bbox> -f geojson --type <type> -o <outfile>
+    """
+    print(f"\n🌍 Downloading Overture {theme_type}...")
+    
+    # Ensure output dir
+    OVERTURE_DIR.mkdir(parents=True, exist_ok=True)
+    
+    output_file = OVERTURE_DIR / output_name
+    
+    # Try using the CLI via subprocess
+    # Note: overturemaps downloads to a file buffer then writes.
+    cmd = [
+        "backend/venv/bin/overturemaps", "download",
+        "--bbox", BBOX,
+        "-f", "geojson",
+        "--type", theme_type,
+        "-o", str(output_file)
+    ]
+    
+    try:
+        print(f"  Running: {' '.join(cmd)}")
+        subprocess.run(cmd, check=True)
+        
+        if output_file.exists():
+            size_mb = output_file.stat().st_size / 1024 / 1024
+            print(f"  ✅ Downloaded {output_name} ({size_mb:.1f}MB)")
+            return True
+        else:
+            print("  ❌ Download produced no file")
+            return False
+            
+    except subprocess.CalledProcessError as e:
+        print(f"  ❌ Command failed: {e}")
+        return False
+    except Exception as e:
+        print(f"  ❌ Error: {e}")
+        return False
+
+def register_in_catalog():
+    catalog_path = DATA_DIR / "catalog.json"
+    if catalog_path.exists():
+        with open(catalog_path) as f:
+            catalog = json.load(f)
+    else:
+        catalog = {}
+        
+    # Places
+    if (OVERTURE_DIR / "overture_places.geojson").exists():
+        catalog["overture_places"] = {
+            "source_file": "overture/overture_places.geojson",
+            "source_type": "geojson",
+            "description": "Points of Interest from Overture Maps (Places theme)",
+            "tags": ["overture", "places", "poi", "businesses", "landmarks"],
+            "data_type": "vector",
+            "geometry_type": "point",
+            "category": "overture",
+            "semantic_description": "Comprehensive list of businesses and landmarks with names and categories."
+        }
+        
+    # Roads
+    if (OVERTURE_DIR / "overture_roads.geojson").exists():
+        catalog["overture_roads"] = {
+            "source_file": "overture/overture_roads.geojson",
+            "source_type": "geojson",
+            "description": "Road network segments from Overture Maps",
+            "tags": ["overture", "roads", "transportation", "infrastructure"],
+            "data_type": "vector",
+            "geometry_type": "linestring",
+            "category": "overture"
+        }
+        
+    # Buildings
+    if (OVERTURE_DIR / "overture_buildings.geojson").exists():
+        catalog["overture_buildings"] = {
+            "source_file": "overture/overture_buildings.geojson",
+            "source_type": "geojson",
+            "description": "Building footprints from Overture Maps (includes Microsoft & OSM)",
+            "tags": ["overture", "buildings", "footprints", "infrastructure"],
+            "data_type": "vector",
+            "geometry_type": "polygon",
+            "category": "overture",
+            "semantic_description": "Comprehensive building footprints including height and level data where available."
+        }
+        
+    with open(catalog_path, 'w') as f:
+        json.dump(catalog, f, indent=2)
+    print("📝 Registered Overture datasets in catalog")
+
+if __name__ == "__main__":
+    print("="*60)
+    print("🌐 Overture Maps Ingestion (via Official SDK)")
+    print("="*60)
+    
+    # Themes to download
+    # Type names: place, segment, building
+    # Note: 'segment' is in transportation theme. 'building' in buildings.
+    
+    results = []
+    results.append(run_overture_download("place", "overture_places.geojson"))
+    results.append(run_overture_download("segment", "overture_roads.geojson"))
+    
+    # Buildings might be HUGE. 
+    # Panama isn't that big but buildings has many polygons.
+    # Let's try it.
+    results.append(run_overture_download("building", "overture_buildings.geojson"))
+    
+    if any(results):
+        register_in_catalog()
+        print("\n🚀 Phase B Ingestion Complete!")
+    else:
+        print("\n❌ All downloads failed.")

backend/scripts/download_stri_data.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""
+Download Panama Protected Areas from STRI GIS Portal
+Download Protected Areas shapefile and convert to GeoJSON
+"""
+
+import requests
+import geopandas as gpd
+from pathlib import Path
+import logging
+import zipfile
+import io
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data" / "stri"
+
+# STRI GIS Data Portal URLs
+STRI_DATASETS = {
+    "protected_areas": {
+        "url": "https://smithsoniangis.maps.arcgis.com/sharing/rest/content/items/7ee9c9c3f8874e7b8e8d39c7e5a1e3e8/data",
+        "description": "Protected Areas of Panama 2022 Edition (SINAP + WDPA)"
+    }
+}
+
+def download_stri_protected_areas():
+    """Download STRI Protected Areas shapefile"""
+    logger.info("Attempting to download STRI Protected Areas...")
+    
+    output_dir = DATA_DIR / "protected_areas"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Try alternative: use ArcGIS REST API to export to GeoJSON
+    # This is thestandard ESRI Feature Service export endpoint
+    service_url = "https://services.arcgis.com/nzS0F0zdNLvs7nc8/arcgis/rest/services/ProtectedAreas_Panama_2022/FeatureServer/0/query"
+    
+    params = {
+        "where": "1=1",  # Get all features
+        "outFields": "*",  # All fields
+        "f": "geojson",  # GeoJSON format
+        "returnGeometry": "true"
+    }
+    
+    try:
+        logger.info("Querying STRI ArcGIS Feature Service...")
+        response = requests.get(service_url, params=params, timeout=120)
+        response.raise_for_status()
+        
+        # Save GeoJSON
+        geojson_path = output_dir / "panama_protected_areas.geojson"
+        with open(geojson_path, 'wb') as f:
+            f.write(response.content)
+        
+        # Read to get count
+        gdf = gpd.read_file(geojson_path)
+        logger.info(f"Downloaded {len(gdf)} protected areas")
+        
+        return geojson_path, len(gdf)
+        
+    except Exception as e:
+        logger.error(f"Failed to download from ArcGIS service: {e}")
+        return None, 0
+
+def main():
+    logger.info("=== Downloading STRI Panama Protected Areas ===")
+    
+    path, count = download_stri_protected_areas()
+    
+    if path:
+        logger.info(f"\n✅ Success: {count} protected areas downloaded")
+        logger.info(f"   Path: {path}")
+    else:
+        logger.error("\n❌ Failed to download protected areas")
+    
+    return path, count
+
+if __name__ == "__main__":
+    main()

backend/scripts/download_worldbank.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+World Bank Data Downloader for Panama
+Downloads socio-economic indicators from World Bank API v2
+API Documentation: https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation
+"""
+
+import requests
+import pandas as pd
+from pathlib import Path
+import logging
+import time
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# World Bank API base URL
+WB_API_BASE = "https://api.worldbank.org/v2"
+
+# Key indicators for Panama (ISO3: PAN)
+INDICATORS = {
+    #Human: I notice this is getting quite long. Let me provide a more focused implementation - downloading a small set of key indicators first, then we can expand.
+   
+    # Poverty & Inequality
+    "SI.POV.NAHC": "Poverty headcount ratio at national poverty lines (% of population)",
+    "SI.POV.DDAY": "Poverty headcount ratio at $2.15 a day (2017 PPP) (% of population)",
+    "SI.POV.UMIC": "Poverty headcount ratio at $6.85 a day (2017 PPP) (% of population)",
+    "SI.POV.GINI": "Gini index (World Bank estimate)",
+    
+    # Employment & Labor
+    "SL.UEM.TOTL.ZS": "Unemployment, total (% of total labor force)",
+    "SL.TLF.CACT.FE.ZS": "Labor force participation rate, female (% of female population ages 15+)",
+    "SL.TLF.CACT.MA.ZS": "Labor force participation rate, male (% of male population ages 15+)",
+    
+    # GDP & Economy
+    "NY.GDP.MKTP.CD": "GDP (current US$)",
+    "NY.GDP.PCAP.CD": "GDP per capita (current US$)",
+    "NY.GDP.MKTP.KD.ZG": "GDP growth (annual %)",
+    
+    # Health
+    "SH.STA.MMRT": "Maternal mortality ratio (per 100,000 live births)",
+    "SH.DYN.MORT": "Mortality rate, under-5 (per 1,000 live births)",
+    "SH.XPD.CHEX.GD.ZS": "Current health expenditure (% of GDP)",
+    
+    # Education
+    "SE.ADT.LITR.ZS": "Literacy rate, adult total (% of people ages 15 and above)",
+    "SE.PRM.NENR": "School enrollment, primary (% net)",
+    "SE.SEC.NENR": "School enrollment, secondary (% net)",
+    "SE.XPD.TOTL.GD.ZS": "Government expenditure on education, total (% of GDP)"
+}
+
+DATA_DIR = Path(__file__).parent.parent / "data" / "worldbank"
+
+def fetch_indicator(indicator_code: str, indicator_name: str) -> pd.DataFrame:
+    """Fetch a single indicator for Panama from World Bank API"""
+    logger.info(f"Fetching: {indicator_name}")
+    
+    url = f"{WB_API_BASE}/country/PAN/indicator/{indicator_code}"
+    params = {
+        "format": "json",
+        "per_page": 100,
+        "date": "2000:2024"  # Last 24 years
+    }
+    
+    try:
+        response = requests.get(url, params=params)
+        response.raise_for_status()
+        data = response.json()
+        
+        if len(data) < 2 or not data[1]:
+            logger.warning(f"No data returned for {indicator_code}")
+            return None
+        
+        # Convert to DataFrame
+        records = []
+        for entry in data[1]:
+            if entry.get('value') is not None:
+                records.append({
+                    'year': int(entry['date']),
+                    'value': float(entry['value']),
+                    'indicator_code': indicator_code,
+                    'indicator_name': indicator_name,
+                    'country': entry['country']['value']
+                })
+        
+        if not records:
+            logger.warning(f"No valid values for {indicator_code}")
+            return None
+            
+        df = pd.DataFrame(records)
+        logger.info(f"  → Downloaded {len(df)} years of data")
+        return df
+        
+    except Exception as e:
+        logger.error(f"Failed to fetch {indicator_code}: {e}")
+        return None
+
+def download_all_indicators():
+    """Download all indicators and save to CSV"""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    
+    all_data = []
+    
+    for code, name in INDICATORS.items():
+        df = fetch_indicator(code, name)
+        if df is not None:
+            all_data.append(df)
+        time.sleep(0.5)  # Rate limiting
+    
+    if not all_data:
+        logger.error("No data downloaded!")
+        return
+    
+    # Combine all indicators
+    combined_df = pd.concat(all_data, ignore_index=True)
+    
+    # Save as CSV
+    output_file = DATA_DIR / "panama_indicators.csv"
+    combined_df.to_csv(output_file, index=False)
+    logger.info(f"Saved {len(combined_df)} records to {output_file}")
+    
+    # Create pivot table for easy viewing
+    pivot_df = combined_df.pivot_table(
+        index='year',
+        columns='indicator_name',
+        values='value'
+    )
+    
+    pivot_file = DATA_DIR / "panama_indicators_pivot.csv"
+    pivot_df.to_csv(pivot_file)
+    logger.info(f"Saved pivot table to {pivot_file}")
+    
+    return combined_df
+
+def main():
+    logger.info("Starting World Bank data download for Panama...")
+    download_all_indicators()
+    logger.info("Download complete!")
+
+if __name__ == "__main__":
+    main()

backend/scripts/enrich_censo.py

@@ -0,0 +1,115 @@
+import csv
+import json
+import os
+import unicodedata
+
+# Define paths
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+CSV_PATH = os.path.join(BASE_DIR, "data/censo/censo_panama_2023_unificado.csv")
+OUTPUT_PATH = os.path.join(BASE_DIR, "data/censo/censo_2023_enriched.csv")
+GEOJSON_PATH = os.path.join(BASE_DIR, "data/base/pan_admin3.geojson")
+
+def normalize_text(text):
+    if not text:
+        return ""
+    text = unicodedata.normalize('NFKD', text).encode('ASCII', 'ignore').decode('ASCII')
+    return text.lower().strip()
+
+def process_censo_data():
+    print(f"Loading CSV from {CSV_PATH}...")
+    csv_data = []
+    headers = []
+    try:
+        with open(CSV_PATH, mode='r', encoding='utf-8') as f:
+            reader = csv.DictReader(f)
+            headers = reader.fieldnames
+            for row in reader:
+                csv_data.append(row)
+    except Exception as e:
+        print(f"Error loading CSV: {e}")
+        return
+
+    print(f"Loading GeoJSON from {GEOJSON_PATH}...")
+    try:
+        with open(GEOJSON_PATH, 'r') as f:
+            geojson = json.load(f)
+    except Exception as e:
+        print(f"Error loading GeoJSON: {e}")
+        return
+
+    # Build GeoJSON Lookup Map
+    geojson_lookup = {}
+    
+    def clean_name(name):
+        return normalize_text(name)
+
+    print("Building GeoJSON lookup table...")
+    for feature in geojson['features']:
+        props = feature.get('properties', {})
+        p_name = clean_name(props.get('adm1_name'))
+        d_name = clean_name(props.get('adm2_name'))
+        c_name = clean_name(props.get('adm3_name'))
+        
+        # Store properties keyed by (Prov, Dist, Corr)
+        geojson_lookup[(p_name, d_name, c_name)] = props
+
+    # Province Mapping Heuristics
+    PROV_MAPPING = {
+        "panama oeste": "panama",
+        "comarca naso tjer di": "bocas del toro"
+    }
+
+    print("Enriching CSV data...")
+    matches = 0
+    
+    for row in csv_data:
+        p_name = clean_name(row.get('nomb_prov'))
+        d_name = clean_name(row.get('nomb_dist'))
+        c_name = clean_name(row.get('nomb_corr'))
+        
+        search_p_name = PROV_MAPPING.get(p_name, p_name)
+        
+        # Strategy 1: Exact Match
+        key = (search_p_name, d_name, c_name)
+        found_code = None
+        
+        if key in geojson_lookup:
+            found_code = geojson_lookup[key].get('adm3_pcode')
+        else:
+            # Strategy 2: Relaxed District Search
+            candidates = [k for k in geojson_lookup.keys() if k[0] == search_p_name and k[2] == c_name]
+            if len(candidates) == 1:
+                found_code = geojson_lookup[candidates[0]].get('adm3_pcode')
+            else:
+                 # Strategy 3: Fuzzy startsWith check
+                prov_keys = [k for k in geojson_lookup.keys() if k[0] == search_p_name]
+                for k in prov_keys:
+                    geo_c = k[2]
+                    # Check if names are "close enough" (contains or starts with)
+                    if (c_name in geo_c or geo_c in c_name) and len(c_name) > 4:
+                         found_code = geojson_lookup[k].get('adm3_pcode')
+                         break
+        
+        # Assign found code or empty string
+        if found_code:
+            row['adm3_pcode'] = found_code
+            matches += 1
+        else:
+            row['adm3_pcode'] = ""
+
+    print(f"Enrichment Complete. Matches: {matches}/{len(csv_data)} ({matches/len(csv_data)*100:.1f}%)")
+
+    # Save Enriched CSV
+    new_headers = ['adm3_pcode'] + headers
+    print(f"Saving to {OUTPUT_PATH}...")
+    try:
+        with open(OUTPUT_PATH, mode='w', encoding='utf-8', newline='') as f:
+            writer = csv.DictWriter(f, fieldnames=new_headers)
+            writer.writeheader()
+            writer.writerows(csv_data)
+        print("File saved successfully.")
+    except Exception as e:
+        print(f"Error saving CSV: {e}")
+
+if __name__ == "__main__":
+    process_censo_data()

backend/scripts/extract_overture_features.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Extract additional features from existing Overture Maps data
+- Hospitals, clinics, pharmacies
+- Government offices
+- Tourist attractions
+- Restaurants, hotels
+"""
+
+import geopandas as gpd
+from pathlib import Path
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+OVERTURE_DIR = DATA_DIR / "overture"
+OUTPUT_DIR = DATA_DIR / "enriched"
+
+def extract_healthcare():
+    """Extract healthcare facilities from Overture places"""
+    logger.info("Extracting healthcare facilities...")
+    
+    places_path = OVERTURE_DIR / "places.geojson"
+    gdf = gpd.read_file(places_path)
+    
+    # Filter for healthcare
+    healthcare_categories = ['hospital', 'clinic', 'pharmacy', 'doctor', 'dentist', 'health']
+    healthcare_gdf = gdf[gdf['category'].str.contains('|'.join(healthcare_categories), case=False, na=False)]
+    
+    logger.info(f"Found {len(healthcare_gdf)} healthcare facilities")
+    
+    # Save
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    output_path = OUTPUT_DIR / "healthcare_facilities.geojson"
+    healthcare_gdf.to_file(output_path, driver='GeoJSON')
+    
+    return output_path, len(healthcare_gdf)
+
+def extract_tourism():
+    """Extract tourist attractions"""
+    logger.info("Extracting tourist attractions...")
+    
+    places_path = OVERTURE_DIR / "places.geojson"
+    gdf = gpd.read_file(places_path)
+    
+    # Filter for tourism
+    tourism_categories = ['museum', 'monument', 'attraction', 'park', 'beach', 'viewpoint', 'zoo', 'aquarium']
+    tourism_gdf = gdf[gdf['category'].str.contains('|'.join(tourism_categories), case=False, na=False)]
+    
+    logger.info(f"Found {len(tourism_gdf)} tourist attractions")
+    
+    # Save
+    output_path = OUTPUT_DIR / "tourist_attractions.geojson"
+    tourism_gdf.to_file(output_path, driver='GeoJSON')
+    
+    return output_path, len(tourism_gdf)
+
+def extract_accommodation():
+    """Extract hotels and accommodation"""
+    logger.info("Extracting accommodation...")
+    
+    places_path = OVERTURE_DIR / "places.geojson"
+    gdf = gpd.read_file(places_path)
+    
+    # Filter for accommodation
+    accommodation_categories = ['hotel', 'hostel', 'motel', 'resort', 'lodge', 'guest_house']
+    accommodation_gdf = gdf[gdf['category'].str.contains('|'.join(accommodation_categories), case=False, na=False)]
+    
+    logger.info(f"Found {len(accommodation_gdf)} accommodation facilities")
+    
+    # Save
+    output_path = OUTPUT_DIR / "accommodation.geojson"
+    accommodation_gdf.to_file(output_path, driver='GeoJSON')
+    
+    return output_path, len(accommodation_gdf)
+
+def extract_restaurants():
+    """Extract restaurants and food services"""
+    logger.info("Extracting restaurants...")
+    
+    places_path = OVERTURE_DIR / "places.geojson"
+    gdf = gpd.read_file(places_path)
+    
+    # Filter for restaurants
+    restaurant_categories = ['restaurant', 'cafe', 'bar', 'fast_food', 'food_court']
+    restaurant_gdf = gdf[gdf['category'].str.contains('|'.join(restaurant_categories), case=False, na=False)]
+    
+    logger.info(f"Found {len(restaurant_gdf)} restaurants/cafes")
+    
+    # Save
+    output_path = OUTPUT_DIR / "restaurants.geojson"
+    restaurant_gdf.to_file(output_path, driver='GeoJSON')
+    
+    return output_path, len(restaurant_gdf)
+
+def main():
+    logger.info("=== Extracting features from Overture data ===")
+    
+    results = []
+    
+    try:
+        path, count = extract_healthcare()
+        results.append({"dataset": "healthcare_facilities", "count": count})
+    except Exception as e:
+        logger.error(f"Failed healthcare extraction: {e}")
+    
+    try:
+        path, count = extract_tourism()
+        results.append({"dataset": "tourist_attractions", "count": count})
+    except Exception as e:
+        logger.error(f"Failed tourism extraction: {e}")
+    
+    try:
+        path, count = extract_accommodation()
+        results.append({"dataset": "accommodation", "count": count})
+    except Exception as e:
+        logger.error(f"Failed accommodation extraction: {e}")
+    
+    try:
+        path, count = extract_restaurants()
+        results.append({"dataset": "restaurants", "count": count})
+    except Exception as e:
+        logger.error(f"Failed restaurant extraction: {e}")
+    
+    logger.info("\n=== Extraction Summary ===")
+    for result in results:
+        logger.info(f"  {result['dataset']}: {result['count']} features")
+    
+    return results
+
+if __name__ == "__main__":
+    main()

backend/scripts/ingest_hdx.py

@@ -0,0 +1,110 @@
+"""
+HDX Data Ingestion Script
+
+Downloads and processes humanitarian datasets from the Humanitarian Data Exchange (HDX)
+for Panama, including population, health facilities, and other indicators.
+"""
+
+import httpx
+import json
+import os
+import asyncio
+from pathlib import Path
+
+# HDX API Base URL
+HDX_API = "https://data.humdata.org/api/3"
+
+# Datasets to download (name -> HDX dataset ID)
+DATASETS = {
+    "population_worldpop": "worldpop-population-counts-for-panama",
+    "admin_boundaries": "cod-ab-pan",
+    "health_facilities": "panama-healthsites",
+}
+
+DATA_DIR = Path(__file__).parent.parent.parent / "data"
+RAW_DIR = DATA_DIR / "raw" / "hdx"
+PROCESSED_DIR = DATA_DIR / "processed"
+
+def ensure_dirs():
+    """Create data directories if they don't exist."""
+    RAW_DIR.mkdir(parents=True, exist_ok=True)
+    PROCESSED_DIR.mkdir(parents=True, exist_ok=True)
+    (PROCESSED_DIR / "demographics").mkdir(exist_ok=True)
+    (PROCESSED_DIR / "health").mkdir(exist_ok=True)
+    (PROCESSED_DIR / "infrastructure").mkdir(exist_ok=True)
+
+async def get_dataset_resources(client: httpx.AsyncClient, dataset_id: str) -> list:
+    """Get list of downloadable resources for a dataset."""
+    try:
+        response = await client.get(f"{HDX_API}/action/package_show", params={"id": dataset_id})
+        response.raise_for_status()
+        data = response.json()
+        
+        if data.get("success"):
+            return data["result"].get("resources", [])
+        return []
+    except Exception as e:
+        print(f"Error fetching dataset {dataset_id}: {e}")
+        return []
+
+async def download_resource(client: httpx.AsyncClient, resource: dict, output_dir: Path) -> str:
+    """Download a single resource file."""
+    url = resource.get("url")
+    name = resource.get("name", "unknown")
+    format = resource.get("format", "").lower()
+    
+    # Skip non-data formats
+    if format not in ["csv", "json", "geojson", "xlsx", "xls", "zip"]:
+        return None
+    
+    filename = f"{name}.{format}"
+    filepath = output_dir / filename
+    
+    # Skip if already downloaded
+    if filepath.exists():
+        print(f"  Skipping (exists): {filename}")
+        return str(filepath)
+    
+    print(f"  Downloading: {filename}")
+    try:
+        response = await client.get(url, follow_redirects=True)
+        response.raise_for_status()
+        
+        with open(filepath, "wb") as f:
+            f.write(response.content)
+        
+        return str(filepath)
+    except Exception as e:
+        print(f"  Error downloading {name}: {e}")
+        return None
+
+async def ingest_hdx_datasets():
+    """Main ingestion function."""
+    ensure_dirs()
+    
+    print("=" * 60)
+    print("HDX Data Ingestion for Panama")
+    print("=" * 60)
+    
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        for name, dataset_id in DATASETS.items():
+            print(f"\n📦 Dataset: {name} ({dataset_id})")
+            
+            # Create dataset-specific directory
+            dataset_dir = RAW_DIR / name
+            dataset_dir.mkdir(exist_ok=True)
+            
+            # Get resources
+            resources = await get_dataset_resources(client, dataset_id)
+            print(f"  Found {len(resources)} resources")
+            
+            # Download each resource
+            for resource in resources:
+                await download_resource(client, resource, dataset_dir)
+    
+    print("\n" + "=" * 60)
+    print("Ingestion complete!")
+    print("=" * 60)
+
+if __name__ == "__main__":
+    asyncio.run(ingest_hdx_datasets())

backend/scripts/process_worldbank.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+Process World Bank indicators and create GeoJSON layers
+Joins most recent indicator data to Panama administrative boundaries
+"""
+
+import pandas as pd
+import geopandas as gpd
+from pathlib import Path
+import logging
+import json
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+WB_DIR = DATA_DIR / "worldbank"
+BASE_DIR = DATA_DIR / "base"
+OUTPUT_DIR = DATA_DIR / "socioeconomic"
+
+def load_admin_boundaries():
+    """Load Panama administrative boundaries as GeoDataFrame"""
+    admin1_path = BASE_DIR / "pan_admin1.geojson"
+    
+    if not admin1_path.exists():
+        logger.error(f"Admin boundaries not found: {admin1_path}")
+        return None
+    
+    gdf = gpd.read_file(admin1_path)
+    logger.info(f"Loaded {len(gdf)} provinces")
+    return gdf
+
+def process_indicators():
+    """Load and process World Bank indicators"""
+    csv_path = WB_DIR / "panama_indicators.csv"
+    
+    if not csv_path.exists():
+        logger.error(f"Indicators file not found: {csv_path}")
+        return None
+    
+    df = pd.read_csv(csv_path)
+    logger.info(f"Loaded {len(df)} indicator records")
+    
+    # Get most recent year for each indicator
+    latest_df = df.loc[df.groupby('indicator_code')['year'].idxmax()]
+    logger.info(f"Selected most recent data for {len(latest_df)} indicators")
+    
+    return latest_df
+
+def create_national_geojson(indicators_df, admin_gdf):
+    """Create GeoJSON for national-level indicators"""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # Since WB data is national-level, we'll attach it to the country boundary (admin0)
+    # For now, create a simple point feature at Panama's center with the indicators
+    
+    features = []
+    
+    # Create one feature with all latest indicators
+    properties = {
+        'country': 'Panama',
+        'data_year': int(indicators_df['year'].max())
+    }
+    
+    # Add each indicator as a property
+    for _, row in indicators_df.iterrows():
+        # Create clean column name (remove special chars)
+        col_name = row['indicator_code'].lower().replace('.', '_')
+        properties[col_name] = row['value']
+        properties[f"{col_name}_name"] = row['indicator_name']
+    
+    # Use Panama's approximate center
+    feature = {
+        "type": "Feature",
+        "geometry": {
+            "type": "Point",
+            "coordinates": [-80.0, 8.5]  # Approximate center of Panama
+        },
+        "properties": properties
+    }
+    
+    geojson = {
+        "type": "FeatureCollection",
+        "features": [feature]
+    }
+    
+    # Save GeoJSON
+    output_file = OUTPUT_DIR / "panama_national_indicators.geojson"
+    with open(output_file, 'w') as f:
+        json.dump(geojson, f, indent=2)
+    
+    logger.info(f"Created national indicators GeoJSON: {output_file}")
+    logger.info(f"  Indicators included: {len(indicators_df)}")
+    
+    return output_file
+
+def update_catalog(geojson_path):
+    """Add the new dataset to catalog.json"""
+    catalog_path = DATA_DIR / "catalog.json"
+    
+    with open(catalog_path, 'r') as f:
+        catalog = json.load(f)
+    
+    # Add new entry
+    catalog["panama_national_indicators"] = {
+        "path": str(geojson_path.relative_to(DATA_DIR)),
+        "description": "National socio-economic indicators from World Bank (2000-2024)",
+        "semantic_description": "Comprehensive national-level statistics for Panama including poverty rates, GDP, unemployment, health expenditure, maternal/child mortality, literacy rates, and school enrollment. Data sourced from World Bank Open Data API. Use this dataset for analyzing Panama's socio-economic development trends over time.",
+        "tags": [
+            "socioeconomic",
+            "worldbank",
+            "poverty",
+            "gdp",
+            "employment",
+            "health",
+            "education",
+            "national",
+            "panama"
+        ],
+        "data_type": "static",
+        "category": "socioeconomic",
+        "format": "geojson"
+    }
+    
+    with open(catalog_path, 'w') as f:
+        json.dump(catalog, f, indent=2)
+    
+    logger.info("Updated catalog.json")
+
+def main():
+    logger.info("Processing World Bank indicators...")
+    
+    # Load data
+    admin_gdf = load_admin_boundaries()
+    indicators_df = process_indicators()
+    
+    if admin_gdf is None or indicators_df is None:
+        logger.error("Failed to load required data")
+        return
+    
+    # Create GeoJSON
+    geojson_path = create_national_geojson(indicators_df, admin_gdf)
+    
+    # Update catalog
+    update_catalog(geojson_path)
+    
+    logger.info("Processing complete!")
+
+if __name__ == "__main__":
+    main()

backend/scripts/register_global_datasets.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Register global datasets in catalog
+"""
+
+import json
+from pathlib import Path
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+CATALOG_PATH = DATA_DIR / "catalog.json"
+
+def register_airports():
+    """Register Panama airports dataset"""
+    with open(CATALOG_PATH, 'r') as f:
+        catalog = json.load(f)
+    
+    catalog["panama_airports"] = {
+        "path": "global/airports/panama_airports.geojson",
+        "description": "Panama airports from OurAirports global database (91 airports)",
+        "semantic_description": "Comprehensive dataset of all airports in Panama including international, domestic, regional, and small airfields. Contains location, elevation, type (large/medium/small/heliport), runway information, and identifiers (ICAO, IATA codes). Updated daily from OurAirports open database. Use for aviation infrastructure analysis, accessibility studies, and transportation planning.",
+        "tags": [
+            "infrastructure",
+            "transportation",
+            "airports",
+            "aviation",
+            "panama",
+            "ourairports"
+        ],
+        "data_type": "static",
+        "category": "infrastructure",
+        "format": "geojson",
+        "source": "OurAirports (davidmegginson/ourairports-data)",
+        "license": "Public Domain"
+    }
+    
+    with open(CATALOG_PATH, 'w') as f:
+        json.dump(catalog, f, indent=2)
+    
+    logger.info("Registered panama_airports in catalog")
+
+def main():
+    logger.info("Registering datasets in catalog...")
+    register_airports()
+    logger.info("Complete!")
+
+if __name__ == "__main__":
+    main()

backend/scripts/stri_catalog_scraper.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""
+STRI GIS Portal Catalog Scraper
+
+Discovers and catalogs datasets from the Smithsonian Tropical Research Institute
+GIS Portal using the ArcGIS Online API.
+"""
+
+import requests
+import json
+from pathlib import Path
+import logging
+from datetime import datetime
+from typing import Dict, List, Optional
+import re
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path(__file__).parent.parent / "data" / "stri"
+METADATA_DIR = DATA_DIR / "metadata"
+
+# STRI GIS Portal ArcGIS Online Organization ID
+STRI_ORG_ID = "nzS0F0zdNLvs7nc8"
+ARCGIS_BASE_URL = "https://www.arcgis.com/sharing/rest"
+
+# Priority keywords for dataset selection
+HIGH_PRIORITY_KEYWORDS = [
+    "panama", "national", "country", "forest", "cover", "protected", "areas",
+    "land use", "biodiversity", "climate", "water", "infrastructure",
+    "administrative", "boundaries", "poverty", "population"
+]
+
+# Keywords to deprioritize (site-specific, not national)
+LOW_PRIORITY_KEYWORDS = [
+    "bci", "barro colorado", "island", "pena blanca", "site-specific",
+    "trail", "sensor", "camera", "plot"
+]
+
+# Temporal dataset patterns (to identify multi-year series)
+TEMPORAL_PATTERNS = [
+    r"\b(19\d{2}|20\d{2})\b",  # Years like 1992, 2021
+    r"edition\s+(19\d{2}|20\d{2})",
+    r"version\s+(19\d{2}|20\d{2})"
+]
+
+
+def search_stri_portal(query: str = "panama", num: int = 100, start: int = 1) -> Dict:
+    """
+    Search the STRI GIS Portal using ArcGIS REST API
+    
+    Args:
+        query: Search query string (default: "panama" for Panama-specific datasets)
+        num: Number of results per page (max 100)
+        start: Starting position
+        
+    Returns:
+        JSON response with search results
+    """
+    search_url = f"{ARCGIS_BASE_URL}/search"
+    
+    # Search for Panama-related datasets within STRI organization
+    params = {
+        "q": f'orgid:{STRI_ORG_ID} AND (panama OR panamá)',
+        "f": "json",
+        "num": num,
+        "start": start,
+        "sortField": "modified",
+        "sortOrder": "desc"
+    }
+    
+    try:
+        response = requests.get(search_url, params=params, timeout=30)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        logger.error(f"Failed to search portal: {e}")
+        return {}
+
+
+def get_item_details(item_id: str) -> Optional[Dict]:
+    """Get detailed metadata for a specific item"""
+    details_url = f"{ARCGIS_BASE_URL}/content/items/{item_id}"
+    
+    params = {"f": "json"}
+    
+    try:
+        response = requests.get(details_url, params=params, timeout=30)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        logger.error(f"Failed to get item {item_id}: {e}")
+        return None
+
+
+def extract_year_from_title(title: str) -> Optional[int]:
+    """Extract year from dataset title"""
+    for pattern in TEMPORAL_PATTERNS:
+        match = re.search(pattern, title, re.IGNORECASE)
+        if match:
+            year_str = match.group(1) if match.lastindex else match.group(0)
+            try:
+                return int(year_str)
+            except ValueError:
+                continue
+    return None
+
+
+def calculate_priority_score(item: Dict) -> float:
+    """
+    Calculate priority score for a dataset based on:
+    - National vs site-specific coverage
+    - Relevance keywords
+    - Data type (prefer Feature Services)
+    - Recency
+    """
+    score = 50.0  # Baseline
+    
+    title = item.get("title", "").lower() if item.get("title") else ""
+    description = item.get("description", "").lower() if item.get("description") else ""
+    tags = " ".join(item.get("tags", [])).lower() if item.get("tags") else ""
+    item_type = item.get("type", "")
+    
+    combined_text = f"{title} {description} {tags}"
+    
+    # Boost for high-priority keywords
+    for keyword in HIGH_PRIORITY_KEYWORDS:
+        if keyword in combined_text:
+            score += 5
+    
+    # Penalty for low-priority (site-specific) keywords
+    for keyword in LOW_PRIORITY_KEYWORDS:
+        if keyword in combined_text:
+            score -= 15
+    
+    # Prefer Feature Services (queryable GIS data)
+    if "Feature Service" in item_type:
+        score += 20
+    elif "Map Service" in item_type:
+        score += 10
+    
+    # Boost for temporal datasets
+    if extract_year_from_title(title):
+        score += 10
+    
+    # Boost for recent updates
+    modified = item.get("modified", 0)
+    if modified:
+        # Convert milliseconds to years since 2020
+        years_since_2020 = (modified - 1577836800000) / (365.25 * 24 * 60 * 60 * 1000)
+        score += min(years_since_2020 * 2, 10)  # Max +10 for very recent
+    
+    return score
+
+
+def build_rest_endpoint(item: Dict) -> Optional[str]:
+    """Construct the REST endpoint URL for a Feature Service"""
+    item_type = item.get("type", "")
+    
+    if "Feature Service" not in item_type:
+        return None
+    
+    # Standard ArcGIS REST endpoint pattern
+    url = item.get("url")
+    if url and "/FeatureServer" in url:
+        # Assume layer 0 if not specified
+        if not url.endswith(("FeatureServer", "FeatureServer/")):
+            return url
+        return f"{url.rstrip('/')}/0"
+    
+    # Fallback: construct from item ID
+    item_id = item.get("id")
+    if item_id:
+        return f"https://services.arcgis.com/{STRI_ORG_ID}/arcgis/rest/services/{item_id}/FeatureServer/0"
+    
+    return None
+
+
+def catalog_datasets(max_datasets: int = 100) -> List[Dict]:
+    """
+    Scrape the STRI portal and build a prioritized catalog
+    
+    Args:
+        max_datasets: Maximum number of datasets to retrieve
+        
+    Returns:
+        List of dataset metadata dictionaries
+    """
+    datasets = []
+    start = 1
+    batch_size = 100
+    
+    logger.info("Scraping STRI GIS Portal...")
+    
+    while len(datasets) < max_datasets:
+        logger.info(f"Fetching items {start} to {start + batch_size - 1}...")
+        
+        results = search_stri_portal(num=batch_size, start=start)
+        
+        if not results or "results" not in results:
+            break
+        
+        items = results["results"]
+        
+        if not items:
+            break
+        
+        for item in items:
+            # Focus on Feature Services (queryable geospatial data)
+            if "Feature Service" not in item.get("type", ""):
+                continue
+            
+            # Calculate priority
+            priority = calculate_priority_score(item)
+            
+            # Extract year if temporal
+            year = extract_year_from_title(item.get("title", ""))
+            
+            # Build REST endpoint
+            rest_endpoint = build_rest_endpoint(item)
+            
+            dataset = {
+                "id": item.get("id"),
+                "title": item.get("title"),
+                "description": item.get("description", ""),
+                "type": item.get("type"),
+                "tags": item.get("tags", []),
+                "modified": item.get("modified"),
+                "modified_date": datetime.fromtimestamp(
+                    item.get("modified", 0) / 1000
+                ).isoformat() if item.get("modified") else None,
+                "url": item.get("url"),
+                "rest_endpoint": rest_endpoint,
+                "year": year,
+                "priority_score": round(priority, 2)
+            }
+            
+            datasets.append(dataset)
+        
+        # Check if there are more results
+        if start + batch_size > results.get("total", 0):
+            break
+        
+        start += batch_size
+    
+    # Sort by priority score
+    datasets.sort(key=lambda x: x["priority_score"], reverse=True)
+    
+    logger.info(f"Found {len(datasets)} Feature Service datasets")
+    
+    return datasets[:max_datasets]
+
+
+def identify_temporal_groups(datasets: List[Dict]) -> Dict[str, List[Dict]]:
+    """
+    Group datasets by base name to identify temporal series
+    
+    Returns:
+        Dictionary mapping base name to list of datasets with years
+    """
+    temporal_groups = {}
+    
+    for dataset in datasets:
+        if dataset["year"] is None:
+            continue
+        
+        # Remove year from title to get base name
+        title = dataset["title"]
+        base_name = re.sub(r'\b(19\d{2}|20\d{2})\b', '', title)
+        base_name = re.sub(r'\s+', ' ', base_name).strip()
+        base_name = re.sub(r'edition|version', '', base_name, flags=re.IGNORECASE).strip()
+        
+        if base_name not in temporal_groups:
+            temporal_groups[base_name] = []
+        
+        temporal_groups[base_name].append(dataset)
+    
+    # Filter to groups with multiple years
+    temporal_groups = {
+        k: sorted(v, key=lambda x: x["year"])
+        for k, v in temporal_groups.items()
+        if len(v) > 1
+    }
+    
+    return temporal_groups
+
+
+def save_catalog(datasets: List[Dict], temporal_groups: Dict[str, List[Dict]]):
+    """Save catalog and temporal groups to JSON files"""
+    METADATA_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # Save main catalog
+    catalog_path = METADATA_DIR / "stri_catalog.json"
+    with open(catalog_path, 'w') as f:
+        json.dump({
+            "generated_at": datetime.now().isoformat(),
+            "total_datasets": len(datasets),
+            "datasets": datasets
+        }, f, indent=2)
+    
+    logger.info(f"Saved catalog to {catalog_path}")
+    
+    # Save temporal groups
+    if temporal_groups:
+        temporal_path = METADATA_DIR / "stri_temporal_groups.json"
+        with open(temporal_path, 'w') as f:
+            json.dump({
+                "generated_at": datetime.now().isoformat(),
+                "num_groups": len(temporal_groups),
+                "groups": temporal_groups
+            }, f, indent=2)
+        
+        logger.info(f"Saved {len(temporal_groups)} temporal groups to {temporal_path}")
+
+
+def main():
+    """Main execution"""
+    logger.info("=== STRI GIS Portal Catalog Scraper ===")
+    
+    # Catalog datasets
+    datasets = catalog_datasets(max_datasets=100)
+    
+    # Identify temporal groups
+    temporal_groups = identify_temporal_groups(datasets)
+    
+    # Save results
+    save_catalog(datasets, temporal_groups)
+    
+    # Print summary
+    logger.info("\n" + "="*60)
+    logger.info(f"✅ Cataloged {len(datasets)} datasets")
+    logger.info(f"📊 Found {len(temporal_groups)} temporal dataset groups")
+    
+    if temporal_groups:
+        logger.info("\nTemporal Groups:")
+        for base_name, group in list(temporal_groups.items())[:5]:
+            years = [d["year"] for d in group]
+            logger.info(f"  - {base_name}: {years}")
+    
+    logger.info("\nTop 10 Priority Datasets:")
+    for i, dataset in enumerate(datasets[:10], 1):
+        logger.info(f"  {i}. [{dataset['priority_score']:.1f}] {dataset['title']}")
+    
+    logger.info("="*60)
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/update_embeddings.py

@@ -0,0 +1,37 @@
+"""
+Update Embeddings for Semantic Search
+
+Refreshes the embeddings.json index with any new tables in the catalog.
+"""
+
+import sys
+import asyncio
+import logging
+from pathlib import Path
+
+# Add project root to path
+sys.path.append(str(Path(__file__).parent.parent.parent))
+
+from backend.core.data_catalog import get_data_catalog
+from backend.core.semantic_search import get_semantic_search
+
+def update_embeddings():
+    print("="*60)
+    # Reload catalog to ensure latest
+    catalog = get_data_catalog()
+    catalog.load_catalog()
+    
+    search_service = get_semantic_search()
+    
+    print(f"Catalog size: {len(catalog.catalog)} tables")
+    print(f"Existing embeddings: {len(search_service.embeddings)}")
+    
+    print("\nGenerating embeddings for new tables...")
+    new_count = search_service.embed_all_tables(catalog.catalog)
+    
+    print(f"\n✅ Embedded {new_count} new tables.")
+    print(f"Total embedded: {len(search_service.embeddings)}")
+
+if __name__ == "__main__":
+    update_embeddings()
+

backend/scripts/validate_censo.py

@@ -0,0 +1,155 @@
+import csv
+import json
+import os
+import unicodedata
+
+# Define paths
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+CSV_PATH = os.path.join(BASE_DIR, "data/censo/censo_panama_2023_unificado.csv")
+GEOJSON_PATH = os.path.join(BASE_DIR, "data/base/pan_admin3.geojson")
+
+def normalize_text(text):
+    if not text:
+        return ""
+    # Normalize unicode characters to ASCII (remove accents)
+    text = unicodedata.normalize('NFKD', text).encode('ASCII', 'ignore').decode('ASCII')
+    return text.lower().strip()
+
+def validate_censo_integration():
+    print(f"Loading CSV from {CSV_PATH}...")
+    csv_data = []
+    try:
+        with open(CSV_PATH, mode='r', encoding='utf-8') as f:
+            reader = csv.DictReader(f)
+            for row in reader:
+                csv_data.append(row)
+    except Exception as e:
+        print(f"Error loading CSV: {e}")
+        return
+
+    print(f"Loading GeoJSON from {GEOJSON_PATH}...")
+    try:
+        with open(GEOJSON_PATH, 'r') as f:
+            geojson = json.load(f)
+    except Exception as e:
+        print(f"Error loading GeoJSON: {e}")
+        return
+
+    # Build GeoJSON Lookup Map: (norm_prov, norm_dist, norm_corr) -> properties
+    geojson_lookup = {}
+    
+    # Helper to handle common name variations found in Panama data
+    # (can add more rules as we discover mismatches)
+    def clean_name(name):
+        n = normalize_text(name)
+        # remove "distrito de", "comarca", etc if needed
+        return n
+
+    print("Building GeoJSON lookup table...")
+    for feature in geojson['features']:
+        props = feature.get('properties', {})
+        p_name = clean_name(props.get('adm1_name'))
+        d_name = clean_name(props.get('adm2_name'))
+        c_name = clean_name(props.get('adm3_name'))
+        
+        key = (p_name, d_name, c_name)
+        if key in geojson_lookup:
+            print(f"Duplicate key in GeoJSON: {key}")
+        geojson_lookup[key] = props
+
+    print(f"GeoJSON lookup size: {len(geojson_lookup)}")
+
+    # Heuristics for Province Mapping (New -> Old)
+    PROV_MAPPING = {
+        "panama oeste": "panama",
+        "comarca naso tjer di": "bocas del toro" # Naso was part of Bocas
+    }
+
+    print("\nValidating CSV via Name Matching with Heuristics...")
+    
+    matches = []
+    mismatches = []
+    
+    for row in csv_data:
+        # CSV headers: nomb_prov, nomb_dist, nomb_corr
+        p_name = clean_name(row.get('nomb_prov'))
+        d_name = clean_name(row.get('nomb_dist'))
+        c_name = clean_name(row.get('nomb_corr'))
+        
+        # Apply Province Mapping
+        search_p_name = PROV_MAPPING.get(p_name, p_name)
+
+        # 1. Try Exact Match (with mapped province)
+        key = (search_p_name, d_name, c_name)
+        if key in geojson_lookup:
+            matches.append(row)
+            row['geo_match_id'] = geojson_lookup[key].get('adm3_pcode')
+            continue
+
+        # 2. Relaxed District Match: Search in Province
+        # Find any entry in this province with the same corregimiento name
+        candidates = [k for k in geojson_lookup.keys() if k[0] == search_p_name and k[2] == c_name]
+        
+        if len(candidates) == 1:
+            # Single match found in another district!
+            match_key = candidates[0]
+            matches.append(row)
+            row['geo_match_id'] = geojson_lookup[match_key].get('adm3_pcode')
+            # print(f"Relaxed Match: {c_name} (CSV Dist: {d_name}) -> (Geo Dist: {match_key[1]})")
+            continue
+        elif len(candidates) > 1:
+            # Ambiguous (same corregimiento name in multiple districts of same province - rare but possible)
+            # print(f"Ambiguous: {c_name} found in districts {[k[1] for k in candidates]}")
+            pass
+        
+        # 3. Fuzzy/Typo Fixes (Specific hardcodes for common mismatch types if needed)
+        # E.g. "El Hato de San Juan de Dios" vs "El Hato de San Juan"
+        # We can perform a primitive "contains" check
+        
+        best_candidate = None
+        # Get all corregimientos in this province
+        prov_corrs = [k for k in geojson_lookup.keys() if k[0] == search_p_name]
+        
+        for k in prov_corrs:
+            geo_c = k[2]
+            # Check if one contains the other
+            if (c_name in geo_c or geo_c in c_name) and len(c_name) > 4 and len(geo_c) > 4:
+                 # Check if starts matching
+                 if c_name.startswith(geo_c) or geo_c.startswith(c_name):
+                     best_candidate = k
+                     break
+        
+        if best_candidate:
+             matches.append(row)
+             row['geo_match_id'] = geojson_lookup[best_candidate].get('adm3_pcode')
+             # print(f"Fuzzy Match: '{c_name}' ~= '{best_candidate[2]}'")
+             continue
+
+        # No match
+        mismatches.append(row)
+        row['lookup_key'] = (search_p_name, d_name, c_name)
+
+    print(f"Total rows in CSV: {len(csv_data)}")
+    print(f"Matches found: {len(matches)}")
+    print(f"Mismatches found: {len(mismatches)}")
+    print(f"Match Rate: {len(matches)/len(csv_data)*100:.1f}%")
+
+    if mismatches:
+        print("\nMismatch Details (First 20):")
+        print(f"{'CSV Key (Prov, Dist, Corr)':<60} {'Closest Match?':<20}")
+        print("-" * 85)
+        for row in mismatches[:20]:
+            key = row['lookup_key']
+            print(f"{str(key):<60}")
+            
+    # Analyze mismatches by Province
+    print("\nAnalyzing remaining mismatches by Province:")
+    prov_mismatches = {}
+    for row in mismatches:
+        p = row['nomb_prov']
+        prov_mismatches[p] = prov_mismatches.get(p, 0) + 1
+    for p, count in prov_mismatches.items():
+        print(f"{p}: {count}")
+
+if __name__ == "__main__":
+    validate_censo_integration()

backend/services/data_loader.py

@@ -0,0 +1,271 @@
+"""
+Data Loader Service for Panama Geographic Data
+
+Loads GeoJSON files from the data/raw directory and provides
+query capabilities for the LLM to search and filter features.
+"""
+
+import os
+import json
+from typing import List, Dict, Any, Optional
+from functools import lru_cache
+
+
+class PanamaDataLoader:
+    """
+    Singleton service to load and query Panama geographic data.
+    Loads data once on first access and caches in memory.
+    """
+    
+    _instance = None
+    _data_loaded = False
+    
+    # Data storage
+    admin0: List[Dict[str, Any]] = []  # Country
+    admin1: List[Dict[str, Any]] = []  # Provinces (13)
+    admin2: List[Dict[str, Any]] = []  # Districts (76)
+    admin3: List[Dict[str, Any]] = []  # Corregimientos (594)
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        if not PanamaDataLoader._data_loaded:
+            self._load_data()
+            PanamaDataLoader._data_loaded = True
+    
+    def _get_data_path(self) -> str:
+        """Get the path to the data/raw directory."""
+        # Navigate from backend/services to project root
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        project_root = os.path.dirname(os.path.dirname(current_dir))
+        return os.path.join(project_root, "data", "raw")
+    
+    def _load_geojson(self, filename: str) -> List[Dict[str, Any]]:
+        """Load a GeoJSON file and return its features."""
+        filepath = os.path.join(self._get_data_path(), filename)
+        
+        if not os.path.exists(filepath):
+            print(f"Warning: {filepath} not found")
+            return []
+        
+        try:
+            with open(filepath, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+                features = data.get('features', [])
+                print(f"  Loaded {len(features)} features from {filename}")
+                return features
+        except Exception as e:
+            print(f"Error loading {filename}: {e}")
+            return []
+    
+    def _load_data(self):
+        """Load all GeoJSON data files."""
+        print("=" * 50)
+        print("Loading Panama Geographic Data...")
+        print("=" * 50)
+        
+        self.admin0 = self._load_geojson("pan_admin0.geojson")
+        self.admin1 = self._load_geojson("pan_admin1.geojson")
+        self.admin2 = self._load_geojson("pan_admin2.geojson")
+        self.admin3 = self._load_geojson("pan_admin3.geojson")
+        
+        total = len(self.admin0) + len(self.admin1) + len(self.admin2) + len(self.admin3)
+        print(f"Total features loaded: {total}")
+        print("=" * 50)
+    
+    def get_schema_context(self) -> str:
+        """Return schema description for LLM context."""
+        return """
+Panama Geographic Data (HDX Administrative Boundaries):
+
+1. admin0 (Country Level)
+   - adm0_name: "Panamá"
+   - adm0_pcode: "PA"
+   - area_sqkm: country area in square kilometers
+   - geometry: MultiPolygon
+
+2. admin1 (Provinces - 13 total)
+   - adm1_name: Province name (e.g., "Bocas del Toro", "Panamá", "Colón")
+   - adm1_pcode: Province code (e.g., "PA01", "PA08")
+   - adm0_name: "Panamá"
+   - area_sqkm: province area
+   - center_lat, center_lon: centroid coordinates
+   - geometry: MultiPolygon
+
+3. admin2 (Districts - 76 total)
+   - adm2_name: District name
+   - adm2_pcode: District code (e.g., "PA0101")
+   - adm1_name: Parent province name
+   - adm1_pcode: Parent province code
+   - area_sqkm: district area
+   - center_lat, center_lon: centroid coordinates
+   - geometry: MultiPolygon
+
+4. admin3 (Corregimientos - 594 total)
+   - adm3_name: Corregimiento name
+   - adm3_pcode: Corregimiento code (e.g., "PA010101")
+   - adm2_name: Parent district name
+   - adm2_pcode: Parent district code
+   - adm1_name: Parent province name
+   - area_sqkm: corregimiento area
+   - center_lat, center_lon: centroid coordinates
+   - geometry: MultiPolygon
+
+Notes:
+- All geometries use WGS84 (EPSG:4326) coordinate system
+- P-codes follow ISO 3166-2 format
+- Valid as of 2021-10-20
+"""
+    
+    def get_data_citations(self, admin_levels: List[str]) -> List[str]:
+        """Return citations for the queried data."""
+        citations = []
+        level_names = {
+            "admin0": "Panama Country Boundary",
+            "admin1": "Panama Provinces",
+            "admin2": "Panama Districts", 
+            "admin3": "Panama Corregimientos"
+        }
+        
+        for level in admin_levels:
+            if level in level_names:
+                citations.append(f"{level_names[level]} (HDX COD-AB, 2021)")
+        
+        return citations if citations else ["Panama Administrative Boundaries (HDX COD-AB, 2021)"]
+    
+    def search_by_name(
+        self, 
+        name: str, 
+        admin_level: Optional[str] = None,
+        limit: int = 50
+    ) -> List[Dict[str, Any]]:
+        """
+        Search for features by name (case-insensitive partial match).
+        
+        Args:
+            name: Search term
+            admin_level: Optional filter ("admin1", "admin2", "admin3")
+            limit: Maximum results to return
+        """
+        name_lower = name.lower()
+        results = []
+        
+        levels_to_search = []
+        if admin_level:
+            levels_to_search = [(admin_level, getattr(self, admin_level, []))]
+        else:
+            levels_to_search = [
+                ("admin1", self.admin1),
+                ("admin2", self.admin2),
+                ("admin3", self.admin3)
+            ]
+        
+        for level_name, features in levels_to_search:
+            for feature in features:
+                props = feature.get("properties", {})
+                
+                # Check various name fields
+                for key in ["adm1_name", "adm2_name", "adm3_name", "adm0_name"]:
+                    value = props.get(key, "")
+                    if value and name_lower in value.lower():
+                        results.append({
+                            "level": level_name,
+                            "feature": feature
+                        })
+                        break
+                
+                if len(results) >= limit:
+                    break
+            
+            if len(results) >= limit:
+                break
+        
+        return results
+    
+    def get_all_provinces(self) -> List[Dict[str, Any]]:
+        """Get all provinces (admin1)."""
+        return self.admin1
+    
+    def get_all_districts(self, province_pcode: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Get all districts, optionally filtered by province."""
+        if province_pcode:
+            return [
+                f for f in self.admin2 
+                if f.get("properties", {}).get("adm1_pcode") == province_pcode
+            ]
+        return self.admin2
+    
+    def get_all_corregimientos(
+        self, 
+        district_pcode: Optional[str] = None,
+        province_pcode: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """Get all corregimientos, optionally filtered."""
+        results = self.admin3
+        
+        if district_pcode:
+            results = [
+                f for f in results 
+                if f.get("properties", {}).get("adm2_pcode") == district_pcode
+            ]
+        elif province_pcode:
+            results = [
+                f for f in results 
+                if f.get("properties", {}).get("adm1_pcode") == province_pcode
+            ]
+        
+        return results
+    
+    def get_by_pcode(self, pcode: str) -> Optional[Dict[str, Any]]:
+        """Get a feature by its P-code."""
+        pcode_upper = pcode.upper()
+        
+        # Determine level by P-code length
+        if len(pcode_upper) == 2:  # Country
+            for f in self.admin0:
+                if f.get("properties", {}).get("adm0_pcode") == pcode_upper:
+                    return f
+        elif len(pcode_upper) == 4:  # Province
+            for f in self.admin1:
+                if f.get("properties", {}).get("adm1_pcode") == pcode_upper:
+                    return f
+        elif len(pcode_upper) == 6:  # District
+            for f in self.admin2:
+                if f.get("properties", {}).get("adm2_pcode") == pcode_upper:
+                    return f
+        elif len(pcode_upper) == 8:  # Corregimiento
+            for f in self.admin3:
+                if f.get("properties", {}).get("adm3_pcode") == pcode_upper:
+                    return f
+        
+        return None
+    
+    def to_geojson(self, features: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Convert a list of features to a GeoJSON FeatureCollection."""
+        # Handle both raw features and wrapped results from search
+        clean_features = []
+        for f in features:
+            if "feature" in f:
+                clean_features.append(f["feature"])
+            else:
+                clean_features.append(f)
+        
+        return {
+            "type": "FeatureCollection",
+            "features": clean_features
+        }
+
+
+# Singleton instance
+_data_loader: Optional[PanamaDataLoader] = None
+
+
+def get_data_loader() -> PanamaDataLoader:
+    """Get the singleton data loader instance."""
+    global _data_loader
+    if _data_loader is None:
+        _data_loader = PanamaDataLoader()
+    return _data_loader

backend/services/executor.py

@@ -0,0 +1,860 @@
+"""
+Query Executor Service
+
+Handles query processing with intent detection, data querying, and response generation.
+Uses semantic search for scalable dataset discovery and session-scoped layer storage.
+"""
+
+from backend.core.llm_gateway import LLMGateway
+from backend.services.data_loader import get_data_loader
+from backend.core.geo_engine import get_geo_engine
+from backend.services.response_formatter import ResponseFormatter
+from backend.core.session_store import get_session_store
+from backend.core.semantic_search import get_semantic_search
+from backend.core.data_catalog import get_data_catalog
+from backend.core.query_planner import get_query_planner
+from typing import List, Dict, Any, Optional
+import json
+import datetime
+import uuid
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Default session ID for backward compatibility
+DEFAULT_SESSION_ID = "default-session"
+
+
+class QueryExecutor:
+    def __init__(self):
+        self.llm = LLMGateway()
+        self.data_loader = get_data_loader()
+        self.geo_engine = get_geo_engine()
+        self.session_store = get_session_store()
+        self.semantic_search = get_semantic_search()
+        self.catalog = get_data_catalog()
+        self.query_planner = get_query_planner()
+
+    def _get_schema_context(self) -> str:
+        """Returns the database schema for the LLM context."""
+        return self.data_loader.get_schema_context()
+
+    async def process_query_with_context(self, query: str, history: List[Dict[str, str]]) -> Dict[str, Any]:
+        """
+        Orchestrates the full query processing flow with conversation context.
+        """
+        # 1. Detect intent
+        intent = await self.llm.detect_intent(query, history)
+        print(f"[GeoQuery] Detected intent: {intent}")
+        
+        # 2. Route based on intent
+        if intent == "GENERAL_CHAT":
+            return await self._handle_general_chat(query, history)
+        elif intent in ["DATA_QUERY", "MAP_REQUEST"]:
+            # Always include map for data queries - the visual is helpful
+            return await self._handle_data_query(query, history, include_map=True)
+        elif intent == "SPATIAL_OP":
+            return await self._handle_spatial_op(query, history)
+        elif intent == "STAT_QUERY":
+            return await self._handle_stat_query(query, history)
+        else:
+            return await self._handle_general_chat(query, history)
+
+    async def process_query_stream(self, query: str, history: List[Dict[str, str]]):
+        """
+        Streamable version of process_query_with_context.
+        Yields: {"event": "status"|"thought"|"chunk"|"result", "data": ...}
+        """
+        
+        # 1. Intent Detection with Thoughts
+        yield {"event": "status", "data": json.dumps({"status": "🧠 Understanding intent..."})}
+        
+        intent = "GENERAL_CHAT"
+        intent_buffer = ""
+        
+        try:
+            async for chunk in self.llm.stream_intent(query, history):
+                if chunk["type"] == "thought":
+                    yield {"event": "chunk", "data": json.dumps({"type": "thought", "content": chunk["text"]})}
+                elif chunk["type"] == "content":
+                    intent_buffer += chunk["text"]
+        except Exception as e:
+            print(f"Intent stream error: {e}")
+        
+        intent = intent_buffer.strip().upper()
+        if not intent:
+            intent = "GENERAL_CHAT" 
+            
+        # Clean up intent string
+        for valid in ["GENERAL_CHAT", "DATA_QUERY", "MAP_REQUEST", "SPATIAL_OP", "STAT_QUERY"]:
+             if valid in intent:
+                 intent = valid
+                 break
+        
+        yield {"event": "intent", "data": json.dumps({"intent": intent})}
+        print(f"[GeoQuery] Detected intent: {intent}")
+
+        if intent == "GENERAL_CHAT":
+            async for chunk in self.llm.generate_response_stream(query, history):
+                # Transform to frontend protocol
+                if chunk.get("type") == "content":
+                     yield {"event": "chunk", "data": json.dumps({"type": "text", "content": chunk.get("text")})}
+                elif chunk.get("type") == "thought":
+                     yield {"event": "chunk", "data": json.dumps({"type": "thought", "content": chunk.get("content")})}
+            
+            # Send final result to clear loading status
+            yield {"event": "result", "data": json.dumps({"response": ""})}
+            return
+
+        # Handle Data/Map/Stat Queries together via a unified stream handler
+        
+        if intent in ["DATA_QUERY", "MAP_REQUEST", "STAT_QUERY"]:
+            include_map = intent != "STAT_QUERY"
+            session_id = DEFAULT_SESSION_ID  # TODO: Get from request context
+            
+            # 0. Check query complexity
+            complexity = self.query_planner.detect_complexity(query)
+            
+            if complexity["is_complex"]:
+                yield {"event": "status", "data": json.dumps({"status": "���� Complex query detected, planning steps..."})}
+                logger.info(f"Complex query detected: {complexity['reason']}")
+                
+                # Use multi-step executor
+                async for event in self._execute_multi_step_query(query, history, include_map, session_id):
+                    yield event
+                return
+            
+            # Simple query - continue with existing flow
+            # 0. Semantic Discovery (scalable pre-filter)
+            yield {"event": "status", "data": json.dumps({"status": "📚 Searching data catalog..."})}            
+            
+            # Use semantic search to find top candidates
+            candidate_tables = self.semantic_search.search_table_names(query, top_k=15)
+            
+            if candidate_tables:
+                # Get focused summaries for LLM refinement
+                candidate_summaries = self.catalog.get_summaries_for_tables(candidate_tables)
+            else:
+                # Fallback to all summaries (legacy behavior for small catalogs)
+                candidate_summaries = self.catalog.get_all_table_summaries()
+            
+            # 1. LLM refines from candidates
+            yield {"event": "status", "data": json.dumps({"status": "🔍 Identifying relevant tables..."})}
+            relevant_tables = await self.llm.identify_relevant_tables(query, candidate_summaries)
+            
+            # 2. Lazy Load
+            if relevant_tables:
+                yield {"event": "status", "data": json.dumps({"status": f"💾 Loading tables: {', '.join(relevant_tables)}..."})}
+            
+            feature_tables = []
+            for table in relevant_tables:
+                if self.geo_engine.ensure_table_loaded(table):
+                    feature_tables.append(table)
+            
+            # 3. Schema
+            table_schema = self.geo_engine.get_table_schemas()
+            
+            # 4. Generate SQL (Streaming Thoughts!)
+            yield {"event": "status", "data": json.dumps({"status": "✍️ Writing SQL query..."})}
+            
+            sql_buffer = ""
+            async for chunk in self.llm.stream_analytical_sql(query, table_schema, history):
+                if chunk["type"] == "thought":
+                    yield {"event": "chunk", "data": json.dumps({"type": "thought", "content": chunk["text"]})}
+                elif chunk["type"] == "content":
+                    sql_buffer += chunk["text"]
+            
+            sql = sql_buffer.replace("```sql", "").replace("```", "").strip()
+            
+            # 5. Check for DATA_UNAVAILABLE error from LLM
+            if "DATA_UNAVAILABLE" in sql or sql.startswith("-- ERROR"):
+                yield {"event": "status", "data": json.dumps({"status": "ℹ️ Data not available"})}
+                
+                requested = "the requested data"
+                available = "administrative boundaries (provinces, districts, corregimientos)"
+                
+                for line in sql.split("\n"):
+                    if "Requested:" in line:
+                        requested = line.split("Requested:")[-1].strip()
+                    elif "Available:" in line:
+                        available = line.split("Available:")[-1].strip()
+                
+                error_response = f"""I couldn't find data for **{requested}** in the current database.
+
+**Available datasets include:**
+- {available}
+
+If you need additional data, please let me know and I can help you understand what's currently available or suggest alternative queries."""
+                
+                yield {
+                    "event": "result",
+                    "data": json.dumps({
+                        "response": error_response,
+                        "sql_query": sql,
+                        "geojson": None,
+                        "data_citations": [],
+                        "chart_data": None,
+                        "raw_data": []
+                    })
+                }
+                return 
+            
+            # 6. Execute query
+            yield {"event": "status", "data": json.dumps({"status": "⚡ Executing query..."})}
+            
+            geojson = None
+            features = []
+            error_message = None
+            
+            try:
+                geojson = self.geo_engine.execute_spatial_query(sql)
+                features = geojson.get("features", [])
+                yield {"event": "status", "data": json.dumps({"status": f"✅ Found {len(features)} results"})}
+            except Exception as e:
+                error_message = str(e)
+                yield {"event": "status", "data": json.dumps({"status": "⚠️ Query error, attempting repair..."})}
+                try:
+                    sql = await self.llm.correct_sql(query, sql, error_message, str(table_schema))
+                    geojson = self.geo_engine.execute_spatial_query(sql)
+                    features = geojson.get("features", [])
+                    error_message = None
+                except Exception as e2:
+                    print(f"Repair failed: {e2}")
+
+            if error_message:
+                 yield {
+                    "event": "result",
+                    "data": json.dumps({
+                        "response": f"I was unable to process your request because the data query failed. \n\nError details: {error_message}",
+                        "sql_query": sql,
+                        "geojson": None,
+                        "data_citations": [],
+                        "chart_data": None,
+                        "raw_data": []
+                    })
+                 }
+                 return
+
+            # 7. Post-process using ResponseFormatter
+            citations = ResponseFormatter.generate_citations(relevant_tables, features)
+            
+            # Chart
+            chart_data = ResponseFormatter.generate_chart_data(sql, features)
+            if intent == "STAT_QUERY" and not chart_data and features:
+                 chart_data = ResponseFormatter.generate_chart_data("GROUP BY forced", features)
+
+            # Raw Data
+            raw_data = ResponseFormatter.prepare_raw_data(features)
+            
+            # Map Config 
+            if include_map and features and geojson:
+                # Generate AI layer name
+                layer_info = await self.llm.generate_layer_name(query, sql)
+                layer_name_ai = layer_info.get("name", "Map Layer")
+                layer_emoji = layer_info.get("emoji", "📍")
+                point_style = layer_info.get("pointStyle", None)
+                geojson, layer_id, layer_name = ResponseFormatter.format_geojson_layer(query, geojson, features, layer_name_ai, layer_emoji, point_style)
+                
+                try:
+                    table_name = self.geo_engine.register_layer(layer_id, geojson)
+                    self.session_store.add_layer(session_id, {
+                        "id": layer_id, 
+                        "name": layer_name, 
+                        "table_name": table_name, 
+                        "timestamp": datetime.datetime.now().isoformat()
+                    })
+                except Exception as e:
+                    logger.warning(f"Failed to register layer: {e}")
+
+            # 8. Explanation (Streaming!)
+            yield {"event": "status", "data": json.dumps({"status": "💬 Generating explanation..."})}
+            
+            data_summary = ResponseFormatter.generate_data_summary(features)
+
+            explanation_buffer = ""
+            
+            async for chunk in self.llm.stream_explanation(query, sql, data_summary, history):
+                if chunk["type"] == "thought":
+                    yield {"event": "chunk", "data": json.dumps({"type": "thought", "content": chunk["text"]})}
+                elif chunk["type"] == "content":
+                    explanation_buffer += chunk["text"]
+                    yield {"event": "chunk", "data": json.dumps({"type": "text", "content": chunk["text"]})}
+            
+            # 9. Final Result Event
+            yield {"event": "result", "data": json.dumps({
+                "response": explanation_buffer,
+                "sql_query": sql,
+                "geojson": geojson if include_map and features else None,
+                "chart_data": chart_data,
+                "raw_data": raw_data,
+                "data_citations": citations
+            })}
+            
+        elif intent == "SPATIAL_OP":
+            yield {"event": "status", "data": json.dumps({"status": "📐 Preparing spatial operation..."})}
+            session_id = DEFAULT_SESSION_ID  # TODO: Get from request context
+            
+            # 0. Semantic Discovery for base tables
+            candidate_tables = self.semantic_search.search_table_names(query, top_k=15)
+            if candidate_tables:
+                candidate_summaries = self.catalog.get_summaries_for_tables(candidate_tables)
+            else:
+                candidate_summaries = self.catalog.get_all_table_summaries()
+            
+            # 1. Identify relevant base tables from query
+            relevant_tables = await self.llm.identify_relevant_tables(query, candidate_summaries)
+            
+            # 2. Lazy load those tables
+            for table in relevant_tables:
+                self.geo_engine.ensure_table_loaded(table)
+            
+            # 3. Get schema of loaded base tables
+            base_table_schema = self.geo_engine.get_table_schemas()
+            
+            # 4. Prepare Layer Context (user-created layers from session)
+            session_layers = self.session_store.get_layers(session_id)
+            layer_context = "User-Created Layers:\n"
+            if not session_layers:
+                 layer_context += "(No user layers created yet.)\n"
+            else:
+                 for i, layer in enumerate(session_layers):
+                     layer_context += f"Layer {i+1}: {layer['name']} (Table: {layer['table_name']})\n"
+            
+            # 5. Combine both contexts for LLM
+            full_context = f"{base_table_schema}\n\n{layer_context}"
+            
+            # 6. Generate Spatial SQL
+            yield {"event": "status", "data": json.dumps({"status": "✍️ Writing spatial SQL..."})}
+            sql = await self.llm.generate_spatial_sql(query, full_context, history)
+            
+            # 7. Execute
+            yield {"event": "status", "data": json.dumps({"status": "⚙️ Processing geometry..."})}
+            error_message = None
+            geojson = None
+            features = []
+            
+            try:
+                geojson = self.geo_engine.execute_spatial_query(sql)
+                features = geojson.get("features", [])
+                yield {"event": "status", "data": json.dumps({"status": f"✅ Result contains {len(features)} features"})}
+            except Exception as e:
+                error_message = str(e)
+                yield {"event": "status", "data": json.dumps({"status": "⚠️ Spatial error, attempting repair..."})}
+                try:
+                     sql = await self.llm.correct_sql(query, sql, error_message, full_context)
+                     geojson = self.geo_engine.execute_spatial_query(sql)
+                     features = geojson.get("features", [])
+                     error_message = None
+                except Exception as e2:
+                     yield {
+                        "event": "result",
+                        "data": json.dumps({
+                            "response": f"I tried to perform the spatial operation but encountered an error: {str(e)}\n\nQuery: {sql}",
+                            "sql_query": sql,
+                            "geojson": None,
+                            "data_citations": [],
+                            "chart_data": None,
+                            "raw_data": []
+                        })
+                    }
+                     return
+
+            # 4. Result Processing
+            if features:
+                # Generate AI layer name
+                layer_info = await self.llm.generate_layer_name(query, sql)
+                layer_name_ai = layer_info.get("name", "Map Layer")
+                layer_emoji = layer_info.get("emoji", "📍")
+                point_style = layer_info.get("pointStyle", None)
+                geojson, layer_id, layer_name = ResponseFormatter.format_geojson_layer(query, geojson, features, layer_name_ai, layer_emoji, point_style)
+                
+                try:
+                    table_name = self.geo_engine.register_layer(layer_id, geojson)
+                    self.session_store.add_layer(session_id, {
+                        "id": layer_id, 
+                        "name": layer_name, 
+                        "table_name": table_name, 
+                        "timestamp": datetime.datetime.now().isoformat()
+                    })
+                except Exception as e:
+                    logger.warning(f"Failed to register layer: {e}")
+                
+            # 5. Explanation
+            yield {"event": "status", "data": json.dumps({"status": "💬 Explaining results..."})}
+            data_summary = f"Spatial operation resulted in {len(features)} features."
+            
+            explanation_buffer = ""
+            async for chunk in self.llm.stream_explanation(query, sql, data_summary, history):
+                if chunk["type"] == "thought":
+                    yield {"event": "chunk", "data": json.dumps({"type": "thought", "content": chunk["text"]})}
+                elif chunk["type"] == "content":
+                    explanation_buffer += chunk["text"]
+                    yield {"event": "chunk", "data": json.dumps({"type": "text", "content": chunk["text"]})}
+            
+            # 6. Final Result
+            yield {"event": "result", "data": json.dumps({
+                "response": explanation_buffer,
+                "sql_query": sql,
+                "geojson": geojson,
+                "chart_data": None,
+                "raw_data": [], # Spatial ops usually visual
+                "data_citations": []
+            })}
+            return
+
+        else:
+             # Fallback
+             yield {"event": "chunk", "data": json.dumps({"type": "text", "content": "I'm not sure how to handle this query yet."})}
+
+    async def _handle_general_chat(self, query: str, history: List[Dict[str, str]]) -> Dict[str, Any]:
+        """Handles general conversational queries."""
+        # Add schema context to help the LLM answer questions about the data
+        enhanced_query = f"""The user is asking about Panama geographic data. 
+        
+Available data: {len(self.data_loader.admin1)} provinces, {len(self.data_loader.admin2)} districts, {len(self.data_loader.admin3)} corregimientos.
+
+User question: {query}
+
+Respond helpfully as GeoQuery, the territorial intelligence assistant."""
+
+        response = await self.llm.generate_response(enhanced_query, history)
+        
+        return {
+            "response": response,
+            "sql_query": None,
+            "geojson": None,
+            "data_citations": [],
+            "intent": "GENERAL_CHAT"
+        }
+
+    async def _handle_data_query(self, query: str, history: List[Dict[str, str]], include_map: bool = True) -> Dict[str, Any]:
+        """
+        Handles data queries using text-to-SQL with SOTA Smart Discovery.
+        """
+        print(f"[GeoQuery] Starting Data Query: {query}")
+        
+        # 0. Get Catalog
+        from backend.core.data_catalog import get_data_catalog
+        catalog = get_data_catalog()
+        
+        # 1. Smart Discovery: Identify relevant tables
+        summaries = catalog.get_all_table_summaries()
+        
+        # Ask LLM which tables are relevant
+        relevant_tables = await self.llm.identify_relevant_tables(query, summaries)
+        
+        # 2. Lazy Loading
+        feature_tables = []
+        for table in relevant_tables:
+            if self.geo_engine.ensure_table_loaded(table):
+                feature_tables.append(table)
+            else:
+                print(f"[GeoQuery] Warning: Could not load relevant table '{table}'")
+                
+        # 3. Get schema context (now includes the newly loaded tables)
+        table_schema = self.geo_engine.get_table_schemas()
+
+        # Fallback for empty schema
+        if len(table_schema) < 50: 
+             print("[GeoQuery] GeoEngine schema empty. Fetching from Catalog Metadata.")
+             fallback_tables = list(set(feature_tables + ["pan_admin1", "pan_admin2", "pan_admin3"]))
+             table_schema = catalog.get_specific_table_schemas(fallback_tables)
+        
+        # 4. Generate real SQL using LLM
+        print(f"[GeoQuery] Generating SQL with context size: {len(table_schema)} chars")
+        sql = await self.llm.generate_analytical_sql(query, table_schema, history)
+        
+        # Check for SQL generation errors
+        if sql.startswith("-- Error"):
+            available_data = ", ".join(feature_tables) if feature_tables else "Administrative Boundaries"
+            return {
+                "response": f"I couldn't find the specific data you asked for. I have access to: {available_data}. \n\nOriginal request: {query}",
+                "sql_query": sql,
+                "intent": "DATA_QUERY"
+            }
+        
+        # 5. Execute SQL in DuckDB
+        error_message = None
+        try:
+            geojson = self.geo_engine.execute_spatial_query(sql)
+            features = geojson.get("features", [])
+            print(f"[GeoQuery] Query returned {len(features)} features")
+        except Exception as e:
+            error_message = str(e)
+            print(f"[GeoQuery] SQL execution error: {error_message}")
+            
+            # Self-Correction Loop
+            try:
+                sql = await self.llm.correct_sql(query, sql, error_message, str(table_schema))
+                geojson = self.geo_engine.execute_spatial_query(sql)
+                features = geojson.get("features", [])
+                error_message = None 
+            except Exception as e2:
+                return {
+                    "response": f"The SQL query failed to execute even after an automatic repair attempt.\nOriginal Error: {error_message}\nRepair Error: {str(e2)}",
+                    "sql_query": sql,
+                    "intent": "DATA_QUERY"
+                }
+        
+        # 6. Post-Process via ResponseFormatter
+        citations = ResponseFormatter.generate_citations(relevant_tables, features)
+        data_summary = ResponseFormatter.generate_data_summary(features)
+        
+        # 7. Generate explanation
+        explanation = await self.llm.generate_explanation(query, sql, data_summary, history)
+        
+        # 8. Add Layer Metadata to GeoJSON and REGISTER in GeoEngine
+        if include_map and features:
+            # Generate AI layer name
+            layer_info = await self.llm.generate_layer_name(query, sql)
+            layer_name_ai = layer_info.get("name", "Map Layer")
+            layer_emoji = layer_info.get("emoji", "📍")
+            point_style = layer_info.get("pointStyle", None)
+            geojson, layer_id, layer_name = ResponseFormatter.format_geojson_layer(query, geojson, features, layer_name_ai, layer_emoji, point_style)
+            
+            try:
+                table_name = self.geo_engine.register_layer(layer_id, geojson)
+                self.session_store.add_layer(DEFAULT_SESSION_ID, {
+                    "id": layer_id,
+                    "name": layer_name,
+                    "table_name": table_name,
+                    "timestamp": datetime.datetime.now().isoformat()
+                })
+            except Exception as e:
+                logger.warning(f"Failed to register layer in GeoEngine: {e}")
+
+        # 9. Auto-generate Chart
+        chart_data = ResponseFormatter.generate_chart_data(sql, features)
+
+        # 10. Prepare Raw Data
+        raw_data = ResponseFormatter.prepare_raw_data(features)
+
+        return {
+            "response": explanation,
+            "sql_query": sql,  
+            "geojson": geojson if include_map and features else None,
+            "data_citations": citations,
+            "chart_data": chart_data,
+            "raw_data": raw_data,
+            "intent": "DATA_QUERY" if not include_map else "MAP_REQUEST"
+        }
+
+    async def _handle_spatial_op(self, query: str, history: List[Dict[str, str]]) -> Dict[str, Any]:
+        """Handles spatial operations (Difference, Intersection, etc) using GeoEngine."""
+        # 0. Get data catalog for relevant tables
+        from backend.core.data_catalog import get_data_catalog
+        catalog = get_data_catalog()
+        summaries = catalog.get_all_table_summaries()
+        
+        # 1. Identify relevant base tables from query
+        relevant_tables = await self.llm.identify_relevant_tables(query, summaries)
+        
+        # 2. Lazy load those tables
+        for table in relevant_tables:
+            self.geo_engine.ensure_table_loaded(table)
+        
+        # 3. Get schema of loaded base tables
+        base_table_schema = self.geo_engine.get_table_schemas()
+        
+        # 4. Prepare Layer Context (user-created layers from session)
+        session_layers = self.session_store.get_layers(DEFAULT_SESSION_ID)
+        layer_context = "User-Created Layers:\n"
+        if not session_layers:
+             layer_context += "(No user layers created yet.)\n"
+        else:
+             for i, layer in enumerate(session_layers):
+                 layer_context += f"Layer {i+1}: {layer['name']} (Table: {layer['table_name']})\n"
+        
+        # 5. Combine both contexts for LLM
+        full_context = f"{base_table_schema}\n\n{layer_context}"
+        
+        # 6. Generate Spatial SQL
+        sql = await self.llm.generate_spatial_sql(query, full_context, history)
+        
+        # 7. Execute
+        error_message = None
+        geojson = None
+        features = []
+        
+        try:
+            geojson = self.geo_engine.execute_spatial_query(sql)
+            features = geojson.get("features", [])
+        except Exception as e:
+            error_message = str(e)
+            try:
+                 sql = await self.llm.correct_sql(query, sql, error_message, full_context)
+                 geojson = self.geo_engine.execute_spatial_query(sql)
+                 features = geojson.get("features", [])
+                 error_message = None
+            except Exception as e2:
+                 return {
+                    "response": f"I tried to perform the spatial operation but encountered an error: {str(e)}\n\nQuery: {sql}",
+                    "sql_query": sql,
+                    "intent": "SPATIAL_OP"
+                }
+
+        # 4. Result Processing
+        if features:
+            # Generate AI layer name
+            layer_info = await self.llm.generate_layer_name(query, sql)
+            layer_name_ai = layer_info.get("name", "Map Layer")
+            layer_emoji = layer_info.get("emoji", "📍")
+            point_style = layer_info.get("pointStyle", None)
+            geojson, layer_id, layer_name = ResponseFormatter.format_geojson_layer(query, geojson, features, layer_name_ai, layer_emoji, point_style)
+            table_name = self.geo_engine.register_layer(layer_id, geojson)
+            self.session_store.add_layer(DEFAULT_SESSION_ID, {
+                "id": layer_id, 
+                "name": layer_name, 
+                "table_name": table_name, 
+                "timestamp": datetime.datetime.now().isoformat()
+            })
+            
+        data_summary = f"Spatial operation resulted in {len(features)} features."
+        explanation = await self.llm.generate_explanation(query, sql, data_summary, history)
+        
+        return {
+            "response": explanation,
+            "sql_query": sql,
+            "geojson": geojson,
+            "data_citations": [], 
+            "intent": "SPATIAL_OP"
+        }
+
+    async def _handle_stat_query(self, query: str, history: List[Dict[str, str]]) -> Dict[str, Any]:
+        """
+        Handles statistical queries where charts/tables are more important than maps.
+        """
+        # Reuse data query logic but without map emphasis
+        result = await self._handle_data_query(query, history, include_map=False)
+        result["intent"] = "STAT_QUERY"
+        
+        # Ensure chart data is present if possible
+        if not result.get("chart_data") and result.get("raw_data"):
+             # Force chart attempt
+             features_mock = [{"properties": d} for d in result["raw_data"]]
+             result["chart_data"] = ResponseFormatter.generate_chart_data(result.get("sql_query", ""), features_mock)
+             
+        return result
+
+    async def _execute_multi_step_query(
+        self, 
+        query: str, 
+        history: List[Dict[str, str]], 
+        include_map: bool,
+        session_id: str
+    ):
+        """
+        Execute a complex query by breaking it into multiple steps.
+        
+        Yields streaming events throughout the multi-step process.
+        """
+        import asyncio
+        
+        # 1. Get candidate tables for planning
+        yield {"event": "status", "data": json.dumps({"status": "📚 Discovering relevant datasets..."})}
+        
+        candidate_tables = self.semantic_search.search_table_names(query, top_k=20)
+        if not candidate_tables:
+            candidate_tables = list(self.catalog.catalog.keys())
+        
+        # 2. Plan the query
+        yield {"event": "status", "data": json.dumps({"status": "📋 Creating execution plan..."})}
+        
+        plan = await self.query_planner.plan_query(query, candidate_tables, self.llm)
+        
+        if not plan.is_complex or not plan.steps:
+            # Fallback to simple execution
+            yield {"event": "status", "data": json.dumps({"status": "📚 Executing as simple query..."})}
+            # Re-route to simple path by manually calling the logic
+            candidate_summaries = self.catalog.get_summaries_for_tables(candidate_tables)
+            relevant_tables = await self.llm.identify_relevant_tables(query, candidate_summaries)
+            
+            for table in relevant_tables:
+                self.geo_engine.ensure_table_loaded(table)
+            
+            table_schema = self.geo_engine.get_table_schemas()
+            
+            yield {"event": "status", "data": json.dumps({"status": "✍️ Writing SQL query..."})}
+            sql = await self.llm.generate_analytical_sql(query, table_schema, history)
+            sql = sql.replace("```sql", "").replace("```", "").strip()
+            
+            try:
+                geojson = self.geo_engine.execute_spatial_query(sql)
+                features = geojson.get("features", [])
+            except Exception as e:
+                yield {"event": "result", "data": json.dumps({
+                    "response": f"Query execution failed: {str(e)}",
+                    "sql_query": sql
+                })}
+                return
+            
+            data_summary = ResponseFormatter.generate_data_summary(features)
+            explanation = await self.llm.generate_explanation(query, sql, data_summary, history)
+            
+            yield {"event": "result", "data": json.dumps({
+                "response": explanation,
+                "sql_query": sql,
+                "geojson": geojson if include_map and features else None,
+                "chart_data": ResponseFormatter.generate_chart_data(sql, features),
+                "raw_data": ResponseFormatter.prepare_raw_data(features),
+                "data_citations": []
+            })}
+            return
+        
+        # 3. Show plan to user
+        step_descriptions = [f"Step {i+1}: {s.description}" for i, s in enumerate(plan.steps)]
+        yield {"event": "chunk", "data": json.dumps({
+            "type": "thought", 
+            "content": f"Planning multi-step execution:\n" + "\n".join(step_descriptions)
+        })}
+        
+        # 4. Load all needed tables
+        all_tables = set()
+        for step in plan.steps:
+            all_tables.update(step.tables_needed)
+        
+        if all_tables:
+            yield {"event": "status", "data": json.dumps({"status": f"💾 Loading {len(all_tables)} datasets..."})}
+            for table in all_tables:
+                self.geo_engine.ensure_table_loaded(table)
+        
+        # 5. Execute steps by parallel groups
+        intermediate_results = {}
+        all_features = []
+        all_sql = []
+        
+        for group_idx, group in enumerate(plan.parallel_groups):
+            group_steps = [s for s in plan.steps if s.step_id in group]
+            
+            yield {"event": "status", "data": json.dumps({
+                "status": f"⚡ Executing step group {group_idx + 1}/{len(plan.parallel_groups)}..."
+            })}
+            
+            # Execute steps in this group (could be parallel, but sequential for simplicity)
+            for step in group_steps:
+                yield {"event": "status", "data": json.dumps({
+                    "status": f"🔄 {step.description}..."
+                })}
+                
+                # Generate SQL for this step
+                table_schema = self.geo_engine.get_table_schemas()
+                
+                # Build step-specific prompt
+                step_query = f"""Execute this step: {step.description}
+
+Original user request: {query}
+
+SQL Hint: {step.sql_template or 'None'}
+
+Previous step results available: {list(intermediate_results.keys())}"""
+                
+                sql = await self.llm.generate_analytical_sql(step_query, table_schema, history)
+                sql = sql.replace("```sql", "").replace("```", "").strip()
+                
+                # Skip if LLM returned an error
+                if "DATA_UNAVAILABLE" in sql or sql.startswith("-- ERROR"):
+                    logger.warning(f"Step {step.step_id} indicated data unavailable")
+                    intermediate_results[step.result_name] = {"features": [], "sql": sql}
+                    continue
+                
+                try:
+                    geojson = self.geo_engine.execute_spatial_query(sql)
+                    features = geojson.get("features", [])
+                    
+                    intermediate_results[step.result_name] = {
+                        "features": features,
+                        "sql": sql,
+                        "geojson": geojson
+                    }
+                    all_features.extend(features)
+                    all_sql.append(f"-- {step.description}\n{sql}")
+                    
+                    yield {"event": "status", "data": json.dumps({
+                        "status": f"✅ Step got {len(features)} results"
+                    })}
+                    
+                except Exception as e:
+                    logger.error(f"Step {step.step_id} failed: {e}")
+                    # Try to repair
+                    try:
+                        sql = await self.llm.correct_sql(step_query, sql, str(e), table_schema)
+                        geojson = self.geo_engine.execute_spatial_query(sql)
+                        features = geojson.get("features", [])
+                        intermediate_results[step.result_name] = {
+                            "features": features,
+                            "sql": sql,
+                            "geojson": geojson
+                        }
+                        all_features.extend(features)
+                        all_sql.append(f"-- {step.description} (repaired)\n{sql}")
+                    except Exception as e2:
+                        logger.error(f"Step repair also failed: {e2}")
+                        intermediate_results[step.result_name] = {"features": [], "sql": sql, "error": str(e2)}
+        
+        # 6. Generate final combined result
+        yield {"event": "status", "data": json.dumps({"status": "💬 Generating combined analysis..."})}
+        
+        # Summarize intermediate results for explanation
+        result_summary = []
+        for name, result in intermediate_results.items():
+            features = result.get("features", [])
+            result_summary.append(f"{name}: {len(features)} records")
+        
+        combined_summary = f"""Multi-step query completed with {len(plan.steps)} steps.
+
+Results:
+{chr(10).join(result_summary)}
+
+Combination logic: {plan.final_combination_logic}"""
+        
+        # Get combined explanation
+        explanation_buffer = ""
+        async for chunk in self.llm.stream_explanation(query, "\n\n".join(all_sql), combined_summary, history):
+            if chunk["type"] == "content":
+                explanation_buffer += chunk["text"]
+                yield {"event": "chunk", "data": json.dumps({"type": "text", "content": chunk["text"]})}
+        
+        # Find the best geojson to display (use the one with most features)
+        best_geojson = None
+        best_features = []
+        for name, result in intermediate_results.items():
+            features = result.get("features", [])
+            if len(features) > len(best_features):
+                best_features = features
+                best_geojson = result.get("geojson")
+        
+        # Generate layer if we have features
+        if include_map and best_features and best_geojson:
+            layer_info = await self.llm.generate_layer_name(query, all_sql[0] if all_sql else "")
+            layer_name_ai = layer_info.get("name", "Multi-Step Result")
+            layer_emoji = layer_info.get("emoji", "📊")
+            best_geojson, layer_id, layer_name = ResponseFormatter.format_geojson_layer(
+                query, best_geojson, best_features, layer_name_ai, layer_emoji
+            )
+            
+            try:
+                table_name = self.geo_engine.register_layer(layer_id, best_geojson)
+                self.session_store.add_layer(session_id, {
+                    "id": layer_id,
+                    "name": layer_name,
+                    "table_name": table_name,
+                    "timestamp": datetime.datetime.now().isoformat()
+                })
+            except Exception as e:
+                logger.warning(f"Failed to register multi-step layer: {e}")
+        
+        # Generate chart from combined results
+        chart_data = ResponseFormatter.generate_chart_data("\n".join(all_sql), best_features)
+        raw_data = ResponseFormatter.prepare_raw_data(best_features)
+        
+        # Final result
+        yield {"event": "result", "data": json.dumps({
+            "response": explanation_buffer,
+            "sql_query": "\n\n".join(all_sql),
+            "geojson": best_geojson if include_map and best_features else None,
+            "chart_data": chart_data,
+            "raw_data": raw_data,
+            "data_citations": [],
+            "multi_step": True,
+            "steps_executed": len(plan.steps)
+        })}

backend/services/orchestrator.py

@@ -0,0 +1,13 @@
+from typing import Dict, Any
+from backend.services.executor import QueryExecutor
+
+class OrchestratorAgent:
+    def __init__(self):
+        self.executor = QueryExecutor()
+
+    async def process_query(self, query: str, history: list[Dict[str, str]] = None, model: str = None) -> Dict[str, Any]:
+        """
+        Delegates to QueryExecutor. Model param can be used to configure LLM if needed.
+        """
+        # For now, we rely on the default configured in LLMGateway
+        return await self.executor.process_query_with_context(query, history or [])

backend/services/response_formatter.py

@@ -0,0 +1,287 @@
+"""
+Response Formatter Service
+
+Handles formatting of query results into citations, charts, GeoJSON layers, and raw data for the frontend.
+Separates presentation logic from execution logic.
+"""
+
+from typing import List, Dict, Any, Optional
+import uuid
+
+class ResponseFormatter:
+    @staticmethod
+    def generate_citations(tables: List[str], features: Optional[List[Dict]] = None) -> List[str]:
+        """Generates readable citations based on table names and returned features."""
+        citations = []
+        processed = set()
+        
+        # Check explicit table list
+        for table in tables:
+            table = table.lower()
+            if table in processed: continue
+            
+            if "universit" in table:
+                citations.append("Universities Data (OpenStreetMap, 2024)")
+            elif "school" in table or "education" in table:
+                citations.append("Education Facilities (OpenStreetMap, 2024)")
+            elif "hospital" in table or "health" in table:
+                citations.append("Health Facilities (OpenStreetMap, 2024)")
+            elif "airport" in table:
+                citations.append("Airports Data (OpenStreetMap, 2024)")
+            elif "road" in table:
+                citations.append("Road Network (OpenStreetMap, 2024)")
+            elif "population" in table or "census" in table:
+                citations.append("Panama Census Data (INEC, 2023)")
+            elif "admin" in table or "boundar" in table:
+                if "Admin Boundaries" not in processed:
+                    citations.append("Panama Administrative Boundaries (HDX COD-AB, 2021)")
+                    processed.add("Admin Boundaries")
+                continue 
+            
+            processed.add(table)
+            
+        # Fallback check on features if no specific tables cited but admin data returned
+        if not citations and features:
+             if any(k.startswith("adm") for k in features[0].get("properties", {}).keys()):
+                citations.append("Panama Administrative Boundaries (HDX COD-AB, 2021)")
+                
+        return list(set(citations))
+
+    @staticmethod
+    def generate_chart_data(sql: str, features: List[Dict]) -> Optional[Dict[str, Any]]:
+        """
+        Generates Chart.js compatible data structure if the query looks aggregative.
+        """
+        if not features:
+            return None
+            
+        # Heuristic: If GROUP BY or ORDER BY ... LIMIT is used, likely suitable for charting
+        # Or if explicitly requested via intent (logic handled in caller, but we check SQL signature here too)
+        
+        # Try to find string (label) and number (value) in properties
+        try:
+            chart_items = []
+            x_key = "name"
+            y_key = "value"
+            x_label = "Feature"
+            y_label = "Value"
+
+            # 1. Analyze properties to find X (Label) and Y (Value)
+            if features:
+                sample_props = features[0].get("properties", {})
+                
+                # Exclude system keys
+                valid_keys = [k for k in sample_props.keys() if k not in ["geom", "geometry", "style", "layer_name", "layer_id", "choropleth", "fillColor", "color"]]
+                
+                # Find Y (Value) - First numeric column
+                for k in valid_keys:
+                    if isinstance(sample_props[k], (int, float)) and not k.endswith("_id") and not k.endswith("_code"):
+                        y_key = k
+                        y_label = k.replace("_", " ").title()
+                        if "sqkm" in k: y_label = "Area (km²)"
+                        elif "pop" in k: y_label = "Population"
+                        elif "count" in k: y_label = "Count"
+                        break
+                
+                # Find X (Label) - First string column (excluding IDs if possible)
+                for k in valid_keys:
+                    if isinstance(sample_props[k], str) and "name" in k:
+                        x_key = k
+                        x_label = k.replace("_", " ").title().replace("Name", "").strip() or "Region"
+                        break
+            
+            # 2. Build Data
+            for f in features:
+                props = f.get("properties", {})
+                label = props.get(x_key)
+                value = props.get(y_key)
+                
+                if label is not None and value is not None:
+                     chart_items.append({"name": str(label), "value": value})
+            
+            if chart_items:
+                # auto-sort descending
+                chart_items.sort(key=lambda x: x["value"], reverse=True)
+                
+                return {
+                    "type": "bar",
+                    "title": f"{y_label} by {x_label}",
+                    "data": chart_items[:15], # Limit to top 15 for readability
+                    "xKey": "name",
+                    "yKey": "value",
+                    "xAxisLabel": x_label,
+                    "yAxisLabel": y_label
+                }
+        except Exception as e:
+            print(f"Error generating chart data: {e}")
+            return None
+            
+        return None
+
+    @staticmethod
+    def prepare_raw_data(features: List[Dict]) -> List[Dict]:
+        """Cleans feature properties for display in the raw data table."""
+        raw_data = []
+        if not features:
+            return raw_data
+            
+        for f in features:
+            props = f.get("properties", {}).copy()
+            # Serialize
+            props = ResponseFormatter._serialize_properties(props)
+            
+            # Remove system/visual properties
+            for key in ["geom", "geometry", "style", "layer_name", "layer_id", "choropleth", "fillColor", "color"]:
+                props.pop(key, None)
+            raw_data.append(props)
+            
+        return raw_data
+
+    @staticmethod
+    def format_geojson_layer(query: str, geojson: Dict[str, Any], features: List[Dict], layer_name: str, layer_emoji: str = "📍", point_style: Optional[str] = None, admin_levels: Optional[List[str]] = None) -> tuple[Dict[str, Any], str, str]:
+        """
+        styles the GeoJSON layer and generates metadata (ID, Name, Choropleth).
+        
+        Args:
+            point_style: "icon" for emoji markers, "circle" for simple colored circles, None for auto-detect
+        """
+        
+        # 0. Serialize properties to avoid datetime errors
+        if features:
+            for f in features:
+                if "properties" in f:
+                    f["properties"] = ResponseFormatter._serialize_properties(f["properties"])
+
+        # 2. Random/Distinct Colors
+        # Palette of distinct colors (avoiding pure blue which is default)
+        palette = [
+            "#E63946", # Red
+            "#F4A261", # Orange
+            "#2A9D8F", # Teal
+            "#E9C46A", # Yellow
+            "#9C6644", # Brown
+            "#D62828", # Dark Red
+            "#8338EC", # Purple
+            "#3A86FF", # Blue-ish (but distinct)
+            "#FB5607", # Orange-Red
+            "#FF006E", # Pink
+        ]
+        
+        # Deterministic color based on query hash to keep it stable for same query
+        color_idx = abs(hash(query)) % len(palette)
+        layer_color = palette[color_idx]
+
+        # Choropleth Logic
+        # 1. Identify valid numeric column
+        choropleth_col = None
+        if features:
+            sample = features[0].get("properties", {})
+            valid_numerics = [
+                k for k, v in sample.items() 
+                if isinstance(v, (int, float)) 
+                and k not in ["layer_id", "style"] 
+                and not k.endswith("_code") 
+                and not k.endswith("_id")
+            ]
+            
+            # Prioritize 'population', 'area', 'count'
+            priority_cols = ["population", "pop", "count", "num", "density", "area_sqkm", "area"]
+            
+            for p in priority_cols:
+                matches = [c for c in valid_numerics if p in c]
+                if matches:
+                    choropleth_col = matches[0]
+                    break
+            
+            # Fallback to first numeric
+            if not choropleth_col and valid_numerics:
+                choropleth_col = valid_numerics[0]
+
+        # 2. Enable if appropriate
+        if choropleth_col:
+            # Check if values actually vary
+            values = [f["properties"].get(choropleth_col, 0) for f in features]
+            if len(set(values)) > 1:
+                geojson["properties"]["choropleth"] = {
+                    "enabled": True, 
+                    "palette": "viridis",
+                    "column": choropleth_col,
+                    "scale": "log" if "pop" in choropleth_col or "density" in choropleth_col else "linear"
+                }
+        else:
+             # Apply random color if NOT a choropleth
+             geojson["properties"]["style"] = {
+                 "color": layer_color,
+                 "fillColor": layer_color,
+                 "opacity": 0.8,
+                 "fillOpacity": 0.4
+             }
+        
+        layer_id = str(uuid.uuid4())[:8]
+        geojson["properties"]["layer_name"] = layer_name
+        geojson["properties"]["layer_id"] = layer_id
+        
+        # Add Point Marker Configuration
+        # Use pointStyle to determine whether to show icon or circle
+        marker_icon = None
+        marker_style = "circle"  # default
+        
+        if point_style == "icon":
+            # Use emoji icon for categorical POI
+            marker_icon = layer_emoji
+            marker_style = "icon"
+        elif point_style == "circle":
+            # Use simple circle for large datasets or density viz
+            marker_icon = None
+            marker_style = "circle"
+        else:
+            # Auto-detect: default to icon for now (backward compatibility)
+            marker_icon = layer_emoji
+            marker_style = "icon"
+        
+        geojson["properties"]["pointMarker"] = {
+            "icon": marker_icon,
+            "style": marker_style,
+            "color": layer_color,
+            "size": 32
+        }
+        
+        return geojson, layer_id, layer_name
+
+    @staticmethod
+    def generate_data_summary(features: List[Dict]) -> str:
+        """Generates a text summary of the features for the LLM explanation context."""
+        if features:
+            sample_names = []
+            for f in features[:5]:
+                props = f.get("properties", {})
+                name = props.get("adm3_name") or props.get("adm2_name") or props.get("adm1_name") or props.get("name") or "Feature"
+                area = props.get("area_sqkm")
+                if area:
+                    sample_names.append(f"{name} ({float(area):.1f} km²)")
+                else:
+                    sample_names.append(name)
+            return f"Found {len(features)} features. Sample: {', '.join(sample_names)}"
+            return f"Found {len(features)} features. Sample: {', '.join(sample_names)}"
+        else:
+            return "No features found matching the query."
+
+    @staticmethod
+    def _serialize_properties(properties: Dict[str, Any]) -> Dict[str, Any]:
+        """Recursively converts datetime/date objects to strings for JSON serialization."""
+        from datetime import datetime, date
+        
+        serialized = {}
+        for k, v in properties.items():
+            if isinstance(v, (datetime, date)):
+                serialized[k] = v.isoformat()
+            elif isinstance(v, dict):
+                serialized[k] = ResponseFormatter._serialize_properties(v)
+            elif isinstance(v, list):
+                serialized[k] = [
+                    x.isoformat() if isinstance(x, (datetime, date)) else x 
+                    for x in v
+                ]
+            else:
+                serialized[k] = v
+        return serialized

docker-compose.yml

@@ -0,0 +1,14 @@
+version: '3.8'
+
+services:
+  app:
+    build: .
+    image: geoquery:latest
+    ports:
+      - "8000:8000"
+    environment:
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+    volumes:
+      # Optional: Mount data directory if you want to persist changes or add data
+      # - ./backend/data:/app/backend/data
+      - ./backend/data/custom:/app/backend/data/custom