nvti commited on
Commit
1071248
·
2 Parent(s): aefa805f083cf4

Merge pull request #21 from tihado/ht/phase9

Browse files

feat: Implement grounded coach summary with HF SLM

app.py CHANGED
@@ -188,6 +188,10 @@ def _profile_input(
188
  }
189
 
190
 
 
 
 
 
191
  def _analysis_gpu_duration(*_args: Any, **_kwargs: Any) -> int:
192
  return default_spaces_gpu_duration()
193
 
@@ -196,11 +200,13 @@ def _analysis_gpu_duration(*_args: Any, **_kwargs: Any) -> int:
196
  def _run_analysis_pipeline(
197
  video_path: str | None,
198
  profile_input: dict[str, Any],
 
199
  progress: Any | None = None,
200
  ) -> dict[str, Any]:
201
  return run_pipeline(
202
  video_path=video_path,
203
  profile_input=profile_input,
 
204
  progress=progress,
205
  )
206
 
@@ -261,6 +267,7 @@ async def analyze_api(
261
  intended_variation: str = Form(default=""),
262
  limitations: str = Form(default="[]"),
263
  equipment: str = Form(default="bodyweight"),
 
264
  ) -> dict[str, Any]:
265
  profile = _profile_input(
266
  goal=goal,
@@ -272,7 +279,11 @@ async def analyze_api(
272
  )
273
  video_path = await _save_upload(video)
274
  try:
275
- result = _run_analysis_pipeline(video_path, profile)
 
 
 
 
276
  finally:
277
  if video_path is not None:
278
  Path(video_path).unlink(missing_ok=True)
@@ -289,6 +300,7 @@ async def analyze_stream_api(
289
  intended_variation: str = Form(default=""),
290
  limitations: str = Form(default="[]"),
291
  equipment: str = Form(default="bodyweight"),
 
292
  ) -> StreamingResponse:
293
  profile = _profile_input(
294
  goal=goal,
@@ -303,7 +315,12 @@ async def analyze_stream_api(
303
 
304
  def worker() -> None:
305
  try:
306
- result = _run_analysis_pipeline(video_path, profile, events.put)
 
 
 
 
 
307
  events.put({"type": "complete", "result": _analysis_response(result)})
308
  except Exception as exc: # pragma: no cover - surfaced to browser clients
309
  events.put({"type": "error", "detail": str(exc)})
 
188
  }
189
 
190
 
191
+ def _parse_bool_form(value: str) -> bool:
192
+ return value.strip().lower() in {"1", "true", "yes", "on"}
193
+
194
+
195
  def _analysis_gpu_duration(*_args: Any, **_kwargs: Any) -> int:
196
  return default_spaces_gpu_duration()
197
 
 
200
  def _run_analysis_pipeline(
201
  video_path: str | None,
202
  profile_input: dict[str, Any],
203
+ bypass_verifier: bool = False,
204
  progress: Any | None = None,
205
  ) -> dict[str, Any]:
206
  return run_pipeline(
207
  video_path=video_path,
208
  profile_input=profile_input,
209
+ bypass_verifier=bypass_verifier,
210
  progress=progress,
211
  )
212
 
 
267
  intended_variation: str = Form(default=""),
268
  limitations: str = Form(default="[]"),
269
  equipment: str = Form(default="bodyweight"),
270
+ bypass_verifier: str = Form(default="false"),
271
  ) -> dict[str, Any]:
272
  profile = _profile_input(
273
  goal=goal,
 
279
  )
280
  video_path = await _save_upload(video)
281
  try:
282
+ result = _run_analysis_pipeline(
283
+ video_path,
284
+ profile,
285
+ _parse_bool_form(bypass_verifier),
286
+ )
287
  finally:
288
  if video_path is not None:
289
  Path(video_path).unlink(missing_ok=True)
 
300
  intended_variation: str = Form(default=""),
301
  limitations: str = Form(default="[]"),
302
  equipment: str = Form(default="bodyweight"),
303
+ bypass_verifier: str = Form(default="false"),
304
  ) -> StreamingResponse:
