How pose estimation, biomechanics rules, and LLM coaching combine to make a Dockerized video-analysis MVP for lifting form

Table of Contents

1. Key Highlights
2. Introduction
3. The athlete-facing problem and product goal
4. High-level architecture and operational flow
5. Tech choices and the rationale behind them
6. Supported exercises and detection heuristics
7. The ML and biomechanics pipeline — a step-by-step walk-through
8. Video annotation and browser playback
9. The role of the LLM: structured coaching reports
10. Example user flows and case studies
11. Frontend experience and interaction design
12. Evaluation, accuracy, and validation
13. Limitations, biases, and ethical considerations
14. Deployment, scaling, and cost considerations
15. Reproducibility, open-source strategy, and getting started
16. Practical improvements and research directions
17. What FormCoach delivers and where it fits in the ecosystem
18. Final operational notes and engineering lessons
19. FAQ

Key Highlights

• FormCoach transforms a short side-view workout video into an annotated MP4, per-rep biomechanics metrics, risk flags, and a structured coaching report generated by an LLM — all via a four-service Docker Compose stack.
• The system pairs YOLOv11-pose keypoint extraction and signal-processing rep segmentation with rule-based biomechanics heuristics to produce interpretable flags, a 0–100 form score, and actionable corrective drills; GPT-4o-mini supplies human-readable coaching when an API key is present.

Introduction

Athletes training without a coach lack reliable objective feedback. Mirrors and guesswork leave critical questions unanswered: Was my torso too far forward? Did my knees cave? Did I hinge or squat? FormCoach addresses those gaps by converting raw workout video into a structured feedback loop: detect → measure → flag → explain → coach → compare. The project stitches together pose estimation, joint-angle math, signal processing, and an LLM for narrative coaching, wrapped in a Docker Compose stack that runs locally. The result is a functional minimum viable product that demonstrates how applied computer vision and simple biomechanics rules produce meaningful, repeatable feedback for lifters and trainers.

The following report examines the system end-to-end: product motivations, architecture, the ML and biomechanics pipeline, user experience, operational realities, limitations, and practical considerations for anyone looking to replicate or extend the work.

The athlete-facing problem and product goal

Most non-coached athletes face four consistent pain points:

• They cannot reliably see their form from the optimal angle while lifting.
• They cannot quantify movement quality beyond subjective impressions.
• They cannot track objective improvement across sessions.
• They rarely receive corrections tied to specific reps and moments.

FormCoach targets those gaps. It accepts short side-view recordings, extracts 17 COCO keypoints per frame, derives joint angles and a per-rep timeline, identifies known risk patterns, and produces both a scored summary and a plain-language coaching report. The product design prioritizes repeatable, explainable outputs over opaque machine decisions, because reproducibility and interpretability matter to athletes and clinicians alike.

Practical example: a recreational lifter records five back squats and receives a frame-annotated video highlighting hip-wink at the bottom of two reps, a per-rep knee angle table, a form score that can be trended, and a coaching card recommending goblet squats with a wall cue to train upright torso. That sequence turns subjective suspicion into actionable next steps.

High-level architecture and operational flow

FormCoach runs as a four-service Docker Compose stack:

• Frontend: React + Vite (port 5173) — upload UI, result viewer, progress and history pages.
• Backend: FastAPI (port 8000) — REST endpoints, upload handling, job management.
• Worker: Celery — the asynchronous video processing pipeline.
• Redis: Celery broker and result backend.

Data flow:

1. The user uploads MP4/MOV/AVI/WebM via the React UI.
2. Backend saves the file and enqueues a Celery task.
3. Worker runs the processing pipeline asynchronously (typically 60–90 seconds on CPU).
4. Frontend polls GET /api/jobs/{job_id} for status updates until the job completes.
5. Completed sessions append a JSON history entry for progression tracking; raw and processed outputs are available via API.

Why an async worker: pose extraction and annotation are compute-bound and take longer than reasonable HTTP timeouts. Celery offloads work, allows progress reporting to Redis, and keeps the web server responsive.

Operational note: the pipeline is intentionally CPU-first to keep the demo accessible; adding a GPU accelerates pose inference and reduces processing time significantly, but complicates local reproducibility.

Tech choices and the rationale behind them

The stack blends established CV tooling, pragmatic infra choices, and modern frontend ergonomics:

