L'électron rare
0ec3da620f
Project root CLAUDE.md: architecture diagram now shows MacStudio voice-bridge (cache → F5 → safe wav), hints engine LLM rewrite via LiteLLM hints-deep (MLX 32B Q4), and MLX-LM inference tier. Infrastructure section adds MacStudio (live stack) and demotes Tower to legacy. tools/macstudio/README.md gets full stack table, aliases, persistence (crontab @reboot + */2 watchdog), resilience (cache, service_down.wav), pool pre-render command, known issues. Home ~/CLAUDE.md edits applied separately (six-node, MacStudio added, Tower line trimmed).
99 lines
5.3 KiB
Markdown
99 lines
5.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for Claude Code working in this repository.
|
|
|
|
## Overview
|
|
|
|
**Le Mystère du Professeur Zacus** — hybrid educational escape room game with ESP32-S3 hardware, React authoring studios, and a portable Runtime 3 scenario engine. Scenarios are authored in YAML, compiled to a portable IR, and executed on both web and ESP32 targets.
|
|
|
|
## Build & Test
|
|
|
|
```bash
|
|
make all-validate # Full pipeline (scenario + audio + printables + runtime3)
|
|
make content-checks # Schema validation only
|
|
|
|
# Runtime 3
|
|
make runtime3-compile # YAML → IR
|
|
make runtime3-simulate # Execute IR
|
|
make runtime3-verify # Verify pivots
|
|
make runtime3-test # Python unittest
|
|
|
|
# Compile a specific scenario
|
|
python3 tools/scenario/compile_runtime3.py game/scenarios/zacus_v2.yaml
|
|
|
|
# Dev CLI (12 actions)
|
|
./tools/dev/zacus.sh content-checks
|
|
./tools/dev/zacus.sh voice-bridge start|stop|status|test
|
|
```
|
|
|
|
Frontend, desktop, and tooling commands live in their nested CLAUDE.md.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
YAML scenario → compile_runtime3.py → Runtime 3 IR → ESP32 / Web player
|
|
↓
|
|
Voice bridge :8200 (MacStudio)
|
|
↳ /tts → F5-TTS-MLX (cache → F5 → safe wav)
|
|
↳ /voice/intent → LiteLLM npc-fast (MLX 7B Q4)
|
|
↳ /voice/transcribe → whisper.cpp :8300
|
|
↓
|
|
Hints engine → /hints/ask (LLM rewrite via hints-deep MLX 32B Q4)
|
|
```
|
|
|
|
Key surfaces:
|
|
- **Scenario IR**: `game/scenarios/zacus_v2.yaml` → `tools/scenario/compile_runtime3.py` → portable Runtime 3 IR. Contract: `specs/ZACUS_RUNTIME_3_SPEC.md`.
|
|
- **Authoring**: `frontend-v3/` (pnpm monorepo: `apps/atelier/` Scratch-like studio + `apps/dashboard/` game-master live view).
|
|
- **Firmware**:
|
|
- `ESP32_ZACUS/` submodule — Freenove ESP32-S3 master (NPC engine, voice pipeline, vision/QR, media manager). Branche `feat/idf-migration` en cours (port Arduino → ESP-IDF 5.4).
|
|
- `PLIP_FIRMWARE/` — retro telephone annex (ES8388 dev kit bringup, Si3210 PCB target). REST endpoint consumed by the master ESP32.
|
|
- **Voice / NPC**: F5-TTS-MLX in-process sur MacStudio (`studio:8200`), voix Zacus clonée via `~/zacus_reference.wav`. Pré-rendu via `tools/tts/generate_npc_pool.py --backend f5`. Service down WAV hardcoded en graceful degradation. NPC phrases : `game/scenarios/npc_phrases.yaml`.
|
|
- **Hints engine**: `tools/hints/server.py` FastAPI (LLM rewrite via LiteLLM `hints-deep`, anti-cheat, adaptive level, safety filter `game/scenarios/hints_safety.yaml`).
|
|
- **Inference stack**: voir `tools/macstudio/README.md` — MLX-LM (npc + hints), whisper.cpp, F5-TTS, LiteLLM proxy `:4000`. Configs versionnées dans `tools/macstudio/`.
|
|
- **MCP hardware**: `tools/dev/mcp_hardware_server.py` (stdio, 6 tools).
|
|
- **Desktop hub**: `desktop/` (Electron, macOS, bundles V3 frontends, talks USB serial).
|
|
|
|
## Where to Look
|
|
|
|
| Task | Location |
|
|
|------|----------|
|
|
| Edit scenarios, NPC phrases, prompts | `game/` |
|
|
| Modify Runtime 3 compiler / validators / TTS pool / dev CLI | `tools/` |
|
|
| Authoring UI / dashboard / simulation | `frontend-v3/` |
|
|
| Zacus Studio macOS app | `desktop/` |
|
|
| Add or change a contract spec | `specs/` |
|
|
| Python tests (Runtime 3, NPC) | `tests/` |
|
|
| Firmware code (Zacus master) | `ESP32_ZACUS/` submodule (own repo) |
|
|
| Firmware code (PLIP retro phone) | `PLIP_FIRMWARE/` (inlined; see README for submodule conversion) |
|
|
|
|
## Canonical Files
|
|
|
|
| File | Role |
|
|
|------|------|
|
|
| `game/scenarios/zacus_v2.yaml` | Scenario source of truth |
|
|
| `game/scenarios/npc_phrases.yaml` | NPC phrase bank (FR) |
|
|
| `specs/ZACUS_RUNTIME_3_SPEC.md` | Runtime contract |
|
|
| `specs/AI_INTEGRATION_SPEC.md` | AI layer architecture |
|
|
| `Makefile` | Top-level automation |
|
|
| `docs/QUICKSTART.md` | Getting started |
|
|
| `docs/DEPLOYMENT_RUNBOOK.md` | Field deployment |
|
|
| `docs/debt/codex-firmware-fixes-to-apply.md` | Pending firmware fixes |
|
|
|
|
## Infrastructure
|
|
|
|
- **MacStudio** (`ssh studio`, M3 Ultra 512 GB) : **stack inférence Zacus complète** — MLX-LM (`npc-fast` 7B Q4 :8501, `hints-deep` 32B Q4 :8500), whisper.cpp `large-v3-turbo-q5_0` :8300, F5-TTS-MLX in-process via voice-bridge :8200 (cache disque + watchdog `*/2` + `service_down.wav` graceful), LiteLLM proxy :4000. Voir `tools/macstudio/README.md`.
|
|
- **Tower** (`clems@192.168.0.120`) : Suite Numérique, n8n, LiteLLM Tower (legacy). **Plus dans la chaîne live Zacus** ; container Docker `zacus-tts-piper` survit pour batch historique uniquement (voix EN-only, FR à déployer si besoin).
|
|
- **KXKM-AI** (`kxkm@kxkm-ai` via Tailscale) : RTX 4090, GPU inference (fine-tuning, plus utilisé en runtime).
|
|
- SSH is key-based only — never `sshpass`.
|
|
|
|
## Language
|
|
|
|
User speaks French → respond in French. Code, comments, commits, docs → English. Full diacritics required in French.
|
|
|
|
## Nested Guidance
|
|
|
|
Domain-specific rules live in nested `CLAUDE.md` files and load automatically when you read files in those directories. Closest file wins. Current nested:
|
|
|
|
- `game/`, `tools/`, `tests/`, `specs/`
|
|
- `frontend-v3/`, `desktop/`
|