How to Build an AI Tutor That Teaches Students Through Interactive Conversations

ai-socratic-tutor/
├── app/
│   ├── __init__.py
│   ├── bkt_engine.py
│   └── socratic_ladder.py
├── tests/
│   └── test_ai_tutor.py
└── requirements.txt

from pydantic import BaseModel, Field

class SkillMasteryState(BaseModel):
    skill_id: str
    p_mastery: float = Field(0.20, ge=0.0, le=1.0, description="Current P(L_t)")
    p_transit: float = Field(0.15, ge=0.0, le=1.0, description="P(T) learning rate")
    p_slip: float = Field(0.10, ge=0.0, le=0.49, description="P(S) careless slip rate")
    p_guess: float = Field(0.20, ge=0.0, le=0.49, description="P(G) lucky guess rate")
    attempts: int = 0
    consecutive_errors: int = 0

    @property
    def is_mastered(self) -> bool:
        return self.p_mastery >= 0.95

def update_bkt_mastery(state: SkillMasteryState, is_correct: bool) -> SkillMasteryState:
    """Updates student skill mastery probability P(L_t) using exact Bayesian Knowledge Tracing."""
    p_l = state.p_mastery
    p_t = state.p_transit
    p_s = state.p_slip
    p_g = state.p_guess

    if is_correct:
        # P(L | correct) = [P(L)*(1 - P(S))] / [P(L)*(1 - P(S)) + (1 - P(L))*P(G)]
        num = p_l * (1.0 - p_s)
        den = num + ((1.0 - p_l) * p_g)
        posterior = num / den if den > 0 else p_l
        consecutive_err = 0
    else:
        # P(L | incorrect) = [P(L)*P(S)] / [P(L)*P(S) + (1 - P(L))*(1 - P(G))]
        num = p_l * p_s
        den = num + ((1.0 - p_l) * (1.0 - p_g))
        posterior = num / den if den > 0 else p_l
        consecutive_err = state.consecutive_errors + 1

    new_p_mastery = posterior + ((1.0 - posterior) * p_t)
    return state.model_copy(
        update={
            "p_mastery": round(min(0.999, max(0.001, new_p_mastery)), 4),
            "attempts": state.attempts + 1,
            "consecutive_errors": consecutive_err,
        }
    )

from enum import IntEnum
from pydantic import BaseModel

class HintLevel(IntEnum):
    LEVEL_1_SOCRATIC_QUESTION = 1
    LEVEL_2_CONCEPTUAL_HINT = 2
    LEVEL_3_WORKED_ANALOGY = 3
    LEVEL_4_GUIDED_STEP_SOLUTION = 4

def select_socratic_hint_level(consecutive_errors: int) -> HintLevel:
    """Escalates scaffolding support gradually based on consecutive student struggles."""
    if consecutive_errors <= 1:
        return HintLevel.LEVEL_1_SOCRATIC_QUESTION
    if consecutive_errors == 2:
        return HintLevel.LEVEL_2_CONCEPTUAL_HINT
    if consecutive_errors == 3:
        return HintLevel.LEVEL_3_WORKED_ANALOGY
    return HintLevel.LEVEL_4_GUIDED_STEP_SOLUTION

def verify_no_answer_spoiler(tutor_response: str, canonical_final_answer: str, current_level: HintLevel) -> bool:
    """Ensures the tutor does not leak the final answer string before HintLevel 4."""
    if current_level < HintLevel.LEVEL_4_GUIDED_STEP_SOLUTION:
        if canonical_final_answer.strip().lower() in tutor_response.lower():
            return False
    return True

from app.bkt_engine import SkillMasteryState, update_bkt_mastery
from app.socratic_ladder import (
    HintLevel,
    select_socratic_hint_level,
    verify_no_answer_spoiler,
)

def test_bkt_mastery_progression_reaches_mastery_after_correct_streak():
    state = SkillMasteryState(skill_id="linear_equations_1")
    for _ in range(6):
        state = update_bkt_mastery(state, is_correct=True)
    assert state.p_mastery >= 0.95
    assert state.is_mastered is True

def test_bkt_incorrect_answer_lowers_posterior_and_escalates_hint_level():
    state = SkillMasteryState(skill_id="fractions_add", p_mastery=0.50)
    state = update_bkt_mastery(state, is_correct=False)
    assert state.p_mastery < 0.50
    assert state.consecutive_errors == 1
    assert select_socratic_hint_level(state.consecutive_errors) == HintLevel.LEVEL_1_SOCRATIC_QUESTION

    state = update_bkt_mastery(state, is_correct=False)
    assert select_socratic_hint_level(state.consecutive_errors) == HintLevel.LEVEL_2_CONCEPTUAL_HINT

def test_anti_spoiler_gate_blocks_premature_answer_leak():
    assert verify_no_answer_spoiler(
        "What happens if you subtract 5 from both sides?",
        canonical_final_answer="x = 12",
        current_level=HintLevel.LEVEL_1_SOCRATIC_QUESTION,
    ) is True

    assert verify_no_answer_spoiler(
        "The answer is x = 12.",
        canonical_final_answer="x = 12",
        current_level=HintLevel.LEVEL_1_SOCRATIC_QUESTION,
    ) is False