@ai.ntellect/core 0.8.3 → 1.1.0

package/docs/modules/memoire/les-adaptateurs/redisadapter.md

@@ -0,0 +1,212 @@
+---
+description: >-
+  L’adaptateur Redis utilise une base de données clé-valeur en mémoire, idéale
+  pour des stockages rapides et temporaires.
+---
+
+# RedisAdapter
+
+`RedisAdapter` intègre **Redis** comme moteur de stockage pour la mémoire des systèmes. 
+
+Redis permet un **accès instantané** aux données grâce à un modèle **clé-valeur**, tout en offrant des fonctionnalités avancées comme **la persistance**, **le TTL (Time-To-Live)** et **la réplication distribuée**.
+
+Ce type d’adaptateur est particulièrement adapté aux agents qui nécessitent **des accès ultra-rapides** et une **gestion fine du cycle de vie des mémoires**.
+
+***
+
+### **Spécificités techniques du RedisAdapter**
+
+#### **Stockage sous forme de clés structurées**
+
+Chaque mémoire est stockée dans Redis avec une clé formée comme suit :
+
+```plaintext
+<memory_prefix>:<room_id>:<memory_id>
+```
+
+Cela permet de **segmenter les mémoires** par `roomId` et d’éviter les collisions.
+
+Exemple de stockage d’une mémoire :
+
+```typescript
+const key = `${this.cachePrefix}${memory.roomId}:${memory.id}`;
+await this.redis.set(key, JSON.stringify(memory), { EX: this.cacheTTL });
+```
+
+L’option `{ EX: this.cacheTTL }` définit **une expiration automatique** après un temps défini, évitant ainsi l’accumulation de données obsolètes.
+
+***
+
+#### **Initialisation et connexion au serveur Redis**
+
+L’adaptateur doit établir une connexion avec un serveur Redis, qui peut être **local, distant ou géré via un service cloud**.
+
+```typescript
+constructor(
+  private readonly redisUrl: string,
+  options: { cachePrefix?: string; cacheTTL?: number }
+) {
+  this.cachePrefix = options.cachePrefix || "memory:";
+  this.cacheTTL = options.cacheTTL || 3600;
+  this.redis = createClient({ url: redisUrl });
+}
+```
+
+* `cachePrefix` permet de **différencier plusieurs types de données** stockées dans Redis.
+* `cacheTTL` définit **le temps de rétention** des mémoires (en secondes).
+
+**Avantage :** Un système utilisant Redis peut fonctionner sans base de données persistante, en exploitant uniquement la mémoire vive du serveur.
+
+***
+
+#### **Création et récupération des mémoires**
+
+**Stockage d’une nouvelle mémoire**
+
+Chaque entrée est **convertie en JSON** et stockée sous une clé unique dans Redis.
+
+```typescript
+async createMemory(input: CreateMemoryInput & { embedding?: number[] }): Promise<BaseMemoryType | undefined> {
+  const memory: BaseMemoryType = {
+    id: input.id || crypto.randomUUID(),
+    data: input.data,
+    embedding: input.embedding,
+    roomId: input.roomId,
+    createdAt: new Date(),
+  };
+
+  const key = `${this.cachePrefix}${memory.roomId}:${memory.id}`;
+  await this.redis.set(key, JSON.stringify(memory), { EX: this.cacheTTL });
+
+  return memory;
+}
+```
+
+💡 **Optimisation :** Redis étant une base en RAM, **éviter de stocker des objets volumineux** pour limiter l’impact sur la mémoire.
+
+***
+
+**Récupération d’une mémoire**
+
+Les entrées sont récupérées en **temps constant** grâce à l’accès clé-valeur.
+
+```typescript
+async getMemoryById(id: string, roomId: string): Promise<BaseMemoryType | null> {
+  const key = `${this.cachePrefix}${roomId}:${id}`;
+  const data = await this.redis.get(key);
+  return data ? JSON.parse(data) : null;
+}
+```
+
+**Temps d’accès :** \~ **1 ms**, bien plus rapide qu’une base de données traditionnelle.
+
+***
+
+#### **Recherche et indexation dans Redis**
+
+Redis ne supporte pas nativement **les recherches full-text**, mais il est possible de **simuler une indexation** en utilisant **les clés et SCAN MATCH**.
+
+```typescript
+async getMemoryByIndex(query: string, options: { roomId: string; limit?: number }): Promise<BaseMemoryType[]> {
+  const pattern = `${this.cachePrefix}${options.roomId}:*`;
+  const keys = await this.redis.keys(pattern);
+
+  const memories = await Promise.all(
+    keys.map(async (key) => {
+      const data = await this.redis.get(key);
+      return data ? JSON.parse(data) : null;
+    })
+  );
+
+  return memories.filter(Boolean).slice(0, options.limit || 10);
+}
+```
+
+**Limite :** Redis ne propose pas de scoring de pertinence comme Meilisearch. Les recherches sont basées sur **des correspondances exactes** ou **un filtrage par clé**.
+
+***
+
+#### **Suppression et nettoyage de la mémoire**
+
+Redis permet une suppression instantanée d’une mémoire spécifique ou d’un ensemble de mémoires.
+
+**Suppression d’une mémoire individuelle**
+
+```typescript
+async clearMemoryById(id: string, roomId: string): Promise<void> {
+  const key = `${this.cachePrefix}${roomId}:${id}`;
+  await this.redis.del(key);
+}
+```
+
+**Suppression de toutes les mémoires d’un agent**
+
+```typescript
+async clearAllMemories(): Promise<void> {
+  const keys = await this.redis.keys(`${this.cachePrefix}*`);
+  if (keys.length > 0) {
+    await this.redis.del(keys);
+  }
+}
+```
+
+**Attention :** Cette opération peut être coûteuse si le volume de données est important.
+
+***
+
+### **Limitations et considérations**
+
+#### **Dépendance à un service en mémoire volatile**
+
+Redis fonctionne en **RAM**, ce qui signifie que **sans mécanisme de persistance activé**, les mémoires stockées peuvent être **perdues en cas de redémarrage**. Par défaut, Redis offre **deux modes de persistance** :
+
+* **RDB (Redis Database Snapshot)** : Sauvegarde périodique en dur.
+* **AOF (Append-Only File)** : Journalisation des opérations pour rejouer l’état en cas de crash.\
+  Si la mémoire de l’agent doit être **persistante sur le long terme**, il est recommandé d’associer Redis avec **une base durable** comme PostgreSQL ou Meilisearch.
+
+#### **Latence ultra-faible mais dépendance au réseau**
+
+Redis est **extrêmement rapide** (accès en **O(1)**), mais cette rapidité dépend de **l’emplacement du serveur**.
+
+* Un **Redis local** offre **des performances optimales**.
+* Un **Redis distant** introduit une **latence liée au réseau**.\
+  Si l’agent est déployé dans un environnement distribué, il est préférable d’**héberger Redis proche de l’instance exécutant l’agent**.
+
+#### **Consommation mémoire et TTL obligatoire**
+
+Redis stocke **tout en RAM**, ce qui peut poser un problème si un système génère un **grand volume de données**.
+
+⚠ **Sans expiration (TTL), les mémoires s’accumulent et saturent Redis**.
+
+Il est **recommandé de fixer une politique d’expiration** (exemple : **stockage des mémoires pour X heures**).
+
+Exemple de gestion du TTL :
+
+```typescript
+await this.redis.set(key, JSON.stringify(memory), { EX: 3600 }); // Expire après 1h
+```
+
+Si l’agent doit **conserver son historique sur le long terme**, une solution **persistante (Meilisearch, SQL, stockage objet)** est plus adaptée.
+
+#### **Absence de moteur de recherche avancé**
+
+Redis **ne supporte pas nativement les recherches full-text ou vectorielles**.
+
+* Pour **des recherches sémantiques**, il est préférable d’utiliser **Meilisearch**.
+* Pour **des recherches par similarité**, Redis **peut stocker des embeddings**, mais un moteur spécialisé comme **FAISS ou Weaviate** est plus efficace.
+
+#### **Non adapté aux grosses bases historiques**
+
+Si le système doit **retrouver des informations sur plusieurs mois/années**, Redis n’est pas une solution idéale.\
+**Recommandation** : Utiliser Redis pour **le stockage temporaire** et exporter les anciennes données vers une **base durable** (Meilisearch/PostgreSQL).
+
+***
+
+### **Cas d’usage adaptés**
+
+**`RedisAdapter`** est particulièrement utile pour :&#x20;
+
+* **Le caching des réponses d’un agent** pour réduire les appels aux LLMs.
+* **Les sessions temporaires**, où l’état mémoire doit expirer après une période définie.
+* **Les interactions en temps réel**, nécessitant des accès ultra-rapides.
+* **Le stockage intermédiaire** avant synchronisation avec une base plus durable.

