Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

25.4 KB
Raw Blame
from __future__ import annotations

from enum import Enum
import time
from typing import Any, Literal

from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator

_KNOWLEDGE_TYPE_LEGACY: dict[str, str] = {
    "记忆型": "memory",
    "概念型": "concept",
    "程序型": "procedure",
    "设计型": "design",
}

_ERROR_TYPE_LEGACY: dict[str, str] = {
    "知识结构性": "structural",
    "理解偏差型": "deviation",
    "应用错误": "application",
    "元认知型": "metacognitive",
}


class KnowledgeType(str, Enum):
    MEMORY = "memory"
    CONCEPT = "concept"
    PROCEDURE = "procedure"
    DESIGN = "design"

    @classmethod
    def _missing_(cls, value: object) -> KnowledgeType | None:
        mapped = _KNOWLEDGE_TYPE_LEGACY.get(str(value))
        return cls(mapped) if mapped else None


class ErrorType(str, Enum):
    KNOWLEDGE_STRUCTURAL = "structural"
    UNDERSTANDING_DEVIATION = "deviation"
    APPLICATION_ERROR = "application"
    METACOGNITIVE = "metacognitive"

    @classmethod
    def _missing_(cls, value: object) -> ErrorType | None:
        mapped = _ERROR_TYPE_LEGACY.get(str(value))
        return cls(mapped) if mapped else None


# Stages removed in the Mastery Path simplification are mapped onto the nearest
# surviving stage so progress persisted by the older engine still deserializes.
_STAGE_LEGACY: dict[str, str] = {
    "diagnostic_phase1": "diagnostic",
    "diagnostic_phase2": "diagnostic",
    "metacognitive_intro": "explain",
    "plan": "explain",
    "pretest": "explain",
    "practice_quiz": "practice",
    "module_test": "review",
}


class LearningStage(str, Enum):
    """The Mastery Path loop: diagnose once, then per knowledge point teach and
    check understanding, then practice the module, diagnose errors, and schedule
    spaced review."""

    DIAGNOSTIC = "diagnostic"
    EXPLAIN = "explain"
    FEYNMAN_CHECK = "feynman_check"
    PRACTICE = "practice"
    ERROR_DIAGNOSIS = "error_diagnosis"
    REVIEW = "review"
    COMPLETED = "completed"

    @classmethod
    def _missing_(cls, value: object) -> LearningStage | None:
        mapped = _STAGE_LEGACY.get(str(value))
        return cls(mapped) if mapped else None


class KnowledgePoint(BaseModel):
    model_config = ConfigDict(extra="ignore")

    id: str
    name: str
    type: KnowledgeType
    module_id: str
    # Required objectives, not a presentation order. Empty on legacy paths.
    prerequisite_ids: list[str] = Field(default_factory=list)
    # Selected non-goal sources that justify this objective. They are curriculum
    # provenance, not proof of factual correctness or retrieval permission.
    topic_source_ids: list[str] = Field(default_factory=list)
    required_visual_tasks: list[
        Literal["identification", "relationship", "table_graph", "comparison"]
    ] = Field(default_factory=list)


class LearningModule(BaseModel):
    model_config = ConfigDict(extra="ignore")

    id: str
    name: str
    order: int
    pass_threshold: float = 0.7
    # What this module is *for*, in one sentence, written when the outline was
    # designed. Two things read it: the learner, who otherwise sees a bare noun
    # where a purpose belongs, and ``mastery_revise``, which may only reshape
    # knowledge points in ways this sentence still covers. Empty means an
    # outline built before the field existed — every reader degrades to the
    # module name, so no migration is needed.
    objective: str = ""
    knowledge_points: list[KnowledgePoint] = Field(default_factory=list)


class DiagnosticResult(BaseModel):
    model_config = ConfigDict(extra="ignore")

    total_questions: int = 0
    correct_count: int = 0
    module_mastery: dict[str, float] = Field(default_factory=dict)


