fix(agents,api): surface fallback model failures with classified details (#335)

app/core/exceptions.py

@@ -10,6 +10,7 @@
 
 from app.core.logging import get_logger
 from app.core.problem_details import (
+    AGENT_FALLBACK_EXHAUSTED_CODE,
     EMBEDDING_AUTH_CODE,
     ERROR_TYPES,
     ProblemDetailResponse,
@@ -40,20 +41,27 @@ def __init__(
         code: str = "INTERNAL_ERROR",
         status_code: int = 500,
         details: dict[str, Any] | None = None,
+        extensions: dict[str, Any] | None = None,
     ) -> None:
         """Initialize application error.
 
         Args:
             message: Human-readable error message.
             code: Machine-readable error code.
             status_code: HTTP status code.
-            details: Additional error context.
+            details: Additional error context. LOG-ONLY — the exception
+                handler never copies it into the response body (it may carry
+                internals).
+            extensions: RFC 7807 extension members the handler DOES merge
+                into the problem+json response body (#335). Only put
+                client-safe, already-sanitized data here.
         """
         super().__init__(message)
         self.message = message
         self.code = code
         self.status_code = status_code
         self.details = details or {}
+        self.extensions = extensions or {}
 
     @property
     def title(self) -> str:
@@ -254,6 +262,41 @@ def __init__(
         )
 
 
+class AgentFallbackExhaustedError(ForecastLabError):
+    """502 — every model in the agent's fallback chain failed (issue #335).
+
+    Raised when the PydanticAI ``FallbackModel`` chain (or a single configured
+    model) fails with provider-API errors on every leg. Mirrors
+    :class:`EmbeddingProviderAuthError`: keeps the public status at 502 (an
+    upstream failure from the caller's perspective) and emits a
+    *machine-readable* ``AGENT_FALLBACK_EXHAUSTED`` problem ``type``/``code``
+    so clients can classify it. The per-model classified failures ride the
+    response-visible ``extensions`` channel as a ``failures`` member —
+    ``details`` stays log-only by design.
+    """
+
+    error_type_uri: str = ERROR_TYPES[AGENT_FALLBACK_EXHAUSTED_CODE]
+
+    def __init__(
+        self,
+        message: str,
+        failures: list[dict[str, Any]],
+    ) -> None:
+        """Initialize with the human summary and classified per-model legs.
+
+        Args:
+            message: Human-actionable summary (already secret-safe).
+            failures: Serialized ``ModelFailureDetail`` dicts — sanitized
+                upstream by the classifier; surfaced verbatim to the client.
+        """
+        super().__init__(
+            message=message,
+            code=AGENT_FALLBACK_EXHAUSTED_CODE,
+            status_code=502,
+            extensions={"failures": failures},
+        )
+
+
 # =============================================================================
 # Exception Handlers (RFC 7807)
 # =============================================================================
@@ -287,6 +330,7 @@ async def forecastlab_exception_handler(
         title=exc.title,
         detail=exc.message,
         error_code=exc.code,
+        extensions=exc.extensions or None,
     )
 
 

app/core/problem_details.py

@@ -29,6 +29,11 @@
 # demo pipeline's classifier) so the marker never drifts between the two.
 EMBEDDING_AUTH_CODE = "EMBEDDING_AUTH"
 
+# Machine-readable code for an exhausted agent model fallback chain (#335).
+# Single source of truth shared by the producer (AgentFallbackExhaustedError)
+# and any consumer classifying the 502 — mirrors EMBEDDING_AUTH_CODE.
+AGENT_FALLBACK_EXHAUSTED_CODE = "AGENT_FALLBACK_EXHAUSTED"
+
 ERROR_TYPES = {
     "NOT_FOUND": f"{ERROR_TYPE_BASE}/not-found",
     "VALIDATION_ERROR": f"{ERROR_TYPE_BASE}/validation",
@@ -43,8 +48,16 @@
     "SERVICE_UNAVAILABLE": f"{ERROR_TYPE_BASE}/service-unavailable",
     "GATEWAY_TIMEOUT": f"{ERROR_TYPE_BASE}/gateway-timeout",
     EMBEDDING_AUTH_CODE: f"{ERROR_TYPE_BASE}/embedding-auth",
+    AGENT_FALLBACK_EXHAUSTED_CODE: f"{ERROR_TYPE_BASE}/agent-fallback-exhausted",
 }
 
+# RFC 7807 extension members may never shadow the spec/base fields the
+# ProblemDetail schema already owns — reserved keys are dropped from any
+# `extensions` merge in problem_response (#335).
+_RESERVED_PROBLEM_KEYS = frozenset(
+    {"type", "title", "status", "detail", "instance", "errors", "code", "request_id"}
+)
+
 
 # =============================================================================
 # Problem Detail Schema
@@ -172,6 +185,7 @@ def problem_response(
     detail: str | None = None,
     error_code: str = "INTERNAL_ERROR",
     errors: list[dict[str, Any]] | None = None,
+    extensions: dict[str, Any] | None = None,
 ) -> ProblemDetailResponse:
     """Create a ProblemDetailResponse with proper content type.
 
@@ -181,6 +195,9 @@ def problem_response(
         detail: Detailed explanation (optional).
         error_code: Internal error code for type URI lookup.
         errors: Field-level validation errors (optional).
+        extensions: Additional RFC 7807 extension members merged into the
+            response body (optional, #335). Reserved base-field keys are
+            silently dropped — extensions can never shadow type/status/etc.
     Returns:
         JSONResponse with problem+json content type.
     """
@@ -192,9 +209,17 @@ def problem_response(
         errors=errors,
     )
 
+    # Merge on the serialized dict (not ProblemDetail(**extensions)) so
+    # arbitrary extension payloads never fight the pydantic constructor.
+    content = problem.model_dump(exclude_none=True)
+    if extensions:
+        content.update(
+            {key: value for key, value in extensions.items() if key not in _RESERVED_PROBLEM_KEYS}
+        )
+
     return ProblemDetailResponse(
         status_code=status,
-        content=problem.model_dump(exclude_none=True),
+        content=content,
     )
 
 

app/core/tests/test_problem_details.py

@@ -0,0 +1,110 @@
+"""Unit tests for RFC 7807 problem_response extension members (issue #335).
+
+The `extensions` channel lets a ForecastLabError surface client-safe data
+(e.g. classified per-model failures) in the problem+json body without going
+through the log-only `details` attribute.
+"""
+
+import json
+from typing import Any
+
+import pytest
+from fastapi import Request
+
+from app.core.exceptions import (
+    AgentFallbackExhaustedError,
+    forecastlab_exception_handler,
+)
+from app.core.problem_details import problem_response
+
+
+def _body(response: Any) -> dict[str, Any]:
+    """Decode a ProblemDetailResponse body."""
+    decoded: dict[str, Any] = json.loads(response.body)
+    return decoded
+
+
+def test_problem_response_without_extensions_unchanged() -> None:
+    """Default (no extensions) output keeps the existing shape exactly."""
+    response = problem_response(
+        status=404,
+        title="Not Found",
+        detail="Resource not found",
+        error_code="NOT_FOUND",
+    )
+
+    body = _body(response)
+    assert response.status_code == 404
+    assert body["status"] == 404
+    assert body["code"] == "NOT_FOUND"
+    assert body["type"] == "/errors/not-found"
+    assert "failures" not in body
+
+
+def test_problem_response_merges_extensions() -> None:
+    """Extension members are merged into the serialized body."""
+    response = problem_response(
+        status=502,
+        title="Agent Fallback Exhausted",
+        detail="All configured agent models failed",
+        error_code="AGENT_FALLBACK_EXHAUSTED",
+        extensions={"failures": [{"model_name": "m1", "reason": "model_not_found"}]},
+    )
+
+    body = _body(response)
+    assert body["code"] == "AGENT_FALLBACK_EXHAUSTED"
+    assert body["type"] == "/errors/agent-fallback-exhausted"
+    assert body["failures"] == [{"model_name": "m1", "reason": "model_not_found"}]
+
+
+def test_problem_response_extensions_cannot_override_reserved() -> None:
+    """Reserved base-field keys in extensions are silently dropped."""
+    response = problem_response(
+        status=502,
+        title="Agent Fallback Exhausted",
+        detail="real detail",
+        error_code="AGENT_FALLBACK_EXHAUSTED",
+        extensions={
+            "status": 200,
+            "code": "HACK",
+            "detail": "spoofed",
+            "type": "about:blank",
+            "title": "spoofed",
+            "safe_key": "kept",
+        },
+    )
+
+    body = _body(response)
+    assert response.status_code == 502
+    assert body["status"] == 502
+    assert body["code"] == "AGENT_FALLBACK_EXHAUSTED"
+    assert body["detail"] == "real detail"
+    assert body["type"] == "/errors/agent-fallback-exhausted"
+    assert body["title"] == "Agent Fallback Exhausted"
+    assert body["safe_key"] == "kept"
+
+
+@pytest.mark.asyncio
+async def test_exception_handler_propagates_extensions() -> None:
+    """The full exception → handler → problem+json path carries extensions.
+
+    Guards the wiring: ForecastLabError.extensions must reach the response
+    body via forecastlab_exception_handler's pass-through (issue #335).
+    """
+    failures = [
+        {"model_name": "m1", "status_code": 404, "reason": "model_not_found", "detail": ""},
+        {"model_name": "m2", "status_code": 429, "reason": "quota_exhausted", "detail": ""},
+    ]
+    exc = AgentFallbackExhaustedError("All configured agent models failed", failures=failures)
+    request = Request(scope={"type": "http", "method": "POST", "path": "/", "headers": []})
+
+    response = await forecastlab_exception_handler(request, exc)
+
+    body = _body(response)
+    assert response.status_code == 502
+    assert body["status"] == 502
+    assert body["code"] == "AGENT_FALLBACK_EXHAUSTED"
+    assert body["type"] == "/errors/agent-fallback-exhausted"
+    assert body["title"] == "Agent Fallback Exhausted"
+    assert body["detail"] == "All configured agent models failed"
+    assert body["failures"] == failures