Assistant vocal CLI personnalisé utilisant Mistral Large pour les réponses, Voxtral TTS pour la synthèse vocale, et Voxtral Realtime pour la transcription micro. Supporte le Model Context Protocol (MCP) pour appeler des outils externes depuis le LLM.

Disclaimer : Cet outil est un "proof-of-concept" expérimental pour investiguer les possibilités offertes par des agents vocaux personnalisés.

Prérequis

Python 3.10+
Node.js 18+ (pour les serveurs MCP embarqués TypeScript)
Une clé API Mistral : console.mistral.ai
Lecteur audio système :
- Linux : aplay (inclus dans alsa-utils → sudo apt install alsa-utils)
- macOS : afplay (inclus avec le système)
- Windows : PowerShell (inclus)

Installation

# 1. Cloner le projet
git clone <url-du-repo>
cd arioch-assistant

# 2. Créer et activer l'environnement virtuel Python
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
# .venv\Scripts\activate       # Windows

# 3. Installer les dépendances Python
pip install -r requirements.txt

# 4. Configurer l'environnement
cp .env.example .env
# Éditer .env et renseigner au minimum MISTRAL_API_KEY

# 5. (Optionnel) Compiler les serveurs MCP embarqués
cd mcp_servers/traveller_map
npm install
npm run build
cd ../..

Configuration

Copiez .env.example en .env et renseignez les variables :

# Obligatoire
MISTRAL_API_KEY=your-api-key-here

# Optionnel — laissez vide pour la voix automatique
VOICE_ID=

# Optionnel — prompt système par défaut
SYSTEM_PROMPT=Tu es Arioch, un assistant vocal intelligent...

# Optionnel — langue préférée pour la sélection de voix TTS
VOICE_LANGUAGE=fr

Utilisation

# Activer l'environnement et lancer
source .venv/bin/activate
python main.py

Commandes disponibles dans le REPL

Commande	Description
`help`	Afficher l'aide
`exit` / `quit`	Quitter l'assistant
`reset`	Effacer l'historique de conversation
`profiles`	Lister les profils disponibles
`profile <slug>`	Charger un profil (ex : `profile traveller_scout`)
`voice <id>`	Définir la voix Voxtral manuellement
`voice clear`	Revenir à la voix automatique
`mode vocal`	Passer en mode entrée microphone
`mode texte`	Revenir en mode saisie clavier
`mcp`	Lister les serveurs MCP connectés
`mcp tools`	Lister tous les outils MCP disponibles

Mode vocal

En mode vocal, appuyez sur Entrée (sans rien écrire) pour commencer à parler. Le microphone s'active, la transcription s'affiche en temps réel via Voxtral Realtime, puis appuyez à nouveau sur Entrée pour envoyer.

La réponse est lue à voix haute dès que la première phrase est disponible (pipeline streaming — voir Architecture).

Profils de personnalité

Les profils sont des fichiers .yaml dans le dossier profiles/. Ils permettent de changer la personnalité du LLM, la voix TTS, et les outils MCP disponibles.

# Lister les profils
> profiles

# Charger un profil
> profile traveller_scout

Structure d'un profil

name: Mon Assistant Spécialisé
description: Courte description affichée dans la liste

# Langue préférée pour la sélection de voix (surcharge .env)
voice_language: fr

# Prompt système du LLM (obligatoire)
system_prompt: |
  Tu es un expert en ...

# Documents texte/markdown injectés dans le prompt système (optionnel)
documents:
  - docs/mon_document.md

# Serveurs MCP à connecter pour ce profil (optionnel)
mcp_servers:
  - name: mon-serveur
    command: node
    args: ["mcp_servers/mon_serveur/dist/index.js"]

Profils inclus

Slug	Nom	Description
`default`	Arioch — Assistant général	Assistant généraliste en français
`traveller_scout`	Scout Ship AI — Traveller RPG	IA de bord d'un vaisseau Scout/Courier (Traveller RPG), avec accès à la carte de l'univers via MCP

Serveurs MCP (Model Context Protocol)

L'assistant supporte le Model Context Protocol pour étendre les capacités du LLM avec des outils externes. Lorsqu'un profil déclare des serveurs MCP, le LLM peut appeler leurs outils automatiquement pour répondre aux questions.

Comment ça fonctionne

Le profil YAML déclare un ou plusieurs serveurs MCP dans mcp_servers
Au chargement du profil, les serveurs sont lancés en arrière-plan (via stdio ou SSE)
Leurs outils sont automatiquement exposés au LLM (Mistral Large)
Le LLM appelle les outils si besoin, les résultats sont injectés dans la réponse

Déclarer un serveur dans un profil

Serveur stdio (processus local, recommandé) :

mcp_servers:
  - name: mon-outil
    command: node
    args: ["mcp_servers/mon_outil/dist/index.js"]
    # env:              # variables d'environnement optionnelles
    #   API_KEY: xxx

Serveur SSE (HTTP distant) :

mcp_servers:
  - name: mon-serveur-distant
    url: "http://localhost:3000/sse"

