@ai.ntellect/core 0.8.3 → 1.1.0

package/docs/core/architecture.md

@@ -0,0 +1,87 @@
+# System Architecture
+
+`@ai.ntellect/core` is designed as a layered system that separates **Intent**, **Routing**, and **Execution**. This architecture ensures that as your AI agent becomes more complex, it remains maintainable and verifiable.
+
+---
+
+## 📐 The Three-Layer Model
+
+### Layer 1: The Intent Layer (Probabilistic)
+This is the only place where "uncertainty" is allowed. We use an LLM to classify user input.
+- **Component**: `IntentClassifier`
+- **Responsibility**: Map `String` $\rightarrow$ `IntentID`.
+- **Guardrail**: Confidence thresholds. If the LLM is unsure, the system triggers a clarification request rather than guessing.
+
+### Layer 2: The Routing Layer (Deterministic)
+Once the intent is known, the system enters the **CortexFlow** layer. Routing is handled by a **Petri Net**.
+- **Component**: `CortexFlowOrchestrator`
+- **Responsibility**: Map `IntentID` $\rightarrow$ `WorkflowPath`.
+- **Guardrail**: Formal Verification. Because Petri Nets are mathematical objects, we use incidence matrices to detect deadlocks and bounded states at build-time.
+
+### Layer 3: The Execution Layer (Typed)
+The final layer is the **GraphFlow** engine, which executes the specific steps of the chosen path.
+- **Component**: `GraphFlow` / `GraphNode`
+- **Responsibility**: Execute business logic and update state.
+- **Guardrail**: Zod Validation. Every state transition is validated against a schema to ensure data integrity.
+
+---
+
+## 🔄 Data Flow & State Management
+
+### The Shared Context
+Every workflow instance has a **Context**. This is a single source of truth that is passed from node to node.
+- **Immutable-ish**: Nodes modify the context, but these modifications are tracked.
+- **Validated**: The context is validated against the `GraphFlow` schema at every node transition.
+
+### Checkpointing & Persistence
+To support long-running workflows (e.g., waiting for an event for 3 days), the architecture uses **Checkpoint Adapters**.
+- After every node execution, the current context and the "marking" (current position in the Petri Net) are snapshotted.
+- This allows the system to be completely stateless; a workflow can be resumed on a different server just by loading its `checkpointId` from Redis or PostgreSQL.
+
+---
+
+## 🧩 Modularity & Adapters
+
+The framework follows the **Dependency Inversion Principle**. Core logic does not depend on specific technologies.
+
+### Pluggable Modules
+We provide interfaces for common agent needs:
+- `IMemoryAdapter`: For long-term memory (InMemory $\rightarrow$ Redis $\rightarrow$ Meilisearch).
+- `ICheckpointAdapter`: For state persistence (InMemory $\rightarrow$ Postgres).
+- `IEventEmitter`: For event handling (Node.js EventEmitter $\rightarrow$ RabbitMQ $\rightarrow$ Kafka).
+
+### The GraphController
+For complex systems, a single graph isn't enough. The `GraphController` allows you to treat `GraphFlows` as building blocks, orchestrating them in parallel or sequence to build "Super-Graphs."
+
+---
+
+---
+
+## 📁 Source Code Structure (Bounded Contexts)
+
+The framework source is organized into **Bounded Contexts** that mirror the three-layer model:
+
+```
+execution/     → Layer 3: GraphFlow engine (typed nodes, events, planner, compiler)
+routing/       → Layer 2: PetriNet, CortexFlowOrchestrator, IntentClassifier
+agent/         → Cognitive loop: Agent, GenericExecutor, handlers, tools
+persistence/   → Barrel: Memory + checkpoint adapters
+pipeline/      → AgentPipeline (trigger → stages → gate)
+modules/       → Plugins: agenda, cli, embedding, memory, nlp
+interfaces/    → Contract interfaces
+types/         → Zod schemas
+```
+
+This structure ensures that each concern (routing, execution, agent loop) lives in its own directory with clear boundaries and no circular dependencies.
+
+---
+
+## 🚀 Summary of the Architectural Edge
+
+| Feature | Traditional AI Frameworks | @ai.ntellect/core |
+| :--- | :--- | :--- |
+| **Control Flow** | LLM-driven (Probabilistic) | Petri Net-driven (Deterministic) |
+| **State** | Loose / Prompt-based | Strongly Typed (Zod) |
+| **Verification** | Trial and Error | Mathematical Proof (Deadlock detection) |
+| **Persistence** | Session-based | Checkpoint-based (Time-travel) |
+| **Latency** | Multiple LLM calls for routing | Single LLM call for classification |

