README.md

---
title: Routeur Ia Api
emoji: 📊
colorFrom: pink
colorTo: purple
sdk: docker
pinned: false
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# CAPL Routeur IA API

API sécurisée pour l'interaction avec des agents IA basés sur LangGraph, avec support multi-modèles (OpenAI et Mistral AI).

## 🚀 Fonctionnalités

- ✅ **Authentification JWT** pour sécuriser l'accès
- ✅ **Completion texte** avec support du streaming (Server-Sent Events)
- ✅ **Multi-modèles**: OpenAI (GPT-4, GPT-3.5) et Mistral AI (Large, Medium, Small, Tiny)
- ✅ **Multi-agents**: Architecture extensible pour différents types d'agents LangGraph
- ✅ **Transcription audio**: Conversion audio vers texte avec OpenAI Whisper
- ✅ **WebSocket**: Communication temps réel bidirectionnelle
- ✅ **Architecture Clean**: Séparation domain/services/api selon les principes SOLID

## 📋 Prérequis

- Python 3.12+
- Clés API OpenAI et Mistral AI

## 🛠️ Installation

1. **Cloner le repository**
```bash
git clone <repository-url>
cd routeur_ia_api
```

2. **Créer un environnement virtuel**
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows
```

3. **Installer les dépendances**
```bash
pip install -r requirements.txt
```

4. **Configurer les variables d'environnement**

Créez un fichier `.env` à la racine du projet (voir `.env.example` pour référence):

```env
# API Keys
OPENAI_API_KEY=sk-your-openai-key-here
MISTRALAI_API_KEY=your-mistral-key-here

# JWT Security
JWT_SECRET_KEY=your-secret-key-here-change-in-production
JWT_ALGORITHM=HS256
JWT_EXPIRATION_MINUTES=60

# API Config
API_TITLE=CAPL Routeur IA API
API_VERSION=1.0.0
ENVIRONMENT=development
```

**⚠️ IMPORTANT**: Changez `JWT_SECRET_KEY` en production avec une valeur sécurisée!

## 🚀 Lancement

### Mode développement

```bash
python app.py
```

ou avec uvicorn directement:

```bash
uvicorn app:app --reload --port 7860
```

### Mode production

```bash
uvicorn app:app --host 0.0.0.0 --port 7860 --workers 4
```

### Avec Docker

```bash
docker build -t routeur-ia-api .
docker run -p 7860:7860 --env-file .env routeur-ia-api
```

## 📚 Documentation API

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

- **Swagger UI**: http://localhost:7860/docs
- **ReDoc**: http://localhost:7860/redoc

## 🔐 Authentification

### 1. Obtenir un token JWT

```bash
curl -X POST "http://localhost:7860/auth/token" \
  -H "Content-Type: application/json"
```

Réponse:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

### 2. Utiliser le token

Incluez le token dans le header `Authorization` de toutes vos requêtes:

```bash
curl -X GET "http://localhost:7860/models" \
  -H "Authorization: Bearer <votre-token>"
```

## 📖 Utilisation

### Liste des modèles disponibles

```bash
curl -X GET "http://localhost:7860/models" \
  -H "Authorization: Bearer <token>"
```

### Liste des agents disponibles

```bash
curl -X GET "http://localhost:7860/agents" \
  -H "Authorization: Bearer <token>"
```

### Completion simple (non-streaming)

```bash
curl -X POST "http://localhost:7860/completion" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Bonjour, comment vas-tu?",
    "model": "gpt-4o",
    "agent_type": "simple",
    "stream": false,
    "temperature": 0.7
  }'
```

### Completion avec streaming (SSE)

```bash
curl -X POST "http://localhost:7860/completion" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "message": "Raconte-moi une histoire",
    "model": "gpt-4o",
    "stream": true
  }'
```

### Transcription audio

```bash
curl -X POST "http://localhost:7860/transcription" \
  -H "Authorization: Bearer <token>" \
  -F "file=@audio.mp3" \
  -F "language=fr"
```

### WebSocket temps réel

```javascript
const ws = new WebSocket('ws://localhost:7860/realtime/ws');

ws.onopen = () => {
  console.log('Connected');
  
  // Envoyer un message
  ws.send(JSON.stringify({
    type: 'message',
    payload: { text: 'Hello!' }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};
```

## 🏗️ Architecture

```
routeur_ia_api/
├── config/           # Configuration et settings
├── core/             # Sécurité JWT et dépendances
├── domain/           # Modèles et enums du domaine
├── services/         # Services métier (LLM, Agent, Transcription)
├── graphs/           # Graphes LangGraph
├── api/
│   ├── routes/       # Routes API
│   └── middleware.py # Middleware personnalisé
├── app.py            # Point d'entrée FastAPI
└── requirements.txt  # Dépendances Python
```

### Principes SOLID appliqués

- **Single Responsibility**: Chaque service a une responsabilité unique
- **Open/Closed**: Agents extensibles via le registre sans modifier l'API
- **Liskov Substitution**: Tous les LLM respectent l'interface `BaseChatModel`
- **Interface Segregation**: Interfaces minimales et spécifiques
- **Dependency Inversion**: Dépendances abstraites via injection

## 🤖 Ajouter un nouvel agent

1. Créez un nouveau graphe dans `graphs/`:

```python
# graphs/custom_graph.py
from langgraph.graph import StateGraph, END

def create_custom_graph(llm):
    # Votre logique
    workflow = StateGraph(CustomState)
    workflow.add_node("custom", custom_node)
    workflow.set_entry_point("custom")
    workflow.add_edge("custom", END)
    return workflow.compile()
```

2. Enregistrez-le dans le registre:

```python
# services/agent_registry.py
from graphs.custom_graph import create_custom_graph

agent_registry.register_agent(
    AgentType.CUSTOM,
    create_custom_graph,
    "Description de votre agent"
)
```

3. Utilisez-le via l'API sans changement de code!

## 🧪 Tests

```bash
# À implémenter
pytest tests/
```

## 📊 Monitoring avec LangSmith

Activez LangSmith dans `.env`:

```env
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langsmith-key
LANGCHAIN_PROJECT=routeur-ia
```

## 🔒 Sécurité

- ✅ Authentification JWT obligatoire
- ✅ Validation Pydantic stricte
- ✅ Headers de sécurité (CORS, CSP, etc.)
- ✅ Gestion des erreurs sécurisée
- ⚠️ En production: Utilisez HTTPS uniquement
- ⚠️ En production: Restreignez CORS aux origines autorisées
- ⚠️ En production: Utilisez un secret JWT robuste

## 📝 TODO / Roadmap

- [ ] Tests unitaires et d'intégration
- [ ] Implémentation complète WebRTC avec aiortc
- [ ] Agent RAG avec base vectorielle
- [ ] Agent avec outils (recherche web, calculatrice)
- [ ] Rate limiting
- [ ] Cache des réponses
- [ ] Métriques Prometheus
- [ ] CI/CD pipeline

## 🤝 Contribution

Les contributions sont les bienvenues! Veuillez suivre les principes SOLID et Clean Architecture.

## 📄 Licence

[À définir]

## 👥 Auteurs

CAPL - Routeur IA Team

---

**Note**: Cette API est en développement actif. Certaines fonctionnalités (notamment WebRTC complet) sont des placeholders et nécessitent une implémentation complète pour la production.