praxis/.ciagent/REQUIREMENTS.md

Praxis — Requirements

Milestone: v0.2 (Proxmox LXC deployment) Status: phase 1 complete — P2 review/ship in-progress (18/20 REQ covered, 2 deferred)

Formal requirements with REQ-IDs. Scoped to the active milestone unless noted. Later-milestone requirements are marked deferred. v0.1 requirements (complete) are retained for reference.

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

Deployment (v0.2 — Proxmox LXC)

REQ-ID	Requirement	Priority	Phase	Status
REQ-DEPLOY-01	Multi-stage Dockerfile: Node stage builds client/dist via npm run build, Python stage runs the Pipecat server and serves client/dist via FastAPI StaticFiles (D-022, D-023)	must	P1	complete
REQ-DEPLOY-02	docker-compose.yml defining the praxis service with volume for SQLite DB (praxis.db), env injection, port mapping (8789), restart policy	must	P1	complete
REQ-DEPLOY-03	Port scripts/proxmox/api.sh from coreci verbatim (PVE REST helpers: pve_curl, pve_poll, pve_nextid, pve_get, pve_env, pve_lxc_env_args)	must	P1	complete
REQ-DEPLOY-04	Port scripts/proxmox/lxc-clone.sh adapted for praxis (hostname=praxis, port 8789, features=nesting=1 for Docker-in-LXC)	must	P1	complete
REQ-DEPLOY-05	Port scripts/proxmox/lxc-config.sh adapted: hookscript snippet, lxc.environment injects GITEA_TOKEN + DEEPGRAM_API_KEY + voice-service env vars (empty if unprovisioned), PRAXIS_PORT=8789	must	P1	complete
REQ-DEPLOY-06	Port scripts/proxmox/firstboot-hook.sh adapted: host-builds Docker image (or loads pre-built), pct exec runs docker compose up -d inside the CT, health-checks /health :8789	must	P1	complete
REQ-DEPLOY-07	Port scripts/proxmox/health-check.sh adapted for praxis: polls http://<bridge-ip>:8789/health (not coreci's /healthz :18080)	must	P1	complete
REQ-DEPLOY-08	Port scripts/proxmox/{lxc-start,rollback,stage-snippet,timing}.sh from coreci (adapted for praxis snippet name)	must	P1	complete
REQ-DEPLOY-09	Port scripts/proxmox/lxc-deploy.sh orchestrator: clone → config → start → health-check → rollback-on-failure, with idempotency (--recreate/--reconfigure)	must	P1	complete
REQ-DEPLOY-10	scripts/install-service.sh adapted: creates praxis user, data/log dirs, env file, systemd unit (praxis.service) that runs docker compose up -d, health-checks /health :8789	must	P1	complete
REQ-DEPLOY-11	scripts/proxmox/praxis.service systemd unit running docker compose up -d with Restart=on-failure	must	P1	complete
REQ-DEPLOY-12	Secret wiring: extend config.json secrets.scopes with proxmox + voice scopes; source PROXMOX_* from ~/coreci/.ciagent/.env.secrets	must	P1	complete
REQ-DEPLOY-13	FastAPI server/__main__.py mounts client/dist as StaticFiles at / (serving the React client from the same port as the API)	must	P1	complete
REQ-DEPLOY-14	.env.example updated with PROXMOX_* + deployment env vars (documented, not secret)	must	P1	complete
REQ-DEPLOY-15	E2E deploy verification: scripts/proxmox/test/ bats tests (mirroring coreci's test structure) + health-check + smoke against live CT	must	P1	complete
REQ-DEPLOY-16	.dockerignore excluding node_modules, .git, __pycache__, .pytest_cache, client/dist (rebuilt in image), .ciagent/.env* (secrets)	must	P1	complete

Non-Functional Requirements (v0.2)

REQ-ID	Requirement	Target	Phase	Status
REQ-NFR-DEPLOY-01	Deploy idempotency — re-running lxc-deploy.sh against a healthy CT is a no-op; unhealthy CT requires explicit --recreate/--reconfigure	must	P1	complete
REQ-NFR-DEPLOY-02	Deploy rollback — any stage failure (clone/config/start/health) triggers rollback.sh (stop + destroy the partial CT)	must	P1	complete
REQ-NFR-DEPLOY-03	First-boot install time	< 5 min (Docker image load + compose up + health)	P1	deferred (live cluster required)
REQ-NFR-DEPLOY-04	Secrets never committed to git (.ciagent/.env* in .gitignore, secrets injected via lxc.environment at runtime)	must	P1	complete

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)