package/docs/core/benchmark.md

@@ -0,0 +1,59 @@
+# Benchmark: CortexFlow vs. LangGraph
+
+To validate our thesis that **deterministic routing is superior to probabilistic routing**, we conducted a rigorous benchmark comparing `CortexFlow` against a standard `LangGraph` implementation.
+
+## 🧪 The Test Scenario
+
+**The Task**: An AI Agent must process an inbox of 5 emails. It must:
+1. Fetch emails $\rightarrow$ 2. Classify urgency $\rightarrow$ 3. Draft responses for urgent ones $\rightarrow$ 4. Archive non-urgent ones.
+
+This is a classic "routing" task where an agent must decide between different paths based on input.
+
+---
+
+## 📊 The Results
+
+### Test 1: Local Execution (Ollama — llama3:latest)
+*Observation: Local LLM calls have high latency (~2s per call), making the number of calls the primary bottleneck.*
+
+| Metric | CortexFlow | LangGraph (Naive) | LangGraph (Optimized) |
+| :--- | :--- | :--- | :--- |
+| **LLM Calls** | **1** | 7 | 2 |
+| **Total Time** | **13.4s** | 3.7s | 4.2s |
+| **Reliability** | 100% (Deterministic) | ~85% (Occasional Drift) | ~95% (Manual Batching) |
+
+**Analysis**: CortexFlow is slower in local mode because it performs **Formal Verification** (deadlock/boundedness checks) at the start. However, it reduces LLM calls by **86%**.
+
+### Test 2: Cloud Execution (Groq API — llama-3.1-8b-instant)
+*Observation: Cloud LLMs have extremely low latency, shifting the bottleneck to the orchestration overhead.*
+
+| Metric | CortexFlow | LangGraph (Naive) | LangGraph (Optimized) |
+| :--- | :--- | :--- | :--- |
+| **LLM Calls** | **1** | 7 | 2 |
+| **Total Time** | **1,650 ms** | 2,192 ms | 1,668 ms |
+| **Performance** | **1.33x Faster** | Baseline | 1.31x Faster |
+
+**Analysis**: In a production environment (low-latency LLM), **CortexFlow is the fastest**. By eliminating the "routing loops," it removes multiple network round-trips.
+
+---
+
+## 📉 The "LLM Call" Tax
+
+The biggest find from this benchmark is the **LLM Call Tax**.
+In traditional frameworks, every decision is a call:
+`User` $\rightarrow$ `Call 1 (Route)` $\rightarrow$ `Call 2 (Validate)` $\rightarrow$ `Call 3 (Act)` $\rightarrow$ `Call 4 (Summarize)`.
+
+In CortexFlow, we pay the tax **once**:
+`User` $\rightarrow$ `Call 1 (Classify Intent)` $\rightarrow$ `System (Deterministic Route)` $\rightarrow$ `Done`.
+
+---
+
+## 🏆 Final Verdict: Why Choose CortexFlow?
+
+The benchmark proves that the gain is not just about milliseconds—it's about **Reliability**.
+
+1. **Zero Routing Hallucinations**: Because the routing is in a Petri Net, the agent *cannot* decide to go to a node that doesn't exist or skip a mandatory step.
+2. **Constant Complexity**: Whether the conversation is 2 turns or 200 turns, the routing cost remains **1 LLM call**.
+3. **Formal Guarantees**: You get a mathematical proof that your agent will never deadlock, regardless of what the LLM outputs.
+
+**LangGraph is a great tool for autonomous exploration. CortexFlow is the tool for production systems.**

package/docs/core/checkpoint.md

