merge main into feat/local-unidic (pick up OJAD graceful-degradation fix #60)

# Conflicts:
#	api/accent/pipeline.py

Author: torrid-fish

api/accent/models.py

@@ -200,3 +200,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

@@ -40,7 +40,7 @@
 
 from api.accent.align import align_accent
 from api.accent.models import AccentResponse, ErrorInfo, WordAccentResult
-from api.accent.ojad import get_ojad_result
+from api.accent.ojad import OJADUnavailableError, get_ojad_result
 from api.accent.postprocess import (
     apply_furigana_toggles,
     convert_furigana_script,
@@ -145,7 +145,21 @@ async def process_accent_chunk(
         # a normal contour; fugashi keeps the original surface so the
         # tokenizer's acronym-merge preserves `Wifi.7` for display.
         ojad_query_text = strip_acronym_dots_for_ojad(stripped_text)
-        _ojad_surface, ojad_results = await get_ojad_result(ojad_query_text, client)
+
+        # OJAD only enriches the result with pitch accent. If it is down, fall
+        # back to furigana-only output (align_accent emits a fallback word with
+        # no pitch contour for every token when given an empty list) rather
+        # than failing the request — see align_accent's `m == 0` branch.
+        warning = None
+        try:
+            _ojad_surface, ojad_results = await get_ojad_result(ojad_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)
         final_results = apply_accent_overrides(final_results)
@@ -180,7 +194,7 @@ async def process_accent_chunk(
         # script before serialisation. Hiragana is the no-op default.
         final_results = convert_furigana_script(final_results, script)
 
-        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}")