docs: spec for AOI advisor — Claude-powered region insight

LLM-driven advice card that recommends timeframe and indicator
priorities when user places an AOI. Uses Claude Haiku via backend proxy.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

docs/superpowers/specs/2026-04-06-aoi-advisor-design.md

@@ -0,0 +1,294 @@
+# AOI Advisor — Claude-Powered Region Insight
+
+**Date:** 2026-04-06
+**Status:** Approved
+**Depends on:** AOI click-to-place redesign (2026-04-06)
+
+## Summary
+
+When a user places an AOI on the map, the backend calls the Claude API to generate a brief region-aware recommendation: what timeframe is interesting for the EO products in that area, and which indicators to prioritize. The advice auto-fills the date pickers and appears as a card in the sidebar. The user can adjust before continuing.
+
+## Motivation
+
+Aperture users (humanitarian programme teams) often don't know the optimal analysis window for a given region. A rainy season, a drought, a displacement event — these affect which time window and indicators will produce the most useful results. A lightweight Claude call with the coordinates can provide immediate, contextual guidance that improves analysis quality.
+
+## User Flow
+
+1. User places AOI (click or geocode) → AOI appears on map
+2. Sidebar shows "Analyzing region..." with a loading indicator
+3. Continue button is disabled during loading
+4. Frontend sends `POST /api/aoi-advice` with the bbox
+5. Backend calls Claude API, returns structured advice
+6. Frontend displays advice card, auto-fills date pickers with recommended window
+7. User reads advice, adjusts dates/indicators if needed, clicks Continue
+
+If the Claude API call fails (missing key, timeout, error), the advice card is skipped silently — Continue enables immediately and the user proceeds without guidance.
+
+## Advice Card UI
+
+Appears in the sidebar between the AOI size toggles and the date pickers:
+
+```
+┌─────────────────────────────────┐
+│ Region Insight                  │
+│                                 │
+│ This area in eastern Chad near  │
+│ the Sudanese border has seen    │
+│ significant displacement since  │
+│ mid-2024. The rainy season runs │
+│ June–October.                   │
+│                                 │
+│ Recommended: Jun 2025 – Apr 2026│
+│ Priority: NDVI, Water, SAR      │
+└─────────────────────────────────┘
+```
+
+- Styled with MERLx warm surface background (`--shell-warm`), subtle border
+- Uses `--font-ui` for text, `--text-xs` size
+- "Region Insight" heading in `--font-ui` bold, `--text-sm`
+- "Recommended" line in `--font-data`
+- "Priority" line lists indicator names as small pill badges
+- No dismiss button — card stays visible until AOI changes
+- When AOI is re-placed (new click or geocode), card resets to loading state and fetches again
+
+## API Endpoint
+
+### `POST /api/aoi-advice`
+
+**Request:**
+```json
+{
+  "bbox": [32.4, 15.6, 32.65, 15.8]
+}
+```
+
+**Response (success):**
+```json
+{
+  "context": "This area covers parts of North Khartoum, Sudan. The region has experienced conflict-related displacement since April 2023. The rainy season runs June through October, with peak vegetation in September.",
+  "recommended_start": "2025-04-01",
+  "recommended_end": "2026-04-01",
+  "indicator_priorities": ["ndvi", "water", "sar", "buildup"],
+  "reasoning": "NDVI captures drought and agricultural impact. Water monitors Nile flooding risk. SAR detects ground changes from conflict damage. Built-up tracks displacement-driven settlement changes."
+}
+```
+
+**Response (failure):**
+```json
+{
+  "context": null,
+  "recommended_start": null,
+  "recommended_end": null,
+  "indicator_priorities": null,
+  "reasoning": null
+}
+```
+
+Frontend treats all-null response same as a failed request: skip the card, enable Continue.
+
+### Authentication
+
+The endpoint requires the same user auth token as other `/api/` endpoints (Bearer header).
+
+## Backend Implementation
+
+### Config
+
+New environment variable: `ANTHROPIC_API_KEY`
+
+In `app/config.py`:
+```python
+ANTHROPIC_API_KEY: str | None = os.environ.get("ANTHROPIC_API_KEY")
+```
+
+### New Module: `app/advisor.py`
+
+Single async function `get_aoi_advice(bbox: list[float]) -> dict` that:
+
+1. Computes center point from bbox
+2. Builds a prompt with center coordinates, current date, and indicator descriptions
+3. Calls Claude API (`claude-haiku-4-5-20251001` for speed/cost) with structured JSON output
+4. Parses response, validates dates, returns the dict
+5. On any error: logs warning, returns all-null dict
+
+### Claude Prompt
+
+**System prompt:**
+```
+You are a remote sensing advisor for humanitarian programme teams. Given a geographic location, provide a brief analysis recommendation.
+
+Available Earth observation indicators:
+- NDVI: Vegetation health from Sentinel-2. Detects drought, crop stress, deforestation.
+- Water (MNDWI): Water extent from Sentinel-2. Detects flooding, drought, reservoir changes.
+- SAR: Radar backscatter from Sentinel-1. Detects ground surface changes, flooding, construction.
+- Built-up (NDBI): Settlement extent from Sentinel-2. Detects urban growth, displacement camps.
+
+Coverage: East Africa region. Resolution: 100m. Max analysis window: 3 years.
+
+Respond with JSON only, no markdown. Structure:
+{
+  "context": "1-3 sentences about this region and recent relevant events",
+  "recommended_start": "YYYY-MM-DD",
+  "recommended_end": "YYYY-MM-DD",
+  "indicator_priorities": ["indicator_id", ...],
+  "reasoning": "1 sentence per indicator explaining why it's relevant here"
+}
+```
+
+**User prompt:**
+```
+Location: {center_lat}°N, {center_lng}°E
+Current date: {today}
+Recommend an analysis timeframe and indicator priorities for this area.
+```
+
+**Model:** `claude-haiku-4-5-20251001` (fast, cheap, sufficient for this structured task)
+**Temperature:** 0
+**Max tokens:** 500
+
+### Route
+
+New route in `app/main.py` or a new router file `app/routes/advisor.py`:
+
+```python
+@app.post("/api/aoi-advice")
+async def aoi_advice(request: AoiAdviceRequest, user = Depends(get_current_user)):
+    result = await get_aoi_advice(request.bbox)
+    return result
+```
+
+### Request Model
+
+In `app/models.py`:
+```python
+class AoiAdviceRequest(BaseModel):
+    bbox: list[float]
+```
+
+## Frontend Implementation
+
+### Changes to `frontend/js/map.js`
+
+No changes. The map module just places the AOI and fires the callback.
+
+### Changes to `frontend/js/api.js`
+
+New function:
+```javascript
+export async function getAoiAdvice(bbox) {
+  const res = await fetch('/api/aoi-advice', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+    body: JSON.stringify({ bbox }),
+  });
+  if (!res.ok) return null;
+  return res.json();
+}
+```
+
+### Changes to `frontend/index.html`
+
+Add the advice card placeholder between the size toggles and the date pickers:
+
+```html
+<!-- AOI Advisor -->
+<div id="aoi-advisor" class="aoi-advisor" style="display:none;">
+  <div id="aoi-advisor-loading" class="aoi-advisor-loading">
+    Analyzing region…
+  </div>
+  <div id="aoi-advisor-content" style="display:none;">
+    <div class="aoi-advisor-heading">Region Insight</div>
+    <p id="advisor-context" class="aoi-advisor-text"></p>
+    <p id="advisor-dates" class="aoi-advisor-meta"></p>
+    <div id="advisor-priorities" class="aoi-advisor-priorities"></div>
+  </div>
+</div>
+```
+
+### Changes to `frontend/js/app.js`
+
+In the `onAoiChange` callback inside `setupDefineArea()`:
+
+1. When bbox is set: show advisor card in loading state, disable Continue
+2. Call `getAoiAdvice(bbox)`
+3. On success: populate card, auto-fill date pickers, enable Continue
+4. On failure/null: hide advisor card, enable Continue immediately
+
+### Changes to `frontend/css/merlx.css`
+
+New styles for the advisor card:
+
+```css
+.aoi-advisor {
+  background: var(--shell-warm);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: var(--space-5);
+  margin-top: var(--space-3);
+}
+
+.aoi-advisor-loading {
+  font-family: var(--font-ui);
+  font-size: var(--text-xs);
+  color: var(--ink-muted);
+}
+
+.aoi-advisor-heading {
+  font-family: var(--font-ui);
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: var(--ink);
+  margin-bottom: var(--space-2);
+}
+
+.aoi-advisor-text {
+  font-family: var(--font-ui);
+  font-size: var(--text-xs);
+  color: var(--ink);
+  line-height: 1.5;
+  margin-bottom: var(--space-3);
+}
+
+.aoi-advisor-meta {
+  font-family: var(--font-data);
+  font-size: var(--text-xs);
+  color: var(--ink-muted);
+  margin-bottom: var(--space-2);
+}
+
+.aoi-advisor-priorities {
+  display: flex;
+  gap: var(--space-2);
+  flex-wrap: wrap;
+}
+```
+
+## Dependencies
+
+New Python package: `anthropic` (add to `pyproject.toml` dependencies).
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `app/config.py` | Add `ANTHROPIC_API_KEY` |
+| `app/models.py` | Add `AoiAdviceRequest` model |
+| `app/advisor.py` | New module: `get_aoi_advice()` function |
+| `app/main.py` | Add `/api/aoi-advice` route |
+| `pyproject.toml` | Add `anthropic` dependency |
+| `frontend/index.html` | Add advisor card HTML |
+| `frontend/js/api.js` | Add `getAoiAdvice()` function |
+| `frontend/js/app.js` | Wire advisor into AOI placement flow |
+| `frontend/css/merlx.css` | Add advisor card styles |
+
+## What This Does NOT Change
+
+- AOI placement mechanics (click-to-place from prior spec)
+- Indicator selection page (user still picks which indicators to run)
+- Job submission payload structure
+- Backend EO processing pipeline
+- Results display
+
+## Cost Estimate
+
+Claude Haiku at ~500 tokens per call: approximately $0.001 per AOI advice request. Negligible.