@ai.ntellect/core 0.4.0 → 0.4.1

package/README.FR.md

@@ -19,6 +19,8 @@ Ce framework est conçu pour exécuter des workflows complexes à l'aide d'une o
    - [Gestionnaire de file d'attente](#gestionnaire-de-file-dattente)
    - [Interpréteur](#interpréteur)
    - [Système de mémoire](#système-de-mémoire)
+   - [Listeners](#listeners)
+   - [Schedulers](#schedulers)
 2. [Définir et exécuter des actions](#définir-et-exécuter-des-actions)
 3. [Gestion de l'état et récursivité](#gestion-de-letat-et-recursivité)
 4. [Installation et configuration](#installation-et-configuration)
@@ -138,6 +140,59 @@ L'architecture mémoire combine une mémoire à court terme et une mémoire à l
 
 ---
 
+### Listeners
+
+Les **listeners** permettent de se connecter à des événements externes via WebSocket. Ils écoutent les mises à jour en temps réel et déclenchent des actions ou des callbacks spécifiques en réponse aux événements.
+
+**Caractéristiques principales :**
+
+- Connexion à des WebSockets pour écouter les événements.
+- Gestion des abonnements avec des messages personnalisés.
+- Déclenchement de callbacks pour traiter les données reçues.
+
+**Exemple d'utilisation :**
+
+```typescript
+agent.addListener(
+  "listener-id",
+  "wss://example.com/socket",
+  () => JSON.stringify({ action: "subscribe" }),
+  async (data) => {
+    console.log("Data reçue :", data);
+  }
+);
+```
+
+---
+
+### Schedulers
+
+Les **schedulers** permettent de planifier des tâches ou actions pour une exécution ultérieure. Ils utilisent des expressions cron pour définir les intervalles de planification.
+
+**Caractéristiques principales :**
+
+- Planification basée sur des expressions cron.
+- Support des tâches récurrentes et non récurrentes.
+- Gestion et annulation des tâches planifiées.
+
+**Exemple d'utilisation :**
+
+```typescript
+const scheduler = new TaskScheduler(agentRuntime, redisCache);
+
+const taskId = await scheduler.scheduleRequest({
+  originalRequest: "Analyse de marché",
+  cronExpression: "0 9 * * *", // Tous les jours à 9h
+});
+
+console.log(`Tâche planifiée avec ID : ${taskId}`);
+
+// Annuler la tâche si nécessaire
+scheduler.cancelScheduledRequest(taskId);
+```
+
+---
+
 ## Définir et exécuter des actions
 
 ### Qu'est-ce qu'une action ?

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

@@ -10,12 +10,13 @@ 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;
 
-  private webSocketClients: Map<
+  private listeners: Map<
     string,
     { socket: WebSocket; callback: (data: any) => Promise<void> }
   > = new Map();
@@ -195,7 +196,7 @@ export class Agent {
     subscriptionMessageFactory: () => string,
     callback: (data: any, agentContext: Agent) => Promise<void>
   ): void {
-    if (this.webSocketClients.has(id)) {
+    if (this.listeners.has(id)) {
       console.warn(`WebSocket with ID ${id} already exists.`);
       return;
     }
@@ -238,6 +239,6 @@ export class Agent {
       console.log(`🔌 WebSocket closed for ID: ${id}`);
     });
 
-    this.webSocketClients.set(id, { socket, callback: wrappedCallback });
+    this.listeners.set(id, { socket, callback: wrappedCallback });
   }
 }

package/dist/agent/index.d.ts

@@ -9,7 +9,7 @@ export declare class Agent {
     private readonly agent;
     private readonly memoryManager;
     private readonly cache;
-    private webSocketClients;
+    private listeners;
     private readonly config;
     constructor(config: {
         cache: CacheConfig;

package/dist/agent/index.js

@@ -12,7 +12,7 @@ const redis_cache_1 = require("../services/redis-cache");
 const queue_item_transformer_1 = require("../utils/queue-item-transformer");
 class Agent {
     constructor(config) {
-        this.webSocketClients = new Map();
+        this.listeners = new Map();
         this.cache = new redis_cache_1.RedisCache(config.cache);
         this.config = config;
         this.agent = new orchestrator_1.AgentRuntime(config.orchestrator.model, config.orchestrator.tools, config.interpreters, config.cache, config.orchestrator.memory);
@@ -104,7 +104,7 @@ class Agent {
         return interpreters.find((interpreter) => interpreter.name === name);
     }
     addListener(id, url, subscriptionMessageFactory, callback) {
-        if (this.webSocketClients.has(id)) {
+        if (this.listeners.has(id)) {
             console.warn(`WebSocket with ID ${id} already exists.`);
             return;
         }
@@ -137,7 +137,7 @@ class Agent {
         socket.on("close", () => {
             console.log(`🔌 WebSocket closed for ID: ${id}`);
         });
-        this.webSocketClients.set(id, { socket, callback: wrappedCallback });
+        this.listeners.set(id, { socket, callback: wrappedCallback });
     }
 }
 exports.Agent = Agent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai.ntellect/core",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "",
   "main": "dist/index.js",
   "scripts": {