@@ -0,0 +1,72 @@
+# Resilience & Checkpoints
+
+In production, workflows fail. Servers crash, APIs timeout, and humans take days to approve requests. The **Checkpoint System** is what makes `@ai.ntellect/core` production-grade.
+
+## 📌 What is a Checkpoint?
+
+A checkpoint is a **serialized snapshot** of a workflow's entire state at a specific point in time. It includes:
+1. The current **Context** (the data).
+2. The current **Node/Position** (where we are).
+3. The **Run ID** (which execution this belongs to).
+4. **Metadata** (timestamps, error states, approval status).
+
+---
+
+## 🛠️ Core Functionalities
+
+### 1. Automatic State Persistence
+By using `executeWithCheckpoint`, the engine automatically saves the state after every single node execution. If the process crashes, you don't lose progress; you simply resume from the last successful node.
+
+### 2. Breakpoints (Human-in-the-Loop)
+Breakpoints allow you to intentionally pause a workflow *before* a critical node executes.
+```typescript
+await workflow.executeWithCheckpoint("start", adapter, {
+  breakpoints: ["execute_payment"], 
+});
+```
+The workflow will stop exactly before `execute_payment`. It stays in a `awaiting_approval` state until an external command calls `resumeFromCheckpoint`.
+
+### 3. Time-Travel Debugging
+This is the most powerful tool for developers. You can resume a workflow from *any* previous checkpoint in its history, and you can even **modify the state** before resuming.
+
+```typescript
+// "What would have happened if the user had entered 'USD' instead of 'EUR'?"
+await workflow.resumeFromCheckpoint(cpId, adapter, {
+  contextModifications: { currency: "USD" },
+});
+```
+
+---
+
+## 🔌 Adapters
+
+You can choose where your checkpoints are stored based on your needs:
+
+| Adapter | Best For | Persistence |
+| :--- | :--- | :--- |
+| `InMemoryCheckpointAdapter` | Local dev, unit tests | Volatile (Lost on restart) |
+| `RedisPetriCheckpointAdapter` | High-performance production | Persistent / Distributed |
+| `PostgresPetriCheckpointAdapter` | Audit-heavy, relational data | Persistent / ACID |
+
+---
+
+## 🧠 Petri Net Checkpoints
+
+For **CortexFlow** workflows, checkpoints are even more critical. We save the **Petri Net Marking** (the distribution of tokens across places).
+
+This means you can:
+- Pause a complex orchestration.
+- Restore the exact state of the Petri Net.
+- See exactly which transitions were enabled at the moment of the pause.
+
+---
+
+## ⚠️ Error Handling & Recovery
+
+When a node fails, the system creates an **Error Checkpoint**.
+Instead of the whole system crashing, the workflow enters a `failed` state. A developer or an automated process can then:
+1. Analyze the error in the checkpoint metadata.
+2. Fix the underlying issue (or modify the context).
+3. Resume the workflow from the failed node.
+
+**This eliminates the need to restart long-running workflows from scratch.**

package/docs/core/documentation.md

