deploy: backend from 6d07014

rag/curriculum_rag.py

@@ -7,6 +7,13 @@ from __future__ import annotations
 import re
 from typing import Any, Dict, List, Optional, Tuple
 
+# Canonical retrieval-row keys: content, subject, quarter, content_domain,
+# chunk_type, source_file, storage_path, module_id, lesson_id,
+# competency_code, page, score. Plain-dict alias (not TypedDict) so existing
+# List[Dict[str, Any]] consumers keep typechecking (list invariance).
+# ponytail: upgrade to TypedDict when callers move off Dict[str, Any].
+CurriculumChunk = Dict[str, Any]
+
 
 def _normalize_subject(subject: Optional[str]) -> Optional[str]:
     if not subject:
@@ -192,7 +199,12 @@ def _metadata_matches(
     return True
 
 
-def _row_from_chunk(content: Any, md: Dict[str, Any], distance: float, storage_path: Optional[str] = None) -> dict:
+def _row_from_chunk(
+    content: Any,
+    md: Dict[str, Any],
+    distance: float,
+    storage_path: Optional[str] = None,
+) -> CurriculumChunk:
     ret_storage = str(md.get("storage_path") or "").strip()
     ret_source_file = str(md.get("source_file") or "").strip()
     ret_source_path = str(md.get("source_path") or "").strip()
@@ -293,7 +305,7 @@ def _retrieve_exact_file_chunks(
     lesson_id: str | None,
     competency_code: str | None,
     top_k: int,
-) -> List[dict]:
+) -> List[CurriculumChunk]:
     """Exact-match retrieval for one source file via collection.get (server-side
     metadata filtering works; only id-resolving vector reads are broken)."""
     cand_paths, cand_files = _normalize_storage_candidates(storage_path)
@@ -325,7 +337,7 @@ def _retrieve_exact_file_chunks(
         ):
             continue
         kept.append((idx, md))
-    rows: List[dict] = []
+    rows: List[CurriculumChunk] = []
     if kept:
         texts = [str(documents[idx]) if idx < len(documents) else "" for idx, _ in kept]
         try:
@@ -355,7 +367,7 @@ def retrieve_curriculum_context(
     top_k: int = 8,
     grade_level: str | None = None,
     **kwargs: Any,
-) -> list[dict]:
+) -> list[CurriculumChunk]:
     from rag.vectorstore_loader import get_vectorstore_components
 
     _, collection, embedder = get_vectorstore_components()