class QuizAttempt(BaseModel):
    model_config = ConfigDict(extra="ignore")

    question_id: str
    knowledge_point_id: str
    module_id: str = ""
    is_correct: bool
    result: Literal["correct", "partial", "incorrect"] | None = None
    user_answer: Any = None
    error_type: ErrorType | None = None
    self_attribution: str = ""
    mastery_estimate: float = 0.0
    timestamp: float = Field(default_factory=time.time)
    # Invalid questions / wrong answer keys are kept for audit, but voided
    # attempts are excluded from mastery, errors, and spaced repetition.
    voided: bool = False
    void_reason: str = ""
    independent: bool = True
    visual_context: dict[str, Any] = Field(default_factory=dict)

    @model_validator(mode="after")
    def _legacy_result(self):
        if self.result is None:
            self.result = "correct" if self.is_correct else "incorrect"
        return self


class RetryAttempt(BaseModel):
    model_config = ConfigDict(extra="ignore")

    timestamp: float
    is_correct: bool
    attempt_number: int


class ErrorRecord(BaseModel):
    model_config = ConfigDict(extra="ignore")

    id: str
    question_id: str
    knowledge_point_id: str
    module_id: str
    error_type: ErrorType
    self_attribution: str = ""
    ai_confirmation: str = ""
    retry_history: list[RetryAttempt] = Field(default_factory=list)
    status: Literal["active", "retrying", "review", "graduated"] = "active"
    created_at: float = Field(default_factory=time.time)


class LearningEvidence(BaseModel):
    """One durable review/assessment event that can recompute retention state.

    Quality is a normalized 0..1 review strength inferred from the outcome
    (not a learner self-rating). Trusted linked assessments may originate in
    another learning surface.
    """

    model_config = ConfigDict(extra="ignore")

    evidence_id: str = ""
    question_id: str = ""
    knowledge_point_id: str
    timestamp: float = Field(default_factory=time.time)
    source: str = "mastery_path"
    assessment_type: Literal["quiz", "qualitative", "review"] = "quiz"
    result: Literal["correct", "incorrect", "partial"] = "incorrect"
    quality: float | None = None
    hints_used: int = 0
    attempt_count: int = 1
    confidence: float | None = None
    learner_answer: str = ""
    feedback: str = ""
    response_time: float | None = None
    session_id: str = ""
    turn_id: str = ""
    visual_context: dict[str, Any] = Field(default_factory=dict)


class RepetitionState(BaseModel):
    model_config = ConfigDict(extra="ignore")

    interval_index: int = 0
    consecutive_correct: int = 0
    consecutive_wrong: int = 0
    next_review_at: float
    # Retention fields. Absent on state written before adaptive SRS; defaults
    # keep old JSON loadable. ``stability == 0`` means "never hydrated" —
    # the scheduler fills it from ``interval_index`` without changing due time.
    difficulty: float = 0.3
    stability: float = 0.0
    retrievability: float = 1.0
    desired_retention: float = 0.9
    review_count: int = 0
    lapse_count: int = 0
    last_review_at: float | None = None
    # The review (or initial schedule) that set ``next_review_at``. Practice
    # inside one session updates ``last_review_at`` but keeps this anchor, so
    # changing the target cannot silently postpone a previously due review.
    last_scheduled_at: float | None = None
    scheduled_after_failure: bool = False


class ReviewTask(BaseModel):
    model_config = ConfigDict(extra="ignore")

    id: str
    knowledge_point_id: str
    knowledge_type: KnowledgeType
    due_at: float
    priority: int
    state: RepetitionState
    forgetting_risk: float = 0.0
    reason: str = ""
    evidence_source: str = ""
    evidence_id: str = ""


class PendingOption(BaseModel):
    """One choice a mastery question offers: a stable label and its answer text.

    Two fields rather than one ``"A: body"`` string because they are two
    different things — the learner picks the label, the card renders the body,
    and grading compares labels. The flat string was inherited from the
    generic ``ask_user`` card, and it had to be split back apart with a regex
    on every read: that is how the maths option ``"x - 1 = 0"`` once
    registered as label ``X`` with the body ``"1 = 0"``. Mastery questions now
    carry the split the tutor made.
    """

    model_config = ConfigDict(extra="ignore")

    label: str
    body: str


