@ai.ntellect/core 1.0.0 → 1.1.0

package/docs/core/graphflow.md

@@ -0,0 +1,137 @@
+# GraphFlow: The Execution Engine
+
+`GraphFlow` is the primary primitive for defining a workflow in `@ai.ntellect/core`. Think of it as a **typed state machine** where each transition is a validated step.
+
+## 🏗️ Creating a Workflow
+
+A GraphFlow consists of a **Schema** (Zod), an initial **Context**, and a set of **Nodes**.
+
+```typescript
+import { z } from "zod";
+import { GraphFlow } from "@ai.ntellect/core";
+
+// 1. Define the state shape (MANDATORY for validation)
+const OrderSchema = z.object({
+  orderId: z.string(),
+  status: z.string(),
+  amount: z.number(),
+});
+
+// 2. Define the workflow
+const orderWorkflow = new GraphFlow({
+  name: "OrderProcessing",
+  schema: OrderSchema,
+  context: { orderId: "", status: "pending", amount: 0 },
+  nodes: [
+    {
+      name: "validate_order",
+      execute: async (ctx) => {
+        if (ctx.amount <= 0) throw new Error("Invalid amount");
+        ctx.status = "validated";
+      },
+      next: "process_payment",
+    },
+    {
+      name: "process_payment",
+      execute: async (ctx) => {
+        // Payment logic here
+        ctx.status = "paid";
+      },
+    },
+  ],
+});
+
+await orderWorkflow.execute("validate_order");
+```
+
+---
+
+## 🛣️ Routing Logic
+
+### Sequential & Conditional Execution
+Nodes move to the next step via the `next` property. This can be:
+- **Static**: `next: "nextNodeName"`
+- **Dynamic**: `next: (ctx) => ctx.amount > 100 ? "high_value_flow" : "standard_flow"`
+
+### Parallel Execution (Fork-Join Model)
+You can execute multiple branches concurrently to reduce latency.
+```typescript
+{
+  name: "start",
+  parallel: { enabled: true, joinNode: "merge" },
+  next: ["fetch_user", "fetch_inventory", "check_credit"],
+}
+```
+The engine clones the context for each branch, executes them via `Promise.all`, and merges the results into the `joinNode` using a **Reducer**.
+
+### Dynamic Fan-Out (The Send API)
+When the number of parallel branches is determined at runtime (e.g., processing a list of items), use the `send` API:
+```typescript
+{
+  name: "distribute",
+  send: (ctx) => ctx.items.map(item => ({
+    to: "processItem",
+    input: { item },
+  })),
+  parallel: { enabled: true, joinNode: "complete" },
+}
+```
+
+---
+
+## ⚡ Event-Driven Nodes
+
+A node can pause execution and wait for an external signal. This is critical for **Human-in-the-Loop** or **Asynchronous Integrations**.
+
+```typescript
+{
+  name: "await_approval",
+  when: {
+    events: ["manager.approved"],
+    timeout: 86400000, // 24 hours
+    strategy: { type: "single" },
+  },
+  execute: async (ctx, _, event) => {
+    ctx.approvedBy = event.payload.managerId;
+    ctx.status = "approved";
+  },
+}
+```
+
+### Event Strategies
+- **`single`**: Fires on the first matching event.
+- **`all`**: Fires only after *every* listed event has arrived.
+- **`correlate`**: Fires when events arrive that match a custom correlation function (e.g., matching `orderId`).
+
+---
+
+## 🔍 Observability & State
+
+Because GraphFlow is deterministic, it is fully observable.
+
+### Reactive State Tracking
+You can subscribe to context changes in real-time:
+```typescript
+workflow.observe().property("status").subscribe(s => console.log(`Status: ${s}`));
+```
+
+### Formal Validation
+The Zod schema isn't just for TypeScript types; it's a **runtime guard**. If a node attempts to set the context to an invalid state, the GraphFlow throws an error immediately, preventing corrupted state from propagating.
+
+---
+
+## 📖 API Reference
+
+### `GraphFlow` Methods
+- `execute(nodeName, initialContext)`: Starts the workflow.
+- `emit(event, payload)`: Triggers event-driven nodes.
+- `getContext()`: Returns the current validated state.
+- `observe()`: Returns an observer for state and event tracking.
+
+### `GraphNodeConfig` Properties
+- `name`: Unique identifier.
+- `execute`: The core logic function.
+- `next`: Routing logic (string or function).
+- `when`: Event-wait configuration.
+- `parallel`: Fork-Join configuration.
+- `retry`: Backoff and attempt configuration.

