@ai.ntellect/core 0.7.8 → 1.0.0

package/README.md

@@ -1,116 +1,193 @@
-# @ai.ntellect/core
+# @ai.ntellect/workflow
 
-@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/workflow** package is a robust framework for managing and executing workflows, supporting dynamic decision-making, conditional paths, event-driven execution, and state persistence.
 
 ## Features
 
-- **GraphFlow** – 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
-- **Observable** – Complete state and event monitoring
+- **Dynamic Workflow Execution:** Manage workflows with complex branching and parallel paths.
+- **Conditional Logic:** Execute nodes based on real-time conditions.
+- **Event-Driven Execution:** Trigger actions dynamically using events.
+- **State Management:** Handle shared and persistent states.
+- **Visualization:** Generate workflow diagrams using Mermaid syntax.
 
 ## Installation
 
-### Prerequisites
+Install the package via npm:
 
-- Node.js (LTS version recommended)
-- TypeScript
-- Zod (for data validation)
+```bash
+npm install @ai.ntellect/workflow
+```
 
-Verify your installation:
+Import the `Workflow` class:
 
-```sh
-node -v
-npm -v
+```javascript
+import { Workflow } from "@ai.ntellect/workflow";
 ```
 
-### Installing the framework
+## Creating a content pipeline workflow
 
-```sh
-npm install @ai.ntellect/core zod
-```
+Here is an example of creating a workflow to manage a content pipeline:
 
-## Example
-
-```typescript
-import { GraphFlow } from "@ai.ntellect/core";
-import { z } from "zod";
-
-// Definition of the context schema
-const ContextSchema = z.object({
-  message: z.string(),
-});
-
-type ContextSchema = typeof ContextSchema;
-
-// Definition of the graph
-const myGraph = new GraphFlow<ContextSchema>("TestGraph", {
-  name: "TestGraph",
-  context: { message: "Installation success" },
-  schema: ContextSchema,
-  nodes: [
-    {
-      name: "printMessage",
-      execute: async (context) => {
-        console.log(context.message);
+```javascript
+import { Workflow } from "@ai.ntellect/workflow";
+
+const contentPipelineDefinition = {
+  name: "ContentPipeline",
+  entryNode: "fetchContent",
+  nodes: {
+    fetchContent: {
+      name: "fetchContent",
+      description: "Fetch content from external APIs",
+      execute: async (state) => {
+        console.log("Fetching content...");
+        state.content = ["Article1", "Article2"];
+        return state;
+      },
+      next: ["processContent"],
+    },
+    processContent: {
+      name: "processContent",
+      description: "Process and analyze content",
+      execute: async (state) => {
+        console.log("Processing content:", state.content);
+        state.processedContent = state.content.map((c) => c.toUpperCase());
+        return state;
+      },
+      next: ["publishContent"],
+    },
+    publishContent: {
+      name: "publishContent",
+      description: "Publish processed content",
+      execute: async (state) => {
+        console.log("Publishing content:", state.processedContent);
+        state.published = true;
+        return state;
       },
-      next: [],
     },
-  ],
-});
+  },
+};
 
-// Execution of the graph
-(async () => {
-  await myGraph.execute("printMessage");
-})();
+const workflow = new Workflow(contentPipelineDefinition);
 ```
 
-## Features
+## Executing the workflow
 
-### Event handling
+Run the content pipeline workflow with an initial state:
 
-```typescript
-// Event-driven node
-{
-  name: "waitForEvent",
-  events: ["dataReceived"],
-  execute: async (context, event) => {
-    context.data = event.payload;
-  }
-}
+```javascript
+const initialState = {};
+await workflow.execute(initialState, "fetchContent");
+```
+
+Example output:
+
+```text
+Fetching content...
+Processing content: [ 'Article1', 'Article2' ]
+Publishing content: [ 'ARTICLE1', 'ARTICLE2' ]
+```
+
+## Visualizing the workflow
+
+Generate a visual representation of the content pipeline workflow:
+
+```javascript
+workflow.visualize("Content Pipeline Workflow");
+```
+
+Output example:
 
-// Emit events
-graph.emit("dataReceived", { value: 42 });
+```mermaid
+workflow TD
+  fetchContent[Fetch Content]
+  processContent[Process Content]
+  publishContent[Publish Content]
+  fetchContent --> processContent
+  processContent --> publishContent
 ```
 
-### State observation
+## Advanced features
+
+### Event-driven execution
+
+Add event-driven nodes to the workflow:
 
-```typescript
-// Observe specific node
-graph.observe().node("myNode").subscribe(console.log);
+```javascript
+workflow.addNode(
+  {
+    name: "eventDrivenNode",
+    description: "Node triggered by a custom event",
+    execute: async (state) => {
+      console.log("Custom event processed.");
+      return state;
+    },
+  },
+  { events: ["customEvent"] }
+);
+
+workflow.emit("customEvent", { state: { exampleKey: "exampleValue" } });
+```
 
-// Observe specific properties
-graph.observe().property("counter").subscribe(console.log);
+Example output:
 
-// Observe events
-graph.observe().event("nodeCompleted").subscribe(console.log);
+```text
+Custom event processed.
 ```
 
-## Documentation
+### Parallel execution
+
+Execute multiple nodes concurrently:
 
-For complete documentation, visit our [GitBook](https://ai-ntellect.gitbook.io/core).
+```javascript
+await workflow.executeParallel(
+  { data: "Parallel Execution" },
+  ["nodeA", "nodeB"],
+  2
+);
+```
+
+### Conditional logic
 
-## Contributing
+Add conditional nodes to control the workflow path:
 
-Contributions are welcome! To suggest an improvement or report an issue:
+```javascript
+workflow.addNode(
+  {
+    name: "conditionalNode",
+    description: "Node executed conditionally",
+    execute: async (state) => {
+      console.log("Condition met, executing node...");
+      return state;
+    },
+  },
+  {
+    condition: (state) => state.content && state.content.length > 0,
+    next: ["publishContent"],
+  }
+);
+```
 
-- Join our [Discord community](https://discord.gg/kEc5gWXJ)
-- Explore the [GitBook documentation](https://ai-ntellect.gitbook.io/core)
-- Open an issue on GitHub
+### Sub-workflows
 
-## Useful links
+Embed sub-workflows for modularity:
 
-- 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)
+```javascript
+const subWorkflowDefinition = {
+  name: "SubWorkflow",
+  nodes: {
+    subNode: {
+      name: "subNode",
+      execute: async (state) => {
+        console.log("Executing sub-workflow.");
+        return state;
+      },
+    },
+  },
+};
+
+workflow.addSubWorkflow(
+  new Workflow(subWorkflowDefinition),
+  "subNode",
+  "processContent"
+);
+```