package/docs/modules/nlp/README.md

@@ -0,0 +1,44 @@
+# Module NLP
+
+Le module NLP enveloppe `@nlpjs/basic` comme nœuds de graphe pour le traitement du langage naturel.
+
+## Installation
+
+Le module est inclus dans le package principal:
+
+```typescript
+import { NLPEngine } from "@ai.ntellect/core";
+```
+
+## Utilisation de base
+
+```typescript
+import { NLPEngine } from "@ai.ntellect/core";
+
+const nlp = new NLPEngine();
+
+// Entraîner le moteur
+await nlp.train([
+  { intent: "greeting", utterances: ["hello", "hi", "hey"], answer: "Hello! How can I help?" },
+  { intent: "goodbye", utterances: ["bye", "see you"], answer: "Goodbye!" },
+]);
+```
+
+## Utilisation comme nœud de graphe
+
+```typescript
+{
+  name: "process_input",
+  execute: async (ctx) => {
+    const result = await nlp.process(ctx.userInput);
+    ctx.intent = result.intent;
+    ctx.answer = result.answer;
+  },
+}
+```
+
+## Cas d'usage
+
+- **Chatbots** — Détection d'intention sur les entrées utilisateur
+- **Classification** — Catégoriser du texte
+- **Réponses automatiques** — Réponses basées sur des règles simples