Backend and pipeline components:

• FastAPI: lightweight, typed API with Pydantic schemas for predictable inputs and outputs.
• Celery + Redis: robust background job system with progress reporting and result storage.
• Ultralytics YOLOv11-pose: single-stage detection and pose estimation supporting 17 COCO keypoints.
• OpenCV: frame I/O and annotation rendering.
• NumPy + SciPy: joint-angle computations, Savitzky–Golay smoothing, and peak detection for rep segmentation.
• FFmpeg: H.264 transcoding for browser-compatible video.

Frontend:

• React 18 + TypeScript for predictable UI state.
• Vite for fast developer feedback.
• Tailwind CSS for compact, themable UI.
• Axios for HTTP requests and polling.

Infrastructure:

• Docker Compose for one-command local launches and reproducibility.
• Shared volume for uploads and outputs.

Design trade-offs:

• Rule-based biomechanics scoring preserves explainability. A data-driven model might detect subtler faults but would require labeled movement data and careful generalization tests.
• YOLOv11-pose provides a small, reliable footprint; higher-accuracy pose models exist but increase runtime and complexity.
• FFmpeg is a required step: OpenCV’s mp4v output fails in many browsers, so a transcode to yuv420p/H.264 is mandatory for cross-browser playback.

Supported exercises and detection heuristics

FormCoach supports five primary movements and a simple auto-detection mode:

• Squat — primary metric: knee angle; filming: side view, full body.
• Deadlift — primary: hip angle; filming: side view, bar path visible.
• Push-up — primary: elbow angle; filming: side or 45°.
• Romanian Deadlift (RDL) — primary: hip angle; filming: hinge visible.
• Lunge — primary: knee angle; filming: side, full stride.

Auto-detection uses heuristic motion patterns derived from the joint-angle ranges and axis-aligned keypoint trajectories:

• Large vertical hip and knee movement → squat.
• Large hip vertical travel with limited knee travel → deadlift / hinge.
• Dominant shoulder movement with stationary hips → push-up.

Users can override auto-detection. Manual selection improves rep segmentation when lighting, occlusion, or camera angle confuses the heuristics. That choice addresses two real-world failure modes: 1) similar pattern overlap between squat and lunge; 2) side-on occlusion in multi-person or crowded gym videos.

Real-world illustrative case: a lifter films an RDL but the auto-detector identifies a deadlift because knee movement exceeds a threshold caused by a small step back. Manual selection of RDL forces the pipeline to analyze hip hinge as the primary signal, resulting in more accurate rep boundaries and angle summaries.

The ML and biomechanics pipeline — a step-by-step walk-through

The core pipeline runs inside the Celery worker as eight sequential stages. Each stage returns progress updates to Redis so the frontend can show progress and intermediate state.

Step 1 — Pose extraction

• The worker calls extract_keypoints() which runs YOLOv11-pose over the video frames.
• YOLO returns 17 COCO keypoints per detected person per frame: nose, eyes, ears, shoulders, elbows, wrists, hips, knees, ankles.
• Coordinates are normalized to frame width/height and filtered with a confidence threshold (≥0.3).
• If no person is detected throughout the sampled frames, the job fails with a clear error and tips to re-record from the side or increase lighting.

Engineering choice: model.predict() is run per video to avoid cross-job tracker state. model.track() with persistent trackers causes state leakage when a single worker serves multiple jobs sequentially.

Step 2 — Joint-angle computation

• For each frame with sufficient keypoints, compute four angles via vector dot-product on triplets:
  • Knee angle: hip–knee–ankle (averaged across left and right when visible).
  • Hip angle: shoulder–hip–knee.
  • Elbow angle: shoulder–elbow–wrist.
  • Torso lean: vector from shoulder–hip midpoint to vertical.
• Angles are expressed in degrees and stored per frame.

Step 3 — Rep segmentation

• Use SciPy signal processing on the primary angle signal (knee for squats, hip for deadlifts/RDLs, elbow for push-ups).
• Interpolate across missing frames caused by low-confidence keypoints.
• Smooth with Savitzky–Golay filtering to preserve peak/trough shape while removing jitter.
• Detect troughs (movement bottoms) using find_peaks on inverted signal.
• Define rep boundaries between consecutive troughs and peaks.

Each detected rep includes start/end frames, duration, min/max per-joint angles, and initial rep-level risk flags.

