# Chat IA

Le Chat IA est une interface conversationnelle sur les données de votre application. Les utilisateurs posent des questions et émettent des commandes en langage naturel ; la plateforme les traduit en requêtes, mutations et déclenchements d'automatisations autorisés, puis renvoie une réponse structurée. Il est disponible à la fois comme point d'accès REST (`POST /api/ai/chat`) et comme composant de page intégrable (`type: ai-chat`).

Le chat est **natif** une fois `AI_PROVIDER` configuré — la plateforme détecte automatiquement chaque table et champ, aucun YAML par table n'est donc nécessaire pour la prise en charge des requêtes. Toutes les actions effectuées via le chat sont régies par le RBAC et les permissions au niveau des champs de l'utilisateur demandeur, et sont écrites dans le journal d'activité pour une auditabilité complète.

## Ce que le chat peut et ne peut pas faire

| Le chat **peut**                                                                            | Le chat **ne peut pas**                                                         |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Interroger des enregistrements à travers les tables en langage naturel                      | Modifier les schémas de table (ajouter/supprimer des champs, changer des types) |
| Créer, mettre à jour et supprimer des enregistrements (opérations destructrices confirmées) | Créer ou modifier des automatisations                                           |
| Déclencher des automatisations à déclenchement manuel que l'utilisateur peut exécuter       | Accéder aux enregistrements hors des permissions RBAC de l'utilisateur          |
| Maintenir le contexte conversationnel au sein d'une session                                 | Contourner les permissions au niveau des champs                                 |

## Architecture

```
Message utilisateur
    │
    ▼
POST /api/ai/chat ──▶ Résoudre l'agent (ou IA par défaut) ──▶ Injecter le contexte
    │                                                            │
    │   ┌────────────────────────────────────────────────────────┘
    ▼   ▼
Fournisseur IA ──▶ Appels d'outils (requête, mutation, déclenchement) ──▶ Vérification RBAC ──▶ Journal d'activité
    │
    ▼
Réponse structurée (texte de réponse + actions effectuées)
```

