Projet-Agent-IA/readme.md

# Projet final Kévin Taccoen

**Les documents liés au projet ne sont pas inclus dans ce repo, il faut les ajouter à la racine dans "documents_projet/" !**

**Le rapport final est dans ce readme, un peu plus bas !**
Si besoin, je reste disponible à `kevin[]taccoen.fr`

## Workflow
![image](imgs/workflow.png)
![workflow](imgs/agent.png)

## Mise en place

La première étape est d'installer le `venv` Python:
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Puis de définir les variables d'env de l'agent
```
cp AgentReact/.env.template AgentReact/.env
nano AgentReact/.env
```

Une fois le dossier **documents_projet** ajouté à la racine, il est possible de générer la base de données vectorielle
```
python RAG/init.py
```

Puis de lancer l'agent
```
python AgentReact/start.py
```

### Exemple de prompt initial
Il faut le coller comme une seule ligne dans l'input, produira des bugs lors de prompts sinon.

**Les outils de gestion TODO ont été désactivés dans tools.py! Ces outils sont très instables, et le modèle sous-performe quand il doit les gérer.**

#### Sans TODO
```
Ton but est d'écrire un rapport de stage sur l'entreprise Diag'n Grow. Commence par préparer un plan avec ton skill "Creation_plan", tu peux rechercher des informations sur l'entreprise avec une recherche internet en utilisant "internet_search". Ensuite, rédige chacune des parties du plan, en utilisant l'outil "append_part_to_report". Fais de petits paragraphes pour rédiger tes parties.
Tu as aussi des rapports de chaque semaine de stage dans le dossier `rapports_resumes`, tu peux en lister les fichiers avec l'outil "list_files".
En plus de ces rapports, tu as une base de données de ce qui a été fait, en plus détaillé, avec l'outil "search_in_files".
Bon couraj, il y a 25 semaines différentes, essaie de les regrouper en groupes de 5 pour aller plus vite. Regarde en particulier le fichier 'rapports_resumes/rapport_outils.txt' qui te donne une liste des outils utilisés.
```


#### Avec TODO
```
Ton but est d'écrire un rapport de stage sur l'entreprise Diag'n Grow. Commence par préparer un plan avec ton skill "Creation_plan", tu peux rechercher des informations sur l'entreprise avec une recherche internet en utilisant "internet_search". Ensuite, rédige chacune des parties du plan, en utilisant l'outil "append_part_to_report". En faisant cela, n'oublie pas de créer une liste de tâches(TODO), et de les garder à jour. A chaque fois qu'une partie du rapport est validée, mets à jour ta liste de tâches pour garder une trace de ta progression.
Tu as aussi des rapports de chaque semaine de stage dans le dossier `rapports_resumes`, tu peux en lister les fichiers avec l'outil "list_files".
En plus de ces rapports, tu as une base de données de ce qui a été fait, en plus détaillé, avec l'outil "search_in_files".
Bon couraj, il y a 25 semaines différentes, essaie de les regrouper en groupes de 5 pour aller plus vite. Regarde en particulier le fichier 'rapports_resumes/rapport_outils.txt' qui te donne une liste des outils utilisés.
```

## Rapport du projet
### Roadmap
J'ai préparé la Roadmap comme une sorte de TODO liste, qui répertorie toutes les étapes nécéssaires à la mise en place du système. J'y ai donc noté tout ce qui a été fait et implémenté. J'ai aussi séparé les étapes en grands thèmes, séparant les différentes phases de création de l'agent.

### Workflow
Au départ, le système vérifie si le dossier `AgentReact/rapports_resumes/` existe. S'il n'est pas présent, une première étape de préparation est lancée.
Un premier nœud va injecter un `HumanMessage` qui donnera les ordres au système de préparation, qui aura ensuite pour objectif de préparer la liste des tâches exécutées et des outils, techniques, entreprises, ... utilisés tout au long du stage, en utilisant des outils dédiés.
Une fois cette première étape terminée, le contexte est réduit, avant de passer à la partie principale.

La partie principale vise à suivre le plan définit dans `skills.md`, en utilisant les outils à disposition, et réduisant la taille du contexte chaque fois que nécessaire. Le système revient vers le nœud *user_prompt* chaque fois que le modèle a besoin d'un prompt, où l'utilisateur peut décider de répondre pour relancer la machine, ou d'envoyer `exit` pour terminer le programme.

### Architecture
Je me suis reposé sur l'architecture du TP3 que nous avions fait en cours. L'idée étant de séparer proprement les outils, les nodes, le `State`, et les différents utilitaires, j'ai pensé que cette lisibilité serait bénéfique pour un projet donc la complexité peut viter augmenter.

Aussi, j'ai repris une approche de mes anciens projets, où j'ai implémenté des classes utilitaires pour représenter certaines choses (`TodoElement`, `InterruptPayload`), ce qui me fournit une interface propre pour travailler avec les TODO, ou la fonction `interrupt()`. Le `State`, ou `interrupt()` ne peuvent prendre que des données sérializables, et j'ai donc implémenté des méthodes pour exporter et importer les objets dans le format *JSON*.

