Helmane：基于 Pipecat 与 Mistral Voxtral 的餐厅电话语音助手 moshi-rag-voice-assistant

Helmane — l'assistante téléphonique des restaurants

Une assistante vocale qui décroche à la place de l'équipe, en salle : elle prend les réservations (et les modifie ou les annule au téléphone), répond aux questions pratiques à partir de la fiche de l'établissement, et prend un message quand elle ne peut pas traiter la demande. Le restaurateur est prévenu par e-mail et retrouve tout dans l'admin.

Un déploiement, plusieurs établissements : chacun est identifié par son numéro Twilio, avec sa voix, son accueil, sa base de connaissances, ses horaires et ses comptes.

Le chemin d'un appel

Il n'y en a qu'un depuis le 18/09/2026 (l'ancienne boucle Gather/Say et les moteurs locaux restent lisibles au tag archive/moteurs-locaux) :

Appel ─▶ Twilio ─▶ POST /twilio/voice (signé) ─▶ TwiML <Connect><Stream>
       ─▶ WS /ws/voice (μ-law 8 kHz, poignée de main signée) ─▶ Pipecat
            ├─ Deepgram nova-3 : transcription (décroche en multilingue, se fixe sur une langue)
            ├─ LLM via OpenRouter : conversation + outils (disponibilité, réservation,
            │    modification, annulation, message) — refus côté serveur hors horaires
            └─ Mistral Voxtral : la voix choisie par l'établissement (30 voix, sans GPU)
       ◀─ audio vers l'appelant (accueil pré-rendu : aucun blanc au décroché)

Assistante en panne ─▶ elle rend la ligne ─▶ POST /twilio/suite ─▶ le restaurant sonne,
                                                                    sinon répondeur

Depuis le 28/09/2026, la voix vient de Mistral. La voix Moshi (moshi-server sur un GPU Modal) n'est plus qu'un secours quand la clé Mistral manque ; son retrait est prévu.

Détail des choix : ARCHITECTURE.md.

Ce que fait le produit

Démarrer

Prérequis : Docker ; des clés OpenRouter, Deepgram, Twilio et Mistral (voix Voxtral, docs/VOXTRAL.md).

cp env.example .env      # OPENROUTER_API_KEY, DEEPGRAM_API_KEY, TWILIO_*, MISTRAL_API_KEY,
                         # PUBLIC_WS_URL, ADMIN_EMAIL, ADMIN_PASSWORD…
docker compose up -d --build
curl -s localhost:8000/health

Dans une base vide, un restaurant de démonstration est semé sur le numéro TWILIO_NUMBER (SEED_DEMO=0 pour ne rien semer). Ensuite, les établissements se gèrent dans /admin. Pour recevoir de vrais appels, Twilio doit joindre l'application en HTTPS : voir docs/TWILIO_SETUP.md.

Production : VPS + Caddy + scripts/deploy.sh, tout est dans docs/DEPLOY.md.

Tests

# Dans l'image Docker (les dépendances verrouillées y sont déjà)
docker run --rm --tmpfs /tmp:exec -v "$PWD:/repo" -w /repo/api moshi-rag-voice-assistant-api \
  sh -c "pip install -q pytest ruff >/dev/null 2>&1; ruff check --config ../ruff.toml app; \
         python -m pytest tests -q -p no:cacheprovider"

# Ou hors Docker (Python 3.12), comme la CI
cd api && pip install -r app/requirements.lock -r tests/requirements-test.txt
python -m pytest tests -q                  # aucun réseau, tout est mocké

La CI (.github/workflows/ci.yml) joue ruff check api/app, pip-audit sur le verrou, la suite, puis scripts/mutation_check.py : chaque garde-fou critique est retiré tour à tour, et un test doit rougir. Un appel réel se vérifie avec docs/RECETTE.md. Le cycle de travail complet (branche, revue, fusion, déploiement) est décrit dans CLAUDE.md.

Structure

api/
  app/
    main.py              webhooks Twilio, flux média, sondes /health et /supervision
    llm.py               prompt système + outils métier (partagés voix et SMS)
    voice/               pipeline Pipecat, voix Mistral (et Moshi en secours), accueil,
                         langue, journal de bord, vigie des pannes
    admin/               plateforme admin (Jinja2 + htmx, rendue côté serveur)
    connecteurs/         carnet de réservations : interne, resOS, faux resOS de test
    tenants.py reservations.py messages.py calls.py users.py   données (SQLite)
    renvoi.py repondeur.py                                     assistante en panne
    site/                page d'accueil publique (prix lus dans plans.py)
    rappel.py            « Rappelez-moi » : l'appel sortant et tous ses plafonds
    disponibilite.py horloge.py notifications.py twilio_signature.py
    twilio_region.py     la région où Twilio traite les appels (us1, ie1) : jeton et API
    supervision.py rgpd.py quotas.py plans.py taches.py db.py
    requirements.txt     l'intention ; requirements.lock : les versions exactes installées
  tests/
deploy/modal_moshi_server.py   la voix de secours Moshi, sur Modal
scripts/                       déploiement, sauvegarde, bancs d'essai, contrôle de mutation
caddy/Caddyfile                TLS, en-têtes de sécurité (CSP)
docs/                          déploiement, recette, supervision, RGPD, tarifs, resOS, voix

Variables essentielles

La liste complète, commentée, est dans env.example. Une variable posée dans .env n'atteint le conteneur que si docker-compose.yml la liste.

Documentation

Documents historiques, conservés pour leur raisonnement et non tenus à jour : ROADMAP.md (état du 19/09/2026 ; le suivi est aujourd'hui dans Jira), docs/PASSATION.md (août 2026), docs/VOICE_STACK.md (étude de juillet 2026), docs/MODAL.md (la voix de secours Moshi).