package/docs/core/introduction.md

@@ -0,0 +1,41 @@
+# Introduction
+
+Welcome to the core of **@ai.ntellect/core**. This framework is built on the principle that **AI agents in production must be deterministic**.
+
+While most frameworks focus on "autonomy" (letting the LLM decide everything), we focus on **Orchestration**. We provide the tools to wrap probabilistic AI in a deterministic shell, ensuring your agent doesn't drift, hallucinate its routing, or enter infinite loops.
+
+---
+
+## 🛠️ The Three Pillars of the Core
+
+### 1. Graph-Based Execution (GraphFlow)
+At the lowest level, we use **GraphFlow**. A GraphFlow is a typed directed graph where each node is a discrete unit of logic.
+- **Modular**: Each node is an independent action.
+- **Typed**: Every transition is validated via Zod, preventing runtime type errors.
+- **Dynamic**: Nodes can execute sequentially, in parallel (Fork-Join), or based on conditional logic.
+
+### 2. Event-Driven Reactivity
+Our engine doesn't just run from start to finish; it lives in a state of reactivity.
+- **External Triggers**: Nodes can pause and wait for webhooks, blockchain events, or user actions.
+- **Asynchronousity**: The system can handle thousands of paused workflows, resuming them only when the required event arrives.
+- **Interoperability**: By using an `IEventEmitter` interface, the framework integrates seamlessly with any event-driven architecture.
+
+### 3. Deterministic Orchestration (CortexFlow)
+This is where the "Intelligence" meets "Control." CortexFlow implements the **Classifier-Controller Split**:
+- **The LLM as the Classifier**: It identifies the *Intent* of the user request.
+- **The Petri Net as the Controller**: It routes that intent through a mathematically verified path.
+
+By moving the routing logic out of the LLM and into a Petri Net, we achieve **formal verification**. We can prove, before a single line of code runs, that your workflow is free of deadlocks and that all states are reachable.
+
+---
+
+## 🚀 Why this matters for Production
+
+| The "Autonomous" Approach | The "@ai.ntellect/core" Approach |
+| :--- | :--- |
+| LLM decides the next step at every turn | LLM decides the *intent* once |
+| Hallucinations lead to routing errors | Routing is deterministic and verified |
+| Prompt engineering is used to "fix" flow | Graph structure defines the flow |
+| Debugging involves "guessing" LLM state | Debugging involves tracing a state machine |
+
+**In short: We move AI from "guessing" to "executing."**

package/docs/core/les-evenements.md

@@ -0,0 +1,95 @@
+# Event-Driven Workflows
+
+In most traditional code, a function starts and runs until it returns. In `@ai.ntellect/core`, a workflow can **pause and wait for the world to change**.
+
+This is achieved through **Event-Driven Nodes**.
+
+## ⚙️ How it Works
+
+An event-driven node uses the `when` property to define its trigger conditions. When the engine reaches such a node, it does not execute the `execute` function immediately. Instead, it:
+1. Saves the current state (Checkpoint).
+2. Registers a listener for the specified events.
+3. Pauses execution.
+
+Once the event arrives via `workflow.emit()`, the engine wakes up, validates the event, and executes the node logic.
+
+---
+
+## 🛠️ Configuration & Strategies
+
+### 1. The `single` Strategy
+The simplest form of reactivity. The node fires as soon as any one of the listed events occurs.
+```typescript
+when: {
+  events: ["payment.received", "payment.manual_override"],
+  strategy: { type: "single" },
+}
+```
+
+### 2. The `all` Strategy
+Used for synchronization. The node only executes after *all* required events have been received.
+```typescript
+when: {
+  events: ["identity.verified", "credit.checked"],
+  strategy: { type: "all" },
+}
+```
+
+### 3. The `correlate` Strategy (Advanced)
+In a multi-user system, you receive thousands of events. You need to ensure the event you receive belongs to the **current workflow instance**.
+
+The `correlate` strategy allows you to provide a function that matches event payloads to the workflow context.
+```typescript
+when: {
+  events: ["order.shipped"],
+  strategy: {
+    type: "correlate",
+    correlation: (events) => 
+      events[0].payload.orderId === ctx.orderId,
+  },
+}
+```
+
+---
+
+## 📡 Emitting Events
+
+Events can be emitted from anywhere in your application—an API endpoint, a webhook handler, or even another GraphFlow.
+
+```typescript
+// Trigger a waiting node in a specific workflow instance
+await workflow.emit("payment.received", {
+  orderId: "order_123",
+  amount: 49.99,
+  timestamp: Date.now(),
+});
+```
+
+---
+
+## ⏱️ Timeouts & Resilience
+
+What happens if the event never arrives? To prevent "zombie" workflows, you can define a `timeout`.
+
+```typescript
+when: {
+  events: ["user.approval"],
+  timeout: 3600000, // 1 hour
+  strategy: { type: "single" },
+}
+```
+If the timeout is reached, the workflow can either:
+1. Throw a timeout error.
+2. Move to a fallback node (via the `next` logic).
+
+## 📈 Use Case: The "Human-in-the-Loop" Pattern
+
+Event-driven nodes are the foundation of **Human-in-the-Loop (HITL)**.
+
+1. **Workflow reaches a sensitive node** (e.g., `execute_large_transfer`).
+2. **Workflow pauses** using a `when` node waiting for `admin.approved`.
+3. **Admin receives an email** with a link.
+4. **Admin clicks "Approve"**, which triggers an API call to `workflow.emit("admin.approved", { ... })`.
+5. **Workflow resumes** and completes the transfer.
+
+This turns a risky autonomous action into a secure, audited business process.