Les chemins dans args peuvent être relatifs à la racine du projet — ils sont automatiquement résolus en chemins absolus.

Inspecter les outils disponibles

> mcp              # liste les serveurs connectés
> mcp tools        # liste tous les outils avec leur description

Architecture

main.py                    ← Point d'entrée
assistant/
├── cli.py                 ← REPL interactif + pipeline TTS streaming
├── llm.py                 ← Chat streaming avec Mistral Large (tool-call loop)
├── tts.py                 ← Synthèse vocale Voxtral TTS
├── audio.py               ← Lecture audio cross-platform (aplay / afplay / PowerShell)
├── stt.py                 ← Transcription micro Voxtral Realtime
├── mcp_client.py          ← Gestionnaire serveurs MCP (keeper-task pattern)
├── profile.py             ← Chargement/application des profils YAML
└── config.py              ← Variables d'environnement
profiles/
├── default.yaml
├── traveller_scout.yaml
└── docs/                  ← Documents de contexte injectés dans les prompts
mcp_servers/
└── traveller_map/         ← Serveur MCP Traveller Map (TypeScript, embarqué)
    ├── src/               ← Sources TypeScript
    └── dist/              ← Build compilé (versionné)
scripts/
├── register_voice.py      ← Enregistrement d'une voix clonée Voxtral
└── list_voices.py         ← Lister les voix disponibles

Pipeline TTS en streaming

Pour minimiser la latence, la réponse du LLM est traitée en 3 étages parallèles :

[Mistral stream] → détection de phrases → sentence_queue
                                               ↓ (thread TTS)
                                         [Voxtral TTS] → audio_queue
                                                              ↓ (thread Audio)
                                                         [aplay / afplay]

Dès qu'une phrase complète est détectée dans le flux de tokens, elle part immédiatement en synthèse. L'audio de la phrase 1 est joué pendant que la phrase 2 est synthétisée.

Tool calling MCP

User → LLM (stream) → [tool_calls détectés] → MCPManager.call_tool()
                              ↑                        ↓
                         [rebouclage]         résultats injectés dans l'historique
                              ↓
                       réponse finale (streamée)

Serveurs MCP embarqués

`mcp_servers/traveller_map` — Carte de l'univers Traveller

Serveur MCP pour l'API travellermap.com. Écrit en TypeScript avec le SDK MCP officiel.

Crédit : Ce serveur est basé sur le projet traveller-map-mcp par @shammond42, distribué sous licence MIT. Les sources ont été intégrées dans ce projet pour être embarquées directement.

Outils disponibles

Outil	Description
`search_worlds`	Recherche un monde par nom dans l'univers Traveller
`find_route`	Calcule une route de saut entre deux mondes
`get_world_info`	Informations détaillées sur un monde (UWP décodé, atmosphère, etc.)
`get_worlds_in_jump_range`	Mondes accessibles depuis une position en N sauts
`get_jump_map`	Carte de la zone autour d'un monde
`get_subsector_map`	Image d'un sous-secteur
`render_custom_map`	Rendu de carte personnalisée
`get_sector_list`	Liste de tous les secteurs de l'univers
`get_sector_data`	Données d'un secteur (format SEC)
`get_sector_metadata`	Métadonnées d'un secteur (JSON)
`get_allegiance_list`	Liste des allégeances politiques

(Re)compiler le serveur

cd mcp_servers/traveller_map
npm install       # première fois seulement
npm run build     # compile TypeScript → dist/

Ajouter un nouveau serveur MCP

Créer un dossier mcp_servers/mon_serveur/
Y placer les sources (TypeScript, Python, ou tout autre langage)
Compiler si nécessaire (npm run build)

Déclarer dans le profil YAML :

mcp_servers:
  - name: mon-serveur
    command: node
    args: ["mcp_servers/mon_serveur/dist/index.js"]

Scripts utilitaires

Enregistrer une voix clonée

python scripts/register_voice.py --name "Ma voix" --audio sample.mp3 --language fr

Renseignez l'ID retourné dans .env :

VOICE_ID=<id_retourné>

Lister les voix disponibles

python scripts/list_voices.py

Variables d'environnement

Variable	Obligatoire	Défaut	Description
`MISTRAL_API_KEY`	✅	—	Clé API Mistral AI
`VOICE_ID`	❌	auto	ID voix Voxtral (sélection auto si vide)
`VOICE_LANGUAGE`	❌	`fr`	Langue préférée pour la sélection de voix
`SYSTEM_PROMPT`	❌	prompt Arioch	Prompt système par défaut
`TTS_PCM_SAMPLE_RATE`	❌	`24000`	Fréquence d'échantillonnage audio TTS

Dépendances Python

Package	Rôle
`mistralai`	SDK Mistral (LLM, TTS, STT Realtime)
`python-dotenv`	Chargement des variables `.env`
`sounddevice`	Capture microphone (mode vocal)
`numpy`	Traitement PCM audio
`pyyaml`	Lecture des fichiers de profil
`mcp`	Client MCP (connexion aux serveurs d'outils)

README.md

Arioch — Assistant vocal (Mistral Large + Voxtral TTS)