@ai.ntellect/core 1.0.0 → 1.1.0

package/modules/nlp/engine.ts

@@ -0,0 +1,324 @@
+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);
+
+    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,19 +1,91 @@
 {
   "name": "@ai.ntellect/core",
-  "version": "1.0.0",
-  "description": "A robust framework for managing and executing workflows, supporting dynamic decision-making, conditional paths, event-driven execution, and state persistence.",
-  "main": "index.js",
+  "version": "1.1.0",
+  "description": "In-process workflow engine with typed graphs, events, and LLM agent support",
+  "main": "dist/index.js",
+  "packageManager": "pnpm@10.33.0",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "rimraf dist && tsc",
+    "prepare": "pnpm run build",
+    "prepublishOnly": "pnpm run build",
+    "cli": "node -r ts-node/register modules/cli/index.ts",
+    "example:hello": "ts-node examples/hello-graph.ts",
+    "example:events": "ts-node examples/event-triggered-workflow.ts",
+    "example:agent": "ts-node examples/agent-tools.ts",
+    "example:agent-events": "ts-node examples/agent-events.ts",
+    "example:agent-project": "ts-node examples/agent-project-creator.ts",
+    "example:agent-complex": "ts-node examples/agent-complex-projects.ts",
+    "example:native-tools": "ts-node examples/native-tools-demo.ts",
+    "example:wallet": "ts-node examples/hl-wallet-assistant/index.ts",
+    "example:onchain": "ts-node examples/onchain-agent/index.ts",
+    "example:trading": "ts-node examples/trading-system/index.ts",
+    "test": "mocha -r ./node_modules/ts-node/register",
+    "test:all": "mocha -r ./node_modules/ts-node/register 'test/**/*.test.ts'",
+    "test:coverage": "nyc --reporter=text --reporter=html pnpm test",
+    "test:watch": "mocha --require ./node_modules/ts-node/register 'test/**/*.test.ts' --watch --watch-files ./**/*.ts,test/**/*.ts",
+    "test:watch:execution": "mocha --require ./node_modules/ts-node/register 'test/execution/**/*.test.ts' --watch --watch-files ./execution/**/*.ts test/**/*.ts",
+    "test:petri": "mocha --require ./node_modules/ts-node/register 'test/routing/**/*.test.ts'",
+    "dev:cli": "ts-node cli-dev.ts",
+    "benchmark": "ts-node benchmark/run-benchmark.ts"
+  },
+  "keywords": [],
+  "author": "Lorcann Rauzduel",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/openai": "^1.1.15",
+    "@nlpjs/basic": "5.0.0-alpha.5",
+    "@types/node-cron": "^3.0.11",
+    "@types/pg": "^8.20.0",
+    "ai": "^4.1.46",
+    "chalk": "^5.4.1",
+    "dotenv": "^17.4.2",
+    "node-cron": "^3.0.3",
+    "pg": "^8.20.0",
+    "redis": "^4.7.0",
+    "rxjs": "^7.8.1",
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.1.43",
+    "@langchain/langgraph": "^1.2.9",
+    "@langchain/ollama": "^1.2.7",
+    "@nktkas/hyperliquid": "^0.32.2",
+    "@types/chai": "^4.3.20",
+    "@types/chai-as-promised": "^7.1.8",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20",
+    "@types/open": "^6.2.1",
+    "@types/sinon": "^17.0.3",
+    "chai": "^4.5.0",
+    "chai-as-promised": "^7.1.2",
+    "googleapis": "^171.4.0",
+    "mocha": "^10.0.0",
+    "neo4j-driver": "^6.1.0",
+    "nyc": "^17.1.0",
+    "open": "^11.0.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "redis": "^4.6.13",
+    "rimraf": "^5.0.10",
+    "sinon": "^19.0.2",
+    "ts-node": "10.9.1",
+    "typescript": "^5.7.2",
+    "viem": "^2.47.17"
+  },
+  "peerDependencies": {
+    "neo4j-driver": "^5.28.0"
+  },
+  "peerDependenciesMeta": {
+    "neo4j-driver": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ai-ntellect/workflow.git"
+    "url": "git+https://github.com/ai-ntellect/core.git"
   },
-  "author": "",
-  "license": "ISC",
   "bugs": {
-    "url": "https://github.com/ai-ntellect/workflow/issues"
+    "url": "https://github.com/ai-ntellect/core/issues"
   },
-  "homepage": "https://github.com/ai-ntellect/workflow#readme"
+  "homepage": "https://github.com/ai-ntellect/core#readme"
 }

package/persistence/index.ts

@@ -0,0 +1,27 @@
+export { Memory } from "../modules/memory";
+export { InMemoryCheckpointAdapter } from "../execution/adapters/in-memory-checkpoint";
+export {
+  IPetriCheckpointAdapter,
+  InMemoryPetriCheckpointAdapter,
+} from "../routing/checkpoint-adapter";
+export { RedisPetriCheckpointAdapter } from "../routing/redis-checkpoint-adapter";
+export { PostgresPetriCheckpointAdapter } from "../routing/postgres-checkpoint-adapter";
+export {
+  Neo4jExecutionTracer,
+} from "./neo4j/execution-tracer";
+export {
+  Neo4jPetriCheckpointAdapter,
+} from "./neo4j/petri-checkpoint-adapter";
+export {
+  Neo4jMemoryAdapter,
+} from "./neo4j/memory-adapter";
+export {
+  Neo4jEntityStore,
+  IEntityStore,
+} from "./neo4j/entity-store";
+export type {
+  Neo4jConfig,
+  Neo4jDriverLike,
+  Neo4jSessionLike,
+} from "./neo4j/driver";
+export { createDriver } from "./neo4j/driver";