package/docs/modules/agenda/README.md

@@ -0,0 +1,63 @@
+# Module Agenda
+
+Planification de tâches récurrentes avec expressions cron. L'agenda s'exécute en processus — quand le cron correspond, votre fonction de tâche s'exécute.
+
+## Installation
+
+Le module est inclus dans le package principal:
+
+```typescript
+import { Agenda } from "@ai.ntellect/core";
+```
+
+## Utilisation de base
+
+```typescript
+import { Agenda, NodeCronAdapter } from "@ai.ntellect/core";
+
+const agenda = new Agenda(new NodeCronAdapter());
+
+// Toutes les heures
+agenda.schedule("0 * * * *", async () => {
+  console.log("Tâche horaire en cours");
+});
+
+// Tâche nommée pour annulation
+agenda.schedule("daily_cleanup", "0 0 * * *", async () => {
+  console.log("Nettoyage quotidien");
+});
+```
+
+## Syntaxe cron
+
+Utilise `node-cron` en arrière-plan. La syntaxe suit les conventions cron standard:
+
+```
+* * * * * *
+│ │ │ │ │ │
+│ │ │ │ │ └── Jour de la semaine (0-7, 0 et 7 = dimanche)
+│ │ │ │ └──── Mois (1-12)
+│ │ │ └────── Jour du mois (1-31)
+│ │ └──────── Heure (0-23)
+│ └────────── Minute (0-59)
+└──────────── Seconde (0-59, optionnel)
+```
+
+## API
+
+- `schedule(cronExpression: string, task: Function): void`
+- `schedule(name: string, cronExpression: string, task: Function): void`
+- `cancel(name: string): void`
+
+## Intégration avec l'Agent
+
+L'agent peut utiliser l'agenda pour planifier des réveils:
+
+```typescript
+const agent = new Agent({
+  role: "Assistant",
+  enableSchedule: true,
+  agenda: agenda,
+  // ...
+});
+```

package/docs/modules/agenda/interface-iagenda.md

