docs: implementation plan for AOI advisor (Claude-powered region insight)

8 tasks: dependency, config/model, advisor module, API endpoint,
frontend API wrapper, HTML/CSS card, app.js wiring, startup logging.

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/plans/2026-04-06-aoi-advisor.md

@@ -0,0 +1,528 @@
+# AOI Advisor Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a Claude-powered advisor that recommends analysis timeframes and indicator priorities when a user places an AOI.
+
+**Architecture:** Frontend calls `POST /api/aoi-advice` after AOI placement. Backend endpoint calls Claude Haiku with coordinates and available indicators. Response is structured JSON that populates an advice card and auto-fills date pickers. Graceful degradation if API key missing or call fails.
+
+**Tech Stack:** Anthropic Python SDK (`anthropic`), FastAPI endpoint, vanilla JS frontend.
+
+**Prerequisite:** The AOI click-to-place plan must be implemented first (the advisor wires into the `onAoiChange` callback from that plan).
+
+---
+
+## File Structure
+
+| File | Role | Action |
+|------|------|--------|
+| `pyproject.toml` | Dependencies | Add `anthropic` |
+| `app/config.py` | Config | Add `ANTHROPIC_API_KEY` |
+| `app/models.py` | Request model | Add `AoiAdviceRequest` |
+| `app/advisor.py` | Claude API call | Create: prompt builder + API call |
+| `app/main.py` | Route registration | Add `/api/aoi-advice` endpoint |
+| `frontend/js/api.js` | API wrapper | Add `getAoiAdvice()` |
+| `frontend/index.html` | Advisor card HTML | Add card between size toggles and dates |
+| `frontend/css/merlx.css` | Card styles | Add `.aoi-advisor` styles |
+| `frontend/js/app.js` | Wire advisor | Call API on AOI change, populate card, auto-fill dates |
+
+---
+
+### Task 1: Add anthropic dependency
+
+**Files:**
+- Modify: `pyproject.toml:6-27`
+
+- [ ] **Step 1: Add anthropic to dependencies**
+
+In `pyproject.toml`, add `"anthropic>=0.40.0",` to the dependencies list, after the `"openeo>=0.28.0",` line:
+
+```toml
+    "openeo>=0.28.0",
+    "anthropic>=0.40.0",
+]
+```
+
+- [ ] **Step 2: Install the dependency**
+
+```bash
+pip install anthropic>=0.40.0
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add pyproject.toml
+git commit -m "chore: add anthropic SDK dependency"
+```
+
+---
+
+### Task 2: Add config and request model
+
+**Files:**
+- Modify: `app/config.py:20-21`
+- Modify: `app/models.py:149` (end of file)
+
+- [ ] **Step 1: Add ANTHROPIC_API_KEY to config**
+
+In `app/config.py`, add after the `OPENEO_CLIENT_SECRET` line (line 20):
+
+```python
+# Anthropic API key for AOI advisor (Claude-powered region insight).
+ANTHROPIC_API_KEY: str | None = os.environ.get("ANTHROPIC_API_KEY")
+```
+
+- [ ] **Step 2: Add AoiAdviceRequest model**
+
+In `app/models.py`, add at the end of the file (after `IndicatorMeta`):
+
+```python
+class AoiAdviceRequest(BaseModel):
+    bbox: list[float] = Field(min_length=4, max_length=4)
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add app/config.py app/models.py
+git commit -m "feat: add ANTHROPIC_API_KEY config and AoiAdviceRequest model"
+```
+
+---
+
+### Task 3: Create advisor module
+
+**Files:**
+- Create: `app/advisor.py`
+
+- [ ] **Step 1: Create app/advisor.py**
+
+```python
+"""AOI Advisor — Claude-powered region insight for analysis recommendations."""
+from __future__ import annotations
+
+import json
+import logging
+from datetime import date
+
+from app.config import ANTHROPIC_API_KEY
+
+logger = logging.getLogger(__name__)
+
+_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: Water extent (MNDWI) from Sentinel-2. Detects flooding, drought, reservoir changes.
+- sar: Radar backscatter from Sentinel-1. Detects ground surface changes, flooding, construction.
+- buildup: Settlement extent (NDBI) 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 is relevant here"
+}"""
+
+_EMPTY_RESPONSE = {
+    "context": None,
+    "recommended_start": None,
+    "recommended_end": None,
+    "indicator_priorities": None,
+    "reasoning": None,
+}
+
+
+async def get_aoi_advice(bbox: list[float]) -> dict:
+    """Call Claude to get region-aware analysis recommendations.
+
+    Returns structured advice dict. On any failure, returns all-null dict.
+    """
+    if not ANTHROPIC_API_KEY:
+        logger.warning("ANTHROPIC_API_KEY not set — skipping AOI advisor")
+        return _EMPTY_RESPONSE
+
+    center_lng = (bbox[0] + bbox[2]) / 2
+    center_lat = (bbox[1] + bbox[3]) / 2
+    today = date.today().isoformat()
+
+    user_prompt = (
+        f"Location: {center_lat:.4f}°N, {center_lng:.4f}°E\n"
+        f"Current date: {today}\n"
+        f"Recommend an analysis timeframe and indicator priorities for this area."
+    )
+
+    try:
+        import anthropic
+
+        client = anthropic.AsyncAnthropic(api_key=ANTHROPIC_API_KEY)
+        message = await client.messages.create(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=500,
+            temperature=0,
+            system=_SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": user_prompt}],
+        )
+
+        raw = message.content[0].text
+        advice = json.loads(raw)
+
+        # Validate expected keys are present
+        for key in ("context", "recommended_start", "recommended_end", "indicator_priorities", "reasoning"):
+            if key not in advice:
+                logger.warning("AOI advisor response missing key: %s", key)
+                return _EMPTY_RESPONSE
+
+        # Validate dates are parseable
+        date.fromisoformat(advice["recommended_start"])
+        date.fromisoformat(advice["recommended_end"])
+
+        # Filter indicator_priorities to only known indicators
+        valid_ids = {"ndvi", "water", "sar", "buildup"}
+        advice["indicator_priorities"] = [
+            i for i in advice["indicator_priorities"] if i in valid_ids
+        ]
+
+        return advice
+
+    except Exception as exc:
+        logger.warning("AOI advisor failed: %s", exc)
+        return _EMPTY_RESPONSE
+```
+
+- [ ] **Step 2: Verify it imports cleanly**
+
+```bash
+cd /Users/kmini/GitHub/Aperture && python3 -c "from app.advisor import get_aoi_advice; print('OK')"
+```
+
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add app/advisor.py
+git commit -m "feat: add advisor module — Claude-powered region insight"
+```
+
+---
+
+### Task 4: Add API endpoint
+
+**Files:**
+- Modify: `app/main.py:15-16` (imports)
+- Modify: `app/main.py:57` (after router includes, before health endpoint)
+
+- [ ] **Step 1: Add imports**
+
+In `app/main.py`, add to the existing imports (after line 15):
+
+```python
+from app.advisor import get_aoi_advice
+from app.models import AoiAdviceRequest
+```
+
+- [ ] **Step 2: Add the endpoint**
+
+In `app/main.py`, add after the `app.include_router(auth_router)` line (line 57) and before the `@app.get("/health")` line:
+
+```python
+    @app.post("/api/aoi-advice")
+    async def aoi_advice(request: AoiAdviceRequest, email: str = Depends(get_current_user)):
+        return await get_aoi_advice(request.bbox)
+```
+
+- [ ] **Step 3: Verify the server starts**
+
+```bash
+cd /Users/kmini/GitHub/Aperture && python3 -c "from app.main import create_app; app = create_app(); print('OK')"
+```
+
+Expected: `OK`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add app/main.py
+git commit -m "feat: add /api/aoi-advice endpoint"
+```
+
+---
+
+### Task 5: Add frontend API function
+
+**Files:**
+- Modify: `frontend/js/api.js:134` (after `spatialUrl` function)
+
+- [ ] **Step 1: Add getAoiAdvice function**
+
+In `frontend/js/api.js`, add before the `/* ── Auth */` section (before line 136):
+
+```javascript
+/* ── AOI Advisor ───────────────────────────────────────── */
+
+/**
+ * Get Claude-powered region insight for an AOI.
+ * @param {Array<number>} bbox - [minLon, minLat, maxLon, maxLat]
+ * @returns {Promise<{context, recommended_start, recommended_end, indicator_priorities, reasoning} | null>}
+ */
+export async function getAoiAdvice(bbox) {
+  try {
+    const result = await apiFetch('/api/aoi-advice', {
+      method: 'POST',
+      body: JSON.stringify({ bbox }),
+    });
+    // Treat all-null as failure
+    if (!result || !result.context) return null;
+    return result;
+  } catch {
+    return null;
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/js/api.js
+git commit -m "feat: add getAoiAdvice API wrapper"
+```
+
+---
+
+### Task 6: Add advisor card HTML and CSS
+
+**Files:**
+- Modify: `frontend/index.html` (after the size toggles `aoi-area-display` div, before the `<hr class="divider" />`)
+- Modify: `frontend/css/merlx.css` (after `.aoi-area-display` styles)
+
+- [ ] **Step 1: Add advisor card HTML**
+
+In `frontend/index.html`, add after the `<div id="aoi-area-display"...></div>` line and before the `<hr class="divider" />` line:
+
+```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>
+          <p id="advisor-reasoning" class="aoi-advisor-text" style="font-style: italic;"></p>
+          <div id="advisor-priorities" class="aoi-advisor-priorities"></div>
+        </div>
+      </div>
+```
+
+- [ ] **Step 2: Add advisor CSS**
+
+In `frontend/css/merlx.css`, add after the `.aoi-area-display` block:
+
+```css
+/* AOI Advisor card */
+.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);
+  animation: pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+.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: 0 0 var(--space-3) 0;
+}
+
+.aoi-advisor-meta {
+  font-family: var(--font-data);
+  font-size: var(--text-xs);
+  color: var(--ink-muted);
+  margin: 0 0 var(--space-2) 0;
+}
+
+.aoi-advisor-priorities {
+  display: flex;
+  gap: var(--space-2);
+  flex-wrap: wrap;
+}
+
+.aoi-advisor-pill {
+  font-family: var(--font-data);
+  font-size: 10px;
+  padding: 2px 8px;
+  border-radius: 10px;
+  background: var(--iris-dim);
+  color: var(--iris-dark);
+  border: 1px solid var(--iris);
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/index.html frontend/css/merlx.css
+git commit -m "feat: add advisor card HTML and CSS styles"
+```
+
+---
+
+### Task 7: Wire advisor into app.js
+
+**Files:**
+- Modify: `frontend/js/app.js:7` (imports)
+- Modify: `frontend/js/app.js` (inside `setupDefineArea()` function)
+
+This task assumes the click-to-place plan has been implemented, so `setupDefineArea()` uses the rewritten version from that plan.
+
+- [ ] **Step 1: Update imports**
+
+In `frontend/js/app.js`, update the api.js import line to add `getAoiAdvice`:
+
+Change:
+
+```javascript
+import { submitJob, getJob, requestMagicLink, verifyToken, listJobs } from './api.js';
+```
+
+to:
+
+```javascript
+import { submitJob, getJob, requestMagicLink, verifyToken, listJobs, getAoiAdvice } from './api.js';
+```
+
+- [ ] **Step 2: Add advisor wiring inside setupDefineArea**
+
+In `frontend/js/app.js`, inside the `setupDefineArea()` function, find the `initAoiMap('map', (bbox) => {` callback. Replace the entire callback with:
+
+```javascript
+    initAoiMap('map', async (bbox) => {
+      _currentBbox = bbox;
+      if (bbox) {
+        const area = _bboxAreaKm2(bbox);
+        areaDisplay.style.display = '';
+        areaDisplay.textContent = `${Math.round(area).toLocaleString()} km²`;
+        areaDisplay.className = 'aoi-area-display';
+
+        // Show advisor loading, disable Continue
+        const advisorEl = document.getElementById('aoi-advisor');
+        const advisorLoading = document.getElementById('aoi-advisor-loading');
+        const advisorContent = document.getElementById('aoi-advisor-content');
+        advisorEl.style.display = '';
+        advisorLoading.style.display = '';
+        advisorContent.style.display = 'none';
+        continueBtn.disabled = true;
+
+        // Fetch advice
+        const advice = await getAoiAdvice(bbox);
+
+        if (advice) {
+          // Populate card
+          document.getElementById('advisor-context').textContent = advice.context;
+          document.getElementById('advisor-dates').textContent =
+            `Recommended: ${advice.recommended_start} to ${advice.recommended_end}`;
+          document.getElementById('advisor-reasoning').textContent = advice.reasoning;
+
+          // Indicator priority pills
+          const pillsEl = document.getElementById('advisor-priorities');
+          pillsEl.innerHTML = '';
+          const names = { ndvi: 'NDVI', water: 'Water', sar: 'SAR', buildup: 'Built-up' };
+          for (const id of (advice.indicator_priorities || [])) {
+            const pill = document.createElement('span');
+            pill.className = 'aoi-advisor-pill';
+            pill.textContent = names[id] || id;
+            pillsEl.appendChild(pill);
+          }
+
+          // Auto-fill date pickers
+          document.getElementById('date-start').value = advice.recommended_start;
+          document.getElementById('date-end').value = advice.recommended_end;
+
+          // Show content, hide loading
+          advisorLoading.style.display = 'none';
+          advisorContent.style.display = '';
+        } else {
+          // No advice — hide card silently
+          advisorEl.style.display = 'none';
+        }
+
+        continueBtn.disabled = false;
+      } else {
+        areaDisplay.style.display = 'none';
+        document.getElementById('aoi-advisor').style.display = 'none';
+        continueBtn.disabled = true;
+      }
+    });
+```
+
+Note: the callback is now `async` — this is fine because MapLibre click callbacks don't use the return value.
+
+- [ ] **Step 3: Verify the full flow**
+
+1. Open the app, log in, navigate to Define Area
+2. Click on the map → AOI appears, "Analyzing region..." shows
+3. After 1-3 seconds, advice card populates with context, dates, priorities
+4. Date pickers are auto-filled with recommended dates
+5. Continue button enables after advice loads
+6. If `ANTHROPIC_API_KEY` is not set: advice card hides silently, Continue enables immediately
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/js/app.js
+git commit -m "feat: wire AOI advisor into Define Area page"
+```
+
+---
+
+### Task 8: Add startup log for API key status
+
+**Files:**
+- Modify: `app/main.py:28-32` (lifespan startup logging)
+
+- [ ] **Step 1: Add Anthropic key status to startup log**
+
+In `app/main.py`, inside the `lifespan` function, after the CDSE credential check (after line 32), add:
+
+```python
+        from app.config import ANTHROPIC_API_KEY
+        if ANTHROPIC_API_KEY:
+            print(f"[Aperture] Anthropic API key configured (AOI advisor enabled)")
+        else:
+            print("[Aperture] Anthropic API key not set — AOI advisor disabled")
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add app/main.py
+git commit -m "chore: log Anthropic API key status on startup"
+```