Le chat résout un agent (lorsqu'un est nommé) ou revient au fournisseur IA par défaut. Le modèle interagit avec les données exclusivement par **appels d'outils** — des opérations structurées que Sovrium exécute après une vérification RBAC — plutôt que de fabriquer des données en texte libre.

## Utiliser le chat comme composant de page

Le composant `ai-chat` intègre un panneau de chat dans n'importe quelle page.

```yaml
pages:
  - name: dashboard
    path: /dashboard
    components:
      - type: ai-chat
        agent: support-agent # optionnel — revient au fournisseur IA par défaut
        placeholder: Posez une question sur vos tickets...
        chatHeight: 600
        showHistory: true
        allowAttachments: false
```

| Propriété          | Description                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `agent`            | Nom de l'agent depuis `app.agents[]`. Omettre pour utiliser le fournisseur IA par défaut. |
| `placeholder`      | Texte d'invite pour le champ de saisie du chat.                                           |
| `chatHeight`       | Hauteur du conteneur de chat en pixels (doit être > 0).                                   |
| `showHistory`      | Si l'historique de conversation précédent doit être affiché au chargement.                |
| `allowAttachments` | Si les pièces jointes de fichiers sont autorisées dans le chat.                           |

## Utiliser l'API REST

```http
POST /api/ai/chat
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "message": "How many open tickets are there?",
  "context": { "table": "tickets" },
  "sessionId": "sess_abc123"
}
```

```json
{
  "reply": "There are 42 open tickets — 5 critical, 12 high, 18 medium, 7 low.",
  "actions": [
    {
      "type": "query",
      "table": "tickets",
      "description": "Counted tickets where status = 'open', grouped by priority"
    }
  ],
  "sessionId": "sess_abc123"
}
```

## Requêtes d'enregistrements

Lorsque `AI_PROVIDER` est défini, l'API de chat traduit nativement les questions en langage naturel en requêtes SQL/API contre les tables **autorisées** de l'utilisateur, les exécute, et formate le résultat dans la conversation. Aucune configuration n'est requise — la plateforme introspecte le schéma automatiquement. Les requêtes n'atteignent jamais des tables ou des champs que le rôle demandeur ne peut pas lire.

## Mutations d'enregistrements

Le chat peut créer, mettre à jour et supprimer des enregistrements pour le compte de l'utilisateur. Les mutations respectent les permissions au niveau des champs (un rôle qui ne peut pas écrire un champ ne peut pas le définir via le chat), et les **opérations destructrices nécessitent une confirmation** avant de s'exécuter. Chaque mutation est enregistrée dans le journal d'activité avec l'utilisateur qui l'a initiée.

## Déclencher des automatisations

Le chat peut invoquer les automatisations à **déclenchement manuel** que l'utilisateur est autorisé à exécuter, puis rapporter le résultat dans la conversation. Le chat ne peut pas exécuter des automatisations d'autres types de déclenchement, ni créer ou éditer des définitions d'automatisation.

## Appel d'outils

Le chat est construit sur l'appel de fonctions/outils. Sovrium présente au modèle un ensemble de définitions d'outils (requête, mutation, déclenchement) ; le modèle retourne un `tool_call` ; Sovrium l'exécute **après une vérification RBAC** et renvoie le résultat au modèle, qui compose alors la réponse finale. L'appel d'outils structuré — plutôt que la génération de données en texte libre — est ce qui maintient le chat ancré et auditable.

```
Message utilisateur → Fournisseur IA (avec définitions d'outils)
                    │
                    ▼
              L'IA retourne tool_call
                    │
                    ▼
         Sovrium exécute l'outil (RBAC vérifié)
                    │
                    ▼
         Résultat de l'outil renvoyé à l'IA
                    │
                    ▼
              L'IA retourne la réponse textuelle finale
```

## Réponses en streaming

Le chat prend en charge le streaming Server-Sent Events (SSE) afin que les utilisateurs voient la génération de texte progressive au lieu d'attendre la réponse complète.

| Comportement                    | Détail                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Livraison par fragments         | Le contenu partiel du message arrive sous forme de fragments SSE, transmis en temps réel à mesure que le fournisseur les émet. |
| Marqueur d'achèvement           | L'événement SSE final porte un marqueur `[DONE]` ; le message complet est assemblé à partir de tous les fragments.             |
| Persistance                     | Les messages diffusés sont persistés dans l'historique de conversation une fois terminés.                                      |
| Permissions                     | Le streaming applique le même RBAC que le chat non diffusé.                                                                    |
| Temps jusqu'au premier fragment | Un `504` est retourné lorsque le fournisseur n'envoie aucun premier fragment avant `AI_CHAT_STREAM_TIMEOUT`.                   |
| Coupure de connexion            | Gérée gracieusement — une réponse partielle est rejetée si la connexion se coupe avant l'achèvement.                           |

## Limitation de débit

Les limites de débit par utilisateur protègent le fournisseur IA d'une surcharge et plafonnent le coût. Les limites sont configurées via des variables d'environnement, et non le schéma de l'application.

| Variable                 | Description                                                                  | Défaut   |
| ------------------------ | ---------------------------------------------------------------------------- | -------- |
| `AI_CHAT_RATE_LIMIT`     | Messages autorisés par fenêtre, par utilisateur.                             | `60`     |
| `AI_CHAT_RATE_WINDOW`    | Durée de la fenêtre de limitation de débit.                                  | 1 minute |
| `AI_CHAT_STREAM_TIMEOUT` | Délai pour le temps jusqu'au premier fragment sur les requêtes en streaming. | —        |

Une requête limitée en débit retourne `429` avec un en-tête `Retry-After` et des informations de quota restant. Chaque utilisateur a un compteur indépendant, et la fenêtre se réinitialise après son expiration. Les appels API d'agent respectent les mêmes limites que le chat utilisateur.

## Gestion des erreurs

Lorsque le fournisseur IA échoue, le chat retourne une erreur conviviale plutôt que de divulguer les rouages internes bruts du fournisseur. Lorsque `AI_PROVIDER` n'est pas défini, le point d'accès du chat répond avec un état désactivé au lieu d'échouer — conformément au contrat « IA dormante jusqu'à configuration » de la plateforme.

## Pages connexes

- [Vue d'ensemble de l'IA](/fr/docs/ai-overview) — l'écosystème IA complet.
- [Fournisseurs IA](/fr/docs/ai-providers) — configurer le backend LLM.
- [Agents IA](/fr/docs/ai-agents) — agents qui propulsent les panneaux de chat nommés.
- [Mémoire IA](/fr/docs/ai-memory) — historique de conversation et faits appris.
- [Vue d'ensemble des enregistrements](/fr/docs/records-overview) — le modèle CRUD d'enregistrements sur lequel le chat opère.
- [Rôles & RBAC](/fr/docs/auth-roles-rbac) — les permissions que le chat applique toujours.