add a debug info

sentence_api/ai_tutor.py

@@ -1,10 +1,14 @@
 """AI-backed sentence explanations for the mobile clients."""
 
 from dataclasses import dataclass
+import logging
 
 import requests
 
 
+logger = logging.getLogger(__name__)
+
+
 class AITutorError(RuntimeError):
     """Raised when the configured AI service cannot answer a request."""
 
@@ -61,15 +65,37 @@ class AITutor:
                 timeout=self.timeout_seconds,
             )
         except requests.RequestException as exc:
+            logger.exception(
+                "AI explanation request failed: endpoint=%s model=%s",
+                self.endpoint,
+                self.model,
+            )
             raise AITutorError("AI service request failed.") from exc
 
         if response.status_code < 200 or response.status_code >= 300:
+            logger.warning(
+                "AI explanation returned HTTP %s: endpoint=%s model=%s body=%s",
+                response.status_code,
+                self.endpoint,
+                self.model,
+                response.text[:1000],
+            )
             raise AITutorError(f"AI service returned HTTP {response.status_code}.")
         try:
             body = response.json()
             explanation = body["choices"][0]["message"]["content"]
         except (KeyError, IndexError, TypeError, ValueError) as exc:
+            logger.warning(
+                "AI explanation returned an unexpected body: endpoint=%s body=%s",
+                self.endpoint,
+                response.text[:1000],
+            )
             raise AITutorError("AI service returned an unexpected response.") from exc
         if not isinstance(explanation, str) or not explanation.strip():
+            logger.warning(
+                "AI explanation returned empty content: endpoint=%s body=%s",
+                self.endpoint,
+                response.text[:1000],
+            )
             raise AITutorError("AI service returned an empty explanation.")
         return explanation.strip()

sentence_api/tests/test_ai_tutor.py

@@ -6,6 +6,7 @@ from sentence_api.ai_tutor import AITutor, AITutorError
 class FakeResponse:
     def __init__(self, status_code=200, body=None):
         self.status_code = status_code
+        self.text = str(body)
         self._body = body or {}
 
     def json(self):