@ai.ntellect/core 1.0.0 → 1.1.1

package/docs/README.md

@@ -0,0 +1,57 @@
+# Documentation: @ai.ntellect/core
+
+Welcome to the official documentation for **@ai.ntellect/core**, the framework for building production-grade LLM agents that don't drift.
+
+## The Core Thesis
+**LLMs are exceptional at generating text, but they are unreliable at controlling systems.**
+
+Most AI frameworks treat the LLM as the "brain" that makes every routing decision. As your agent grows in complexity, this leads to:
+- **Routing Hallucinations**: The LLM forgets the rules and calls tools in the wrong order.
+- **Context Bloat**: The prompt grows too large as it tries to explain every possible path.
+- **Unpredictability**: The same input can lead to different execution paths.
+
+**@ai.ntellect/core solves this by splitting the brain:**
+1. **The LLM is the Classifier**: It identifies *intent* once.
+2. **The System is the Controller**: A verified Petri Net handles the *routing* deterministically.
+3. **GraphFlow is the Executor**: Typed graphs handle the *execution* without further LLM interference.
+
+---
+
+## 🧭 Navigation Guide
+
+### 🚀 Getting Started
+- [Quick Start Guide](./tutoriels/pour-commencer.md) — From `npm install` to your first workflow in 5 minutes.
+- [The Philosophy](./philosophie.md) — Understand why deterministic control is the only way to scale AI agents.
+- [Key Concepts](./concepts-cles.md) — GraphFlow, CortexFlow, and State Management.
+
+### 🛠️ The Engine
+- [GraphFlow Deep Dive](./core/graphflow.md) — Nodes, Parallelism, and the Send API.
+- [Event-Driven Architectures](./core/les-evenements.md) — Building reactive systems that wait for the world.
+- [Resilience & Checkpoints](./core/checkpoint.md) — Time-travel debugging and human-in-the-loop.
+- [Technical Architecture](./core/architecture.md) — The blueprint of the engine.
+
+### 🧠 AI Orchestration (CortexFlow)
+- [Deterministic Routing](./core/graphflow.md) — How intent classification works.
+- [Formal Verification](./core/architecture.md) — Deadlock detection and reachability analysis.
+- [Hybrid Fallback](./core/architecture.md) — Balancing determinism with conversational flexibility.
+
+### 🧩 Modules & Tooling
+- [Memory Systems](./modules/memoire/) — Pluggable persistence (Redis, Meilisearch).
+- [Agenda & Scheduling](./modules/agenda/) — Cron-based automation.
+- [Interactive CLI](./cli/) — Debugging and running agents from your terminal.
+
+### 📈 Real-World Application
+- [Design Patterns](./cas-dusages.md) — How to model Approval Flows, RAG, and ETL pipelines.
+- [Benchmarks](./core/benchmark.md) — CortexFlow vs LangGraph: Performance and Reliability.
+
+---
+
+## 🛠️ Quick Reference
+
+| If you want to... | Go to... |
+| :--- | :--- |
+| Build a simple sequence of tasks | [GraphFlow](./core/graphflow.md) |
+| Create an agent that handles intents | [CortexFlow](./core/graphflow.md) |
+| Make a workflow pause for a human | [Checkpoints](./core/checkpoint.md) |
+| Trigger a workflow via Webhook | [Events](./core/les-evenements.md) |
+| Run an agent in your terminal | [CLI](./cli/) |

package/docs/SUMMARY.md