class PendingQuestion(BaseModel):
    """A question posed to the learner and awaiting their answer.

    Persisted so grading is deterministic across turns: the expected answer
    lives here server-side and never round-trips through the model. The tutor
    poses a question with ``mastery_quiz`` (storing this), the learner answers
    on a later turn, and ``mastery_grade`` scores the stored answer.
    """

    model_config = ConfigDict(extra="ignore")

    question_id: str
    knowledge_point_id: str
    module_id: str = ""
    prompt: str = ""
    question_type: str = "short"
    expected_answer: str = ""
    options: list[PendingOption] = Field(default_factory=list)
    # Reference explanation and difficulty, captured when the question is
    # posed. Server-side like ``expected_answer`` — ``public_pending_question``
    # never projects them, so an explanation cannot leak the answer into the
    # card the learner is about to answer. They travel with the attempt into
    # the question bank, which is what makes a mastery mistake reviewable
    # later instead of a bare right/wrong.
    explanation: str = ""
    difficulty: str = ""
    # Server-side provenance snapshot; never projected onto an answer card.
    source_evidence: dict[str, Any] = Field(default_factory=dict)
    # Server-owned exposure evidence, independent of visual-task metadata.
    # Never included in the learner's question/answer-key projection.
    assistance_used: bool = False
    # Native registration identity; later teaching must not contaminate an
    # unrelated question merely because it cites the same physical page.
    assistance_context: dict[str, str] = Field(default_factory=dict)
    created_at: float = Field(default_factory=time.time)
    visual_context: dict[str, Any] = Field(default_factory=dict)
    accepted_answers: list[str] = Field(default_factory=list)
    # One active interaction can present multiple independent questions. The
    # parent owns lifecycle only; answer keys and credit remain on its leaves.
    questions: list[PendingQuestion] = Field(default_factory=list)

    @model_validator(mode="after")
    def _validate_group(self) -> PendingQuestion:
        if self.question_type != "group":
            if self.questions:
                raise ValueError("Only a group may contain questions")
            return self
        if not 2 <= len(self.questions) <= 4:
            raise ValueError("A question group needs two to four questions")
        ids = [q.question_id for q in self.questions]
        if len(set(ids)) != len(ids) or self.question_id in ids or not all(ids):
            raise ValueError("Group question ids must be distinct and nonempty")
        question_keys = {(q.knowledge_point_id, q.prompt.strip()) for q in self.questions}
        if len(question_keys) != len(self.questions):
            raise ValueError(
                "A group needs distinct questions, not copies of the same objective prompt"
            )
        if any(
            q.question_type not in {"choice", "short", "open"}
            or q.questions
            or not q.expected_answer.strip()
            or not q.prompt.strip()
            or not q.knowledge_point_id.strip()
            for q in self.questions
        ):
            raise ValueError("Group leaves need independent, non-nested answer contracts")
        if self.expected_answer or self.options or self.visual_context:
            raise ValueError("A group parent cannot carry an answer key or visual task")
        return self

    @field_validator("options", mode="before")
    @classmethod
    def _read_legacy_option_strings(cls, value: Any) -> Any:
        """Read the ``["A: body", …]`` rows written before options were split.

        The regex inference lives here, on the way in, so it runs once for a
        question stored by an older version instead of on every read — and
        never for a question posed since.
        """
        if not isinstance(value, list) or not value:
            return value
        if not all(isinstance(entry, str) for entry in value):
            return value
        from deeptutor.learning.pending import parse_options

        return [{"label": label, "body": body} for label, body in parse_options(value).items()]

    @property
    def choice_map(self) -> dict[str, str]:
        """The ``{label: body}`` form grading and the question bank compare on."""
        return {option.label: option.body for option in self.options}


class InteractionStatus(str, Enum):
    """Durable lifecycle for one learner-facing mastery interaction.

    The chat runtime may disappear at any point; this state is the source of
    truth for whether a question still needs an answer or has already been
    graded.  Terminal interactions are retained for idempotent retries and
    audit history.
    """

    REGISTERED = "registered"
    AWAITING_INPUT = "awaiting_input"
    ANSWERED = "answered"
    GRADED = "graded"
    ABANDONED = "abandoned"


