Recréer Guide-IA avec corrections HTTP et bon sub_url

Guide-IA.-.md

@@ -0,0 +1,156 @@
+# Guide-IA
+
+## Introduction
+L'IA dans **pronote-sync** permet de générer des **synthèses automatiques** à partir des données récupérées depuis Pronote (cours, devoirs, notes, etc.). Cette fonctionnalité est **optionnelle** et **désactivée par défaut** (`AI_ENABLED=false`). Elle n'est pas requise pour la synchronisation CalDAV ou XMPP.
+
+Pour une référence complète des variables de configuration, consultez le [tableau des variables dans la page Configuration](Configuration).
+
+---
+
+## Fournisseurs supportés
+Le projet supporte trois types de fournisseurs IA :
+
+- **`openai`** : API officielle d'OpenAI.
+- **`litellm`** : Proxy LiteLLM, qui permet d'unifier plusieurs fournisseurs derrière une seule API compatible OpenAI.
+- **`openai-compatible`** : Toute API compatible OpenAI (OpenRouter, Ollama, vLLM, etc.) avec une URL de base personnalisée.
+
+---
+
+## OpenAI
+
+### Obtenir une clé API
+1. Rendez-vous sur [platform.openai.com](https://platform.openai.com).
+2. Connectez-vous ou créez un compte.
+3. Allez dans **Dashboard** → **API keys**.
+4. Cliquez sur **Create new secret key**.
+5. Copiez la clé générée (elle commence par `sk-...`).
+
+### Configuration
+- **URL de base** : `https://api.openai.com/v1`
+- **Modèles recommandés** : `gpt-4o`, `gpt-4o-mini`, `o3-mini`, etc.
+
+### Exemple de configuration
+```ini
+AI_ENABLED=true
+AI_PROVIDER=openai
+AI_API_KEY=sk-votre-cle-api
+AI_MODEL=gpt-4o-mini
+```
+
+---
+
+## OpenRouter
+
+OpenRouter est un service qui agrège plusieurs fournisseurs IA (OpenAI, Anthropic, DeepSeek, Meta, etc.) sous une seule API compatible OpenAI.
+
+### Obtenir une clé API
+1. Rendez-vous sur [openrouter.ai/keys](https://openrouter.ai/keys).
+2. Connectez-vous ou créez un compte.
+3. Cliquez sur **Create Key**.
+4. Copiez la clé générée.
+
+### Configuration
+- **Fournisseur** : `openai-compatible`
+- **URL de base** : `https://openrouter.ai/api/v1`
+- **Modèles** : Format `fournisseur/modele`, par exemple :
+  - `openai/gpt-4o`
+  - `anthropic/claude-3.5-sonnet`
+  - `deepseek/deepseek-chat`
+  - `meta-llama/llama-3.3-70b-instruct`
+
+### Exemple de configuration
+```ini
+AI_ENABLED=true
+AI_PROVIDER=openai-compatible
+AI_BASE_URL=https://openrouter.ai/api/v1
+AI_API_KEY=votre-cle-openrouter
+AI_MODEL=openai/gpt-4o-mini
+AI_ALLOW_INSECURE_HTTP=false
+```
+
+---
+
+## Ollama (local)
+
+Ollama permet d'exécuter des modèles IA localement. **pronote-sync** peut s'y connecter via l'endpoint de compatibilité OpenAI.
+
+### Prérequis
+- Ollama installé et fonctionnel sur votre machine.
+- Un modèle téléchargé (ex. `llama3.2`, `mistral`, `qwen2.5`).
+
+### Configuration
+- **URL de base** : `http://127.0.0.1:11434/v1` (endpoint de compatibilité OpenAI d'Ollama).
+- **Clé API** : Ollama n'exige pas de clé API, mais la configuration attend une valeur non vide. Utilisez une valeur arbitraire comme `local-not-required`.
+- **Modèles** : Utilisez le nom du modèle téléchargé (ex. `llama3.2`).
+
+### Lister les modèles disponibles
+```bash
+ollama list
+```
+
+### Exemple de configuration
+```ini
+AI_ENABLED=true
+AI_PROVIDER=openai-compatible
+AI_BASE_URL=http://127.0.0.1:11434/v1
+AI_API_KEY=local-not-required
+AI_MODEL=llama3.2
+AI_ALLOW_INSECURE_HTTP=true
+```
+
+---
+
+## LiteLLM (proxy)
+
+[LiteLLM](https://litellm.ai/) est un proxy open-source qui expose une API unifiée compatible OpenAI pour plusieurs fournisseurs (OpenAI, Anthropic, Azure, etc.).
+
+### Configuration
+- **Fournisseur** : `litellm`
+- **URL de base** : Par défaut, `http://localhost:4000/v1` (si LiteLLM est exécuté localement).
+- **Clé API** : Configurez une clé maîtresse dans le `config.yaml` de LiteLLM ou utilisez celle générée au démarrage.
+
+### Exemple de configuration
+```ini
+AI_ENABLED=true
+AI_PROVIDER=litellm
+AI_BASE_URL=http://localhost:4000/v1
+AI_API_KEY=sk-litellm-master-key
+AI_MODEL=gpt-4o-mini
+```
+
+---
+
+## Sécurité
+
+### HTTPS obligatoire par défaut
+- Par défaut, seules les URL en **HTTPS** sont acceptées pour `AI_BASE_URL`. Les URL en HTTP sont rejetées.
+
+### Autoriser HTTP avec `AI_ALLOW_INSECURE_HTTP`
+- Lorsque `AI_ALLOW_INSECURE_HTTP=true`, les URL en **HTTP sont acceptées pour n'importe quel hôte** (pas seulement localhost).
+- ⚠️ **Avertissement** : Cette option désactive la protection HTTPS pour toutes les URL du provider `openai-compatible`. Ne l'utilisez que pour des connexions locales (ex. Ollama sur `127.0.0.1`) ou dans un environnement de confiance. En production, utilisez toujours HTTPS.
+- Exemple : `http://127.0.0.1:11434/v1` (Ollama local).
+
+### Clé API
+- **Jamais dans l'URL** : Les credentials dans l'URL (ex. `user:pass@host`) sont **rejetés**.
+- **Pas de paramètres sensibles dans la query string** : Les paramètres comme `?token` ou `?api_key=...` sont **rejetés**, même sans valeur.
+- **Stockage sécurisé** : `AI_API_KEY` est stockée en `SecretStr` et masquée dans les logs.
+
+### URL complète requise
+- **Aucune manipulation automatique de `/v1`** : L'URL doit être **complète et correcte**. Par exemple, `https://openrouter.ai/api/v1` est valide, mais `https://openrouter.ai/api` ne le sera pas.
+
+### Mode dégradé
+- Si la configuration est **invalide** (URL malformée, clé manquante, etc.), la factory retourne `None` avec un **avertissement** (mode dégradé). Le pipeline fonctionne alors **sans IA**.
+
+---
+
+## Mode dégradé à l'exécution
+
+Si l'IA échoue **pendant l'exécution** (erreur réseau, clé invalide, quota dépassé, etc.) :
+- Le pipeline retourne un message **sans synthèse**.
+- La synchronisation **CalDAV/XMPP reste fonctionnelle** et n'est pas affectée.
+
+---
+
+## Liens utiles
+→ [Configuration](Configuration) — Tableau complet des variables IA.
+→ [Sécurité](Sécurité) — Bonnes pratiques pour la gestion des secrets.