praxis/.ciagent/REQUIREMENTS.md

Praxis — Requirements

Milestone: v0.1 (foundation) Status: clarify

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	planned
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	planned
REQ-VOICE-03	End-to-end voice round-trip < 600ms (ASR → LLM → TTS first audio)	must	P1	planned
REQ-VOICE-04	Interruptibility — learner can cut the AI off mid-sentence (abort-and-yield semantics per D-008)	must	P1	planned
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	planned
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	planned

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	planned

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	planned
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	planned
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	planned
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	planned

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	planned

Non-Functional Requirements

REQ-ID	Requirement	Target	Phase	Status
REQ-NFR-LAT-01	End-to-end voice round-trip latency	< 600ms	P1	planned
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)	planned
REQ-NFR-SAFE-01	Domain safety guardrails + disclaimers for safety-sensitive scenarios	baseline for v0.1 (Customer Service lower risk)	P1	planned
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)