La base de données vectorielle est implémentée dans `VectorDatabase.py`, ce qui permet de facilement changer de source de données, et d'obtenir un poitn d'accès aux données depuis n'importe quel emplacement du programme.

L'affichage des messages/du graphe est fait via `StreamGraph.py`, une fonction d'affichage récursive capable de gérer les interuptions et reprises, tout en gardant une trace du parcours des messages pour ne jamais afficher deux fois le même. Cette fonction a aussi un réglage pour dissimuler l'affichage des messages Système et des outils.

Le fichier `nodes.py` contient des paramètres sur le graphe, tel que la taille maximale du contexte (avant réduction), le système de résumé, ou le prompt anti-injections. Tous les nœuds y sont définits. 

### State
Le `State` contient trois variables:
- **todo**, une liste de tâches à faire, au format JSON, pouvant être reformées vers de vraies instances avec `TodoElement.fromJSON(...)`. Ces tâches sont injectables avant chaque prompt de l'utilisateur via un message système injecté dans l'appel au LLM.
- **lastSummarizedMessage**: Pour éviter de résumer des messages déjà résumés, le système garde une trace d'où l'on s'était arrêté lors du dernier appel au nœud de gestion du contexte.
- **stop**: Passera à `True` si l'utilisateur écrit `exit` dans le prompt, mettant fin à l'exécution.

### Outils
Plusieurs jeux d'outils sont disponibles, permettant de lister des fichiers, rechercher sur internet, ou dans la base vectorielle, de lire des fichiers locaux, de gérer les tâches en cours (*désactivé dans la dernière version, instable*), ou de récupérer un skill de `skills.md`.

Un jeu d'outils réservé au LLM en charge du résumé de éléments du stage est disponible, avec un outil pour écrire le résumé d'une semaine, un pour faire un rapport sur les outils utilisés par le stagiaire, une recherche internet, ou dans la base vectorielle.

Toutes les recherches dans la base vectorielle (outil `search_in_files`) sont reliées à un *cross-encodeur*, qui vérifie si les documents retrouvés correspondent à la requête. Si besoin, une IA va reformuler la question pour recommencer la recherche.

La philosophie derrière la mise en place des outils était de ne pas laisser d'outils trop généralistes ou dangereux. Il n'y a donc pas d'outil pour écrire dans un fichier de façon générale, uniquement `append_part_to_report` qui ajoute une partie dans le rapport de stage, après validation humaine.

### Gestion du contexte
Le contexte est maintenu en-dessous d'une certaine limite par le nœud `context_shortener`. Il permet de faire un résumé de tous les messages qui en ont besoin, sans repasser deux fois sur le même; tandis que les retours des appels aux outils sont placés dans des fichiers et remplacés par le chemin vers le fichier créé.
La limite de taille du contexte est définie dans `nodes.py`.

La taille du contexte est vérifiée après les résultats des outils. Si besoin, le LLM peut toujours retrouver le résultat des outils en allant lire le fichier généré.

### Human In The Loop
La classe `InterruptPayload` est dédiée à cette partie. L'idée est que l'on puisse placer un `interrupt()` à n'importe quel endroit du workflow, pour y passer un une requête à l'utilisateur. Cette requête peut être des arguments d'un appel de fonction, ou une demande de prompt.

Dans les outils, `InterruptPayload` peut prendre les arguments d'appel dans un dictionnaire, les convertir en JSON pour être passés dans l'`interrupt()` puis réassemblés de l'autre côté. L'affichage utilisateur implémenté dans cette classe permet ensuite d'accepter, de refuser ou de modifier une demande de lancement d'outil.

Dans le nœud `user_prompt`, `InterruptPayload` peut demander le prompt à l'utilisateur, toujours en le sérialisant en JSON, pour le renvoyer dans le workflow.

Les outils de recherche internet, et d'écriture dans le rapport de stage sont protégés par `InterruptPayload`, et l'utilisateur pourra toujours voir la requête du LLM avant qu'elle ne soit exécutée.

Aussi,`StreamGraph.py`, qui affiche le graphe dans une boucle récursive, est compatible avec `InterruptPayload` pour l'affichage et la gestion du retour utilisateur.

### Observabilité
Lors du lancement du programme, tous les messages sont affichés dans la console. Il est possible de cacher les messages système et d'outils dans les paramètres de `StreamGraph.py` (appelé depuis `start.py`) pour augmenter la lisibilité.
Aussi, lors du dévelopement, *Mlflow* a été utilisé pour analyser l'évolution du `State`  et les arguments d'appel exacts pour le LLM.

Aussi, *Mlflow* ne semble pas apprécier l'appel aux `interrupt()` dans le code, considérant cela comme un plantage du système, sans qu'une solution a ce problème n'a pu être trouvée. Cela ne concerne que *Mlflow* et n'a aucun impact sur l'agent IA créé.