package/docs/philosophie.md

@@ -0,0 +1,51 @@
+# The Philosophy of Deterministic Control
+
+In the current AI landscape, there is a fundamental tension between **autonomy** and **reliability**.
+
+## The Problem: The "LLM-as-Brain" Fallacy
+
+Most modern agent frameworks are built on the assumption that the LLM should act as the central controller. In this model, the LLM:
+1. Analyzes the state.
+2. Decides which tool to call.
+3. Evaluates the result.
+4. Decides the next step.
+
+This is "Autonomous Reasoning." It works beautifully in demos, but it fails in production. Why? Because **probabilistic models are fundamentally unsuitable for control flow.**
+
+When an LLM manages routing, you introduce **non-deterministic drift**. A slight change in prompt or a random seed shift can lead the agent to skip a critical validation step or enter an infinite loop.
+
+## Our Solution: The Classifier-Controller Split
+
+We believe that for an AI agent to be production-ready, it must be **verifiable**. To achieve this, `@ai.ntellect/core` implements a strict separation of concerns:
+
+### 1. The LLM as the Classifier (The "What")
+We use the LLM for what it is best at: **high-dimensional pattern matching**. 
+Instead of asking the LLM "What should I do next?", we ask "Which known intent does this user request match?". The LLM provides a classification, not a command.
+
+### 2. The System as the Controller (The "How")
+Once the intent is identified, the LLM is removed from the routing logic. The flow is handed over to a **verified Petri Net**.
+The Petri Net defines the legal transitions of the system. It doesn't "guess" the next step; it executes a mathematically proven path.
+
+---
+
+## The Three Pillars of Our Approach
+
+### 🛡️ Determinism over Autonomy
+We prioritize **predictability** over "magic." We believe that a developer should be able to look at a graph and know exactly how the system will behave, regardless of the LLM's temperature.
+
+### 🔍 Verifiability over Trust
+"Trusting" an LLM to follow instructions is a risk. **Verifying** a Petri Net for deadlocks or reachability is a guarantee. By using formal methods, we move from "It usually works" to "It is mathematically impossible for this to deadlock."
+
+### 🏗️ Transparency over Opacity
+We reject "Black Box" orchestration. Every transition, every state change, and every checkpoint in `@ai.ntellect/core` is observable and traceable. You don't debug a prompt; you debug a state machine.
+
+## Alignment with d/acc (Defensive Accelerationism)
+
+This technical philosophy is a practical application of **Defensive Accelerationism**. We accelerate the capabilities of AI, but we do so by building **defensive infrastructures**. 
+
+By wrapping probabilistic AI in deterministic controllers, we create systems that are:
+- **Resilient**: They don't break when the LLM hallucinates.
+- **Sovereign**: The developer, not the model provider, maintains total control over the logic.
+- **Transparent**: The execution path is a visible graph, not a hidden chain of thought.
+
+**We don't want agents that "try their best." We want agents that execute precisely.**

