fix(accent): degrade gracefully when OJAD is unavailable

OJAD (www.gavo.t.u-tokyo.ac.jp) outages made /MarkAccent/ hang for the
full global 10s timeout and then return HTTP 500, because get_ojad_result
re-raised the transport error and the pipeline turned it into a 500.

Pitch accent from OJAD only enriches the furigana result, so an OJAD
outage should not fail the whole request:

- ojad.py: add a short per-request timeout (connect=2s, read=5s) so a
  down OJAD fails fast instead of hanging on the global 10s, and raise a
  dedicated OJADUnavailableError on any httpx.HTTPError (connect/read
  timeouts, connection errors, non-2xx status).
- pipeline.py: catch OJADUnavailableError and degrade to furigana-only
  output (align_accent already emits accent_marking_type=0 for an empty
  OJAD list) with status 200 and a warning, instead of 500.
- models.py: add an optional, backward-compatible `warning` field to
  AccentResponse for degraded results.

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

Author: torrid-fish

api/accent/models.py

@@ -111,3 +111,8 @@ class AccentResponse(BaseModel):
         default=None,
         description="An object that describes the details of an error when one occurs",
     )
+    warning: str | None = Field(
+        default=None,
+        description="A non-fatal warning when results are degraded, e.g. furigana "
+        "returned without pitch accent because OJAD was unavailable",
+    )

api/accent/ojad.py

@@ -23,6 +23,20 @@
 
 OJAD_URL = "https://www.gavo.t.u-tokyo.ac.jp/ojad/phrasing/index"
 
+# Per-request timeout for the OJAD POST. Overrides the global client timeout so a
+# down / unresponsive OJAD fails fast (≈2s on a dead host) instead of hanging for
+# the full global 10s before the pipeline can degrade gracefully.
+OJAD_TIMEOUT = httpx.Timeout(5.0, connect=2.0)
+
+
+class OJADUnavailableError(Exception):
+    """OJAD could not be reached or returned an error.
+
+    Raised on any transport failure (connect / read timeout, connection
+    refused) or non-2xx status. Callers should treat this as "no pitch
+    contour available" and degrade rather than fail the whole request.
+    """
+
 
 async def get_ojad_result(
     query_text: str,
@@ -47,12 +61,14 @@ async def get_ojad_result(
 
     # Send a POST and receive the website html code
     try:
-        response = await client.post(OJAD_URL, data=data)
+        response = await client.post(OJAD_URL, data=data, timeout=OJAD_TIMEOUT)
         response.raise_for_status()
         logger.debug(f"[OJAD] Status Code: {response.status_code}")
-    except Exception:
-        logger.exception("[OJAD] Request Failed")
-        raise
+    except httpx.HTTPError as e:
+        # Covers ConnectTimeout / ReadTimeout / ConnectError as well as the
+        # HTTPStatusError from raise_for_status() — all httpx.HTTPError subclasses.
+        logger.warning(f"[OJAD] Unavailable: {e}")
+        raise OJADUnavailableError(str(e)) from e
 
     website = response.text
 

api/accent/pipeline.py

@@ -18,7 +18,7 @@
 from api.accent.align import align_accent
 from api.accent.furigana import fetch_furigana
 from api.accent.models import AccentResponse, ErrorInfo
-from api.accent.ojad import get_ojad_result
+from api.accent.ojad import OJADUnavailableError, get_ojad_result
 
 logger = logging.getLogger("api")
 
@@ -42,11 +42,24 @@ async def process_accent_chunk(text: str, client: httpx.AsyncClient) -> AccentRe
         furigana_results = furigana_response.result
         logger.debug(f"Yahoo Results Count: {len(furigana_results)}")
 
-        _ojad_surface, ojad_results = await get_ojad_result(query_text, client)
+        # OJAD only enriches the result with pitch accent. If it is down, fall
+        # back to furigana-only output (align_accent emits accent_marking_type=0
+        # for every mora when given an empty list) rather than failing the
+        # request — see api/accent/align.py "MATCH FAILED" branch.
+        warning = None
+        try:
+            _ojad_surface, ojad_results = await get_ojad_result(query_text, client)
+        except OJADUnavailableError as e:
+            logger.warning(f"OJAD unavailable, degrading to furigana-only: {e}")
+            ojad_results = []
+            warning = (
+                "OJAD pitch-accent service is unavailable; "
+                "returning furigana without pitch accent."
+            )
 
         final_results = await align_accent(furigana_results, ojad_results)
 
-        return AccentResponse(status=200, result=final_results)
+        return AccentResponse(status=200, result=final_results, warning=warning)
 
     except Exception as e:
         logger.exception(f"Unexpected error occurred: {text}")