class MasteryInteraction(BaseModel):
    """A persisted question/answer transaction for a mastery path."""

    model_config = ConfigDict(extra="ignore")

    interaction_id: str
    path_id: str
    question: PendingQuestion
    status: InteractionStatus = InteractionStatus.REGISTERED
    session_id: str = ""
    turn_id: str = ""
    user_answer: str = ""
    answers: dict[str, str] = Field(default_factory=dict)
    result: dict[str, Any] = Field(default_factory=dict)
    created_at: float = Field(default_factory=time.time)
    updated_at: float = Field(default_factory=time.time)


class MasteryEvent(BaseModel):
    """Committed path event consumed by recovery and future live UIs."""

    model_config = ConfigDict(extra="ignore")

    id: int = 0
    path_id: str
    revision: int
    event_type: str
    payload: dict[str, Any] = Field(default_factory=dict)
    session_id: str = ""
    turn_id: str = ""
    created_at: float = Field(default_factory=time.time)


class MasteryPathLease(BaseModel):
    """The one active mutating turn allowed for a mastery path."""

    model_config = ConfigDict(extra="ignore")

    path_id: str
    session_id: str
    turn_id: str
    acquired_at: float = Field(default_factory=time.time)


class TopicSourceKind(str, Enum):
    """What a learner may point a mastery goal at.

    Everything DeepTutor already holds for them is fair game: their library
    (``BOOK``), their notes (``NOTEBOOK``), an indexed corpus or one document
    inside it (``KNOWLEDGE_BASE`` / ``FILE``), and — added with the mastery
    goal rework — the working history that shows what they have actually been
    doing: past conversations, their own wrong answers, drafts they are
    writing, and study partner transcripts.
    """

    GOAL = "goal"
    BOOK = "book"
    NOTEBOOK = "notebook"
    KNOWLEDGE_BASE = "knowledge_base"
    FILE = "file"
    #: One chat session. ``source_id`` is its session id, or a
    #: ``partner:{pid}:{session_key}`` reference for a study partner's.
    CHAT = "chat"
    #: One question-bank entry — a question the learner has already answered.
    #: ``source_id`` is its numeric entry id.
    QUESTION_BANK = "question_bank"
    #: One Co-Writer draft. ``source_id`` is the document id.
    COWRITER = "cowriter"
    #: One partner-group conversation, as ``{group_id}:{session_key}``.
    PARTNER_GROUP = "partner_group"


class TopicSource(BaseModel):
    """One ordered source selected while designing a learning topic."""

    model_config = ConfigDict(extra="ignore")

    id: str
    kind: TopicSourceKind
    source_id: str = ""
    label: str
    excerpt: str = ""
    position: int = 0
    available: bool = True
    metadata: dict[str, Any] = Field(default_factory=dict)
    created_at: float = Field(default_factory=time.time)


class TopicMetadata(BaseModel):
    """Product-level identity around the deterministic learning aggregate."""

    model_config = ConfigDict(extra="ignore")

    path_id: str
    goal: str = ""
    description: str = ""
    emoji: str = "🧭"
    map_seed: int = 0
    status: Literal["active", "archived"] = "active"
    created_at: float = Field(default_factory=time.time)
    updated_at: float = Field(default_factory=time.time)


class MasteryTopic(BaseModel):
    model_config = ConfigDict(extra="ignore")

    metadata: TopicMetadata
    sources: list[TopicSource] = Field(default_factory=list)


class LearnerMasteryOverride(BaseModel):
    """Explicit learner claim that bypasses, but never impersonates, evidence."""

    model_config = ConfigDict(extra="ignore")

    knowledge_point_id: str
    note: str = ""
    created_at: float = Field(default_factory=time.time)


class DeferredObjective(BaseModel):
    """Learner asked to leave this objective for now without claiming mastery."""

    model_config = ConfigDict(extra="ignore")

    knowledge_point_id: str
    note: str = ""
    created_at: float = Field(default_factory=time.time)


class TeachingPreference(BaseModel):
    """An explicit path-local request, independent of other preferences."""

    model_config = ConfigDict(extra="forbid")
    text: str = Field(min_length=1, max_length=400)
    evidence: str = Field(min_length=1, max_length=300)
    session_id: str = ""
    turn_id: str = ""
    updated_at: float = Field(default_factory=time.time)