305
  profile = _profile_input(
306
  goal=goal,
 
315
 
316
  def worker() -> None:
317
  try:
318
+ result = _run_analysis_pipeline(
319
+ video_path,
320
+ profile,
321
+ _parse_bool_form(bypass_verifier),
322
+ events.put,
323
+ )
324
  events.put({"type": "complete", "result": _analysis_response(result)})
325
  except Exception as exc: # pragma: no cover - surfaced to browser clients
326
  events.put({"type": "error", "detail": str(exc)})
src/pozify/contracts.py CHANGED
@@ -133,9 +133,10 @@ class IssueMarkers:
133
  @dataclass(frozen=True)
134
  class CoachSummary:
135
  summary: str
136
- what_went_well: list[str]
137
- main_findings: list[str]
138
- variation_explanation: str
 
139
  top_fixes: list[str]
140
  next_session_plan: list[str]
141
  confidence_notes: list[str]
@@ -494,9 +495,10 @@ def _validate_coach_summary(value: Any, path: str) -> None:
494
  payload,
495
  {
496
  "summary",
497
- "what_went_well",
498
- "main_findings",
499
- "variation_explanation",
 
500
  "top_fixes",
501
  "next_session_plan",
502
  "confidence_notes",
@@ -504,9 +506,16 @@ def _validate_coach_summary(value: Any, path: str) -> None:
504
  path,
505
  )
506
  _require_type(payload["summary"], str, f"{path}.summary")
507
- _require_string_list(payload["what_went_well"], f"{path}.what_went_well")
508
- _require_string_list(payload["main_findings"], f"{path}.main_findings")
509
- _require_type(payload["variation_explanation"], str, f"{path}.variation_explanation")
 
 
 
 
 
 
 
510
  _require_string_list(payload["top_fixes"], f"{path}.top_fixes")
511
  _require_string_list(payload["next_session_plan"], f"{path}.next_session_plan")
512
  _require_string_list(payload["confidence_notes"], f"{path}.confidence_notes")
 
133
  @dataclass(frozen=True)
134
  class CoachSummary:
135
  summary: str
136
+ what_you_did: list[str]
137
+ what_looked_good: list[str]
138
+ what_changed_across_reps: list[str]
139
+ valid_variation_vs_issue: list[str]
140
  top_fixes: list[str]
141
  next_session_plan: list[str]
142
  confidence_notes: list[str]
 
495
  payload,
496
  {
497
  "summary",
498
+ "what_you_did",
499
+ "what_looked_good",
500
+ "what_changed_across_reps",
501
+ "valid_variation_vs_issue",
502
  "top_fixes",
503
  "next_session_plan",
504
  "confidence_notes",
 
506
  path,
507
  )
508
  _require_type(payload["summary"], str, f"{path}.summary")
509
+ _require_string_list(payload["what_you_did"], f"{path}.what_you_did")
510
+ _require_string_list(payload["what_looked_good"], f"{path}.what_looked_good")
511
+ _require_string_list(
512
+ payload["what_changed_across_reps"],
513
+ f"{path}.what_changed_across_reps",
514
+ )
515
+ _require_string_list(
516
+ payload["valid_variation_vs_issue"],
517
+ f"{path}.valid_variation_vs_issue",
518
+ )
519
  _require_string_list(payload["top_fixes"], f"{path}.top_fixes")
520
  _require_string_list(payload["next_session_plan"], f"{path}.next_session_plan")
521
  _require_string_list(payload["confidence_notes"], f"{path}.confidence_notes")
src/pozify/env.py ADDED
@@ -0,0 +1,34 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ from pathlib import Path
5
+
6
+
7
+ _LOADED_ENV_FILES: set[Path] = set()
8
+
9
+
10
+ def env_truthy(value: str | None) -> bool:
11
+ if value is None:
12
+ return False
13
+ return value.strip().lower() in {"1", "true", "yes", "on"}
14
+
15
+
16
+ def load_local_env(filename: str = ".env") -> None:
17
+ candidates = (
18
+ Path.cwd() / filename,
19
+ Path(__file__).resolve().parents[2] / filename,
20
+ )
21
+ for path in candidates:
22
+ resolved = path.resolve()
23
+ if resolved in _LOADED_ENV_FILES or not resolved.is_file():
24
+ continue
25
+ for line in resolved.read_text(encoding="utf-8").splitlines():
26
+ stripped = line.strip()
27
+ if not stripped or stripped.startswith("#") or "=" not in stripped:
28
+ continue
29
+ key, value = stripped.split("=", 1)
30
+ key = key.strip()
31
+ if not key or key in os.environ:
32
+ continue
33
+ os.environ[key] = value.strip().strip("'").strip('"')
34
+ _LOADED_ENV_FILES.add(resolved)
src/pozify/knowledge_cards.py ADDED
@@ -0,0 +1,371 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+
5
+ from pozify.contracts import ExerciseClassification, GOALS, IssueMarkers, UserProfile, Variation
6
+
7
+
8
+ CARD_TYPE_ORDER = {
9
+ "exercise": 0,
10
+ "variation": 1,
11
+ "issue": 2,
12
+ "goal": 3,
13
+ "safety_rule": 4,
14
+ }
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class KnowledgeCard:
19
+ card_id: str
20
+ card_type: str
21
+ labels: tuple[str, ...]
22
+ title: str
23
+ summary: str
24
+ evidence_rules: tuple[str, ...]
25
+ coaching_points: tuple[str, ...]
26
+ allowed_interpretations: tuple[str, ...] = ()
27
+ forbidden_claims: tuple[str, ...] = ()
28
+ related_cards: tuple[str, ...] = ()
29
+
30
+
31
+ def _card(
32
+ card_id: str,
33
+ card_type: str,
34
+ labels: tuple[str, ...],
35
+ title: str,
36
+ summary: str,
37
+ evidence_rules: tuple[str, ...],
38
+ coaching_points: tuple[str, ...],
39
+ *,
40
+ allowed_interpretations: tuple[str, ...] = (),
41
+ forbidden_claims: tuple[str, ...] = (),
42
+ related_cards: tuple[str, ...] = (),
43
+ ) -> KnowledgeCard:
44
+ return KnowledgeCard(
45
+ card_id=card_id,
46
+ card_type=card_type,
47
+ labels=labels,
48
+ title=title,
49
+ summary=summary,
50
+ evidence_rules=evidence_rules,
51
+ coaching_points=coaching_points,
52
+ allowed_interpretations=allowed_interpretations,
53
+ forbidden_claims=forbidden_claims,
54
+ related_cards=related_cards,
55
+ )
56
+
57
+
58
+ CARD_REGISTRY: tuple[KnowledgeCard, ...] = (
59
+ _card(
60
+ "exercise:squat",
61
+ "exercise",
62
+ ("squat",),
63
+ "Squat",
64
+ "A squat summary should describe depth, balance, and torso position "
65
+ "from structured rep evidence.",
66
+ (
67
+ "Use rep analysis and issue markers instead of inferring directly from the video.",
68
+ "Valid stance variations should not be framed as faults by default.",
69
+ ),
70
+ (
71
+ "Call out depth, stance, and torso control only when they appear "
72
+ "in structured evidence.",
73
+ "Keep fixes simple and specific to the detected issue labels.",
74
+ ),
75
+ ),
76
+ _card(
77
+ "exercise:push_up",
78
+ "exercise",
79
+ ("push_up",),
80
+ "Push-up",
81
+ "A push-up summary should focus on body line, depth, and rep consistency "
82
+ "from structured evidence.",
83
+ (
84
+ "Treat hand placement or knee support as variation context when the "
85
+ "variation detector marks them as not-issues.",
86
+ "Do not infer shoulder or wrist pain from the movement.",
87
+ ),
88
+ (
89
+ "Explain whether the set looked controlled before suggesting changes.",
90
+ "Use issue labels such as `hip_sag` or `incomplete_depth` only "
91
+ "when they are present in JSON.",
92
+ ),
93
+ ),
94
+ _card(
95
+ "exercise:shoulder_press",
96
+ "exercise",
97
+ ("shoulder_press",),
98
+ "Shoulder Press",
99
+ "A shoulder press summary should focus on lockout, symmetry, and rep "
100
+ "consistency from structured evidence.",
101
+ (
102
+ "Partial range can be a valid variation context and should not be "
103
+ "automatically overcorrected.",
104
+ "Use rep analysis and issue markers instead of diagnosing shoulder limitations.",
105
+ ),
106
+ (
107
+ "Separate partial range context from incomplete lockout issue markers.",
108
+ "Use `asymmetry` only when it is explicitly present in JSON.",
109
+ ),
110
+ ),
111
+ _card(
112
+ "variation:wide_grip_push_up",
113
+ "variation",
114
+ ("wide_grip_push_up", "wide_hand_placement"),
115
+ "Wide-Grip Push-up",
116
+ "A wide-grip push-up is a valid push-up variation when detected by the "
117
+ "variation step.",
118
+ (
119
+ "If `wide_hand_placement` appears in not_issues, treat hand width "
120
+ "as context, not a fault.",
121
+ ),
122
+ (
123
+ "Acknowledge the wide-grip setup without asking the athlete to "
124
+ "normalize it unless another issue requires it.",
125
+ ),
126
+ allowed_interpretations=("Variation, not automatically an issue.",),
127
+ ),
128
+ _card(
129
+ "variation:knee_push_up",
130
+ "variation",
131
+ ("knee_push_up", "knee_contact"),
132
+ "Knee Push-up",
133
+ "A knee push-up is a valid push-up variation when knee support is intentionally detected.",
134
+ (
135
+ "If `knee_contact` appears in not_issues, do not correct knee support as an error.",
136
+ ),
137
+ (
138
+ "Explain the movement as a valid regression or variation rather than a mistake.",
139
+ ),
140
+ allowed_interpretations=("Variation, not automatically an issue.",),
141
+ ),
142
+ _card(
143
+ "issue:shallow_depth",
144
+ "issue",
145
+ ("shallow_depth",),
146
+ "Shallow Depth",
147
+ "The squat bottom position stayed above the expected depth threshold in the issue markers.",
148
+ (
149
+ "Only mention this issue when `shallow_depth` exists in `issue_markers.json`.",
150
+ ),
151
+ (
152
+ "Sit slightly deeper before standing up.",
153
+ "Slow the bottom portion so depth stays consistent.",
154
+ ),
155
+ ),
156
+ _card(
157
+ "issue:hip_sag",
158
+ "issue",
159
+ ("hip_sag",),
160
+ "Hip Sag",
161
+ "The push-up body line dropped below the body-line threshold across a sustained interval.",
162
+ (
163
+ "Only mention this issue when `hip_sag` exists in `issue_markers.json`.",
164
+ ),
165
+ (
166
+ "Keep shoulders, hips, and ankles moving as one line.",
167
+ "Reduce speed if body line drops on later reps.",
168
+ ),
169
+ ),
170
+ _card(
171
+ "issue:incomplete_lockout",
172
+ "issue",
173
+ ("incomplete_lockout",),
174
+ "Incomplete Lockout",
175
+ "The elbows did not reach the lockout threshold at the top of the shoulder press.",
176
+ (
177
+ "Only mention this issue when `incomplete_lockout` exists in `issue_markers.json`.",
178
+ ),
179
+ (
180
+ "Finish each rep by reaching a cleaner top position.",
181
+ "Use a slower press so the top range stays consistent.",
182
+ ),
183
+ ),
184
+ _card(
185
+ "issue:incomplete_depth",
186
+ "issue",
187
+ ("incomplete_depth",),
188
+ "Incomplete Depth",
189
+ "The push-up bottom position stayed above the depth threshold at the bottom of the rep.",
190
+ ("Only mention this issue when it exists in `issue_markers.json`.",),
191
+ (
192
+ "Lower a bit more at the bottom if control stays clean.",
193
+ "Use slower reps to make bottom depth repeatable.",
194
+ ),
195
+ ),
196
+ _card(
197
+ "issue:knee_valgus",
198
+ "issue",
199
+ ("knee_valgus",),
200
+ "Knee Valgus",
201
+ "The knees tracked inward relative to the ankles beyond the configured threshold.",
202
+ ("Only mention this issue when it exists in `issue_markers.json`.",),
203
+ (
204
+ "Keep the knees tracking more evenly over the feet.",
205
+ "Use a slightly slower descent so knee path stays consistent.",
206
+ ),
207
+ ),
208
+ _card(
209
+ "issue:excessive_torso_lean",
210
+ "issue",
211
+ ("excessive_torso_lean",),
212
+ "Excessive Torso Lean",
213
+ "The torso lean exceeded the configured threshold near the squat bottom.",
214
+ ("Only mention this issue when it exists in `issue_markers.json`.",),
215
+ (
216
+ "Keep the chest taller through the bottom.",
217
+ "Use a controlled descent so the torso angle stays steadier.",
218
+ ),
219
+ ),
220
+ _card(
221
+ "issue:asymmetry",
222
+ "issue",
223
+ ("asymmetry",),
224
+ "Asymmetry",
225
+ "The left-right wrist height difference exceeded the configured symmetry threshold.",
226
+ ("Only mention this issue when it exists in `issue_markers.json`.",),
227
+ (
228
+ "Try to finish both sides at a more even height.",
229
+ "Use a slower tempo to keep both arms in sync.",
230
+ ),
231
+ ),
232
+ _card(
233
+ "goal:strength",
234
+ "goal",
235
+ ("strength",),
236
+ "Strength Goal",
237
+ "Strength-oriented coaching should prioritize a few high-value fixes over many cues.",
238
+ ("Keep the plan focused and repeatable.",),
239
+ ("Use 1 to 2 form priorities for the next session.",),
240
+ ),
241
+ _card(
242
+ "goal:hypertrophy",
243
+ "goal",
244
+ ("hypertrophy",),
245
+ "Hypertrophy Goal",
246
+ "Hypertrophy-oriented coaching should emphasize repeatable reps and manageable fixes.",
247
+ ("Keep cues practical for multi-rep sets.",),
248
+ ("Prioritize consistency over perfect-looking single reps.",),
249
+ ),
250
+ _card(
251
+ "goal:endurance",
252
+ "goal",
253
+ ("endurance",),
254
+ "Endurance Goal",
255
+ "Endurance-oriented coaching should emphasize repeatability across the full set.",
256
+ ("Call out late-set drift when the rep analysis shows it.",),
257
+ ("Use pacing and consistency cues for the next session.",),
258
+ ),
259
+ _card(
260
+ "goal:mobility",
261
+ "goal",
262
+ ("mobility",),
263
+ "Mobility Goal",
264
+ "Mobility-oriented coaching should stay descriptive and avoid medical claims.",
265
+ ("Describe range findings without diagnosing restrictions.",),
266
+ ("Use easy controlled reps next session to compare range consistency.",),
267
+ ),
268
+ _card(
269
+ "goal:beginner_practice",
270
+ "goal",
271
+ ("beginner_practice",),
272
+ "Beginner Practice Goal",
273
+ "Beginner practice coaching should stay simple, encouraging, and concrete.",
274
+ ("Limit the number of corrections in a single summary.",),
275
+ ("Pick the top one or two form priorities for next time.",),
276
+ ),
277
+ _card(
278
+ "safety:no_diagnosis",
279
+ "safety_rule",
280
+ ("no_diagnosis",),
281
+ "No Diagnosis",
282
+ "The summary must not diagnose pain, injury, imbalance, mobility deficits, or pathology.",
283
+ ("Do not use diagnostic language.",),
284
+ ("Use uncertainty language when evidence is limited.",),
285
+ forbidden_claims=("diagnosis", "injury", "pathology", "medical assessment"),
286
+ ),
287
+ _card(
288
+ "safety:no_injury_prevention_claim",
289
+ "safety_rule",
290
+ ("no_injury_prevention_claim",),
291
+ "No Injury Prevention Claim",
292
+ "The summary must not claim that a cue will prevent injury.",
293
+ ("Do not promise injury prevention.",),
294
+ ("Keep coaching language descriptive and performance-focused.",),
295
+ forbidden_claims=("injury prevention", "prevent injury"),
296
+ ),
297
+ _card(
298
+ "safety:grounded_only",
299
+ "safety_rule",
300
+ ("grounded_only",),
301
+ "Grounded Only",
302
+ "The summary must explain only the structured evidence and retrieved knowledge cards.",
303
+ ("Do not infer new issues that are absent from JSON.",),
304
+ ("State confidence limits when the evidence is thin.",),
305
+ ),
306
+ _card(
307
+ "safety:variation_not_issue",
308
+ "safety_rule",
309
+ ("variation_not_issue",),
310
+ "Variation Is Not Automatically An Issue",
311
+ "A detected variation or listed not-issue should not be overcorrected as a mistake.",
312
+ ("Keep valid variation context separate from issue language.",),
313
+ ("Explain why the variation is treated as context when needed.",),
314
+ ),
315
+ )
316
+
317
+
318
+ CARDS_BY_ID = {card.card_id: card for card in CARD_REGISTRY}
319
+ CARDS_BY_LABEL = {
320
+ label: card
321
+ for card in CARD_REGISTRY
322
+ for label in card.labels
323
+ }
324
+ KNOWN_ISSUE_LABELS = frozenset(
325
+ label for card in CARD_REGISTRY if card.card_type == "issue" for label in card.labels
326
+ )
327
+ KNOWN_VARIATION_LABELS = frozenset(
328
+ label for card in CARD_REGISTRY if card.card_type == "variation" for label in card.labels
329
+ )
330
+
331
+
332
+ def get_card_by_label(label: str) -> KnowledgeCard | None:
333
+ return CARDS_BY_LABEL.get(label)
334
+
335
+
336
+ def cards_for_labels(labels: list[str] | tuple[str, ...]) -> list[KnowledgeCard]:
337
+ cards = {
338
+ card.card_id: card
339
+ for label in labels
340
+ for card in [get_card_by_label(label)]
341
+ if card is not None
342
+ }
343
+ return sorted(
344
+ cards.values(),
345
+ key=lambda card: (CARD_TYPE_ORDER.get(card.card_type, 99), card.card_id),
346
+ )
347
+
348
+
349
+ def retrieve_cards(
350
+ *,
351
+ profile: UserProfile,
352
+ classification: ExerciseClassification,
353
+ variation: Variation,
354
+ issues: IssueMarkers,
355
+ ) -> list[KnowledgeCard]:
356
+ labels = [
357
+ classification.exercise,
358
+ variation.detected_variation,
359
+ *variation.not_issues,
360
+ *[issue.issue for issue in issues.issues],
361
+ profile.goal,
362
+ "no_diagnosis",
363
+ "no_injury_prevention_claim",
364
+ "grounded_only",
365
+ "variation_not_issue",
366
+ ]
367
+ return cards_for_labels(labels)
368
+
369
+
370
+ def supported_goal_labels() -> frozenset[str]:
371
+ return frozenset(GOALS)
src/pozify/pipeline.py CHANGED
@@ -8,10 +8,13 @@ from uuid import uuid4
8
 
9
  from pozify.artifacts import write_json
10
  from pozify.contracts import UserProfile, to_dict
 
11
  from pozify.exercises import create_exercise_strategy
 
12
  from pozify.steps import (
13
  annotated_renderer,
14
  coach_summary,
 
15
  exercise_classifier,
16
  pose_cleaning,
17
  pose_landmarker,
@@ -22,6 +25,7 @@ from pozify.steps import (
22
 
23
  RUNS_DIR = Path("runs")
24
  ProgressCallback = Callable[[dict[str, Any]], None]
 
25
 
26
 
27
  def _env_mock_mode(video_path: str | None) -> bool:
@@ -38,9 +42,16 @@ def run_pipeline(
38
  profile_input: dict[str, Any],
39
  *,
40
  mock: bool | None = None,
 
41
  progress: ProgressCallback | None = None,
42
  ) -> dict[str, Any]:
 
43
  mock_mode = _env_mock_mode(video_path) if mock is None else mock
 
 
 
 
 
44
 
45
  run_id = (
46
  f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{uuid4().hex[:8]}"
@@ -215,12 +226,60 @@ def run_pipeline(
215
  if mock_mode:
216
  mock_steps.insert(0, "exercise_classifier")
217
 
218
- summary = coach_summary.run(
219
- profile, classification, reps, analysis, variation, issues
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
220
  )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
221
  write_artifact("coach_summary.json", summary)
222
-
223
- verification = verifier.run(summary, issues, variation)
224
  write_artifact("verification.json", verification)
225
  emit(
226
  "coach",
@@ -249,6 +308,11 @@ def run_pipeline(
249
  "analysis_mode": analysis_mode,
250
  "pose_source": pose_source,
251
  "mock_steps": mock_steps,
 
 
 
 
 
252
  },
253
  }
254
  write_artifact("final_report.json", final_report)
 
8
 
9
  from pozify.artifacts import write_json
10
  from pozify.contracts import UserProfile, to_dict
11
+ from pozify.env import env_truthy, load_local_env
12
  from pozify.exercises import create_exercise_strategy
13
+ from pozify.knowledge_cards import retrieve_cards
14
  from pozify.steps import (
15
  annotated_renderer,
16
  coach_summary,
17
+ coach_summary_fallback,
18
  exercise_classifier,
19
  pose_cleaning,
20
  pose_landmarker,
 
25
 
26
  RUNS_DIR = Path("runs")
27
  ProgressCallback = Callable[[dict[str, Any]], None]
28
+ BYPASS_VERIFIER_ENV = "POZIFY_COACH_SUMMARY_BYPASS_VERIFIER"
29
 
30
 
31
  def _env_mock_mode(video_path: str | None) -> bool:
 
42
  profile_input: dict[str, Any],
43
  *,
44
  mock: bool | None = None,
45
+ bypass_verifier: bool | None = None,
46
  progress: ProgressCallback | None = None,
47
  ) -> dict[str, Any]:
48
+ load_local_env()
49
  mock_mode = _env_mock_mode(video_path) if mock is None else mock
50
+ bypass_verifier_enabled = (
51
+ env_truthy(os.getenv(BYPASS_VERIFIER_ENV))
52
+ if bypass_verifier is None
53
+ else bypass_verifier
54
+ )
55
 
56
  run_id = (
57
  f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{uuid4().hex[:8]}"
 
226
  if mock_mode:
227
  mock_steps.insert(0, "exercise_classifier")
228
 
229
+ summary_cards = retrieve_cards(
230
+ profile=profile,
231
+ classification=classification,
232
+ variation=variation,
233
+ issues=issues,
234
+ )
235
+ coach_result = coach_summary.run_with_metadata(
236
+ profile,
237
+ classification,
238
+ reps,
239
+ analysis,
240
+ variation,
241
+ issues,
242
+ cards=summary_cards,
243
+ )
244
+ summary = coach_result.summary
245
+ verification = verifier.run(
246
+ summary,
247
+ issues,
248
+ variation,
249
+ classification=classification,
250
+ analysis=analysis,
251
+ reps=reps,
252
  )
253
+ coach_summary_source = coach_result.source
254
+ coach_summary_provider = coach_result.provider
255
+ coach_summary_model = coach_result.model
256
+ coach_summary_verifier_bypassed = False
257
+ if not verification.passed:
258
+ if bypass_verifier_enabled and coach_result.source == "model_or_local":
259
+ coach_summary_verifier_bypassed = True
260
+ else:
261
+ summary = coach_summary_fallback.build_fallback_summary(
262
+ profile=profile,
263
+ classification=classification,
264
+ reps=reps,
265
+ analysis=analysis,
266
+ variation=variation,
267
+ issues=issues,
268
+ cards=summary_cards,
269
+ failure_reason="; ".join(verification.notes) or "verification_failed",
270
+ )
271
+ coach_summary_source = "fallback_after_verification"
272
+ coach_summary_provider = coach_result.provider
273
+ coach_summary_model = coach_result.model
274
+ verification = verifier.run(
275
+ summary,
276
+ issues,
277
+ variation,
278
+ classification=classification,
279
+ analysis=analysis,
280
+ reps=reps,
281
+ )
282
  write_artifact("coach_summary.json", summary)
 
 
283
  write_artifact("verification.json", verification)
284
  emit(
285
  "coach",
 
308
  "analysis_mode": analysis_mode,
309
  "pose_source": pose_source,
310
  "mock_steps": mock_steps,
311
+ "coach_summary_source": coach_summary_source,
312
+ "coach_summary_provider": coach_summary_provider,
313
+ "coach_summary_model": coach_summary_model,
314
+ "coach_summary_verifier_bypassed": coach_summary_verifier_bypassed,
315
+ "coach_summary_verifier_bypass_requested": bypass_verifier_enabled,
316
  },
317
  }
318
  write_artifact("final_report.json", final_report)
src/pozify/slm/__init__.py ADDED
@@ -0,0 +1,7 @@
 
 
 
 
 
 
 
 
1
+ from pozify.slm.providers import CoachSummaryGeneration, CoachSummaryModel, get_coach_summary_model
2
+
3
+ __all__ = [
4
+ "CoachSummaryGeneration",
5
+ "CoachSummaryModel",
6
+ "get_coach_summary_model",
7
+ ]
src/pozify/slm/prompting.py ADDED
@@ -0,0 +1,116 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from typing import Any
5
+
6
+ from pozify.contracts import (
7
+ ExerciseClassification,
8
+ IssueMarkers,
9
+ RepAnalysis,
10
+ Reps,
11
+ UserProfile,
12
+ Variation,
13
+ to_dict,
14
+ )
15
+ from pozify.knowledge_cards import KnowledgeCard
16
+
17
+
18
+ def build_summary_evidence(
19
+ *,
20
+ profile: UserProfile,
21
+ classification: ExerciseClassification,
22
+ reps: Reps,
23
+ analysis: RepAnalysis,
24
+ variation: Variation,
25
+ issues: IssueMarkers,
26
+ cards: list[KnowledgeCard],
27
+ ) -> dict[str, Any]:
28
+ issue_counts: dict[str, int] = {}
29
+ top_issue_intervals = []
30
+ for issue in sorted(issues.issues, key=lambda item: item.severity, reverse=True):
31
+ issue_counts[issue.issue] = issue_counts.get(issue.issue, 0) + 1
32
+ if len(top_issue_intervals) < 3:
33
+ top_issue_intervals.append(
34
+ {
35
+ "issue": issue.issue,
36
+ "rep_id": issue.rep_id,
37
+ "severity": round(issue.severity, 3),
38
+ "start_sec": round(issue.start_sec, 3),
39
+ "end_sec": round(issue.end_sec, 3),
40
+ "evidence": issue.evidence,
41
+ }
42
+ )
43
+
44
+ return {
45
+ "user_profile": to_dict(profile),
46
+ "exercise_classification": {
47
+ "exercise": classification.exercise,
48
+ "confidence": classification.confidence,
49
+ "fallback_required": classification.fallback_required,
50
+ },
51
+ "variation": to_dict(variation),
52
+ "rep_summary": {
53
+ "rep_count": len(reps.reps),
54
+ "aggregate_metrics": analysis.aggregate_metrics,
55
+ "rep_metrics": [to_dict(item) for item in analysis.items],
56
+ },
57
+ "issue_summary": {
58
+ "issue_counts": issue_counts,
59
+ "issues": [to_dict(issue) for issue in issues.issues],
60
+ "top_issue_intervals": top_issue_intervals,
61
+ },
62
+ "knowledge_cards": [to_dict(card) for card in cards],
63
+ }
64
+
65
+
66
+ def build_coach_summary_prompt(
67
+ *,
68
+ profile: UserProfile,
69
+ classification: ExerciseClassification,
70
+ reps: Reps,
71
+ analysis: RepAnalysis,
72
+ variation: Variation,
73
+ issues: IssueMarkers,
74
+ cards: list[KnowledgeCard],
75
+ ) -> str:
76
+ evidence = build_summary_evidence(
77
+ profile=profile,
78
+ classification=classification,
79
+ reps=reps,
80
+ analysis=analysis,
81
+ variation=variation,
82
+ issues=issues,
83
+ cards=cards,
84
+ )
85
+ expected_schema = {
86
+ "summary": "string",
87
+ "what_you_did": ["string"],
88
+ "what_looked_good": ["string"],
89
+ "what_changed_across_reps": ["string"],
90
+ "valid_variation_vs_issue": ["string"],
91
+ "top_fixes": ["string"],
92
+ "next_session_plan": ["string"],
93
+ "confidence_notes": ["string"],
94
+ }
95
+
96
+ instructions = {
97
+ "task": "Generate a grounded coach summary from structured exercise-analysis artifacts.",
98
+ "rules": [
99
+ "Use only the evidence JSON and retrieved knowledge cards.",
100
+ "Do not infer new issues that are absent from issue_summary.issues.",
101
+ "Do not diagnose injuries, pain, mobility deficits, or pathology.",
102
+ "Do not claim injury prevention.",
103
+ "Do not treat a valid detected variation or not-issue label as an error.",
104
+ "When referencing an issue or variation, include its exact label in "
105
+ "backticks at least once.",
106
+ "If evidence is limited or confidence is low, say so in confidence_notes.",
107
+ "Return JSON only. No markdown fences. No extra commentary.",
108
+ ],
109
+ "schema": expected_schema,
110
+ }
111
+ return "\n\n".join(
112
+ [
113
+ json.dumps(instructions, ensure_ascii=False, indent=2),
114
+ json.dumps(evidence, ensure_ascii=False, indent=2),
115
+ ]
116
+ )
src/pozify/slm/providers.py ADDED
@@ -0,0 +1,143 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ import os
5
+ from typing import Protocol
6
+
7
+ from pozify.env import env_truthy, load_local_env
8
+
9
+
10
+ PROVIDER_ENV = "POZIFY_COACH_SUMMARY_PROVIDER"
11
+ MODEL_ENV = "POZIFY_COACH_SUMMARY_MODEL"
12
+ DISABLE_REMOTE_ENV = "POZIFY_COACH_SUMMARY_DISABLE_REMOTE"
13
+ MAX_TOKENS_ENV = "POZIFY_COACH_SUMMARY_MAX_TOKENS"
14
+ TEMPERATURE_ENV = "POZIFY_COACH_SUMMARY_TEMPERATURE"
15
+ HF_TOKEN_ENV = "HF_TOKEN"
16
+
17
+ DEFAULT_PROVIDER = "hf_inference"
18
+ DEFAULT_MODEL = "Qwen/Qwen2.5-7B-Instruct"
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class CoachSummaryGeneration:
23
+ text: str
24
+ provider: str
25
+ model: str
26
+
27
+
28
+ class CoachSummaryModel(Protocol):
29
+ def generate_summary(self, prompt: str) -> CoachSummaryGeneration:
30
+ ...
31
+
32
+
33
+ def _env_float(name: str, default: float) -> float:
34
+ value = os.getenv(name)
35
+ if value is None:
36
+ return default
37
+ try:
38
+ return float(value)
39
+ except ValueError:
40
+ return default
41
+
42
+
43
+ def _env_int(name: str, default: int) -> int:
44
+ value = os.getenv(name)
45
+ if value is None:
46
+ return default
47
+ try:
48
+ return int(value)
49
+ except ValueError:
50
+ return default
51
+
52
+
53
+ class HFInferenceCoachSummaryModel:
54
+ def __init__(
55
+ self,
56
+ *,
57
+ model: str = DEFAULT_MODEL,
58
+ max_tokens: int = 700,
59
+ temperature: float = 0.1,
60
+ token: str | None = None,
61
+ ) -> None:
62
+ self.model = model
63
+ self.max_tokens = max_tokens
64
+ self.temperature = temperature
65
+ self.token = token
66
+ self._client = None
67
+
68
+ def _client_instance(self):
69
+ if self._client is not None:
70
+ return self._client
71
+ try:
72
+ from huggingface_hub import InferenceClient
73
+ except ImportError as exc: # pragma: no cover - dependency declared in project
74
+ raise RuntimeError("huggingface_hub is required for Hugging Face inference") from exc
75
+ self._client = InferenceClient(api_key=self.token)
76
+ return self._client
77
+
78
+ def generate_summary(self, prompt: str) -> CoachSummaryGeneration:
79
+ client = self._client_instance()
80
+ if hasattr(client, "chat_completion"):
81
+ response = client.chat_completion(
82
+ model=self.model,
83
+ messages=[
84
+ {
85
+ "role": "system",
86
+ "content": "Return JSON only.",
87
+ },
88
+ {
89
+ "role": "user",
90
+ "content": prompt,
91
+ },
92
+ ],
93
+ temperature=self.temperature,
94
+ max_tokens=self.max_tokens,
95
+ )
96
+ choices = getattr(response, "choices", None) or []
97
+ if not choices:
98
+ raise RuntimeError("Hugging Face inference returned no choices")
99
+ message = getattr(choices[0], "message", None)
100
+ text = getattr(message, "content", None)
101
+ if not isinstance(text, str) or not text.strip():
102
+ raise RuntimeError("Hugging Face inference returned an empty message")
103
+ return CoachSummaryGeneration(
104
+ text=text,
105
+ provider="hf_inference",
106
+ model=self.model,
107
+ )
108
+
109
+ if hasattr(client, "text_generation"):
110
+ text = client.text_generation(
111
+ prompt,
112
+ model=self.model,
113
+ max_new_tokens=self.max_tokens,
114
+ temperature=self.temperature,
115
+ return_full_text=False,
116
+ )
117
+ if not isinstance(text, str) or not text.strip():
118
+ raise RuntimeError("Hugging Face text generation returned empty output")
119
+ return CoachSummaryGeneration(
120
+ text=text,
121
+ provider="hf_inference",
122
+ model=self.model,
123
+ )
124
+
125
+ raise RuntimeError("No supported Hugging Face inference method is available")
126
+
127
+
128
+ def get_coach_summary_model() -> CoachSummaryModel | None:
129
+ load_local_env()
130
+
131
+ if env_truthy(os.getenv(DISABLE_REMOTE_ENV)):
132
+ return None
133
+
134
+ provider = os.getenv(PROVIDER_ENV, DEFAULT_PROVIDER).strip().lower()
135
+ if provider != "hf_inference":
136
+ return None
137
+
138
+ return HFInferenceCoachSummaryModel(
139
+ model=os.getenv(MODEL_ENV, DEFAULT_MODEL),
140
+ max_tokens=_env_int(MAX_TOKENS_ENV, 700),
141
+ temperature=_env_float(TEMPERATURE_ENV, 0.1),
142
+ token=os.getenv(HF_TOKEN_ENV),
143
+ )
src/pozify/steps/coach_summary.py CHANGED
@@ -1,5 +1,9 @@
1
  from __future__ import annotations
2
 
 
 
 
 
3
  from pozify.contracts import (
4
  CoachSummary,
5
  ExerciseClassification,
@@ -8,7 +12,78 @@ from pozify.contracts import (
8
  Reps,
9
  UserProfile,
10
  Variation,
 
11
  )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12
 
13
 
14
  def run(
@@ -18,46 +93,89 @@ def run(
18
  analysis: RepAnalysis,
19
  variation: Variation,
20
  issues: IssueMarkers,
 
 
 
21
  ) -> CoachSummary:
22
- issue_labels = [issue.issue for issue in issues.issues]
23
- main_issue = issue_labels[0] if issue_labels else "no_major_issue"
24
- issue_text = (
25
- f"The strongest frame-level marker is `{main_issue}`, with timestamps and metric evidence in the issue timeline."
26
- if issues.issues
27
- else "The frame-level issue rules did not find a sustained threshold violation."
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
28
  )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
29
 
30
- return CoachSummary(
31
- summary=(
32
- f"The pipeline segmented {len(reps.reps)} {classification.exercise} reps from the current pose stream. "
33
- f"Exercise routing, variation labeling, and coaching language may still use lightweight rules or placeholders. "
34
- f"The detected variation is `{variation.detected_variation}`. {issue_text}"
35
- ),
36
- what_went_well=[
37
- f"Current placeholder ROM score is {analysis.aggregate_metrics['avg_rom_score']}.",
38
- f"Current placeholder symmetry score is {analysis.aggregate_metrics['avg_symmetry_score']}.",
39
- ],
40
- main_findings=[
41
- f"Frame-level marker `{main_issue}` appears in {len(issues.issues)} interval(s)."
42
- if issues.issues
43
- else "No sustained issue interval detected."
44
- ],
45
- variation_explanation=(
46
- f"`{variation.detected_variation}` was included as context for interpreting issue markers. "
47
- f"It should be reviewed alongside camera angle and pose confidence."
48
- ),
49
- top_fixes=[
50
- "Keep the same setup and record from a stable camera angle.",
51
- "Stop the set when the first repeated issue marker appears.",
52
- "Use slower reps until the highlighted metric improves.",
53
- ],
54
- next_session_plan=[
55
- "Warm up with 1 easy set of 5 controlled reps.",
56
- "Perform 2 working sets and keep the camera angle consistent.",
57
- "Compare the next run against this report's issue timeline.",
58
- ],
59
- confidence_notes=[
60
- f"Current mock classifier confidence placeholder: {classification.confidence:.0%}.",
61
- "Rep segmentation can run on real pose, but downstream interpretation is still partially mocked.",
62
- ],
63
  )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  from __future__ import annotations
2
 
3
+ from dataclasses import dataclass
4
+ import json
5
+ from typing import Any
6
+
7
  from pozify.contracts import (
8
  CoachSummary,
9
  ExerciseClassification,
 
12
  Reps,
13
  UserProfile,
14
  Variation,
15
+ validate_contract,
16
  )
17
+ from pozify.knowledge_cards import KnowledgeCard, retrieve_cards
18
+ from pozify.slm.prompting import build_coach_summary_prompt
19
+ from pozify.slm.providers import CoachSummaryModel, get_coach_summary_model
20
+ from pozify.steps.coach_summary_fallback import build_fallback_summary
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class CoachSummaryResult:
25
+ summary: CoachSummary
26
+ provider: str
27
+ model: str
28
+ source: str
29
+
30
+
31
+ def _extract_json_object(text: str) -> dict[str, Any]:
32
+ text = text.strip()
33
+ if text.startswith("```"):
34
+ lines = [line for line in text.splitlines() if not line.strip().startswith("```")]
35
+ text = "\n".join(lines).strip()
36
+
37
+ try:
38
+ payload = json.loads(text)
39
+ except json.JSONDecodeError:
40
+ start = text.find("{")
41
+ end = text.rfind("}")
42
+ if start == -1 or end == -1 or end <= start:
43
+ raise
44
+ payload = json.loads(text[start : end + 1])
45
+
46
+ if not isinstance(payload, dict):
47
+ raise ValueError("Coach summary model output must be a JSON object")
48
+ return payload
49
+
50
+
51
+ def _summary_from_payload(payload: dict[str, Any]) -> CoachSummary:
52
+ summary = CoachSummary(
53
+ summary=str(payload["summary"]),
54
+ what_you_did=[str(item) for item in payload["what_you_did"]],
55
+ what_looked_good=[str(item) for item in payload["what_looked_good"]],
56
+ what_changed_across_reps=[str(item) for item in payload["what_changed_across_reps"]],
57
+ valid_variation_vs_issue=[str(item) for item in payload["valid_variation_vs_issue"]],
58
+ top_fixes=[str(item) for item in payload["top_fixes"]],
59
+ next_session_plan=[str(item) for item in payload["next_session_plan"]],
60
+ confidence_notes=[str(item) for item in payload["confidence_notes"]],
61
+ )
62
+ validate_contract("coach_summary.json", summary)
63
+ return summary
64
+
65
+
66
+ def _fallback(
67
+ *,
68
+ profile: UserProfile,
69
+ classification: ExerciseClassification,
70
+ reps: Reps,
71
+ analysis: RepAnalysis,
72
+ variation: Variation,
73
+ issues: IssueMarkers,
74
+ cards: list[KnowledgeCard],
75
+ failure_reason: str | None = None,
76
+ ) -> CoachSummary:
77
+ return build_fallback_summary(
78
+ profile=profile,
79
+ classification=classification,
80
+ reps=reps,
81
+ analysis=analysis,
82
+ variation=variation,
83
+ issues=issues,
84
+ cards=cards,
85
+ failure_reason=failure_reason,
86
+ )
87
 
88
 
89
  def run(
 
93
  analysis: RepAnalysis,
94
  variation: Variation,
95
  issues: IssueMarkers,
96
+ *,
97
+ cards: list[KnowledgeCard] | None = None,
98
+ model: CoachSummaryModel | None = None,
99
  ) -> CoachSummary:
100
+ return run_with_metadata(
101
+ profile,
102
+ classification,
103
+ reps,
104
+ analysis,
105
+ variation,
106
+ issues,
107
+ cards=cards,
108
+ model=model,
109
+ ).summary
110
+
111
+
112
+ def run_with_metadata(
113
+ profile: UserProfile,
114
+ classification: ExerciseClassification,
115
+ reps: Reps,
116
+ analysis: RepAnalysis,
117
+ variation: Variation,
118
+ issues: IssueMarkers,
119
+ *,
120
+ cards: list[KnowledgeCard] | None = None,
121
+ model: CoachSummaryModel | None = None,
122
+ ) -> CoachSummaryResult:
123
+ cards = cards or retrieve_cards(
124
+ profile=profile,
125
+ classification=classification,
126
+ variation=variation,
127
+ issues=issues,
128
  )
129
+ provider = get_coach_summary_model() if model is None else model
130
+ if provider is None:
131
+ return CoachSummaryResult(
132
+ summary=_fallback(
133
+ profile=profile,
134
+ classification=classification,
135
+ reps=reps,
136
+ analysis=analysis,
137
+ variation=variation,
138
+ issues=issues,
139
+ cards=cards,
140
+ failure_reason="remote provider unavailable",
141
+ ),
142
+ provider="none",
143
+ model="none",
144
+ source="fallback_initial",
145
+ )
146
 
147
+ prompt = build_coach_summary_prompt(
148
+ profile=profile,
149
+ classification=classification,
150
+ reps=reps,
151
+ analysis=analysis,
152
+ variation=variation,
153
+ issues=issues,
154
+ cards=cards,
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
155
  )
156
+
157
+ try:
158
+ generation = provider.generate_summary(prompt)
159
+ payload = _extract_json_object(generation.text)
160
+ return CoachSummaryResult(
161
+ summary=_summary_from_payload(payload),
162
+ provider=generation.provider,
163
+ model=generation.model,
164
+ source="model_or_local",
165
+ )
166
+ except Exception as exc:
167
+ return CoachSummaryResult(
168
+ summary=_fallback(
169
+ profile=profile,
170
+ classification=classification,
171
+ reps=reps,
172
+ analysis=analysis,
173
+ variation=variation,
174
+ issues=issues,
175
+ cards=cards,
176
+ failure_reason=str(exc),
177
+ ),
178
+ provider="fallback",
179
+ model="fallback",
180
+ source="fallback_initial",
181
+ )
src/pozify/steps/coach_summary_fallback.py ADDED
@@ -0,0 +1,211 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+
3
+ from pozify.contracts import (
4
+ CoachSummary,
5
+ ExerciseClassification,
6
+ IssueMarkers,
7
+ RepAnalysis,
8
+ Reps,
9
+ UserProfile,
10
+ Variation,
11
+ )
12
+ from pozify.knowledge_cards import KnowledgeCard, get_card_by_label
13
+
14
+
15
+ def _metric_score(metric: float, *, high: float = 0.8, medium: float = 0.65) -> str:
16
+ if metric >= high:
17
+ return "looked steady"
18
+ if metric >= medium:
19
+ return "looked fairly consistent"
20
+ return "showed room to tighten up"
21
+
22
+
23
+ def _issue_cards(issues: IssueMarkers) -> list[KnowledgeCard]:
24
+ cards: list[KnowledgeCard] = []
25
+ seen: set[str] = set()
26
+ for issue in issues.issues:
27
+ card = get_card_by_label(issue.issue)
28
+ if card is None or card.card_id in seen:
29
+ continue
30
+ seen.add(card.card_id)
31
+ cards.append(card)
32
+ return cards
33
+
34
+
35
+ def _top_issue_labels(issues: IssueMarkers) -> list[str]:
36
+ ranked = sorted(issues.issues, key=lambda item: item.severity, reverse=True)
37
+ labels: list[str] = []
38
+ for issue in ranked:
39
+ if issue.issue not in labels:
40
+ labels.append(issue.issue)
41
+ if len(labels) == 3:
42
+ break
43
+ return labels
44
+
45
+
46
+ def _confidence_notes(
47
+ classification: ExerciseClassification,
48
+ analysis: RepAnalysis,
49
+ variation: Variation,
50
+ reps: Reps,
51
+ ) -> list[str]:
52
+ notes: list[str] = []
53
+ if classification.confidence < 0.7:
54
+ notes.append(
55
+ "Exercise classification confidence is limited at "
56
+ f"{classification.confidence:.0%}, so treat the summary as a cautious read."
57
+ )
58
+ if variation.variation_confidence < 0.7:
59
+ notes.append(
60
+ "Variation confidence is "
61
+ f"{variation.variation_confidence:.0%}, so the variation call should be "
62
+ "treated as contextual rather than absolute."
63
+ )
64
+ pose_valid_ratio = float(analysis.aggregate_metrics.get("pose_valid_ratio", 1.0))
65
+ if pose_valid_ratio < 0.85:
66
+ notes.append(
67
+ f"Pose coverage is {pose_valid_ratio:.0%}, so some coaching points may be "
68
+ "based on limited landmark evidence."
69
+ )
70
+ if not reps.reps:
71
+ notes.append("No full reps were segmented, so the summary stays conservative.")
72
+ if not notes:
73
+ notes.append(
74
+ "This summary stays grounded to the current JSON evidence and may "
75
+ "miss details outside that evidence."
76
+ )
77
+ return notes
78
+
79
+
80
+ def build_fallback_summary(
81
+ *,
82
+ profile: UserProfile,
83
+ classification: ExerciseClassification,
84
+ reps: Reps,
85
+ analysis: RepAnalysis,
86
+ variation: Variation,
87
+ issues: IssueMarkers,
88
+ cards: list[KnowledgeCard],
89
+ failure_reason: str | None = None,
90
+ ) -> CoachSummary:
91
+ del cards
92
+ rep_count = len(reps.reps)
93
+ avg_rom = float(analysis.aggregate_metrics.get("avg_rom_score", 0.0))
94
+ avg_stability = float(analysis.aggregate_metrics.get("avg_stability_score", 0.0))
95
+ avg_symmetry = float(analysis.aggregate_metrics.get("avg_symmetry_score", 0.0))
96
+ fatigue_delta = float(analysis.aggregate_metrics.get("fatigue_trend_rom_delta", 0.0))
97
+ issue_labels = _top_issue_labels(issues)
98
+ issue_cards = _issue_cards(issues)
99
+ issue_count = len(issues.issues)
100
+
101
+ what_you_did = [
102
+ (
103
+ f"You completed {rep_count} detected `"
104
+ f"{classification.exercise}` reps with the variation labeled as "
105
+ f"`{variation.detected_variation}`."
106
+ )
107
+ ]
108
+ if profile.goal:
109
+ what_you_did.append(f"Your selected training goal was `{profile.goal}`.")
110
+
111
+ what_looked_good = [
112
+ f"Range of motion {_metric_score(avg_rom)} overall ({avg_rom:.0%}).",
113
+ f"Rep stability {_metric_score(avg_stability)} overall ({avg_stability:.0%}).",
114
+ f"Left-right symmetry {_metric_score(avg_symmetry)} overall ({avg_symmetry:.0%}).",
115
+ ]
116
+ if issue_count == 0:
117
+ what_looked_good.append(
118
+ "No sustained issue markers were detected in the current JSON evidence."
119
+ )
120
+
121
+ if rep_count <= 1:
122
+ what_changed = [
123
+ "There was not enough rep-to-rep data to describe a clear trend "
124
+ "across reps."
125
+ ]
126
+ elif fatigue_delta <= -0.08:
127
+ what_changed = [
128
+ f"Range of motion trended down across reps (delta {fatigue_delta:.2f}), "
129
+ "which suggests the later reps were less consistent."
130
+ ]
131
+ elif fatigue_delta >= 0.08:
132
+ what_changed = [
133
+ f"Range of motion improved slightly across reps (delta {fatigue_delta:.2f}) "
134
+ "as the set went on."
135
+ ]
136
+ else:
137
+ what_changed = ["Rep-to-rep range stayed fairly stable across the set."]
138
+
139
+ variation_notes = [
140
+ f"The detected variation was `{variation.detected_variation}`, so it should be "
141
+ "treated as context rather than a fault by default."
142
+ ]
143
+ if variation.not_issues:
144
+ variation_notes.append(
145
+ "The variation step marked "
146
+ + ", ".join(f"`{label}`" for label in variation.not_issues)
147
+ + " as not-issue context."
148
+ )
149
+ if issue_labels:
150
+ variation_notes.append(
151
+ "The actual issue markers in this set were "
152
+ + ", ".join(f"`{label}`" for label in issue_labels)
153
+ + "."
154
+ )
155
+ else:
156
+ variation_notes.append(
157
+ "No issue labels were present, so there is nothing to overcorrect."
158
+ )
159
+
160
+ top_fixes: list[str] = []
161
+ for card in issue_cards[:3]:
162
+ top_fixes.append(card.coaching_points[0])
163
+ if not top_fixes:
164
+ top_fixes.append(
165
+ "Keep the same camera angle and repeat the set to confirm the current pattern."
166
+ )
167
+
168
+ next_session_plan = [
169
+ "Start with 1 easy set of controlled reps using the same camera angle.",
170
+ (
171
+ "Keep your top focus on "
172
+ + (
173
+ ", ".join(f"`{label}`" for label in issue_labels)
174
+ if issue_labels
175
+ else "repeatable control"
176
+ )
177
+ + "."
178
+ ),
179
+ "Compare the next run against this report to see whether the same labels show up again.",
180
+ ]
181
+
182
+ confidence_notes = _confidence_notes(classification, analysis, variation, reps)
183
+ if failure_reason:
184
+ confidence_notes.append(
185
+ "Fallback summary was used because the generated summary did not pass "
186
+ f"verification: {failure_reason}"
187
+ )
188
+
189
+ issue_text = (
190
+ "No issue markers were present."
191
+ if not issue_labels
192
+ else "The highest-priority issue labels were "
193
+ + ", ".join(f"`{label}`" for label in issue_labels)
194
+ + "."
195
+ )
196
+ summary = (
197
+ "This grounded summary is based on structured artifacts for "
198
+ f"`{classification.exercise}` rather than direct video interpretation. "
199
+ f"{issue_text} The detected variation was `{variation.detected_variation}`."
200
+ )
201
+
202
+ return CoachSummary(
203
+ summary=summary,
204
+ what_you_did=what_you_did,
205
+ what_looked_good=what_looked_good,
206
+ what_changed_across_reps=what_changed,
207
+ valid_variation_vs_issue=variation_notes,
208
+ top_fixes=top_fixes,
209
+ next_session_plan=next_session_plan,
210
+ confidence_notes=confidence_notes,
211
+ )
src/pozify/steps/verifier.py CHANGED
@@ -1,30 +1,167 @@
1
  from __future__ import annotations
2
 
3
- from pozify.contracts import CoachSummary, IssueMarkers, Variation, Verification
4
 
 
 
 
 
 
 
 
 
 
 
5
 
6
- def run(summary: CoachSummary, issues: IssueMarkers, variation: Variation) -> Verification:
7
- issue_labels = {issue.issue for issue in issues.issues}
8
- mentioned_known_issue = (
9
- not issue_labels
10
- or any(label in " ".join(summary.main_findings + [summary.summary]) for label in issue_labels)
11
- )
12
- separated_variation = variation.detected_variation in summary.variation_explanation
13
- avoids_medical_claims = all(
14
- banned not in summary.summary.lower()
15
- for banned in ["diagnose", "injury prevention", "medical assessment"]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
16
  )
 
 
 
17
 
18
  checks = {
19
- "mentions_only_known_issues_mock": mentioned_known_issue,
20
- "separates_variation_from_issue": separated_variation,
21
- "avoids_medical_claims": avoids_medical_claims,
22
- "includes_confidence_notes": bool(summary.confidence_notes),
 
23
  }
24
 
 
 
 
 
 
 
 
 
 
 
 
 
 
25
  return Verification(
26
  passed=all(checks.values()),
27
  checks=checks,
28
- notes=[] if all(checks.values()) else ["Mock verifier found a summary contract issue."],
29
  )
30
-
 
1
  from __future__ import annotations
2
 
3
+ import re
4
 
5
+ from pozify.contracts import (
6
+ CoachSummary,
7
+ ExerciseClassification,
8
+ IssueMarkers,
9
+ RepAnalysis,
10
+ Reps,
11
+ Variation,
12
+ Verification,
13
+ )
14
+ from pozify.knowledge_cards import KNOWN_ISSUE_LABELS
15
 
16
+
17
+ DIAGNOSIS_PATTERNS = (
18
+ "diagnos",
19
+ "injury",
20
+ "tendonitis",
21
+ "tear",
22
+ "impingement",
23
+ "pathology",
24
+ "medical assessment",
25
+ )
26
+ INJURY_PREVENTION_PATTERNS = (
27
+ "prevent injury",
28
+ "injury prevention",
29
+ "avoid injury",
30
+ )
31
+ NEGATIVE_VARIATION_CONTEXT = (
32
+ "is an issue",
33
+ "is a fault",
34
+ "is a problem",
35
+ "fault",
36
+ "problem",
37
+ "error",
38
+ "wrong",
39
+ "incorrect",
40
+ "should be fixed",
41
+ )
42
+ SAFE_VARIATION_CONTEXT = (
43
+ "not-issue context",
44
+ "not an issue",
45
+ "rather than a fault",
46
+ "context rather than a fault",
47
+ )
48
+
49
+
50
+ def _contains_negative_variation_language(lines: list[str], labels: list[str]) -> bool:
51
+ for line in lines:
52
+ lowered = line.lower()
53
+ if not any(label in lowered for label in labels):
54
+ continue
55
+ if any(token in lowered for token in SAFE_VARIATION_CONTEXT):
56
+ continue
57
+ if any(token in lowered for token in NEGATIVE_VARIATION_CONTEXT):
58
+ return True
59
+ return False
60
+
61
+
62
+ def _summary_sections(summary: CoachSummary) -> list[str]:
63
+ return [
64
+ summary.summary,
65
+ *summary.what_you_did,
66
+ *summary.what_looked_good,
67
+ *summary.what_changed_across_reps,
68
+ *summary.valid_variation_vs_issue,
69
+ *summary.top_fixes,
70
+ *summary.next_session_plan,
71
+ *summary.confidence_notes,
72
+ ]
73
+
74
+
75
+ def _normalized_text(summary: CoachSummary) -> str:
76
+ return " ".join(_summary_sections(summary)).lower()
77
+
78
+
79
+ def _mentioned_labels(summary: CoachSummary) -> set[str]:
80
+ text = " ".join(_summary_sections(summary))
81
+ labels = set(re.findall(r"`([a-z0-9_]+)`", text))
82
+ lowered = text.lower()
83
+ for label in KNOWN_ISSUE_LABELS:
84
+ if label in lowered:
85
+ labels.add(label)
86
+ return labels
87
+
88
+
89
+ def _confidence_notes_required(
90
+ classification: ExerciseClassification,
91
+ analysis: RepAnalysis,
92
+ variation: Variation,
93
+ reps: Reps,
94
+ issues: IssueMarkers,
95
+ ) -> bool:
96
+ if classification.confidence < 0.7:
97
+ return True
98
+ if variation.variation_confidence < 0.7:
99
+ return True
100
+ if float(analysis.aggregate_metrics.get("pose_valid_ratio", 1.0)) < 0.85:
101
+ return True
102
+ if len(reps.reps) == 0:
103
+ return True
104
+ if len(issues.issues) == 0:
105
+ return True
106
+ return False
107
+
108
+
109
+ def run(
110
+ summary: CoachSummary,
111
+ issues: IssueMarkers,
112
+ variation: Variation,
113
+ *,
114
+ classification: ExerciseClassification,
115
+ analysis: RepAnalysis,
116
+ reps: Reps,
117
+ ) -> Verification:
118
+ allowed_issues = {issue.issue for issue in issues.issues}
119
+ mentioned_labels = _mentioned_labels(summary)
120
+ mentioned_issues = mentioned_labels & KNOWN_ISSUE_LABELS
121
+
122
+ no_issue_outside_json = mentioned_issues <= allowed_issues
123
+
124
+ variation_lines = summary.valid_variation_vs_issue + summary.top_fixes
125
+ variation_text = " ".join(variation_lines).lower()
126
+ variation_not_overcorrected = True
127
+ variation_labels = [variation.detected_variation, *variation.not_issues]
128
+ if _contains_negative_variation_language(variation_lines, variation_labels):
129
+ variation_not_overcorrected = False
130
+ if variation.detected_variation and variation.detected_variation not in variation_text:
131
+ variation_not_overcorrected = False
132
+
133
+ normalized = _normalized_text(summary)
134
+ no_diagnosis = all(pattern not in normalized for pattern in DIAGNOSIS_PATTERNS)
135
+ no_injury_prevention_claim = all(
136
+ pattern not in normalized for pattern in INJURY_PREVENTION_PATTERNS
137
  )
138
+ confidence_present = (
139
+ not _confidence_notes_required(classification, analysis, variation, reps, issues)
140
+ ) or bool(summary.confidence_notes)
141
 
142
  checks = {
143
+ "no_issue_outside_json": no_issue_outside_json,
144
+ "variation_not_overcorrected": variation_not_overcorrected,
145
+ "no_diagnosis": no_diagnosis,
146
+ "no_injury_prevention_claim": no_injury_prevention_claim,
147
+ "confidence_notes_present_when_required": confidence_present,
148
  }
149
 
150
+ notes: list[str] = []
151
+ if not no_issue_outside_json:
152
+ extra = sorted(mentioned_issues - allowed_issues)
153
+ notes.append(f"Summary mentioned issue labels not present in JSON: {', '.join(extra)}.")
154
+ if not variation_not_overcorrected:
155
+ notes.append("Summary did not keep valid variation context separate from issue correction.")
156
+ if not no_diagnosis:
157
+ notes.append("Summary used diagnosis-style language.")
158
+ if not no_injury_prevention_claim:
159
+ notes.append("Summary made an injury-prevention claim.")
160
+ if not confidence_present:
161
+ notes.append("Summary is missing required confidence notes.")
162
+
163
  return Verification(
164
  passed=all(checks.values()),
165
  checks=checks,
166
+ notes=notes,
167
  )
 
tests/test_coach_summary.py ADDED
@@ -0,0 +1,384 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ from pathlib import Path
5
+ import sys
6
+ import tempfile
7
+ import unittest
8
+ from unittest.mock import patch
9
+
10
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
11
+
12
+ from pozify.contracts import (
13
+ CoachSummary,
14
+ ExerciseClassification,
15
+ IssueMarker,
16
+ IssueMarkers,
17
+ Rep,
18
+ RepAnalysis,
19
+ RepAnalysisItem,
20
+ Reps,
21
+ UserProfile,
22
+ Variation,
23
+ )
24
+ from pozify.env import load_local_env
25
+ from pozify.knowledge_cards import retrieve_cards
26
+ from pozify.steps import coach_summary, coach_summary_fallback, verifier
27
+
28
+
29
+ class _BadModel:
30
+ def generate_summary(self, prompt: str):
31
+ del prompt
32
+ raise RuntimeError("synthetic model failure")
33
+
34
+
35
+ class _GoodModel:
36
+ def generate_summary(self, prompt: str):
37
+ del prompt
38
+ from pozify.slm.providers import CoachSummaryGeneration
39
+
40
+ return CoachSummaryGeneration(
41
+ text=(
42
+ '{"summary":"Structured summary.","what_you_did":["You completed 2 `push_up` reps."],'
43
+ '"what_looked_good":["Tempo looked steady."],'
44
+ '"what_changed_across_reps":["Later reps drifted into `hip_sag`."],'
45
+ '"valid_variation_vs_issue":["The detected variation was `wide_grip_push_up` with `wide_hand_placement` as context."],'
46
+ '"top_fixes":["Keep the hips in line through the later reps."],'
47
+ '"next_session_plan":["Repeat the set with slower reps."],'
48
+ '"confidence_notes":["Confidence is limited."]}'
49
+ ),
50
+ provider="hf_inference",
51
+ model="Qwen/Qwen2.5-7B-Instruct",
52
+ )
53
+
54
+
55
+ def _profile() -> UserProfile:
56
+ return UserProfile(
57
+ goal="beginner_practice",
58
+ experience_level="beginner",
59
+ intended_exercise="push_up",
60
+ intended_variation=None,
61
+ known_limitations=[],
62
+ equipment="bodyweight",
63
+ )
64
+
65
+
66
+ def _classification() -> ExerciseClassification:
67
+ return ExerciseClassification(
68
+ exercise="push_up",
69
+ confidence=0.66,
70
+ window_predictions=[],
71
+ fallback_required=False,
72
+ )
73
+
74
+
75
+ def _reps() -> Reps:
76
+ return Reps(
77
+ exercise="push_up",
78
+ reps=[
79
+ Rep(1, 0, 10, 20, 0.0, 0.33, 0.67),
80
+ Rep(2, 21, 30, 40, 0.7, 1.0, 1.33),
81
+ ],
82
+ partial_reps=[],
83
+ )
84
+
85
+
86
+ def _analysis() -> RepAnalysis:
87
+ return RepAnalysis(
88
+ exercise="push_up",
89
+ items=[
90
+ RepAnalysisItem(
91
+ rep_id=1,
92
+ duration_sec=0.67,
93
+ range_of_motion_score=0.82,
94
+ stability_score=0.84,
95
+ symmetry_score=0.88,
96
+ metrics={"body_line_score": 0.9},
97
+ variation_hints=["wide_grip_push_up"],
98
+ ),
99
+ RepAnalysisItem(
100
+ rep_id=2,
101
+ duration_sec=0.63,
102
+ range_of_motion_score=0.68,
103
+ stability_score=0.71,
104
+ symmetry_score=0.82,
105
+ metrics={"body_line_score": 0.6},
106
+ variation_hints=["wide_grip_push_up"],
107
+ ),
108
+ ],
109
+ aggregate_metrics={
110
+ "avg_rom_score": 0.75,
111
+ "avg_stability_score": 0.78,
112
+ "avg_symmetry_score": 0.85,
113
+ "fatigue_trend_rom_delta": -0.12,
114
+ "pose_valid_ratio": 0.79,
115
+ },
116
+ )
117
+
118
+
119
+ def _variation() -> Variation:
120
+ return Variation(
121
+ exercise="push_up",
122
+ detected_variation="wide_grip_push_up",
123
+ variation_confidence=0.68,
124
+ not_issues=["wide_hand_placement"],
125
+ )
126
+
127
+
128
+ def _issues() -> IssueMarkers:
129
+ return IssueMarkers(
130
+ issues=[
131
+ IssueMarker(
132
+ rep_id=2,
133
+ issue="hip_sag",
134
+ severity=0.82,
135
+ start_frame=24,
136
+ end_frame=31,
137
+ start_sec=0.8,
138
+ end_sec=1.03,
139
+ affected_joints=["left_hip", "right_hip"],
140
+ evidence={"body_line_score": 0.59, "confidence": 0.82},
141
+ )
142
+ ]
143
+ )
144
+
145
+
146
+ class CoachSummaryTests(unittest.TestCase):
147
+ def test_load_local_env_populates_missing_values(self) -> None:
148
+ with tempfile.TemporaryDirectory() as temp_dir:
149
+ env_path = Path(temp_dir) / ".env"
150
+ env_path.write_text(
151
+ "HF_TOKEN=test-token\nPOZIFY_COACH_SUMMARY_MODEL=Qwen/Qwen2.5-7B-Instruct\n",
152
+ encoding="utf-8",
153
+ )
154
+ with patch.dict(os.environ, {}, clear=True):
155
+ current = Path.cwd()
156
+ try:
157
+ os.chdir(temp_dir)
158
+ load_local_env()
159
+ finally:
160
+ os.chdir(current)
161
+
162
+ self.assertEqual(os.getenv("HF_TOKEN"), "test-token")
163
+ self.assertEqual(
164
+ os.getenv("POZIFY_COACH_SUMMARY_MODEL"),
165
+ "Qwen/Qwen2.5-7B-Instruct",
166
+ )
167
+
168
+ def test_card_retrieval_is_deterministic_and_grounded(self) -> None:
169
+ cards = retrieve_cards(
170
+ profile=_profile(),
171
+ classification=_classification(),
172
+ variation=_variation(),
173
+ issues=_issues(),
174
+ )
175
+
176
+ card_ids = [card.card_id for card in cards]
177
+ self.assertEqual(
178
+ card_ids[:4],
179
+ [
180
+ "exercise:push_up",
181
+ "variation:wide_grip_push_up",
182
+ "issue:hip_sag",
183
+ "goal:beginner_practice",
184
+ ],
185
+ )
186
+ self.assertIn("safety:no_diagnosis", card_ids)
187
+
188
+ def test_coach_summary_falls_back_when_model_fails(self) -> None:
189
+ cards = retrieve_cards(
190
+ profile=_profile(),
191
+ classification=_classification(),
192
+ variation=_variation(),
193
+ issues=_issues(),
194
+ )
195
+
196
+ summary = coach_summary.run(
197
+ _profile(),
198
+ _classification(),
199
+ _reps(),
200
+ _analysis(),
201
+ _variation(),
202
+ _issues(),
203
+ cards=cards,
204
+ model=_BadModel(),
205
+ )
206
+
207
+ self.assertTrue(summary.confidence_notes)
208
+ self.assertIn("Fallback summary was used", " ".join(summary.confidence_notes))
209
+ self.assertIn("`wide_grip_push_up`", " ".join(summary.valid_variation_vs_issue))
210
+
211
+ def test_coach_summary_metadata_includes_provider_and_model(self) -> None:
212
+ result = coach_summary.run_with_metadata(
213
+ _profile(),
214
+ _classification(),
215
+ _reps(),
216
+ _analysis(),
217
+ _variation(),
218
+ _issues(),
219
+ cards=retrieve_cards(
220
+ profile=_profile(),
221
+ classification=_classification(),
222
+ variation=_variation(),
223
+ issues=_issues(),
224
+ ),
225
+ model=_GoodModel(),
226
+ )
227
+
228
+ self.assertEqual(result.provider, "hf_inference")
229
+ self.assertEqual(result.model, "Qwen/Qwen2.5-7B-Instruct")
230
+ self.assertEqual(result.source, "model_or_local")
231
+
232
+ def test_verifier_rejects_issue_not_in_json(self) -> None:
233
+ summary = CoachSummary(
234
+ summary="The strongest issue was `incomplete_depth`.",
235
+ what_you_did=["You completed 2 `push_up` reps."],
236
+ what_looked_good=["Tempo looked steady."],
237
+ what_changed_across_reps=["Later reps lost range."],
238
+ valid_variation_vs_issue=["The detected variation was `wide_grip_push_up`."],
239
+ top_fixes=["Address `incomplete_depth` first."],
240
+ next_session_plan=["Repeat the set with slower reps."],
241
+ confidence_notes=["Confidence is limited."],
242
+ )
243
+
244
+ result = verifier.run(
245
+ summary,
246
+ _issues(),
247
+ _variation(),
248
+ classification=_classification(),
249
+ analysis=_analysis(),
250
+ reps=_reps(),
251
+ )
252
+
253
+ self.assertFalse(result.passed)
254
+ self.assertFalse(result.checks["no_issue_outside_json"])
255
+
256
+ def test_verifier_rejects_diagnosis_and_variation_overcorrection(self) -> None:
257
+ summary = CoachSummary(
258
+ summary="This `wide_grip_push_up` pattern shows a shoulder injury risk.",
259
+ what_you_did=["You completed 2 `push_up` reps."],
260
+ what_looked_good=["The set started under control."],
261
+ what_changed_across_reps=["Later reps drifted into `hip_sag`."],
262
+ valid_variation_vs_issue=[
263
+ "Your `wide_grip_push_up` with `wide_hand_placement` is a problem "
264
+ "that should be fixed."
265
+ ],
266
+ top_fixes=["Correct `wide_hand_placement` before anything else."],
267
+ next_session_plan=["Repeat the set."],
268
+ confidence_notes=["Confidence is limited."],
269
+ )
270
+
271
+ result = verifier.run(
272
+ summary,
273
+ _issues(),
274
+ _variation(),
275
+ classification=_classification(),
276
+ analysis=_analysis(),
277
+ reps=_reps(),
278
+ )
279
+
280
+ self.assertFalse(result.passed)
281
+ self.assertFalse(result.checks["variation_not_overcorrected"])
282
+ self.assertFalse(result.checks["no_diagnosis"])
283
+
284
+ def test_fallback_summary_does_not_false_positive_on_issue_marker_phrase(self) -> None:
285
+ summary = coach_summary_fallback.build_fallback_summary(
286
+ profile=_profile(),
287
+ classification=ExerciseClassification(
288
+ exercise="squat",
289
+ confidence=0.92,
290
+ window_predictions=[],
291
+ fallback_required=False,
292
+ ),
293
+ reps=Reps(
294
+ exercise="squat",
295
+ reps=[Rep(1, 0, 10, 20, 0.0, 0.33, 0.67)],
296
+ partial_reps=[],
297
+ ),
298
+ analysis=RepAnalysis(
299
+ exercise="squat",
300
+ items=[],
301
+ aggregate_metrics={
302
+ "avg_rom_score": 0.57,
303
+ "avg_stability_score": 0.68,
304
+ "avg_symmetry_score": 0.56,
305
+ "fatigue_trend_rom_delta": -0.10,
306
+ "pose_valid_ratio": 0.93,
307
+ },
308
+ ),
309
+ variation=Variation(
310
+ exercise="squat",
311
+ detected_variation="wide_squat_stance",
312
+ variation_confidence=0.82,
313
+ not_issues=["wide_stance"],
314
+ ),
315
+ issues=IssueMarkers(
316
+ issues=[
317
+ IssueMarker(
318
+ rep_id=1,
319
+ issue="shallow_depth",
320
+ severity=0.81,
321
+ start_frame=10,
322
+ end_frame=14,
323
+ start_sec=0.33,
324
+ end_sec=0.46,
325
+ affected_joints=["left_hip", "right_hip"],
326
+ evidence={"confidence": 0.81},
327
+ )
328
+ ]
329
+ ),
330
+ cards=[],
331
+ )
332
+
333
+ result = verifier.run(
334
+ summary,
335
+ IssueMarkers(
336
+ issues=[
337
+ IssueMarker(
338
+ rep_id=1,
339
+ issue="shallow_depth",
340
+ severity=0.81,
341
+ start_frame=10,
342
+ end_frame=14,
343
+ start_sec=0.33,
344
+ end_sec=0.46,
345
+ affected_joints=["left_hip", "right_hip"],
346
+ evidence={"confidence": 0.81},
347
+ )
348
+ ]
349
+ ),
350
+ Variation(
351
+ exercise="squat",
352
+ detected_variation="wide_squat_stance",
353
+ variation_confidence=0.82,
354
+ not_issues=["wide_stance"],
355
+ ),
356
+ classification=ExerciseClassification(
357
+ exercise="squat",
358
+ confidence=0.92,
359
+ window_predictions=[],
360
+ fallback_required=False,
361
+ ),
362
+ analysis=RepAnalysis(
363
+ exercise="squat",
364
+ items=[],
365
+ aggregate_metrics={
366
+ "avg_rom_score": 0.57,
367
+ "avg_stability_score": 0.68,
368
+ "avg_symmetry_score": 0.56,
369
+ "fatigue_trend_rom_delta": -0.10,
370
+ "pose_valid_ratio": 0.93,
371
+ },
372
+ ),
373
+ reps=Reps(
374
+ exercise="squat",
375
+ reps=[Rep(1, 0, 10, 20, 0.0, 0.33, 0.67)],
376
+ partial_reps=[],
377
+ ),
378
+ )
379
+
380
+ self.assertTrue(result.checks["variation_not_overcorrected"])
381
+
382
+
383
+ if __name__ == "__main__":
384
+ unittest.main()
tests/test_pipeline_contracts.py CHANGED
@@ -14,8 +14,9 @@ import numpy as np
14
  sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
15
 
16
  from pozify import pipeline
17
- from pozify.contracts import ContractValidationError, UserProfile, validate_contract
18
  from pozify.exercise_catalog import USER_SELECTABLE_EXERCISES
 
19
 
20
 
21
  PROFILE_INPUT = {
@@ -83,12 +84,13 @@ EXPECTED_ARTIFACT_KEYS = {
83
  "issue_markers.json": ["issues"],
84
  "coach_summary.json": [
85
  "confidence_notes",
86
- "main_findings",
87
  "next_session_plan",
88
  "summary",
89
  "top_fixes",
90
- "variation_explanation",
91
- "what_went_well",
 
 
92
  ],
93
  "verification.json": ["checks", "notes", "passed"],
94
  "final_report.json": [
@@ -245,6 +247,62 @@ class PipelineContractTests(unittest.TestCase):
245
  self.assertEqual(payload_by_step["issues"]["issue_count"], 0)
246
  self.assertIn("annotated_video_path", payload_by_step["render"])
247
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
248
  def test_contract_validation_rejects_missing_required_field(self) -> None:
249
  payload = {
250
  "goal": "beginner_practice",
 
14
  sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
15
 
16
  from pozify import pipeline
17
+ from pozify.contracts import CoachSummary, ContractValidationError, UserProfile, Verification, validate_contract
18
  from pozify.exercise_catalog import USER_SELECTABLE_EXERCISES
19
+ from pozify.steps.coach_summary import CoachSummaryResult
20
 
21
 
22
  PROFILE_INPUT = {
 
84
  "issue_markers.json": ["issues"],
85
  "coach_summary.json": [
86
  "confidence_notes",
 
87
  "next_session_plan",
88
  "summary",
89
  "top_fixes",
90
+ "valid_variation_vs_issue",
91
+ "what_changed_across_reps",
92
+ "what_looked_good",
93
+ "what_you_did",
94
  ],
95
  "verification.json": ["checks", "notes", "passed"],
96
  "final_report.json": [
 
247
  self.assertEqual(payload_by_step["issues"]["issue_count"], 0)
248
  self.assertIn("annotated_video_path", payload_by_step["render"])
249
 
250
+ def test_pipeline_can_bypass_verifier_and_keep_model_summary(self) -> None:
251
+ model_summary = CoachSummary(
252
+ summary="Model summary kept.",
253
+ what_you_did=["You completed 1 `squat` rep."],
254
+ what_looked_good=["The setup looked steady."],
255
+ what_changed_across_reps=["Not enough reps for a trend."],
256
+ valid_variation_vs_issue=["The detected variation was `wide_squat_stance`."],
257
+ top_fixes=["Sit slightly deeper before standing up."],
258
+ next_session_plan=["Repeat the set with the same camera angle."],
259
+ confidence_notes=["Confidence is limited."],
260
+ )
261
+ with (
262
+ patch.dict(os.environ, {"POZIFY_COACH_SUMMARY_BYPASS_VERIFIER": "1"}),
263
+ patch(
264
+ "pozify.pipeline.coach_summary.run_with_metadata",
265
+ return_value=CoachSummaryResult(
266
+ summary=model_summary,
267
+ provider="hf_inference",
268
+ model="Qwen/Qwen2.5-7B-Instruct",
269
+ source="model_or_local",
270
+ ),
271
+ ),
272
+ patch(
273
+ "pozify.pipeline.verifier.run",
274
+ return_value=Verification(
275
+ passed=False,
276
+ checks={
277
+ "no_issue_outside_json": True,
278
+ "variation_not_overcorrected": False,
279
+ "no_diagnosis": True,
280
+ "no_injury_prevention_claim": True,
281
+ "confidence_notes_present_when_required": True,
282
+ },
283
+ notes=["Synthetic verifier failure."],
284
+ ),
285
+ ),
286
+ ):
287
+ result = pipeline.run_pipeline(
288
+ video_path=None, profile_input=PROFILE_INPUT, mock=True
289
+ )
290
+
291
+ self._assert_pipeline_artifacts(result)
292
+ report = result["final_report"]
293
+ self.assertEqual(report["coach_summary"]["summary"], "Model summary kept.")
294
+ self.assertEqual(report["artifacts"]["coach_summary_source"], "model_or_local")
295
+ self.assertEqual(report["artifacts"]["coach_summary_provider"], "hf_inference")
296
+ self.assertEqual(
297
+ report["artifacts"]["coach_summary_model"],
298
+ "Qwen/Qwen2.5-7B-Instruct",
299
+ )
300
+ self.assertTrue(report["artifacts"]["coach_summary_verifier_bypassed"])
301
+ self.assertFalse(report["verification"]["passed"])
302
+ self.assertTrue(
303
+ report["artifacts"]["coach_summary_verifier_bypass_requested"]
304
+ )
305
+
306
  def test_contract_validation_rejects_missing_required_field(self) -> None:
307
  payload = {
308
  "goal": "beginner_practice",
web/app.js CHANGED
@@ -334,7 +334,12 @@ function SummaryTab({ result }) {
334
  h(
335
  "div",
336
  { className: "note-grid" },
337
- h(NoteList, { title: "What went well", items: summary.what_went_well }),
 
 
 
 
 
338
  h(NoteList, { title: "Top fixes", items: summary.top_fixes }),
339
  h(NoteList, { title: "Next session", items: summary.next_session_plan }),
340
  ),
@@ -648,27 +653,58 @@ function CoachTab({ result }) {
648
  h("p", null, "Coach notes appear after analysis."),
649
  );
650
  const summary = result.report.coach_summary;
 
 
 
 
 
 
 
651
  return h(
652
  "section",
653
  { className: "summary" },
654
  h("h2", null, "Coach summary"),
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
655
  h("p", null, summary.summary),
656
  h(
657
  "div",
658
  { className: "note-grid" },
659
- h(NoteList, { title: "Main findings", items: summary.main_findings }),
 
 
 
 
660
  h(NoteList, { title: "Top fixes", items: summary.top_fixes }),
661
  h(NoteList, {
662
  title: "Confidence notes",
663
  items: summary.confidence_notes,
664
  }),
665
  ),
666
- h(
667
- "article",
668
- { className: "note full-note" },
669
- h("h3", null, "Variation context"),
670
- h("p", null, summary.variation_explanation),
671
- ),
672
  );
673
  }
674
 
@@ -773,6 +809,7 @@ function App() {
773
  const [variation, setVariation] = useState("");
774
  const [equipment, setEquipment] = useState("bodyweight");
775
  const [limitations, setLimitations] = useState([]);
 
776
  const [result, setResult] = useState(null);
777
  const [activeTab, setActiveTab] = useState("summary");
778
  const [status, setStatus] = useState("idle");
@@ -820,6 +857,7 @@ function App() {
820
  payload.append("intended_variation", variation);
821
  payload.append("limitations", JSON.stringify(limitations));
822
  payload.append("equipment", equipment);
 
823
 
824
  try {
825
  const response = await fetch("/api/analyze/stream", {
@@ -992,6 +1030,21 @@ function App() {
992
  ),
993
  ),
994
  ),
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
995
  ),
996
  h(
997
  "button",
 
334
  h(
335
  "div",
336
  { className: "note-grid" },
337
+ h(NoteList, { title: "What you did", items: summary.what_you_did }),
338
+ h(NoteList, { title: "What looked good", items: summary.what_looked_good }),
339
+ h(NoteList, {
340
+ title: "What changed across reps",
341
+ items: summary.what_changed_across_reps,
342
+ }),
343
  h(NoteList, { title: "Top fixes", items: summary.top_fixes }),
344
  h(NoteList, { title: "Next session", items: summary.next_session_plan }),
345
  ),
 
653
  h("p", null, "Coach notes appear after analysis."),
654
  );
655
  const summary = result.report.coach_summary;
656
+ const coachArtifacts = result.report.artifacts || {};
657
+ const coachSource = coachArtifacts.coach_summary_source || "";
658
+ const coachProvider = coachArtifacts.coach_summary_provider || "n/a";
659
+ const coachModel = coachArtifacts.coach_summary_model || "n/a";
660
+ const verifierBypassed = Boolean(
661
+ coachArtifacts.coach_summary_verifier_bypassed,
662
+ );
663
  return h(
664
  "section",
665
  { className: "summary" },
666
  h("h2", null, "Coach summary"),
667
+ h(
668
+ "div",
669
+ { className: "stat-grid" },
670
+ [
671
+ ["Provider", coachProvider],
672
+ ["Model", coachModel],
673
+ ["Source", coachSource || "n/a"],
674
+ ].map(([name, value]) =>
675
+ h(
676
+ "div",
677
+ { className: "stat", key: name },
678
+ h("span", null, name),
679
+ h("strong", null, value),
680
+ ),
681
+ ),
682
+ ),
683
+ coachSource.startsWith("fallback")
684
+ ? h("p", null, "A conservative fallback summary was used because the generated summary was unavailable or did not pass verification.")
685
+ : null,
686
+ verifierBypassed
687
+ ? h("p", null, "Verifier bypass is active, so the model summary is shown even though verification did not pass.")
688
+ : null,
689
  h("p", null, summary.summary),
690
  h(
691
  "div",
692
  { className: "note-grid" },
693
+ h(NoteList, { title: "What you did", items: summary.what_you_did }),
694
+ h(NoteList, {
695
+ title: "Variation vs issue",
696
+ items: summary.valid_variation_vs_issue,
697
+ }),
698
  h(NoteList, { title: "Top fixes", items: summary.top_fixes }),
699
  h(NoteList, {
700
  title: "Confidence notes",
701
  items: summary.confidence_notes,
702
  }),
703
  ),
704
+ h(NoteList, {
705
+ title: "Next session plan",
706
+ items: summary.next_session_plan,
707
+ }),
 
 
708
  );
709
  }
710
 
 
809
  const [variation, setVariation] = useState("");
810
  const [equipment, setEquipment] = useState("bodyweight");
811
  const [limitations, setLimitations] = useState([]);
812
+ const [bypassVerifier, setBypassVerifier] = useState(false);
813
  const [result, setResult] = useState(null);
814
  const [activeTab, setActiveTab] = useState("summary");
815
  const [status, setStatus] = useState("idle");
 
857
  payload.append("intended_variation", variation);
858
  payload.append("limitations", JSON.stringify(limitations));
859
  payload.append("equipment", equipment);
860
+ payload.append("bypass_verifier", String(bypassVerifier));
861
 
862
  try {
863
  const response = await fetch("/api/analyze/stream", {
 
1030
  ),
1031
  ),
1032
  ),
1033
+ h(
1034
+ "div",
1035
+ { className: "field full" },
1036
+ h("span", { className: "label" }, "Advanced"),
1037
+ h(
1038
+ "label",
1039
+ { className: "check-chip" },
1040
+ h("input", {
1041
+ type: "checkbox",
1042
+ checked: bypassVerifier,
1043
+ onChange: () => setBypassVerifier((current) => !current),
1044
+ }),
1045
+ h("span", null, "Bypass verifier and show model output"),
1046
+ ),
1047
+ ),
1048
  ),
1049
  h(
1050
  "button",