VocalGuard

Système moderne de gestion d'appels avec interface vocale intelligente, basé sur callattendant.

Fonctionnalités

• Interface vocale moderne avec reconnaissance et synthèse vocale
• Blocage intelligent des appels indésirables avec OSINT
• Enrichissement OSINT des numéros (réputation, lieu, opérateur) via phone_number_profiles
• Prospection Entreprises : import Excel .xlsx (uniquement sans website), catégories normalisées (M2M), pagination/filtres/suppression, modale de détails (onglets).
• Services de réputation externes (NOMOROBO pour USA, SHOULDIANSWER pour hors USA)
• Page Appels avec recherche intelligente et filtres avancés (statut, réputation)
• Messagerie vocale avancée
• Interface web moderne et réactive (Next.js + TypeScript)
• API REST complète
• Support des modems USB modernes
• Intégration avec services de reconnaissance vocale (Whisper, VOSK) et capture micro via sounddevice
• Base de données moderne avec SQLAlchemy
• Architecture modulaire et extensible avec patterns modernes (Repository, Service Layer, Event-Driven)

Technologies

• Python 3.9+ (3.13 recommandé)
• FastAPI pour l'API REST
• SQLAlchemy pour la base de données
• Whisper/VOSK pour la reconnaissance vocale
• pyttsx3/gTTS pour la synthèse vocale
• Next.js + React (TypeScript) pour l'interface web

Installation

Prérequis

• Python 3.13 (production)
• Modem USB compatible (US Robotics 5637, Zoom 3095, ou autres modems Conexant)
• Raspberry Pi 3B+ ou mieux (ou système Linux compatible)

Installation rapide

Linux/Mac

chmod +x run.sh
./run.sh

Windows

.\run.ps1

Options utiles :

# Mode une seule fenêtre (backend + celery en arrière-plan + logs dans logs/)
.\run.ps1 -SingleWindow

Environnement conda conseillé (prod Python 3.13)

conda create -n vocalguard python=3.13 -y
conda activate vocalguard
pip install -r requirements.txt

Installation manuelle

# Créer un environnement virtuel
python3 -m venv venv
source venv/bin/activate  # Sur Windows: venv\Scripts\activate

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

# Créer les dossiers nécessaires
mkdir -p logs audio_cache data

# Configuration
cp config/config.example.yaml config/config.yaml
# Éditer config/config.yaml selon vos besoins

Lancement

En développement (backend uniquement) :

cd VocalGuard
uvicorn backend.main:app --reload

• L'API sera accessible sur http://localhost:8000
• La documentation de l'API sera disponible sur http://localhost:8000/docs

Le backend utilise par défaut une base SQLite locale vocalguard.db à la racine.
En production, vous pouvez passer sur PostgreSQL en ajustant database_url dans la configuration.

Profils d'environnement (.env et .env.prod)

• Mode standard: Config charge .env
• Mode production-like local: Config charge .env.prod si VG_ENV=prod

Exemple PowerShell:

$env:VG_ENV="prod"
python -m backend.main

Structure du projet

VocalGuard/
  backend/                   # Backend Python (FastAPI, modem, OSINT, RDV, devis...)
    api/                     # API REST (routes + modèles Pydantic)
    core/                    # Cœur téléphonie (modem, CallManager, events, config)
    voice/                   # Reconnaissance et synthèse vocale
    services/                # Logique métier (appels, blocage, OSINT, conversation...)
    repositories/            # Repositories SQLAlchemy
    database/                # Modèles + initialisation DB
    osint/                   # Service OSINT persistant (PhoneNumberProfile)
    workers/                 # Tâches Celery (OSINT, futurs jobs)
    ai/                      # Intégration IA locale (patterns + ML)
    web/                     # Ancienne interface statique (optionnelle)
    domain/                  # Espace pour les services métier plus hauts niveaux
    settings/                # Surcouche de configuration si besoin
    main.py                  # Point d'entrée FastAPI (backend.main:app)
    celery_app.py            # Configuration Celery
    requirements.txt         # Dépendances backend

  frontend/                  # Interface web (Next.js + TypeScript)
    src/
      app/                   # Pages: dashboard, appels, RDV, devis, clients, etc.
      components/            # Layout, sidebar, topbar, tables, cartes...
      services/              # Clients d'API typés (calls, osint, crm, settings)
      styles/                # Styles globaux

  config/                    # Fichiers YAML de config (modem, réponses...)
  docs/                      # Documentation (ARCHITECTURE, OSINT, etc.)
  logs/                      # Logs backend
  vocalguard.db              # Base SQLite de développement
  requirements.txt           # Dépendances racine (backend)
  README.md                  # Ce fichier

