@ai.ntellect/core 0.6.20 → 0.6.21

package/README.md

@@ -1,192 +1,155 @@
-# **@ai.ntellect/core Documentation**
+# @ai.ntellect/core
 
-## **1. Introduction**
+@ai.ntellect/core is a modular and event-driven framework designed to orchestrate and execute intelligent workflows using execution graphs. It enables automation of complex tasks, seamless integration with external services, and the creation of AI-driven agents in a flexible and scalable way.
 
-The **`@ai.ntellect/core`** framework is a powerful tool designed to **model, execute, and manage dynamic interaction flows** using **graph structures**. Unlike traditional **Directed Acyclic Graphs (DAGs)**, this framework supports cycles, enabling nodes to be executed multiple times and allowing for loop-based workflows.
+## Key features
 
-### **Key Features**
+- **GraphFlow** – A graph-based execution engine for automating business processes.
+- **Event-Driven** – Nodes can react to real-time events and trigger actions dynamically.
+- **Modular** – Plug-and-play modules and adapters for memory, scheduling, and external APIs.
+- **Extensible** – Custom nodes, adapters, and interactions with third-party services.
+- **Scalable** – Manage multiple graphs in parallel with GraphController.
 
-- Dynamic workflow execution
-- Cyclic and acyclic graph support
-- Strong typing with Zod validation
-- Event-driven architecture
-- Built-in error handling and retries
-- Conditional execution paths
-- Parameter validation
-- State management
+## Installation
 
-### **Common Use Cases**
+### Prerequisites
 
-- **AI Agents**: Building conversational AI systems that can maintain context and make decisions
-- **Transaction Processing**: Managing complex financial workflows with validation chains
-- **Task Orchestration**: Coordinating multiple dependent operations
-- **Decision Trees**: Implementing complex business logic with multiple branches
-- **State Machines**: Managing application state transitions
-- **Event Processing**: Handling and responding to system events
+- Node.js (LTS version recommended)
+- TypeScript
+- Zod (for data validation)
 
-## **2. Core Concepts**
+Verify your installation:
 
-### **2.1 Graph Theory Foundation**
-
-A directed graph in our framework is defined as **G = (V, E)** where:
+```sh
+node -v
+npm -v
+```
 