@@ -0,0 +1,34 @@
+# Table of Contents
+
+* [Welcome](./README.md)
+
+## 🚀 Getting Started
+* [Quick Start Guide](./tutoriels/pour-commencer.md)
+* [The Philosophy](./philosophie.md)
+* [Key Concepts](./concepts-cles.md)
+
+## 🛠️ The Engine (Core)
+* [GraphFlow Deep Dive](./core/graphflow.md)
+* [Event-Driven Architectures](./core/les-evenements.md)
+* [Resilience & Checkpoints](./core/checkpoint.md)
+* [Multi-Graph Orchestration](./core/graphcontroller.md)
+* [Technical Architecture](./core/architecture.md)
+* [Visualizing Your Agents](./core/documentation.md)
+* [Performance Benchmarks](./core/benchmark.md)
+
+## 🧩 Modules & Tooling
+* [Modular Extensions](./modules/introduction.md)
+* [Memory Systems](./modules/memoire/)
+* [Agenda & Scheduling](./modules/agenda/)
+* [Interactive CLI](./cli/README.md)
+
+## 📖 Tutorials
+* [Building Your First Workflow](./tutoriels/creer-un-graphe-simple.md)
+* [Building Tool-Using Agents](./tutoriels/creer-un-agent.md)
+* [Implementing Human-in-the-Loop](./tutoriels/checkpoint-usage.md)
+* [Advanced Branching](./tutoriels/branching.md)
+* [Handling Errors & Retries](./tutoriels/retry.md)
+
+## 🔗 Links
+* [NPM Package](https://www.npmjs.com/package/@ai.ntellect/core)
+* [GitHub Repository](https://github.com/ai-ntellect/core)

package/docs/cas-dusages.md

@@ -0,0 +1,69 @@
+# Use Cases & Design Patterns
+
+`@ai.ntellect/core` is designed for scenarios where **failure is not an option**. While simple chatbots can use raw LLM loops, production systems require structured, predictable execution.
+
+Here are the primary patterns you can build with this framework.
+
+---
+
+## 1. Task-Based Assistants (The "Router" Pattern)
+Perfect for applications that provide a suite of specific services.
+
+**The Pattern**: `Natural Language` $\rightarrow$ `Intent Classification` $\rightarrow$ `Deterministic Workflow`.
+
+- **Example**: A Banking Assistant.
+  - "What's my balance?" $\rightarrow$ `GET_BALANCE` intent $\rightarrow$ `fetchBalance` GraphFlow.
+  - "Pay my electricity bill" $\rightarrow$ `PAY_BILL` intent $\rightarrow$ `validateAccount` $\rightarrow$ `executePayment` $\rightarrow$ `notifyUser` GraphFlow.
+- **Why this wins**: The LLM cannot "hallucinate" a new payment method or skip the validation step. The path is hardcoded in the Petri Net.
+
+---
+
+## 2. Human-in-the-Loop (The "Approval" Pattern)
+Essential for high-stakes actions that require a human "sanity check."
+
+**The Pattern**: `Workflow Execution` $\rightarrow$ `Checkpoint` $\rightarrow$ `Awaiting Approval` $\rightarrow$ `Resume`.
+
+- **Example**: Enterprise Expense Approval.
+  - Employee submits a \$5,000 expense.
+  - GraphFlow processes the request and hits a **Breakpoint**.
+  - Execution pauses; state is saved to Redis.
+  - Manager receives a notification and calls `/approve`.
+  - GraphFlow resumes from the exact same state and completes the payment.
+- **Why this wins**: You don't have to write complex "polling" logic. The system natively supports pausing and resuming long-running processes.
+
+---
+
+## 3. Event-Driven Orchestration (The "Reactive" Pattern)
+For systems that must react to the real world (Webhooks, IoT, Blockchain).
+
+**The Pattern**: `Event Trigger` $\rightarrow$ `Context Correlation` $\rightarrow$ `Workflow Trigger`.
+
+- **Example**: Crypto Whale Alert & Trade.
+  - **Event**: A large transfer is detected on-chain.
+  - **Action**: Trigger a GraphFlow that analyzes the wallet history, calculates the impact, and executes a hedge trade.
+- **Why this wins**: By using **Event-Driven Nodes**, your workflows can "sleep" for days and wake up the instant a specific external condition is met.
+
+---
+
+## 4. Financial & Critical Workflows (The "Zero-Failure" Pattern)
+For systems where a single error can result in financial loss or compliance breach.
+
+**The Pattern**: `Formal Verification` $\rightarrow$ `Zod Validation` $\rightarrow$ `Atomic Execution`.
+
+- **Example**: Automated Compliance Reporting.
+  - Collect data from 5 different APIs.
+  - Validate each piece of data against a strict Zod schema.
+  - Use a **Fork-Join** model to process reports in parallel.
+  - Merge results using a custom **Reducer** to ensure no data is lost.
+- **Why this wins**: The use of Petri Nets allows you to prove that the workflow will never enter an invalid state (Deadlock Detection), and Zod ensures that no corrupted data ever reaches your core logic.
+
+---
+
+## 🚀 Summary: When to use what?
+
+| If you need... | Use this pattern | Key Primitive |
+| :--- | :--- | :--- |
+| Predictable routing | **Task-Based** | `CortexFlow` (Intent $\rightarrow$ Net) |
+| Safety / Oversight | **Approval** | `Checkpoints` + `Breakpoints` |
+| External triggers | **Reactive** | `Event-Driven Nodes` |
+| Mathematical certainty | **Zero-Failure** | `Petri Net Verification` + `Zod` |

package/docs/cli/README.md

@@ -0,0 +1,65 @@
+# Interactive CLI: Debugging & Control
+
+The `@ai.ntellect/core` CLI is not just a runner—it is a **control center** for your agents. It allows you to interact with agents in real-time, inspect their internal state, and manually steer execution using checkpoints.
+
+## 🚀 Getting Started
+
+Launch the REPL by specifying your LLM provider and model:
+
+```sh
+pnpm cli -p groq -m llama-3.1-8b-instant       # High-speed Groq
+pnpm cli -p openai -m gpt-4o-mini              # Versatile OpenAI
+pnpm cli -p ollama -m llama3                # Local Privacy (Ollama)
+```
+
+### Configuration
+The CLI automatically loads your `.env` file for API keys (`GROQ_API_KEY`, `OPENAI_API_KEY`, etc.), so you don't have to pass them manually.
+
+---
+
+## ⌨️ Control Commands (Slash Commands)
+
+While in the interactive session, use these commands to manage the agent's lifecycle:
+
+### 🔍 State Inspection
+- `/status` — View the current execution state and active node.
+- `/history` — Print the full conversation and tool execution history.
+- `/list` — List all available checkpoints for the current session.
+
+### 🕹️ Execution Control
+- `/resume [cpId]` — **Time Travel**: Jump back to a specific checkpoint and continue from there.
+- `/approve` — Signal a "Yes" to a pending human-in-the-loop breakpoint.
+- `/reject` — Signal a "No" to a pending human-in-the-loop breakpoint.
+- `/modify k=v` — **State Injection**: Change a variable in the context *before* resuming execution.
+
+### 🧹 Session Management
+- `/clear` — Reset the current conversation context.
+- `/help` — Show all available commands.
+- `/exit` — Gracefully terminate the session.
+
+---
+
+## 🛑 Human-in-the-Loop (HITL)
+
+The CLI is designed for **safe AI deployment**. By default, the agent is configured with a breakpoint before the `think` node (the LLM call). 
+
+**The Workflow:**
+1. The agent identifies a need to call a tool.
+2. The CLI **pauses** execution.
+3. You review the proposed action.
+4. You type `/approve` to let it proceed or `/modify` to correct the parameters.
+
+This ensures that no destructive action (like a financial transfer or a file deletion) happens without explicit human consent.
+
+## 📖 Example Session
+
+```text
+> /role Financial Assistant
+> Transfer $50 to Alice
+[BREAKPOINT] Agent wants to execute: transfer_funds { amount: 50, to: "Alice" }
+> /approve
+[Executing...]
+Transaction successful. Reference: TX_9921.
+> /status
+Current Node: notify_user | Status: COMPLETED
+```

package/docs/concepts-cles.md

@@ -0,0 +1,50 @@
+# Key Concepts
+
+To understand `@ai.ntellect/core`, you need to shift your mental model from "autonomous agents" to "deterministic orchestration."
+
+## 🧠 The Classifier-Controller Split
+
+The core innovation of this framework is the separation of **Intent Classification** from **Execution Logic**.
+
+### 1. The Classifier (LLM)
+The LLM is used as a high-dimensional pattern matcher. Its only job is to map a user's natural language input to a pre-defined **Intent**.
+- **Input**: "I need to check my balance and transfer $50 to Alice."
+- **Output**: `{ intent: "TRANSFER_FUNDS", confidence: 0.98 }`
+
+By restricting the LLM to classification, we eliminate the "routing hallucinations" that occur when the LLM tries to decide the next step in a complex workflow.
+
+### 2. The Controller (Petri Net)
+Once the intent is classified, the **CortexFlow Orchestrator** takes over. It uses a verified Petri Net to determine the exact sequence of steps.
+- **Deterministic**: The same intent always triggers the same path.
+- **Verifiable**: We can mathematically prove the workflow will never deadlock.
+- **Observably**: Every transition is a discrete event that can be logged and audited.
+
+---
+
+## 🏗️ The Execution Engine: GraphFlow
+
+While the Controller decides *which* workflow to run, **GraphFlow** is the engine that actually *runs* it.
+
+### Workflow as a Typed Graph
+A `GraphFlow` is a directed graph where each node is a discrete unit of logic. Unlike simple scripts, GraphFlows are:
+- **Strongly Typed**: Every transition is validated via Zod.
+- **Stateful**: They maintain a shared context that evolves as the graph is traversed.
+- **Resilient**: Built-in retry logic and checkpointing allow workflows to survive crashes or wait for human approval.
+
+### Orchestration vs. Automation
+- **Automation**: A linear sequence of "If X then Y." It's brittle and fails when the world changes.
+- **Orchestration**: The coordination of multiple asynchronous processes, handling parallel branches, and reacting to external events. 
+
+`@ai.ntellect/core` provides **orchestration**, allowing you to build systems that are as flexible as a human operator but as reliable as a compiler.
+
+---
+
+## 🔄 The Lifecycle of a Request
+
+1. **Input**: User sends a message.
+2. **Classify**: LLM identifies the **Intent**.
+3. **Route**: The **Petri Net** finds the matching transition.
+4. **Execute**: The **GraphFlow** associated with that transition runs its nodes.
+5. **Respond**: The final state is returned to the user.
+
+**Total LLM calls for routing: 1.**

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 |