praxis/.ciagent/REQUIREMENTS.md

# Praxis — Requirements

**Milestone:** v0.1 (foundation)
**Status:** complete

Formal requirements with REQ-IDs. Scoped to v0.1 unless noted. Later-milestone requirements are marked `deferred`.

## Functional Requirements

### Voice Conversation Engine

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-VOICE-01 | Real-time streaming ASR accepting accented, noisy speech (Canadian English pilot) | must | P1 | complete |
| REQ-VOICE-02 | Streaming TTS with natural prosody, one voice persona (single voice for both mentor and role-play character per D-006) | must | P1 | complete |
| REQ-VOICE-03 | End-to-end voice round-trip < 600ms (ASR → LLM → TTS first audio) | must | P1 | complete |
| REQ-VOICE-04 | Interruptibility — learner can cut the AI off mid-sentence (abort-and-yield semantics per D-008) | must | P1 | complete |
| REQ-VOICE-05 | Multi-language support (10+ launch languages) | later | deferred | deferred |
| REQ-VOICE-06 | Persona switching — same AI becomes customer/colleague/patient/mentor | later | deferred | deferred |

### Scenario Engine

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-SCEN-01 | One branching Customer Service role-play scenario (Canada context): "Angry customer requesting refund on damaged product" with one branch point (escalate vs accept), defined success criteria, common mistakes, and a `failure_mode` field present but not actively provoked in v0.1 (per D-009, D-010) | must | P1 | complete |
| REQ-SCEN-02 | Dynamic difficulty adjustment based on learner performance | later | deferred | deferred |
| REQ-SCEN-03 | Scenario library tagged by skill, difficulty, failure mode | later | deferred | deferred |
| REQ-SCEN-04 | Expert-authored scenario format with AI-generated variations | later | deferred | deferred |

### Mastery & Assessment

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-MAST-01 | Competency rubric per skill | later | deferred | deferred |
| REQ-MAST-02 | Mastery Score updated after each session, requiring varied-scenario success | later | deferred | deferred |
| REQ-MAST-03 | Portable verifiable credentials on mastery | later | deferred | deferred |
| REQ-MAST-04 | No quizzes — assessment built into scenarios | principle | — | accepted |

### Skill Paths

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-PATH-01 | Launch paths: Customer Service, Retail Sales, Hospitality Front Desk, Home Health Aide, Basic English for Work, Auto-Rickshaw/Taxi | later | deferred | deferred |
| REQ-PATH-02 | Path structured as a job (6-week example structure per PRD §6.4) | later | deferred | deferred |

### Live Assist

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-ASSIST-01 | Hands-free voice companion invocable while working | later | deferred | deferred |
| REQ-ASSIST-02 | Context-aware (knows current scenario/skill) | later | deferred | deferred |
| REQ-ASSIST-03 | Guardrails: coaches, does not do the job; never lies to real customers | later | deferred | deferred |

### Low-Bandwidth Surfaces

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-LOWBW-01 | WhatsApp/SMS bot thin entry point (2-min voice-note scenarios) | later | deferred | deferred |
| REQ-LOWBW-02 | USSD fallback for feature phones | later | deferred | deferred |
| REQ-LOWBW-03 | Offline cache for pre-downloaded scenarios and voices | later | deferred | deferred |

### Employer / Program Dashboard

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-DASH-01 | Anonymized cohort view (practice, mastery progression, failure patterns) | later | deferred | deferred |
| REQ-DASH-02 | For training operators and SME HR, not individual learners | later | deferred | deferred |

### Learner State

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-STATE-01 | Single-learner session log with progress and session history (v0.1: local SQLite persistence, no auth, no multi-tenant per D-007) | must | P1 | complete |

### Coaching Debrief

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-DEBRIEF-01 | End-of-session single text+voice summary (not full multi-moment replay) per D-011 | must | P1 | complete |

### LLM Foundation

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-LLM-01 | Ollama-hosted `gemma4:cloud` model callable for edge/fast-path persona responses (via Ollama Cloud direct API per D-020) | must | P1 | complete |
| REQ-LLM-02 | Ollama-hosted `deepseek-v4-flash:cloud` model callable for complex coaching/debrief (no-think mode for latency per D-020) | must | P1 | complete |
| REQ-LLM-03 | Open-weights foundation enabling on-prem option for partners (model-call layer swappable per D-020) | principle | — | accepted |

### Orchestration & Pipeline (research-derived D-017)

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-ORCH-01 | Pipecat server orchestrates ASR→LLM→TTS pipeline with Silero VAD + interruptibility (D-017) | must | P1 | complete |
| REQ-ORCH-02 | Pluggable guardrail layer with Customer Service ruleset (D-019): no legal/financial/medical advice, no real-company impersonation, stay-in-role, session-start disclaimer | must | P1 | complete |

### Scenario Format (research-derived D-018)

| REQ-ID | Requirement | Priority | Phase | Status |
|--------|-------------|----------|-------|--------|
| REQ-SCEN-FMT-01 | YAML DSL scenario definition → Pydantic model → Pipecat Flows consumption (D-018); supports `failure_mode` field (D-009) | must | P1 | complete |

## Non-Functional Requirements

| REQ-ID | Requirement | Target | Phase | Status |
|--------|-------------|--------|-------|--------|
| REQ-NFR-LAT-01 | End-to-end voice round-trip latency | < 600ms | P1 | complete |
| REQ-NFR-COST-01 | Cost per active learner per month | ≤ $3 (target markets; no enforced ceiling in v0.1 Canada pilot per D-012, but architecture must not preclude it). Log actual per-session cost in v0.1. | P1 (logging only) | complete |
| REQ-NFR-SAFE-01 | Domain safety guardrails + disclaimers for safety-sensitive scenarios | baseline for v0.1 (Customer Service lower risk) | P1 | complete |
| REQ-NFR-BW-01 | Usable on 2G/3G bandwidth | target | later | deferred |
| REQ-NFR-DEVICE-01 | Usable on $100 Android phone | target | later | deferred |
| REQ-NFR-AUDIO-01 | Audio-only in v1 (no large video assets) | principle | — | accepted |

## Constraints (binding)

- C-1 Voice is primary interface; text is fallback only
- C-2 Must work on $100 Android phone over 2G/3G (relaxed for v0.1 Canada pilot)
- C-3 Cost ≤ $3/active learner/month (relaxed for v0.1 pilot)
- C-4 Audio-only in v1
- C-5 Open-weights LLM via Ollama catalog — `gemma4:cloud` + `deepseek-v4-flash:cloud`
- C-6 Domain safety guardrails + HITL + disclaimers for safety-sensitive domains
- C-7 Scenarios authored by domain experts + learning designers; AI generates variations only
- C-8 Latency budget < 600ms end-to-end

## Out of Scope (v0.1)

- Mastery scoring, competency rubrics, verifiable credentials
- Multi-language (launch: Canadian English only)
- Employer dashboard
- Live Assist mode
- WhatsApp/SMS/USSD surfaces
- Drill Mode, Review Mode
- Scenario authoring marketplace
- B2B SaaS
- Voice cloning of real individuals
- Early childhood education, medical procedures (permanent per PRD §11.6)