refactor: simplify narrator integration per code review

- Remove dead generate_explainer_pairs/generate_summarizer_pairs wrappers
- Derive _REQUIRED_KEYS sets from schema dicts in prompts.py
- Simplify dedup loop in check_shap_grounding with dict.fromkeys()
- Add narrator key to load_seed_queries() return
- Update test_distill.py to use generate_pairs() directly
- Fix stale docstring in generate_pairs()

Author: William-Hill

tests/training/test_distill.py

@@ -7,8 +7,7 @@
 from training.distill import (
     validate_json,
     call_teacher,
-    generate_explainer_pairs,
-    generate_summarizer_pairs,
+    generate_pairs,
 )
 
 
@@ -80,10 +79,11 @@ def test_generates_pairs_from_seed_data(self, sample_school_config, sample_cours
         })
 
         with patch("training.distill.call_teacher", return_value=mock_response):
-            pairs = generate_explainer_pairs(
+            pairs = generate_pairs(
                 config=sample_school_config,
                 seed_data=[sample_course_pairing_data],
                 count=2,
+                task="explainer",
             )
 
         assert len(pairs) == 2
@@ -92,10 +92,11 @@ def test_generates_pairs_from_seed_data(self, sample_school_config, sample_cours
 
     def test_skips_invalid_responses(self, sample_school_config, sample_course_pairing_data):
         with patch("training.distill.call_teacher", return_value="not json"):
-            pairs = generate_explainer_pairs(
+            pairs = generate_pairs(
                 config=sample_school_config,
                 seed_data=[sample_course_pairing_data],
                 count=3,
+                task="explainer",
             )
 
         assert len(pairs) == 0
@@ -112,10 +113,11 @@ def test_generates_pairs_from_seed_data(self, sample_school_config, sample_query
         })
 
         with patch("training.distill.call_teacher", return_value=mock_response):
-            pairs = generate_summarizer_pairs(
+            pairs = generate_pairs(
                 config=sample_school_config,
                 seed_data=[sample_query_result_data],
                 count=2,
+                task="summarizer",
             )
 
         assert len(pairs) == 2

training/distill.py

@@ -171,7 +171,7 @@ def generate_pairs(
         config: Parsed school config.
         seed_data: List of seed data dicts.
         count: Number of pairs to generate.
-        task: "explainer" or "summarizer".
+        task: "narrator", "explainer", or "summarizer".
         outfile: If provided, pairs are written incrementally.
         system_prompt: Pre-built system prompt (avoids recomputation).
     """
@@ -221,24 +221,6 @@ def generate_pairs(
     return pairs
 
 
-def generate_explainer_pairs(
-    config: dict[str, Any], seed_data: list[dict[str, Any]],
-    count: int, outfile: Path | None = None,
-    system_prompt: str | None = None,
-) -> list[dict]:
-    """Generate explainer training pairs via teacher model distillation."""
-    return generate_pairs(config, seed_data, count, "explainer", outfile, system_prompt)
-
-
-def generate_summarizer_pairs(
-    config: dict[str, Any], seed_data: list[dict[str, Any]],
-    count: int, outfile: Path | None = None,
-    system_prompt: str | None = None,
-) -> list[dict]:
-    """Generate summarizer training pairs via teacher model distillation."""
-    return generate_pairs(config, seed_data, count, "summarizer", outfile, system_prompt)
-
-
 def main(school: str, local: bool = False) -> None:
     """Run distillation for a school."""
     config = load_school_config(school)

training/eval.py

@@ -17,34 +17,15 @@
 from typing import Any
 
 from training.config import get_message_content, get_training_data_dir, read_jsonl
+from training.prompts import EXPLAINER_SCHEMA, NARRATOR_SCHEMA, SUMMARIZER_SCHEMA
 
 # ---------------------------------------------------------------------------
-# Required keys per task
+# Required keys per task — derived from schema definitions in prompts.py
 # ---------------------------------------------------------------------------
 
-_EXPLAINER_REQUIRED_KEYS: set[str] = {
-    "explanation",
-    "structural_factors",
-    "student_impact",
-    "advisor_recommendation",
-    "data_limitations",
-    "related_intervention",
-}
-
-_NARRATOR_REQUIRED_KEYS: set[str] = {
-    "narrative",
-    "key_drivers",
-    "recommended_actions",
-    "data_limitations",
-}
-
-_SUMMARIZER_REQUIRED_KEYS: set[str] = {
-    "summary",
-    "key_insights",
-    "context",
-    "action_items",
-    "caveats",
-}
+_EXPLAINER_REQUIRED_KEYS: set[str] = set(EXPLAINER_SCHEMA.keys())
+_NARRATOR_REQUIRED_KEYS: set[str] = set(NARRATOR_SCHEMA.keys())
+_SUMMARIZER_REQUIRED_KEYS: set[str] = set(SUMMARIZER_SCHEMA.keys())
 
 # ---------------------------------------------------------------------------
 # Ship criteria — minimum thresholds per task
@@ -204,14 +185,7 @@ def check_shap_grounding(outputs: list[str], inputs: list[dict[str, Any]], min_f
                 top_features.append(entry["feature"])
             for entry in model_attrs.get("top_negative", [])[:3]:
                 top_features.append(entry["feature"])
-        # Deduplicate while preserving order
-        seen = set()
-        unique_features = []
-        for f in top_features:
-            if f not in seen:
-                seen.add(f)
-                unique_features.append(f)
-        top_features = unique_features[:6]  # top 3 per direction, deduplicated
+        top_features = list(dict.fromkeys(top_features))[:6]
 
         if not top_features:
             passing += 1  # no SHAP data to ground against

training/seed.py

@@ -168,6 +168,7 @@ def load_seed_queries(school: str) -> dict[str, list[dict]]:
     with seed_path.open("r", encoding="utf-8") as fh:
         data = yaml.safe_load(fh) or {}
     return {
+        "narrator": data.get("narrator", []),
         "explainer": data.get("explainer", []),
         "summarizer": data.get("summarizer", []),
     }