Step 4 — Per-frame timeline

• Annotate every frame with:
  • status: good | flag | no_pose
  • flags: list of active risk flag names for that frame
  • rep_number: which rep this frame belongs to
  • angles: joint-angle snapshot
  • time_sec: elapsed seconds
• This timeline enables interactive UX: a user clicks a flag event and the player seeks to the flagged frame.

Step 5 — Risk flags and scoring

• A set of rule-based flags is applied to rep-level summaries and frame-level windows. Representative flags:
  • excessive_forward_lean: torso lean exceeds threshold.
  • hip_wink: pelvis tucks at the bottom of a squat, detected by abrupt hip angle change.
  • knee_cave_risk: knee valgus below a safe angle.
  • lumbar_flexion_risk: closed hip hinge / rounded lumbar in deadlifts/RDLs.
  • elbow_flare: elbow angle indicates flared elbows during push-ups.
• Each flag contributes a rep risk score between 0 and 1. Rep scores average into an overall risk metric: LOW (<0.2), MEDIUM (0.2–0.5), HIGH (>0.5).

Step 6 — Form score (0–100)

• The system computes a composite form score that rewards a high proportion of “good” frames and penalizes flagged reps and high-risk severity.
• The score is designed for progression charts: a single, repeatable numeric signal across sessions.

Step 7 — Flag insights

• For each unique flag, create a FlagInsight:
  • Label — human-readable.
  • Causal explanation — ties to frame-level metrics (“Torso leaned 62° from vertical at rep 3”).
  • Corrective drill — short actionable cue (e.g., “Try goblet squats facing a wall”).
  • Example frame timestamp and count of occurrences.
• This makes the output explanatory rather than merely diagnostic.

Step 8 — Joint trajectories

• Compute hip and knee midpoints across frames as normalized (x,y) time series. These feed trajectory charts that illustrate the movement arc and symmetry across reps.

Practical nuance: interpolation and smoothing choices materially affect rep counts and detected minima/maxima. The Savitzky–Golay filter window and polynomial order are tuned to preserve rep peak shapes while removing keypoint jitter. Changes to those parameters should be validated on held-out videos.

Video annotation and browser playback

Annotation uses OpenCV to render frame-by-frame overlays:

• Skeleton overlay connects detected keypoints; connection lines are green unless a flag activates, in which case they turn red.
• Per-frame joint angles render as text at joint locations.
• A rep counter and status badge (“GOOD FORM”, “RISK DETECTED”, “NO POSE”) appear in corners.

OpenCV writes an intermediate MP4 with the mp4v codec, but that output is not reliably playable in HTML5 across all browsers. FFmpeg transcodes the annotated output to H.264 (yuv420p), which ensures cross-browser playback. That transcode step is operationally required: skipping it results in inconsistent playback on Safari and certain Chromium builds.

Real-world lesson: minor codec decisions cause significant UX issues. In demos intended for non-technical users, invest time in ensuring video playback compatibility.

The role of the LLM: structured coaching reports

After biomechanics processing, the worker composes a structured prompt to GPT-4o-mini containing:

• Aggregate metrics: total reps and overall risk.
• Per-rep angle summaries.
• Detected flags and counts.

The prompt instructs the model to return structured JSON with keys such as overall_assessment, strengths, and corrections (title + cue). The frontend renders the response into:

• An assessment paragraph.
• A “What you’re doing well” block.
• Numbered correction cards with succinct, actionable cues.

If an OPENAI_API_KEY is absent, the system falls back to a deterministic template that translates the biomechanics data into a coaching report. That fallback preserves functionality while avoiding API dependency.

Care required: LLM outputs can drift. Prompting for strict JSON and validating parse results protects the UI from malformed responses. Enforcing a rigid schema and fallback ensures consistent rendering.

Safety note: the LLM provides general coaching cues, not medical or clinical advice. Flags are movement-quality indicators, not diagnostic statements.

Example user flows and case studies

1. Recreational lifter — squat practice

• Upload: five squats filmed side-on.
• Outcomes: pipeline finds five reps, flags hip_wink in reps 2 and 4, assigns form score 72/100.
• Coach report: recommends goblet squats facing a wall and tempo work to maintain an upright torso.
• Progress: lifter uses a baseline comparison to a prior session. The system reports an 8-point improvement and a 6° increase in knee depth.

