explainers/explainer_types.py

from dataclasses import dataclass, field
from typing import List, Optional, Dict, Any


@dataclass
class ExplainerScaffold:
    concept: Optional[str] = None
    ask: Optional[str] = None
    givens: List[str] = field(default_factory=list)
    target: Optional[str] = None

    setup_actions: List[str] = field(default_factory=list)
    intermediate_steps: List[str] = field(default_factory=list)
    first_move: Optional[str] = None
    next_hint: Optional[str] = None

    common_traps: List[str] = field(default_factory=list)
    variables_to_define: List[str] = field(default_factory=list)
    equations_to_form: List[str] = field(default_factory=list)

    answer_hidden: bool = True

    solution_path_type: Optional[str] = None
    key_operations: List[str] = field(default_factory=list)
    hint_ladder: List[str] = field(default_factory=list)


@dataclass
class ExplainerResult:
    understood: bool = False
    topic: Optional[str] = None

    summary: Optional[str] = None
    teaching_points: List[str] = field(default_factory=list)
    scaffold: ExplainerScaffold = field(default_factory=ExplainerScaffold)
    meta: Dict[str, Any] = field(default_factory=dict)

    asks_for: Optional[str] = None
    givens: List[str] = field(default_factory=list)
    constraints: List[str] = field(default_factory=list)
    relationships: List[str] = field(default_factory=list)
    needed_concepts: List[str] = field(default_factory=list)
    trap_notes: List[str] = field(default_factory=list)

    strategy_hint: Optional[str] = None
    plain_english: Optional[str] = None