package/docs/tutoriels/ajouter-des-conditions.md

@@ -0,0 +1,150 @@
+---
+description: >-
+  Ajoutez des conditions pour orienter l'exécution en fonction des données du
+  contexte. Créez des branches conditionnelles pour adapter le parcours.
+---
+
+# Ajouter des conditions
+
+Dans ce tutoriel, nous allons apprendre **comment prendre des décisions dynamiques** dans un **GraphFlow**. Nous allons modifier notre graphe pour **choisir un chemin d'exécution** en fonction des données du contexte.
+
+Cela permet de :
+
+* **Modifier le flux d'exécution** en fonction des entrées.
+* **Créer des branches conditionnelles** (ex : Si `x > 10`, alors `A`, sinon `B`).
+* **Améliorer la flexibilité du graphe** en lui permettant de s'adapter aux données.
+
+***
+
+### **Ajouter des conditions à un graphe**
+
+Nous allons **ajouter une logique conditionnelle** qui :
+
+1. **Convert text to uppercase**.
+2. **Check text length**.
+3. **If text length > 10**, mark as **"LONG"**.
+4. **Else**, mark as **"SHORT"**.
+
+Nous utiliserons **une fonction `next` dynamique** qui **choisit** la prochaine étape en fonction des données.
+
+***
+
+### **Implémentation du graphe avec logique conditionnelle**
+
+Nous allons modifier **notre précédent GraphFlow** pour ajouter **deux branches conditionnelles**.
+
+```typescript
+import { GraphFlow, GraphNodeConfig } from "@ai.ntellect/core";
+import { z } from "zod";
+
+// Définition du schéma du contexte
+const schema = z.object({
+  input: z.string(),
+  processed: z.string().optional(),
+  result: z.string().optional(),
+});
+
+// Node 1: Convert text to uppercase
+const processText: GraphNodeConfig<typeof schema> = {
+  name: "processText",
+  execute: async (context) => {
+    context.processed = context.input.toUpperCase();
+    console.log("Text transformed:", context.processed);
+  },
+  next: (context) => {
+    return (context.processed?.length ?? 0) > 10
+      ? ["longTextHandler"]
+      : ["shortTextHandler"];
+  },
+};
+
+// Node 2A: Handle long text
+const longTextHandler: GraphNodeConfig<typeof schema> = {
+  name: "longTextHandler",
+  execute: async (context) => {
+    context.result = `LONG: ${context.processed}`;
+    console.log("Long text:", context.result);
+  },
+  next: ["logResult"],
+};
+
+// Node 2B: Handle short text
+const shortTextHandler: GraphNodeConfig<typeof schema> = {
+  name: "shortTextHandler",
+  execute: async (context) => {
+    context.result = `COURT: ${context.processed}`;
+    console.log("Short text:", context.result);
+  },
+  next: ["logResult"],
+};
+
+// Final node: Display result
+const logResult: GraphNodeConfig<typeof schema> = {
+  name: "logResult",
+  execute: async (context) => {
+    console.log("Final result:", context.result);
+  },
+};
+
+// Création du graphe
+const graph = new GraphFlow("GraphWithDecision", {
+  name: "GraphWithDecision",
+  nodes: [processText, longTextHandler, shortTextHandler, logResult],
+  context: { input: "" },
+  schema,
+  entryNode: "processText",
+});
+
+// Exécution du graphe avec différents inputs
+(async () => {
+    console.log("Execution with short text");
+    // ...
+    console.log("Execution with long text");
+  await graph.execute("processText", { input: "Hello GraphFlow!" });
+})();
+```
+
+***
+
+### **Explication du code**
+
+#### **Ajout d’un `next` dynamique**
+
+```typescript
+next: (context) => {
+  return (context.processed?.length ?? 0) > 10
+    ? ["longTextHandler"]
+    : ["shortTextHandler"];
+},
+```
+
+* **Si le texte est long** (`> 10 caractères`), on va vers **`longTextHandler`**.
+* **Sinon**, on va vers **`shortTextHandler`**.
+
+#### **Affichage du résultat final**
+
+* `longTextHandler` marque le texte comme **"LONG"**.
+* `shortTextHandler` marque le texte comme **"SHORT"**.
+* Le `logResult` affiche le **résultat final**.
+
+***
+
+### **Résultat attendu**
+
+#### Cas 1 : **Texte court**
+
+```
+Execution with short text
+Text transformed: HELLO
+Short text: COURT: HELLO
+Final result: COURT: HELLO
+```
+
+#### Cas 2 : **Long text**
+
+```
+Execution with long text
+Text transformed: HELLO GRAPHFLOW!
+Long text: LONG: HELLO GRAPHFLOW!
+Final result: LONG: HELLO GRAPHFLOW!
+```

