🎙️ Dictée Vocale Telegram & Alexa

Assistant pédagogique intelligent combinant Google Gemini AI, Telegram Bot API et Amazon Alexa pour des dictées scolaires personnalisées et interactives.

Fonctionnalités • Architecture • Workflow Pédagogique • Installation • Commandes • Configuration

---

📖 À propos

Ce projet transforme votre enceinte Amazon Alexa en véritable maître de dictée scolaire, piloté en temps réel depuis Telegram :

• Génération IA sur mesure : Google Gemini génère des textes originaux adaptés au niveau de l'enfant (du CP aux adultes).
• Découpage en syntagmes grammaticaux : Les phrases sont segmentées par groupes de sens naturels (2 à 4 mots + mots outils liés), sans coupures arbitraires.
• Régulation prosodique & pauses intelligentes : Balises SSML avec cadences adaptées et pauses de silence dédiées à l'écriture.
• Correction & Suivi Telegram : Envoi de la fiche pédagogique complète (règles clés, pièges orthographiques, texte corrigé).

---

🌟 Fonctionnalités Clés

• 🧠 Intelligence Artificielle Google Gemini :

  • Calibrage précis selon le niveau scolaire (CP, CE1, CE2, CM1, CM2, 6ème, 5ème, 4ème, 3ème, Adulte).
  • Gestion du nombre de lignes manuscrites souhaité (calibré sur ~10 mots/ligne d'écolier).
  • Fallback automatique entre modèles actifs pour une disponibilité maximale.

• 🎙️ Audio Alexa Ultra-Naturel & Pédagogique :

  • Première lecture fluide : Histoire lue sans énoncer la ponctuation pour favoriser la compréhension globale.
  • Dictée progressive : Répétition de chaque groupe de sens avec temps d'écriture suffisant.
  • Intonation de ponctuation optimisée : Pauses SSML précises (<break time="700ms"/>) et prosodie naturelle sur les mots clés (« virgule, », « point. »).

• 📱 Interface Telegram Moderne & Intuitive :

  • Assistant interactif (Wizard) avec boutons en ligne pour configurer le niveau, le thème et la longueur.
  • Mode commande directe : /dictee CE2 Les animaux de la savane 4.
  • Statut en direct : Progression étape par étape affichée dans Telegram pendant la dictée.
  • Interruption instantanée : Commande /stop pour stopper immédiatement la lecture vocale.

---

🏗️ Architecture

telegram-dictee-bot/
├── src/
│   ├── __init__.py          # Initialisation du module
│   ├── bot.py               # Handlers Telegram, Wizard interactif & retours statut
│   ├── config.py            # Validation Pydantic Settings & variables d'environnement
│   ├── gemini_client.py     # Client Google Gemini, parsing structuré & syntagmes
│   └── voice_engine.py      # Moteur vocal asynchrone, SSML & client Voice Monkey
├── tests/
│   └── test_dictation.py    # Tests unitaires & intégration asynchrone
├── .env.example             # Modèle de configuration sécurisé
├── .gitignore               # Protection stricte contre les fuites de secrets
├── docker-compose.yml       # Orchestration conteneurisée
├── Dockerfile               # Image optimisée Python 3.12 Slim
├── LICENSE                  # Licence MIT
├── requirements.txt         # Dépendances applicatives
└── README.md                # Documentation

---

🔄 Rythme & Workflow Pédagogique

flowchart TD
    A[📱 Utilisateur lance /dictee] --> B[🧠 Gemini génère la dictée structurée]
    B --> C[📋 Telegram affiche le texte complet et lance le compte à rebours]
    C --> D[🔊 Étape 1 : Présentation 90% & Première lecture globale 70%]
    D --> E[⏸️ Pause de préparation 8s pour prendre le stylo]
    E --> F[✍️ Étape 2 : Dictée par syntagmes 60%]
    F -->|1ère lecture du groupe + Pause écriture 6s| G[Répétition du groupe 60% + Pause 6s]
    G -->|Toutes les phrases complétées| H[🔍 Étape 3 : Relecture globale 70%]
    H --> I[📊 Telegram envoie la correction détaillée et la grille d'évaluation]

Loading

---

🚀 Installation & Démarrage Rapide

Méthode 1 : Déploiement Docker (Recommandé)

1. Cloner le dépôt :

   git clone https://github.com/zaidrabeh/Auto-Dict-e-BOT.git
   cd Auto-Dict-e-BOT

2. Créer le fichier de configuration .env :

   cp .env.example .env
   nano .env

3. Lancer avec Docker Compose :

   docker compose up -d --build

4. Vérifier les journaux :

   docker compose logs -f

---

Méthode 2 : Exécution Locale (Python 3.12+)

# 1. Créer l'environnement virtuel
python3 -m venv .venv
source .venv/bin/activate

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

# 3. Configurer l'environnement
cp .env.example .env
# Éditer .env avec vos clés

# 4. Lancer le bot
python -m src.bot

---

🕹️ Guide des Commandes

Commande	Description	Exemple
/start	Message d'accueil et présentation des fonctionnalités	/start
/dictee	Ouvre l'assistant interactif (choix niveau, thème, lignes)	/dictee
/dictee [args]	Lancement direct rapide avec paramètres	/dictee CM1 La forêt 5
/stop	Interrompt immédiatement la dictée vocale en cours	/stop
/stats	Affiche la configuration active et les vitesses vocales	/stats
/aide	Guide détaillé d'utilisation et exemples	/aide

---

⚙️ Variables d'Environnement

Variable	Description	Valeur par défaut
TELEGRAM_BOT_TOKEN	Token du bot Telegram fourni par @BotFather	Requis
GEMINI_API_KEY	Clé API Google AI Studio	Requis
GEMINI_MODEL	Modèle Gemini principal	gemini-3.7-flash
VOICEMONKEY_API_KEY	Token API Voice Monkey	Requis
VOICEMONKEY_DEVICE	Nom de l'enceinte Alexa ciblée	Requis
VOICEMONKEY_API_URL	URL de l'API Voice Monkey	https://api-v2.voicemonkey.io/announcement
SPEED_RATE_INTRO	Vitesse de présentation du titre et consignes	90%
SPEED_RATE_READING	Vitesse de lecture globale initiale	70%
SPEED_RATE_DICTEE	Vitesse de diction pendant l'écriture	60%
SPEED_RATE_REVIEW	Vitesse de relecture complète finale	70%

---

🧪 Tests Unitaires & Intégration

Pour exécuter la suite de tests avec pytest :

PYTHONPATH=. pytest tests/test_dictation.py -v

---

📄 Licence

Ce projet est sous licence MIT. Libre d'utilisation, de modification et de distribution.