@@ -0,0 +1,170 @@
+---
+description: >-
+  L’interface IAgenda définit les fonctionnalités essentielles pour planifier,
+  exécuter et gérer des tâches dans un système de workflows automatisés.
+---
+
+# Interface IAgenda
+
+L’interface **IAgenda** définit les fonctionnalités essentielles pour **planifier, exécuter et gérer des tâches** dans un système automatisé.
+
+Ce module suit une approche **agnostique du moteur**, permettant une intégration avec **différents services de planification** (**Node-Cron, Redis, AWS EventBridge**) ainsi qu’un **stockage persistant des tâches** via **IMemoryAdapter**.
+
+***
+
+### **Objectif de l'interface**
+
+L'interface **IAgenda** doit permettre :
+
+* **Planification dynamique** de tâches périodiques ou ponctuelles.
+* **Stockage et récupération** des tâches planifiées via **IMemoryAdapter**.
+* **Gestion complète du cycle de vie** des tâches (**création, exécution, annulation**).
+* **Intégration avec un moteur de planification configurable** (**ICronService**).
+* **Persistance des tâches après redémarrage** via un stockage mémoire.
+* **Interopérabilité avec plusieurs moteurs de planification** (local, distribué, cloud).
+
+***
+
+### **Définition de l’interface**
+
+```ts
+/**
+ * Interface pour la gestion des tâches planifiées
+ */
+export interface IAgenda {
+  /**
+   * Planifie une tâche à exécuter périodiquement ou une seule fois.
+   * @param {ScheduledTaskInput} request - Configuration de la tâche à planifier.
+   * @param {ScheduledTaskCallbacks} [callbacks] - Callbacks pour suivre l’exécution.
+   * @returns {Promise<string>} ID unique de la tâche planifiée.
+   */
+  scheduleTask(
+    request: ScheduledTaskInput,
+    callbacks?: ScheduledTaskCallbacks
+  ): Promise<string>;
+
+  /**
+   * Annule une tâche planifiée en fonction de son ID.
+   * @param {string} taskId - ID de la tâche à annuler.
+   * @returns {Promise<boolean>} `true` si la tâche a été annulée, sinon `false`.
+   */
+  cancelTask(taskId: string): Promise<boolean>;
+
+  /**
+   * Récupère toutes les tâches planifiées stockées en mémoire.
+   * @returns {Promise<ScheduledTask[]>} Liste des tâches stockées.
+   */
+  getScheduledTasks(): Promise<ScheduledTask[]>;
+
+  /**
+   * Annule toutes les tâches planifiées.
+   * @returns {Promise<void>}
+   */
+  cancelAllTasks(): Promise<void>;
+
+  /**
+   * Arrête l’ensemble des tâches et libère les ressources.
+   * @returns {Promise<void>}
+   */
+  shutdown(): Promise<void>;
+}
+```
+
+***
+
+### **Interfaces associées**
+
+#### **ScheduledTaskInput : Définition d’une tâche planifiée**
+
+```ts
+/**
+ * Configuration d'une tâche planifiée
+ */
+export interface ScheduledTaskInput {
+  /** ID unique de la tâche (optionnel) */
+  id?: string;
+  /** Requête ou action à exécuter */
+  originalRequest: string;
+  /** Expression `cron` définissant la récurrence */
+  cronExpression: string;
+  /** Indique si la tâche est récurrente */
+  isRecurring?: boolean;
+  /** Date de début d’exécution (optionnel) */
+  startDate?: Date;
+}
+```
+
+***
+
+#### **ScheduledTask : Représentation d’une tâche active**
+
+```ts
+/**
+ * Représentation d'une tâche planifiée
+ */
+export interface ScheduledTask extends ScheduledTaskInput {
+  /** ID unique attribué à la tâche */
+  id: string;
+  /** Date de création de la tâche */
+  createdAt: Date;
+}
+```
+
+***
+
+#### **ScheduledTaskCallbacks : Suivi de l’exécution**
+
+```ts
+/**
+ * Callbacks pour suivre l'exécution d'une tâche planifiée
+ */
+export interface ScheduledTaskCallbacks {
+  /** Appelé lorsque la tâche est planifiée */
+  onScheduled?: (id: string) => void;
+  /** Appelé lorsque la tâche est exécutée */
+  onExecuted?: (id: string, originalRequest: string) => void;
+}
+```
+
+***
+
+### **Pourquoi cette interface ?**
+
+L’interface **IAgenda** offre plusieurs avantages en termes de conception et d’extensibilité :
+
+#### **Indépendance du moteur de planification**
+
+* Compatible avec **Node-Cron, Redis, AWS EventBridge**, et d’autres solutions.
+* Séparation claire entre **la logique métier** et **le moteur de tâches**.
+
+#### **Persistance des tâches**
+
+* Intégration avec **IMemoryAdapter** pour **stocker les tâches planifiées** même après un redémarrage.
+* Permet une **synchronisation avec des bases de données** (**Redis, Meilisearch, SQLite, etc.**).
+
+#### **Gestion avancée du cycle de vie**
+
+* **Annulation, exécution immédiate, reprogrammation dynamique**.
+* Suivi des exécutions via des **callbacks événementiels**.
+
+***
+
+### **Cas d’usage**
+
+L’interface **IAgenda** est conçue pour gérer **la planification automatique des tâches**, avec des cas d’usage variés :
+
+#### **Tâches périodiques et planification automatique**
+
+* Exécution de **mises à jour programmées** toutes les nuits.
+* **Relances automatiques** en cas d’échec.
+
+#### **Orchestration de workflows distribués**
+
+* Utilisation d’un **adaptateur Redis** pour **synchroniser plusieurs agents**.
+* Planification de tâches sur **AWS EventBridge** pour **déclencher des workflows serverless**.
+
+#### **Persistance et reprise après redémarrage**
+
+* **Sauvegarde des tâches planifiées** dans **Meilisearch ou Redis**.
+* Reprise automatique après un **redémarrage du système**.
+