@@ -0,0 +1,55 @@
+# Living Documentation: Visualizing Your Agents
+
+One of the biggest challenges in AI orchestration is the "Black Box" problem: you don't know why an agent took a certain path. `@ai.ntellect/core` solves this by treating **documentation as code**.
+
+CortexFlow can automatically generate visual and textual documentation directly from your Petri Net definitions.
+
+---
+
+## 🛠️ Generation Tools
+
+### 1. CLI Generation
+You can generate documentation for any JSON-defined Petri Net using the provided script:
+
+```bash
+npx ts-node scripts/generate-petri-docs.ts <petri-net.json> [output-dir]
+```
+
+**What you get:**
+- **Markdown (`.md`)**: A human-readable explanation of all places, transitions, and the intended flow.
+- **Mermaid Diagram (`.mmd`)**: A visual graph that can be rendered in GitHub, Notion, or Obsidian.
+- **Interactive HTML (`.html`)**: A standalone page with an embedded render of the workflow.
+
+### 2. Programmatic Generation
+You can integrate documentation generation into your CI/CD pipeline or your own admin dashboard:
+
+```typescript
+import { PetriDocumentationGenerator } from "@ai.ntellect/core/routing/documentation-generator";
+
+const generator = new PetriDocumentationGenerator();
+await generator.generateForPetri(net, {
+  outputDir: "./docs/petri",
+  format: "all",
+});
+```
+
+---
+
+## 🔍 Session-Based Documentation (The "Audit Trail")
+
+Unlike static documentation, **Session Documentation** captures the *actual* execution of a specific request.
+
+When you generate documentation for a session:
+1. **State Highlighting**: The resulting diagram highlights exactly where the tokens were located at the time of the snapshot.
+2. **Transition History**: The Markdown report lists every transition that was fired, in order, with its associated `traceId`.
+3. **Enabled Analysis**: The report shows which transitions were "enabled" (ready to fire) but were not chosen.
+
+**This turns your documentation into a forensic tool for debugging production agents.**
+
+---
+
+## 📈 Why "Living" Docs?
+
+- **Zero Drift**: Since the docs are generated from the `PetriNet` object, they can never be out of sync with the code.
+- **Accessibility**: Non-technical stakeholders (Product Managers, Compliance Officers) can review the Mermaid diagrams to verify the business logic.
+- **Fast Onboarding**: New developers can visualize the entire agent's decision tree without reading thousands of lines of code.

package/docs/core/graphcontroller.md

@@ -0,0 +1,63 @@
+# GraphController: Multi-Graph Orchestration
+
+While a `GraphFlow` is powerful for a single workflow, real-world applications often require the coordination of multiple independent workflows. The `GraphController` is the orchestrator that manages these relationships.
+
+## 🎯 Purpose
+
+The `GraphController` allows you to treat individual `GraphFlows` as modular components. Instead of building one giant, monolithic graph, you can build small, testable graphs and compose them into complex pipelines.
+
+---
+
+## 🚀 Execution Modes
+
+### 1. Sequential Execution
+Use `executeSequential` when Workflow B depends on the successful completion of Workflow A.
+
+```typescript
+const controller = new GraphController();
+
+await controller.executeSequential([
+  { graph: userValidationGraph, startNode: "start" },
+  { graph: paymentProcessingGraph, startNode: "init" },
+  { graph: notificationGraph, startNode: "send" },
+]);
+```
+If any graph in the sequence fails, the chain stops, and the error is propagated, preventing inconsistent states.
+
+### 2. Parallel Execution
+Use `executeParallel` to trigger multiple independent workflows simultaneously, reducing overall latency.
+
+```typescript
+const results = await controller.executeParallel([
+  { graph: fetchStockGraph, startNode: "start" },
+  { graph: fetchPriceGraph, startNode: "start" },
+  { graph: checkComplianceGraph, startNode: "start" },
+]);
+```
+The `GraphController` manages the `Promise.all` logic internally and returns an array of results once all graphs have completed.
+
+---
+
+## 🛠️ Advanced Patterns
+
+### The "Super-Graph" Pattern
+You can use a `GraphController` inside a `GraphNode` of another `GraphFlow`. This allows you to create hierarchical workflows:
+- **Parent Graph**: Handles high-level business logic.
+- **Child Graphs (via Controller)**: Handle specific technical implementations.
+
+### Cross-Graph Event Communication
+Graphs managed by a controller can communicate via the event system.
+1. `Graph A` emits an event `data.ready`.
+2. `Graph B` has a node waiting for `data.ready`.
+3. `Graph B` wakes up and processes the data produced by `Graph A`.
+
+---
+
+## ⚖️ When to use GraphController vs. Parallel Nodes?
+
+| Feature | Parallel Nodes (within GraphFlow) | GraphController (across GraphFlows) |
+| :--- | :--- | :--- |
+| **Scope** | Intra-graph (Internal) | Inter-graph (External) |
+| **State** | Shares the same `Context` | Each graph has its own `Context` |
+| **Coupling** | Tightly coupled | Loosely coupled (Modular) |
+| **Use Case** | Splitting a single task into sub-tasks | Orchestrating different business modules |

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,
+  // ...
+});
+```