2. Remote physical-therapy check-in

• Patient records Romanian deadlifts for a clinician to monitor hip hinge mechanics.
• Outcomes: the system flags lumbar_flexion_risk on three reps and provides example frames the clinician can reference.
• Usefulness: the clinician receives quantifiable hip-angle minima and rep timestamps for asynchronous review.

3. Strength coach remotely monitoring a team

• The coach asks athletes to upload standardized side-view videos. Across sessions, the coach uses the progress page to spot regressions in form score or increases in risk flags.
• This creates an evidence-backed basis for individual corrective programming.

These flows show how a reproducible measurement pipeline becomes a practical feedback loop for training and remote coaching.

Frontend experience and interaction design

The UI centers around a timeline-synced review:

• Home page: exercise picker (auto-detect/manual), optional baseline selection, drag-and-drop upload, and camera-check tips.
• Results page: form score badge, risk level pill, a video player connected to a timeline scrubber with flag events and a joint trajectory chart. Clicking a flag seeks to the frame.
• Flag insights: each flag links to a corrective drill and example frame for immediate repetition of feedback.
• Comparison panel: concise, human-readable deltas when a baseline is selected.
• Progress page: per-exercise session grouping and a bar chart of form scores.

UX considerations:

• Camera setup validation runs a lightweight sample of frames to detect gross framing or lighting issues and returns actionable tips rather than hard blocks.
• Polling every two seconds for job status keeps the UI responsive without overwhelming the backend.
• Visual cues intentionally prioritize clarity: green for acceptable, red for problematic, and gray for no-pose frames that require re-recording.

Design trade-off: the system opts for batch review instead of live feedback. Live feedback is technically feasible but substantially increases engineering complexity in streaming inference, latency, and UI reactivity.

Evaluation, accuracy, and validation

FormCoach is an MVP, not a validated clinical device. Still, some evaluation practices are essential for improving and trusting outputs:

Quantitative checks:

• Per-frame keypoint confidence statistics: track percent of frames with low-confidence keypoints and flag problematic recordings automatically.
• Rep segmentation precision: measure correspondence between detected rep counts and human-labeled rep counts on a diverse sample.
• Angle error analysis: compare computed angles from YOLO keypoints to a marker-based motion-capture baseline on a small validation set to estimate systematic bias.

Recommended validation protocol:

1. Collect a labeled dataset of 100–200 short videos across exercises, camera angles, and body types.
2. Manually annotate rep boundaries and key failure modes.
3. Measure rep detection F1, angle RMSE vs ground truth, and flag precision/recall.
4. Calibrate biomechanical thresholds against the annotated set and document sensitivity to anthropometry.

Reporting metrics:

• Rep counting accuracy (precision, recall, F1).
• Angle estimation error (mean absolute error in degrees).
• Flag precision/recall for each biomechanical rule.

These metrics guide which heuristics need adjustment. For instance, if knee-valgus detection has low recall due to hip-keypoint noise, consider integrating temporal smoothing or adding a learned classifier trained on low-confidence patterns.

Limitations, biases, and ethical considerations

The system has explicit and implicit boundaries:

Scope limits:

• Designed for single-person, predominantly side-view recordings.
• Thresholds are heuristic and uncalibrated for body size, limb proportions, or pathology.
• Auto-detection misclassifies similar movement patterns on occasion.
• No live real-time feedback — only batch processing.

Biases and failure modes:

• Pose estimators struggle in low light, heavy occlusion, or with non-standard clothing, skewing angle estimates.
• Training data biases of the underlying pose model can produce systematic errors for certain body shapes, skin tones, or assistive devices.
• The LLM may produce phrasing that oversteps into clinical language unless prompt scaffolding prevents that.

Ethical and legal considerations:

• Videos of people are sensitive. The system must handle privacy responsibly:
  • Provide clear notices that uploads remain local by default for the demo.
  • For deployments, implement optional client-side encryption, minimal retention periods, and deletion capabilities.
  • Avoid storage of personally identifiable information when unnecessary.
• The product should not be presented as a medical device. All outputs should include disclaimers that flags are movement-quality observations, not medical diagnoses.

Mitigations:

• Add a camera-check that warns when recording conditions will likely produce unreliable results.
• Expose per-frame confidence metrics in the UI so users understand when evidence is weak.
• Build a human-in-the-loop workflow for contexts where decisions matter clinically (e.g., remote rehab).

