teaching_angle_generator.py

# teaching_angle_generator.py
# Dynamically generates a list of teaching angles/lenses for classroom sessions.
#
# Mirrors the pattern in story_genre_generator.py:
#   1. LLM generates 50 angles at high temperature
#   2. Python picks a random angle from the list
#   3. The list is cached to disk and refreshed when exhausted or stale
#
# Key functions:
#   generate_teaching_angles(basil_assessment) -> list[str]
#   pick_angle(basil_assessment) -> str

import os
import json
import random
from datetime import datetime
from openai import OpenAI

from config import (
    TASK_AGENT_MODEL,
    PROMPT_TEACHING_ANGLE_GENERATOR,
    TEACHING_ANGLES_FILE,
    CLASSROOM_DIR,
)
from file_lock_utils import get_lock

from llm_client import create_smart_client
client = create_smart_client()

FALLBACK_ANGLES = [
    "historical origins",
    "scientific principles behind",
    "cultural traditions around the world",
    "famous people and pioneers in",
    "comparison across countries",
    "everyday applications of",
    "how it's made or built",
    "the math and numbers behind",
    "geography and places related to",
    "artistic expression in",
    "inventions and discoveries in",
    "philosophical questions about",
    "fun facts and world records",
    "how it connects to faith and values",
    "environmental and ecological impact",
    "careers and jobs related to",
    "how it has changed over time",
    "mysteries and unsolved questions in",
    "the future of",
    "how it works at a microscopic level",
    "stories and legends about",
    "economics and trade related to",
    "health and the human body connections",
    "music and sound connections",
    "architecture and design in",
    "language and vocabulary of",
    "animals and nature connections",
    "technology and innovation in",
    "sports and competition in",
    "food and cooking connections",
]


def _load_prompt_template() -> str:
    """Load the teaching angle generator prompt template."""
    if os.path.exists(PROMPT_TEACHING_ANGLE_GENERATOR):
        with open(PROMPT_TEACHING_ANGLE_GENERATOR, "r") as f:
            return f.read()
    raise FileNotFoundError(
        f"Teaching angle generator prompt not found: {PROMPT_TEACHING_ANGLE_GENERATOR}"
    )


def _load_cached_angles() -> dict:
    """Load cached angles from disk. Returns full data dict or empty dict."""
    if not os.path.exists(TEACHING_ANGLES_FILE):
        return {}
    try:
        with open(TEACHING_ANGLES_FILE, "r") as f:
            return json.load(f)
    except (json.JSONDecodeError, IOError):
        return {}


def _save_angles(angles: list, age_band: int):
    """Save angles list to the cache file."""
    data = {
        "generated_at": datetime.now().isoformat(),
        "age_band": age_band,
        "angles": angles,
    }
    os.makedirs(os.path.dirname(TEACHING_ANGLES_FILE), exist_ok=True)
    with open(TEACHING_ANGLES_FILE, "w") as f:
        json.dump(data, f, indent=2)


def generate_teaching_angles(
    basil_assessment: dict,
    recent_angles: list = None,
    n: int = 50,
) -> list:
    """
    Generate a diverse list of teaching angles/lenses via LLM.

    Args:
        basil_assessment: Dict with age_band, capabilities, etc.
        recent_angles: List of recently used angle names to avoid.
        n: Number of angles to request.

    Returns:
        List of angle name strings (deduplicated, filtered).
    """
    age_band = basil_assessment.get("age_band", 0)

    if recent_angles:
        recent_text = ", ".join(recent_angles[-30:])
    else:
        recent_text = "(none)"

    template = _load_prompt_template()
    prompt = template.format(recent_angles=recent_text)

    system_msg = f"Generate exactly {n} teaching angles. Output valid JSON only."

    try:
        response = client.chat.completions.create(
            model=TASK_AGENT_MODEL,
            messages=[
                {"role": "system", "content": system_msg},
                {"role": "user", "content": prompt},
            ],
            temperature=1.0,
            max_tokens=2000,
        )

        raw_output = response.choices[0].message.content.strip()

        if raw_output.startswith("```"):
            lines = raw_output.split("\n")
            raw_output = "\n".join(lines[1:-1])

        data = json.loads(raw_output)
        angles_list = data.get("angles", [])

        seen = set()
        recent_lower = set(a.lower().strip() for a in (recent_angles or []))
        filtered = []

        for angle in angles_list:
            if isinstance(angle, str):
                angle = angle.strip()
                if not angle:
                    continue
                key = angle.lower()
                if key in seen or key in recent_lower:
                    continue
                seen.add(key)
                filtered.append(angle)

        print(f"[TeachingAngle] Generated {len(filtered)} angles for age_band={age_band}")

        _save_angles(filtered, age_band)

        return filtered

    except json.JSONDecodeError as e:
        print(f"[TeachingAngle] JSON parse error: {e}")
        return FALLBACK_ANGLES[:]
    except Exception as e:
        print(f"[TeachingAngle] Error: {e}")
        return FALLBACK_ANGLES[:]


def pick_angle(basil_assessment: dict, used_angles_this_session: list = None) -> str:
    """
    Pick a random teaching angle for the current classroom session.

    Loads the cached angle list, regenerating it if empty or missing.
    Avoids angles already used in this session (if provided).

    Args:
        basil_assessment: Dict with age_band, capabilities, etc.
        used_angles_this_session: Angles already tried this session (for retries).

    Returns:
        An angle string, e.g. "historical origins".
    """
    used_this_session = set(
        a.lower().strip() for a in (used_angles_this_session or [])
    )

    with get_lock(TEACHING_ANGLES_FILE):
        cached = _load_cached_angles()
        angles = cached.get("angles", [])

        available = [a for a in angles if a.lower().strip() not in used_this_session]

        if len(available) < 5:
            print(f"[TeachingAngle] Only {len(available)} angles available, regenerating...")
            angles = generate_teaching_angles(
                basil_assessment,
                recent_angles=list(used_this_session),
            )
            available = [a for a in angles if a.lower().strip() not in used_this_session]

    if not available:
        available = [
            a for a in FALLBACK_ANGLES
            if a.lower().strip() not in used_this_session
        ]
        if not available:
            available = FALLBACK_ANGLES[:]

    chosen = random.choice(available)
    return chosen


if __name__ == "__main__":
    print("Testing Teaching Angle Generator...")
    print()

    test_assessment = {
        "age_band": 2,
        "capabilities": ["Some word production", "Basic pattern recognition"],
    }

    angles = generate_teaching_angles(test_assessment)
    print(f"\nGenerated {len(angles)} angles:")
    for i, angle in enumerate(angles, 1):
        print(f"  {i:>3}. {angle}")

    print(f"\n--- Random picks ---")
    for _ in range(5):
        angle = pick_angle(test_assessment)
        print(f"  Picked: {angle}")