@ai.ntellect/core 0.4.0 → 0.5.0

package/README.md

@@ -4,57 +4,59 @@
 
 This framework is designed to execute complex workflows using advanced orchestration, memory management, and actionable intelligence. It integrates tools, interpreters, and memory systems to:
 
-- Contextually analyze user inputs.
+- Analyze user inputs in their context.
 - Execute predefined workflows and dynamic actions.
 - Efficiently manage short-term and long-term memory.
-- Seamlessly integrate with external APIs and tools.
+- Enable seamless integration with external APIs and tools.
 
 ---
 
-## Table of contents
+## Table of Contents
 
-1. [Architecture components](#architecture-components)
-   - [Agent runtime](#agent-runtime)
+1. [Architecture Components](#architecture-components)
+   - [Agent Runtime](#agent-runtime)
    - [Orchestrator](#orchestrator)
-   - [Queue manager](#queue-manager)
+   - [Queue Manager](#queue-manager)
    - [Interpreter](#interpreter)
-   - [Memory system](#memory-system)
-2. [Defining and executing actions](#defining-and-executing-actions)
-3. [State management and recursion](#state-management-and-recursion)
-4. [Installation and setup](#installation-and-setup)
-5. [Example usage](#example-usage)
-6. [Work in progress (WIP)](#work-in-progress)
+   - [Memory System](#memory-system)
+   - [Listeners](#listeners)
+   - [Schedulers](#schedulers)
+2. [Defining and Executing Actions](#defining-and-executing-actions)
+3. [State Management and Recursion](#state-management-and-recursion)
+4. [Installation and Configuration](#installation-and-configuration)
+5. [Usage Example](#usage-example)
+6. [Work in Progress (WIP)](#work-in-progress-wip)
 
 ---
 
-## Architecture components
+## Architecture Components
 
-### Agent runtime
+### Agent Runtime
 
-The `AgentRuntime` is the core engine that coordinates the global workflow. It connects all components and ensures tasks are executed efficiently.
+The `AgentRuntime` is the main engine coordinating the overall workflow. It connects all components and ensures tasks are executed efficiently.
 
 **Responsibilities:**
 
 - Build context for the current state using memory systems (RAG and CAG).
-- Orchestrate actions using the Queue Manager.
+- Orchestrate actions using the queue manager.
 - Leverage interpreters to analyze results and generate responses.
 
-#### Context building
+#### Context Building
 
-The `buildContext` method constructs a comprehensive context by:
+The `buildContext` method creates a complete context by:
 
 1. Adding tools and user requests.
-2. Retrieving recent actions using cache memory (CAG).
+2. Retrieving recent actions via cache memory (CAG).
 3. Fetching relevant knowledge from persistent memory (RAG).
 4. Including available interpreters for the request.
 
-#### Processing workflows
+#### Workflow Processing
 
 The `process` method:
 
-1. Generates responses based on the context using a language model.
+1. Generates responses based on context using a language model.
 2. Handles recursive workflows for action execution.
-3. Selects appropriate interpreters for result analysis.
+3. Selects appropriate interpreters to analyze results.
 
 ---
 
@@ -62,33 +64,33 @@ The `process` method:
 
 The **orchestrator** directs workflows by analyzing user inputs and planning actions. It interacts with tools, memory systems, and interpreters to ensure logical execution.
 
-**Key features:**
+**Key Features:**
 
-- Dynamic selection of actions based on context.
-- Management of memory interactions for RAG and CAG operations.
-- Multi-step workflow handling with iterative refinement.
+- Dynamic action selection based on context.
+- Memory interaction management for RAG and CAG operations.
+- Multi-step workflow management with iterative refinement.
 
 ---
 
-### Queue manager
+### Queue Manager
 
-The **queue manager** organizes and executes actions in the correct order, whether sequentially or in parallel. It acts as the central mechanism for managing workflows, ensuring that each action is properly queued, validated, and executed.
+The **queue manager** is responsible for organizing and executing actions in the correct order, whether sequential or parallel. It acts as the central mechanism for managing workflows, ensuring each action is properly queued, validated, and executed.
 
-**Responsibilities:**
+**Main Responsibilities:**
 
-1. **Queueing actions:**
+1. **Action Queueing:**
 
-   - Actions are added to a queue for execution, either individually or as a batch.
-   - Logs queued actions for debugging and traceability.
+   - Actions are added to a queue for execution, individually or in batches.
+   - Includes logging support for debugging and traceability.
 
-2. **Processing actions:**
+2. **Action Processing:**
 
-   - Executes actions in the queue while maintaining the correct order.
-   - Ensures dependencies between actions are respected.
+   - Executes actions while maintaining correct order.
+   - Respects dependencies between actions.
    - Handles errors or confirmations via callbacks.
 
-3. **Confirmation handling:**
-   - Supports confirmation prompts for critical actions.
+3. **Confirmation Management:**
+   - Supports prompts for critical actions.
    - Relies on callbacks to decide whether to proceed with specific actions.
 
 **Example:**
@@ -107,48 +109,101 @@ console.log("Results:", results);
 
 ### Interpreter
 
-The **interpreter** specializes in analyzing results and generating domain-specific insights. Each interpreter is tailored to a specific use case and uses its own character configuration.
+The **interpreter** specializes in analyzing results and generating domain-specific insights. Each interpreter is tailored for a specific use case and uses its own character configuration.
 
 **Examples:**
 
 1. **MarketInterpreter**: Analyzes financial market data.
-2. **SecurityInterpreter**: Conducts security checks.
+2. **SecurityInterpreter**: Performs security checks.
 3. **GeneralInterpreter**: Processes general-purpose requests.
 
-#### Interpretation workflow
+#### Interpretation Workflow
 
 1. Builds context with the current state, including results and user requests.
 2. Uses the language model to generate actionable insights.
-3. Provides detailed responses for the final user.
+3. Provides detailed responses for the end user.
 
 ---
 
-### Memory system
+### Memory System
 
 The memory architecture combines short-term and long-term memory to provide contextual processing.
 
-#### Types of memory
+#### Memory Types
 
-1. **Cache memory (Redis):**
-   - Stores temporary data for fast retrieval.
+1. **Cache Memory (Redis):**
+   - Stores temporary data for quick access.
    - Examples: Recent actions, session data.
-2. **Persistent memory (Meilisearch):**
+2. **Persistent Memory (Meilisearch):**
    - Stores long-term data such as historical interactions and knowledge.
-   - Enables semantic searches and vector-based retrieval.
+   - Supports semantic searches and vector-based retrievals.
+
+---
+
+### Listeners
+
+**Listeners** connect to external events via WebSocket. They listen for real-time updates and trigger specific actions or callbacks in response to events.
+
+**Key Features:**
+
+- Connect to WebSockets to listen for events.
+- Manage subscriptions with custom messages.
+- Trigger callbacks to process received data.
+
+**Usage Example:**
+
+```typescript
+agent.addListener(
+  "listener-id",
+  "wss://example.com/socket",
+  () => JSON.stringify({ action: "subscribe" }),
+  async (data) => {
+    console.log("Received data:", data);
+  }
+);
+```
+
+---
+
+### Schedulers
+
+**Schedulers** allow tasks or actions to be scheduled for later execution. They use cron expressions to define scheduling intervals.
+
+**Key Features:**
+
+- Cron-based scheduling.
+- Support for recurring and non-recurring tasks.
+- Management and cancellation of scheduled tasks.
+
+**Usage Example:**
+
+```typescript
+const scheduler = new TaskScheduler(agentRuntime, redisCache);
+
+const taskId = await scheduler.scheduleRequest({
+  originalRequest: "Market analysis",
+  cronExpression: "0 9 * * *", // Every day at 9 AM
+});
+
+console.log(`Task scheduled with ID: ${taskId}`);
+
+// Cancel the task if needed
+scheduler.cancelScheduledRequest(taskId);
+```
 
 ---
 
-## Defining and executing actions
+## Defining and Executing Actions
 
-### What are actions?
+### What is an Action?
 
-Actions are fundamental tasks executed by the framework. Each action includes:
+Actions are the fundamental tasks executed by the framework. Each action includes:
 
 - A unique name and description.
 - Input parameters validated using schemas.
 - Execution logic encapsulated in the `execute` method.
 
-### Example action
+### Action Example
 
 ```typescript
 import { z } from "zod";
@@ -156,7 +211,7 @@ import { parseEther } from "ethers";
 
 export const prepareTransaction = {
   name: "prepare-transaction",
-  description: "Prepare a token transfer for user approval.",
+  description: "Prepares a token transfer for user approval.",
   parameters: z.object({
     walletAddress: z.string(),
     amount: z.string(),
@@ -174,25 +229,25 @@ export const prepareTransaction = {
 
 ---
 
-## State management and recursion
+## State Management and Recursion
 
-The agent manages state and recursive workflows to ensure actions are executed in an orderly manner until completion, while respecting a maximum iteration limit to avoid infinite loops.
+The agent manages state and recursive workflows to ensure actions are executed in an orderly manner and to completion, while adhering to a maximum number of iterations to avoid infinite loops.
 
-### State management
+### State Management
 
 The state (`State`) includes:
 
-- `currentContext`: Current context of the user request.
-- `previousActions`: List of previously executed actions.
+- `currentContext`: The current context of the user request.
+- `previousActions`: A list of previously executed actions.
 
 When an action is completed, the state is updated to include:
 
-- Results of previous actions.
-- Remaining context to process.
+- Results from previous actions.
+- Remaining context to be processed.
 
-### Controlled recursion
+### Controlled Recursion
 
-To prevent infinite loops, the system limits the number of iterations using the `maxIterations` configuration.
+To prevent infinite loops, the system limits the number of iterations via the `maxIterations` configuration.
 
 **Workflow:**
 
@@ -201,14 +256,14 @@ To prevent infinite loops, the system limits the number of iterations using the
    - Executes actions in the queue.
    - Updates the state with new results.
 
-2. **Limit validation:**
+2. **Limit Validation:**
 
-   - If the iteration count exceeds `maxIterations`, processing is stopped with a "Max iterations reached" message.
+   - If the number of iterations exceeds `maxIterations`, processing is stopped with a "Max iterations reached" message.
 
 3. **Recursion:**
    - If actions remain to be executed, the agent recursively calls the `process` method with the updated state.
 
-**Example:**
+**State and Recursion Example:**
 
 ```typescript
 const updatedNextState: State = {
@@ -227,23 +282,23 @@ if (countIterations < this.config.maxIterations) {
 
 ---
 
-## Installation and setup
+## Installation and Configuration
 
-### Install dependencies
+### Install Dependencies
 
 ```bash
 npm install
 ```
 
-### Configure external services
+### Configure External Services
 
-#### Redis (cache memory)
+#### Redis (Cache Memory)
 
 ```bash
 docker run --name redis -d -p 6379:6379 redis
 ```
 
-#### Meilisearch (persistent memory)
+#### Meilisearch (Persistent Memory)
 
 ```bash
 curl -L https://install.meilisearch.com | sh
@@ -252,9 +307,9 @@ curl -L https://install.meilisearch.com | sh
 
 ---
 
-## Example usage
+## Usage Example
 
-### Initialize the agent
+### Initialize the Agent
 
 ```typescript
 import { deepseek } from "@ai-ntellect/core";
@@ -297,7 +352,7 @@ const agent = new Agent({
 });
 ```
 
-### Process a request
+### Process a Request
 
 ```typescript
 const state = {

package/agent/index.ts

@@ -2,33 +2,25 @@ import { LanguageModel } from "ai";
 import WebSocket from "ws";
 import { Interpreter } from "../llm/interpreter";
 import { MemoryManager } from "../llm/memory-manager";
-import { AgentRuntime } from "../llm/orchestrator";
-import { State } from "../llm/orchestrator/types";
+import { Orchestrator } from "../llm/orchestrator";
 import { CacheMemory } from "../memory/cache";
 import { PersistentMemory } from "../memory/persistent";
-import { ActionQueueManager } from "../services/queue";
-import { CacheConfig, RedisCache } from "../services/redis-cache";
-import { ActionData, ActionSchema, QueueCallbacks } from "../types";
-import { QueueItemTransformer } from "../utils/queue-item-transformer";
-export class Agent {
-  private readonly agent: AgentRuntime;
-  private readonly memoryManager: MemoryManager;
-  private readonly cache: RedisCache;
+import { CacheConfig, RedisCache } from "../services/cache";
+import { Workflow } from "../services/workflow";
+import { AgentEvent, MyContext, QueueCallbacks, SharedState } from "../types";
+import { createMainWorkflow } from "./workflow";
 
-  private webSocketClients: Map<
+export class Agent {
+  public readonly memoryManager: MemoryManager;
+  public readonly cache: RedisCache;
+  public readonly orchestrator: Orchestrator;
+  private listeners: Map<
     string,
     { socket: WebSocket; callback: (data: any) => Promise<void> }
   > = new Map();
-  private readonly config: {
-    orchestrator: {
-      model: LanguageModel;
-      tools: ActionSchema[];
-      memory?: {
-        cache?: CacheMemory;
-        persistent?: PersistentMemory;
-      };
-    };
+  public readonly config: {
     interpreters: Interpreter[];
+    orchestrator: Orchestrator;
     memoryManager: {
       model: LanguageModel;
       memory?: {
@@ -41,15 +33,8 @@ export class Agent {
 
   constructor(config: {
     cache: CacheConfig;
-    orchestrator: {
-      model: LanguageModel;
-      tools: ActionSchema[];
-      memory?: {
-        cache?: CacheMemory;
-        persistent?: PersistentMemory;
-      };
-    };
     interpreters: Interpreter[];
+    orchestrator: Orchestrator;
     memoryManager: {
       model: LanguageModel;
       memory?: {
@@ -62,13 +47,7 @@ export class Agent {
   }) {
     this.cache = new RedisCache(config.cache);
     this.config = config;
-    this.agent = new AgentRuntime(
-      config.orchestrator.model,
-      config.orchestrator.tools,
-      config.interpreters,
-      config.cache,
-      config.orchestrator.memory
-    );
+
     this.memoryManager = new MemoryManager({
       model: config.memoryManager.model,
       memory: {
@@ -76,142 +55,71 @@ export class Agent {
         persistent: config.memoryManager.memory?.persistent ?? undefined,
       },
     });
+    this.orchestrator = config.orchestrator;
     this.config.maxIterations = 3;
   }
 
-  public async process(state: State, callbacks?: QueueCallbacks): Promise<any> {
+  public async process(prompt: string, callbacks?: AgentEvent): Promise<any> {
     console.log("🔄 Processing state:");
-    console.dir(state, { depth: null });
-    let countIterations = 0;
-    const response = await this.agent.process(state);
-
-    const unscheduledActions = response.actions.filter(
-      (action) => !action.scheduler?.isScheduled
-    );
-    // Execute actions if needed
-    if (unscheduledActions?.length > 0 && response.shouldContinue) {
-      console.log("\n📋 Processing action queue");
-      const queueManager = new ActionQueueManager(
-        this.config.orchestrator.tools,
-        callbacks
-      );
-      const queueItems = QueueItemTransformer.transformActionsToQueueItems(
-        response.actions as ActionData[]
-      );
-      if (!queueItems) {
-        throw new Error("No queue items found");
-      }
+    const agent = this;
+    const recentMessages = await this.cache.getRecentMessages();
+    const previousActions = await this.cache.getRecentPreviousActions(1);
+
+    const initialState: SharedState<MyContext> = {
+      messages: [...recentMessages, { role: "user", content: prompt }],
+      context: {
+        prompt,
+        processing: {
+          stop: false,
+        },
+        results: previousActions,
+      },
+    };
 
-      console.log(
-        "📋 Actions to execute:",
-        queueItems
-          .map((item) => (typeof item === "string" ? item : item.name))
-          .join(", ")
-      );
-
-      queueManager.addToQueue(queueItems);
-      console.log("\n⚡ Executing actions...");
-      const results = await queueManager.processQueue();
-      console.log("✅ Execution results:", results);
-
-      const updatedNextState: State = {
-        ...state,
-        currentContext: state.currentContext,
-        previousActions: [...(state.previousActions || []), ...(results || [])],
-      };
+    const mainWorkflow = createMainWorkflow(agent, prompt, callbacks);
+    const workflow = new Workflow<MyContext>(mainWorkflow);
 
-      console.log("\n🔁 Recursively processing with updated state");
-      countIterations++;
-      if (countIterations < this.config.maxIterations) {
-        return this.process(updatedNextState);
+    await workflow.execute(
+      initialState,
+      mainWorkflow.entryNode,
+      async (state) => {
+        callbacks?.onMessage && (await callbacks.onMessage(state));
       }
-    }
-
-    if (countIterations >= this.config.maxIterations) {
-      console.log("Max iterations reached");
-      response.shouldContinue = false;
-      console.log("Forcing stop");
-    }
-
-    // Handle final interpretation
-    if (
-      !response.shouldContinue &&
-      state.previousActions?.length &&
-      response.interpreter
-    ) {
-      console.log("\n🏁 Analysis complete - generating final interpretation");
-      const interpreter = this.getInterpreter(
-        this.config.interpreters,
-        response.interpreter
-      );
-      console.log("🎭 Selected Interpreter:", interpreter?.name);
-      console.dir(state, { depth: null });
-      const interpretationResult = (await interpreter?.process(
-        "Interpret the analysis results",
-        {
-          ...state,
-          results: JSON.stringify(state.previousActions),
-          userRequest: state.currentContext,
-        }
-      )) as { response: string };
-
-      console.log("\n📊 Final Analysis:", interpretationResult.response);
-
-      const finalState: State = {
-        ...state,
-        results: interpretationResult.response,
-      };
-
-      console.log("🔄 Final state:", finalState);
-    }
-
-    // Return the final response at the end of the function
-    const validatedActions = response.actions.map((action) => ({
-      ...action,
-      parameters: action.parameters.map((param) => ({
-        ...param,
-        value: param.value ?? null, // Set a default value if undefined
-      })),
-    }));
-
-    const result = {
-      ...response,
-      actions: validatedActions,
-      results: JSON.stringify(state.previousActions),
-    };
-    if (!result.shouldContinue) {
-      await this.memoryManager.process(state, JSON.stringify(result));
-    }
-    return result;
+    );
   }
 
-  private getInterpreter(interpreters: Interpreter[], name: string) {
+  public getInterpreter(interpreters: Interpreter[], name: string) {
     return interpreters.find((interpreter) => interpreter.name === name);
   }
 
-  public addListener(
-    id: string,
-    url: string,
-    subscriptionMessageFactory: () => string,
-    callback: (data: any, agentContext: Agent) => Promise<void>
-  ): void {
-    if (this.webSocketClients.has(id)) {
+  public addListener({
+    id,
+    url,
+    onSubscribe,
+    onMessage,
+  }: {
+    id: string;
+    url: string;
+    onSubscribe: () => string;
+    onMessage: (data: any, agentContext: Agent) => Promise<void>;
+  }): void {
+    if (this.listeners.has(id)) {
       console.warn(`WebSocket with ID ${id} already exists.`);
       return;
     }
 
     const socket = new WebSocket(url);
 
-    const wrappedCallback = async (data: any) => {
-      await callback(data, this);
+    const wrappedOnMessage = async (data: any) => {
+      await onMessage(data, this);
     };
 
     socket.on("open", () => {
       console.log(`🔗 WebSocket connected for ID: ${id}`);
 
       // Envoie le message d'abonnement si une factory est fournie
-      if (subscriptionMessageFactory) {
-        const subscriptionMessage = subscriptionMessageFactory();
+      if (onSubscribe) {
+        const subscriptionMessage = onSubscribe();
         socket.send(subscriptionMessage);
         console.log(
           `📡 Sent subscription message for ID ${id}:`,
@@ -224,7 +132,7 @@ export class Agent {
       console.log(`📨 Message received for WebSocket ID ${id}:`, message);
       try {
         const data = JSON.parse(message);
-        await wrappedCallback(data);
+        await wrappedOnMessage(data);
       } catch (error) {
         console.error(`❌ Error in callback for WebSocket ID ${id}:`, error);
       }
@@ -238,6 +146,6 @@ export class Agent {
       console.log(`🔌 WebSocket closed for ID: ${id}`);
     });
 
-    this.webSocketClients.set(id, { socket, callback: wrappedCallback });
+    this.listeners.set(id, { socket, callback: wrappedOnMessage });
   }
 }

package/agent/workflow/conditions.ts

@@ -0,0 +1,16 @@
+import { SharedState } from "../../types";
+
+export const hasActions = (state: SharedState<any>): boolean =>
+  !!state.context.actions && state.context.actions.length > 0;
+
+export const isNotStopped = (state: SharedState<any>): boolean =>
+  !state.context.processing?.stop;
+
+export const isInterpreterDefined = (state: SharedState<any>): boolean =>
+  !!state.context.interpreter;
+
+export const isResultsDefined = (state: SharedState<any>): boolean =>
+  !!state.context.results && state.context.results.length > 0;
+
+export const isStopped = (state: SharedState<any>): boolean =>
+  !!state.context.processing?.stop;