class TeachingObservation(BaseModel):
    """A teaching attempt or difficulty; never an assessment of mastery."""

    model_config = ConfigDict(extra="forbid")
    knowledge_point_id: str = Field(min_length=1, max_length=200)
    text: str = Field(min_length=1, max_length=400)
    basis: Literal["learner_report", "tentative"] = "tentative"
    strategy: str = Field(default="", max_length=300)
    outcome: Literal["unknown", "helped", "not_helped"] = "unknown"
    evidence: str = Field(default="", max_length=300)
    session_id: str = ""
    turn_id: str = ""
    updated_at: float = Field(default_factory=time.time)


class LearnerProfile(BaseModel):
    """Who is learning this goal — collected once, honoured every turn.

    An outline used to be designed from the goal and the materials alone, so
    the same "I want to learn linear algebra" produced the same route for a
    second-year undergraduate and for a backend engineer with six evenings.
    These are the things only the learner knows; the tutor can read the
    material's own difficulty for itself.

    Intake answers are free text on purpose. The useful answer to "how much time do
    you have" is "两周,每天晚上一小时", not an enum the learner has to be
    translated into. Empty means never asked, which is why nothing here is
    required: a goal created before intake existed reads as a profile with
    nothing in it, and the tutor simply asks.
    """

    model_config = ConfigDict(extra="ignore")

    #: What they can already do — where the route should start, and where
    #: ``probe`` should aim.
    prior_knowledge: str = ""
    #: What "done" means to them. "Read papers in the field" and "implement it
    #: myself" are different routes over the same subject.
    target_level: str = ""
    #: How much time they have. Sizes the outline.
    time_budget: str = ""
    #: How they want it taught — language, worked examples over prose,
    #: intuition before formalism.
    preferences: str = ""
    #: Explicit sequencing preference. Existing paths keep the diagnostic default.
    teaching_strategy: Literal["probe_first", "teach_first"] = "probe_first"
    #: Anything else worth carrying that the four fields above do not hold.
    notes: str = ""
    teaching_preferences: dict[str, TeachingPreference] = Field(default_factory=dict)
    teaching_observations: dict[str, TeachingObservation] = Field(default_factory=dict)
    updated_at: float = Field(default_factory=time.time)

    def is_empty(self) -> bool:
        """Whether intake has produced nothing yet."""
        return not any(
            (
                self.prior_knowledge.strip(),
                self.target_level.strip(),
                self.time_budget.strip(),
                self.preferences.strip(),
                self.teaching_strategy != "probe_first",
                self.notes.strip(),
                self.teaching_preferences,
            )
        )


ReadingExtensionResultType = Literal[
    "card",
    "quiz",
    "feedback",
    "browser_speech",
]


class ReadingProgressRecord(BaseModel):
    """One material's Reading progress in an account's learning records."""

    model_config = ConfigDict(extra="ignore")

    material_id: str
    latest_locator: int = Field(ge=1)
    latest_percentage: float = Field(ge=0.0, le=1.0)
    furthest_locator: int = Field(ge=1)
    furthest_percentage: float = Field(ge=0.0, le=1.0)
    updated_at: float = Field(default_factory=time.time)


class ReadingActivityRecord(BaseModel):
    """One successful Reading-extension action, without source content."""

    model_config = ConfigDict(extra="ignore")

    activity_id: str
    material_id: str
    extension_id: str
    action: str
    locator: int = Field(ge=1)
    result_type: ReadingExtensionResultType
    created_at: float = Field(default_factory=time.time)


class ReadingLearningRecords(BaseModel):
    """Account-scoped Reading summary for reporting surfaces."""

    model_config = ConfigDict(extra="ignore")

    progress: list[ReadingProgressRecord] = Field(default_factory=list)
    activities: list[ReadingActivityRecord] = Field(default_factory=list)


