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](architecture/domain-model.md) — canonical entities, enums, relationships, open decisions
- [Datasource Contracts](architecture/datasource-contracts.md) — schemas, validation rules, migration notes
- [Agent Orchestration](architecture/agent-orchestration.md) — LangGraph state, nodes, routing, conflict resolution
- [Report Contract](architecture/report-contract.md) — exact output schema, scoring, rendering