lang_tools.exercises.base

Common exercise interface shared by every mechanic.

Pattern rules

Each concrete exercise builds an ExerciseRound, evaluates user input via submit, and returns a RoundResult whose word_results feed back into UserWordProgress. Calling finish() aggregates a SessionSummary and optionally persists progress through a caller-supplied callback.

Classes:

• ExerciseRound –

  Generic round container.

• RoundResult –

  Outcome of one submit() call.

• SessionSummary –

  Aggregate stats produced by finish().

• WordResult –

  Per-word outcome of a single round.

ExerciseRound

Bases: BaseModel

Generic round container.

Attributes:

• prompt (Any) –

  Exercise-specific prompt payload.

• expected (Any) –

  Exercise-specific expected answer used by submit.

RoundResult

Bases: BaseModel

Outcome of one submit() call.

Attributes:

• correct (bool) –

  Whether the round overall counts as correct.

• feedback (str | None) –

  Optional human-readable feedback message.

• word_results (list[WordResult]) –

  Per-word outcomes for progress tracking.

SessionSummary

Bases: BaseModel

Aggregate stats produced by finish().

Attributes:

• exercise_type (ExerciseType) –

  Tag of the originating exercise.

• total_rounds (int) –

  Number of rounds played.

• correct_rounds (int) –

  Number of rounds the user completed correctly.

• words_practiced (list[str]) –

  Distinct word IDs touched during the session.

• duration_seconds (float) –

  Wall-clock duration in seconds.

WordResult

Bases: BaseModel

Per-word outcome of a single round.

Attributes:

• word_id (str) –

  ID of the involved Word.

• correct (bool) –

  Whether the user got it right.