@ai.ntellect/core 0.7.14 → 0.8.0

package/modules/nlp/engine.ts

@@ -0,0 +1,325 @@
+import { ActionHandler, NLPConfig } from "../../types";
+
+const { dockStart } = require("@nlpjs/basic");
+
+/**
+ * NLP Engine for processing natural language commands
+ * @example
+ * const engine = await NLPEngine.create({
+ *   corpus: require('./corpus.json'),
+ *   responses: require('./responses.json'),
+ *   entities: require('./entities.json')
+ * });
+ *
+ * engine.addAction('transferTokens', async (data) => {
+ *   // Handle transfer logic
+ * });
+ *
+ * const response = await engine.process('transfer 5 ETH');
+ */
+export class NLPEngine {
+  private manager: any;
+  private responses: Record<string, any>;
+  private intentHandlers: Record<string, ActionHandler> = {};
+
+  constructor() {
+    this.responses = {};
+  }
+
+  /**
+   * Creates and initializes a new NLP Engine
+   */
+  static async create(config: NLPConfig): Promise<NLPEngine> {
+    const engine = new NLPEngine();
+    await engine.init(config);
+    return engine;
+  }
+
+  /**
+   * Initializes the NLP engine with configuration
+   */
+  private async init({
+    corpus,
+    responses,
+    entities,
+    language = "en",
+    threshold = 0.5,
+  }: NLPConfig) {
+    const dock = await dockStart({
+      settings: {
+        nlp: {
+          forceNER: true,
+          languages: [language],
+          corpora: corpus ? [corpus] : undefined,
+        },
+        ner: { threshold },
+      },
+      use: ["Basic", "LangEn"],
+    });
+
+    this.manager = dock.get("nlp");
+    this.responses = responses || {};
+
+    if (corpus) {
+      await this.manager.addCorpus(corpus);
+    }
+
+    if (entities) {
+      this.registerEntities(entities);
+    }
+
+    await this.manager.train();
+  }
+
+  /**
+   * Registers entities for Named Entity Recognition (NER)
+   * @private
+   * @param {Record<string, any>} entities - Entity definitions
+   */
+  private registerEntities(entities: Record<string, any>) {
+    Object.entries(entities).forEach(([name, data]: [string, any]) => {
+      if (data.options) {
+        Object.entries(data.options).forEach(([option, texts]) => {
+          this.manager.addNerRuleOptionTexts(
+            "en",
+            name,
+            option,
+            texts as string[]
+          );
+        });
+      } else if (data.regex) {
+        this.manager.addNerRegexRule("en", name, data.regex);
+      } else if (data.trim) {
+        data.trim.forEach((trimRule: any) => {
+          if (trimRule.position === "afterLast") {
+            trimRule.words.forEach((word: string) => {
+              this.manager.addNerAfterLastCondition("en", name, word);
+            });
+          } else if (trimRule.position === "betweenLast") {
+            this.manager.addNerBetweenLastCondition(
+              "en",
+              name,
+              trimRule.leftWords,
+              trimRule.rightWords
+            );
+          }
+        });
+      }
+    });
+  }
+
+  /**
+   * Adds an action handler for a specific intent
+   * @param {string} name - Intent name
+   * @param {ActionHandler} handler - Action handler function
+   */
+  addAction(name: string, handler: ActionHandler): void {
+    this.intentHandlers[name] = handler;
+  }
+
+  /**
+   * Creates and loads a pre-trained NLP Engine
+   */
+  static async loadFromModel(
+    modelPath: string,
+    responses?: Record<string, any>
+  ): Promise<NLPEngine> {
+    const engine = new NLPEngine();
+    engine.responses = responses || {};
+    await engine.loadModel(modelPath);
+    return engine;
+  }
+
+  /**
+   * Loads a pre-trained model and configures default actions
+   */
+  private async loadModel(modelPath: string) {
+    const dock = await dockStart({
+      settings: {
+        nlp: {
+          forceNER: true,
+          languages: ["en"],
+        },
+      },
+      use: ["Basic", "LangEn"],
+    });
+
+    this.manager = dock.get("nlp");
+    await this.manager.load(modelPath);
+
+    // Configure default actions handler
+    this.setupDefaultActions();
+  }
+
+  /**
+   * Setup default actions to handle responses
+   */
+  private setupDefaultActions() {
+    this.manager.onIntent = async (data: any) => {
+      // Execute registered action if exists
+      if (data.actions?.length > 0) {
+        for (const actionData of data.actions) {
+          const result = await this.executeAction(actionData, data);
+          if (result) {
+            data.actionResult = result;
+          }
+        }
+      }
+
+      // Format response if answer exists
+      if (data.answer && this.responses[data.answer]) {
+        data.jsonResponse = this.formatResponse(
+          this.responses[data.answer],
+          data.actionResult || {}
+        );
+      }
+
+      return data;
+    };
+  }
+
+  /**
+   * Execute a single action
+   */
+  private async executeAction(actionData: any, context: any): Promise<any> {
+    const { action, parameters } = actionData;
+    const handler = this.manager.actions[action];
+    if (handler) {
+      return handler(context);
+    }
+    return null;
+  }
+
+  /**
+   * Processes natural language input text
+   * @param {string} input - Input text to process
+   * @returns {Promise<any>} Processing result with intent, entities and response
+   */
+  async process(input: string) {
+    const result = await this.manager.process("en", input);
+    console.log("NLP Engine Result:", result);
+
+    // Si une action est définie, exécuter le handler
+    if (result.intent) {
+      const handler = this.intentHandlers[result.intent.split(".")[1]];
+      if (handler) {
+        const handlerResult = await handler(result);
+        return {
+          ...result,
+          ...handlerResult,
+        };
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Trains the NLP model with current corpus
+   * @returns {Promise<void>}
+   */
+  public async train(): Promise<void> {
+    await this.manager.train();
+  }
+
+  /**
+   * Exports the trained model
+   * @param {boolean} [minified=true] - Whether to minify the exported model
+   * @returns {string} Exported model as string
+   */
+  public export(minified = true): string {
+    return this.manager.export(minified);
+  }
+
+  /**
+   * Imports a previously trained model
+   * @param {string} data - Model data to import
+   */
+  public import(data: string): void {
+    this.manager.import(data);
+  }
+
+  /**
+   * Saves the current model to a file
+   * @param {string} [path='./model.json'] - Path to save the model
+   * @returns {Promise<void>}
+   */
+  public async saveModel(path = "./model.json"): Promise<void> {
+    this.manager.save();
+    this.manager.save("./model.json");
+  }
+
+  /**
+   * Formats response using template and context
+   */
+  private formatResponse(template: any, context: any): any {
+    const response = JSON.parse(JSON.stringify(template));
+
+    // Format data fields
+    if (response.data) {
+      Object.keys(response.data).forEach((key) => {
+        if (context[key] !== undefined) {
+          response.data[key] = context[key];
+        }
+      });
+    }
+
+    return response;
+  }
+
+  /**
+   * Gets entity value from NLP result
+   * @param {any} data - NLP processing result
+   * @param {string} entityName - Name of the entity to extract
+   * @returns {string|undefined} Entity value if found
+   */
+  getEntity(data: any, entityName: string): string | undefined {
+    const entity = data.entities?.find((e: any) => e.entity === entityName);
+    return entity ? entity.utteranceText : undefined;
+  }
+
+  /**
+   * Gets entity option from NLP result
+   * @param {any} data - NLP processing result
+   * @param {string} entityName - Name of the entity to extract
+   * @returns {string|undefined} Entity option if found
+   */
+  getEntityOption(data: any, entityName: string): string | undefined {
+    const entity = data.entities?.find((e: any) => e.entity === entityName);
+    return entity ? entity.option : undefined;
+  }
+
+  /**
+   * Gets recipient entity from NLP result
+   * @param {any} data - NLP processing result
+   * @returns {string|undefined} Recipient value if found
+   */
+  getRecipient(data: any): string | undefined {
+    const toEntity = data.entities?.find((e: any) => e.entity === "to");
+    return toEntity ? toEntity.utteranceText : undefined;
+  }
+
+  /**
+   * Gets current responses configuration
+   * @returns {Record<string, any>} Current responses
+   */
+  public getResponses(): Record<string, any> {
+    return this.responses;
+  }
+
+  /**
+   * Gets current corpus configuration
+   * @returns {any} Current corpus
+   */
+  public getCorpus(): any {
+    return this.manager.corpora;
+  }
+
+  /**
+   * Gets current entities configuration
+   * @returns {any} Current entities configuration
+   */
+  public getEntities(): any {
+    return this.manager.nerManager?.rules || {};
+  }
+}

package/modules/nlp/index.ts

@@ -0,0 +1,45 @@
+import { NLPNodeConfig } from "@/interfaces";
+import { ZodSchema } from "zod";
+import { NLPEngine } from "./engine";
+
+/**
+ * NLPNode class handles natural language processing operations with type-safe schema validation
+ * @template T - Zod schema type for validation
+ */
+export class NLPNode<T extends ZodSchema> {
+  private engine!: NLPEngine;
+
+  /**
+   * Creates an instance of NLPNode
+   * @param {NLPNodeConfig<T>} config - Configuration object for the NLP node
+   */
+  constructor(private config: NLPNodeConfig<T>) {}
+
+  /**
+   * Initializes the NLP engine and sets up intent handlers
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    this.engine = await NLPEngine.create(this.config.nlpConfig);
+    console.log("Loaded engine");
+    if (this.config.intentHandlers) {
+      Object.entries(this.config.intentHandlers).forEach(
+        ([intent, handler]) => {
+          this.engine.addAction(intent, handler);
+        }
+      );
+    }
+  }
+
+  /**
+   * Processes the input text through the NLP engine
+   * @param {string} input - Text to be processed
+   * @returns {Promise<any>} - Processing result from the engine
+   */
+  async process(input: string) {
+    console.log("NLP Node processing:", input);
+    const result = await this.engine.process(input);
+    console.log("NLP Node result:", result);
+    return result;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai.ntellect/core",
-  "version": "0.7.14",
+  "version": "0.8.0",
   "description": "",
   "main": "dist/index.js",
   "scripts": {
@@ -17,8 +17,11 @@
   "author": "Lorcann Rauzduel",
   "license": "ISC",
   "dependencies": {
+    "@ai-sdk/openai": "^1.1.15",
+    "@nlpjs/basic": "5.0.0-alpha.5",
     "@types/node-cron": "^3.0.11",
-    "ai": "^3.0.0",
+    "ai": "^4.1.46",
+    "chalk": "^5.4.1",
     "node-cron": "^3.0.3",
     "redis": "^4.7.0",
     "rxjs": "^7.8.1",

package/test/graph/index.test.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { GraphController } from "../../graph/controller";
 import { GraphFlow } from "../../graph/index";
 import { NodeParams } from "../../graph/node";
-import { GraphContext, GraphConfig, GraphNodeConfig } from "../../types";
+import { GraphConfig, GraphContext, GraphNodeConfig } from "../../types";
 
 use(chaiAsPromised);
 
@@ -595,14 +595,16 @@ describe("GraphFlow", function () {
    * Tests single event waiting functionality
    */
   it("should wait for a single event before continuing", async function () {
-    this.timeout(5000);
-
     const waitingNode: GraphNodeConfig<TestSchema> = {
       name: "waitingNode",
       execute: async (context: GraphContext<typeof TestSchema>) => {
         context.value = 1;
       },
-      waitForEvent: true,
+      when: {
+        events: ["someEvent"],
+        timeout: 1000,
+        strategy: { type: "single" },
+      },
       next: ["finalNode"],
     };
 

package/test/graph/node.test.ts

@@ -512,10 +512,10 @@ describe("GraphNode", () => {
     const nodes = new Map();
     nodes.set("waitForEventsNode", {
       name: "waitForEventsNode",
-      waitForEvents: {
+      when: {
         events: ["event1", "event2"],
         timeout: 1000,
-        strategy: "all",
+        strategy: { type: "all" },
       },
       execute: async (context: TestContext) => {
         context.message = "Events received";
@@ -554,10 +554,10 @@ describe("GraphNode", () => {
     const nodes = new Map();
     nodes.set("timeoutNode", {
       name: "timeoutNode",
-      waitForEvents: {
+      when: {
         events: ["event1", "event2"],
         timeout: 100,
-        strategy: "all",
+        strategy: { type: "all" },
       },
       execute: async (context: TestContext) => {
         context.message = "Should not execute";
@@ -571,7 +571,6 @@ describe("GraphNode", () => {
       eventSubject,
       stateSubject
     );
-
     await expect(
       node.executeNode("timeoutNode", { counter: 0, message: "Hello" }, null)
     ).to.be.rejectedWith("Timeout waiting for events");
@@ -581,10 +580,10 @@ describe("GraphNode", () => {
     const nodes = new Map();
     nodes.set("partialEventsNode", {
       name: "partialEventsNode",
-      waitForEvents: {
+      when: {
         events: ["event1", "event2"],
         timeout: 1000,
-        strategy: "all",
+        strategy: { type: "all" },
       },
       execute: async (context: TestContext) => {
         context.message = "All events received";
@@ -598,14 +597,12 @@ describe("GraphNode", () => {
       eventSubject,
       stateSubject
     );
-
     const execution = node.executeNode(
       "partialEventsNode",
       { counter: 0, message: "Hello" },
       null
     );
 
-    // N'émettre qu'un seul événement
     setTimeout(() => {
       eventEmitter.emit("event1", { data: "test1" });
     }, 100);
@@ -617,13 +614,20 @@ describe("GraphNode", () => {
     const nodes = new Map();
     nodes.set("correlatedEventsNode", {
       name: "correlatedEventsNode",
-      correlateEvents: {
+      when: {
         events: ["payment", "stock"],
         timeout: 1000,
-        correlation: (events: Array<{ type: string; payload?: any }>) => {
-          const paymentEvent = events.find((e) => e.type === "payment");
-          const stockEvent = events.find((e) => e.type === "stock");
-          return paymentEvent?.payload?.id === stockEvent?.payload?.id;
+        strategy: {
+          type: "correlate",
+          correlation: (events: Array<{ type: string; payload?: any }>) => {
+            const paymentEvent = events.find(
+              (e: { type: string }) => e.type === "payment"
+            );
+            const stockEvent = events.find(
+              (e: { type: string }) => e.type === "stock"
+            );
+            return paymentEvent?.payload?.id === stockEvent?.payload?.id;
+          },
         },
       },
       execute: (context: TestContext) => {

package/types/agent.ts

@@ -0,0 +1,174 @@
+import { GraphFlow } from "@/graph";
+import { z } from "zod";
+
+/**
+ * Represents an action that has been executed by the agent
+ * @interface ExecutedAction
+ * @property {string} name - The name of the executed action
+ * @property {boolean} isExecuted - Whether the action was successfully executed
+ * @property {string | null} [error] - Optional error message if the action failed
+ * @property {any} result - The result of the action execution
+ * @property {string} timestamp - When the action was executed
+ */
+export type ExecutedAction = {
+  name: string;
+  isExecuted: boolean;
+  error?: string | null;
+  result: any;
+  timestamp: string;
+};
+
+/**
+ * Represents the context in which an agent operates
+ * @interface AgentContext
+ * @property {Object} input - The input provided to the agent
+ * @property {string} input.raw - The raw input text
+ * @property {number[]} [input.embedding] - Optional vector embedding of the input
+ * @property {ActionSchema[]} actions - List of actions available to the agent
+ * @property {string} response - The agent's response
+ * @property {string} [knowledge] - Optional knowledge base or context
+ * @property {ExecutedAction[]} executedActions - History of executed actions
+ */
+export type AgentContext = {
+  input: {
+    raw: string;
+    embedding?: number[];
+  };
+  actions: ActionSchema[];
+  response: string;
+  knowledge?: string;
+  executedActions: ExecutedAction[];
+};
+
+export const AgentContextSchema = z.object({
+  input: z.object({
+    raw: z.string(),
+    embedding: z.array(z.number()).optional(),
+  }),
+  actions: z.array(
+    z.object({
+      name: z.string(),
+      parameters: z.array(
+        z.object({
+          name: z.string(),
+          value: z.any(),
+        })
+      ),
+      isExecuted: z.boolean().optional(),
+      result: z.any().optional(),
+    })
+  ),
+  knowledge: z.string().optional(),
+  response: z.string(),
+  executedActions: z
+    .array(
+      z.object({
+        name: z.string(),
+        result: z.any(),
+        timestamp: z.string(),
+      })
+    )
+    .optional(),
+});
+
+/**
+ * Represents a section of the prompt with a title and content
+ * @interface PromptSection
+ * @property {string} title - The title of the prompt section
+ * @property {string | ((context: AgentContext) => string | Promise<string>)} content - The content or a function to generate content
+ */
+export type PromptSection = {
+  title: string;
+  content: string | ((context: AgentContext) => string | Promise<string>);
+};
+
+/**
+ * Supported LLM providers
+ */
+export type LLMProvider = "openai" | "anthropic" | "custom";
+
+/**
+ * Supported LLM models
+ */
+export type LLMModel = "gpt-4" | "gpt-3.5-turbo" | "claude-2" | string;
+
+export type ExecutorConfig = {
+  llmConfig: LLMConfig;
+  verbose?: boolean;
+};
+
+/**
+ * Configuration for the Agent
+ * @type AssistantConfig
+ * @extends {Omit<ExecutorConfig, "verbose">}
+ * @property {string} role - The function/job of the assistant (e.g., "Email Assistant")
+ * @property {string} goal - The specific objective the assistant tries to achieve
+ * @property {string} backstory - The personality and behavioral traits of the assistant
+ * @property {any[]} [tools] - Optional tools the assistant can use
+ * @property {any} [memory] - Optional memory system
+ * @property {boolean} [verbose] - Whether to log detailed information
+ */
+export type AgentConfig = {
+  role: string;
+  goal: string;
+  backstory: string;
+  tools: GraphFlow<any>[];
+  memory?: any;
+  verbose?: boolean;
+  llmConfig: ExecutorConfig["llmConfig"];
+};
+
+/**
+ * Represents the schema of an action that can be performed by the agent
+ * @interface ActionSchema
+ * @property {string} name - The name of the action
+ * @property {Array<{name: string, value: any}>} parameters - The parameters required for the action
+ */
+export type ActionSchema = {
+  name: string;
+  parameters: Array<{ name: string; value: any }>;
+};
+
+/**
+ * Represents the output of the agent's decision-making process
+ * @interface DecisionOutput
+ * @property {ActionSchema[]} actions - The actions to be executed
+ * @property {string} response - The agent's response message
+ */
+export type DecisionOutput = {
+  actions: ActionSchema[];
+  response: string;
+};
+
+/**
+ * Configuration for the Language Model
+ * @interface LLMConfig
+ * @property {LLMProvider} provider - The LLM provider to use
+ * @property {string} apiKey - API key for the provider
+ * @property {LLMModel} model - The specific model to use
+ * @property {number} [temperature] - Optional temperature parameter for response randomness
+ * @property {number} [maxTokens] - Optional maximum tokens for the response
+ * @property {Function} [customCall] - Optional custom implementation for API calls
+ */
+export type LLMConfig = {
+  provider: LLMProvider;
+  apiKey: string;
+  model: LLMModel;
+  temperature?: number;
+  maxTokens?: number;
+  customCall?: (
+    prompt: string | PromptInput,
+    schema: z.ZodType<any>
+  ) => Promise<any>;
+};
+
+/**
+ * Structure for prompt input to the LLM
+ * @interface PromptInput
+ * @property {string} system - The system message/context
+ * @property {string} user - The user's input message
+ */
+export type PromptInput = {
+  system: string;
+  user: string;
+};