Live
Powered by

Nutrition analysis handoff data contract

Purpose

Define the minimum structured context that Coach Luca should provide when preparing a nutrition item for specialist analysis.

  • athlete_username
  • received_at
  • consumed_at or consumed_window
  • effective_entry_date
  • source_batch_id or equivalent grouping clue when the case involves several photos or follow-up context
  • media_paths
  • photo_description
  • analysis_prompt_path
  • detected_items
  • athlete_stated_items
  • meal_role
  • session_context
  • day_type when known
  • dietary_compatibility, including uncertain when evidence is insufficient
  • analysis_services
  • local_analysis_path when the local prompt-format result is stored separately
  • service_results, normalized per service
  • aggregate_estimate
  • open_assumptions
  • open_questions, only when they materially affect guidance

Minimum acceptable handoff

At minimum, the handoff should tell the nutrition specialist:

  • what the athlete likely consumed
  • when it was consumed or when it was likely consumed
  • what evidence supports that read
  • what remains uncertain
  • what images or labels exist
  • what session or recovery context matters
  • which analysis services ran and what each one returned
  • what aggregate estimate was derived from the service results

Example handoff payload

- athlete_username: <username>
- received_at: 2026-04-12 19:50 MDT
- consumed_at: assumed 2026-04-12 19:50 MDT
- effective_entry_date: 2026-04-12
- source_batch_id: 2026-04-12-19:50-single-item
- media_paths:
  - /athlete/logs/media/YYYY-MM-DD/<file-name>.jpg
- detected_items:
  - grilled chicken breast
  - 5 small potatoes
  - roasted squash
  - roasted peppers
- athlete_stated_items:
  - grilled chicken breast
  - 5 small potatoes
  - roasted squash
  - roasted peppers
- meal_role: dinner
- session_context: same-day post-ride recovery meal after a 3:00 endurance ride
- day_type: endurance-ride day
- dietary_compatibility: uncertain
- analysis_services:
  - local
  - claude-cli
- local_analysis_path: athlete/data/nutrition-analysis/raw/2026-04-12/item-01/item-01-local.md
- service_results:
  - local: 620 kcal, 54 g carbs, 42 g protein, 18 g fat, confidence moderate
  - claude-cli: 640 kcal, 58 g carbs, 44 g protein, 19 g fat, confidence moderate
- aggregate_estimate:
  - calories_kcal: 630
  - carbohydrate_g: 56
  - protein_g: 43
  - fat_g: 18.5
  - method: simple mean across 2 successful services
- open_assumptions:
  - chicken treated as lean breast rather than thigh or heavily glazed cut
  - vegetables treated as modest-oil roasted sides
  - water not counted because consumed volume was not confirmed
- open_questions:
  - none required for a practical coaching read

Style

Keep the handoff structured, concise, and factual.

Do not fill it with athlete-facing prose. Do not use placeholder specialist attributions. Do not duplicate the full human-readable daily log entry when a concise structured handoff will do.