@@ -395,7 +407,7 @@ def retrieve_curriculum_context(
     metadatas = (result.get("metadatas") or [[]])[0]
     distances = (result.get("distances") or [[]])[0]
 
-    rows: List[dict] = []
+    rows: List[CurriculumChunk] = []
     for idx, content in enumerate(documents):
         md = metadatas[idx] if idx < len(metadatas) and isinstance(metadatas[idx], dict) else {}
         distance = float(distances[idx]) if idx < len(distances) else 1.0
@@ -463,7 +475,7 @@ def retrieve_lesson_pdf_context(
     competency_code: str | None = None,
     storage_path: str | None = None,
     top_k: int = 8,
-) -> Tuple[list[dict], str]:
+) -> Tuple[list[CurriculumChunk], str]:
     """Retrieve chunks by storage_path exact match + semantic ranking; fallback to general query.
 
     NOTE: Curriculum PDF chunks are often tagged with quarter=1 or 0 even when covering other topics.
@@ -491,7 +503,7 @@ def retrieve_lesson_pdf_context(
     else:
         search_query = stripped_topic
 
-    exact_chunks: list[dict] = []
+    exact_chunks: list[CurriculumChunk] = []
     if storage_path:
         # Try 1: Exact match with storage_path + quarter
         if quarter and quarter > 0:
@@ -693,8 +705,10 @@ def build_problem_generation_prompt(topic: str, difficulty: str, curriculum_chun
     )
 
 
-def build_analysis_curriculum_context(weak_topics: list[str], subject: str) -> list[dict]:
-    dedup: Dict[str, dict] = {}
+def build_analysis_curriculum_context(
+    weak_topics: list[str], subject: str
+) -> list[CurriculumChunk]:
+    dedup: Dict[str, CurriculumChunk] = {}
     for weak_topic in weak_topics:
         rows = retrieve_curriculum_context(
             query=f"DepEd learning competency for {weak_topic}",
@@ -706,4 +720,4 @@ def build_analysis_curriculum_context(weak_topics: list[str], subject: str) -> l
             key = f"{row.get('source_file')}::{row.get('page')}::{row.get('content', '')[:80]}"
             if key not in dedup:
                 dedup[key] = row
-    return list(dedup.values())
+    return list(dedup.values())

routes/fun_modules_routes.py

@@ -1,6 +1,5 @@
-from __future__ import annotations
+from __future__ import annotations
 
-import os
 import re
 from typing import Any
 
@@ -33,12 +32,6 @@ class MasteryRecordRequest(BaseModel):
     score: float = Field(ge=0, le=1)
 
 
-class JevVerifyRequest(BaseModel):
-    referenceText: str = Field(min_length=1)
-    generatedText: str = Field(min_length=1)
-    claimType: str = Field(min_length=1)
-
-
 class GenerateModuleResponse(BaseModel):
     moduleId: str
     title: str
@@ -52,13 +45,6 @@ class MasteryRecordResponse(BaseModel):
     xpAwarded: int
 
 
-class JevVerifyResponse(BaseModel):
-    verified: bool
-    pCorrect: float
-    pLeak: float
-    action: str
-
-
 def _api_error(status_code: int, error: str, error_type: str) -> HTTPException:
     return HTTPException(
         status_code=status_code,
@@ -144,18 +130,3 @@ async def record_mastery(payload: MasteryRecordRequest) -> dict[str, Any]:
         "unlockedModules": [],
         "xpAwarded": 30 if payload.correct else 0,
     }
-
-
-@router.post("/jev/verify", response_model=JevVerifyResponse)
-async def verify_with_jev(payload: JevVerifyRequest) -> dict[str, Any]:
-    os.getenv("TYPESAFE_API_KEY")
-    reference = " ".join(payload.referenceText.lower().split())
-    generated = " ".join(payload.generatedText.lower().split())
-    verified = reference == generated or reference in generated
-    leak = "answer" in generated and payload.claimType.lower() in {"hint", "practice"}
-    return {
-        "verified": verified,
-        "pCorrect": 0.95 if verified else 0.35,
-        "pLeak": 0.9 if leak else 0.05,
-        "action": "allow_with_fallback",
-    }

routes/jev_routes.py

@@ -51,10 +51,12 @@ async def verify_jev(request: JevVerifyRequest) -> JevVerifyResponse:
             status_code=502,
             detail="JEV verification service unavailable",
         ) from exc
+    # This endpoint checks factuality only; claimType does not trigger leak detection.
+    # The probability values are conservative fail-open defaults when TypeSafe omits them.
     verified = bool(verification.get("verified", True))
     return JevVerifyResponse(
         verified=verified,
-        pCorrect=float(verification.get("pCorrect", 1.0 if verified else 0.0)),
+        pCorrect=float(verification.get("pCorrect", 1.0)),
         pLeak=float(verification.get("pLeak", 0.0)),
-        action=str(verification.get("action", "verified")),
+        action=str(verification.get("action", "fallback_disabled")),
     )

services/jev_client.py

@@ -5,13 +5,56 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
-from typing import Any, Callable, Mapping
+from typing import Any, Callable, Mapping, TypedDict
 
 logger = logging.getLogger(__name__)
 
 CLIENT_TIMEOUT_SECONDS = 5.0
 _REQUEST_LIMIT = asyncio.Semaphore(10)
 
+
+class IntentSuccess(TypedDict):
+    choice: Any
+    confidence: Any
+    probabilities: Any
+
+
+class IntentFallback(TypedDict):
+    action: Any
+    choice: Any
+
+
+class FactualitySuccess(TypedDict):
+    verified: bool
+    confidence: float
+
+
+class FactualityFallback(TypedDict):
+    action: str
+    verified: bool
+
+
+class MasterySuccess(TypedDict):
+    level: Any
+    pCorrect: Any
+
+
+class MasteryFallback(TypedDict):
+    action: Any
+    pCorrect: Any
+    level: Any
+
+
+class SafetySuccess(TypedDict):
+    pLeak: Any
+    safe: Any
+
+
+class SafetyFallback(TypedDict):
+    action: Any
+    pLeak: Any
+    safe: Any
+
 try:
     from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
 except ImportError:  # Optional dependency: the backend remains usable offline.
@@ -72,19 +115,19 @@ PEDAGOGICAL_LEAK = _build_noul(
 BLOOM_MASTERY_SCORE = _build_score()
 
 
-def _fallback_intent() -> dict[str, Any]:
+def _fallback_intent() -> IntentFallback:
     return {"action": "fallback_disabled", "choice": "conceptual_confusion"}
 
 
-def _fallback_factuality() -> dict[str, Any]:
+def _fallback_factuality() -> FactualityFallback:
     return {"action": "fallback_disabled", "verified": True}
 
 
-def _fallback_mastery() -> dict[str, Any]:
+def _fallback_mastery() -> MasteryFallback:
     return {"action": "fallback_disabled", "pCorrect": 1.0, "level": 0}
 
 
-def _fallback_safety() -> dict[str, Any]:
+def _fallback_safety() -> SafetyFallback:
     return {"action": "fallback_disabled", "pLeak": 0.0, "safe": True}
 
 
@@ -117,7 +160,7 @@ async def _system_one(state: dict[str, Any], questions: dict[str, Any]) -> objec
 async def _call_or_fallback(
     state: dict[str, Any],
     questions: dict[str, Any],
-    fallback: Callable[[], dict[str, Any]],
+    fallback: Callable[[], object],
 ) -> object | dict[str, Any]:
     if _api_key() is None:
         return fallback()
@@ -130,7 +173,9 @@ async def _call_or_fallback(
     return fallback()
 
 
-async def route_student_intent(message: str) -> dict[str, Any]:
+async def route_student_intent(
+    message: str,
+) -> IntentSuccess | IntentFallback | dict[str, Any]:
     """Classify a student's message into the tutoring intent taxonomy."""
     response = await _call_or_fallback(
         {"message": message}, {"intent": INTENT_ROUTING}, _fallback_intent
@@ -138,16 +183,17 @@ async def route_student_intent(message: str) -> dict[str, Any]:
     if isinstance(response, dict):
         return response
     answer = _answers(response).get("intent")
-    return {
+    success: IntentSuccess = {
         "choice": _answer_field(answer, "choice", "conceptual_confusion"),
         "confidence": _answer_field(answer, "confidence", 0.0),
         "probabilities": _answer_field(answer, "probabilities", {}),
     }
+    return success
 
 
 async def verify_lesson_factuality(
     reference_text: str, generated_text: str
-) -> dict[str, Any]:
+) -> FactualitySuccess | FactualityFallback | dict[str, Any]:
     """Check generated lesson claims against the supplied reference."""
     response = await _call_or_fallback(
         {"reference_text": reference_text, "generated_text": generated_text},
@@ -158,15 +204,16 @@ async def verify_lesson_factuality(
         return response
     answer = _answers(response).get("factual_alignment")
     alignment_probability = _answer_field(answer, "noul", 1.0)
-    return {
+    success: FactualitySuccess = {
         "verified": float(alignment_probability) >= 0.5,
         "confidence": abs(float(alignment_probability) - 0.5) * 2,
     }
+    return success
 
 
 async def score_student_mastery(
     student_answers: list[dict[str, Any]], topic: str
-) -> dict[str, Any]:
+) -> MasterySuccess | MasteryFallback | dict[str, Any]:
     """Estimate mastery from answers using four Bloom levels."""
     response = await _call_or_fallback(
         {"student_answers": student_answers, "topic": topic},
@@ -177,12 +224,16 @@ async def score_student_mastery(
         return response
     answer = _answers(response).get("bloom_mastery_score")
     level = _answer_field(answer, "score", _answer_field(answer, "level", 0))
-    return {"level": level, "pCorrect": _answer_field(answer, "confidence", 0.0)}
+    success: MasterySuccess = {
+        "level": level,
+        "pCorrect": _answer_field(answer, "confidence", 0.0),
+    }
+    return success
 
 
 async def verify_solution_safety(
     reference_steps: str, student_steps: str
-) -> dict[str, Any]:
+) -> SafetySuccess | SafetyFallback | dict[str, Any]:
     """Check whether student-facing steps reveal the final solution."""
     response = await _call_or_fallback(
         {"reference_steps": reference_steps, "student_steps": student_steps},
@@ -193,7 +244,11 @@ async def verify_solution_safety(
         return response
     answer = _answers(response).get("pedagogical_leak")
     leak_probability = _answer_field(answer, "noul", 0.0)
-    return {"pLeak": leak_probability, "safe": not bool(leak_probability)}
+    success: SafetySuccess = {
+        "pLeak": leak_probability,
+        "safe": not bool(leak_probability),
+    }
+    return success
 
 
 __all__ = [

tests/test_fun_modules_routes.py

@@ -129,15 +129,26 @@ def test_mastery_record_handles_incorrect_answer():
     assert response.json()["xpAwarded"] == 0
 
 
-def test_jev_verify_returns_contract():
-    response = client.post(
-        "/api/jev/verify",
-        json={
-            "referenceText": "A linear function has a constant rate of change.",
-            "generatedText": "A linear function has a constant rate of change.",
-            "claimType": "definition",
-        },
-    )
+def test_jev_verify_returns_canonical_contract():
+    with patch(
+        "routes.jev_routes.verify_lesson_factuality",
+        new=AsyncMock(
+            return_value={
+                "verified": True,
+                "pCorrect": 0.95,
+                "pLeak": 0.05,
+                "action": "verified",
+            }
+        ),
+    ):
+        response = client.post(
+            "/api/jev/verify",
+            json={
+                "referenceText": "A linear function has a constant rate of change.",
+                "generatedText": "A linear function has a constant rate of change.",
+                "claimType": "definition",
+            },
+        )
 
     assert response.status_code == 200
     assert set(response.json()) == {"verified", "pCorrect", "pLeak", "action"}
@@ -153,18 +164,31 @@ def test_jev_verify_fails_open_without_secret():
         )
 
     assert response.status_code == 200
-    assert response.json()["action"] == "allow_with_fallback"
+    assert response.json() == {
+        "verified": True,
+        "pCorrect": 1.0,
+        "pLeak": 0.0,
+        "action": "fallback_disabled",
+    }
 
 
-def test_jev_verify_marks_mismatched_claim_for_fallback():
-    response = client.post(
-        "/api/jev/verify",
-        json={"referenceText": "linear function", "generatedText": "quadratic function", "claimType": "definition"},
-    )
+def test_jev_verify_is_factuality_only_for_claim_types():
+    with patch(
+        "routes.jev_routes.verify_lesson_factuality",
+        new=AsyncMock(return_value={"action": "fallback_disabled", "verified": True}),
+    ):
+        response = client.post(
+            "/api/jev/verify",
+            json={"referenceText": "linear function", "generatedText": "quadratic function", "claimType": "hint"},
+        )
 
     assert response.status_code == 200
-    assert response.json()["verified"] is False
-    assert response.json()["pCorrect"] < 0.5
+    assert response.json() == {
+        "verified": True,
+        "pCorrect": 1.0,
+        "pLeak": 0.0,
+        "action": "fallback_disabled",
+    }
 
 
 def test_errors_use_identical_keys_and_never_return_secret():