[NAH-13] Weak-topic targeting: bias next_card toward low-grade topics

next_card now looks at the next few due cards and surfaces the one whose topic
has the lowest average grade so far (when that topic is actually weak, avg < 3).
The chosen card is rotated to the front so apply_result's "pop the front"
contract still holds. No-op until there's answer history, so early cards keep
normal order.

Tests (test_weak_topic.py, no model): no-history order, weak topic surfaced,
lookahead window respected, apply_result contract preserved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

learning_engine.py

@@ -30,12 +30,28 @@ def init_session(deck: list[Card]) -> Session:
     )
 
 
+WEAK_TOPIC_THRESHOLD = 3.0   # avg grade below this = a topic the user is weak on
+WEAK_LOOKAHEAD = 4           # how far down the queue we'll reach to surface a weak card
+
+
 def next_card(session: Session) -> Card | None:
-    """Pop the next due card id from the queue, biased toward weak topics."""
-    if not session["queue"]:
+    """
+    Return the next card to study. Among the next few due cards we bias toward
+    the user's weakest topic (lowest average grade so far) — so once the model
+    sees you're shaky on a topic, that topic comes back sooner. With no history
+    yet this is a no-op and we serve the queue in order.
+
+    The chosen card is rotated to the front of the queue so `apply_result`'s
+    "pop the front" contract still holds.
+    """
+    queue = session["queue"]
+    if not queue:
         return None
-    card_id = session["queue"][0]
-    return _find(session, card_id)
+
+    idx = _weak_biased_index(session)
+    if idx > 0:
+        queue.insert(0, queue.pop(idx))   # bring the weak-topic card to the front
+    return _find(session, queue[0])
 
 
 # ---- Grading ---------------------------------------------------------------
@@ -191,6 +207,39 @@ def _find(session: Session, card_id: str) -> Card | None:
     return next((c for c in session["deck"] if c["id"] == card_id), None)
 
 
+def _topic_averages(session: Session) -> dict[str, float]:
+    """Average grade per topic across answered history (empty until first answer)."""
+    grades: dict[str, list[int]] = {}
+    for h in session["history"]:
+        grades.setdefault(h["topic"], []).append(h["grade"])
+    return {t: _avg(g) for t, g in grades.items()}
+
+
+def _weak_biased_index(session: Session) -> int:
+    """
+    Index into the queue of the card to serve next. Looks at the next
+    WEAK_LOOKAHEAD cards and picks the one whose topic has the lowest average
+    grade, as long as that topic is actually weak (avg < threshold). Returns 0
+    (keep normal order) when nothing in reach is weak or there's no history yet.
+    """
+    queue = session["queue"]
+    averages = _topic_averages(session)
+    if not averages:
+        return 0
+
+    best_idx, best_avg = 0, None
+    for i, card_id in enumerate(queue[:WEAK_LOOKAHEAD]):
+        card = _find(session, card_id)
+        if card is None:
+            continue
+        avg = averages.get(card["topic"])
+        if avg is None or avg >= WEAK_TOPIC_THRESHOLD:
+            continue
+        if best_avg is None or avg < best_avg:
+            best_idx, best_avg = i, avg
+    return best_idx
+
+
 def _insert_at(session: Session, card_id: str, pos: int) -> None:
     pos = max(0, min(pos, len(session["queue"])))
     session["queue"].insert(pos, card_id)

test_weak_topic.py

@@ -0,0 +1,73 @@
+"""
+NAH-13 — weak-topic targeting: next_card biases toward low-average-grade topics.
+
+No model needed (pure scheduling logic). Run:  python3 test_weak_topic.py
+"""
+import learning_engine as le
+from schema import new_card
+
+
+def _deck():
+    return [
+        new_card("strong q1", "a", topic="Algebra", card_id="alg1"),
+        new_card("strong q2", "a", topic="Algebra", card_id="alg2"),
+        new_card("weak q1", "a", topic="Geometry", card_id="geo1"),
+        new_card("weak q2", "a", topic="Geometry", card_id="geo2"),
+    ]
+
+
+def test_no_history_keeps_order():
+    s = le.init_session(_deck())
+    # No answers yet -> serve the queue head untouched.
+    assert le.next_card(s)["id"] == "alg1"
+    assert s["queue"][0] == "alg1"
+    print("ok  no history -> normal queue order")
+
+
+def test_weak_topic_surfaces_first():
+    s = le.init_session(_deck())
+    # Simulate: aced Algebra, bombed Geometry.
+    s["history"] = [
+        {"card_id": "alg1", "topic": "Algebra", "grade": 5, "user_answer": ""},
+        {"card_id": "geo1", "topic": "Geometry", "grade": 1, "user_answer": ""},
+    ]
+    # Queue still leads with an Algebra card, but a weak Geometry card is in reach.
+    s["queue"] = ["alg2", "geo2", "alg1"]
+    card = le.next_card(s)
+    assert card["topic"] == "Geometry", f"expected weak topic first, got {card}"
+    assert s["queue"][0] == card["id"], "chosen card must be rotated to the front"
+    print("ok  weak topic (Geometry) surfaced ahead of strong topic")
+
+
+def test_lookahead_window_respected():
+    s = le.init_session(_deck())
+    s["history"] = [{"card_id": "geo1", "topic": "Geometry", "grade": 0, "user_answer": ""}]
+    # Weak Geometry card sits beyond the lookahead window -> not pulled forward.
+    s["queue"] = ["alg1", "alg2", "alg2", "alg1", "geo2"]
+    le.WEAK_LOOKAHEAD  # window is 4; geo2 is at index 4
+    card = le.next_card(s)
+    assert card["topic"] == "Algebra", "weak card outside window should not jump"
+    print("ok  weak card beyond lookahead window left in place")
+
+
+def test_apply_result_contract_holds():
+    # next_card rotates the served card to front; apply_result pops the front.
+    s = le.init_session(_deck())
+    s["history"] = [{"card_id": "geo1", "topic": "Geometry", "grade": 1, "user_answer": ""}]
+    s["queue"] = ["alg1", "geo2"]
+    card = le.next_card(s)
+    assert card["id"] == "geo2"
+    before = len(s["queue"])
+    le.apply_result(s, card, {"score": 4, "correct": True,
+                              "explanation": "", "missed_concept": ""})
+    assert "geo2" not in s["queue"][:1], "served card should be popped from front"
+    assert len(s["queue"]) == before, "popped one, re-inserted one"
+    print("ok  apply_result still pops the served card from the front")
+
+
+if __name__ == "__main__":
+    test_no_history_keeps_order()
+    test_weak_topic_surfaces_first()
+    test_lookahead_window_respected()
+    test_apply_result_contract_holds()
+    print("\nAll NAH-13 weak-topic tests passed.")