Beta/README.md

# Superviseur Bot (Bêta)

Bot Discord IA d'assistance et de modération avancée, utilisant **Ollama** pour l'inférence LLM locale.

## Fonctionnalités

- **IA conversationnelle** : Répond aux questions et exécute des actions sur Discord via JSON
- **Modération silencieuse** : Scan de toxicité de chaque message via LLM en arrière-plan
- **Gestion vocale** : Transcription Whisper en temps réel + détection de mots-clés
- **Mémoire utilisateur** : Historique par utilisateur avec résumé automatique
- **Dispatch d'insights** : Coordination staff avec boutons d'acceptation Discord
- **RGPD** : Purge automatique des données > 30 jours

## Installation

### Prérequis

- Python 3.9+
- **Ollama** installé et en cours d'exécution (https://ollama.com)
- Modèle `gpt-oss:20b` disponible dans Ollama

### Dépendances

```bash
pip install -r requirements.txt
```

### Configuration Ollama

```bash
# Pull le modèle dans Ollama
ollama pull gpt-oss:20b
```

### Configuration

Créer un fichier `.env` à la racine du dossier `beta/` :

```bash
# Discord
DISCORD_TOKEN=your_discord_bot_token
GUILD_ID=your_guild_id

# LLM
OLLAMA_MODEL=gpt-oss:20b

# Staff
ADMIN_IDS=123456789,987654321
PRIMARY_ASSETS_IDS=111222333,444555666

# Channel d'introspection
INTROSPECTION_CHANNEL_ID=123456789
```

## Utilisation

```bash
cd beta
python main.py
```

Le bot va :
1. Se connecter à Ollama
2. Initialiser tous les composants (mémoire, modération, vocal)
3. Se connecter à Discord
4. Traiter les messages

## Architecture

```
beta/
├── main.py              # Point d'entrée
├── core/
│   ├── bot.py           # Classe principale Superviseur
│   ├── llm.py           # Gestionnaire LLM (Ollama API)
│   ├── action_router.py # Routage des actions IA → Discord
│   ├── dispatcher.py    # Dispatch d'insights vers staff
│   ├── voice.py         # Gestion vocale + Whisper
│   ├── tasks.py         # Tâches de fond
│   ├── messaging.py     # Envoi de messages
│   └── permissions.py   # Whitelist et permissions
├── brain/
│   ├── memoire.py       # Mémoire utilisateur (JSON/Redis)
│   ├── moderation.py    # Modération IA + SQLite
│   └── infos_serveurs.py # Infos serveur
├── commandes/
│   ├── security/        # kick, ban, mute, warn, purge...
│   ├── salons/          # Créer, supprimer, modifier salons
│   ├── roles/           # Créer, supprimer, modifier rôles
│   └── autres/          # Config, status, ping, etc.
├── data/                # Logs, DB SQLite
└── memoires/            # Historique utilisateur (JSON)
```

## Actions IA

Le bot peut exécuter les actions suivantes via LLM :
- `CREATE_CHANNEL`, `DELETE_CHANNEL`, `MODIFY_CHANNEL`
- `CREATE_ROLE`, `DELETE_ROLE`, `ADD_ROLE_TO_USER`
- `KICK`, `BAN`, `UNBAN`, `MUTE`, `TIMEOUT`, `WARN`, `PURGE`
- `JOIN_VOICE`, `LEAVE_VOICE`
- `ALERT`, `INSIGHT`, `FORGET_USER`, `READ_LOGS`

## Support

1. Vérifier les logs dans `data/bot.log`
2. Activer le mode debug : `LOG_LEVEL=DEBUG`
3. Vérifier qu'Ollama est actif : `ollama list`
python test_llama_integration.py
```

This will test:
- Model loading
- LLMManager functionality
- Text generation
- JSON extraction
- Performance

## Performance

### Expected Performance

With the 120B model and optimized parameters:
- **Context**: 4096 tokens
- **Threads**: 16 CPU threads
- **Memory**: ~64GB RAM usage
- **Response time**: 5-15 seconds for typical queries
- **Concurrency**: 4 simultaneous requests

### Performance Tips

1. **Use mlock**: Prevents swapping to disk
2. **Optimize threads**: Match your CPU core count
3. **Monitor memory**: Ensure sufficient RAM
4. **Batch size**: Adjust based on your system

### Monitoring

The bot includes built-in metrics:
- LLM request counts
- Success/failure rates
- Response times
- Memory usage

Enable metrics server with `METRICS_ENABLED=1`.

## Troubleshooting

### Common Issues

1. **Model not found**
   - Check `MODEL_PATH` in `.env`
   - Verify model file exists
   - Check file permissions

2. **Memory errors**
   - Ensure sufficient RAM
   - Reduce `n_ctx` or `n_threads`
   - Disable `use_mlock` for testing

3. **Slow responses**
   - Check CPU usage
   - Verify model is in RAM
   - Reduce `n_threads` if CPU is overloaded

4. **Import errors**
   - Install `llama-cpp-python` with proper backend
   - Check Python version compatibility

### Debug Mode

Enable verbose logging by setting:
```bash
LOG_LEVEL=DEBUG
```

### Model Loading Issues

If model loading fails:
1. Check model file integrity
2. Verify GGUF format compatibility
3. Try with `use_mlock=False`
4. Reduce model size for testing

## Migration Notes

### From Ollama

If you were previously using Ollama:

1. **Remove Ollama**: No longer needed
2. **Update configuration**: Remove Ollama URLs
3. **Install llama-cpp-python**: Add to requirements
4. **Test thoroughly**: Verify all functionality

### Code Changes

Key files modified:
- `beta.py`: Main entry point with model loading
- `superviseur/llm.py`: LLMManager with llama-cpp-python
- `superviseur/bot.py`: Bot integration
- `requirements.txt`: Updated dependencies

## Security

### Data Privacy

- No external network calls
- All processing local
- GDPR compliance maintained
- Memory management for sensitive data

### Model Security

- Local model storage
- No external dependencies
- Controlled access
- Proper cleanup

## Support

For issues or questions:
1. Check the troubleshooting section
2. Run the test script
3. Enable debug logging
4. Check system resources
5. Verify model compatibility

## Contributing

When contributing to this project:
1. Test with the test script
2. Verify performance
3. Update documentation
4. Follow existing code patterns
5. Ensure backward compatibility

## License

This project is licensed under the same license as the original Superviseur bot.