@ai.ntellect/core 0.3.1 → 0.4.0

package/.nvmrc

@@ -0,0 +1 @@
+v22.0.0 

package/README.FR.md

@@ -1,370 +1,310 @@
 # AI.ntellect Core Framework
 
-## Table des matières
-
-1. [Composants principaux](#composants-principaux)
-   - [Orchestrator](#orchestrator)
-   - [Queue Manager](#queue-manager)
-   - [Évaluateur](#évaluateur)
-   - [Interpreter](#interpreter)
-   - [Mémoire](#architecture-mémoire)
-2. [Création et gestion des actions](#création-et-gestion-des-actions)
-3. [Exécution du Workflow](#exécution-du-workflow)
-4. [Appels API et côté client](#appels-api-et-côté-client)
-5. [WIP (Work in Progress)](#wip-work-in-progress)
-
----
-
-## 1. Composants principaux
+## Vue d'ensemble
 
-Le système repose sur plusieurs composants clés qui assurent une gestion fluide et efficace des actions et du processus global de workflow.
+Ce framework est conçu pour exécuter des workflows complexes à l'aide d'une orchestration avancée, de la gestion de mémoire et d'une intelligence exploitable. Il intègre des outils, des interpréteurs et des systèmes de mémoire pour :
 
-### Orchestrator
+- Analyser les entrées utilisateur dans leur contexte.
+- Exécuter des workflows prédéfinis et des actions dynamiques.
+- Gérer efficacement la mémoire à court et à long terme.
+- Permettre une intégration fluide avec des API et outils externes.
 
-L'orchestrateur est responsable de la gestion de l'exécution des actions dans un workflow. Il analyse les besoins en fonction des entrées (comme le prompt utilisateur) et décide de l'ordre des actions à effectuer. Il interagit avec les autres composants comme la mémoire cache et les événements pour organiser l'exécution des tâches.
-
-- **Rôle principal** : Organiser et diriger l'exécution des actions.
-- **Interactions** :
-  - Demande des actions à exécuter.
-  - Utilise la mémoire cache pour éviter la redondance.
-  - Émet des événements pour informer les autres composants de l'état du workflow.
+---
 
-### Queue Manager
+## Table des matières
 
-Le gestionnaire de la file d'attente (Queue Manager) organise les actions à exécuter et gère leur ordre d'exécution. Il permet de maintenir un flux fluide d'exécution, en ajoutant les actions à la file d'attente selon les priorités définies par l'orchestrateur.
+1. [Composants d'architecture](#composants-darchitecture)
+   - [Runtime de l'agent](#runtime-de-lagent)
+   - [Orchestrateur](#orchestrateur)
+   - [Gestionnaire de file d'attente](#gestionnaire-de-file-dattente)
+   - [Interpréteur](#interpréteur)
+   - [Système de mémoire](#système-de-mémoire)
+2. [Définir et exécuter des actions](#définir-et-exécuter-des-actions)
+3. [Gestion de l'état et récursivité](#gestion-de-letat-et-recursivité)
+4. [Installation et configuration](#installation-et-configuration)
+5. [Exemple d'utilisation](#exemple-dutilisation)
+6. [Travaux en cours (WIP)](#travaux-en-cours-wip)
 
-- **Rôle principal** : Gérer la file d'attente des actions et s'assurer qu'elles sont exécutées dans le bon ordre.
-- **Fonctions principales** :
-  - Ajouter de nouvelles actions à la file d'attente.
-  - Gérer les priorités des actions.
-  - Assurer une exécution correcte et en temps voulu des actions.
+---
 
-### Évaluateur
+## Composants d'architecture
 
-L'évaluateur collabore maintenant avec les Interpreters :
+### Runtime de l'agent
 
-- Analyse les résultats des actions exécutées
-- Détermine si des actions supplémentaires sont nécessaires et renvoie à la Queue Manager
-- Sinon, il sélectionne l'Interpreter approprié selon le type de demande
+Le `AgentRuntime` est le moteur principal qui coordonne le workflow global. Il connecte tous les composants et garantit que les tâches sont exécutées efficacement.
 
-### Interpreter
+**Responsabilités :**
 
-L'Interpreter est le composant spécialisé dans l'interprétation des résultats d'actions et la génération de réponses adaptées. Chaque Interpreter est configuré avec un contexte spécifique et produit des réponses dans un format adapté à son domaine d'expertise.
+- Construire un contexte pour l'état actuel à l'aide des systèmes de mémoire (RAG et CAG).
+- Orchestrer les actions à l'aide du gestionnaire de file d'attente.
+- Exploiter les interpréteurs pour analyser les résultats et générer des réponses.
 
-**Caractéristiques principales** :
+#### Construction du contexte
 
-- Configuration avec un contexte métier spécifique
-- Format de réponse adapté au domaine
-- Traitement spécialisé des données selon le contexte
+La méthode `buildContext` crée un contexte complet en :
 
-**Fonctionnement** :
+1. Ajoutant les outils et les demandes utilisateur.
+2. Récupérant les actions récentes via la mémoire cache (CAG).
+3. Cherchant les connaissances pertinentes dans la mémoire persistante (RAG).
+4. Incluant les interpréteurs disponibles pour la demande.
 
-- Reçoit les résultats des actions via l'Evaluator
-- Analyse les données selon son contexte spécifique
-- Produit une réponse formatée selon les règles de son domaine
+#### Traitement des workflows
 
-Voici quelques exemples d'Interpreters qui peuvent être implémentés :
+La méthode `process` :
 
-1. **MarketInterpreter**
+1. Génère des réponses basées sur le contexte à l'aide d'un modèle de langage.
+2. Gère les workflows récursifs pour l'exécution des actions.
+3. Sélectionne les interpréteurs appropriés pour analyser les résultats.
 
-   - Spécialisé dans l'analyse des données de marché
-   - Format adapté aux analyses financières
+---
 
-2. **SecurityInterpreter**
+### Orchestrateur
 
-   - Dédié aux vérifications de sécurité
-   - Format optimisé pour les rapports de sécurité
+L'**orchestrateur** dirige les workflows en analysant les entrées utilisateur et en planifiant les actions. Il interagit avec les outils, les systèmes de mémoire et les interpréteurs pour garantir une exécution logique.
 
-3. **GeneralInterpreter**
-   - Traitement des requêtes générales
-   - Format flexible selon le contexte
+**Caractéristiques clés :**
 
-Ces exemples illustrent la flexibilité du système, qui peut être étendu avec d'autres types d'Interpreters selon les besoins.
+- Sélection dynamique des actions en fonction du contexte.
+- Gestion des interactions mémoire pour les opérations RAG et CAG.
+- Gestion des workflows multi-étapes avec affinage itératif.
 
-[![Sans-titre-2024-11-08-0220.png](https://i.postimg.cc/nryjsx5y/Sans-titre-2024-11-08-0220.png)](https://postimg.cc/rR9FbBqj)
+---
 
-### Mémoire
+### Gestionnaire de file d'attente
 
-Le système implémente une architecture de mémoire qui combine différentes solutions de stockage :
+Le **gestionnaire de file d'attente** est chargé d'organiser et d'exécuter les actions dans le bon ordre, qu'elles soient séquentielles ou parallèles. Il agit comme le mécanisme central pour gérer les workflows, en s'assurant que chaque action est correctement mise en file d'attente, validée et exécutée.
 
-#### Installation et configuration
+**Responsabilités principales :**
 
-##### Meilisearch (Mémoire à long terme)
+1. **Mise en file d'attente des actions :**
 
-Meilisearch peut être auto-hébergé pour un contrôle total sur la mémoire à long terme de l'agent :
+   - Les actions sont ajoutées à une file pour exécution, individuellement ou en lot.
+   - Prise en charge des journaux pour le débogage et la traçabilité.
 
-```bash
-# Installation de Meilisearch
-curl -L https://install.meilisearch.com | sh
+2. **Traitement des actions :**
 
-# Lancement de Meilisearch avec une clé maître
-./meilisearch --master-key="VOTRE_CLE_MAITRE"
-```
+   - Exécute les actions en maintenant le bon ordre.
+   - Respecte les dépendances entre les actions.
+   - Gère les erreurs ou confirmations via des rappels.
 
-##### Redis (Mémoire à court terme)
+3. **Gestion des confirmations :**
+   - Prend en charge les invites de confirmation pour les actions critiques.
+   - S'appuie sur des rappels pour décider de poursuivre des actions spécifiques.
 
-Redis gère les composants de mémoire à court terme :
+**Exemple :**
 
-```bash
-# Utilisation de Docker
-docker run --name redis -d -p 6379:6379 redis
+```typescript
+import { ActionQueueManager } from "@ai-ntellect/core";
+import { actions, callbacks } from "@ai-ntellect/core/examples";
 
-# Ou installation locale
-sudo apt-get install redis-server
+const queueManager = new ActionQueueManager(actions, callbacks);
+queueManager.addToQueue([{ name: "fetch-data", parameters: [...] }]);
+const results = await queueManager.processQueue();
+console.log("Résultats :", results);
 ```
 
-2. **Configuration** :
-   - Port par défaut : 6379
-   - Configuration des limites de mémoire
-   - Activation de la persistance si nécessaire
-
-#### Types de mémoire
-
-##### Mémoire à court terme (Redis)
-
-1. **Mémoire procédurale** :
-
-   - Stockée dans Redis pour un accès rapide
-   - Contient les séquences d'actions et workflows réutilisables
-   - Optimise les performances via le cache
-   - Exemple : "Séquence commune d'approbation + échange de tokens"
-
-2. **Mémoire épisodique court terme** :
-   - Messages et interactions récents
-   - Contexte temporaire des conversations en cours
-   - Stockée dans Redis pour une récupération rapide
-   - Exemple : "10 derniers messages de la conversation actuelle"
-
-##### Mémoire à long terme (Meilisearch)
-
-1. **Mémoire sémantique** :
-
-   - Stockage permanent des faits et connaissances
-   - Indexée pour une récupération efficace
-   - Stocke les relations entre concepts
-   - Exemple : "Le token X a l'adresse de contrat Y sur le réseau Z"
+---
 
-2. **Mémoire épisodique long terme** :
-   - Interactions et expériences historiques
-   - Contexte persistant entre les sessions
-   - Recherchable par similarité vectorielle
-   - Exemple : "Transactions réussies passées de l'utilisateur X"
+### Interpréteur
 
-### Cache Augmented Generation (CAG)
+L'**interpréteur** se spécialise dans l'analyse des résultats et la génération d'informations spécifiques à un domaine. Chaque interpréteur est adapté à un cas d'utilisation particulier et utilise sa propre configuration de caractère.
 
-Le CAG optimise l'exécution des workflows via le cache Redis :
+**Exemples :**
 
-- **Rôle principal** : Mettre en cache les modèles procéduraux fréquemment utilisés
-- **Implémentation** :
+1. **MarketInterpreter** : Analyse des données financières de marché.
+2. **SecurityInterpreter** : Vérification de la sécurité.
+3. **GeneralInterpreter** : Traitement des demandes générales.
 
-  - Utilise Redis pour un stockage haute performance
-  - Stocke les séquences d'actions et leurs résultats
-  - Permet une récupération rapide des modèles communs
+#### Workflow d'interprétation
 
-- **Bénéfices** :
-  - Réduit la charge de calcul
-  - Accélère les opérations répétitives
-  - Optimise l'utilisation des ressources
+1. Construit un contexte avec l'état actuel, y compris les résultats et les demandes utilisateur.
+2. Utilise le modèle de langage pour générer des informations exploitables.
+3. Fournit des réponses détaillées pour l'utilisateur final.
 
-### Retrieval Augmented Generation (RAG)
+---
 
-Le système RAG améliore l'accès à la mémoire à long terme via Meilisearch :
+### Système de mémoire
 
-- **Implémentation** :
+L'architecture mémoire combine une mémoire à court terme et une mémoire à long terme pour fournir un traitement contextuel.
 
-  - Recherche vectorielle pour la similarité sémantique
-  - Double indexation (globale et spécifique à l'utilisateur)
-  - Combine avec la recherche textuelle traditionnelle
+#### Types de mémoire
 
-- **Fonctionnalités** :
-  - Récupération de mémoire sémantique et épisodique
-  - Capacités de recherche contextuelle
-  - Classement des résultats basé sur la pertinence
+1. **Mémoire cache (Redis) :**
+   - Stocke des données temporaires pour un accès rapide.
+   - Exemples : Actions récentes, données de session.
+2. **Mémoire persistante (Meilisearch) :**
+   - Stocke des données à long terme comme les interactions historiques et les connaissances.
+   - Permet des recherches sémantiques et des récupérations basées sur des vecteurs.
 
 ---
 
-## 2. Création et gestion des actions
+## Définir et exécuter des actions
+
+### Qu'est-ce qu'une action ?
 
-Les actions sont des tâches spécifiques à réaliser dans le cadre du workflow. Elles peuvent être des interactions avec des APIs, des transactions blockchain, ou toute autre opération nécessaire.
+Les actions sont les tâches fondamentales exécutées par le framework. Chaque action comprend :
 
-Chaque action est définie comme un objet contenant un nom, une description, des paramètres, et une fonction d'exécution.
+- Un nom et une description uniques.
+- Des paramètres d'entrée validés à l'aide de schémas.
+- Une logique d'exécution encapsulée dans la méthode `execute`.
 
 ### Exemple d'action
 
 ```typescript
-import { networkConfigs } from "@config/network";
-import { parseEther } from "ethers";
 import { z } from "zod";
+import { parseEther } from "ethers";
 
 export const prepareTransaction = {
   name: "prepare-transaction",
-  description: "Préparer un transfert pour que l'utilisateur la signe.",
+  description: "Prépare un transfert de token pour approbation utilisateur.",
   parameters: z.object({
     walletAddress: z.string(),
-    amount: z.string().describe("Montant à envoyer"),
-    networkId: z
-      .string()
-      .describe("Réseau cible (par exemple, ethereum, arbitrum)"),
+    amount: z.string(),
+    networkId: z.string(),
   }),
-  execute: async ({
-    walletAddress,
-    amount,
-    network,
-  }: {
-    walletAddress: string;
-    amount: string;
-    networkId: string;
-  }) => {
-    try {
-      const networkConfig = networkConfigs[networkId];
-      if (!networkConfig) {
-        throw new Error(`Réseau ${network} non trouvé`);
-      }
-
-      return {
-        to: walletAddress,
-        value: parseEther(amount).toString(),
-        chain: {
-          id: networkConfig.id,
-          rpc: networkConfig.rpc,
-        },
-        type: "transfer",
-      };
-    } catch (error) {
-      return "Erreur lors de la préparation de la transaction";
-    }
+  execute: async ({ walletAddress, amount, networkId }) => {
+    return {
+      to: walletAddress,
+      value: parseEther(amount).toString(),
+      network: networkId,
+    };
   },
 };
 ```
 
-### Comment définir une action :
-
-1. **Nom** : Identifiant unique pour l'action.
-2. **Description** : Brève description de ce que fait l'action.
-3. **Paramètres** : Les paramètres nécessaires pour l'exécution de l'action, validés par `zod`.
-4. **Exécution** : Fonction `execute` qui effectue l'action.
-
 ---
 
-## 3. Exécution du workflow
+## Gestion de l'état et récursivité
 
-L'agent gère l'ensemble du processus de compréhension des requêtes utilisateur et de coordination des réponses. Voici un exemple d'utilisation de l'agent :
+L'agent gère l'état et les workflows récursifs pour s'assurer que les actions sont exécutées de manière ordonnée et jusqu'à leur achèvement, tout en respectant un maximum d'itérations pour éviter les boucles infinies.
 
-```typescript
-const memory = new PersistentMemory({
-  host: "http://localhost:7700",
-  apiKey: "VOTRE_CLE_API",
-});
+### Gestion de l'état
 
-const orchestrator = new Orchestrator(
-  [
-    getChainsTVL,
-    getRssNews,
-    // autres outils...
-  ],
-  memory
-);
+L'état (`State`) contient :
 
-const agent = new Agent({
-  user: { id: "user_id" },
-  orchestrator,
-  persistentMemory: memory,
-  stream: false,
-  maxEvaluatorIteration: 1,
-});
+- `currentContext` : Contexte actuel de la requête utilisateur.
+- `previousActions` : Liste des actions exécutées précédemment.
 
-// Traitement d'une requête utilisateur
-const result = await agent.process(prompt, context, {
-  onMessage: (message) => {
-    console.log({ message });
-  },
-});
-```
+Lorsqu'une action est terminée, l'état est mis à jour pour inclure :
 
-### Flux de traitement de l'agent :
+- Les résultats des actions précédentes.
+- Le contexte restant à traiter.
 
-1. L'utilisateur envoie un prompt
-2. L'agent analyse le prompt et le contexte
-3. L'orchestrateur exécute les outils/actions nécessaires
-4. L'évaluateur évalue les résultats
-5. L'agent génère la réponse finale
+### Récursivité contrôlée
 
----
+Pour éviter les boucles infinies, le système limite le nombre d'itérations via la configuration `maxIterations`.
 
-## 4. WIP (Work in Progress)
+**Fonctionnement :**
 
-Voici les éléments actuellement en développement ou à améliorer :
+1. **Initialisation :** À chaque itération, l'agent :
 
----
+   - Exécute les actions dans la file d'attente.
+   - Met à jour l'état avec les nouveaux résultats.
 
-## Collaboration multi-agent
+2. **Validation des limites :**
 
-**Objectif** : Permettre à plusieurs agents de collaborer sur des tâches complexes avec spécialisation et coordination.
+   - Si le nombre d'itérations dépasse `maxIterations`, le traitement est interrompu avec un message "Max iterations reached".
 
-**Intérêt** : La collaboration entre agents permet de diviser les tâches complexes en sous-tâches spécialisées, améliorant ainsi l'efficacité et la qualité des résultats. Elle permet également une meilleure gestion des ressources et une adaptation plus rapide aux changements.
+3. **Récursivité :**
+   - Si des actions restent à exécuter, l'agent appelle récursivement la méthode `process` avec le nouvel état.
 
-**Étapes à réaliser** :
+**Exemple de gestion d'état et récursivité :**
 
-- [ ] Mise en place d'un cadre de délégation des tâches.
-- [ ] Gestion partagée du contexte.
-- [ ] Établissement de protocoles de résolution des conflits.
+```typescript
+const updatedNextState: State = {
+  ...state,
+  currentContext: state.currentContext,
+  previousActions: [...(state.previousActions || []), ...(results || [])],
+};
 
-**Statut** : Phase de recherche, planification architecturale en cours.
+if (countIterations < this.config.maxIterations) {
+  return this.process(updatedNextState);
+} else {
+  console.log("Max iterations reached");
+  response.shouldContinue = false;
+}
+```
 
 ---
 
-## Gestion des interactions complexes on-chain
+## Installation et configuration
 
-**Objectif** : Créer un modèle pour la reconnaissance des interactions on-chain et la création de workflows pour des interactions complexes.
+### Installer les dépendances
 
-**Intérêt** : Cette fonctionnalité permet à l'agent de comprendre et d'interagir avec des contrats intelligents de manière plus intuitive, facilitant ainsi l'exécution d'actions complexes sur la blockchain. Cela améliore l'accessibilité et l'efficacité des interactions avec les contrats intelligents.
-
-**Étapes à réaliser** :
-
-- [ ] Extraction et traitement des ABI des contrats pertinents.
-- [ ] Filtrage des fonctions pertinentes.
-- [ ] Génération de requêtes hypothétiques en langage naturel.
-- [ ] Conversion des requêtes en embeddings vectoriels.
-- [ ] Stockage des embeddings et des requêtes associées.
-- [ ] Recherche de similarité basée sur le cosine.
-- [ ] Classement des résultats en fonction de la pertinence.
-
-**Statut** : Étude en cours pour déterminer la meilleure approche et les technologies à utiliser.
+```bash
+npm install
+```
 
----
+### Configurer les services externes
 
-## Implémentation du Lit Protocol
+#### Redis (Mémoire cache)
 
-**Objectif** : Ajouter la possibilité d'exécuter des actions Lit, permettant de déployer et d'exécuter des calculs décentralisés et sécurisés sur le réseau Lit.
+```bash
+docker run --name redis -d -p 6379:6379 redis
+```
 
-**Intérêt** : L'intégration du Lit Protocol permet d'exécuter des actions Lit de manière décentralisée, en utilisant des clés cryptographiques pour valider les opérations. Ces actions peuvent être utilisées pour exécuter des scripts JavaScript dans un environnement décentralisé, ce qui permet une grande transparence, car toutes les interactions sont enregistrées sur la blockchain. L'un des principaux avantages réside dans l'automatisation et la sécurité des processus tout en préservant la confidentialité des utilisateurs, ce qui renforce la confiance dans les interactions on-chain.
+#### Meilisearch (Mémoire persistante)
 
-**Étapes à réaliser** :
+```bash
+curl -L https://install.meilisearch.com | sh
+./meilisearch --master-key="VOTRE_CLÉ_MAÎTRE"
+```
 
-- [x] Étudier la documentation du Lit Protocol, en particulier la section sur les actions Lit et leur mise en œuvre.
-- [ ] Intégrer le protocole dans l'architecture existante pour permettre l'exécution des actions Lit.
-- [ ] Développer des modules pour l'exécution des actions Lit, incluant la gestion des signatures et l'exécution des scripts dans un environnement sécurisé.
-- [ ] Tester l'intégration, la sécurité et la transparence des actions Lit pour garantir leur bon fonctionnement.
+---
 
-**Statut** : En cours d'étude pour déterminer la faisabilité et les implications techniques, notamment en ce qui concerne l'intégration de la décentralisation dans le système existant.
+## Exemple d'utilisation
 
-### Exemple d'utilisation
+### Initialiser l'agent
 
 ```typescript
-const securityInterpreter = new Interpreter("security", securityContext);
-const marketInterpreter = new Interpreter("market", marketContext);
-const generalInterpreter = new Interpreter("general", generalContext);
+import { deepseek } from "@ai-ntellect/core";
+import { Agent } from "@ai-ntellect/core";
+import { checkHoneypot, fetchMarkPrice } from "@ai-ntellect/core/actions";
+import {
+  generalInterpreterCharacter,
+  marketInterpreterCharacter,
+  securityInterpreterCharacter,
+} from "@ai-ntellect/core/interpreter/context";
+
+const model = deepseek("deepseek-reasoner");
 
 const agent = new Agent({
-  interpreters: [securityInterpreter, marketInterpreter, generalInterpreter],
-  orchestrator,
-  memory: {
-    persistent: memory,
-    cache: cacheMemory,
+  orchestrator: {
+    model,
+    tools: [checkHoneypot, fetchMarkPrice],
+  },
+  interpreters: [
+    new Interpreter({
+      name: "security",
+      model,
+      character: securityInterpreterCharacter,
+    }),
+    new Interpreter({
+      name: "market",
+      model,
+      character: marketInterpreterCharacter,
+    }),
+    new Interpreter({
+      name: "general",
+      model,
+      character: generalInterpreterCharacter,
+    }),
+  ],
+  memoryManager: {
+    model,
   },
-  stream: false,
-  maxEvaluatorIteration: 1,
+  maxIterations: 3,
 });
+```
+
+### Traiter une demande
+
+```typescript
+const state = {
+  currentContext: "Analyse des tendances de marché XRP/USD",
+  previousActions: [],
+};
 
-const result = await agent.process(prompt, context);
+const result = await agent.process(state);
+console.log("Résultat :", result);
 ```