package/docs/tutoriels/branching.md

@@ -0,0 +1,194 @@
+# Branching
+
+Le branching permet de créer des chemins d'exécution multiples dans votre graphe, que ce soit par condition, en parallèle, ou via un fan-out dynamique.
+
+## Branching conditionnel
+
+Utilisez `next` avec une condition pour diriger le flux vers différents nœuds :
+
+```typescript
+import { GraphFlow } from "@ai.ntellect/core";
+
+const workflow = new GraphFlow({
+  name: "order-process",
+  context: { amount: 0, status: "" },
+  nodes: [
+    {
+      name: "check_amount",
+      execute: async (ctx) => {
+        ctx.status = ctx.amount > 1000 ? "high" : "normal";
+      },
+      next: [
+        { when: (ctx) => ctx.status === "high", to: "manager_approval" },
+        { when: (ctx) => ctx.status === "normal", to: "auto_approve" },
+      ],
+    },
+    {
+      name: "manager_approval",
+      execute: async (ctx) => { ctx.approved = true; },
+      next: "notify",
+    },
+    {
+      name: "auto_approve",
+      execute: async (ctx) => { ctx.approved = true; },
+      next: "notify",
+    },
+    {
+      name: "notify",
+      execute: async (ctx) => { console.log("Commande approuvée"); },
+    },
+  ],
+});
+
+await workflow.execute("check_amount", { amount: 1500 });
+```
+
+## Parallélisation (Fork-Join)
+
+Activez `parallel: { enabled: true }` sur un nœud pour exécuter plusieurs branches simultanément. Utilisez `joinNode` pour spécifier où les branches se rejoignent.
+
+```typescript
+const workflow = new GraphFlow({
+  name: "parallel-processing",
+  context: { results: [], data: "test" },
+  nodes: [
+    {
+      name: "split",
+      execute: async (ctx) => { ctx.results = []; },
+      parallel: { enabled: true },
+      next: [
+        { to: "process_a", branchId: "a" },
+        { to: "process_b", branchId: "b" },
+        { to: "process_c", branchId: "c" },
+      ],
+    },
+    {
+      name: "process_a",
+      execute: async (ctx) => { ctx.results.push("A"); },
+      joinNode: "merge",
+    },
+    {
+      name: "process_b",
+      execute: async (ctx) => { ctx.results.push("B"); },
+      joinNode: "merge",
+    },
+    {
+      name: "process_c",
+      execute: async (ctx) => { ctx.results.push("C"); },
+      joinNode: "merge",
+    },
+    {
+      name: "merge",
+      execute: async (ctx) => {
+        console.log("Résultats:", ctx.results); // ["A", "B", "C"]
+      },
+    },
+  ],
+});
+
+await workflow.execute("split");
+```
+
+Chaque branche reçoit une copie isolée du contexte (`structuredClone`). Les résultats sont fusionnés selon les règles de réduction définies.
+
+## Reducers (fusion des résultats)
+
+Contrôlez comment les résultats des branches parallèles sont fusionnés avec des reducers :
+
+```typescript
+import { Reducers } from "@ai.ntellect/core";
+
+{
+  name: "split",
+  execute: async (ctx) => { ctx.results = []; },
+  parallel: { enabled: true },
+  reducers: [
+    { key: "results", reducer: Reducers.append }, // concatène les tableaux
+  ],
+  next: [
+    { to: "branch_a", branchId: "a" },
+    { to: "branch_b", branchId: "b" },
+  ],
+}
+```
+
+Reducers intégrés :
+- `Reducers.append` — concatène les tableaux
+- `Reducers.deepMerge` — fusion profonde (défaut)
+- `Reducers.lastWins` — garde la dernière valeur
+- `Reducers.sum` — additionne les nombres
+
+## Send API (fan-out dynamique)
+
+Le `send` API permet de créer dynamiquement des branches au runtime :
+
+```typescript
+import { SendAPI } from "@ai.ntellect/core";
+
+{
+  name: "distribute",
+  execute: async (ctx) => { ctx.processed = 0; },
+  send: (ctx) => {
+    const items = ctx.items || ["a", "b", "c"];
+    return SendAPI.map(items, (item, i) => ({
+      to: "process_item",
+      input: { item, index: i },
+      branchId: `item_${i}`,
+    }));
+  },
+  reducers: [
+    { key: "processed", reducer: (acc, val) => acc + val },
+  ],
+  joinNode: "done",
+},
+{
+  name: "process_item",
+  execute: async (ctx) => {
+    console.log("Traitement:", ctx.item);
+    return 1; // sera additionné par le reducer
+  },
+  joinNode: "done",
+},
+{
+  name: "done",
+  execute: async (ctx) => {
+    console.log("Total traité:", ctx.processed); // 3
+  },
+}
+```
+
+## Subgraphs (branches complexes)
+
+Une branche peut être un graphe complet enregistré via `SubgraphManager` :
+
+```typescript
+import { SubgraphManager } from "@ai.ntellect/core";
+
+const subgraph = new GraphFlow({
+  name: "subtask",
+  context: { result: "" },
+  nodes: [{
+    name: "run",
+    execute: async (ctx) => { ctx.result = "done"; },
+  }],
+});
+
+const manager = new SubgraphManager();
+manager.register("subtask", subgraph);
+
+// Utilisable comme branche parallèle
+{
+  name: "run_subgraph",
+  execute: async (ctx) => {},
+  parallel: { enabled: true },
+  next: [{ to: "subtask", subgraph: "subtask" }],
+  joinNode: "next",
+}
+```
+
+## Cas d'usage
+
+- **Validation parallèle** : Vérifier plusieurs conditions simultanément
+- **Pipeline de données** : Traiter des éléments indépendants en parallèle
+- **Fan-out dynamique** : Distribuer du travail selon la taille d'un tableau
+- **Subgraphs** : Décomposer un workflow complexe en composants réutilisables