@ai.ntellect/core 1.0.0 → 1.1.0

package/docs/tutoriels/creer-un-agent.md

@@ -0,0 +1,108 @@
+# Building Tool-Using Agents
+
+An **Agent** is a high-level entity that combines an LLM's reasoning with GraphFlow's deterministic execution. 
+
+Instead of letting the LLM "guess" how to solve a problem, we give it a set of **Tools** (which are just GraphFlows) and let it decide which one to use.
+
+## 🛠️ Step 1: Create the Tools
+
+A tool is simply a `GraphFlow`. The LLM uses the `name` and the `Zod schema` to understand what the tool does and what parameters it needs.
+
+```typescript
+import { z } from "zod";
+import { GraphFlow } from "@ai.ntellect/core";
+
+// Tool 1: A simple calculator
+const calculator = new GraphFlow({
+  name: "calculator",
+  schema: z.object({
+    a: z.number(),
+    b: z.number(),
+    operation: z.enum(["add", "subtract", "multiply", "divide"]),
+    result: z.number().optional(),
+  }),
+  context: { a: 0, b: 0, operation: "add" },
+  nodes: [{
+    name: "calc",
+    execute: async (ctx) => {
+      if (ctx.operation === "add") ctx.result = ctx.a + ctx.b;
+      // ... other operations
+    }
+  }],
+});
+
+// Tool 2: A web search tool
+const webSearch = new GraphFlow({
+  name: "web_search",
+  schema: z.object({
+    query: z.string(),
+    results: z.array(z.string()).optional(),
+  }),
+  context: { query: "", results: [] },
+  nodes: [{
+    name: "search",
+    execute: async (ctx) => {
+      const res = await fetch(`https://api.example.com/search?q=${ctx.query}`);
+      ctx.results = await res.json();
+    }
+  }],
+});
+```
+
+## 🤖 Step 2: Initialize the Agent
+
+The `Agent` class handles the "Cognitive Loop": **Think $\rightarrow$ Execute $\rightarrow$ Reply**.
+
+```typescript
+import { Agent } from "@ai.ntellect/core";
+
+const agent = new Agent({
+  role: "Research Assistant",
+  goal: "Provide accurate data and calculations",
+  tools: [calculator, webSearch],
+  llmConfig: { 
+    provider: "ollama", 
+    model: "llama3" 
+  },
+});
+```
+
+## 🚀 Step 3: Process a Request
+
+When you call `agent.process()`, the following happens:
+1. **Analyze**: The LLM looks at the user request and the available tools.
+2. **Select**: The LLM chooses the best tool and extracts the parameters.
+3. **Execute**: The framework runs the selected `GraphFlow` deterministically.
+4. **Synthesize**: The LLM takes the tool result and formulates a final answer.
+
+```typescript
+const response = await agent.process("Search for the current price of Bitcoin and multiply it by 2");
+
+// The agent will:
+// 1. Call 'web_search' with { query: "current price of Bitcoin" }
+// 2. Take the result and call 'calculator' with { a: price, b: 2, operation: "multiply" }
+// 3. Return: "The current price is X, so double that is Y."
+```
+
+---
+
+## 🧠 Pro Tip: Adding Memory
+
+By default, an agent might forget what it just did. Enable `memory: true` to allow the agent to track its own history and avoid repeating the same mistake.
+
+```typescript
+const smartAgent = new Agent({
+  // ... other config
+  memory: true,
+});
+```
+
+## ⚖️ Agent vs. CortexFlow
+
+| Agent (Standard) | CortexFlow (Deterministic) |
+| :--- | :--- |
+| LLM chooses tools in a loop | LLM classifies intent once |
+| High flexibility, higher drift | Low drift, total predictability |
+| Best for open-ended exploration | Best for business-critical workflows |
+
+**Rule of thumb**: Use the `Agent` module for "Assistant" behavior, and `CortexFlow` for "Workflow" behavior.

package/docs/tutoriels/creer-un-graphe-simple.md

@@ -0,0 +1,92 @@
+# Building Your First Workflow
+
+In this guide, we'll move from a single node to a **complete pipeline**. We will build a data processing workflow that retrieves, transforms, and logs information.
+
+## 🏗️ The Blueprint
+
+We want to create a three-step process:
+`Retrieve Data` $\rightarrow$ `Transform to Uppercase` $\rightarrow$ `Log Result`
+
+### 1. Define the State (Schema)
+The **Schema** is the most important part of a GraphFlow. It acts as a contract. If a node tries to set a value that doesn't match the schema, the workflow will throw an error immediately.
+
+```typescript
+import { z } from "zod";
+
+const DataSchema = z.object({
+  rawInput: z.string(),
+  processedData: z.string().optional(),
+  finalResult: z.string().optional(),
+});
+```
+
+### 2. Define the Nodes
+Each node is a discrete unit of logic. We use the `next` property to define the path.
+
+```typescript
+const retrieveNode = {
+  name: "retrieve",
+  execute: async (ctx) => {
+    ctx.rawInput = "deterministic orchestration is powerful";
+  },
+  next: "transform", // Go to 'transform' next
+};
+
+const transformNode = {
+  name: "transform",
+  execute: async (ctx) => {
+    ctx.processedData = ctx.rawInput.toUpperCase();
+  },
+  next: "log", // Go to 'log' next
+};
+
+const logNode = {
+  name: "log",
+  execute: async (ctx) => {
+    ctx.finalResult = `SUCCESS: ${ctx.processedData}`;
+    console.log(ctx.finalResult);
+  },
+};
+```
+
+### 3. Assemble the GraphFlow
+
+```typescript
+import { GraphFlow } from "@ai.ntellect/core";
+
+const workflow = new GraphFlow({
+  name: "DataPipeline",
+  schema: DataSchema,
+  context: { rawInput: "", processedData: "", finalResult: "" },
+  nodes: [retrieveNode, transformNode, logNode],
+});
+
+await workflow.execute("retrieve");
+```
+
+---
+
+## ⚡ Advanced Routing: Dynamic Branching
+
+In the real world, workflows aren't always linear. You can make the `next` property a **function** to create conditional logic.
+
+**Example: High-Value Path**
+```typescript
+const checkAmount = {
+  name: "checkAmount",
+  execute: async (ctx) => {
+    ctx.amount = 150;
+  },
+  next: (ctx) => {
+    return ctx.amount > 100 ? ["premium_flow"] : ["standard_flow"];
+  },
+};
+
+// Now the workflow splits based on the value of 'amount'
+```
+
+## 🚀 Summary
+You've just built a deterministic pipeline. Unlike a standard script, this workflow is:
+1. **Observable**: You can track exactly which node is running.
+2. **Type-Safe**: Zod ensures your data is always correct.
+3. **Extensible**: You can add a "Retry" or "Checkpoint" to any node without rewriting the whole logic.

package/docs/tutoriels/gerer-les-erreurs.md

@@ -0,0 +1,124 @@
+---
+description: >-
+  Implémentez des stratégies de gestion d'erreurs, définissez des tentatives de
+  reprise et assurez-vous que votre graphe réagit aux échecs de manière
+  contrôlée.
+---
+
+# Gérer les erreurs
+
+Dans ce tutoriel, nous allons voir **comment gérer les erreurs et les retries** dans un graphe **GraphFlow**.
+
+L'objectif est de :
+
+* **Détecter une erreur** et l'afficher.
+* **Mettre en place un retry automatique** en cas d'échec d'un nœud.
+* **Continuer l'exécution même après un échec** si nécessaire.
+
+***
+
+### **Ajouter une gestion des erreurs et retries**
+
+Nous allons **modifier le nœud `retrieveData`** pour qu'il **puisse échouer** et **être retenté automatiquement**.
+
+#### **Modification :**
+
+* On ajoute une **erreur simulée** dans `retrieveData`.
+* On active un **retry** avec `maxAttempts: 2` et un délai de 2 secondes.
+* Si le retry échoue, on affiche un message et on continue l'exécution.
+
+Voici **le code complet avec cette nouvelle gestion** :
+
+```typescript
+import { GraphFlow, GraphNodeConfig } from "@ai.ntellect/core";
+import { z } from "zod";
+
+// Définition du contexte
+const schema = z.object({
+  input: z.string(),
+  processed: z.string().optional(),
+  result: z.string().optional(),
+});
+
+// Step 1: Retrieve data (with simulated error)
+const retrieveData: GraphNodeConfig<typeof schema> = {
+  name: "retrieveData",
+  execute: async (context) => {
+    console.log("Attempting to retrieve data...");
+    if (Math.random() < 0.7) {
+      throw new Error("Simulated error during data retrieval!");
+    }
+    context.input = "Hello, GraphFlow!";
+      console.log("Data retrieved:", context.input);
+  },
+  retry: {
+    maxAttempts: 2, // On tente 2 fois avant d'abandonner
+    delay: 2000, // 2 secondes d'attente entre chaque tentative
+    onRetryFailed: async (error) => {
+      console.log("❌ Retry failed:", error.message);
+    },
+    continueOnFailed: true, // On continue l'exécution même en cas d'échec
+  },
+  next: ["processData"],
+};
+
+// Step 2: Transform data
+const processData: GraphNodeConfig<typeof schema> = {
+  name: "processData",
+  execute: async (context) => {
+    if (!context.input) {
+      console.log("No data retrieved, cannot transform.");
+      return;
+    }
+    context.processed = context.input.toUpperCase();
+    console.log("Data transformed:", context.processed);
+  },
+  next: ["logResult"],
+};
+
+// Step 3: Display result
+const logResult: GraphNodeConfig<typeof schema> = {
+  name: "logResult",
+  execute: async (context) => {
+    if (!context.processed) {
+       console.log("No result to display.");
+      return;
+    }
+    console.log("Final Result:", context.result);
+  },
+};
+
+// Construction du graphe
+const graphDefinition = {
+  name: "SimpleGraph",
+  nodes: [retrieveData, processData, logResult],
+  context: { input: "" },
+  schema,
+  entryNode: "retrieveData",
+};
+
+// Exécution du graphe
+const graph = new GraphFlow("SimpleGraph", graphDefinition);
+
+(async () => {
+  try {
+    console.log("Executing graph...");
+    await graph.execute("retrieveData");
+     console.log("Graph completed!");
+  } catch (error) {
+     console.error("Error:", error);
+  }
+})();
+```
+
+***
+
+### **Explication des changements**
+
+1. **Simulated error in `retrieveData`** : 70% chance of failure.
+2. **Automatic retry** : Up to 2 attempts with **2 second delay**.
+3. **If retry fails**, a message is displayed (`onRetryFailed`).
+4. **Continue execution** even if `retrieveData` fails (`continueOnFailed: true`).
+5. **If data retrieval completely fails**, `processData` and `logResult` execute but display a warning.
+
+**Important** : Le graphe peut avoir **différents comportements** en fonction de si l'erreur est résolue ou non après les retries.

package/docs/tutoriels/pour-commencer.md

@@ -0,0 +1,73 @@
+# Quick Start Guide
+
+Welcome to **@ai.ntellect/core**. This guide will take you from zero to your first deterministic workflow in less than 5 minutes.
+
+## 1. Installation
+
+Install the core package and Zod (used for state validation):
+
+```sh
+pnpm add @ai.ntellect/core zod
+```
+
+## 2. Your First Workflow: "Hello World"
+
+The basic unit of execution in this framework is the `GraphFlow`. Create a file named `index.ts`:
+
+```typescript
+import { z } from "zod";
+import { GraphFlow } from "@ai.ntellect/core";
+
+// 1. Define the state shape (This ensures your agent never crashes due to missing data)
+const Schema = z.object({
+  message: z.string(),
+});
+
+// 2. Define the workflow
+const workflow = new GraphFlow({
+  name: "hello-world",
+  schema: Schema,
+  context: { message: "" },
+  nodes: [
+    {
+      name: "greet",
+      execute: async (ctx) => {
+        ctx.message = "Hello from @ai.ntellect/core!";
+        console.log("Node 'greet' executed.");
+      },
+    },
+  ],
+});
+
+// 3. Run it
+async function run() {
+  await workflow.execute("greet");
+  console.log("Final State:", workflow.getContext().message);
+}
+
+run();
+```
+
+## 3. Running the code
+
+Use `ts-node` to execute your TypeScript file directly:
+
+```sh
+pnpm ts-node index.ts
+```
+
+**Expected Output:**
+```text
+Node 'greet' executed.
+Final State: Hello from @ai.ntellect/core!
+```
+
+---
+
+## 🧭 What's Next?
+
+Now that you've run a simple node, it's time to explore the real power of the framework:
+
+- **Want to chain multiple steps?** $\rightarrow$ [Build a Simple Graph](./creer-un-graphe-simple.md)
+- **Want to add an LLM?** $\rightarrow$ [Create a Tool-Using Agent](./creer-un-agent.md)
+- **Want to handle real-world events?** $\rightarrow$ [Explore Event-Driven Nodes](../core/les-evenements.md)

package/docs/tutoriels/retry.md

@@ -0,0 +1,166 @@
+# Retry
+
+Le retry permet de gérer les échecs temporaires en réessayant l'exécution d'un nœud avec une stratégie de délai configurable.
+
+## Configuration de base
+
+Ajoutez une configuration `retry` sur n'importe quel nœud :
+
+```typescript
+import { GraphFlow } from "@ai.ntellect/core";
+
+const workflow = new GraphFlow({
+  name: "api-fetch",
+  context: { data: null, attempts: 0 },
+  nodes: [
+    {
+      name: "fetch_api",
+      execute: async (ctx) => {
+        ctx.attempts++;
+        const response = await fetch("https://api.example.com/data");
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        ctx.data = await response.json();
+      },
+      retry: {
+        maxAttempts: 3,
+        backoff: "exponential",
+        delay: 1000, // délai initial en ms
+      },
+    },
+  ],
+});
+
+await workflow.execute("fetch_api");
+console.log(`Récupéré après ${workflow.getContext().attempts} tentative(s)`);
+```
+
+## Stratégies de backoff
+
+### Fixed (fixe)
+
+Délai constant entre chaque tentative :
+
+```typescript
+retry: {
+  maxAttempts: 3,
+  backoff: "fixed",
+  delay: 1000, // 1 seconde à chaque fois
+}
+```
+
+### Linear (linéaire)
+
+Délai qui augmente linéairement (`delay * attempt`) :
+
+```typescript
+retry: {
+  maxAttempts: 3,
+  backoff: "linear",
+  delay: 1000, // 1s, 2s, 3s...
+}
+```
+
+### Exponential (exponentiel)
+
+Délai qui double à chaque tentative (`delay * 2^(attempt-1)`) :
+
+```typescript
+retry: {
+  maxAttempts: 3,
+  backoff: "exponential",
+  delay: 1000, // 1s, 2s, 4s...
+}
+```
+
+## Exemple complet avec gestion d'erreur
+
+```typescript
+const workflow = new GraphFlow({
+  name: "robust-fetch",
+  context: { data: null, error: null, attempts: 0 },
+  nodes: [
+    {
+      name: "fetch_with_retry",
+      execute: async (ctx) => {
+        ctx.attempts++;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+
+        try {
+          const response = await fetch("https://api.example.com/data", {
+            signal: controller.signal,
+          });
+          clearTimeout(timeout);
+
+          if (!response.ok) throw new Error(`HTTP ${response.status}`);
+          ctx.data = await response.json();
+        } catch (err) {
+          if (ctx.attempts >= 3) {
+            ctx.error = err.message;
+            throw err; // Propager après le dernier essai
+          }
+          throw err; // Déclenche le retry
+        }
+      },
+      retry: {
+        maxAttempts: 3,
+        backoff: "exponential",
+        delay: 1000,
+      },
+      next: [
+        { when: (ctx) => !ctx.error, to: "success" },
+        { when: (ctx) => ctx.error, to: "handle_error" },
+      ],
+    },
+    {
+      name: "success",
+      execute: async (ctx) => {
+        console.log("Success:", ctx.data);
+      },
+    },
+    {
+      name: "handle_error",
+      execute: async (ctx) => {
+        console.error("Failure after", ctx.attempts, "attempts:", ctx.error);
+      },
+    },
+  ],
+});
+```
+
+## Retry avec état persistant
+
+Combinez le retry avec le système de checkpoints pour survivre à un redémarrage :
+
+```typescript
+import { InMemoryCheckpointAdapter } from "@ai.ntellect/core";
+
+const adapter = new InMemoryCheckpointAdapter();
+
+const workflow = new GraphFlow({
+  name: "resilient-task",
+  context: { attempts: 0 },
+  nodes: [
+    {
+      name: "unstable_task",
+      execute: async (ctx) => {
+        ctx.attempts++;
+        if (Math.random() < 0.7) throw new Error("Aleatory failure");
+        ctx.done = true;
+      },
+      retry: { maxAttempts: 5, backoff: "exponential", delay: 500 },
+    },
+  ],
+});
+
+// Avec checkpoint, l'état des tentatives est préservé
+await workflow.executeWithCheckpoint("unstable_task", {}, adapter);
+```
+
+## Cas d'usage
+
+- **Appels API instables** : Réessayer en cas d'erreurs réseau (429, 500, 503)
+- **Opérations de base de données** : Gérer les verrous temporaires ou timeouts
+- **Services tiers** : Tolérance aux pannes transientes
+- **Webhooks** : Garantir la livraison malgré les erreurs temporaires
+- **LLM calls** : Gérer les rate limits des API d'IA

package/execution/adapters/in-memory-checkpoint.ts

@@ -0,0 +1,35 @@
+import { ICheckpointAdapter } from "../../interfaces";
+import { Checkpoint } from "../../types";
+
+export class InMemoryCheckpointAdapter implements ICheckpointAdapter {
+  private storage = new Map<string, Checkpoint>();
+
+  async save(checkpoint: Checkpoint): Promise<void> {
+    this.storage.set(checkpoint.id, structuredClone(checkpoint));
+  }
+
+  async load(id: string): Promise<Checkpoint | null> {
+    const cp = this.storage.get(id);
+    return cp ? structuredClone(cp) : null;
+  }
+
+  async list(graphName: string): Promise<Checkpoint[]> {
+    return Array.from(this.storage.values())
+      .filter((cp) => cp.graphName === graphName)
+      .sort((a, b) => b.metadata.createdAt - a.metadata.createdAt);
+  }
+
+  async delete(id: string): Promise<void> {
+    this.storage.delete(id);
+  }
+
+  async clear(graphName?: string): Promise<void> {
+    if (!graphName) {
+      this.storage.clear();
+      return;
+    }
+    for (const [id, cp] of this.storage) {
+      if (cp.graphName === graphName) this.storage.delete(id);
+    }
+  }
+}

package/execution/compiler.ts

@@ -0,0 +1,47 @@
+import { GraphFlow } from './index';
+import { z } from 'zod';
+import { Plan } from './planner';
+import { ToolRegistry } from './registry';
+
+export function compilePlan(plan: Plan, registry: ToolRegistry): { graph: GraphFlow<any>; startNode: string } {
+  const graph = new GraphFlow<any>({
+    name: 'compiled-plan',
+    context: {},
+    schema: z.object({}).passthrough(),
+    nodes: [],
+    entryNode: '',
+  });
+
+  plan.steps.forEach((step, index) => {
+    const tool = registry.get(step.node);
+    if (!tool) {
+      throw new Error(`Unknown tool: ${step.node}`);
+    }
+
+    const nodeName = `step_${index}_${step.node}`;
+    const nextNode = index < plan.steps.length - 1
+      ? `step_${index + 1}_${plan.steps[index + 1].node}`
+      : undefined;
+
+    graph.addNode({
+      name: nodeName,
+      execute: async (ctx: any) => {
+        // Merge accumulated context with step params
+        const toolCtx = { ...ctx, ...step.params };
+        console.log(`  [${nodeName}] Executing ${step.node} with:`, toolCtx);
+
+        // Execute the tool's graph
+        const resultCtx = await tool.graph.execute(tool.startNode, toolCtx);
+
+        // Merge tool result back into ctx (which is the graph's context)
+        Object.assign(ctx, resultCtx, { _lastStep: step.node });
+        console.log(`  [${nodeName}] Updated context:`, ctx);
+      },
+      next: nextNode,
+    });
+  });
+
+  const startNode = plan.steps.length > 0 ? `step_0_${plan.steps[0].node}` : '';
+
+  return { graph, startNode };
+}