From 0baff0b4471bba9ffe47b21b7faff60072753d9d Mon Sep 17 00:00:00 2001
From: Shuming Liu <smshine@qq.com>
Date: Sun, 6 Sep 2026 07:59:00 +0800
Subject: [PATCH] add a debug info

---
 sentence_api/ai_tutor.py            | 26 ++++++++++++++++++++++++++
 sentence_api/tests/test_ai_tutor.py |  1 +
 2 files changed, 27 insertions(+)

diff --git a/sentence_api/ai_tutor.py b/sentence_api/ai_tutor.py
index 81fe3c2..4730f6e 100644
--- a/sentence_api/ai_tutor.py
+++ b/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()
diff --git a/sentence_api/tests/test_ai_tutor.py b/sentence_api/tests/test_ai_tutor.py
index ad0a564..4edb04c 100644
--- a/sentence_api/tests/test_ai_tutor.py
+++ b/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):