Deployment, scaling, and cost considerations

Local demo vs production:

• Local Docker Compose provides reproducibility and quick launches for demos and developer testing.
• Production deployments require container orchestration (Kubernetes), logging, monitoring, autoscaling, and more robust storage.

Compute options:

• CPU-only execution keeps costs low but yields 60–90 second processing times for short clips.
• Adding GPU inference (NVIDIA with CUDA) reduces pose extraction time dramatically but increases instance cost.
• Consider serverless inference patterns for occasional spikes, or keep a small GPU pool for lower latency.

Storage and retention:

• Session_history.json stores a capped list of recent results for quick progress metrics.
• Full biomechanics outputs and annotated videos can be large; implement S3 or equivalent for persistence with lifecycle rules.

Security:

• Use HTTPS and secure pre-signed URLs for uploads in distributed deployments.
• Protect the OpenAI API key in server-side environments and restrict access to systems that need it.

Cost drivers:

• GPU instances for low latency.
• LLM usage — GPT-4o-mini incurs per-token costs; structure prompts to be succinct and cache repeated coaching templates when possible.
• Storage and egress for large annotated videos.

A deployment-savvy organization will separate inference, orchestration, and storage responsibilities and instrument the stack for per-job cost accounting.

Reproducibility, open-source strategy, and getting started

The project includes a simple get-started sequence:

• git clone repo, copy .env.example to .env, optionally add OPENAI_API_KEY, and docker compose up --build.
• The frontend exposes http://localhost:5173 for uploads and viewing.

For teams planning to fork or extend:

• Keep the processing pipeline modular so that pose extraction, angle computation, rep segmentation, and LLM prompting are separable.
• Add automated tests for each stage, including deterministic synthetic video tests.
• Document the parameters behind smoothing and thresholds in a single config file to make calibration transparent.
• Provide a labeled validation dataset and scripts to compute rep-count and angle-error metrics.

Open-source considerations:

• License the code to permit reuse but state clearly the non-medical nature of outputs.
• Provide small sample videos for integration tests while avoiding publishing videos with real people without explicit consent.

Practical improvements and research directions

Immediate product improvements:

• Anthropometric calibration: ask users for height and limb cues or include a short calibration motion to scale thresholds.
• Multi-view support: allow multi-camera uploads for more robust angle estimation and occlusion handling.
• Per-user model adaptation: track a user’s baseline and adapt thresholds and cues over time.
• Improved auto-detection: add a lightweight learned classifier on top of angle features to disambiguate squat vs lunge and deadlift vs RDL.
• Live feedback mode: stream frames to a light inference server for near-real-time cues during sets.

Longer-term research directions:

• Train a small supervised model to predict flags from temporally-augmented keypoint sequences, improving tolerance to noisy keypoints.
• Fuse inertial measurement data with video for hybrid accuracy in live performance.
• Explore interpretable ML methods to maintain explainability while raising sensitivity to subtle faults.

Each path increases complexity. Prioritize changes that improve trust and reproducibility first: calibration, per-user baselines, and clear confidence reporting.

What FormCoach delivers and where it fits in the ecosystem

FormCoach demonstrates a pragmatic blueprint for applied sports-tech prototypes: integrate a robust pose backbone, use principled signal processing, encode domain heuristics for explainability, and augment with an LLM for human-friendly narrative. That combination yields a product that sits between purely visual overlays and full-motion-capture systems.

Where it fits:

• Useful for recreational athletes and coaches seeking objective, asynchronous feedback.
• Valuable as an educational tool for movement awareness and drill prescription.
• Insufficient for clinical diagnosis or high-precision biomechanical analysis that requires laboratory-grade motion capture.

Compared to commercial motion-capture systems:

• Lower cost and friction — runs on consumer video, no markers required.
• Lower absolute accuracy — marker-based systems remain the gold standard for kinematics.
• Higher accessibility — deployable locally or in lightweight cloud services with modest compute.

Adoption advice:

• Emphasize repeatability in recording: consistent camera placement, lighting, and clothing produce the most reliable results.
• Use the system as a complement to coaching rather than a replacement for in-person assessment in complex cases.

Final operational notes and engineering lessons

Key engineering takeaways from building and running the MVP:

• Avoid persistent tracker state across jobs. Use per-video predict() sessions to prevent cross-job contamination.
• Ensure video codec compatibility. Always transcode annotated outputs to H.264/yuv420p for reliable HTML5 playback.
• Use strict schema enforcement with LLM outputs. Prompt the model for JSON and validate the response before UI rendering.
• Add a camera-check step that returns actionable advice rather than hard blocks — give users agency to proceed when appropriate.
• Document PyTorch and Ultralytics version interactions; weight loading may require patches across library versions.

These operational details make the difference between a brittle demo and a usable product.

FAQ

Q: What exercises does the system support? A: Five primary movements: squat, deadlift, Romanian deadlift (RDL), push-up, and lunge. There is also an auto-detect mode based on heuristic motion patterns, but manual selection improves reliability in ambiguous recordings.

Q: How accurate are the angle estimates and flags? A: Accuracy varies with recording quality, lighting, and camera angle. Angle estimates derive from 17-keypoint COCO-style pose predictions; expect per-joint errors on the order of several degrees under good conditions, larger in poor lighting or occlusion. Flags are rule-based heuristics and should be treated as movement-quality indicators rather than clinical diagnoses. For higher rigor, validate the pipeline on a labeled dataset and calibrate thresholds.

Q: Does the app run in real time? A: The current MVP runs batch processing asynchronously via Celery. On CPU, a typical processing time is 60–90 seconds for short recordings. Adding a GPU reduces inference time substantially; however, live streaming and sub-second feedback are not implemented in this version.

Q: Is a GPU required? A: No. The system runs on CPU, which keeps the demo accessible. A GPU improves pose extraction speed and reduces end-to-end latency.

Q: How safe is my video data? A: The demo is intended for local use through Docker Compose. For production, implement privacy controls: encrypted storage, short retention windows, user-initiated deletion, and clear consent. Avoid uploading sensitive content to shared servers unless privacy and security policies are in place.

Q: What happens if the LLM is unavailable? A: The pipeline includes a deterministic template fallback that generates coaching text from biomechanical outputs, so the product still provides coaching cues even without an OpenAI API key.

Q: Can the system be customized for clinical or specialized sports use? A: Yes, with caveats. Customization requires dataset collection for calibration and possibly retraining or extending rule sets. For clinical deployment, perform formal validation and follow regulatory guidance applicable to medical devices in your jurisdiction.

Q: How does FormCoach compare with motion-capture systems? A: Marker-based motion capture provides higher accuracy and temporal fidelity. FormCoach trades some accuracy for accessibility: it uses consumer video and delivers interpretable, repeatable cues suited to coaching and remote monitoring rather than laboratory-grade kinematic analysis.

Q: Is the code available? A: The project is presented as a reproducible demo with instructions to clone and run locally. Follow the repository README for setup steps. For collaborators, pull requests and issues can be used to iterate on features.

Q: What are the next steps to improve results? A: Prioritize anthropometric calibration, better auto-detection, per-user baselining, and a small labeled validation dataset. These steps increase practical trustworthiness more than switching to a higher-capacity pose model alone.

Q: Can FormCoach handle multi-person videos? A: The MVP is designed for single-person recordings. Multi-person scenarios introduce identity and occlusion complications that require explicit tracking and selection logic. Avoid multi-person footage for reliable results.

Q: Are the biomechanics thresholds fixed? A: Thresholds are heuristic defaults. They should be calibrated to target populations if the system will be used for anything beyond exploratory or coaching purposes.

Q: What should I do if the system reports no person detected? A: Re-record with improved lighting, ensure the full body is in frame from the side, place the camera at hip height roughly 6–10 feet away, and avoid extreme zoom. The camera-check endpoint provides specific tips based on sample frames.

Q: Can I integrate FormCoach into a larger coaching platform? A: The system exposes REST endpoints for uploads, job polling, and streaming annotated outputs, making it straightforward to integrate into existing platforms with proper authentication and storage considerations.

Q: Is the coaching report suitable as a medical recommendation? A: No. Reports provide coaching cues and corrections but are not medical advice. For injury, persistent pain, or rehabilitation, consult a qualified clinician.

If you have further questions about deploying, extending, or validating the pipeline, the codebase includes configuration knobs for smoothing windows, confidence thresholds, and LLM prompt templates to support experimentation and iteration.