class LearningProgress(BaseModel):
    model_config = ConfigDict(extra="ignore")

    book_id: str
    # Who is learning this goal. Absent on every path created before intake
    # existed, and on any goal whose learner has not been asked yet — readers
    # treat both the same way, so no migration is needed.
    learner_profile: LearnerProfile | None = None
    # The learner-facing name of this path. Empty means "never named": the
    # display name is then derived (``policy.path_display_name``), which is how
    # every path behaved before this field existed — so an aggregate persisted
    # without it needs no migration.
    name: str = ""
    diagnostic: DiagnosticResult | None = None
    modules: list[LearningModule] = Field(default_factory=list)
    current_module_id: str = ""
    current_stage: LearningStage = LearningStage.DIAGNOSTIC
    current_kp_index: int = 0
    mastery_levels: dict[str, float] = Field(default_factory=dict)
    # Qualitative gate for CONCEPT / DESIGN knowledge points: True once the
    # tutor judges the learner's explanation sufficient (``mastery_assess``).
    # The quantitative ``mastery_levels`` gate covers MEMORY / PROCEDURE.
    qualitative_mastery: dict[str, bool] = Field(default_factory=dict)
    knowledge_types: dict[str, KnowledgeType] = Field(default_factory=dict)
    lesson_evidence: dict[str, dict[str, Any]] = Field(default_factory=dict)
    source_grounded: bool = False
    # Exact pages authorized for learner display, kept with the native path.
    # A private retrieval or lesson packet is not a public exposure receipt.
    source_exposures: list[dict[str, Any]] = Field(default_factory=list)
    quiz_attempts: list[QuizAttempt] = Field(default_factory=list)
    error_records: list[ErrorRecord] = Field(default_factory=list)
    # Durable review history used to recompute retention. Distinct from
    # ``quiz_attempts`` (mastery evidence) so the two can evolve separately.
    learning_evidence: list[LearningEvidence] = Field(default_factory=list)
    # One target per learning path; older aggregates load at the baseline 0.9.
    # It is copied into each repetition state when that state is created.
    desired_retention: float = Field(default=0.9, ge=0.7, le=0.99, allow_inf_nan=False)
    repetition_states: dict[str, RepetitionState] = Field(default_factory=dict)
    review_queue: list[ReviewTask] = Field(default_factory=list)
    # A learner may explicitly claim prior mastery.  Policy exposes this as a
    # separate provenance (``mastery_source=learner``); assessed mastery and
    # its evidence remain untouched and can take over later.
    learner_mastery_overrides: dict[str, LearnerMasteryOverride] = Field(default_factory=dict)
    # Temporarily skipped objectives. These never count as mastered; routing
    # just prefers any other eligible waypoint until only deferred ones remain.
    deferred_objectives: dict[str, DeferredObjective] = Field(default_factory=dict)
    explained_objectives: dict[str, dict[str, Any]] = Field(default_factory=dict)
    # A single outstanding question; grading reads its expected answer so the
    # model never has to recall it across turns.
    pending_question: PendingQuestion | None = None
    feynman_retries: dict[str, int] = Field(default_factory=dict)
    feynman_explanations: dict[str, str] = Field(default_factory=dict)
    stage_failure_counts: dict[str, int] = Field(default_factory=dict)
    stage_failure_notes: dict[str, str] = Field(default_factory=dict)
    version: int = 0
    created_at: float = Field(default_factory=time.time)
    updated_at: float = Field(default_factory=time.time)


__all__ = [
    "LearnerProfile",
    "KnowledgeType",
    "ErrorType",
    "LearningStage",
    "KnowledgePoint",
    "LearningModule",
    "DiagnosticResult",
    "QuizAttempt",
    "RetryAttempt",
    "ErrorRecord",
    "LearningEvidence",
    "RepetitionState",
    "ReviewTask",
    "PendingQuestion",
    "InteractionStatus",
    "MasteryInteraction",
    "MasteryEvent",
    "MasteryPathLease",
    "TopicSourceKind",
    "TopicSource",
    "TopicMetadata",
    "MasteryTopic",
    "LearnerMasteryOverride",
    "DeferredObjective",
    "ReadingActivityRecord",
    "ReadingLearningRecords",
    "ReadingProgressRecord",
    "LearningProgress",
]