package/persistence/neo4j/driver.ts

@@ -0,0 +1,34 @@
+export interface Neo4jSessionLike {
+  run(query: string, params?: Record<string, any>): Promise<{ records: any[] }>;
+  close(): Promise<void>;
+}
+
+export interface Neo4jDriverLike {
+  session(config?: { database?: string }): Neo4jSessionLike;
+  close(): Promise<void>;
+}
+
+export type Neo4jConfig =
+  | { driver: Neo4jDriverLike; database?: string }
+  | { url: string; username: string; password: string; database?: string };
+
+export async function createDriver(config: Neo4jConfig): Promise<{ driver: Neo4jDriverLike; database?: string }> {
+  if ("driver" in config) {
+    return { driver: config.driver, database: config.database };
+  }
+
+  let neo4j: any;
+  try {
+    neo4j = await import("neo4j-driver");
+  } catch {
+    throw new Error(
+      "neo4j-driver is not installed. Install it with: npm install neo4j-driver"
+    );
+  }
+
+  const driver = neo4j.default.auth
+    ? neo4j.default.driver(config.url, neo4j.default.auth.basic(config.username, config.password))
+    : neo4j.default.driver(config.url, neo4j.default.auth.basic(config.username, config.password));
+
+  return { driver, database: config.database };
+}

package/persistence/neo4j/entity-store.ts

@@ -0,0 +1,141 @@
+import { Entity } from "../../agent/entity-resolver/types";
+import { IEntityStore } from "../../agent/entity-resolver/entity-index";
+import { Neo4jDriverLike, Neo4jSessionLike } from "./driver";
+
+export { IEntityStore };
+
+export class Neo4jEntityStore implements IEntityStore {
+  constructor(
+    private driver: Neo4jDriverLike,
+    private database?: string
+  ) {}
+
+  private session(): Neo4jSessionLike {
+    return this.driver.session(this.database ? { database: this.database } : undefined);
+  }
+
+  async upsertMany(entities: Entity[]): Promise<void> {
+    const s = this.session();
+    try {
+      for (const entity of entities) {
+        await s.run(
+          `MERGE (e:Entity {id: $id})
+           SET e.category = $category,
+               e.filename = $filename,
+               e.stem = $stem,
+               e.extension = $extension,
+               e.path = $path,
+               e.scope = $scope
+           WITH e
+           UNWIND $tokens AS tokenValue
+           MERGE (t:Token {value: tokenValue})
+           MERGE (e)-[:HAS_TOKEN]->(t)`,
+          {
+            id: entity.id,
+            category: entity.category,
+            filename: entity.filename,
+            stem: entity.stem,
+            extension: entity.extension,
+            path: entity.path,
+            scope: entity.path.split("/")[0] || "root",
+            tokens: entity.tokens,
+          }
+        );
+
+        const dir = entity.path.substring(0, entity.path.lastIndexOf("/")) || "/";
+        await s.run(
+          `MATCH (e:Entity {id: $id})
+           MERGE (d:Dir {path: $dir})
+           MERGE (e)-[:IN_DIR]->(d)`,
+          { id: entity.id, dir }
+        );
+      }
+    } finally {
+      await s.close();
+    }
+  }
+
+  async loadAll(scope?: string): Promise<Entity[]> {
+    const s = this.session();
+    try {
+      let query: string;
+      let params: Record<string, any> = {};
+
+      if (scope) {
+        query = `MATCH (e:Entity)
+                 WHERE e.scope = $scope
+                 OPTIONAL MATCH (e)-[:HAS_TOKEN]->(t:Token)
+                 RETURN e, collect(t.value) AS tokens
+                 ORDER BY e.filename`;
+        params.scope = scope;
+      } else {
+        query = `MATCH (e:Entity)
+                 OPTIONAL MATCH (e)-[:HAS_TOKEN]->(t:Token)
+                 RETURN e, collect(t.value) AS tokens
+                 ORDER BY e.filename`;
+      }
+
+      const result = await s.run(query, params);
+
+      return result.records.map((r: any) => {
+        const entity = r.get("e");
+        const props = entity.properties ? (typeof entity.properties === "function" ? entity.properties() : entity.properties) : entity;
+        return {
+          id: props.id,
+          category: props.category || "file",
+          filename: props.filename,
+          stem: props.stem,
+          extension: props.extension || null,
+          tokens: r.get("tokens") || [],
+          path: props.path,
+        } as Entity;
+      });
+    } finally {
+      await s.close();
+    }
+  }
+
+  async recordResolution(
+    entityId: string,
+    query: string,
+    confidence: number
+  ): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (e:Entity {id: $entityId})
+         CREATE (r:Resolution {id: $resolutionId, query: $query, confidence: $confidence, at: $at})
+         MERGE (e)-[:RESOLVED_BY]->(r)`,
+        {
+          entityId,
+          resolutionId: `res-${entityId}-${Date.now()}`,
+          query,
+          confidence,
+          at: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async clear(scope?: string): Promise<void> {
+    const s = this.session();
+    try {
+      if (scope) {
+        await s.run(
+          `MATCH (e:Entity {scope: $scope})
+           DETACH DELETE e`,
+          { scope }
+        );
+      } else {
+        await s.run(
+          `MATCH (e:Entity)
+           DETACH DELETE e`
+        );
+      }
+    } finally {
+      await s.close();
+    }
+  }
+}