Files

T

Praxis CI 48cbd4a2b3 docs(P00): complete pre-execution phase

---ci---
phase: 0
milestone: v0.1
status: complete
requirements:
  covered: [REQ-VOICE-01, REQ-VOICE-02, REQ-VOICE-03, REQ-VOICE-04, REQ-SCEN-01, REQ-STATE-01, REQ-LLM-01, REQ-LLM-02, REQ-DEBRIEF-01, REQ-ORCH-01, REQ-ORCH-02, REQ-SCEN-FMT-01, REQ-NFR-LAT-01, REQ-NFR-SAFE-01, REQ-NFR-COST-01]
  partial: []
---/ci---

2026-08-01 12:49:34 +00:00

7.3 KiB

Raw Blame History

Praxis — Architecture (Research-Refined)

Status: Research-refined (Phase 0 RESEARCH stage). Informed by .ciagent/RESEARCH.md — web-verified vendor catalogs, GitHub metadata, official docs.

High-Level Topology

Three-tier architecture per PRD §7:

┌──────────────────────────────────────────────────────────┐
│  Client (Android, iOS, Web, WhatsApp, USSD)              │
│  - Voice I/O, cached scenarios, offline scenarios        │
└────────────────┬─────────────────────────────────────────┘
                 │
┌────────────────▼─────────────────────────────────────────┐
│  Edge / Region (per market)                              │
│  - ASR + TTS (low-latency, local accent models)          │
│  - Scenario runtime + role orchestration                 │
│  - Caching layer                                         │
└────────────────┬─────────────────────────────────────────┘
                 │
┌────────────────▼─────────────────────────────────────────┐
│  Core Platform                                           │
│  - LLM tutor (long-context, persona-aware, safety-tuned) │
│  - Scenario Authoring & Tagging                          │
│  - Mastery Rubric Engine                                 │
│  - User state, progress, credentialing                  │
│  - Analytics                                             │
└──────────────────────────────────────────────────────────┘

LLM Foundation (D-003, D-020 — research-verified)

Open-weights models hosted via Ollama Cloud direct API (https://ollama.com/api/chat + OLLAMA_API_KEY) — no local daemon required for v0.1.

Model	Verified status	Role	Context	Mode
`gemma4:cloud`	✅ Real, current (256K ctx, Text+Image, "Low Usage" tier)	Role-play fast path / persona turns	256K	standard
`deepseek-v4-flash:cloud`	✅ Real, current (1M ctx, 284B MoE / 13B active, "Medium Usage" tier)	Coaching debrief + scenario-branch decisions	1M	no-think (latency); think/max-think reserved for offline analysis

Post-pilot cost-reduction path: self-host gemma4:e4b (edge, native audio modality, 9.6GB) on partner hardware for the ≤$3/learner/month target. Architecture must keep the model-call layer swappable (D-020).

Notable future option: gemma4:e2b/e4b support Text+Image+Audio input — potential future Ollama-hosted ASR for cost reduction (not v0.1; dedicated Deepgram is lower-latency + more accent-robust).

v0.1 Component Map (research-refined minimal viable voice loop)

Client: React + WebRTC (Pipecat client SDK)
   │  audio in/out (WebRTC, UDP, sub-50ms)
   ▼
Pipecat server (Python)
   ├─ VAD: Silero
   ├─ STT: Deepgram Nova-3 (cloud, streaming, WebSocket)
   ├─ LLM: Ollama Cloud direct API (https://ollama.com/api/chat)
   │     ├─ gemma4:cloud         (role-play fast path)
   │     └─ deepseek-v4-flash:cloud (debrief, no-think mode)
   ├─ TTS: Cartesia Sonic (cloud, ~120ms)  ← behind interface
   │     └─ fallback: Piper (self-hosted, ~80ms)  ← R4 mitigation
   ├─ Scenario runtime: Pipecat Flows + YAML→Pydantic scenarios
   ├─ Guardrail layer: pluggable interface (v0.1: Customer Service ruleset)
   └─ Learner state: SQLite (praxis.db, single-learner, no auth)

v0.1 deliberately excludes: edge-region split, multi-market deployment, caching layer, scenario authoring tools, mastery engine, credentialing, analytics, WhatsApp/USSD surfaces.

Latency Budget (< 600ms end-to-end — research-revised)

Segment	Budget	Source / note
Client capture + WebRTC uplink	~50ms	WebRTC UDP, Canada region
ASR (Deepgram Nova-3 first partial)	~250ms	Vendor claim; R1: measure in Phase 1
LLM first token (gemma4:cloud direct API)	~200ms	R3: measure in Phase 1
TTS first audio (Cartesia Sonic)	~120ms	Vendor/leaderboard; R2: measure in Phase 1
WebRTC downlink + playback	~50ms
Total (all-cloud target)	~670ms	⚠️ Marginally over 600ms
Total (Piper TTS mitigation)	~550ms	R4: pre-stage Piper self-hosted on pilot server

R4 — single biggest v0.1 technical risk: the all-cloud three-hop path likely lands ~670ms. The TTS service MUST sit behind an interface (D-014) and Piper-on-pilot-server MUST be pre-staged as the likely production v0.1 TTS. This is the first Phase 1 spike.

Critical Risks to Engineer Around

Accent robustness — even a great LLM fails if ASR mishears the learner. Canadian English/French accents, code-switching.
Hallucinated advice in safety-sensitive domains — health, electrical. Domain-specific guardrails, escalation, disclaimers. (v0.1 uses Customer Service path, lower risk, but architecture must support the guardrail layer.)
Cost per learner per month must stay ≤ $3 in target markets. v0.1 Canada pilot relaxes this, but architecture must not bake in assumptions that violate it.
Ollama model availability / cost — :cloud variants imply hosted inference; verify pricing and rate limits at research phase.

Deployment (v0.1)

Single-region pilot (Canada)
LLM via Ollama Cloud direct API (no local daemon)
ASR via Deepgram cloud (North American endpoint)
TTS: Cartesia cloud (quality benchmark) + Piper self-hosted on pilot server (R4 latency mitigation, likely production v0.1)
Pipecat server on single pilot host (Python)
Client: React web app (Pipecat client SDK, WebRTC transport)
SQLite local file (praxis.db) on pilot host

Open Architecture Questions (resolved by research)

Question (from initial ARCHITECTURE.md)	Resolution
Client framework	React + WebRTC via Pipecat client SDK (D-015)
Streaming transport	WebRTC (Pipecat); WebSocket dev fallback (D-016)
ASR/TTS provider	Deepgram Nova-3 (ASR, D-013); Cartesia Sonic + Piper fallback (TTS, D-014)
Learner state store	SQLite confirmed (D-007 → 0.90)
Ollama deployment	Ollama Cloud direct API (D-020)
Scenario definition format	YAML DSL → Pydantic → Pipecat Flows (D-018)

Open Architecture Questions (remaining for PLAN stage)

R1-R4 latency spikes (see Risks below) — first Phase 1 tasks
Pipecat Flows schema mapping for the one branch point (escalate vs accept) in the refund scenario
Guardrail ruleset concrete implementation (D-019) — system-prompt template + output filter
SQLite schema for session log + progress + scenario state
OLLAMA_API_KEY + DEEPGRAM_API_KEY + CARTESIA_API_KEY secret management (extend config.secrets.scopes)

7.3 KiB Raw Blame History