feat: add GET /inspect/explain endpoint for multi-LLM interpretability

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

inspection/router.py

@@ -4,9 +4,10 @@ All endpoints are on-demand — they do not affect the main inference pipeline.
 Endpoints are mounted at /inspect in app.py.
 """
 
+import asyncio
 import logging
 from pathlib import Path
-from typing import Optional
+from typing import Dict, Optional
 
 from fastapi import APIRouter, HTTPException, Query
 from fastapi.responses import JSONResponse, Response
@@ -764,3 +765,130 @@ async def get_pointcloud(
         )
 
     return JSONResponse(result)
+
+
+# ── Explainability (Multi-LLM) ───────────────────────────────────
+
+# Per-(job_id, track_id) locks to prevent duplicate concurrent LLM calls
+_explain_locks: Dict[tuple, asyncio.Lock] = {}
+
+
+def _get_explain_lock(job_id: str, track_id: str) -> asyncio.Lock:
+    """Get or create an asyncio lock for a (job_id, track_id) pair."""
+    key = (job_id, track_id)
+    if key not in _explain_locks:
+        _explain_locks[key] = asyncio.Lock()
+    return _explain_locks[key]
+
+
+@router.get("/explain/{job_id}/{track_id}")
+async def explain_track(job_id: str, track_id: str):
+    """Generate a multi-LLM interpretability tree for a tracked object.
+
+    Calls GPT-4o (primary) to generate a hierarchical feature tree,
+    then Claude + Gemini (validators) in parallel to validate each feature.
+    Results are cached per (job_id, track_id).
+    """
+    from jobs.storage import get_explanation, set_explanation
+    from models.isr.utils import crop_and_encode, encode_frame
+    from inspection.frames import extract_frame
+
+    job = _get_job_or_404(job_id)
+
+    # Check cache first
+    cached = get_explanation(job_id, track_id)
+    if cached:
+        return JSONResponse(cached)
+
+    # Acquire per-track lock to prevent duplicate LLM calls
+    lock = _get_explain_lock(job_id, track_id)
+    async with lock:
+        # Re-check cache after acquiring lock
+        cached = get_explanation(job_id, track_id)
+        if cached:
+            return JSONResponse(cached)
+
+        # Validate OpenAI key is available
+        import os
+        if not os.environ.get("OPENAI_API_KEY"):
+            raise HTTPException(status_code=503, detail="OpenAI API key not configured")
+
+        storage = get_job_storage()
+
+        # Parse track_id
+        instance_id = _parse_track_id(track_id)
+
+        # Find the best frame for this track (largest bbox area)
+        best_frame_idx = None
+        best_area = 0
+        best_track = None
+
+        with storage._lock:
+            frames = storage._tracks.get(job_id, {})
+            for fidx in sorted(frames.keys(), reverse=True):
+                for det in frames[fidx]:
+                    tid = det.get("instance_id")
+                    tid_str = det.get("track_id")
+                    if (tid is not None and tid == instance_id) or tid_str == track_id:
+                        bbox = det.get("bbox")
+                        if bbox:
+                            area = (bbox[2] - bbox[0]) * (bbox[3] - bbox[1])
+                            if area > best_area:
+                                best_area = area
+                                best_frame_idx = fidx
+                                best_track = dict(det)
+
+        if best_frame_idx is None or best_track is None:
+            raise HTTPException(status_code=404, detail=f"Track {track_id} not found in any frame.")
+
+        # Extract frame
+        input_path = job.input_video_path
+        if not input_path or not Path(input_path).exists():
+            raise HTTPException(status_code=404, detail="Input video not found on disk.")
+
+        frame = await asyncio.to_thread(extract_frame, input_path, best_frame_idx)
+
+        # Encode images
+        crop_b64 = crop_and_encode(frame, best_track["bbox"], max_dim=512, quality=80)
+        if not crop_b64:
+            raise HTTPException(status_code=422, detail="Failed to crop track from frame.")
+
+        frame_b64 = encode_frame(frame, max_dim=1024, quality=70)
+        if not frame_b64:
+            raise HTTPException(status_code=422, detail="Failed to encode frame.")
+
+        # Get mission query (job.queries is List[str])
+        mission = ", ".join(job.queries) if job.queries else "general surveillance"
+
+        # Build metadata
+        metadata = {
+            "label": best_track.get("label", "unknown"),
+            "score": best_track.get("score", 0),
+            "speed_kph": best_track.get("speed_kph", 0),
+            "direction_clock": best_track.get("direction_clock", "unknown"),
+            "depth_rel": best_track.get("depth_rel"),
+            "depth_est_m": best_track.get("depth_est_m"),
+            "angle_deg": best_track.get("angle_deg"),
+            "bbox": best_track.get("bbox"),
+        }
+
+        # Run explainer
+        from models.isr.explainer import ISRExplainer
+
+        explainer = ISRExplainer()
+        try:
+            result = await asyncio.wait_for(
+                explainer.explain(crop_b64, frame_b64, metadata, mission),
+                timeout=30.0,
+            )
+        except asyncio.TimeoutError:
+            raise HTTPException(status_code=504, detail="Explanation timed out (30s)")
+        except ValueError as e:
+            raise HTTPException(status_code=502, detail=str(e))
+
+        # Add track_id to result
+        result["track_id"] = track_id
+
+        # Cache and return
+        set_explanation(job_id, track_id, result)
+        return JSONResponse(result)