server/debrief.py — generate_debrief() loads the session turns + branch
outcome + scenario debrief.debrief_focus, calls deepseek-v4-flash:cloud in
no_think mode (D-020, REQ-LLM-02) with the debrief prompt template
(docs/debrief/default.yaml), produces a concise 3-bullet text summary
(what you did well / what to improve / one next step) referencing the
learner's actual turns + branch outcome.
TASK-05-02: the debrief text is routed through the CustomerServiceGuardrail
output filter (debrief role) — legal-action recommendations are blocked and
replaced with a coaching redirect.
TASK-05-03: the debrief is synthesized via the same TTSProvider interface
as the role-play (D-006 one voice) — no separate TTS path (verified by
structural test).
5 tests pass (debrief references turns + branch, no_think mode asserted,
guardrail blocks 'tell the customer to sue', normal coaching passes,
TTSProvider synthesis reuses role-play voice).
---ci---
phase: 1
milestone: v0.1
plan: 05
task: 05-01,05-02,05-03
status: execute
persona: backend-engineer
requirements:
covered: [REQ-DEBRIEF-01, REQ-LLM-02, REQ-NFR-SAFE-01]
---/ci---
server/interruptibility.py — programmatic check that the pipeline task is
configured with allow_interruptions=True (D-008 abort-and-yield). The manual
test (speaking during AI speech cuts it off) is documented in
docs/latency-report.md; the automated test confirms the flag is set.
server/scenarios/classifier.py — classify_branch() uses
deepseek-v4-flash:cloud no-think (D-020) as LLM-as-judge to classify the
learner's turn transcripts into accept_resolution or escalate at session end,
OFFLINE from the voice loop (D-P1-05, G-002 post-hoc classification). Parses
the LLM's JSON response leniently (code fences, unknown-id fallback, malformed
JSON scan). classify_branch_sync_heuristic() is a rule-based fallback for
tests/e2e when no API key is present. 11 tests pass (interruptibility flag
on/off/missing; classifier accept/escalate scripted transcripts; JSON parse
valid/code-fenced/unknown-id/malformed; fake-LLM async classify; offline
structural assertion).
---ci---
phase: 1
milestone: v0.1
plan: 03
task: 03-05,03-06
status: execute
persona: backend-engineer
requirements:
covered: [REQ-VOICE-04, REQ-SCEN-01]
---/ci---
server/guardrails/customer_service.py implements the Guardrail interface with
the v0.1 Customer Service ruleset (RESEARCH.md safety baseline): blocks
legal/financial/medical advice, real-company impersonation, and a debrief
output filter that blocks recommendations the learner advise legal action
('tell the customer to sue them' → blocked_legal with a coaching redirect).
Session-start disclaimer text defined ('This is an AI practice session…').
Selected via PRAXIS_GUARDRAIL=customer_service (default); swaps in for
NoOpGuardrail with no pipeline change (D-019). server/__main__.py loads the
guardrail and logs the disclaimer as the first AI utterance. 9 unit tests
pass (disclaimer, blocks legal/financial/medical, allows normal coaching,
debrief filter blocks 'sue them', debrief allows coaching, swappable with
NoOp).
---ci---
phase: 1
milestone: v0.1
plan: 03
task: 03-04
status: execute
persona: backend-engineer
requirements:
covered: [REQ-ORCH-02, REQ-NFR-SAFE-01]
---/ci---
server/scenarios/runtime.py — ScenarioRuntime maps a Scenario to a Pipecat
Flows state-machine spec: initial 'conversation' state with the scenario's
system prompt + opening line, branch metadata carried in the spec (v0.1
has no in-flight transitions per G-002 — branching is post-hoc; Phase 2+
can fork without schema change). set_branch() resolves the branch outcome
from the classifier; debrief_focus() returns the per-branch focus.
TASK-03-07: server/pipeline.py build_pipeline() now accepts a scenario_id,
loads the runtime, and uses scenario.setup.system_prompt instead of the
SLICE-02 hardcoded walking-skeleton prompt. Falls back gracefully if the
scenario can't load. server/__main__.py passes
PRAXIS_SCENARIO=customer_service_refund_ca_v01 by default. 7 runtime tests
pass (system prompt, set_branch accept/escalate, unknown-branch error,
debrief_focus per branch, flows spec branches, debrief model config).
---ci---
phase: 1
milestone: v0.1
plan: 03
task: 03-03,03-07
status: execute
persona: backend-engineer
requirements:
covered: [REQ-SCEN-01, REQ-SCEN-FMT-01, REQ-ORCH-02]
---/ci---
client/ — React + Vite + TypeScript scaffolded with the Pipecat client SDK
(@pipecat-ai/client-js) and SmallWebRTCTransport
(@pipecat-ai/small-webrtc-transport). useVoiceSession.ts hook manages mic
permission, WebRTC connect, audio playback, live transcript, and a latency
readout (captures the e2e_latency_ms metric the server emits). App.tsx is a
minimal one-page session UI: disclaimer, Start/End buttons, status badge,
latency readout (within/over 600ms budget), live transcript. vite.config.ts
proxies /pipecat + /health to the Python server (port 8789). npm run
typecheck + npm run build pass.
server/latency.py — LatencyObserver (a Pipecat FrameProcessor) timestamps
transcript-ready, LLM-first-token, TTS-first-audio, and playback-start per
turn, computes ASR→TTS-first-audio (the v0.1 latency target), and logs it
to console with a within/over-budget verdict. Wired into the pipeline
between STT/LLM/TTS so it observes without altering the frame stream. 5
unit tests pass (LatencyRecord e2e math + observer construction +
reset_turn). Full server suite: 18 passed.
---ci---
phase: 1
milestone: v0.1
plan: 02
task: 02-05,02-06
status: execute
persona: frontend-engineer,backend-engineer
requirements:
covered: [REQ-VOICE-01, REQ-VOICE-02, REQ-VOICE-03, REQ-NFR-LAT-01]
---/ci---
server/guardrails/noop.py implements the Guardrail interface with an
always-allow stub so the Pipecat pipeline has the pluggable hook from
SLICE-02. Swapping to CustomerServiceGuardrail (SLICE-03 TASK-03-04)
requires no pipeline change (D-019). The session-start disclaimer text
(RESEARCH.md safety baseline) is defined here so the pipeline can play
it as the first AI utterance even before the real ruleset lands.
---ci---
phase: 1
milestone: v0.1
plan: 02
task: 02-07
status: execute
persona: backend-engineer
requirements:
covered: [REQ-ORCH-02]
---/ci---
server/llm/ollama_cloud.py wraps the Ollama Cloud direct API
(https://ollama.com/api/chat + bearer, stream=True) behind LLMProvider.
chat() streams LLMStreamChunk (is_first flag for TTFT measurement);
chat_full() accumulates for the debrief / branch classifier (offline).
Two models: gemma4:cloud (roleplay_model) + deepseek-v4-flash:cloud
(debrief_model, no_think mode for latency, D-020). Resolves R6 — the
adapter confirms the direct API + bearer path; a live first-token
confirmation is pending the R3 probe with a real key. Graceful no-key
degradation (no chunks, no crash). 6 unit tests pass (mocked httpx
streaming response + env model selection + chat_full accumulation).
---ci---
phase: 1
milestone: v0.1
plan: 02
task: 02-03
status: execute
persona: backend-engineer
requirements:
covered: [REQ-LLM-01, REQ-LLM-02]
---/ci---
server/tts/cartesia_tts.py wraps the raw Cartesia Sonic WebSocket API
(wss://api.cartesia.ai/tts/websocket) — streaming PCM s16le, one voice
(CARTESIA_VOICE_ID, D-006). server/tts/piper_tts.py wraps piper-tts
self-hosted synthesis (R4 mitigation, open-weights). Both implement
TTSProvider (synthesize streaming + synthesize_all). Both degrade
gracefully (no audio, no crash) when the API key / voice model is absent.
PRAXIS_TTS=cartesia|piper selects the adapter via the registry with no
pipeline change (D-014). 7 unit tests pass (mock streams + env selection
+ graceful missing-key/model handling).
---ci---
phase: 1
milestone: v0.1
plan: 02
task: 02-02
status: execute
persona: backend-engineer
requirements:
covered: [REQ-VOICE-02]
---/ci---
Praxis CI