Repository Guidelines

Project Structure & Module Organization

firmware/esp32s3_audio_min/ implements the ESP32-S3 bridge; it now emits binary AUD0 frames and obeys PAUSE / RESUME commands.
Desktop modules live under desktop_vad/, asr/ (whisper.cpp, Faster-Whisper, Vosk), llm/, and tts/, with orchestration in controller/.
scripts/ exposes validation CLIs (esp_audio_tester.py, vad_test.py, asr_transcribe.py, session_controller.py, etc.).
Specifications, validation notes, and roadmap checkpoints are in docs/; runtime traces go to logs/sessions/.
External sources belong in third_party/ (see its README for clone/build instructions).

uv venv --python 3.10 --seed
uv pip install pyserial webrtcvad requests soundfile faster-whisper vosk — baseline environment.
uv run scripts/esp_audio_tester.py --port /dev/gradi-esp-mediate record --seconds 5 --output esp_mic_test.wav — exercises the binary mic stream (handles READY/PAUSE/RESUME automatically).
uv run scripts/asr_transcribe.py --asr-engine faster_whisper --fw-model-dir third_party/faster-whisper/models phrase01.wav — smoke test Faster-Whisper; swap --asr-engine for whisper_cpp or vosk as needed.
uv run scripts/session_controller.py --port /dev/gradi-esp-mediate --kokoro-voice af_bella --max-cycles 1 — full Idle→Playback cycle; add --verbose-esp during debugging.

Python: 4-space indent, type hints, snake_case modules, CamelCase dataclasses, minimal but meaningful comments.
Firmware: keep constants in constexpr, avoid heap allocations in realtime paths, and restrict UART output to the defined text commands.
Log lines consumed by automation must remain single-line JSON, emitted via the controller.

Manual validation is expected: capture WAV artifacts, transcript files, or session JSONL before merging.
Future automated tests should live under tests/, mirror package paths, and use pytest with test_<module>.py naming.
When diagnosing audio regressions, include the relevant logs/sessions/session_*.jsonl and note ASR engine / firmware build used.

Use short, imperative commit titles (e.g., Switch ESP stream to AUD0 frames). Keep firmware, desktop, and docs changes separated when practical.
Reference roadmap IDs (B1, C2, E1, etc.) in PR descriptions and list the validation commands you executed.
PRs should summarize observed behavior, link to artifacts (WAV, JSONL), and call out remaining risks or follow-up tasks.