Adolfo Reyna
106 lines
8.3 KiB
Markdown
106 lines
8.3 KiB
Markdown
---
|
|
project_key: kids-hermes-voice
|
|
status: active
|
|
factory_maturity: discovery
|
|
updated: 2026-08-18
|
|
---
|
|
|
|
# Kids Hermes Voice — Project Definition
|
|
|
|
## Purpose
|
|
|
|
Kids Hermes Voice is the child-safe, local voice experience spanning the Tactility ESP32 client, the voice-gateway application, and the Hermes kids/voice runtime. It is distinct from `family-voice`, which remains the evaluation-only speaker-identification and privacy research project. Speaker identification may later supply non-authoritative context to this project only after an explicit consent decision.
|
|
|
|
## Execution map
|
|
|
|
| Host / target | Repository / service | Paseo-project role | Current evidence |
|
|
|---|---|---|---|
|
|
| Mac mini `.102` | `~/Projects/electronics/tactility/tactility_apps` — `Apps/PipecatVoice` / related `ReynaBot` paths | `Kids Hermes Voice · Tactility client` | Repository is present on `main`, ahead of `origin/main` by 1 commit, with existing modified/untracked voice-related work; preserve it until inventoried. Existing Tactility Apps workspace: `wks_c488f281bcb459c7` (registration must be rechecked before dispatch). |
|
|
| Mac mini `.102` | `~/Projects/pipecat-voice-gateway` | `Kids Hermes Voice · Gateway` | Repository is present on `main`, with existing modified/untracked gateway work; no reset, commit, or deployment is authorized. Workspace registration still needs discovery. |
|
|
| AeroPi5 `.126` | Hermes kids/voice runtime and legacy voice-host role | `Kids Hermes Voice · Runtime` | Host was reachable on 2026-08-18. Exact checkout, active service ownership, and current configuration are unverified; read-only discovery only. |
|
|
| Tactility ESP32 fleet | First target board must be named per task | Deployment target, not a Paseo host | No install, flash, or runtime change is authorized by this record. |
|
|
|
|
## Architecture boundary
|
|
|
|
```text
|
|
Tactility voice client <-> voice-gateway protocol <-> Hermes kids/voice runtime
|
|
device UX transport child-safe response policy
|
|
```
|
|
|
|
- The client owns capture, playback, device UI, and protocol compatibility.
|
|
- The gateway owns the versioned voice transport, capability negotiation, turn telemetry, and compatibility fallbacks.
|
|
- The Hermes runtime owns the child-safe profile, permitted tools, and local response routing.
|
|
- `family-voice` owns offline speaker-ID evaluation and privacy review; it is not an authentication mechanism.
|
|
|
|
## Personas
|
|
|
|
- Integration planner: maps protocol, repository boundaries, and acceptance criteria; read-only.
|
|
- Tactility client implementer: isolated worktree only.
|
|
- Gateway/runtime implementer: isolated worktree only; never edits both repositories in one shared checkout.
|
|
- Build/protocol verifier: reports exact commands and outcomes without source fixes.
|
|
- Child-safety/privacy reviewer: checks profile/tool boundary, retention, and no-cloud/raw-audio claims.
|
|
- Device QA/deployment executor: acts only for a named device after explicit approval, rollback plan, and compatible SDK/firmware verification.
|
|
|
|
## Safety boundaries
|
|
|
|
- Do not expose administrator/system tools to child-facing sessions.
|
|
- Do not upload, commit, or place raw audio, embeddings, credentials, or pairing material in project records.
|
|
- No always-listening capture, enrollment, firmware flash, device install, daemon restart, gateway deployment, profile/permission change, or service reconfiguration without explicit human approval.
|
|
- Existing dirty worktrees are evidence to inventory, not permission to reset, commit, merge, or overwrite.
|
|
- Every source-changing lane uses one isolated worktree and an explicitly `auto-review` Paseo coding session; planners/reviewers remain read-only.
|
|
|
|
## First coordination task — baseline contract and inventory
|
|
|
|
**Goal:** establish an implementation-ready, evidence-backed baseline without changing source or devices.
|
|
|
|
**Incident context:** this voice path reportedly worked previously but has not been restored for an extended period. Treat the current effort as a restoration investigation: establish the last known working boundaries and concrete present blockers before proposing a change.
|
|
|
|
**Acceptance criteria:**
|
|
1. Identify the intended first device/board and its current firmware/SDK compatibility.
|
|
2. Inventory existing uncommitted client and gateway work by file and behavioral intent; classify it as preserve, superseded, or candidate for the first worktree.
|
|
3. Confirm the live runtime host, checkout/service owner, and the current kids/voice entry route on AeroPi5.
|
|
4. Produce a versioned client↔gateway protocol contract covering capability negotiation, PCM-first streamed output, state/error events, interruption behavior, and the full-WAV/base64 fallback.
|
|
5. Name the first source-changing milestone and its repository owner; no coding until the human approves that scope.
|
|
|
|
**Allowed now:** read-only repository, workspace, host, and device discovery; protocol planning; build-command discovery.
|
|
|
|
**Required evidence:** exact git/workspace status; repository `AGENTS.md`; runtime/service ownership; device identity plus firmware/SDK version; proposed contract location and verification commands.
|
|
|
|
**Forbidden effects:** source edits, commits, resets, installs, flashes, starts/stops/restarts, profile/permission changes, external sends, credentials, and raw-audio collection/export.
|
|
|
|
**Approval gate:** explicit human approval is required before dispatching an implementation agent, changing source, or interacting with a device/runtime.
|
|
|
|
## Baseline findings — 2026-08-18
|
|
|
|
- The canonical device architecture is **protocol-v1 LAN WebSocket**, not Pipecat SmallWebRTC inside a Tactility external ELF. The latter is a documented no-go for the current SDK/firmware boundary.
|
|
- The Mac mini currently has a live LAN adapter at `192.168.68.102:8644`, serving `/api/esp32/voice/ws`; a non-mutating HTTP probe correctly received `400` requesting a WebSocket upgrade. The default Hermes gateway separately listens on `*:8642`.
|
|
- Current Tactility `PipecatVoice` source and README agree on the `.102:8644` adapter endpoint, but prior restoration evidence refers to a different endpoint. The first gate is therefore endpoint plus persisted-device-config reconciliation, not a transport redesign.
|
|
- AeroPi5 has an active `hermes-gateway-kids.service` running the `kids` profile from `~/.hermes/profiles/kids`. It has no Paseo CLI/workspace registration, and no `:8642` listener was observed in this discovery; it is a runtime-policy dependency, not the current LAN adapter host.
|
|
- Board `.129` is reachable and its dashboard API returned HTTP `200`; board `.112` responds to ICMP but its dashboard port `80` was unavailable. `.129` is the evidence-backed candidate for the first restoration validation, pending the human naming it as the approved target.
|
|
- The local client protocol test passed (`voice_protocol tests passed`) and both involved working trees passed `git diff --check`. This is static evidence only; it does not prove a board WebSocket session, upstream PCM, speaker playback, reconnect, or STT/Hermes/TTS.
|
|
- Existing gateway/client modifications must be inventoried and retained. A credential-bearing source artifact was encountered during read-only inspection; it must be remediated in an explicitly approved, secret-safe source-change lane and must never be copied into records, logs, or chat.
|
|
|
|
## Canonical project layout
|
|
|
|
```text
|
|
Kids Hermes Voice (cross-project record)
|
|
├── Tactility client: tactility_apps/Apps/PipecatVoice
|
|
│ └── device capture/playback, protocol-v1 state machine, persisted non-secret endpoint
|
|
├── LAN adapter: voice-assistant/hermes-esp32-voice-gateway
|
|
│ └── 192.168.68.102:8644 protocol boundary, LAN framing/limits, deterministic audio fixtures
|
|
├── Voice processing: pipecat-voice-gateway
|
|
│ └── STT/TTS/turn-service experimentation; never silently substitutes for the adapter contract
|
|
└── Kids runtime: AeroPi5 ~/.hermes profile `kids`
|
|
└── child-safe policy and allowed-tool boundary; distinct from transport ownership
|
|
```
|
|
|
|
The next read-only deliverable is an endpoint/persisted-config reconciliation report for the approved board. Only after that evidence exists may a separate, approved worktree lane define the smallest restoration edit.
|
|
|
|
## Related records
|
|
|
|
- `family-voice.md`
|
|
- `tactility.md`
|
|
- `../tactility_voice_gateway_elato_transition_2026.md`
|
|
- `../voice_dev_infrastructure_2026.md`
|
|
- `../../areas/operations/services_inventory.md`
|