# Grands principes de l’IA (sous-module ai, AnythingLLM)

Ce document décrit les grands principes d’intégration de l’IA dans le projet (sous-module `ai`, socle AnythingLLM/Ollama). Les backends **docv** et **enso** consomment l’API IA ; ils n’appellent pas directement AnythingLLM ou Ollama. Référence : `docs/ARCHITECTURE_DOCV_ENSO.md` (sections 2bis, 2ter).

---

## 1. Dossier ↔ Workspace AnythingLLM

- Un **dossier** (métier) est **synchronisé** avec un **workspace AnythingLLM**.
- Correspondance bijective ou dédiée : un dossier applicatif = un workspace AnythingLLM pour le contexte et les opérations IA sur ce dossier.
- La synchronisation assure que le contenu pertinent du dossier (documents, métadonnées, structure) est disponible dans le workspace pour les requêtes et les opérations IA.
- **Arborescence versionnée** : le répertoire `data/dossiers-permanents/` du dépôt (gabarits + miroirs d’upload optionnels) peut alimenter le workspace après `git pull` sur la machine AnythingLLM ; procédure : [ANYTHINGLLM_DATAROOM_SYNC.md](ANYTHINGLLM_DATAROOM_SYNC.md). Référence données / Git côté API : [DOSSIERS_PERMANENTS_DATA_GIT.md](DOSSIERS_PERMANENTS_DATA_GIT.md).

---

## 2. Pré-traitement par librairies (avant appel IA)

L’API IA s’appuie au **maximum sur des librairies classiques** pour préparer les données et réduire la charge sur le modèle. L’IA reçoit des entrées normalisées et vérifiées.

| Domaine | Règle | Objectif |
|--------|--------|----------|
| **Traductions** | Uniquement **vers l’anglais**. | Langue cible unique pour les requêtes IA ; les librairies de traduction traitent les textes avant envoi au modèle. |
| **Extraction de données** | Uniquement **vers du JSON**. | Sorties structurées, exploitables par le code ; extraction par librairies (OCR, parsing PDF/Excel, etc.) avant ou en complément de l’IA. |
| **Vérification de vraisemblance** | Codes, identifiants, clés : **vérification en amont** de l’appel IA. | Validation de format, plages, existence (regex, schémas, BDD) avant de soumettre à l’IA ; l’IA ne remplace pas la vérification de cohérence des codes/IDs/clés. |
| **Images et formats non convertibles** | Si le format est **nécessaire à l’interprétation** et **non convertible** en texte/JSON : **amélioration de la qualité**, **retournement dans le bon sens** (orientation), puis envoi à l’IA. | Préparation des visuels (redressement, contraste, netteté) par librairies classiques ; autres supports possibles avec les librairies usuelles avant appel au modèle. |

En résumé : traductions → anglais uniquement ; extractions → JSON uniquement ; vérification des codes/IDs/clés en amont ; pour les images ou formats non convertibles, prétraitement (qualité, orientation) puis IA.

---

## 3. Rôle de l’IA

- L’**IA effectue les opérations demandées** sur les données préparées (contexte du workspace, entrées normalisées).
- Elle ne remplace pas les librairies pour la traduction systématique, l’extraction structurée vers JSON ni la vérification de vraisemblance des codes/identifiants/clés.

---

## 4. Workflow optionnel : IA distante (cloud)

Optionnellement, l’IA peut **déclencher un workflow** pour déléguer à une IA distante (cloud) :

1. **Anonymisation** : suppression ou masquage des données identifiantes dans la question ou le contexte envoyé.
2. **Décontextualisation** : formulation de la question (ou du lot) sans référence directe au dossier ou à l’office.
3. **Appel IA distante (cloud)** : envoi de la requête anonymisée et décontextualisée au service IA cloud.
4. **Récupération du résultat** : réception de la réponse du cloud.
5. **Renommage et recontextualisation** : réinjection des identifiants, du contexte dossier/office et adaptation des libellés pour réintégrer la réponse dans l’application.

Ce workflow est **optionnel** et paramétrable (activation par office, par type d’opération ou par configuration).

---

## 5. Déclenchement des fonctionnalités IA : Cursor instrumenté

- Les **fonctionnalités IA** sont déclenchées à travers un **Cursor instrumenté** pour l’API : un **projet/workspace** dédié expose les points d’entrée et le contexte pour les appels IA.
- **Agents, subagents, commandes, skills et plans** sont **systématiquement utilisés** par le code et par les **hooks** : pas d’appel IA ad hoc sans passer par ces mécanismes (agents, subagents, commandes, skills, plans).
- Le code applicatif et les hooks s’appuient sur ce Cursor instrumenté pour toute opération IA (chat, extraction, génération, etc.).

---

## 6. Synthèse

| Principe | Description |
|----------|-------------|
| Dossier ↔ Workspace | Un dossier métier est synchronisé avec un workspace AnythingLLM. |
| Librairies en priorité | Traductions → anglais uniquement ; extractions → JSON uniquement ; vérification des codes/IDs/clés en amont ; images/formats non convertibles : amélioration qualité et orientation avant IA. |
| Rôle de l’IA | L’IA réalise les opérations demandées sur des entrées préparées. |
| Workflow cloud (optionnel) | Anonymisation → décontextualisation → appel IA cloud → récupération → renommage et recontextualisation. |
| Cursor instrumenté | Fonctionnalités IA déclenchées via un Cursor instrumenté pour l’API (projet/workspace) ; agents, subagents, commandes, skills et plans utilisés systématiquement par le code et les hooks. |