Documentation

• Guide d'installation
• Architecture v3 (backend + frontend)
• Architecture v2 (améliorée) - historique
• Architecture originale - historique
• Module OSINT - Enrichissement des numéros de téléphone
• Page Appels et OSINT - Liste des appels, filtres, recherche intelligente
• API Agenda - Endpoints agenda, settings et jours non travaillés
• Services de réputation - NOMOROBO / SHOULDIANSWER (type callattendant)
• Mise en production (RPi) - Service systemd, demarrage au boot, logs
• CI/CD - Tests GitHub Actions, déploiement auto prod, cron update
• Résumé des améliorations
• Améliorations par rapport à callattendant
• Test vocal (micro, patterns, intents)
• Intents IVR (strategies question-reponse)

API

Une fois l'application lancée, accédez à :

• API Documentation : http://localhost:8000/docs
• API Alternative : http://localhost:8000/redoc
• Health Check : http://localhost:8000/health

Entreprises (prospection)

• Import : POST /api/v1/entreprises/import (fichier .xlsx, filtre automatique: conserve uniquement les lignes sans website)
• Suivi temps réel : WebSocket GET /ws/events avec events:
  • entreprise.import.started
  • entreprise.import.progress
  • entreprise.import.completed
  • osint.profile.completed / osint.profile.failed (fin de tâches Celery, relayées via l’API)
• Liste : GET /api/v1/entreprises (pagination + filtres q, city, category, has_phone)

UI : page Entreprises (frontend) avec jauge de progression, liste compacte, filtres, suppression en masse et modale de détails multi-onglets.

Exemples d'utilisation

Lister les appels

curl http://localhost:8000/api/v1/calls

Ajouter un appelant à la liste blanche

curl -X POST http://localhost:8000/api/v1/callers \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+33123456789", "is_whitelisted": true}'

Récupérer les messages vocaux

curl http://localhost:8000/api/v1/voicemails

Enrichir un numéro via OSINT

curl http://localhost:8000/api/v1/osint/phone/+33123456789

Vérifier la réputation d'un numéro

curl http://localhost:8000/api/v1/osint/reputation/+33123456789

Agenda (nouveaux endpoints)

curl http://localhost:8000/api/v1/agenda
curl http://localhost:8000/api/v1/agenda/settings

Développement

Structure du projet

Le projet suit une architecture modulaire avec patterns modernes :

• backend/core/ : Cœur du système (modem, gestion d'appels, événements)
• backend/repositories/ : Pattern Repository pour l'accès aux données
• backend/services/ : Couche Service pour la logique métier
• backend/voice/ : Module vocal (reconnaissance et synthèse)
• backend/api/ : API REST FastAPI avec dependency injection
• backend/database/ : Modèles et gestion de base de données

Voir ARCHITECTURE_V3.md pour plus de détails sur l'architecture unifiée backend/frontend.

Tests

pytest tests/

Tests vocaux (micro + TTS)

Deux scripts permettent de tester la voix en local sans modem :

• Conversation par intents (reco + patterns + WAV telephonique 8 kHz) :

  python scripts/test_patterns_voice.py

  Les strategies question-reponse sont definies dans config/intents_ivr.yaml. Les reponses sont generees en WAV dans ivr_wav/.

Prerequis : sounddevice (capture micro), et optionnellement ffmpeg pour la conversion MP3 vers WAV 8 kHz. Voir scripts/README_VOICE_TEST.md et config/README_INTENTS_IVR.md.

Contribution

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.

Licence

MIT - Voir le fichier LICENSE

Remerciements

Basé sur le projet callattendant de emxsys.