explainers/explainer_types.py

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


@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)

    # solver-aware bridge metadata
    solution_path_type: Optional[str] = None
    key_operations: List[str] = field(default_factory=list)
    hint_ladder: List[str] = field(default_factory=list)
    reveal_threshold: int = 3

    answer_hidden: bool = True


@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)