traininglogs

A session is one workout on one day. A session has three ordered groups of movements: an optional session-level warmup, the main work (exercises), and an optional session-level cooldown. Session warmup/cooldown movements are lightweight (name, reps or duration, notes) and use their own models — they are not exercises. An exercise has sets and, separately, its own optional warmup sets (e.g. ramp-up sets before a lift's working weight) — a different thing from the session-level warmup despite the shared name. A working set may carry a failure technique (myo-reps, lengthened-partials, static hold, drop set) when it's taken to RPE 10.

TrainingSession
├── data_model_version, data_model_type, session_id, user_id, user_name
│                            system fields — injected by the processor, never user-supplied
├── date                     YYYY-MM-DD
├── program = None           real program name; stays unset for ad-hoc sessions (inputs/sessions/)
├── program_author = None
├── program_length_weeks = None
│                            set for real programs — used to validate `week` below
├── phase = None
├── week = None              must be 1..program_length_weeks when both are set
├── is_deload_week = None
├── focus = None
├── session_duration_minutes = None
├── weight_unit               "kg" (default) or "lbs" — lbs converted to kg at parse time
├── warmup = None            [SessionWarmup] — session-level warmup movements
├── exercises                [Exercise] — the main work, always at least one
├── cooldown = None          [SessionCooldown] — session-level cooldown movements
└── notes = None             remarks that don't belong to any specific exercise or set

SessionWarmup / SessionCooldown   (identical shape, two separate models — not Exercise)
├── number, name
├── reps = None
├── duration_seconds = None
└── notes = None

Exercise
├── number, name
├── tags = None              free-text classification: ["strength"], ["cardio"],
│                            ["mobility"], ["skill", "jiu-jitsu"], etc.
├── modality = None          free-text equipment/style: "barbell", "bodyweight", "gi", "pool", etc.
├── movement_pattern = None  list, supports compound patterns: squat, hip_hinge, push,
│                            pull, lunge, carry, rotation
├── target_muscle_groups = None
├── rep_tempo = None
├── current_goal = None      Goal — target weight/sets/rep range/rest for this exercise
├── notes = None
├── warmup_notes = None
├── form_cues = None
├── warmup_sets = None       [WarmupSet] — this exercise's own ramp-up sets, lower-resolution
└── sets = None              [WorkingSet] — the sets that count

WarmupSet
├── number, weight_kg
├── rep_count = None
└── notes = None

WorkingSet                    one flat model — every measurement field optional; the fields
│                            present on a given set describe what kind of set it was
├── number
├── rpe = None                1–10, whole or half steps
├── rest = None                {minutes, seconds} — never both set at once
├── notes = None
├── weight_kg = None
├── rep_count = None          {full, partial}
├── unilateral_rep_count = None   {left: {full, partial}, right: {full, partial}}
├── rep_quality_assessment = None  good | bad | perfect | learning
├── duration_seconds = None
├── distance_meters = None
├── heart_rate_bpm = None
└── failure_technique = None   only valid when rpe == 10; discriminated union on technique_type
    ├── MyoReps    → mini_sets[]        {number, rep_count}
    ├── LLP        → partial_rep_count
    ├── Static     → hold_duration_seconds
    └── DropSet    → drop_sets[]        {number, weight_kg, rep_count}

The default parsing path. The user writes freely — during or after the workout — and the pipeline maps the draft to a TrainingSession. Nothing is written to the database until the person confirms the reading.

The flow

TrainingSession.model_validate() always runs on the final result. The model produces input to Pydantic, never a bypass around it.

ConfirmationCard architecture

The card is a tree of dataclasses defined in agent/validation_card_data.py, built from a TrainingLogLLMExtract by agent/validation_card_builder.py. It is the stable contract between the LLM output and any renderer — terminal today, JSON/frontend later.

UserValidationCard
  SessionHeader              date · focus · duration · program / phase / week
  NotePreview = None         session-level note, shown right after the header
  SessionMovementSection[]   warmup / cooldown, each a MovementRow[]
  ExerciseCard[]
    ExerciseHeader           number · name · goal (plain English)
    WarmupRow[]               weight · reps
    WorkingSetRow[]           weight · reps · RPE · quality · failure (plain English)
    NotePreview = None        first ~40 chars of note + "…" if truncated
    NotePreview = None        same, for the exercise's own warmup notes

Fields the LLM was uncertain about are flagged in uncertain_fields: list[str] (dot-path format, e.g. "exercises[1].sets[0].weight_kg"). The renderer marks those positions with ?. The user's eyes go directly to uncertain fields; everything else can be scanned in seconds.

Form cues are not shown on the card — they are stored but low-stakes if wrong, and omitting them keeps the card skimmable. Notes (session-level and exercise-level) are shown as a truncated preview. Goals and warmup sets are shown in full because they are stored data the user should verify.

Correction loop

After the card is printed, the person sees one prompt: confirm, or say what's wrong. Anything other than y/yes is a correction. The model is sent the current extract and the correction, and returns a list of edits — {path, value} pairs — not a rewritten extract. The edits are applied in Python; a field the correction doesn't name cannot change, because Python only touches the paths it's given. Measured on a real ten-exercise session: the old whole-document shape needed roughly 5,410 output tokens against a 4,096 ceiling, so it could not have returned a correction for a session that size at all.

Each correction is appended to extractions.corrections. extractions.extract itself is never rewritten. The card is rebuilt from the edited extract and shown again. This repeats until the person confirms.

LLM call design

All four use claude-haiku-4-5, structured tool-call output, and a schema derived from the Pydantic models — no separate schema to keep in sync. A worker gets an isolated chunk when the segmenter's anchor for that exercise can be found verbatim in the text; when it can't, the worker falls back to the full text with a warning noting lower reliability, not a failure. A worker that raises becomes a flagged placeholder exercise plus a warning — never a crash.

CLI interface

# AI parser (default) — free-text input, confirmation card
traininglogs log draft.md

# Rule-based parser — structured markdown, no confirmation card
traininglogs log session.md --parser rules

All log flags (--no-commit, --pr) apply to both parser modes. The --parser flag only controls the parse stage; everything downstream is identical. Use traininglogs validate to test parsing with no DB or git side effects.