Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Praxis CI
|
48cbd4a2b3 |
@@ -0,0 +1,114 @@
|
||||
# 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
|
||||
|
||||
1. **Accent robustness** — even a great LLM fails if ASR mishears the learner. Canadian English/French accents, code-switching.
|
||||
2. **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.)
|
||||
3. **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.
|
||||
4. **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`)
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"phase": 0,
|
||||
"stage": "plan",
|
||||
"milestone": "v0.1",
|
||||
"phase_role": "pre_execution",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-01T00:03:00Z"
|
||||
}
|
||||
@@ -0,0 +1,204 @@
|
||||
# Praxis — v0.1 Foundation Grill (Red-Team Review)
|
||||
|
||||
> **Grill date:** 2026-08-01
|
||||
> **Griller:** CIAgent (adversarial executive review)
|
||||
> **Mode:** mechanical (autonomy `full`, no user interaction)
|
||||
> **Branch:** `phase/00-pre-execution`
|
||||
> **Artifacts reviewed:** PROJECT.md (D-001..D-020), ROADMAP.md, REQUIREMENTS.md, ARCHITECTURE.md, PERSONAS.md, RESEARCH.md (R1-R10), PLAN.md (D-P1-01..06), config.json, CHECKPOINT.json, git log (5 commits)
|
||||
> **Codebase state:** planning artifacts only — no `src/`, `server/`, or `client/` exists yet (expected at Phase 1 EXECUTE)
|
||||
|
||||
---
|
||||
|
||||
## Verdict
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Verdict** | **PROCEED** |
|
||||
| **Confidence** | **0.72** |
|
||||
| **Binding decisions** | 8 (G-001..G-008) |
|
||||
| **Escalations** | 0 (all axes resolved with confidence ≥ 0.60) |
|
||||
| **Challenges posed** | 28 forcing questions across 10 axes; 9 produced material findings |
|
||||
|
||||
**One-line summary:** v0.1 is a genuinely well-prepared foundation milestone with research-grounded, swappable architecture and front-loaded risk spikes. It is **not**, however, what its "pilot" framing implies: it is a tech-validation harness with no real learners, no timeline, no budget, no named sponsor, and all three thesis-defining constraints (2G, $100 phone, $3/learner) explicitly relaxed. The binding decisions below correct the framing and require two concrete refinements before EXECUTE (no-go action definition, recruitment-plan deferral). None block execution.
|
||||
|
||||
---
|
||||
|
||||
## Per-Axis Findings
|
||||
|
||||
### Axis 1 — The Business Case Itself — confidence 0.72
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| What problem does this solve, and is it still top priority? | PROJECT.md L9-15 (voice-first apprenticeship for resource-constrained environments); D-001 overrides PRD's Kenya → Canada | The PRD thesis is "apprenticeship for **resource-constrained** environments on **$100 Android over 2G**." v0.1 relaxes **both** defining constraints (C-2 relaxed per REQUIREMENTS L116, C-3 relaxed per D-012). v0.1 validates the **easy version** of the problem on Canadian cloud infrastructure. The hard version (the actual moat per RESEARCH L279) remains unproven. |
|
||||
| Is the Canada pilot a business case or tech validation? | D-012 (PROJECT L82): "Canada pilot is a foundation/tech-validation milestone, not a unit-economics milestone" | **It is tech validation.** D-012 admits it. This is honest but the surrounding "pilot" language (ROADMAP L33, PLAN L15) oversells it. No market entry is occurring. |
|
||||
| What happens if R4 latency fails 600ms? | ARCHITECTURE L76-78 (Piper mitigation ~550ms); PLAN SLICE-01 "go/no-go gate" | A mitigation path exists (Piper, then self-hosted `gemma4:e4b`). But the go/no-go gate defines no explicit **no-go actions** — see G-003. If both mitigations fail, the project has no documented kill/scope-reduce trigger. |
|
||||
| ROI against counterfactual? | No ROI document exists; success metrics (PROJECT L107-117) are "Year-1 targets, post-v0.1" | No counterfactual. Acceptable for a foundation milestone; would be a blocker for a funded market-entry pilot. |
|
||||
|
||||
**Axis verdict:** Sound **for a foundation milestone**. The business case is tech-validation, honestly admitted in D-012. The risk is that v0.1's success could be misread as thesis validation when it validates only the voice loop. → **G-001**.
|
||||
|
||||
---
|
||||
|
||||
### Axis 2 — Scope and Requirements — confidence 0.78
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Scope expanding, contracting, or stable? | D-002 (v0.1 frozen), D-006..D-012 (7 ambiguities resolved), REQUIREMENTS L124-135 (explicit out-of-scope) | **Stable and frozen.** Out-of-scope is comprehensive (14 items). This is well-handled — rare for a project in flux. |
|
||||
| Is v0.1 SO thin it doesn't validate the thesis? | PLAN L15 (one scenario, one branch, one voice, debrief, no mastery) | v0.1 validates the **daily loop** (speak → AI responds → debrief). It does NOT validate apprenticeship (no mastery gates, no progression, no multi-scenario). Acceptable: the daily loop is the load-bearing wall; mastery is a later floor. |
|
||||
| Does "one branch point" actually prove branching works? | D-010 (PROJECT L80): one branch (escalate vs accept); PLAN TASK-03-06: branch classifier runs **at session end** via LLM-as-judge, **offline from voice loop**; D-P1-05 confirms "offline at session end" | **No.** The "branch" is a **post-hoc outcome label**, not a runtime conversation fork. The conversation is linear; the branch is classified after the fact. Pipecat Flows is wired (TASK-03-03) but the branch does not change the conversation in-flight. The claim "exercises branching" (D-010 rationale) is overstated. |
|
||||
| Hidden requirements disclosed late? | None found — guardrails (D-019), data residency (R10), PIPEDA all surfaced in research | Clean. No hidden regulatory/security requirements lurking. |
|
||||
|
||||
**Axis verdict:** Scope is honest and frozen. The one overstatement is the branching claim. → **G-002**.
|
||||
|
||||
---
|
||||
|
||||
### Axis 3 — Architecture and Technical Feasibility — confidence 0.75
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Has the architecture been validated by builders, not just sellers? | RESEARCH L314 ("Measure, don't assume"); R1-R4 all "measure in Phase 1"; PLAN SLICE-01 is the measurement | Architecture is **research-grounded** (web-verified, not vendor-pitched) but **not yet builder-validated**. SLICE-01 is the validation. Correct sequencing. |
|
||||
| Integration surface — where does cost double? | Three cloud hops (Deepgram + Ollama Cloud + Cartesia) + WebRTC + Pipecat + React SDK + SQLite | Six integration points. Each is a place where latency or cost can surprise. The plan puts all swappable services behind interfaces from SLICE-02 (TASK-02-01..02-03) — correct risk management. |
|
||||
| Is the ~670ms budget real? | ARCHITECTURE L75 (all-cloud ~670ms, **over** 600ms); L76 (Piper ~550ms, 50ms margin); all numbers vendor-claimed, unmeasured | The all-cloud path **fails** the target by 70ms on paper. The Piper mitigation has **50ms margin** — and that's vendor-claimed, not measured. This is genuinely tight. SLICE-01 measures it. The risk is real but correctly front-loaded. |
|
||||
| Is Piper fallback a real mitigation or hand-wave? | D-014 (TTS behind interface, Piper pre-staged); R8 (Piper maintainer gap — OHF seeking maintainers); RESEARCH L135 | **Real but thin.** Piper is a first-class Pipecat TTS service and is fast on CPU. But: (a) 50ms margin is slim, (b) R8 flags a maintainer sustainability risk, (c) Piper prosody is "good but not Cartesia-tier" — quality regression. It's a legitimate mitigation, not a hand-wave, but it trades quality for latency and has a dependency-health caveat. |
|
||||
| Is Pipecat a safe foundation? | D-017 (13.8k★, 11k+ commits, active); R6 (Ollama direct-API integration depth unverified) | **Yes for v0.1.** Active, well-adopted, native integrations for all three services. R6 (unverified Ollama direct-API integration) is a real risk mitigated by SLICE-02 TASK-02-03 (thin adapter if Pipecat's Ollama service rejects custom host+bearer). Long-term: if Pipecat stagnates, Praxis can fork — but that's a future-milestone concern. |
|
||||
| Is Ollama Cloud direct API a SPOF? | D-020 (single vendor, US-hosted); R10 (PIPEDA data residency); R5 (tier throttling) | **Yes.** Single vendor, single region (US), tier-based throttling. Mitigations: swappable LLM interface (D-020), self-host `gemma4:e4b` post-pilot path. For v0.1 single-learner, acceptable. R10 (PIPEDA) is low-medium and unresolved — flagged for monitoring, not blocking. |
|
||||
|
||||
**Axis verdict:** Architecture is the strongest part of this project. Research-grounded, swappable, risk-front-loaded. The 670ms budget is the tightest constraint and has no margin, but SLICE-01 addresses it correctly. The one gap: the go/no-go gate has no defined no-go actions. → **G-003**.
|
||||
|
||||
---
|
||||
|
||||
### Axis 4 — People, Skills, and Organization — confidence 0.70
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Key-person dependency? | PERSONAS.md: 4 active personas; backend-engineer owns majority surface (Pipecat + all service integrations per PERSONAS L145) | **backend-engineer is the critical persona.** It owns Pipecat server, Ollama/Deepgram/Cartesia/Piper adapters, guardrails, scenario runtime. If backend-engineer capacity is constrained, the critical path stalls. This is a concentration risk. |
|
||||
| Resources allocated at claimed percentages? | config.json: max_concurrent_agents 5; PLAN D-P1-04 (SLICE-03 || SLICE-04 parallel in Wave 2) | Parallelism is feasible (5 agent slots, 2 parallel slices in Wave 2). No BAU fire-fighting concern (autonomous project). |
|
||||
| Product owner with authority? | D-001 ("user-directed" Canada override); no named PO | The human "user" makes high-level decisions; the CI orchestrator handles execution prioritization. No named PO for day-to-day. Acceptable for an autonomous CI project but means prioritization is algorithmic, not market-informed. |
|
||||
| Building capability they don't have? | R6 (Pipecat + Ollama direct-API integration unverified); personas have no prior Pipecat track record | **Yes — first Pipecat integration.** Mitigated by SLICE-02 verification task. Acceptable for a foundation milestone (learning-as-you-go is fine for prototypes/tech-validation; the plan treats it as such with early spikes). |
|
||||
|
||||
**Axis verdict:** Thin but appropriate for an autonomous agent project. backend-engineer concentration is the structural risk. No binding decision — noted as a monitoring item.
|
||||
|
||||
---
|
||||
|
||||
### Axis 5 — Timeline and Estimates — confidence 0.65
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Was the deadline set before or after scope? | **No deadline exists anywhere.** ROADMAP.md: phases with no dates. PLAN.md: 5 slices, 3 waves, no duration estimates. | **There is no timeline.** This is itself a grill finding. |
|
||||
| Is missing timeline a blocker? | CHECKPOINT.json (stage: plan); autonomy: full (no external deadline) | For Phase 0 pre-execution in an autonomous CI project with no external deadline, the absence of a calendar timeline is **defensible** — you plan first, estimate later. But Phase 1 EXECUTE has no per-slice effort estimate either, which means no burn-rate tracking is possible. |
|
||||
| Critical path + 3-month push risk? | PLAN §3: SLICE-01 → SLICE-02 → (SLICE-03 ‖ SLICE-04) → SLICE-05 | The single thing that would push by 3+ months: **R4 latency failing even with Piper**, forcing a self-hosted-LLM/edge architecture rethink. SLICE-01 is the de facto time-box on this risk. |
|
||||
| Definition of done? | PLAN §4: 10 explicit Phase 1 exit criteria | **Well-handled.** 10 concrete, testable exit criteria. This compensates partially for the missing timeline — "done" is unambiguous even if "when" is not. |
|
||||
| Estimates evidence-based? | None exist | No estimates at all. The wave structure is a sequencing estimate but not a duration estimate. |
|
||||
|
||||
**Axis verdict:** Missing timeline is a finding but not a blocker for pre-execution. The 10 exit criteria provide a strong definition of done. → **G-004** (add per-slice estimates at EXECUTE).
|
||||
|
||||
---
|
||||
|
||||
### Axis 6 — Budget and Financial Realism — confidence 0.70
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Budget spent vs. remaining? | **No budget exists.** No dollar amount, no token budget, no compute allocation defined anywhere. | There is no budget to track. For an autonomous CI pilot, the "budget" is tokens/compute — and no token budget is defined. |
|
||||
| Predictable cost drivers? | RESEARCH L60 (Ollama tier pricing, not unit-economics-friendly at scale); Deepgram $0.0043/min; Cartesia per-char; WebRTC TURN/STUN if behind NAT | Cost drivers are identified in research but no aggregate estimate exists. The Ollama tier model (Pro $20/Max $100) means pilot cost is plan-tier-based, not per-session — so logged per-session cost (TASK-04-04) will **not** map to at-scale unit economics. |
|
||||
| Is v0.1 measuring things that inform $3/learner? | SLICE-04 TASK-04-04 (per-session cost logging: tokens, minutes, chars, derived cents) | **Yes — the measurement infrastructure is correct.** It logs the right inputs. But the outputs won't be representative: Canada + cloud + Ollama-tier pricing is the **most expensive** configuration, not the $3/learner target configuration (which requires self-hosted `gemma4:e4b` + Piper). |
|
||||
| Burn rate / runway? | No budget → no burn rate → no runway calculation | Ungoverned. Acceptable for a pilot; would be a blocker for a funded delivery. |
|
||||
| Budget contingent on something? | D-004 (monetization deferred to Phase 1); D-012 (no enforced ceiling) | No contingencies — because there's no budget to be contingent. |
|
||||
|
||||
**Axis verdict:** Budget is hand-waved but **honestly so** (D-012 admits it's not a unit-economics milestone). The cost-logging infrastructure is the right v0.1 contribution. The gap: v0.1 logged costs will mislead if read as representative of at-scale economics. → **G-005**.
|
||||
|
||||
---
|
||||
|
||||
### Axis 7 — Risks, Assumptions, and Dependencies — confidence 0.72
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Is R4 actually the biggest risk? | RESEARCH L358 (R4: all-cloud ~670ms); PLAN SLICE-01 go/no-go | R4 is the biggest **technical** risk and is well-handled. But it has a mitigation path (Piper, self-host). The risks below are **less mitigated**. |
|
||||
| Accent robustness on real Canadian speech? | D-013 (Deepgram "accent-robust" — vendor claim); R9 (French-Canadian code-switching, logged as low-risk) | **Unmeasurable in v0.1** — there are no real learners (D-007: hardcoded profile). Deepgram's accent robustness is vendor-claimed, not tested on real Canadian speech. This is arguably a **bigger** risk than R4 because it has no quick fix (retrain or switch ASR) and can't be validated until real learners exist. |
|
||||
| Is the branch point too trivial? | D-010 (one binary branch); TASK-03-06 (post-hoc LLM-as-judge) | The branch is post-hoc, not runtime (see Axis 2). It proves the **data model** (branch field exists) but not the **branching runtime** (conversation forks in-flight). |
|
||||
| LLM hallucinating outside Customer Service role? | D-019 (guardrail ruleset); TASK-03-04 (unit test: "sue them" blocked) | Guardrails are system-prompt + output filter. TASK-03-04 tests one case ("sue them"). **No adversarial/jailbreak test** of the guardrail. For Customer Service (low-risk domain), this is acceptable — but the guardrail layer's pluggability for high-risk domains (health/electrical) is untested under adversarial pressure. |
|
||||
| Top 3 assumptions? | (1) Pipecat integrates with Ollama direct API (R6); (2) Deepgram Nova-3 handles Canadian English (R1/R9); (3) Cartesia/Piper hits latency targets (R2/R4) | All three are "measure in Phase 1" — correctly front-loaded. The **fourth unstated assumption**: that real learners will use this. No evidence. |
|
||||
| Single killing risk? | No recruitment plan; PERSONAS.md is personas, not recruitment | **No real learners.** The entire "pilot" depends on ~50 real Canadian learners (implied by success metrics context) and there is **no recruitment plan, no recruitment channel, no recruitment budget.** v0.1 will produce a dev-harness demo, not a pilot. This is the biggest unflagged risk. |
|
||||
| Pre-mortem (12 months, failed — why?) | Inferred | Most likely causes: (a) R4 can't hit 600ms even with Piper → architecture rethink; (b) voice loop works but debrief is generic → doesn't validate apprenticeship; (c) **no real learners ever use it** — dev demo that never reaches a population. (c) is the most likely. |
|
||||
|
||||
**Axis verdict:** R4 is well-handled. The bigger risks are (1) no real-learner recruitment plan, (2) accent robustness unmeasurable without learners, (3) guardrail not adversarially tested, (4) post-hoc branching. → **G-006**.
|
||||
|
||||
---
|
||||
|
||||
### Axis 8 — Governance, Decision-Making, and Communication — confidence 0.68
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Decision-maker when executives disagree? | D-001 ("user-directed"); no governance body, no named sponsor | The human "user" is the sole decision-maker. No sponsor, no committee. For an autonomous CI project, the orchestrator + user play this role. No disagreement-resolution mechanism exists — but with one decision-maker, none is needed yet. |
|
||||
| Governance cadence / escalation pattern? | config.json escalation_hooks (deploy, delete_data, merge_to_main); escalation_timeout 300s | Escalation hooks exist for **operational** actions (deploy/delete/merge) but **not for project-level risks** (R4 failure, scope drift, recruitment failure). No cadence — the pipeline stages are the cadence. |
|
||||
| Omissions from status reports? | .ciagent artifacts are the status report | Thorough on architecture/requirements/risks. **Omit:** timeline, budget, sponsor, recruitment plan, real-learner validation, no-go actions. These omissions are the grill findings. |
|
||||
| Stop-the-project trigger? | PLAN SLICE-01 "go/no-go gate" — but no-go actions undefined | **No explicit stop trigger.** The SLICE-01 gate is the closest but its no-go branch is a blank. No pre-agreed kill criteria. |
|
||||
|
||||
**Axis verdict:** Governance is minimal — appropriate for an autonomous CI project but with two gaps: no-go actions undefined, no project-level escalation for non-operational risks. → **G-007** (ties to G-003).
|
||||
|
||||
---
|
||||
|
||||
### Axis 9 — Change, Adoption, and Operational Readiness — confidence 0.80
|
||||
|
||||
| Forcing question | Evidence | Finding |
|
||||
|---|---|---|
|
||||
| Who uses v0.1, how does their work change? | D-007 (single hardcoded learner "Alex", no auth); PERSONAS.md (Aspiring Alex persona) | **No real users.** v0.1's "learner" is a hardcoded SQLite row (`learner-1`, "Alex"). No real human will use v0.1. This is a dev harness, not a pilot. |
|
||||
| Plan to get 50 real learners? | **None.** No recruitment plan, no channel, no budget, no timeline for recruitment. PERSONAS.md L103 describes "Aspiring Alex" as a persona, not a recruitment target. | **Missing entirely.** This is the most serious finding. The "pilot" framing (ROADMAP, PLAN) implies learners; the reality (D-007) is a hardcoded profile. |
|
||||
| Ops/support involved now or handed finished product? | No ops team; single pilot host (ARCHITECTURE L88-95) | N/A for a dev harness. No production operations to hand off. Acceptable. |
|
||||
| Rollback plan? | Greenfield — no production system to roll back to | N/A. Acceptable. |
|
||||
| Success criteria validated with judges? | PLAN §1.2 (10 tech exit criteria); no adoption/success criteria validated with learners | Exit criteria are **all technical** (latency, DB rows, guardrail unit tests). **No adoption criteria.** No one has validated that "a learner completes a session" = success with actual learners. |
|
||||
|
||||
**Axis verdict:** v0.1 has no real learners and no plan to get them. It is a tech-validation harness, not a pilot. This is the most serious finding — not because it blocks execution, but because the "pilot" framing is misleading. → **G-008**.
|
||||
|
||||
---
|
||||
|
||||
### Meta — Closing Review — confidence 0.75
|
||||
|
||||
| Forcing question | Finding |
|
||||
|---|---|
|
||||
| **What would the auditor flag?** | (1) No timeline; (2) no budget; (3) no named sponsor; (4) no recruitment plan; (5) "pilot" framing overstated; (6) branching is post-hoc not runtime; (7) go/no-go no-go actions undefined; (8) guardrail not adversarially tested; (9) thesis-critical constraints (C-2, C-3) all deferred. |
|
||||
| **What is the project NOT doing that it should?** | Recruiting real learners. Adversarially testing guardrails. Estimating timeline/budget. Defining no-go actions. Testing debrief quality (not just existence). |
|
||||
| **Simplest 80%-of-value version?** | v0.1 **is** already the simplest version. One scenario, one voice, no mastery. Correctly scoped. The over-scoping risk is low; the under-scoping risk (doesn't validate thesis) is real but acknowledged by design (D-002). |
|
||||
| **What must be true for success in 90 days?** | (a) R4 latency is measurable and has a viable path to <600ms — **likely** (SLICE-01); (b) voice loop works end-to-end — **likely** (SLICE-02); (c) debrief generates **meaningful, non-generic** coaching — **unverified** (no quality test in plan); (d) real learners use it — **false today** (no recruitment plan). (c) and (d) are the gaps. |
|
||||
|
||||
---
|
||||
|
||||
## Binding Decisions
|
||||
|
||||
| ID | Decision | Rationale | Confidence | Alternatives |
|
||||
|----|----------|-----------|------------|--------------|
|
||||
| G-001 | v0.1 is explicitly a **tech-validation milestone**, not market validation. The thesis-critical constraints (C-2: $100 Android/2G, C-3: $3/learner) are **deferred and unmeasured**. v0.1 success must not be reported as product-market-fit or thesis validation. | D-012 admits "tech-validation, not unit-economics"; C-2/C-3 both relaxed per REQUIREMENTS L116-117. v0.1 validates the voice loop on the **least hard** configuration (Canada, cloud, high bandwidth). The moat (low-bandwidth/mobile/B2C-apprentice per RESEARCH L279) is unproven. | 0.78 | Claim thesis validation at v0.1 (false); enforce C-2/C-3 in v0.1 (premature, wrong milestone) |
|
||||
| G-002 | v0.1's branch point is a **post-hoc outcome classification** (LLM-as-judge at session end, offline), **not a runtime conversation fork**. The claim "exercises branching" (D-010 rationale) is overstated. Phase 2+ must validate **true in-flight branching** before claiming the scenario engine works. | PLAN TASK-03-06 + D-P1-05 confirm classifier runs "offline at session end"; conversation is linear; Pipecat Flows is wired but the branch does not change in-flight behavior. | 0.80 | Redefine v0.1 branching as runtime (adds latency + complexity); drop the branch entirely (loses data-model validation) |
|
||||
| G-003 | The SLICE-01 go/no-go gate must define **explicit no-go actions** before EXECUTE: (a) if e2e >600ms with Cartesia but ≤600ms with Piper → swap TTS to Piper (SLICE-02 pre-stage); (b) if e2e >600ms even with Piper → evaluate self-hosted `gemma4:e4b` for LLM hop; (c) if e2e >600ms with both mitigations → **escalate: reduce latency target for v0.1 or rethink architecture**. "Measure and decide" without defined decisions is not a gate. | PLAN L44/L227 call SLICE-01 a "go/no-go gate" but define no no-go branch. ARCHITECTURE L78 says "must be spiked" but not what failure triggers. A gate with no defined failure action is a measurement, not a gate. | 0.75 | Leave no-go undefined (current state — not a real gate); define a hard kill (too aggressive for a foundation milestone) |
|
||||
| G-004 | No calendar timeline is acceptable for v0.1 Phase 0 (pre-execution, autonomous project, no external deadline). Phase 1 EXECUTE should add **per-slice rough effort estimates** (even token-budget-order) to enable burn-rate tracking and parallelism planning. The 10 Phase 1 exit criteria (PLAN §4) compensate for the missing timeline by providing an unambiguous definition of done. | No timeline in any document (ROADMAP, PLAN, CHECKPOINT). Defensible for pre-execution; not defensible for EXECUTE where parallelism (D-P1-04) and burn-rate need sizing. Exit criteria are strong (10 testable items). | 0.65 | Add full Gantt timeline now (premature for autonomous project); proceed with no estimates at EXECUTE (no burn-rate visibility) |
|
||||
| G-005 | v0.1 cost logging (SLICE-04 TASK-04-04) is the correct measurement infrastructure, but **v0.1 logged costs will NOT be representative of at-scale per-learner cost**. Ollama tier-based pricing (Pro/Max plan, not per-token) + Canada cloud + low volume = the most expensive configuration. The $3/learner target requires self-hosted `gemma4:e4b` + Piper (post-pilot path). Cost representativeness must be re-measured in a later milestone with self-hosted models before making unit-economics claims. | RESEARCH L60 ("usage-tier pricing is not unit-economics-friendly at scale"); D-012 (no enforced ceiling); D-020 (self-host e4b is post-pilot path). The logged cost informs the **measurement method**, not the **number**. | 0.72 | Treat v0.1 logged cost as representative (false); enforce $3 ceiling in v0.1 (premature, D-012 rejects) |
|
||||
| G-006 | The single biggest **unflagged** v0.1 risk is the **absence of a real-learner recruitment plan**. v0.1 as scoped will produce a dev-harness demo (hardcoded learner-1 "Alex"), not a pilot with learners. This does not block tech validation (which can proceed without learners) but blocks any "pilot" claim. Accent robustness (R9) and adoption cannot be validated without real learners. Recruitment is deferred to a later milestone. | D-007 (hardcoded profile, no auth); PERSONAS.md (persona roster, not recruitment plan); no recruitment plan/budget/channel in any document. The "pilot" language in ROADMAP/PLAN implies learners; the reality is a dev harness. | 0.80 | Block v0.1 until recruitment plan exists (too conservative for tech validation); claim pilot status at v0.1 (false) |
|
||||
| G-007 | The SLICE-01 go/no-go gate is the de facto **stop-the-project trigger**, but its no-go branch actions are currently undefined (ties to G-003). Additionally, no project-level escalation path exists for non-operational risks (R4 failure, scope drift, recruitment failure) — only operational hooks (deploy/delete/merge per config.json). Define no-go actions per G-003 before EXECUTE. | config.json escalation_hooks cover operational actions only; PLAN L227 gate has no no-go definition; no stop trigger in any document. | 0.70 | Add a governance committee (overhead for autonomous project); proceed with no stop trigger (high-risk by definition) |
|
||||
| G-008 | v0.1 must be explicitly understood as a **tech-validation harness**, not a learner pilot. The "pilot" framing in ROADMAP L33 and PLAN L15 should be read as "tech pilot," not "learner pilot." Real-learner recruitment, adoption validation, and accent robustness on real speech are deferred to a later milestone. This is a framing correction, not a scope change — v0.1's technical scope is correct. | D-007 (pilot harness, not production multi-user); D-012 (tech-validation milestone); G-006 (no recruitment plan). The technical scope (one scenario, one voice, debrief, SQLite) is right; the labeling oversells it. | 0.82 | Relabel as "v0.1 tech-validation" formally (would modify PROJECT/ROADMAP — grill surfaces, doesn't rewrite); proceed with "pilot" framing as-is (misleading) |
|
||||
|
||||
---
|
||||
|
||||
## Escalations
|
||||
|
||||
**None.** All nine axes plus meta resolved with confidence ≥ 0.60. The two findings closest to escalation threshold:
|
||||
|
||||
1. **No-go action definition (G-003/G-007, confidence 0.70-0.75):** resolvable with evidence — the go/no-go gate exists, it just needs its no-go branch specified. Not an escalation; a binding pre-EXECUTE refinement.
|
||||
2. **Real-learner recruitment (G-006/G-008, confidence 0.80):** resolvable with evidence — D-007 and D-012 already admit v0.1 is a tech-validation harness. The binding decision makes the implication explicit and defers recruitment. Not an escalation; a framing correction.
|
||||
|
||||
---
|
||||
|
||||
## Summary of Most Serious Findings
|
||||
|
||||
1. **"Pilot" is a misnomer (G-006, G-008).** v0.1 has no real learners, no recruitment plan, no recruitment budget. It is a tech-validation harness with a hardcoded SQLite row ("Alex"). The technical scope is correct; the framing oversells it. Accent robustness and adoption are unvalidatable without learners.
|
||||
|
||||
2. **All thesis-defining constraints are deferred (G-001).** The Praxis moat is "$100 Android on 2G at $3/learner" (RESEARCH L279). v0.1 relaxes C-2 (2G/device) and C-3 ($3/learner). It validates the voice loop on the **easiest, most expensive** configuration (Canada, cloud, high bandwidth, Ollama tier pricing). v0.1 success must not be reported as thesis validation.
|
||||
|
||||
3. **"Branching scenario" is post-hoc, not runtime (G-002).** The branch is an LLM-as-judge classification at session end, offline from the voice loop. The conversation is linear. The data model (branch field) is validated; the branching runtime is not.
|
||||
|
||||
4. **Go/no-go gate has no no-go actions (G-003, G-007).** SLICE-01 is called a "go/no-go gate" but defines no failure actions. A gate with no defined no-go branch is a measurement, not a gate. Must be specified before EXECUTE.
|
||||
|
||||
5. **No timeline, no budget, no sponsor (G-004, G-005).** Defensible for Phase 0 pre-execution in an autonomous project, but EXECUTE needs per-slice estimates for burn-rate tracking. v0.1 cost logging is methodologically correct but its numbers won't represent at-scale economics (Ollama tier pricing ≠ per-token unit economics).
|
||||
|
||||
**What's done well (to be clear-eyed):** Research grounding (D-013..D-020 are web-verified, not vendor-pitched), swappable interfaces (TTS/LLM/guardrail all behind abstractions from SLICE-02), risk front-loading (SLICE-01 spike before building), explicit out-of-scope (14 items), 10 testable exit criteria, vertical-slice discipline (5 slices, each demoable). This is a well-prepared foundation. The findings above are framing corrections and pre-EXECUTE refinements, not structural rework.
|
||||
|
||||
---
|
||||
|
||||
*End of grill report. Verdict: PROCEED at confidence 0.72. 8 binding decisions (G-001..G-008), 0 escalations. Escalations visible via `ciagent audit`. This grill surfaces findings; it does not rewrite PROJECT.md, ROADMAP.md, or REQUIREMENTS.md. Binding decisions that warrant spec changes must be promoted explicitly by the user (e.g., via `ciagent-clarify` or a follow-up CLARIFY stage).*
|
||||
@@ -0,0 +1,147 @@
|
||||
# Praxis — Persona Assessment
|
||||
|
||||
> **Generated:** Phase 0 RESEARCH stage
|
||||
> **Project:** Praxis (v0.1 foundation)
|
||||
> **Source:** Research findings (`.ciagent/RESEARCH.md`) + config.json personas
|
||||
|
||||
## Persona Roster
|
||||
|
||||
### Active personas (4)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: lead-developer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Coordinates task decomposition across the voice-loop pipeline; resolves conflicts between backend/frontend/data personas. Required for every milestone.
|
||||
domain: coordination
|
||||
frameworks: [pipecat, react]
|
||||
constraints: [pragmatic, latency-budget-aware (<600ms), voice-first-architecture]
|
||||
territory: []
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: backend-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Owns the Pipecat server, Ollama Cloud direct API integration, Deepgram ASR service, guardrail layer, and scenario runtime (Pipecat Flows + YAML→Pydantic). Core of the v0.1 voice loop.
|
||||
domain: backend
|
||||
frameworks: [pipecat, pydantic, ollama, deepgram, cartesia, piper, sqlite]
|
||||
constraints: [api-first, type-safe, latency-budget-aware, streaming-first, pluggable-interfaces-for-swap]
|
||||
territory:
|
||||
- "**/server/**"
|
||||
- "**/pipecat/**"
|
||||
- "**/services/**"
|
||||
- "**/scenarios/**"
|
||||
- "**/guardrails/**"
|
||||
- "**/db/**"
|
||||
- "**/llm/**"
|
||||
- "**/asr/**"
|
||||
- "**/tts/**"
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: frontend-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Owns the React + WebRTC client via Pipecat client SDK — audio capture/playback, interruptibility UI, session display, debrief rendering. Voice-first UI constraints differ from typical web frontend.
|
||||
domain: frontend
|
||||
frameworks: [react, pipecat-client-sdk, webrtc]
|
||||
constraints: [component-first, voice-first-ui, minimal-client-javascript, webRTC-audio-pipeline]
|
||||
territory:
|
||||
- "**/client/**"
|
||||
- "**/ui/**"
|
||||
- "**/components/**"
|
||||
- "**/web/**"
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: data-engineer
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Owns SQLite schema (praxis.db), session-log migrations, scenario YAML→Pydantic schema definitions, and learner-state access layer. v0.1 data surface is small but schema-first discipline is still required.
|
||||
domain: data
|
||||
frameworks: [sqlite, pydantic, pydantic-ai]
|
||||
constraints: [schema-first, type-safe, migration-driven, single-learner-no-auth]
|
||||
territory:
|
||||
- "**/migrations/**"
|
||||
- "**/schema/**"
|
||||
- "**/models/**"
|
||||
- "**/db/**"
|
||||
- "**/scenarios/*.yaml"
|
||||
---
|
||||
```
|
||||
|
||||
### Deactivated personas (0)
|
||||
|
||||
No default personas are deactivated for v0.1. All four default personas have relevant territory.
|
||||
|
||||
### Custom personas (proposed for later milestones — NOT v0.1)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: voice-engineer
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: PROPOSED for v0.2+ when latency tuning, accent modeling, and multi-voice personas become central. v0.1 uses Pipecat's built-in voice pipeline (Silero VAD + Deepgram + Cartesia/Piper), so a dedicated voice-engineer is not warranted yet.
|
||||
domain: voice
|
||||
frameworks: [webrtc, silero-vad, audio-codecs]
|
||||
constraints: [sub-600ms-latency, accent-robustness, audio-quality-vs-latency-tradeoff]
|
||||
territory: []
|
||||
---
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: ml-engineer
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: PROPOSED for v0.3+ when fine-tuning Ollama models on Canadian English / role-play data becomes relevant. v0.1 uses off-the-shelf cloud models — no ML training in scope.
|
||||
domain: ml
|
||||
frameworks: [ollama, pytorch, axolotl]
|
||||
constraints: [open-weights, cost-bounded-fine-tuning]
|
||||
territory: []
|
||||
---
|
||||
```
|
||||
|
||||
## Framework Alignment (overrides from config.json defaults)
|
||||
|
||||
The default config.json personas had empty `frameworks[]`. Research identified the actual v0.1 stack, so frameworks are now populated above:
|
||||
|
||||
| Persona | Frameworks (research-aligned) |
|
||||
|---------|-------------------------------|
|
||||
| lead-developer | pipecat, react |
|
||||
| backend-engineer | pipecat, pydantic, ollama, deepgram, cartesia, piper, sqlite |
|
||||
| frontend-engineer | react, pipecat-client-sdk, webrtc |
|
||||
| data-engineer | sqlite, pydantic, pydantic-ai |
|
||||
|
||||
## Territory Alignment
|
||||
|
||||
Default config.json territory globs were generic (`**/server/**`, `**/client/**`, etc.). Research refined them to match the v0.1 Pipecat-based architecture — see `territory:` fields above. Notable additions:
|
||||
- backend-engineer now owns `**/pipecat/**`, `**/scenarios/**`, `**/guardrails/**`, `**/llm/**`, `**/asr/**`, `**/tts/**` (voice-loop service boundaries)
|
||||
- data-engineer now owns `**/scenarios/*.yaml` (scenario schema authorship)
|
||||
|
||||
## Constraint Alignment
|
||||
|
||||
Default config.json constraints were generic. Research added project-specific constraints:
|
||||
- All personas: `latency-budget-aware (<600ms)` — the binding v0.1 NFR
|
||||
- backend-engineer: `streaming-first`, `pluggable-interfaces-for-swap` (D-014/D-019/D-020 require swappable TTS/LLM/guardrail layers)
|
||||
- frontend-engineer: `voice-first-ui`, `webRTC-audio-pipeline`, `minimal-client-javascript`
|
||||
- data-engineer: `single-learner-no-auth` (D-007)
|
||||
|
||||
## Phase-Specific Personas
|
||||
|
||||
None for v0.1. No personas are created for a specific phase and removed after — the four active personas span the whole milestone. The proposed `voice-engineer` and `ml-engineer` are for later milestones, not phase-specific.
|
||||
|
||||
## Notes for EXECUTE stage
|
||||
|
||||
- Territory enforcement mode: `warn` (per config.json `personas.territory_enforcement`)
|
||||
- The backend-engineer owns the majority of v0.1 task surface (Pipecat server + all service integrations)
|
||||
- The frontend-engineer's surface is smaller but has the R2/R4 latency risk (WebRTC audio pipeline + TTS playback)
|
||||
- The data-engineer's surface is the smallest (one SQLite schema + one YAML scenario) but is on the critical path (scenario definition blocks scenario runtime)
|
||||
@@ -0,0 +1,291 @@
|
||||
# Praxis — Phase 1 Plan (Minimal Viable Voice Loop)
|
||||
|
||||
> **Milestone:** v0.1 (foundation)
|
||||
> **Phase:** 1 — Minimal Viable Voice Loop
|
||||
> **Branch:** `phase/01-minimal-voice-loop` (created at EXECUTE)
|
||||
> **Status:** plan
|
||||
> **Source artifacts:** PROJECT.md (D-001..D-020), REQUIREMENTS.md, ARCHITECTURE.md, RESEARCH.md (R1-R10), PERSONAS.md, ROADMAP.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Phase 1 Summary
|
||||
|
||||
### Goal
|
||||
|
||||
A single learner can open the React web client, speak to an AI tutor playing a Customer Service role-play scenario ("angry customer requesting refund on damaged product", one branch point: escalate vs accept), hear the tutor respond with <600ms end-to-end latency target, receive a single end-of-session text+voice coaching debrief, and have the session logged to SQLite learner state.
|
||||
|
||||
### Scope (in)
|
||||
|
||||
- Streaming voice loop: Deepgram Nova-3 ASR → Ollama Cloud LLM (`gemma4:cloud`) → Cartesia/Piper TTS, orchestrated by Pipecat with Silero VAD
|
||||
- One branching Customer Service scenario (refund, one branch point, `failure_mode` field present)
|
||||
- Interruptibility (abort-and-yield per D-008)
|
||||
- Pluggable guardrail layer with Customer Service ruleset
|
||||
- Single-learner SQLite session log + per-session cost logging
|
||||
- End-of-session text+voice coaching debrief (`deepseek-v4-flash:cloud`, no-think mode)
|
||||
- React + WebRTC client via Pipecat client SDK
|
||||
- R1-R4 latency spike (the single biggest v0.1 technical risk — RESEARCH.md directive)
|
||||
|
||||
### Scope (out — deferred per PROJECT.md)
|
||||
|
||||
- Mastery scoring, competency rubrics, credentials
|
||||
- Multi-language (Canadian English only)
|
||||
- Employer dashboard, Live Assist, WhatsApp/USSD
|
||||
- Multi-learner / auth / multi-tenant
|
||||
- Active failure-injection provocation (hook present, not provoked — D-009)
|
||||
- Multiple personas / voice switching (one voice — D-006)
|
||||
|
||||
### Risks addressed in this plan
|
||||
|
||||
| # | Risk (from RESEARCH.md) | How this plan addresses it |
|
||||
|---|---|---|
|
||||
| R1 | Deepgram first-partial latency from Canada unmeasured | SLICE-01 day-1 probe; SLICE-02 integrated measurement |
|
||||
| R2 | Cartesia first-audio latency unmeasured | SLICE-01 probe; SLICE-02 integrated measurement |
|
||||
| R3 | Ollama Cloud `gemma4:cloud` first-token latency unmeasured | SLICE-01 probe; SLICE-02 integrated measurement |
|
||||
| R4 | All-cloud three-hop path likely ~670ms (over 600ms) | SLICE-01 measures the integrated path; TTS behind interface from SLICE-02; Piper pre-staged as mitigation if R4 confirms. **SLICE-01 is the wave-1 go/no-go gate.** |
|
||||
| R6 | Pipecat + Ollama direct-API integration depth unverified | SLICE-02 task verifies Pipecat Ollama service accepts custom host + bearer; thin adapter if not |
|
||||
| R7 | Scenario branch detection (learner signal classification) | SLICE-03: LLM-as-judge (`deepseek-v4-flash:cloud` no-think) at session end, offline from voice loop |
|
||||
|
||||
### Success criteria (Phase 1 exit)
|
||||
|
||||
1. A learner can complete a full session: open client → hear disclaimer → speak to AI customer → AI responds <600ms (target; logged even if exceeded) → reach a branch outcome → receive text+voice debrief → session logged to SQLite.
|
||||
2. R1-R4 latency report exists with measured (not vendor-claimed) per-segment and end-to-end numbers; a documented TTS decision (Cartesia vs Piper) justified by data.
|
||||
3. All 15 P1 REQ-IDs verified as covered (see §5 coverage matrix).
|
||||
4. Per-session cost is logged (token counts + segment latencies + derived cost).
|
||||
5. Guardrail layer is pluggable (interface + one Customer Service ruleset implementation) and enforces the v0.1 ruleset (disclaimer, no legal/financial/medical advice, stay-in-role).
|
||||
6. Scenario is YAML → Pydantic → Pipecat Flows with `failure_mode` field present.
|
||||
|
||||
---
|
||||
|
||||
## 2. Vertical Slices
|
||||
|
||||
Slices are ordered into 3 waves. Each slice delivers end-to-end value (a demoable behavior), not a horizontal layer. Wave N+1 depends on Wave N output.
|
||||
|
||||
### SLICE-01 — Component & Integrated Latency Spike (R1-R4)
|
||||
|
||||
**Wave:** 1
|
||||
**REQ-IDs covered:** REQ-VOICE-03, REQ-NFR-LAT-01, REQ-LLM-01 (probe), REQ-LLM-02 (probe)
|
||||
**Personas:** lead-developer, backend-engineer
|
||||
**Dependencies:** none (first slice)
|
||||
**Demoable outcome:** A latency report (`docs/latency-report.md` or `reports/latency-spike.md`) with measured per-segment and end-to-end numbers, plus a recorded go/no-go decision on TTS (Cartesia cloud vs Piper self-hosted pre-stage). Running `make latency-spike` (or `python scripts/latency_spike.py`) reproduces the measurements.
|
||||
|
||||
**Rationale:** RESEARCH.md is explicit: "This is the single biggest v0.1 technical risk and must be spiked in Phase 1 week 1." The all-cloud three-hop path likely lands ~670ms. We measure before building the full loop so SLICE-02 can wire the correct TTS from the start.
|
||||
|
||||
**Tasks:**
|
||||
|
||||
| Task ID | Description | Verification |
|
||||
|---------|-------------|--------------|
|
||||
| TASK-01-01 | Create repo skeleton: `server/`, `client/`, `scenarios/`, `db/`, `guardrails/`, `llm/`, `asr/`, `tts/`, `scripts/`, `tests/` dirs; `pyproject.toml` (server) with pipecat, deepgram, cartesia, piper-tts, ollama, pydantic, aiosqlite deps; `.env.example` documenting `DEEPGRAM_API_KEY`, `CARTESIA_API_KEY`, `OLLAMA_API_KEY`, `PIPECAT_*` scopes. | `python -c "import pipecat"` succeeds; dir structure matches PERSONAS.md territory. |
|
||||
| TASK-01-02 | R1 probe: `scripts/probe_deepgram.py` — streaming WebSocket to Deepgram Nova-3, send a sample audio file (or synthesized PCM), measure first-partial-transcript latency from a Canada-region endpoint over 20 iterations; log min/median/p95. | Running the script prints a latency table; results recorded in latency report. |
|
||||
| TASK-01-03 | R2 probe: `scripts/probe_cartesia.py` — WebSocket to Cartesia Sonic, send a sample text chunk, measure first-audio-byte latency over 20 iterations; log min/median/p95. | Running the script prints a latency table; results recorded. |
|
||||
| TASK-01-04 | R3 probe: `scripts/probe_ollama.py` — direct API call to `https://ollama.com/api/chat` with `OLLAMA_API_KEY` bearer, model `gemma4:cloud`, `stream=True`, measure time-to-first-token over 20 iterations; also probe `deepseek-v4-flash:cloud` no-think mode TTFT. Log min/median/p95 + any throttle events (R5). | Running the script prints TTFT tables for both models; results recorded. |
|
||||
| TASK-01-05 | R4 probe: `scripts/probe_e2e.py` — integrated three-hop: feed a sample ASR transcript → Ollama `gemma4:cloud` streaming → Cartesia TTS streaming; measure end-to-end (transcript-in → first-audio-out). Run 10 iterations. Also measure the same path with Piper self-hosted (if Piper can be stood up locally in this task; otherwise note as pending and pre-stage in SLICE-02). | Running the script prints the integrated e2e latency; recorded in report. |
|
||||
| TASK-01-06 | Write `docs/latency-report.md`: per-segment measured latencies (R1-R4), integrated e2e, comparison vs the 600ms budget, and a TTS decision (Cartesia cloud vs Piper pre-stage) with rationale. If e2e >600ms with Cartesia, document Piper as the production v0.1 TTS and note pre-staging work for SLICE-02. | Report file exists with measured numbers (not vendor claims) and a decision block. |
|
||||
|
||||
**Must-have verification criteria:**
|
||||
- [ ] `scripts/probe_deepgram.py`, `probe_cartesia.py`, `probe_ollama.py`, `probe_e2e.py` all run and produce measured latency output.
|
||||
- [ ] `docs/latency-report.md` contains real measured numbers for R1, R2, R3, R4 (not vendor claims).
|
||||
- [ ] Report contains an explicit TTS decision (Cartesia vs Piper) justified by the R4 integrated measurement.
|
||||
- [ ] If R4 integrated path >600ms, Piper pre-staging is documented as a SLICE-02 task.
|
||||
|
||||
---
|
||||
|
||||
### SLICE-02 — Thin Vertical Voice Loop (Walking Skeleton)
|
||||
|
||||
**Wave:** 1
|
||||
**REQ-IDs covered:** REQ-VOICE-01, REQ-VOICE-02, REQ-VOICE-03, REQ-VOICE-04, REQ-ORCH-01, REQ-LLM-01, REQ-NFR-LAT-01
|
||||
**Personas:** lead-developer, backend-engineer, frontend-engineer
|
||||
**Dependencies:** SLICE-01 (uses the TTS decision; latency budget confirmed feasible)
|
||||
**Demoable outcome:** A learner opens a minimal React page, clicks "Start", speaks one utterance, and hears the AI reply over WebRTC — end-to-end voice loop works, latency is displayed. Quality may be poor (hardcoded single-turn scenario, no branching, stub guardrail). This is the walking skeleton that makes latency measurable on the real integrated path.
|
||||
|
||||
**Rationale:** The first integrated slice must be minimal but complete (client → server → ASR → LLM → TTS → client) so we measure real latency, not probe latency. All swappable services (TTS D-014, LLM D-020, guardrail D-019) sit behind interfaces from this first slice so later swaps don't touch the pipeline.
|
||||
|
||||
**Tasks:**
|
||||
|
||||
| Task ID | Description | Verification |
|
||||
|---------|-------------|--------------|
|
||||
| TASK-02-01 | Define service interfaces in `server/services/`: `TTSProvider` (async `synthesize(text) -> audio_stream`, `voice_id`), `LLMProvider` (async `chat(messages, stream=True) -> token_stream`, `model`), `Guardrail` (async `check(text, context) -> verdict`). ABCs/Protocols with type annotations. | `python -c "from server.services import TTSProvider, LLMProvider, Guardrail"` succeeds; interfaces are abstract. |
|
||||
| TASK-02-02 | Implement `CartesiaTTS` and `PiperTTS` adapters behind `TTSProvider`. Pre-stage Piper self-hosted on the pilot server per SLICE-01 decision (install `piper-tts`, download one voice model). TTS selection via env var `PRAXIS_TTS=cartesia|piper`. | Both adapters pass unit tests with a mock stream; `PRAXIS_TTS=piper` selects Piper; `PRAXIS_TTS=cartesia` selects Cartesia. |
|
||||
| TASK-02-03 | Implement `OllamaCloudLLM` adapter behind `LLMProvider` — direct API to `https://ollama.com/api/chat` with bearer auth, `stream=True`, model param. Verify Pipecat's Ollama LLM service accepts custom host + bearer (R6); if not, wrap with this thin adapter so Pipecat consumes it as a generic LLM service. | Adapter unit-tested with a mocked HTTP streaming response; a real call to `gemma4:cloud` returns a first token (confirms R6). |
|
||||
| TASK-02-04 | Build Pipecat server pipeline in `server/pipeline.py`: Silero VAD → Deepgram Nova-3 STT (streaming) → `OllamaCloudLLM` (`gemma4:cloud`) → selected `TTSProvider` → WebRTC output. Wire interruptibility: learner VAD during TTS aborts TTS + yields floor (D-008, Pipecat built-in). Hardcoded single-turn system prompt (no YAML scenario yet). | `python -m server` starts the Pipecat pipeline; a WebSocket/WebRTC connection is accepted; logs show VAD → STT → LLM → TTS frame flow. |
|
||||
| TASK-02-05 | Build minimal React client in `client/` (Vite + React + Pipecat client SDK): one page with "Start session" button, mic permission, WebRTC connect, audio playback, live transcript display (optional), and a latency readout. No branching UI, no debrief. | `npm run dev` serves the client; clicking Start connects WebRTC; speaking produces an AI audio reply in the browser. |
|
||||
| TASK-02-06 | Add an end-to-end latency probe to the pipeline: timestamp at final-transcript-ready, LLM-first-token, TTS-first-audio, client-playback-start; log to console and surface the ASR→TTS-first-audio number to the client for display. | The client displays a latency number after the first turn; logged numbers match `probe_e2e.py` within tolerance. |
|
||||
| TASK-02-07 | Stub guardrail: `NoOpGuardrail` implementing `Guardrail` (always returns allow) so the pipeline has the pluggable hook in place. Real ruleset comes in SLICE-03. | Pipeline calls `guardrail.check()` on each turn; swapping to a real impl requires no pipeline change. |
|
||||
|
||||
**Must-have verification criteria:**
|
||||
- [ ] A learner can click Start, speak one utterance, and hear the AI reply in the browser.
|
||||
- [ ] End-to-end latency (transcript-ready → first-audio) is measured and displayed.
|
||||
- [ ] TTS is selected via env var; both Cartesia and Piper adapters exist behind the `TTSProvider` interface.
|
||||
- [ ] LLM is behind `LLMProvider`; `gemma4:cloud` returns tokens via direct API (R6 resolved).
|
||||
- [ ] Interruptibility works: speaking during AI TTS cuts the AI off (manual test).
|
||||
- [ ] Guardrail slot exists and is swappable without touching the pipeline.
|
||||
|
||||
---
|
||||
|
||||
### SLICE-03 — Branching Scenario + Guardrails + Interruptibility
|
||||
|
||||
**Wave:** 2
|
||||
**REQ-IDs covered:** REQ-SCEN-01, REQ-SCEN-FMT-01, REQ-ORCH-02, REQ-VOICE-04, REQ-NFR-SAFE-01
|
||||
**Personas:** lead-developer, backend-engineer, data-engineer
|
||||
**Dependencies:** SLICE-02 (voice loop + interfaces exist)
|
||||
**Demoable outcome:** The AI plays the "angry customer refund" scenario with a real branch point — the learner's approach either resolves (accept) or escalates — and the session-start disclaimer plays. Guardrails enforce the Customer Service ruleset. The scenario is defined in YAML, loaded via Pydantic, and drives Pipecat Flows.
|
||||
|
||||
**Tasks:**
|
||||
|
||||
| Task ID | Description | Verification |
|
||||
|---------|-------------|--------------|
|
||||
| TASK-03-01 | Define Pydantic scenario schema in `server/scenarios/schema.py`: `Scenario` (id, path, market, language, title, difficulty, failure_mode, persona, setup, success_criteria, common_mistakes, branches[], debrief) matching the RESEARCH.md example. `Branch` has id, trigger.learner_signals, outcome, failure_mode (optional), debrief_focus. Validate at load time. | Unit tests: a valid YAML parses; an invalid YAML raises a typed Pydantic error. |
|
||||
| TASK-03-02 | Author `scenarios/customer_service_refund_ca_v01.yaml` per D-010 and the RESEARCH.md example: "Angry customer requesting refund on damaged product", one branch point (accept_resolution vs escalate), `failure_mode: escalates_unresolved` present, success criteria, common mistakes, debrief config (model `deepseek-v4-flash:cloud`, mode `no_think`). | `python -c "from server.scenarios.loader import load; load('customer_service_refund_ca_v01')"` returns a valid `Scenario` object with both branches. |
|
||||
| TASK-03-03 | Integrate Pipecat Flows: map the scenario branches to a Flows state machine. The system prompt is built from `setup.system_prompt`; opening line from `setup.opening_line` is the first TTS utterance. Branch transition logic is driven by learner-signal classification (TASK-03-06). | Pipeline runs the scenario: AI speaks the opening line, then converses; reaching a branch transitions to the branch outcome. |
|
||||
| TASK-03-04 | Implement `CustomerServiceGuardrail` behind the `Guardrail` interface (D-019): system-prompt constraints (no legal/financial/medical advice, no real-company impersonation, stay-in-role, concise-for-voice), debrief output filter (block recommendations that learner advise legal action), session-start disclaimer audio ("This is an AI practice session for training purposes. It is not a real conversation and no real company is involved."). Wire into pipeline replacing `NoOpGuardrail`. | Unit tests: guardrail flags a "sue them" recommendation; allows a normal coaching line; disclaimer text is defined. Pipeline plays disclaimer as first audio. |
|
||||
| TASK-03-05 | Verify interruptibility on branching turns: learner can cut the AI mid-utterance during any turn (including the opening line and post-branch turns); AI aborts TTS and yields (D-008). Manual + automated test. | Manual test: speaking during AI speech cuts it off; a test script confirms TTS abort event fires on VAD during TTS. |
|
||||
| TASK-03-06 | Implement branch classifier (R7): at session end (or turn boundary), call `deepseek-v4-flash:cloud` in no-think mode as LLM-as-judge to classify learner signals into `accept_resolution` or `escalate` based on the turn transcripts + the scenario's `learner_signals` definitions. Offline from the voice loop (not on the latency-critical path). | A scripted transcript classified as "empathy + concrete_resolution" → accept; "defensive + policy_first" → escalate. |
|
||||
| TASK-03-07 | Replace the hardcoded system prompt from SLICE-02 with the scenario-driven prompt from the loaded YAML. The pipeline now starts a session by loading a named scenario. | Starting a session with scenario `cs_refund_ca_v01` plays the correct opening line and uses the scenario's system prompt. |
|
||||
|
||||
**Must-have verification criteria:**
|
||||
- [ ] Scenario is YAML → Pydantic → Pipecat Flows; `failure_mode` field is present.
|
||||
- [ ] One branch point (accept vs escalate) is reachable and changes the session outcome.
|
||||
- [ ] Session-start disclaimer audio plays as the first AI utterance.
|
||||
- [ ] `CustomerServiceGuardrail` is plugged into the `Guardrail` interface (no pipeline change) and enforces the ruleset (unit-tested).
|
||||
- [ ] Interruptibility works on all turns (manual + automated).
|
||||
- [ ] Branch classifier runs offline (not on the voice latency path) and correctly classifies two scripted transcripts.
|
||||
|
||||
---
|
||||
|
||||
### SLICE-04 — Learner State + Cost Logging
|
||||
|
||||
**Wave:** 2
|
||||
**REQ-IDs covered:** REQ-STATE-01, REQ-NFR-COST-01
|
||||
**Personas:** lead-developer, backend-engineer, data-engineer
|
||||
**Dependencies:** SLICE-02 (loop produces turns to log), SLICE-03 (scenario produces branch outcome to log)
|
||||
**Demoable outcome:** After a session, `praxis.db` contains the session row with branch path and outcome, all turns with ASR/TTS text and per-turn latency, and a derived cost row. `sqlite3 praxis.db "SELECT * FROM sessions"` shows the last session.
|
||||
|
||||
**Tasks:**
|
||||
|
||||
| Task ID | Description | Verification |
|
||||
|---------|-------------|--------------|
|
||||
| TASK-04-01 | Create SQLite schema in `db/schema.sql` + migrations (`db/migrations/0001_init.sql`): `learner(id, display_name, created_at)` with one hardcoded row (`learner-1`, "Alex"); `sessions(id, learner_id, scenario_id, started_at, ended_at, branch_path_json, outcome, cost_estimated_cents)`; `turns(id, session_id, seq, role, asr_text, tts_text, latency_ms, created_at)`; `progress(learner_id, scenario_id, attempts, last_outcome, updated_at)`. Use aiosqlite for async access. | Migration runs; `sqlite3 praxis.db ".schema"` shows all 4 tables; the hardcoded learner row exists. |
|
||||
| TASK-04-02 | Implement `db/store.py` async access layer: `start_session(learner_id, scenario_id)`, `log_turn(session_id, seq, role, asr_text, tts_text, latency_ms)`, `end_session(session_id, branch_path, outcome, cost_cents)`, `update_progress(learner_id, scenario_id, outcome)`. Type-annotated, returns typed objects. | Unit tests with a temp DB: start session → log 3 turns → end session → query returns the full session with turns. |
|
||||
| TASK-04-03 | Wire the store into the Pipecat pipeline: on session start (create row), per turn (log turn with latency), on branch decision (update branch_path), on session end (set outcome + update progress). No auth — `learner_id` is the hardcoded `learner-1`. | After a manual session, `SELECT * FROM sessions` and `SELECT * FROM turns` show the session and its turns. |
|
||||
| TASK-04-04 | Implement cost logging (REQ-NFR-COST-01, D-012): per session, count LLM input/output tokens (gemma4 + deepseek-v4-flash), Deepgram audio minutes, Cartesia/Piper characters; derive an estimated cost in cents using a `cost_rates.yaml` config (no enforced ceiling). Store in `sessions.cost_estimated_cents`. | After a session, `SELECT cost_estimated_cents FROM sessions` returns a non-null number; a `cost_breakdown` is logged (token counts, minutes, chars). |
|
||||
|
||||
**Must-have verification criteria:**
|
||||
- [ ] SQLite `praxis.db` exists with `learner`, `sessions`, `turns`, `progress` tables.
|
||||
- [ ] One hardcoded learner row exists (no auth).
|
||||
- [ ] A completed session produces a `sessions` row + `turns` rows + a `progress` update.
|
||||
- [ ] `cost_estimated_cents` is non-null for a completed session and backed by a logged breakdown.
|
||||
|
||||
---
|
||||
|
||||
### SLICE-05 — Coaching Debrief + Full Client UX
|
||||
|
||||
**Wave:** 3
|
||||
**REQ-IDs covered:** REQ-DEBRIEF-01, REQ-LLM-02, REQ-NFR-SAFE-01 (debrief filter)
|
||||
**Personas:** lead-developer, backend-engineer, frontend-engineer
|
||||
**Dependencies:** SLICE-03 (branch outcome + scenario debrief config), SLICE-04 (session logged with turns)
|
||||
**Demoable outcome:** At session end, the learner sees a text coaching debrief and hears a voice version, both generated from their actual turns + branch outcome + the scenario's `debrief_focus`. The React client shows a polished session flow: start → live turn indicators → interrupt feedback → end debrief view (text + audio playback + latency summary).
|
||||
|
||||
**Tasks:**
|
||||
|
||||
| Task ID | Description | Verification |
|
||||
|---------|-------------|--------------|
|
||||
| TASK-05-01 | Implement debrief generation in `server/debrief.py`: on session end, load the session turns + branch outcome + scenario `debrief.debrief_focus`, call `deepseek-v4-flash:cloud` in no-think mode (per D-020 / scenario config) with the debrief prompt template. Produce a concise text summary (what you did well / what to improve / one next step). | A scripted session (turns + outcome=escalate) produces a debrief text that references the learner's actual turns and the `escalates_unresolved` focus. |
|
||||
| TASK-05-02 | Route the debrief text through `CustomerServiceGuardrail` output filter (block legal-action recommendations, keep focus on learner performance). | Unit test: a debrief containing "tell the customer to sue" is filtered/blocked; a normal coaching debrief passes. |
|
||||
| TASK-05-03 | Synthesize the debrief as voice via the `TTSProvider` (same voice as the role-play per D-006) and stream to the client over the existing WebRTC connection. | At session end, the client receives and plays the debrief audio; the same `TTSProvider` interface is reused (no new TTS path). |
|
||||
| TASK-05-04 | Build the full React client session UX: (a) start screen with scenario title + disclaimer acknowledgement, (b) live session view with turn indicators (learner/AI), interrupt feedback (visual on AI-yield), live latency readout, (c) end-of-session debrief view with debrief text + audio replay + latency/cost summary. Replace the SLICE-02 minimal page. | A full session flows through all three views; the debrief view shows text + an audio playback control + a latency summary. |
|
||||
| TASK-05-05 | Wire debrief persistence: store the debrief text + the branch outcome in the session row (extend `sessions` with `debrief_text` column via migration `0002_debrief.sql`). | After a session, `SELECT debrief_text FROM sessions WHERE id=?` returns the generated debrief. |
|
||||
| TASK-05-06 | End-to-end verification script (`scripts/e2e_smoke.py` or `tests/test_e2e.py`): start session → simulate 2-3 turns → trigger a branch → end session → assert debrief generated, session + turns + cost logged in SQLite, latency < budget (or logged if exceeded). | Running the script passes; it asserts DB rows, debrief non-empty, cost non-null. |
|
||||
|
||||
**Must-have verification criteria:**
|
||||
- [ ] At session end, a text coaching debrief is generated referencing the learner's actual turns and branch outcome.
|
||||
- [ ] The debrief is spoken in the same voice as the role-play (D-006) via the `TTSProvider` interface.
|
||||
- [ ] Debrief text passes the guardrail output filter.
|
||||
- [ ] React client shows a complete session flow: start → live → debrief views.
|
||||
- [ ] `deepseek-v4-flash:cloud` no-think mode is used for the debrief (REQ-LLM-02).
|
||||
- [ ] End-to-end smoke test passes (session → turns → branch → debrief → DB logged).
|
||||
|
||||
---
|
||||
|
||||
## 3. Wave Ordering
|
||||
|
||||
```
|
||||
Wave 1 (foundation + risk spike — must pass before Wave 2)
|
||||
├── SLICE-01 Latency spike (R1-R4) [lead-developer, backend-engineer]
|
||||
└── SLICE-02 Thin vertical voice loop [lead-developer, backend-engineer, frontend-engineer]
|
||||
↑ depends on SLICE-01 TTS decision
|
||||
|
||||
Wave 2 (scenario + state — builds on verified loop)
|
||||
├── SLICE-03 Branching scenario + guardrails [lead-developer, backend-engineer, data-engineer]
|
||||
└── SLICE-04 Learner state + cost logging [lead-developer, backend-engineer, data-engineer]
|
||||
↑ SLICE-03 and SLICE-04 can run in parallel after Wave 1;
|
||||
SLICE-04 wiring benefits from SLICE-03 branch outcome but schema is independent
|
||||
|
||||
Wave 3 (debrief + UX — completes the daily loop)
|
||||
└── SLICE-05 Coaching debrief + full client [lead-developer, backend-engineer, frontend-engineer]
|
||||
↑ depends on SLICE-03 (branch outcome + debrief config) and SLICE-04 (session turns logged)
|
||||
```
|
||||
|
||||
**Wave 1 gate:** SLICE-01 produces the latency report + TTS decision. If R4 confirms e2e >600ms with Cartesia, Piper pre-staging becomes a SLICE-02 task before the loop is wired. Wave 2 does not start until the walking skeleton (SLICE-02) demonstrates a working end-to-end voice turn with measured latency.
|
||||
|
||||
**Wave 2 parallelism:** SLICE-03 (scenario + guardrails) and SLICE-04 (SQLite state) are largely independent — the schema is authored from REQUIREMENTS, not from scenario runtime. They can proceed in parallel; SLICE-04's pipeline wiring consumes SLICE-03's branch outcome, so the final wiring task in SLICE-04 depends on SLICE-03's branch classifier. In practice, start both, merge the wiring last.
|
||||
|
||||
**Wave 3 gate:** SLICE-05 requires both SLICE-03 (branch outcome + debrief config) and SLICE-04 (logged turns) to be verified.
|
||||
|
||||
---
|
||||
|
||||
## 4. Phase 1 Exit Criteria
|
||||
|
||||
All must be true for Phase 1 to ship:
|
||||
|
||||
1. **Full session works end-to-end:** A learner opens the React client, hears the disclaimer, speaks to the AI customer (refund scenario), the AI responds, the conversation reaches a branch outcome (accept or escalate), the learner receives a text+voice coaching debrief, and the session is logged to `praxis.db`.
|
||||
2. **Latency is measured, not assumed:** `docs/latency-report.md` exists with real R1-R4 numbers. End-to-end latency is logged per session (even if >600ms — the target, with Piper mitigation if needed).
|
||||
3. **TTS is behind an interface and swappable:** `PRAXIS_TTS=cartesia|piper` selects the provider with no pipeline change (D-014).
|
||||
4. **LLM is behind an interface and swappable:** `LLMProvider` wraps Ollama Cloud direct API; `gemma4:cloud` (role-play) and `deepseek-v4-flash:cloud` no-think (debrief) both callable (D-020, REQ-LLM-01, REQ-LLM-02).
|
||||
5. **Guardrail layer is pluggable:** `Guardrail` interface + `CustomerServiceGuardrail` implementation; disclaimer plays; ruleset unit-tested (D-019, REQ-NFR-SAFE-01).
|
||||
6. **Scenario is YAML → Pydantic → Pipecat Flows:** `customer_service_refund_ca_v01.yaml` loads, validates, drives the branching runtime, and carries the `failure_mode` field (D-018, REQ-SCEN-FMT-01, REQ-SCEN-01).
|
||||
7. **Interruptibility works:** Learner speech cuts AI TTS mid-utterance; AI yields (D-008, REQ-VOICE-04).
|
||||
8. **Learner state persists:** SQLite has session + turns + progress + cost; single hardcoded learner, no auth (D-007, REQ-STATE-01).
|
||||
9. **Cost is logged per session:** `cost_estimated_cents` non-null with a logged breakdown (REQ-NFR-COST-01, D-012 — no enforced ceiling).
|
||||
10. **End-to-end smoke test passes:** `tests/test_e2e.py` (or `scripts/e2e_smoke.py`) verifies the full loop including DB assertions.
|
||||
|
||||
---
|
||||
|
||||
## 5. REQ Coverage Matrix
|
||||
|
||||
Every P1 must/principle REQ-ID mapped to at least one slice.
|
||||
|
||||
| REQ-ID | Priority | Slice(s) | Covered by task(s) |
|
||||
|--------|----------|----------|--------------------|
|
||||
| REQ-VOICE-01 | must | SLICE-02 | TASK-02-04 (Deepgram Nova-3 streaming ASR in pipeline) |
|
||||
| REQ-VOICE-02 | must | SLICE-02 | TASK-02-02, TASK-02-04 (TTS behind interface, one voice, Cartesia/Piper) |
|
||||
| REQ-VOICE-03 | must | SLICE-01, SLICE-02 | TASK-01-05, TASK-02-06 (measured e2e latency) |
|
||||
| REQ-VOICE-04 | must | SLICE-02, SLICE-03 | TASK-02-04, TASK-03-05 (interruptibility, abort-and-yield) |
|
||||
| REQ-SCEN-01 | must | SLICE-03 | TASK-03-02, TASK-03-03 (refund scenario, one branch, failure_mode) |
|
||||
| REQ-STATE-01 | must | SLICE-04 | TASK-04-01..04-03 (SQLite, single learner, session log) |
|
||||
| REQ-LLM-01 | must | SLICE-01, SLICE-02 | TASK-01-04, TASK-02-03 (gemma4:cloud direct API callable) |
|
||||
| REQ-LLM-02 | must | SLICE-01, SLICE-05 | TASK-01-04, TASK-05-01 (deepseek-v4-flash:cloud no-think for debrief) |
|
||||
| REQ-DEBRIEF-01 | must | SLICE-05 | TASK-05-01..05-03 (end-of-session text+voice summary) |
|
||||
| REQ-ORCH-01 | must | SLICE-02 | TASK-02-04 (Pipecat + Silero VAD + interruptibility) |
|
||||
| REQ-ORCH-02 | must | SLICE-03 | TASK-03-04 (pluggable guardrail + Customer Service ruleset) |
|
||||
| REQ-SCEN-FMT-01 | must | SLICE-03 | TASK-03-01, TASK-03-02 (YAML DSL → Pydantic → Pipecat Flows) |
|
||||
| REQ-NFR-LAT-01 | must | SLICE-01, SLICE-02 | TASK-01-05, TASK-02-06 (<600ms measured + logged) |
|
||||
| REQ-NFR-SAFE-01 | must (baseline) | SLICE-03, SLICE-05 | TASK-03-04, TASK-05-02 (guardrails + disclaimer + debrief filter) |
|
||||
| REQ-NFR-COST-01 | must (logging) | SLICE-04 | TASK-04-04 (per-session cost logged, no enforced ceiling) |
|
||||
|
||||
**Coverage: 15/15 P1 REQ-IDs mapped.** No P1 REQ is uncovered.
|
||||
|
||||
---
|
||||
|
||||
## Planning Decisions
|
||||
|
||||
| ID | Decision | Rationale | Confidence | Alternatives |
|
||||
|----|----------|-----------|------------|--------------|
|
||||
| D-P1-01 | 5 slices across 3 waves | Wave 1 = risk spike + walking skeleton (2 slices); Wave 2 = scenario + state (2 slices, parallelizable); Wave 3 = debrief + UX (1 slice). Balances risk-front-loading with vertical-slice discipline. | 0.85 | 4 slices (merge state into scenario), 6 slices (split client UX from debrief) |
|
||||
| D-P1-02 | SLICE-01 is a standalone probe slice before SLICE-02 | RESEARCH.md mandates R1-R4 be spiked in week 1. Standalone probes are cheaper/faster than building the full loop first, and the TTS decision (R4) informs SLICE-02 wiring. | 0.90 | Fold probes into SLICE-02 (delays the go/no-go; risks building on the wrong TTS) |
|
||||
| D-P1-03 | SLICE-02 is a thin walking skeleton (hardcoded single-turn, no branching) | Measures integrated latency on the real path before investing in scenario runtime. Quality is deliberately poor; completeness over polish. | 0.85 | Build the full branching loop directly (couples latency validation to scenario complexity) |
|
||||
| D-P1-04 | SLICE-03 and SLICE-04 run in parallel in Wave 2 | The SQLite schema is authored from REQUIREMENTS, not from scenario runtime; only the final wiring task depends on the branch classifier. Parallelism shortens Wave 2. | 0.75 | Strict sequence (slower, no benefit) |
|
||||
| D-P1-05 | Branch classifier (R7) uses LLM-as-judge offline at session end | Keeps the latency-critical voice loop free of a second LLM call. `deepseek-v4-flash:cloud` no-think is cheap and fast enough for a one-shot end-of-session classification. | 0.80 | Rule-based classifier (brittle), inline per-turn classifier (adds latency) |
|
||||
| D-P1-06 | Debrief reuses the same `TTSProvider` (one voice, D-006) | D-006 mandates one voice persona for both role-play and mentor. No second TTS config; the debrief is just another TTS utterance via the same interface. | 0.90 | Separate mentor voice (violates D-006, adds config risk) |
|
||||
|
||||
---
|
||||
|
||||
*End of Phase 1 plan. Next step: orchestrator reviews, optionally grills (GRILL stage), then proceeds to EXECUTE on branch `phase/01-minimal-voice-loop`.*
|
||||
@@ -0,0 +1,133 @@
|
||||
# Praxis — Voice-first AI Apprenticeship Platform
|
||||
|
||||
**Milestone:** v0.1 (foundation)
|
||||
**Status:** research
|
||||
**Autonomy:** full
|
||||
|
||||
## Vision
|
||||
|
||||
Praxis is a voice-first, AI-tutored skill platform for learners in resource-constrained environments. Instead of courses, videos, and quizzes, learners practice real job scenarios through real-time spoken conversation with AI tutors. The platform treats every learner as an apprentice to a master craftsperson — open the app, talk, do the job, get better at it.
|
||||
|
||||
**One-line pitch:** Praxis turns every smartphone into a master craftsperson that talks to you, challenges you, and helps you get good at your job.
|
||||
|
||||
## Objective
|
||||
|
||||
Build a voice-first AI apprenticeship platform where learners engage in spoken role-play scenarios with AI tutors, receive coaching debriefs, and progress via mastery gates — working on low-cost phones over constrained bandwidth.
|
||||
|
||||
## v0.1 Scope (Foundation)
|
||||
|
||||
v0.1 establishes the minimal viable voice loop on which all later capabilities build. v1.0 is reserved for a working, tested product; v0.1 is the foundation milestone.
|
||||
|
||||
**v0.1 in scope:**
|
||||
- Phase 0: pre-execution (specify, clarify, research, plan, grill)
|
||||
- Phase 1: minimal viable voice loop — one persona, one branching scenario, ASR + TTS round-trip (<600ms target), single learner state, Ollama-hosted LLM foundation
|
||||
|
||||
**v0.1 out of scope (deferred to later milestones):**
|
||||
- Mastery scoring, competency rubrics, verifiable credentials
|
||||
- Multi-language support (launch: Canadian English; French-Canadian noted for later)
|
||||
- Employer / program dashboard
|
||||
- Live Assist on-the-job companion mode
|
||||
- WhatsApp / SMS bot, USSD fallback
|
||||
- Drill Mode, Review Mode
|
||||
- Open scenario authoring marketplace
|
||||
- B2B SaaS
|
||||
- Voice cloning of real individuals
|
||||
- Early childhood education, medical procedures (permanently out of scope per PRD §11.6)
|
||||
|
||||
## Product Principles (non-negotiable)
|
||||
|
||||
1. **Voice is the primary interface.** Text is fallback, not default.
|
||||
2. **Doing > Knowing.** Every session produces observable action, not passive consumption.
|
||||
3. **One skill, one outcome.** Each path is a job someone can get.
|
||||
4. **Works on a cheap phone, on 2G.** Engineering constraints are product features.
|
||||
5. **The AI is a master, not a chatbot.** Personality, standards, opinions.
|
||||
6. **Mastery gates progression.** Move on when you can do the thing.
|
||||
7. **Failure is the curriculum.** AI provokes mistakes, then coaches recovery.
|
||||
|
||||
## Requirements (summary — see REQUIREMENTS.md for formal REQ-IDs)
|
||||
|
||||
- Voice conversation engine: real-time ASR + streaming TTS, <600ms round-trip, interruptible, persona switching
|
||||
- Scenario engine: branching role-plays with failure-injection and dynamic difficulty (v0.1: one scenario)
|
||||
- Learner state: progress, session history, mastery accumulation (v0.1: single-learner state, no mastery scoring yet)
|
||||
- LLM foundation: Ollama-hosted open-weights models `gemma4:cloud` and `deepseek-v4-flash:cloud`
|
||||
- Low-bandwidth surfaces (later milestones)
|
||||
- Employer dashboard (later milestones)
|
||||
|
||||
## Constraints
|
||||
|
||||
- C-1 Voice is primary interface; text is fallback only
|
||||
- C-2 Must work on $100 Android phone over 2G/3G
|
||||
- C-3 Cost ≤ $3/active learner/month (target markets; v0.1 is Canada launch — relaxed for pilot)
|
||||
- C-4 Audio-only in v1 (no large video assets)
|
||||
- C-5 Open-weights LLM via Ollama catalog — `gemma4:cloud` + `deepseek-v4-flash:cloud`
|
||||
- C-6 Domain safety guardrails + human-in-the-loop + 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 (ASR → LLM → TTS)
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| ID | Decision | Rationale | Confidence | Alternatives |
|
||||
|----|----------|-----------|------------|--------------|
|
||||
| D-001 | Launch market = **Canada** (path: Customer Service) | User-directed; Canada as initial market for v0.1 pilot. PRD named Kenya — overridden. | 0.70 | Kenya + Customer Service (PRD default) |
|
||||
| D-002 | Milestone = **v0.1 foundation** (v1.0 reserved for working/tested product) | User-directed; v0.1 is the foundation slice (Phase 0 + Phase 1 minimal voice loop). v1.0 is a future milestone. | 0.90 | v1.0 = Phase 0 + Phase 1 (too ambitious for first milestone) |
|
||||
| D-003 | LLM foundation = **Ollama catalog** — `gemma4:cloud` + `deepseek-v4-flash:cloud` | User-directed; open-weights via Ollama, two base models for edge/cloud split. Research phase to verify exact catalog IDs. | 0.75 | Llama-family, Mistral-family, Qwen-family |
|
||||
| D-004 | Defer monetization model decision to Phase 1 | PRD §11.5 explicitly lists this as a Phase 1 decision (B2C paid, B2B per-seat, donor-funded, government). | 0.85 | Decide now (insufficient data) |
|
||||
| D-005 | Single-project mode | Fresh repo with one project; no multi-project need. | 1.00 | Multi-project mode |
|
||||
| D-006 | "One persona" = one voice persona; scenario role-play uses the same TTS voice as mentor (no distinct character voice in v0.1) | Minimizes v0.1 surface area; PRD's full persona-switching (REQ-VOICE-06) is deferred. Same voice avoids a second TTS configuration to validate. | 0.70 | Two voices (mentor + character) — adds TTS config risk |
|
||||
| D-007 | "Single learner state" = local single hardcoded profile, no auth, no multi-tenant; persisted via SQLite on-device (or local file fallback) | v0.1 is a pilot harness, not a production multi-user system. Auth/multi-tenant is a later-milestone concern. SQLite chosen as the default local store; research phase may refine. | 0.80 | In-memory only (no persistence), server-side Postgres (premature) |
|
||||
| D-008 | Interruptibility = abort-and-yield (learner speech cuts AI TTS immediately, AI yields the floor, no pause/resume state machine in v0.1) | Matches real-conversation semantics per PRD §6.1; pause/resume adds state-machine complexity inappropriate for v0.1. | 0.75 | Pause/resume state machine |
|
||||
| D-009 | Failure-injection hook = architecturally present (scenario declares a `failure_mode` field) but NOT actively provoked in v0.1 sessions | v0.1 validates the data model and one scenario's success criteria; provoking failures is a coaching-debrief feature tied to mastery (deferred). Hook present so Phase 2+ can activate it without schema change. | 0.70 | Active failure injection in v0.1 (couples to deferred mastery engine) |
|
||||
| D-010 | v0.1 Canada Customer Service scenario = "Angry customer requesting refund on a damaged product" (retail context, single branch point) | Concrete, universally recognizable, low safety-risk (non-medical/non-electrical). One branch point (customer escalates vs accepts resolution) keeps scenario runtime minimal while exercising branching. | 0.65 | "Customer with wrong booking" (hospitality — less universal for Canada pilot) |
|
||||
| D-011 | Coaching debrief = included in v0.1 as a single end-of-session text+voice summary (not the full PRD §5.1 multi-moment replay) | The debrief is part of the core daily loop and cheap to include at a basic level. Full replay/multi-moment coaching is tied to mastery (deferred). | 0.70 | Exclude debrief entirely (loses core loop identity), full replay (over-scoped) |
|
||||
| D-012 | v0.1 cost ceiling = no enforced ceiling (pilot); architecture must not bake in assumptions that would prevent meeting ≤$3/learner/month post-pilot | C-3 is a target-market constraint. Canada pilot is a foundation/tech-validation milestone, not a unit-economics milestone. Logging actual cost per session is a v0.1 NFR to inform later milestones. | 0.85 | Enforce $3 ceiling in v0.1 (premature optimization, wrong market) |
|
||||
| D-013 | ASR = **Deepgram Nova-3** streaming (cloud, WebSocket) | Research-verified: streaming-native, ~200-300ms first partial, accent-robust for Canadian English, first-class Pipecat integration, Canada data-residency available. Fallback: Groq-hosted Whisper. | 0.85 | whisper.cpp (breaks <600ms budget), OpenAI Whisper API (batch) |
|
||||
| D-014 | TTS = **Cartesia Sonic** (cloud, ~120ms first audio) primary; **Piper** (self-hosted, ~80ms) fallback behind interface | Research-verified: Cartesia #1 on Speech Arena; Piper is open-weights post-pilot ≤$3/learner path. R4 risk: all-cloud path ~670ms — Piper local may be required for production v0.1 latency. | 0.80 | ElevenLabs (quality but higher latency/cost), Amazon Polly |
|
||||
| D-015 | Client = **React + WebRTC** via Pipecat client SDK | Research-verified: Pipecat ships React/RN/Swift/Kotlin SDKs; web client = fastest v0.1 iteration, no app-store distribution, upgrades to React Native for Android later. | 0.85 | Python CLI harness (dev-integration only), native Android Kotlin (premature) |
|
||||
| D-016 | Transport = **WebRTC** (UDP, sub-50ms audio); WebSocket dev fallback | Research-verified: WebRTC is Pipecat's production transport; adaptive bitrate, UDP. SSE/HTTP rejected (unidirectional/high overhead). | 0.85 | WebSocket-only (higher audio latency), custom raw HTTP/2 |
|
||||
| D-017 | Orchestration = **Pipecat** (not custom, not Vocode) | Research-verified: 13.8k★, active, integrates Deepgram+Cartesia+Piper+Ollama natively, has VAD/interrupt/Flows for branching. Vocode stale since Nov 2024. Custom orchestration rebuilds solved problems. | 0.85 | Vocode (stale), custom from scratch |
|
||||
| D-018 | Scenario format = **YAML DSL → Pydantic → Pipecat Flows** | Research-verified: YAML is human-authorable + diffable + supports comments (critical for learning-designer rationale per C-7); Pydantic gives typed runtime; Pipecat Flows consumes the schema for branching. JSON is wire format only. | 0.85 | JSON DSL (no comments), code-authored (couples authoring to engineering) |
|
||||
| D-019 | v0.1 guardrail layer = **pluggable interface** with Customer Service ruleset implementation | Research: v0.1 is low-risk (Customer Service) but architecture must support pluggable guardrails for later high-risk domains (health/electrical). Ruleset: no legal/financial/medical advice, no real-company employee impersonation, stay-in-role, session-start disclaimer audio, no PII beyond hardcoded profile. | 0.80 | No guardrails (violates C-6), hardcoded non-pluggable rules (blocks future domains) |
|
||||
| D-020 | LLM access = **Ollama Cloud direct API** (`https://ollama.com/api/chat` + `OLLAMA_API_KEY`) — no local daemon | Research-verified: `:cloud` tags are real Ollama hosted-inference on NVIDIA cloud partners. Direct API eliminates local-daemon deployment dependency. `gemma4:cloud` (256K ctx) → role-play fast path; `deepseek-v4-flash:cloud` (1M ctx, no-think mode) → debrief. Self-host `gemma4:e4b` is the post-pilot cost-reduction path. | 0.85 | Local Ollama daemon proxy mode (adds deployment dependency) |
|
||||
|
||||
### Confidence updates from research
|
||||
|
||||
| ID | Before | After | Reason |
|
||||
|----|--------|-------|--------|
|
||||
| D-003 | 0.75 | **0.95** | Both Ollama model IDs verified in catalog as real, current, cloud-hosted tags |
|
||||
| D-007 | 0.80 | **0.90** | SQLite confirmed appropriate for v0.1 single-learner scale; no evidence favors alternatives |
|
||||
|
||||
## Target Users (v0.1 pilot: Canada)
|
||||
|
||||
| Persona | Description | Pain |
|
||||
|---------|-------------|------|
|
||||
| Aspiring Adebayo → "Aspiring Alex" | 19–28, Canada. Recent secondary school grad. Smartphone, limited data. Wants a service job. | Can't afford vocational school. Needs to actually do the job. |
|
||||
| Upskilling Ursula → "Upskilling Uma" | 25–40, Canada. Retail, hospitality, healthcare. Wants promotion/new role. | No time for courses. Learns on the job. |
|
||||
| Frontline Felix | Customer service / sales / field tech agent, hired recently. | Manager has no time to coach. Wants quick on-shift practice. |
|
||||
|
||||
## Success Metrics (Year-1 targets, post-v0.1)
|
||||
|
||||
| Metric | Target | Why |
|
||||
|--------|--------|-----|
|
||||
| Active weekly learners | 100k | Engagement, not downloads |
|
||||
| Sessions per learner / week | ≥5 | Habit formation |
|
||||
| Mastery rate per path | ≥40% completion | Real learning |
|
||||
| Median session length | 6–10 min | On-the-go use |
|
||||
| Cost / active learner / month | ≤$3 | Sustainable |
|
||||
| Reported job/promotion outcome | ≥25% | North star |
|
||||
| NPS (learner) | ≥50 | Word-of-mouth growth |
|
||||
|
||||
## Open Questions (for research/clarify phases)
|
||||
|
||||
1. Will learners talk to their phone in public? (earbuds + "no one will know" framing)
|
||||
2. How to certify mastery credibly? (employer/agency recognition)
|
||||
3. Domain safety minimum HITL for health/electrical scenarios
|
||||
4. Voice cloning / impersonation disclosure
|
||||
5. Monetization model (deferred to Phase 1)
|
||||
6. Skills that should remain out of scope
|
||||
|
||||
## References
|
||||
|
||||
- PRD v0.1 (this document's source)
|
||||
- ARCHITECTURE.md — system architecture
|
||||
- ROADMAP.md — phase breakdown
|
||||
- REQUIREMENTS.md — formal requirements with REQ-IDs
|
||||
@@ -0,0 +1,135 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,431 @@
|
||||
# Praxis — Research Findings (v0.1 Foundation)
|
||||
|
||||
> **Phase:** 0 (pre-execution / research)
|
||||
> **Branch:** `phase/00-pre-execution`
|
||||
> **Status:** research complete — pending orchestrator review
|
||||
> **Date:** 2026-08-01
|
||||
> **Method:** web-verified vendor catalogs, GitHub repo metadata, and official docs. Where a claim could not be verified online, it is marked with an explicit confidence score.
|
||||
|
||||
This document grounds the v0.1 architecture and Phase 1 plan in ecosystem evidence. It addresses the 10 research scope items and concludes with an architecture diff and a risks/unknowns list for the PLAN stage.
|
||||
|
||||
---
|
||||
|
||||
## Summary of Findings (Executive 1-Pager)
|
||||
|
||||
1. **D-003 VERIFIED — both Ollama model IDs are real and current.** `gemma4:cloud` and `deepseek-v4-flash:cloud` both exist in the Ollama catalog as official cloud-hosted tags. `:cloud` is a real Ollama concept: Ollama-hosted inference on NVIDIA cloud partners (US/Europe/Singapore), callable via a local `ollama run` proxy OR directly at `https://ollama.com/api/chat` with an `OLLAMA_API_KEY`. This is the highest-confidence finding and unblocks the LLM foundation. Raise D-003 confidence from 0.75 → 0.95.
|
||||
|
||||
2. **Recommended ASR: Deepgram Nova-3 streaming (cloud).** Streaming-native, ~300ms partial-transcript latency (sub-200ms for first partial with endpointing), best-in-class accuracy on accented English, Canada data-residency available, pay-as-you-go. Fallback/alternative: Groq-hosted Whisper (lower cost, higher latency) or whisper.cpp self-hosted (zero cost, but breaks the <600ms budget on CPU).
|
||||
|
||||
3. **Recommended TTS: Cartesia Sonic (cloud) primary, Piper (self-hosted) as open-weights fallback.** Cartesia Sonic is #1 on the Artificial Analysis Speech Arena leaderboard, purpose-built for voice agents with state-space-model architecture, ~120ms first-audio, streaming-native. Piper1-gpl is the open-weights self-hosted fallback for the post-pilot ≤$3/learner target. ElevenLabs is the quality benchmark but higher latency/cost.
|
||||
|
||||
4. **Recommended client framework: Web (React + WebRTC) via Pipecat's official client SDK.** Pipecat ships React/React Native/Swift/Kotlin/C++ client SDKs and WebSocket + WebRTC transports. A React + WebRTC web client is the fastest v0.1 iteration path, needs no app-store distribution, and upgrades trivially to React Native for later Android targets. A Python CLI harness is a viable secondary dev-integration test path but not the v0.1 deliverable.
|
||||
|
||||
5. **Recommended streaming transport: WebRTC** for bidirectional audio + control; **WebSocket** as the fallback for token-streaming-only dev mode. WebRTC gives sub-50ms audio transport with UDP, adaptive bitrate, and is the transport Pipecat's production examples use. SSE/raw HTTP are rejected (unidirectional or too high overhead).
|
||||
|
||||
6. **D-007 CONFIRMED: SQLite is the correct v0.1 learner state store.** Single-learner, no auth, no concurrency, schema needs (session log, progress, scenario state) fit SQLite trivially. No evidence favors DuckDB/LiteDB/JSON for this scale. Raise D-007 confidence from 0.80 → 0.90.
|
||||
|
||||
7. **Recommended scenario format: YAML DSL** authored by domain experts (C-7), loaded into a typed Python schema (Pydantic). YAML is human-authorable, diffable in git, supports comments (critical for learning-designer rationale), and parses to the branching model. JSON is the runtime wire format. Code-authored is rejected for v0.1 (couples authoring to engineering).
|
||||
|
||||
8. **Prior art scan:** Second Nature (closest analog — AI role-play sales/support training with coaching debriefs, used by Oracle/Zoom/GoHealth, reduces ramp time 34%), Speak (language learning, voice-first consumer), Cartesia/Retell/Vapi (voice-agent infra, not learning), Duolingo voice features (limited). Key lesson: Second Nature validates the Praxis thesis (role-play + coaching works) but is B2B/enterprise/desktop — Praxis's wedge is mobile-first, voice-primary, low-bandwidth, B2C-apprentice.
|
||||
|
||||
9. **Recommended orchestration: Pipecat.** 13.8k stars, actively maintained (11k+ commits), Python, integrates Deepgram + Cartesia/Piper + Ollama natively, has VAD, interruptibility, "Pipecat Flows" for structured branching conversations, and client SDKs for all target platforms. Vocode is stale (last updated Nov 2024). Custom orchestration is rejected for v0.1 (rebuilds solved problems).
|
||||
|
||||
10. **Safety baseline (v0.1 Customer Service):** Minimal but present. (a) System-prompt guardrails (no legal/financial/medical advice, no impersonation of a real company employee, stay in scenario role), (b) output filter on debrief text, (c) session-start disclaimer audio ("This is an AI practice session"), (d) no PII collection beyond a hardcoded learner profile. The architecture must support a pluggable guardrail layer for later high-risk domains (health/electrical).
|
||||
|
||||
---
|
||||
|
||||
## Ollama Catalog Verification (D-003)
|
||||
|
||||
**Source:** Ollama official library (https://ollama.com/library/gemma4, https://ollama.com/library/deepseek-v4-flash), Ollama Cloud docs (https://docs.ollama.com/cloud), Ollama pricing (https://ollama.com/pricing). Verified 2026-08-01.
|
||||
|
||||
### Finding: Both exact model IDs exist and are current
|
||||
|
||||
| Model ID (as specified in D-003) | Exists? | Status | Context Window | Modalities | Tag details |
|
||||
|---|---|---|---|---|---|
|
||||
| `gemma4:cloud` | ✅ YES | Current (updated ~1 month ago) | 256K | Text, Image | "Low Usage" tier — cloud-hosted, Ollama-managed |
|
||||
| `deepseek-v4-flash:cloud` | ✅ YES | Current (updated 7 hours ago as of fetch) | 1M | Text | "Medium Usage" tier — cloud-hosted, Ollama-managed |
|
||||
|
||||
Additional verified tags available:
|
||||
- `gemma4`: also has `e2b`, `e4b` (edge, with **native audio modality** — CoVoST/FLEURS benchmarks present), `12b`, `26b` (MoE 4B active), `31b` (dense), `31b-cloud`.
|
||||
- `deepseek-v4-flash`: only `cloud` and `0731-cloud` tags (it is a cloud-only release — 284B MoE / 13B active, too large for self-host on pilot hardware).
|
||||
|
||||
### Is `:cloud` a real Ollama concept?
|
||||
|
||||
**Yes.** Per Ollama Cloud docs: `:cloud` tags are models that "run without a powerful GPU" — they are "automatically offloaded to Ollama's cloud service." Ollama collaborates with NVIDIA Cloud Providers (NCPs), hosts primarily in the US with Europe/Singapore routing, and enforces no-logging/no-training/zero-data-retention. Two access modes:
|
||||
1. **Local proxy:** `ollama run gemma4:cloud` — local Ollama daemon forwards to cloud (requires `ollama signin`).
|
||||
2. **Direct API:** `https://ollama.com/api/chat` with `Authorization: Bearer $OLLAMA_API_KEY` — no local Ollama install needed. This is the mode v0.1 should use (server-side, no local daemon dependency).
|
||||
|
||||
### Pricing implications (informs D-012 cost logging)
|
||||
|
||||
Ollama uses a usage-tier model (small/light = level 1 → extra heavy = level 4), not per-token pricing, on Free/Pro($20)/Max($100) plans. `gemma4:cloud` = "Low Usage"; `deepseek-v4-flash:cloud` = "Medium Usage". For a v0.1 Canada pilot (low volume, no enforced ceiling per D-012), a Pro plan likely covers development. **Risk:** usage-tier pricing is not unit-economics-friendly at scale; post-pilot, self-hosting `gemma4:e4b` (edge, audio-capable, 9.6GB) on partner hardware becomes the ≤$3/learner path. Architecture must keep the model-call layer swappable.
|
||||
|
||||
### Native audio modality discovery (notable)
|
||||
|
||||
`gemma4:e2b` and `gemma4:e4b` support **Text, Image, Audio** input (audio encoder ~300M params; CoVoST 35.54, FLEURS 0.08). This means a future architecture could use gemma4 edge models for Ollama-hosted ASR — but for v0.1, dedicated ASR (Deepgram) is lower-latency and more accent-robust. Log this as a future-cost-reduction option.
|
||||
|
||||
### Recommendation
|
||||
|
||||
- **Adopt `gemma4:cloud` and `deepseek-v4-flash:cloud` exactly as specified in D-003.** No rename needed.
|
||||
- **Use direct API mode** (`https://ollama.com/api/chat` + `OLLAMA_API_KEY`) for v0.1 — eliminates the local-Ollama-daemon deployment dependency.
|
||||
- **Map roles:** `gemma4:cloud` (256K ctx, fast) → persona/role-play turns + fast path; `deepseek-v4-flash:cloud` (1M ctx, reasoning modes: no-think/think/max-think) → coaching debrief + scenario-branch decisions. Use **no-think mode** for debrief to keep latency down; reserve think/max-think for offline analysis.
|
||||
- **Confidence update:** D-003 0.75 → **0.95**.
|
||||
|
||||
---
|
||||
|
||||
## ASR Recommendation
|
||||
|
||||
### Options compared
|
||||
|
||||
| Option | Type | Streaming | Accent robustness (Canadian English) | First-partial latency | Cost | v0.1 fit |
|
||||
|---|---|---|---|---|---|---|
|
||||
| **Deepgram Nova-3** | Cloud | Native (WebSocket) | Excellent (trained on diverse English; Canadian English well-covered) | ~200-300ms first partial; endpointing available | Pay-as-you-go (~$0.0043/min streaming) | **Best** |
|
||||
| Groq-hosted Whisper | Cloud | Via Pipecat | Good (Whisper multilingual) | ~300-500ms (batch-ish chunks) | Low (Groq inference cheap) | Good fallback |
|
||||
| whisper.cpp | Self-hosted | Chunked | Good | 500ms+ on CPU (breaks budget) | $0 (self-host) | Reject for <600ms |
|
||||
| OpenAI Whisper API | Cloud | Batch-oriented | Good | 1s+ (not streaming-native) | Per-min | Reject |
|
||||
| AssemblyAI | Cloud | Streaming (WebSocket) | Good | ~300ms | Pay-as-you-go, comparable to Deepgram | Viable alternative |
|
||||
| Mozilla Whisper (local) | Self-hosted | Chunked | Good | Slow on CPU | $0 | Reject for v0.1 |
|
||||
| gemma4:e4b audio (Ollama) | Self/hosted | Research-grade | Unknown for accents | Unknown (not production ASR) | $0 | Future option only |
|
||||
|
||||
### Recommendation: Deepgram Nova-3 streaming (cloud)
|
||||
|
||||
**Rationale:**
|
||||
- **Streaming-native** with WebSocket transport — aligns with the ASR→LLM→TTS streaming pipeline needed for <600ms.
|
||||
- **Accent robustness** — Deepgram is the ASR provider for many voice-agent platforms (Vapi, Retell, Pipecat default) and handles Canadian English (including regionalisms and French-Canadian code-switching) well. Nova-3 is their current flagship.
|
||||
- **Latency** — first partial transcripts in the ~200-300ms band fit the ~120ms ASR budget (partial results can feed LLM context before final transcript).
|
||||
- **Pipecat integration** — Deepgram is a first-class Pipecat STT service with VAD + endpointing configured out of the box.
|
||||
- **Data residency** — Deepgram offers region selection; Canada pilot can use a North American endpoint.
|
||||
- **Cost** — pay-as-you-go, no upfront. For a pilot, cost is negligible; per-D-012, log actuals.
|
||||
|
||||
**Risks/unknowns:**
|
||||
- Exact first-partial latency under Canadian network conditions — **measure in Phase 1 spike**.
|
||||
- French-Canadian accent edge cases — v0.1 is English-only but some learners may code-switch; log misheard turns.
|
||||
|
||||
**Fallback path:** If Deepgram latency or cost is unacceptable post-measurement, swap to Groq Whisper via Pipecat (same interface, lower cost, slightly higher latency) or self-host whisper.cpp on a GPU for the ≤$3/learner milestone.
|
||||
|
||||
---
|
||||
|
||||
## TTS Recommendation
|
||||
|
||||
### Options compared
|
||||
|
||||
| Option | Type | Streaming | First-audio latency | Natural prosody | Cost | v0.1 fit |
|
||||
|---|---|---|---|---|---|---|
|
||||
| **Cartesia Sonic** | Cloud | Native (WebSocket) | ~120ms (state-space model, #1 Speech Arena) | Excellent, purpose-built for agents | Pay-as-you-go | **Best** |
|
||||
| ElevenLabs | Cloud | Native | <500ms (per their FAQ; optimistically ~300ms) | Best-in-class expressiveness | Per-character (higher) | Quality benchmark; viable |
|
||||
| PlayHT | Cloud | Streaming | ~300-400ms | Good | Per-character | Viable alternative |
|
||||
| **Piper1-gpl** | Self-hosted | Chunked/HTTP | <200ms on CPU (fast, local) | Good (neural, not top-tier) | $0 | **Best open-weights fallback** |
|
||||
| Coqui (XTTS) | Self-hosted | Limited | Variable | Good | $0 | Project largely stalled; reject |
|
||||
| Amazon Polly | Cloud | Streaming (PCM) | ~150-250ms | Decent (neural voices) | Per-char | Viable but generic |
|
||||
| Google Cloud TTS | Cloud | Streaming | ~200-300ms | Good | Per-char | Viable alternative |
|
||||
|
||||
### Recommendation: Cartesia Sonic (cloud) primary; Piper1-gpl (self-hosted) fallback
|
||||
|
||||
**Primary — Cartesia Sonic:**
|
||||
- **#1 on Artificial Analysis Speech Arena leaderboard** (verified via cartesia.ai homepage claim; the leaderboard is an independent benchmark). State-space-model architecture is explicitly designed for low-latency streaming.
|
||||
- **~120ms first-audio** fits the TTS budget. Streaming-native so LLM tokens can feed in as they arrive.
|
||||
- **Purpose-built for voice agents** — Cartesia's own product is "Line" voice agents; they dogfood the TTS for exactly the Praxis use case.
|
||||
- **Pipecat integration** — Cartesia is a first-class Pipecat TTS service.
|
||||
- One voice persona (D-006) → one Cartesia voice ID; trivial config.
|
||||
|
||||
**Fallback — Piper1-gpl (open-weights):**
|
||||
- **Open-weights, self-hostable, $0 marginal cost** — the post-pilot ≤$3/learner/month path (C-3).
|
||||
- **Fast on CPU** (Piper is engineered for low-resource devices — used by Home Assistant, NVDA). Sub-200ms first-audio feasible on modest hardware.
|
||||
- **Pipecat integration** — Piper is a first-class Pipecat TTS service.
|
||||
- **Tradeoff:** prosody is good but not Cartesia/ElevenLabs-tier. For v0.1 pilot quality, Cartesia wins; for unit economics later, Piper wins.
|
||||
- **Note:** `piper-tts` (`pip install piper-tts`) is the current package; the old `rhasspy/piper` repo is archived (moved to OHF-Voice/piper1-gpl). The Open Home Foundation is seeking maintainers — minor sustainability risk.
|
||||
|
||||
**Architecture requirement:** The TTS service must be behind an interface so v0.1 (Cartesia) and later (Piper) are swappable without touching the orchestration pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Client Framework Recommendation
|
||||
|
||||
### Options compared
|
||||
|
||||
| Option | Voice I/O | Iteration speed | App-store needed? | Path to $100 Android (C-2) | v0.1 fit |
|
||||
|---|---|---|---|---|---|
|
||||
| **Web (React + WebRTC + Web Audio API)** | ✅ (mic/speaker via browser) | Fastest (hot reload, no build/sign) | No | PWA works; later wrap with React Native/Capacitor | **Best** |
|
||||
| Python CLI harness (sounddevice + websockets) | ✅ (local audio) | Fast (scripting) | No | Not a learner surface | Good for dev integration test, not deliverable |
|
||||
| Minimal Android (Kotlin) | ✅ | Slow (Gradle, emulator, sign) | No (sideload) but heavy | Native path | Over-scoped for v0.1 |
|
||||
| Electron desktop | ✅ | Medium | No | Not mobile | Wrong form factor |
|
||||
|
||||
### Recommendation: Web (React + WebRTC) via Pipecat client SDK
|
||||
|
||||
**Rationale:**
|
||||
- **Pipecat ships a React client SDK** (and React Native, Swift, Kotlin, C++) — using it means the v0.1 client is a thin React app that connects to the Pipecat server over WebRTC. Voice I/O, VAD signaling, and interrupt events are handled by the SDK.
|
||||
- **No app-store distribution** needed for a pilot harness (D-007: single-learner, no auth). A browser URL suffices.
|
||||
- **Fastest iteration** — hot reload, no device flashing, no signing. Critical for Phase 1 latency tuning.
|
||||
- **Upgrade path to mobile** — the same React codebase wraps into React Native (Pipecat has an RN SDK) for the later $100-Android milestone. No throwaway work.
|
||||
- **WebRTC** gives sub-50ms audio transport and is what Pipecat's production examples use.
|
||||
|
||||
**Secondary: Python CLI harness.** Build a minimal `sounddevice` + WebSocket script as a dev-integration test (runs the full loop headless in CI, measures latency). This is a *test tool*, not the v0.1 learner surface.
|
||||
|
||||
---
|
||||
|
||||
## Streaming Transport Recommendation
|
||||
|
||||
### Options compared
|
||||
|
||||
| Transport | Bidirectional audio | LLM token streaming | Latency | Complexity | v0.1 fit |
|
||||
|---|---|---|---|---|---|
|
||||
| **WebRTC** | ✅ (UDP, sub-50ms) | ✅ (data channels) | Lowest | Higher (signaling, STUN/TURN) | **Best** (Pipecat handles this) |
|
||||
| WebSocket | ✅ (TCP, ~50-100ms) | ✅ (native) | Low | Low | Good fallback / dev mode |
|
||||
| SSE | ❌ (server→client only) | ✅ | — | Low | Reject (no upstream audio) |
|
||||
| Raw HTTP/2 streaming | ⚠️ (awkward) | ✅ | Medium | Medium | Reject |
|
||||
|
||||
### Recommendation: WebRTC (primary), WebSocket (dev fallback)
|
||||
|
||||
- **WebRTC** for the v0.1 client↔server audio path. Pipecat's `SmallWebRTCTransport` or Daily/LiveKit transports handle signaling, STUN/TURN, and audio frames. UDP audio = lowest transport latency, critical for the <600ms budget.
|
||||
- **WebSocket** as a dev-mode fallback for the Python CLI harness (no WebRTC signaling complexity in a local test).
|
||||
- The LLM↔orchestrator token stream is internal (Ollama streaming API) and not a transport decision.
|
||||
|
||||
---
|
||||
|
||||
## Learner State Store Confirmation (D-007)
|
||||
|
||||
**Confirmed: SQLite.** No evidence supports switching.
|
||||
|
||||
- **Scale:** single learner, no concurrency, no auth (D-007). SQLite handles this with zero operational overhead.
|
||||
- **Schema needs (v0.1):** session log (turns, timestamps, ASR/TTS text), progress (scenario attempts, success/failure), scenario state (current branch, `failure_mode` field per D-009). Trivial relational fit.
|
||||
- **Deployment:** a single `praxis.db` file on the server (v0.1 is a pilot harness, not on-device per se — the "local" in D-007 means local-to-the-pilot-instance, not on the learner's phone). For a true on-device later milestone, SQLite (via reactive wrappers) remains correct.
|
||||
- **Alternatives rejected:**
|
||||
- DuckDB — analytical OLAP; overkill, no benefit at single-row writes.
|
||||
- Plain JSON — no queryability, no schema enforcement, corruption risk.
|
||||
- LiteDB — .NET ecosystem; Praxis is Python.
|
||||
- Postgres — premature (D-007 explicitly defers server-side multi-tenant).
|
||||
|
||||
**Confidence update:** D-007 0.80 → **0.90**.
|
||||
|
||||
**Recommended v0.1 schema (illustrative, for PLAN to refine):**
|
||||
- `sessions(id, learner_id, scenario_id, started_at, ended_at, branch_path_json, outcome)`
|
||||
- `turns(id, session_id, seq, role, asr_text, tts_text, latency_ms, created_at)`
|
||||
- `progress(learner_id, scenario_id, attempts, last_outcome, updated_at)`
|
||||
- `learner(id, display_name, created_at)` — single hardcoded row for v0.1.
|
||||
|
||||
---
|
||||
|
||||
## Scenario Definition Format
|
||||
|
||||
### Recommendation: YAML DSL → typed Python schema (Pydantic)
|
||||
|
||||
**Rationale:**
|
||||
- **C-7:** scenarios authored by domain experts + learning designers. YAML is human-authorable, supports comments (learning-designer rationale, branch intent), and is git-diffable for review.
|
||||
- **Typed validation:** parse YAML → Pydantic model → fail fast on schema errors at load time.
|
||||
- **Runtime wire format:** JSON (serialized from the Pydantic model).
|
||||
- **Code-authored rejected for v0.1:** couples authoring to engineering; non-engineers can't review/author.
|
||||
- **Pipecat Flows** handles the runtime branching state machine; the YAML feeds it.
|
||||
|
||||
### Example schema (v0.1 — one scenario, one branch point per D-010)
|
||||
|
||||
```yaml
|
||||
# scenarios/customer_service_refund_ca_v01.yaml
|
||||
id: cs_refund_ca_v01
|
||||
path: customer_service
|
||||
market: CA
|
||||
language: en-CA
|
||||
title: "Angry customer requesting refund on a damaged product"
|
||||
difficulty: 1
|
||||
failure_mode: escalates_unresolved # D-009: present, not provoked in v0.1
|
||||
persona:
|
||||
voice_id: "cartesia:some-voice-id" # D-006: same voice as mentor
|
||||
character: "Customer (Jordan)"
|
||||
setup:
|
||||
system_prompt: |
|
||||
You are Jordan, a customer who received a damaged product.
|
||||
You are frustrated but not abusive. You want a refund.
|
||||
Stay in character. Do not break role.
|
||||
opening_line: "Hi, I received my order yesterday and the item is cracked. I want my money back."
|
||||
success_criteria:
|
||||
- "Acknowledged the customer's frustration empathetically"
|
||||
- "Offered a concrete resolution (refund or replacement)"
|
||||
- "Confirmed next steps"
|
||||
common_mistakes:
|
||||
- "Jumping to policy before acknowledging emotion"
|
||||
- "Using jargon ('RMA', 'SLA')"
|
||||
branches:
|
||||
- id: accept_resolution
|
||||
trigger:
|
||||
learner_signals: ["empathy", "concrete_resolution"]
|
||||
outcome: success
|
||||
debrief_focus: "What you did well"
|
||||
- id: escalate
|
||||
trigger:
|
||||
learner_signals: ["defensive", "policy_first"]
|
||||
outcome: failure
|
||||
failure_mode: escalates_unresolved
|
||||
debrief_focus: "The customer escalated because they felt unheard"
|
||||
debrief:
|
||||
model: deepseek-v4-flash:cloud
|
||||
mode: no_think # latency
|
||||
prompt_template: debrief/default
|
||||
```
|
||||
|
||||
This schema carries the `failure_mode` field (D-009), one branch point (D-010), success criteria, common mistakes, and the debrief model config — all v0.1 requirements.
|
||||
|
||||
---
|
||||
|
||||
## Prior Art Scan
|
||||
|
||||
| Platform | What it is | What they got right | What they got wrong / gaps for Praxis |
|
||||
|---|---|---|---|
|
||||
| **Second Nature** (secondnature.ai) | B2B AI role-play training for sales/support/call-center. Used by Oracle, Zoom, GoHealth. | Role-play + coaching-debrief thesis (validated: 34% ramp reduction). Manager insights dashboard. Multi-persona scenarios. Real-time feedback flags mistakes. | Enterprise/desktop/web-chat-first, not voice-primary-mobile. B2B per-seat pricing. Not low-bandwidth. No consumer-apprentice framing. |
|
||||
| **Speak** (speak.com) | Consumer language learning, voice-first. | Voice-primary interface, mobile-first, accent feedback, daily habit. | Language-learning, not job-skill apprenticeship. No role-play scenarios, no mastery gates for job outcomes. |
|
||||
| **Cartesia Line / Retell / Vapi** | Voice-agent infrastructure platforms. | Best-in-class latency/quality stacks; validate that sub-600ms voice loops are production-feasible. | Infrastructure, not learning. No scenarios, no coaching, no mastery. Praxis builds *on top of* this category (or directly on Pipecat). |
|
||||
| **Duolingo voice features** | Limited speech-recognition in a gamified language app. | Habit/engagement mechanics, mobile reach. | Voice is a side feature, not the interface. No conversational role-play. No job outcomes. |
|
||||
| **Gabby / other AI tutor startups** | Various AI tutoring experiments. | Personalization, on-demand. | Most are text-first or video-first; few solve the latency/voice-primary loop well; high churn without job-outcome anchoring. |
|
||||
|
||||
**Lessons for v0.1:**
|
||||
1. **Second Nature validates the Praxis thesis** (role-play + coaching works, enterprises pay) — but Praxis's wedge is the *opposite* market (consumer/mobile/low-bandwidth/B2C-apprentice). Don't copy their enterprise desktop UX.
|
||||
2. **Voice-primary + mobile + low-bandwidth is the defensible moat** — none of the prior art optimizes for a $100 Android phone on 2G/3G (C-2). This is v0.1's architectural north star even though v0.1 itself is a Canada pilot on relaxed constraints.
|
||||
3. **Job-outcome anchoring** (REQ success metric: ≥25% report job/promotion) is what separates Praxis from language apps. The scenario must feel like the job.
|
||||
4. **Coaching debrief is non-negotiable** — Second Nature's real-time feedback and post-session coaching is the engagement/learning engine. D-011 includes it at a basic level; keep it.
|
||||
|
||||
---
|
||||
|
||||
## LLM Orchestration Pattern Recommendation
|
||||
|
||||
### Recommendation: Pipecat pipeline (ASR → LLM → TTS, streaming, with interruptibility)
|
||||
|
||||
**Pattern:**
|
||||
```
|
||||
Client (WebRTC audio)
|
||||
→ Pipecat InputProcessor (VAD: Silero)
|
||||
→ Deepgram STT (streaming partials)
|
||||
→ FrameRouter (partial transcripts prime LLM context; final transcript triggers turn)
|
||||
→ OllamaLLM (gemma4:cloud, stream=True, no local daemon — direct API)
|
||||
→ Cartesia TTS (stream chunks as LLM tokens arrive)
|
||||
→ OutputProcessor → WebRTC audio back to client
|
||||
[Interrupt]: learner VAD fires during TTS → abort TTS + yield floor (D-008)
|
||||
```
|
||||
|
||||
**Why Pipecat (not custom, not Vocode):**
|
||||
- **13.8k stars, 11k+ commits, actively maintained** (verified on GitHub). Vocode's `vocode-core` last updated Nov 2024 — stale.
|
||||
- **Native integrations** for Deepgram (STT), Cartesia/Piper/ElevenLabs (TTS), and **Ollama (LLM)** — all three v0.1 services are first-class. No glue code.
|
||||
- **Built-in VAD** (Silero) and **interruptibility** (abort-and-yield semantics match D-008 out of the box).
|
||||
- **Pipecat Flows** for structured/branching conversations — maps directly to the v0.1 scenario branch point (D-010).
|
||||
- **Client SDKs** (React/RN/Swift/Kotlin) for the WebRTC transport.
|
||||
- **Python** — matches the SQLite + scenario-YAML toolchain.
|
||||
|
||||
**Latency optimization patterns to apply (from Pipecat/Voice-agent ecosystem conventions):**
|
||||
1. **Stream partial ASR → prime LLM** — feed Deepgram partials into Ollama as user-context so the first LLM token fires ~immediately on final transcript.
|
||||
2. **Stream LLM tokens → TTS chunked** — don't wait for the full LLM response; Cartesia/Piper accept incremental text. First-audio fires on first sentence-boundary token.
|
||||
3. **no-think mode for deepseek-v4-flash** during debrief (avoids reasoning latency on the critical path).
|
||||
4. **Short system prompts** for the role-play fast path (gemma4:cloud); long context (256K/1M) is available but not used per-turn for latency.
|
||||
5. **Measure, don't assume** — Phase 1 must include a latency probe (per-segment timing) from day one.
|
||||
|
||||
**Custom orchestration rejected for v0.1** — it would rebuild VAD, streaming frame routing, interruptibility, and transport abstractions that Pipecat already provides. Revisit only if Pipecat proves incompatible with a v0.1 requirement (flag as a risk).
|
||||
|
||||
---
|
||||
|
||||
## Safety Baseline Guardrails (v0.1 Customer Service)
|
||||
|
||||
Customer Service is low-risk per PRD, but v0.1 ships a minimal guardrail layer (C-6, REQ-NFR-SAFE-01) that the architecture extends for later high-risk domains.
|
||||
|
||||
### v0.1 guardrails list (concrete)
|
||||
|
||||
1. **System-prompt constraints** (role-play fast path, `gemma4:cloud`):
|
||||
- "You are role-playing a customer service scenario. Stay in character."
|
||||
- "Do not give legal, financial, or medical advice. If asked, say you cannot and redirect to the scenario."
|
||||
- "Do not impersonate a real employee of any actual company. Use the fictional persona only."
|
||||
- "Do not share personal data about real people."
|
||||
- "Keep responses concise for voice (1-3 sentences)."
|
||||
|
||||
2. **Debrief output filter** (`deepseek-v4-flash:cloud`):
|
||||
- Coaching text must be about the learner's performance, not advice about the customer's legal rights.
|
||||
- Block any recommendation that the learner advise a real customer to take legal action.
|
||||
|
||||
3. **Session-start disclaimer** (TTS audio, first turn):
|
||||
- "This is an AI practice session for training purposes. It is not a real conversation and no real company is involved."
|
||||
|
||||
4. **No PII collection:**
|
||||
- Hardcoded learner profile (D-007). No name/email/phone collected. ASR transcripts are ephemeral-turn-logged but not associated with a real identity.
|
||||
|
||||
5. **Architecture for later extension:**
|
||||
- Guardrail layer must be a pluggable interface (`Guardrail.check(text, context) -> verdict`) so health/electrical domains (later milestones) can inject domain-specific rules without touching the pipeline.
|
||||
- v0.1 ships one implementation: the Customer Service ruleset above.
|
||||
|
||||
6. **No HITL in v0.1** (Customer Service is low-risk; HITL is for safety-sensitive domains per C-6, deferred).
|
||||
|
||||
---
|
||||
|
||||
## Risks & Unknowns Remaining for PLAN Stage
|
||||
|
||||
| # | Risk / Unknown | Severity | Mitigation / PLAN action |
|
||||
|---|---|---|---|
|
||||
| R1 | **Deepgram first-partial latency under Canadian network conditions unmeasured.** Vendor claims ~200-300ms; real-world may differ. | High | Phase 1 day-1 spike: measure Deepgram partial latency from a Canada endpoint. If >300ms, evaluate Groq Whisper fallback. |
|
||||
| R2 | **Cartesia Sonic exact first-audio latency unmeasured.** ~120ms is vendor/leaderboard claim. | High | Phase 1 spike: measure Cartesia first-audio from a sample LLM token stream. If >180ms, evaluate Piper fallback. |
|
||||
| R3 | **Ollama Cloud direct-API latency & rate limits unmeasured.** `gemma4:cloud` first-token latency from `ollama.com/api/chat` is unknown; usage-tier throttling on Pro plan unknown. | High | Phase 1 spike: measure TTFT for `gemma4:cloud` via direct API. If >250ms, consider local-Ollama-daemon mode on a pilot GPU with `gemma4:e4b`. |
|
||||
| R4 | **End-to-end <600ms may be infeasible with all-cloud (ASR+LLM+TTS each cloud-round-trip).** Three cloud hops + WebRTC could exceed 600ms. | High | Budget the three network hops explicitly. If infeasible, move one component self-hosted (likely TTS→Piper on the pilot server, or LLM→local `gemma4:e4b`). |
|
||||
| R5 | **`gemma4:cloud` "Low Usage" tier may throttle under concurrent pilot sessions.** | Medium | v0.1 is single-learner; low risk. Log throttling events. For multi-learner, revisit plan tier. |
|
||||
| R6 | **Pipecat + Ollama direct-API integration depth unverified.** Pipecat has an Ollama LLM service, but whether it supports the `https://ollama.com` direct host + bearer token cleanly needs a code check. | Medium | Phase 1 task: verify Pipecat Ollama service accepts custom host + auth headers; if not, wrap with a thin adapter. |
|
||||
| R7 | **Scenario branch detection (how to classify learner signals into accept/escalate).** The YAML schema declares `learner_signals` but the classifier is unspecified. | Medium | v0.1: use an LLM-as-judge call (`deepseek-v4-flash:cloud` no-think) at turn boundaries to classify signals. Keep it offline from the voice loop (runs between turns or at session end). |
|
||||
| R8 | **Piper1-gpl maintainer gap.** Open Home Foundation is seeking maintainers. | Low (v0.1 uses Cartesia) | Monitor; if Piper stagnates, evaluate Kokoro (also in Pipecat) for the open-weights fallback. |
|
||||
| R9 | **French-Canadian accent/code-switching in v0.1 English pilot.** | Low (v0.1 English-only) | Log misheard turns; inform the later multilingual milestone (REQ-VOICE-05). |
|
||||
| R10 | **Ollama Cloud data residency.** Hosted primarily US; Europe/Singapore routing possible. Canada pilot may raise PIPEDA considerations. | Low-Medium | Confirm Ollama's zero-data-retention policy covers pilot needs; if Canada data-residency is required, consider self-hosted `gemma4:e4b` + Piper for an all-Canada-region stack. |
|
||||
|
||||
---
|
||||
|
||||
## Updated Architecture Recommendations (diff vs current ARCHITECTURE.md)
|
||||
|
||||
The current ARCHITECTURE.md is initial and lists 6 open questions. This research resolves them. Below is the diff to apply at PLAN (the orchestrator may commit an updated ARCHITECTURE.md).
|
||||
|
||||
### Resolved open questions
|
||||
|
||||
| Open question in ARCHITECTURE.md | Resolution (from this research) |
|
||||
|---|---|
|
||||
| Client framework: native Android vs cross-platform vs web PWA? | **Web (React + WebRTC) via Pipecat client SDK** for v0.1; React Native for later Android. |
|
||||
| Streaming transport: WebSocket vs WebRTC vs custom? | **WebRTC primary** (Pipecat transport); WebSocket dev fallback. |
|
||||
| ASR/TTS provider: self-hosted (Whisper/Piper) vs cloud (Deepgram/PlayHT)? | **Deepgram Nova-3 (cloud ASR) + Cartesia Sonic (cloud TTS)** primary; Piper (self-hosted) open-weights TTS fallback. |
|
||||
| Learner state store: SQLite vs Postgres for v0.1? | **SQLite** (confirmed). |
|
||||
| Ollama deployment: self-hosted vs Ollama Cloud? | **Ollama Cloud direct API** (`https://ollama.com/api/chat` + `OLLAMA_API_KEY`) for v0.1; no local daemon. Self-host `gemma4:e4b` is the post-pilot cost-reduction path. |
|
||||
| Scenario definition format: YAML/JSON DSL vs code-authored? | **YAML DSL → Pydantic model**, fed to Pipecat Flows. |
|
||||
|
||||
### Updated v0.1 component map
|
||||
|
||||
```
|
||||
Client: React + WebRTC (Pipecat client SDK)
|
||||
│ audio in/out (WebRTC, UDP)
|
||||
▼
|
||||
Pipecat server (Python)
|
||||
├─ VAD: Silero
|
||||
├─ STT: Deepgram Nova-3 (cloud, streaming)
|
||||
├─ LLM: Ollama Cloud direct API
|
||||
│ ├─ gemma4:cloud (role-play fast path)
|
||||
│ └─ deepseek-v4-flash:cloud (debrief, no-think)
|
||||
├─ TTS: Cartesia Sonic (cloud) [Piper fallback behind interface]
|
||||
├─ Scenario runtime: Pipecat Flows + YAML scenarios
|
||||
├─ Guardrail layer: pluggable (v0.1: Customer Service ruleset)
|
||||
└─ Learner state: SQLite (praxis.db)
|
||||
```
|
||||
|
||||
### Updated latency budget (revised with verified component choices)
|
||||
|
||||
| Segment | Budget | Source / note |
|
||||
|---|---|---|
|
||||
| Client capture + WebRTC uplink | ~50ms | WebRTC UDP, Canada region |
|
||||
| ASR (Deepgram first partial) | ~250ms | Vendor claim; **R1: measure** |
|
||||
| LLM first token (gemma4:cloud direct API) | ~200ms | **R3: measure** |
|
||||
| TTS first audio (Cartesia Sonic) | ~120ms | Vendor/leaderboard; **R2: measure** |
|
||||
| WebRTC downlink + playback | ~50ms | |
|
||||
| **Total (target)** | **~670ms** | ⚠️ Slightly over 600ms with all-cloud; **R4 mitigation**: move TTS to local Piper (~80ms) to bring total to ~550ms. |
|
||||
|
||||
**Key architecture insight:** the all-cloud three-hop path likely lands ~670ms, marginally over the 600ms target. The PLAN stage should design the TTS service behind an interface and pre-stage a Piper-on-pilot-server configuration as the likely production v0.1 choice, with Cartesia as the quality-benchmark option for non-latency-critical turns (e.g., the debrief). Alternatively, self-host `gemma4:e4b` for the LLM hop. **This is the single biggest v0.1 technical risk and must be spiked in Phase 1 week 1.**
|
||||
|
||||
### Decisions recommended for the orchestrator to record
|
||||
|
||||
| ID | Decision | Confidence | Source |
|
||||
|---|---|---|---|
|
||||
| D-003 (update) | Confirm `gemma4:cloud` + `deepseek-v4-flash:cloud` via Ollama Cloud direct API | 0.95 | This research (catalog verified) |
|
||||
| D-007 (update) | Confirm SQLite for v0.1 learner state | 0.90 | This research |
|
||||
| D-013 (new) | ASR = Deepgram Nova-3 streaming (cloud) | 0.85 | This research |
|
||||
| D-014 (new) | TTS = Cartesia Sonic (cloud) primary; Piper (self-hosted) fallback behind interface | 0.80 | This research |
|
||||
| D-015 (new) | Client = React + WebRTC via Pipecat client SDK | 0.85 | This research |
|
||||
| D-016 (new) | Transport = WebRTC (Pipecat); WebSocket dev fallback | 0.85 | This research |
|
||||
| D-017 (new) | Orchestration = Pipecat (not custom, not Vocode) | 0.85 | This research |
|
||||
| D-018 (new) | Scenario format = YAML DSL → Pydantic → Pipecat Flows | 0.85 | This research |
|
||||
| D-019 (new) | v0.1 guardrail layer = pluggable interface; Customer Service ruleset implementation | 0.80 | This research |
|
||||
| D-020 (new) | LLM access mode = Ollama Cloud direct API (no local daemon) for v0.1 | 0.85 | This research |
|
||||
|
||||
---
|
||||
|
||||
*End of research findings. Next step: orchestrator reviews this document, records decisions D-013..D-020 (and updates D-003, D-007), updates ARCHITECTURE.md, and proceeds to the PLAN phase where R1-R4 latency spikes are the first Phase 1 tasks.*
|
||||
@@ -0,0 +1,79 @@
|
||||
# Praxis — Roadmap
|
||||
|
||||
**Milestone:** v0.1 (foundation)
|
||||
**Status:** specify
|
||||
|
||||
## Milestone Philosophy
|
||||
|
||||
v0.1 is the **foundation milestone** — it establishes the minimal viable voice loop (one persona, one scenario, ASR+TTS+LLM round-trip, single learner state). v1.0 is reserved for a working, tested product and is a future milestone.
|
||||
|
||||
## v0.1 Phases (2 phases)
|
||||
|
||||
### Phase 0 — Pre-Execution (current)
|
||||
|
||||
**Branch:** `phase/00-pre-execution`
|
||||
**Ship target:** patch release (first patch on the v0.0.x line)
|
||||
|
||||
Pipeline stages: SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL
|
||||
|
||||
**Goal:** Produce all `.ciagent/` planning artifacts, validated requirements, research-grounded architecture, and persona-assigned vertical-slice plans for Phase 1.
|
||||
|
||||
**Deliverables:**
|
||||
- PROJECT.md (validated)
|
||||
- REQUIREMENTS.md (formal REQ-IDs)
|
||||
- ARCHITECTURE.md (research-refined)
|
||||
- PERSONAS.md (persona roster + territory)
|
||||
- Phase 1 plan (vertical slices with wave ordering)
|
||||
|
||||
### Phase 1 — Minimal Viable Voice Loop
|
||||
|
||||
**Branch:** `phase/01-minimal-voice-loop` (to be created at EXECUTE)
|
||||
**Ship target:** patch release
|
||||
|
||||
**Goal:** A single learner can open the client, speak to an AI tutor playing a Customer Service role-play scenario, hear the tutor respond with <600ms round-trip latency, and have the session logged to learner state.
|
||||
|
||||
**Vertical slices (to be refined by ci-planner):**
|
||||
1. LLM foundation wiring — Ollama `gemma4:cloud` + `deepseek-v4-flash:cloud` callable, streaming first-token <200ms
|
||||
2. ASR + TTS round-trip — streaming, interruptible, one voice persona
|
||||
3. Scenario runtime — one branching Customer Service scenario (Canada context) with failure-injection hook
|
||||
4. Learner state — session log, single learner, local persistence
|
||||
5. Client harness — minimal UI/harness exercising the full loop end-to-end
|
||||
|
||||
### Final Phase (P2) — Review + Ship
|
||||
|
||||
**Branch:** `phase/02-final-review-ship`
|
||||
**Ship target:** final patch = v0.1 milestone release
|
||||
|
||||
**Goal:** Multi-persona code review, project audit, milestone merge to main, milestone release.
|
||||
|
||||
## Future Milestones (post-v0.1, indicative)
|
||||
|
||||
| Milestone | Scope (indicative) |
|
||||
|-----------|-------------------|
|
||||
| v0.2 | Mastery scoring + competency rubrics for the Customer Service path |
|
||||
| v0.3 | Second scenario + second persona; Drill Mode |
|
||||
| v0.4 | Live Assist on-the-job companion |
|
||||
| v0.5 | Low-bandwidth surfaces (WhatsApp, offline cache) |
|
||||
| v0.6 | Multi-language (French-Canadian, then PRD's 10-language list) |
|
||||
| v0.7 | Employer / program dashboard |
|
||||
| v0.8 | Credentialing (verifiable, shareable) |
|
||||
| v0.9 | USSD fallback, feature-phone support |
|
||||
| v1.0 | Working, tested product — multiple paths, multi-market, production-ready |
|
||||
|
||||
These are indicative and will be refined by ci-roadmapper at the start of each milestone.
|
||||
|
||||
## Requirement Coverage (initial — to be refined by ci-planner)
|
||||
|
||||
| REQ-ID | Phase | Status |
|
||||
|--------|-------|--------|
|
||||
| REQ-VOICE-01 | P1 | planned |
|
||||
| REQ-VOICE-02 | P1 | planned |
|
||||
| REQ-VOICE-03 | P1 | planned |
|
||||
| REQ-VOICE-04 | P1 | planned |
|
||||
| REQ-SCEN-01 | P1 | planned |
|
||||
| REQ-STATE-01 | P1 | planned |
|
||||
| REQ-LLM-01 | P1 | planned |
|
||||
| REQ-LLM-02 | P1 | planned |
|
||||
| REQ-NFR-LAT-01 | P1 | planned |
|
||||
| REQ-NFR-COST-01 | later | deferred |
|
||||
| REQ-NFR-SAFE-01 | P1 (baseline) | planned |
|
||||
@@ -0,0 +1,102 @@
|
||||
{
|
||||
"projects": [
|
||||
{
|
||||
"slug": "praxis",
|
||||
"name": "Praxis",
|
||||
"milestone": "v0.1",
|
||||
"status": "specify"
|
||||
}
|
||||
],
|
||||
"active_project": "praxis",
|
||||
"active_projects": ["praxis"],
|
||||
"autonomy": {
|
||||
"level": "full",
|
||||
"escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
|
||||
"clarify_budget": 10,
|
||||
"decision_confidence_threshold": 0.6,
|
||||
"max_revision_iterations": 3,
|
||||
"max_verification_retries": 2,
|
||||
"escalation_timeout_ms": 300000
|
||||
},
|
||||
"model_profile": "quality",
|
||||
"parallelization": {
|
||||
"enabled": true,
|
||||
"max_concurrent_agents": 5,
|
||||
"min_plans_for_parallel": 2,
|
||||
"max_concurrent_projects": 3
|
||||
},
|
||||
"verification": {
|
||||
"automated_only": true,
|
||||
"escalate_visual": true,
|
||||
"escalate_external_integration": true,
|
||||
"test_first": false
|
||||
},
|
||||
"security": {
|
||||
"auto_accept_low_severity": true,
|
||||
"auto_mitigate_medium_severity": true,
|
||||
"escalate_high_severity": true
|
||||
},
|
||||
"git": {
|
||||
"branching_strategy": "phase",
|
||||
"auto_commit": true,
|
||||
"auto_push": false
|
||||
},
|
||||
"sessions": {
|
||||
"max_concurrent_sessions": 3,
|
||||
"session_timeout_ms": 3600000,
|
||||
"session_isolation": "branch"
|
||||
},
|
||||
"personas": {
|
||||
"enabled": true,
|
||||
"territory_enforcement": "warn",
|
||||
"personas": [
|
||||
{
|
||||
"name": "lead-developer",
|
||||
"domain": "coordination",
|
||||
"frameworks": [],
|
||||
"constraints": ["pragmatic", "battle-tested defaults"],
|
||||
"territory": []
|
||||
},
|
||||
{
|
||||
"name": "backend-engineer",
|
||||
"domain": "backend",
|
||||
"frameworks": [],
|
||||
"constraints": ["api-first", "type-safe", "latency-budget-aware"],
|
||||
"territory": ["**/server/**", "**/api/**", "**/services/**"]
|
||||
},
|
||||
{
|
||||
"name": "frontend-engineer",
|
||||
"domain": "frontend",
|
||||
"frameworks": [],
|
||||
"constraints": ["component-first", "voice-first-ui"],
|
||||
"territory": ["**/client/**", "**/ui/**", "**/components/**"]
|
||||
},
|
||||
{
|
||||
"name": "data-engineer",
|
||||
"domain": "data",
|
||||
"frameworks": [],
|
||||
"constraints": ["schema-first", "type-safe", "migration-driven"],
|
||||
"territory": ["**/migrations/**", "**/schema/**", "**/models/**", "**/db/**"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"release": {
|
||||
"forge": "gitea",
|
||||
"base_url": "https://git.cloudinit.dev",
|
||||
"owner": "coreci",
|
||||
"repo": "praxis"
|
||||
},
|
||||
"secrets": {
|
||||
"scopes": [
|
||||
{
|
||||
"name": "release",
|
||||
"env_vars": ["GITEA_TOKEN"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"ship": {
|
||||
"per_phase": true,
|
||||
"allow_skip": false,
|
||||
"max_release_retries": 3
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user