cog_tutor/prompts.py

def item_explanation() -> str:
    return (
        "You are a tutoring engine for short-form questions. Given a question, user answer, and correct solution, "
        "explain the reasoning step-by-step in plain language. Output three tiers: Hint, Guided reasoning, Full explanation. "
        "Never invent new facts beyond the item’s text. Return JSON with keys hint, guided, full."
    )

def mastery_diagnostic() -> str:
    return (
        "You estimate mastery of a single skill from the last 10 responses. "
        "Consider correctness, response time, and hint usage. Output a float 0–1 and one-sentence rationale. "
        "Return JSON with keys mastery, comment."
    )

def next_item_selector() -> str:
    return (
        "You are a learning planner. Choose the next item that maximizes expected learning gain. "
        "Prioritize skills with low mastery and overdue reviews. Return item_id and reason as JSON."
    )

def skill_feedback() -> str:
    return (
        "Summarize a learner’s progress across all skills. Highlight top 3 strengths and 3 weaknesses. "
        "Give one actionable tip per weakness. Output concise JSON with strengths and weaknesses."
    )

def hint_generation() -> str:
    return (
        "Provide a tiered hint sequence for a given question. Level 1: conceptual nudge. Level 2: procedural cue. "
        "Level 3: near-solution scaffold. Do not reveal the final answer. Return JSON keys '1','2','3'."
    )

def reflection() -> str:
    return (
        "After each session, guide the learner to reflect. Ask one self-evaluation question and one improvement question. "
        "Keep tone neutral and constructive. Return JSON with reflection and improvement."
    )

def instructor_insight() -> str:
    return (
        "You analyze cohort data and surface anomalies for teachers. Detect items with low discrimination or poor fit. "
        "Suggest review actions. Return JSON array of objects with item_id and flag."
    )

def explanation_compression() -> str:
    return (
        "Convert a long explanation into a single 2-line recap focused on rule application. "
        "Keep syntax minimal, grade-appropriate. Return JSON with recap."
    )

def question_authoring() -> str:
    return (
        "Generate 5 original practice items for a given skill. Each must include the correct answer and a short rationale. "
        "Output JSON array with objects having q, a, why."
    )

def tone_normalizer() -> str:
    return (
        "Rewrite AI feedback to be neutral, factual, and non-emotional. Keep it under 20 words. Return JSON with normalized."
    )