subject_topic_generator.py

# subject_topic_generator.py
# Generates specific topics within a school subject for classroom sessions.
#
# Mirrors the pattern in story_genre_generator.py but with per-subject caching:
#   1. LLM generates 30-40 topics for a given subject
#   2. Topics are cached per-subject (one JSON file per normalized subject name)
#   3. Python picks a random topic from the cached list
#   4. Cache is refreshed when exhausted or missing
#
# Key functions:
#   generate_topics_for_subject(subject, recent_topics) -> list[str]
#   pick_topic(subject, basil_assessment, used_topics_this_session) -> str

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

from config import (
    TASK_AGENT_MODEL,
    PROMPT_SUBJECT_TOPIC_GENERATOR,
    SUBJECT_TOPICS_DIR,
)
from file_lock_utils import get_lock

from llm_client import create_smart_client
client = create_smart_client()


def _normalize_subject_key(subject: str) -> str:
    """Normalize subject name to a safe filesystem key."""
    key = subject.lower().strip()
    key = re.sub(r'[^a-z0-9]+', '_', key)
    key = key.strip('_')
    return key or "unknown"


def _cache_path_for_subject(subject: str) -> str:
    """Get the cache file path for a given subject."""
    key = _normalize_subject_key(subject)
    return os.path.join(SUBJECT_TOPICS_DIR, f"{key}.json")


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


def _load_cached_topics(subject: str) -> dict:
    """Load cached topics for a subject. Returns full data dict or empty dict."""
    path = _cache_path_for_subject(subject)
    if not os.path.exists(path):
        return {}
    try:
        with open(path, "r") as f:
            return json.load(f)
    except (json.JSONDecodeError, IOError):
        return {}


def _save_topics(subject: str, topics: list):
    """Save topics list to the per-subject cache file."""
    data = {
        "generated_at": datetime.now().isoformat(),
        "subject": subject,
        "topics": topics,
    }
    os.makedirs(SUBJECT_TOPICS_DIR, exist_ok=True)
    path = _cache_path_for_subject(subject)
    with open(path, "w") as f:
        json.dump(data, f, indent=2)


def generate_topics_for_subject(
    subject: str,
    recent_topics: list = None,
    n: int = 35,
) -> list:
    """
    Generate specific topics within a subject via LLM.

    Args:
        subject: The school subject (e.g., "Geography", "Music")
        recent_topics: Topics recently used (to avoid in generation)
        n: Approximate number of topics to request

    Returns:
        List of topic name strings (deduplicated, filtered).
    """
    if recent_topics:
        recent_text = ", ".join(recent_topics[-20:])
    else:
        recent_text = "(none)"

    template = _load_prompt_template()
    prompt = template.format(
        subject=subject,
        recent_topics=recent_text,
    )

    system_msg = f"Generate 30-40 specific topics within the subject '{subject}'. 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)
        topics_list = data.get("topics", [])

        seen = set()
        recent_lower = set(t.lower().strip() for t in (recent_topics or []))
        filtered = []

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

        print(f"[SubjectTopic] Generated {len(filtered)} topics for '{subject}'")

        _save_topics(subject, filtered)

        return filtered

    except json.JSONDecodeError as e:
        print(f"[SubjectTopic] JSON parse error for '{subject}': {e}")
        return _fallback_topics(subject)
    except Exception as e:
        print(f"[SubjectTopic] Error for '{subject}': {e}")
        return _fallback_topics(subject)


def pick_topic(
    subject: str,
    basil_assessment: dict = None,
    used_topics_this_session: list = None,
) -> str:
    """
    Pick a random topic within the given subject.

    Loads the cached topic list for this subject, regenerating if
    empty or missing. Avoids topics already used this session.

    Args:
        subject: The school subject
        basil_assessment: Dict with age_band, capabilities, etc. (unused for now)
        used_topics_this_session: Topics already tried this session (for retries)

    Returns:
        A topic string, e.g., "Geography of Iran".
    """
    used_this_session = set(
        t.lower().strip() for t in (used_topics_this_session or [])
    )

    cache_path = _cache_path_for_subject(subject)
    lock_path = cache_path  # Lock per-subject file

    os.makedirs(SUBJECT_TOPICS_DIR, exist_ok=True)

    with get_lock(lock_path):
        cached = _load_cached_topics(subject)
        topics = cached.get("topics", [])

        available = [t for t in topics if t.lower().strip() not in used_this_session]

        if len(available) < 3:
            print(f"[SubjectTopic] Only {len(available)} topics for '{subject}', regenerating...")
            topics = generate_topics_for_subject(
                subject,
                recent_topics=list(used_this_session),
            )
            available = [t for t in topics if t.lower().strip() not in used_this_session]

    if not available:
        fallback = _fallback_topics(subject)
        available = [t for t in fallback if t.lower().strip() not in used_this_session]
        if not available:
            available = fallback

    chosen = random.choice(available)
    return chosen


def _fallback_topics(subject: str) -> list:
    """Return generic fallback topics when LLM generation fails."""
    return [
        f"Introduction to {subject}",
        f"The History of {subject}",
        f"Famous Figures in {subject}",
        f"{subject} Around the World",
        f"The Science Behind {subject}",
        f"Fun Facts About {subject}",
        f"{subject} in Everyday Life",
        f"Great Discoveries in {subject}",
        f"{subject} and the Natural World",
        f"How {subject} Has Changed Over Time",
    ]


if __name__ == "__main__":
    print("Testing Subject Topic Generator...")
    print()

    test_subjects = ["Geography", "Music", "Marine Biology"]

    for subject in test_subjects:
        print(f"{'='*50}")
        print(f"Subject: {subject}")
        print(f"{'='*50}")

        topics = generate_topics_for_subject(subject)
        print(f"Generated {len(topics)} topics:")
        for i, topic in enumerate(topics, 1):
            print(f"  {i:>3}. {topic}")

        print(f"\n--- Random picks ---")
        used = []
        for _ in range(3):
            t = pick_topic(subject, used_topics_this_session=used)
            used.append(t)
            print(f"  Picked: {t}")
        print()