-- **V**: Set of nodes (vertices)
-- **E**: Set of directed edges
+If Node.js is not installed, download it from [nodejs.org](https://nodejs.org/).
 
-Each node represents an executable action, and edges represent conditional transitions between actions.
+### Installing the framework
 
-#### Example Graph Structure:
+Create a new Node.js project:
 
+```sh
+mkdir ai-ntellect-demo
+cd ai-ntellect-demo
+npm init -y
 ```
-(ValidateInput) → (ProcessData) → (SaveResult)
-       ↓                              ↑
-    (RetryInput) ──────────────────────
-```
-
-### **2.2 Node Types**
 
-#### **Basic Node**
+Install TypeScript and Node.js types:
 
-```typescript
-const basicNode: Node<ContextType> = {
-  name: "processData",
-  execute: async (context) => {
-    // Process data
-  },
-  next: ["saveResult"],
-};
+```sh
+npm install --save-dev typescript @types/node
+npx tsc --init
 ```
 
-#### **Conditional Node**
-
-```typescript
-const conditionalNode: Node<ContextType> = {
-  name: "validateInput",
-  condition: (context) => context.isValid,
-  execute: async (context) => {
-    // Validation logic
-  },
-  next: ["processData"],
-};
-```
+Install @ai.ntellect/core and its dependencies:
 
-## **3. Advanced Features**
+```sh
+npm install @ai.ntellect/core zod
+```
 
-### **3.1 Event-Driven Execution**
+## Verifying the Installation
 
-Nodes can respond to system events:
+Create a new file `index.ts`:
 
-```typescript
-const eventNode: Node<ContextType> = {
-  name: "handleUserInput",
-  events: ["userSubmitted"],
-  execute: async (context) => {
-    // Handle user input
-  },
-};
+```sh
+touch index.ts
 ```
 
-### **3.2 Retry Mechanisms**
-
-Built-in retry support for handling transient failures:
-
-```typescript
-const retryableNode: Node<ContextType> = {
-  name: "apiCall",
-  retry: {
-    maxAttempts: 3,
-    delay: 1000, // ms
-  },
-  execute: async (context) => {
-    // API call logic
-  },
-};
-```
+Add the following code to test a simple graph execution:
 
-## **4. Real-World Examples**
+```ts
+import { GraphFlow } from "@ai.ntellect/core";
+import { z } from "zod";
 
-### **4.1 AI Agent Workflow**
-
-```typescript
-const aiAgentGraph = new Graph<AIContextType>("AIAgent", {
-  nodes: [
-    {
-      name: "analyzeInput",
-      execute: async (context) => {
-        context.intent = await analyzeUserIntent(context.input);
-      },
-      next: ["selectAction"],
-    },
-    {
-      name: "selectAction",
-      execute: async (context) => {
-        context.selectedAction = determineNextAction(context.intent);
-      },
-      next: ["validateResponse"],
-    },
-    {
-      name: "generateResponse",
-      execute: async (context) => {
-        context.response = await generateAIResponse(context);
-      },
-      next: ["validateResponse"],
-    },
-  ],
+const ContextSchema = z.object({
+  message: z.string(),
 });
-```
 
-### **4.2 Transaction Processing**
+type ContextSchema = typeof ContextSchema;
 
-```typescript
-const transactionGraph = new Graph<TransactionContext>("TransactionProcessor", {
+const myGraph = new GraphFlow<ContextSchema>("TestGraph", {
+  name: "TestGraph",
+  context: { message: "Installation successful!" },
+  schema: ContextSchema,
   nodes: [
     {
-      name: "validateFunds",
+      name: "printMessage",
       execute: async (context) => {
-        context.hasSufficientFunds = await checkBalance(context.amount);
+        console.log(context.message);
       },
-      next: ["processPayment"],
-    },
-    {
-      name: "processPayment",
-      retry: {
-        maxAttempts: 3,
-        delay: 1000,
-      },
-      condition: (context) => context.hasSufficientFunds,
-      execute: async (context) => {
-        await processPayment(context.transactionData);
-      },
-      next: ["notifyUser"],
+      next: [],
     },
   ],
 });
+
+(async () => {
+  await myGraph.execute("printMessage");
+})();
 ```
 
-## **5. Event Listeners**
+Run the test:
 
-```typescript
-graph.on("nodeStarted", ({ name, context }) => {
-  console.log(`Node ${name} started with context:`, context);
-});
+```sh
+npx ts-node index.ts
+```
 
-graph.on("nodeCompleted", ({ name, context }) => {
-  console.log(`Node ${name} completed with context:`, context);
-});
+Expected output:
 
-graph.on("nodeError", ({ name, error }) => {
-  console.error(`Error in node ${name}:`, error);
-});
 ```
+Installation successful!
+```
+
+## Core concepts
+
+### GraphFlow
+
+GraphFlow is the core execution engine that automates workflows through graph-based logic. Each node in the graph can:
+
+- Execute a specific action.
+- Wait for an event before proceeding.
+- Depend on conditional logic.
+- Modify a shared execution context.
+
+### GraphController
+
+GraphController orchestrates multiple GraphFlows, enabling:
+
+- Sequential or parallel execution of multiple graphs.
+- Inter-graph communication for complex workflows.
+- Advanced event-based automation.
+
+### Modules and Adapters
+
+The framework provides modular extensions:
+
+- **Memory Module** – Stores and retrieves contextual information.
+- **Scheduler (Agenda)** – Manages task scheduling and timed executions.
+- **Adapters** – Integrate with databases, APIs, and external services.
+
+## Tutorials
+
+Step-by-step guides are available for:
+
+- Creating a simple graph
+- Adding conditions and handling errors
+- Waiting for events and executing multiple graphs
+- Building an AI-powered agent with @ai.ntellect/core
+
+Check out the complete documentation at [GitBook](https://ai-ntellect.gitbook.io/core).
+
+## Contributing
 
-## **6. Future Developments**
+Contributions are welcome. To suggest an improvement or report an issue:
 
-Planned features include:
+- Join our [Discord community](https://discord.gg/kEc5gWXJ)
+- Explore the [GitBook documentation](https://ai-ntellect.gitbook.io/core)
+- Open an issue on GitHub
 
-- Advanced memory management for AI agents
-- Graph composition and nesting
-- Real-time monitoring dashboard
-- Performance analytics
-- Distributed execution support
+## Useful links
 
-For more information and updates, visit the official documentation or join our community discussions.
+- Documentation: [GitBook](https://ai-ntellect.gitbook.io/core)
+- Community: [Discord](https://discord.gg/kEc5gWXJ)
+- GitHub Repository: [@ai.ntellect/core](https://github.com/ai-ntellect/core)

package/dist/graph/controller.js

@@ -23,14 +23,14 @@ class GraphController {
      * @returns Map containing results of each graph execution, keyed by graph name and index
      * @template T - Zod schema type for graph context validation
      */
-    static executeSequential(graphs, startNodes, inputContexts) {
+    static executeSequential(graphs, startNodes, inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const results = new Map();
             for (let i = 0; i < graphs.length; i++) {
-                const result = yield graphs[i].execute(startNodes[i], inputContexts === null || inputContexts === void 0 ? void 0 : inputContexts[i]);
+                const result = yield graphs[i].execute(startNodes[i], inputs[i]);
                 results.set(`${graphs[i].name}-${i}`, result);
             }
-            return results;
+            return Array.from(results.values());
         });
     }
     /**
@@ -43,32 +43,29 @@ class GraphController {
      * @returns Map containing results of each graph execution, keyed by graph name
      * @template T - Zod schema type for graph context validation
      */
-    static executeParallel(graphs, startNodes, inputContexts, inputs, concurrencyLimit) {
+    static executeParallel(graphs, startNodes, concurrency, inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const results = new Map();
-            if (inputContexts) {
-                inputContexts = inputContexts.map((ctx) => ctx || {});
-            }
             if (inputs) {
                 inputs = inputs.map((input) => input || {});
             }
-            if (concurrencyLimit) {
-                for (let i = 0; i < graphs.length; i += concurrencyLimit) {
+            if (concurrency) {
+                for (let i = 0; i < graphs.length; i += concurrency) {
                     const batchResults = yield Promise.all(graphs
-                        .slice(i, i + concurrencyLimit)
-                        .map((graph, index) => graph.execute(startNodes[i + index], (inputContexts === null || inputContexts === void 0 ? void 0 : inputContexts[i + index]) || {}, inputs === null || inputs === void 0 ? void 0 : inputs[i + index])));
+                        .slice(i, i + concurrency)
+                        .map((graph, index) => graph.execute(startNodes[i + index], inputs === null || inputs === void 0 ? void 0 : inputs[i + index])));
                     batchResults.forEach((result, index) => {
                         results.set(`${graphs[i + index].name}`, result);
                     });
                 }
             }
             else {
-                const allResults = yield Promise.all(graphs.map((graph, index) => graph.execute(startNodes[index], (inputContexts === null || inputContexts === void 0 ? void 0 : inputContexts[index]) || {}, (inputs === null || inputs === void 0 ? void 0 : inputs[index]) || {})));
+                const allResults = yield Promise.all(graphs.map((graph, index) => graph.execute(startNodes[index], (inputs === null || inputs === void 0 ? void 0 : inputs[index]) || {})));
                 allResults.forEach((result, index) => {
                     results.set(`${graphs[index].name}`, result);
                 });
             }
-            return results;
+            return Array.from(results.values());
         });
     }
 }