docs/PRD.md

Ergo-Agentic: Product Requirements Document

Overview

Ergo-Agentic is an AI-powered ergonomic assessment backend that analyzes images of office and home-office workstations to produce detailed ergonomic findings, risk assessments, and actionable recommendations.

Users upload one or more images (or video) of their workspace. The system uses multiple AI vision models orchestrated via LangGraph to visually assess ergonomic parameters, identify risks, and generate a comprehensive report.

Problem Statement

Manual ergonomic assessments are expensive, time-consuming, and require trained professionals. Current self-assessment tools rely on users answering questionnaires about their setup, which is subjective and error-prone.

Ergo-Agentic replaces the questionnaire with visual AI analysis — the user simply provides photos of their workspace, and the system objectively assesses their ergonomic setup.

Target Users

• Office workers (corporate and home office)
• Ergonomic consultants conducting remote assessments
• HR/wellness teams managing workplace ergonomics at scale

Input

• Images: One or more photos of the user's workspace (e.g., chair-only shot, desk-and-chair shot, standing-desk shot). Users may upload multiple images without labels — the system determines what each image contains and which parameters can be assessed from it.
• Metadata: Equipment details (chair adjustable/non-adjustable, etc.), user information

Video Support

Video input is a future addition, not in the current scope. When added:

• The system will extract distinct frames from the video
• Each distinct frame will be treated as an image in the pipeline
• The worst observed posture across all frames will be used (same aggregation rule as multiple images)
• A duration/frequency threshold may be added later to avoid over-penalizing transient frames

Output

Primary Output: Outcome Matrix

The core deliverable of the agentic pipeline is the outcome matrix — a structured table of which parameters were assessed, which outcome(s) were selected, and the supporting evidence. This is a machine-readable assessment result that can be consumed by any downstream system.

For each assessed parameter, the matrix contains:

• The final outcome(s) selected
• Whether it's a good habit or a risk
• Evidence summary (which images, which models, reasoning)
• Review decision (confirmed, overridden, or skipped)

Secondary Output: Report JSON (optional, separate concern)

The outcome matrix can be transformed into a full report JSON matching datasources/report-sample.json:

Section	Description
goodHabits	Parameters where the user's setup is optimal
issueBasedReport	Per-issue findings with affected body parts and recommendations
potentialRiskPart	Body-part-centric view aggregating all issues, with worst potential medical condition
actionPlans	Prioritized recommendations with point values
mergedProducts	Product recommendations triggered by detected issues
ergoPostureScore	Composite score (0-100, higher is better)

Report building is a deterministic transformation (JSON lookups, no AI) and can run inside or outside the agentic pipeline.

Assessment Framework

Parameters (12 currently, extensible)

Grouped by equipment area:

Group	Parameters
Chair	Back posture, Seat height, Seat depth, Armrest height
Desk	Sitting desk height, Standing desk height
Keyboard & Mouse	Placement distance from desk edge
Laptop	Distance from user, Screen height
Screen/Monitor	Screen height, Screen distance, Screen arrangement (multi-screen only)

Screen logic (simplified): If the setup has only a monitor, assess monitor. If only a laptop, assess laptop. If mixed, treat monitor as primary screen. For multiple screens, assess arrangement (is person centered on primary?). The agent simply assesses what it sees — mapping to specific outcome key variants happens downstream.

Each parameter has predefined options with:

• A unique option key (e.g., chair-posture-slouching)
• A human-readable description
• A reference image showing the posture/position
• Risk information (risk title, root cause, overall risk description)
• Some options are "good" (empty risk fields), others carry risk

The option key serves as the outcome — the central glue connecting all datasources.

Accessory Detection

The Image Analyzer also detects ergonomic accessories and specialized equipment present in the workspace. This is an open-ended detection — not limited to a fixed list. Examples include:

• Ergonomic supports: footrest, seat cushion, lumbar pillow, wrist rest, monitor riser
• Desk converters: sit-stand converter, standing desk attachment
• Laptop accessories: laptop stand, laptop riser, cooling pad
• Input devices: external keyboard, external mouse, vertical mouse, ergonomic keyboard
• Specialized equipment: Wacom/drawing tablet, document holder/reader
• Other: anti-fatigue mat, desk lamp, headset stand

Detected accessories enrich the assessment metadata and may influence parameter evaluation (e.g., a laptop stand affects laptop height assessment).

Work Locations

The system also detects the type of work environment:

• Home office (dedicated setup)
• Dining table
• Couch
• Bed
• Floor sitting

Body Parts & Medical Conditions

11 body regions are tracked: head, eyes, neck, shoulders, elbows, forearms, wrists, fingers, lower back, knees, feet.

Each body part has progressive conditions at low/medium/high risk levels (e.g., neck: strain -> pain -> cervical spondylosis).

Recommendations

Two recommendation paths based on the issue:

• Self-fixable: adjustable (user can fix with current equipment) and non-adjustable (needs different equipment)
• Others: optimal (ideal correction) and dependency (fix depends on resolving other issues first)

Scoring

• Each parameter has a maximum posture score
• Good habits earn full points; risks reduce the score
• Scores are aggregated and normalized to 0-100
• Higher score = better ergonomic setup

Datasource Files

File	Purpose	Entries
common-assessment-parameters.json	Parameter definitions with options and reference images (the visual rubric)	12 parameters
common-body-parts.json	Body region definitions with medical conditions at each risk level	11 body parts
issue-based-outcomes.json	Per-outcome findings: risk level, posture score, habits, recommendations	68 outcomes
body-based-outcomes.json	Per-outcome body part impacts: affected parts, conditions, body-specific recommendations	65 outcomes

Extensibility

The framework is designed to grow:

• New parameter groups (e.g., lighting, accessories, footrest) can be added to common-assessment-parameters.json
• New outcomes and their mappings are added to the outcome files
• The agent pipeline discovers applicable parameters from the datasources
• New models can be added to the vision agent pool via configuration

Non-Goals (Current Scope)

• Video input (future scope — see Input section)
• Real-time video streaming analysis
• Automatic equipment purchasing
• Integration with HR/workplace management systems
• Mobile app (backend only)

See Also

For detailed implementation specs, see docs/architecture/:

• Domain Model — canonical entities, enums, relationships, open decisions
• Datasource Contracts — schemas, validation rules, migration notes
• Agent Orchestration — LangGraph state, nodes, routing, conflict resolution
• Report Contract — exact output schema, scoring, rendering