add explain module

sentence_api/tests/test_ai_tutor.py

@@ -0,0 +1,57 @@
+import pytest
+
+from sentence_api.ai_tutor import AITutor, AITutorError
+
+
+class FakeResponse:
+    def __init__(self, status_code=200, body=None):
+        self.status_code = status_code
+        self._body = body or {}
+
+    def json(self):
+        if self._body is None:
+            raise ValueError("invalid JSON")
+        return self._body
+
+
+def test_ai_tutor_parses_chat_completion(monkeypatch):
+    requests_payloads = []
+
+    def fake_post(endpoint, headers, json, timeout):
+        requests_payloads.append((endpoint, headers, json, timeout))
+        return FakeResponse(
+            body={
+                "choices": [
+                    {"message": {"content": " 这句话的意思是…… "}}
+                ]
+            }
+        )
+
+    monkeypatch.setattr("sentence_api.ai_tutor.requests.post", fake_post)
+    tutor = AITutor("https://ai.test/chat", "secret", "test-model", 1.5)
+
+    explanation = tutor.explain(
+        "The early bird catches the worm.",
+        course_title="English idioms",
+        sentence_index=1,
+        language="en",
+    )
+
+    endpoint, headers, payload, timeout = requests_payloads[0]
+    assert explanation == "这句话的意思是……"
+    assert endpoint == "https://ai.test/chat"
+    assert headers["Authorization"] == "Bearer secret"
+    assert payload["model"] == "test-model"
+    assert "The early bird catches the worm." in payload["messages"][1]["content"]
+    assert timeout == 1.5
+
+
+def test_ai_tutor_rejects_unexpected_response(monkeypatch):
+    monkeypatch.setattr(
+        "sentence_api.ai_tutor.requests.post",
+        lambda *args, **kwargs: FakeResponse(body={"choices": []}),
+    )
+    tutor = AITutor("https://ai.test/chat", "secret", "test-model", 1)
+
+    with pytest.raises(AITutorError):
+        tutor.explain("Hello.")

sentence_api/tests/test_api.py

@@ -80,6 +80,70 @@ def test_invalid_hash_is_rejected(tmp_path):
     assert response.status_code == 422
 
 
+def test_sentence_explanation_requires_login(tmp_path):
+    index_path = tmp_path / "boundaries.json"
+    index_path.write_text("{}", encoding="utf-8")
+    settings = replace(
+        Settings.from_env(),
+        data_dir=tmp_path / "data",
+        legacy_boundaries_file=index_path,
+    )
+    settings.ensure_directories()
+    client = TestClient(
+        create_app(
+            BoundaryStore(index_path),
+            settings=settings,
+            repository=VideoRepository(settings.database_path),
+        )
+    )
+
+    response = client.post(
+        "/api/v1/sentences/explain",
+        json={"sentence_text": "Hello."},
+    )
+
+    assert response.status_code == 401
+
+
+def test_sentence_explanation_uses_server_side_ai_client(tmp_path, monkeypatch):
+    client = make_client(tmp_path)
+    requested = []
+
+    def explain(text, **kwargs):
+        requested.append((text, kwargs))
+        return "这句话表示打招呼。"
+
+    class StubAITutor:
+        pass
+
+    stub = StubAITutor()
+    stub.explain = explain
+    monkeypatch.setattr(client.app.state, "ai_tutor", stub)
+
+    response = client.post(
+        "/api/v1/sentences/explain",
+        json={
+            "sentence_text": "Hello.",
+            "course_title": "Greetings",
+            "sentence_index": 0,
+            "language": "en",
+        },
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {"explanation": "这句话表示打招呼。"}
+    assert requested == [
+        (
+            "Hello.",
+            {
+                "course_title": "Greetings",
+                "sentence_index": 0,
+                "language": "en",
+            },
+        )
+    ]
+
+
 def test_oss_video_url_is_used_for_catalog_and_content(tmp_path):
     index_path = tmp_path / "boundaries.json"
     index_path.write_text("{}", encoding="utf-8")