Askeo System Architecture
Static proven templates + dynamic coaching logic — Last updated: 2026-08-03 — Served: 2026-09-16 23:26 UTC
Voice layer that walks users through the questionnaire, explains options, reconciles answers, and recommends program switches. Never generates workout content — only populates structured data.
Capabilities
Explain questions
→
Reconcile answers
→
Build week_schedule
→
Recommend switches
→
Explain why
Question Guide
- "What's HIIT?" → explains with examples
- Compares options: upper/lower vs PPL
- Suggests based on user's goals
Answer Reconciliation
- User says 4 days + 1 HIIT → 5 active days
- Resolves conflicts between fields
- Updates structured payload
Program Switching
- Tracks time on current template
- Recommends switch after N weeks
- Adjusts progression type
Week Schedule Builder
- Distributes modalities across days
- Respects user preferences
- Outputs structured JSON
{
"profile": {
"modality_primary": "bodybuilding",
"modality_secondary": ["hiit"],
"modality_mix": "separate_days",
"days_per_week": 5
},
"week_schedule": {
"monday": "bodybuilding",
"tuesday": "bodybuilding",
"wednesday": "hiit",
"thursday": "bodybuilding",
"friday": "bodybuilding"
}
}
Clickable-button interface that collects structured data. AI coach runs alongside, explaining options and reconciling answers. Same questions regardless of AI presence — AI is the guide, not the generator.
Question flow
Goals
→
Equipment
→
Primary Style
→
Additional Activities
→
How to Organize
→
Days / Minutes
→
Experience
→
Focus / Split
→
Limitations
Question Types
- Single-select — one answer (days, experience, focus)
- Multi-select — toggle chips (goals, activities, limitations)
- Text — free input (location)
AI Integration
- "?" button next to jargon terms
- AI explains each option on demand
- AI reconciles conflicting answers
Output
- Structured answers object
- AI-filled fields + week_schedule
- Sent to POST /api/trainer/generate
Pure logic, no AI. Takes structured input, applies proven rules, returns identical output for identical input. This is the engine — never changes without deliberate decision.
Data path
POST /api/trainer/generate
→
intake.py — normalize answers
→
UserProfile dataclass
→
progression.py — route to template
→
Slot-based exercise picker
→
Deterministic workout draft
intake.py
- Validates raw answers
- Unit conversion (imperial/metric)
- Builds UserProfile dataclass
- Reads modality_primary/secondary/mix
- Reads optional week_schedule
progression.py
- Routes to correct template builder
- Handles week_schedule if present
- Falls back to modality builders
- Seed-based RNG for determinism
ExerciseLibrary DB
- ~1318 exercises
- 158 canonical whitelist
- Tier 1–4 ranking
- Equipment + movement tags
exercise_whitelist.py
- Maps raw names → canonical
- Title Case display names
- Tier-ordered pools
- Keyword matching
SlotSpec(
slot_id="compound_1",
label="Heavy Compound",
movements=["push"],
tier_range=(1, 2),
equipment="barbell",
sets_range=(4, 5),
reps_range=(6, 8),
rest_seconds=150
)
Renders workout plans, enables set logging, shows AI coach interface, and displays transition history. Pure presentation — all logic lives in the backend.
Week View
- Day cards with template names
- Exercise list with sets/reps/rest
- Video play buttons if available
Workout Logger
- Log sets, reps, weight
- RIR / RPE capture
- Notes per set
- Feeds back to AI coach
AI Coach Chat
- Bubble UI alongside questionnaire
- Shows coach recommendations
- User approves or requests changes
Transition History
- Shows past template switches
- Progression type changes
- Coach notes for each phase
These rules govern how the system behaves. They don't change unless we explicitly decide to change them.
Static templates, dynamic coaching — exercises and structure are proven; when to switch is personalized
Structured data only in backend — no free-text conversation parsing; AI outputs JSON objects
Deterministic generation — same input = same workout. Only user data changes the output
Slot guardrails — every template enforces compound-first, isolation-last ordering
No AI in the generator — AI is the voice, not the brain. Generation is pure logic
Periodization by default — users switch templates over time; system tracks and recommends
Every workout day template in the system. Each has explicit slots with movement, tier, equipment, sets/reps/rest constraints.
Single Body Part
- Chest Day (5 slots)
- Back Day (5 slots)
- Shoulder Day (5 slots)
- Leg Day (5 slots)
- Arm Day (5 slots)
Combination Days
- Chest + Triceps
- Back + Biceps
- Upper Body
- Lower Body
Split Templates
- Full Body (3–6 days)
- Upper/Lower (alternating)
- Push/Pull/Legs (rotating)
Simple Modality
- HIIT (3–5 exercises, 30s rest)
- Cardio (3–5 exercises, 45s rest)
- Yoga / Mobility (2–3 holds)
- Calisthenics (skill work)
- CrossFit (WOD style)