@ai.ntellect/core 1.0.0 → 1.1.0

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

package/docs/tutoriels/checkpoint-usage.md

@@ -0,0 +1,99 @@
+# Utiliser les Checkpoints
+
+Ce tutoriel vous guide dans l'utilisation du système de checkpoints pour sauvegarder et reprendre des workflows.
+
+## Prérequis
+
+- Avoir lu [Créer un graphe simple](./creer-un-graphe-simple.md)
+- Comprendre les concepts de base de GraphFlow
+
+## Configuration de l'adaptateur
+
+```typescript
+import { GraphFlow } from "@ai.ntellect/core";
+import { InMemoryCheckpointAdapter } from "@ai.ntellect/core";
+import { z } from "zod";
+
+const Schema = z.object({
+  step: z.string(),
+  data: z.any().optional(),
+});
+
+const adapter = new InMemoryCheckpointAdapter();
+
+const workflow = new GraphFlow({
+  name: "checkpoint-demo",
+  schema: Schema,
+  context: { step: "start", data: null },
+  nodes: [
+    {
+      name: "step1",
+      execute: async (ctx) => {
+        ctx.step = "step1";
+        ctx.data = "Data processed - node 1";
+      },
+      next: ["step2"],
+    },
+    {
+      name: "step2",
+      execute: async (ctx) => {
+        ctx.step = "step2";
+        ctx.data = "Data processed - node 2";
+      },
+    },
+  ],
+});
+```
+
+## Exécution avec checkpoints
+
+```typescript
+// Démarrer l'exécution avec checkpointing
+const runId = await workflow.executeWithCheckpoint("step1", adapter);
+
+console.log(workflow.getContext().step); // "step1" ou "step2" selon le timing
+```
+
+## Lister les checkpoints
+
+```typescript
+const checkpoints = await workflow.listCheckpoints(adapter);
+console.log(checkpoints);
+// Affiche tous les checkpoints du run
+```
+
+## Reprendre l'exécution
+
+```typescript
+// Reprendre depuis le dernier checkpoint
+await workflow.resumeFromCheckpoint(runId, adapter);
+```
+
+## Voyage temporel
+
+```typescript
+// Reprendre depuis un checkpoint spécifique avec modification d'état
+const cpId = checkpoints[0].id; // Premier checkpoint
+await workflow.resumeFromCheckpoint(cpId, adapter, {
+  contextModifications: { step: "modified", data: "Changed!" },
+});
+```
+
+## Utiliser les breakpoints
+
+```typescript
+// Pause automatique avant certains nœuds
+await workflow.executeWithCheckpoint("step1", adapter, {
+  breakpoints: ["step2"], // Pause avant step2
+});
+// Le workflow s'arrête avant d'exécuter step2
+```
+
+## Résumé
+
+Vous savez maintenant:
+- ✅ Configurer un adaptateur de checkpoint
+- ✅ Exécuter un workflow avec sauvegarde automatique
+- ✅ Lister et reprendre des checkpoints
+- ✅ Faire du voyage temporel avec modification d'état
+- ✅ Utiliser des breakpoints pour pause humaine