@ai.ntellect/core 0.5.0 → 0.6.1

package/index copy.ts

@@ -0,0 +1,81 @@
+export interface NetworkConfig {
+  name: string;
+  id?: number;
+  rpc: string;
+  explorerUrl: string;
+  nativeToken: string; // WETH
+}
+export const networkConfigs: Record<string, NetworkConfig> = {
+  ethereum: {
+    name: "Ethereum Mainnet",
+    id: 1,
+    rpc: "https://eth.llamarpc.com",
+    explorerUrl: "https://etherscan.io",
+    nativeToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+  },
+  polygon: {
+    name: "Polygon Mainnet",
+    id: 137,
+    rpc: "https://polygon.llamarpc.com",
+    explorerUrl: "https://polygonscan.com",
+    nativeToken: "0x0000000000000000000000000000000000001010",
+  },
+  arbitrum: {
+    name: "Arbitrum Mainnet",
+    id: 42161,
+    rpc: "https://arbitrum.llamarpc.com",
+    explorerUrl: "https://arbiscan.io",
+    nativeToken: "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
+  },
+  base: {
+    name: "Base Mainnet",
+    id: 8453,
+    rpc: "https://base.llamarpc.com",
+    explorerUrl: "https://basescan.org",
+    nativeToken: "0x4200000000000000000000000000000000000006",
+  },
+  solana: {
+    name: "Solana Mainnet",
+    rpc: "https://api.mainnet-beta.solana.com",
+    explorerUrl: "https://solscan.io",
+    nativeToken: "So11111111111111111111111111111111111111112",
+  },
+  sepolia: {
+    name: "Sepolia Testnet",
+    id: 11155111,
+    rpc: "https://rpc.sepolia.ethpandaops.io",
+    explorerUrl: "https://sepolia.etherscan.io",
+    nativeToken: "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14",
+  },
+  baseSepolia: {
+    name: "Base Sepolia Testnet",
+    id: 84532,
+    rpc: "https://base-sepolia-rpc.publicnode.com",
+    explorerUrl: "https://sepolia.basescan.org",
+    nativeToken: "0x4200000000000000000000000000000000000006",
+  },
+};
+
+export const getNetworkProvider = (networkName: string) => {
+  const config = networkConfigs[networkName.toLowerCase()];
+  if (!config) {
+    throw new Error(`Network ${networkName} not supported`);
+  }
+  return { config };
+};
+
+export const ROUTER_ADDRESSES: { [key: string]: string } = {
+  ethereum: "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
+  sepolia: "0xeE567Fe1712Faf6149d80dA1E6934E354124CfE3",
+  arbitrum: "0x4752ba5dbc23f44d87826276bf6fd6b1c372ad24",
+  polygon: "0xedf6066a2b290C185783862C7F4776A2C8077AD1",
+  base: "0x4752ba5dbc23f44d87826276bf6fd6b1c372ad24",
+  optimism: "0x4A7b5Da61326A6379179b40d00F57E5bbDC962c2",
+  blast: "0xBB66Eb1c5e875933D44DAe661dbD80e5D9B03035",
+  zora: "0xa00F34A632630EFd15223B1968358bA4845bEEC7",
+  worldchain: "0x541aB7c31A119441eF3575F6973277DE0eF460bd",
+};
+
+export const getRouterAddress = (networkName: string) => {
+  return ROUTER_ADDRESSES[networkName.toLowerCase()];
+};

package/index.ts

@@ -1,8 +1,8 @@
-export * from "./agent";
-export * from "./llm/interpreter";
-export * from "./llm/interpreter/context";
-export * from "./llm/orchestrator";
-export * from "./types";
+export * from "./graph/controller";
+export * from "./graph/engine";
+export * from "./memory";
+export * from "./memory/adapters/meilisearch";
+export * from "./memory/adapters/redis";
 
-export * from "./memory/cache";
-export * from "./memory/persistent";
+export * from "./interfaces";
+export * from "./types";

package/interfaces/index.ts

@@ -0,0 +1,119 @@
+import { BaseMemoryType } from "@/types";
+import { SharedState } from "@/types";
+
+/* ======================== PERSISTENCE ======================== */
+
+/**
+ * Interface for persisting graph execution state.
+ */
+export interface Persistence<T> {
+  saveState(
+    graphName: string,
+    state: SharedState<T>,
+    currentNode: string
+  ): Promise<void>;
+  loadState(
+    graphName: string
+  ): Promise<{ state: SharedState<T>; currentNode: string } | null>;
+}
+
+/* ======================== REAL-TIME NOTIFICATIONS ======================== */
+
+/**
+ * Interface for real-time notifications.
+ */
+export interface RealTimeNotifier {
+  notify(event: string, data: any): void;
+}
+
+/* ======================== EMBEDDING SERVICE ======================== */
+
+/**
+ * Interface for an embedding service that processes text into vector representations.
+ */
+export interface EmbeddingService {
+  /**
+   * Generates an embedding for a single text.
+   * @param {string} text - The input text to embed.
+   * @returns {Promise<number[]>} - A vector representation of the text.
+   */
+  embedText(text: string): Promise<number[]>;
+
+  /**
+   * Generates embeddings for multiple texts at once.
+   * @param {string[]} texts - The array of texts to embed.
+   * @returns {Promise<number[][]>} - A list of vector representations.
+   */
+  embedMany(texts: string[]): Promise<number[][]>;
+
+  /**
+   * Calculates the similarity between two embeddings.
+   * @param {number[]} embedding1 - First vector.
+   * @param {number[]} embedding2 - Second vector.
+   * @returns {number} - A similarity score between the two vectors.
+   */
+  calculateSimilarity(embedding1: number[], embedding2: number[]): number;
+}
+
+/* ======================== MEMORY SERVICE ======================== */
+
+/**
+ * Interface for managing memory storage and retrieval.
+ */
+export interface BaseMemoryService {
+  /**
+   * Initializes the memory storage connection.
+   * @returns {Promise<void>} - Resolves when initialization is complete.
+   */
+  initializeConnection(): Promise<void>;
+
+  /**
+   * Stores a new memory entry.
+   * @param {BaseMemoryType} memory - The memory data to store.
+   * @param {number} [ttl] - Optional time-to-live in seconds.
+   * @returns {Promise<void>}
+   */
+  createMemory(memory: BaseMemoryType, ttl?: number): Promise<void>;
+
+  /**
+   * Retrieves a memory entry by its unique ID.
+   * @param {string} id - The memory entry identifier.
+   * @returns {Promise<BaseMemoryType | null>} - The found memory or null.
+   */
+  getMemoryById(id: string): Promise<BaseMemoryType | null>;
+
+  /**
+   * Searches for memory entries based on a query and optional constraints.
+   * @param {string} query - The search query.
+   * @param {Object} options - Search options.
+   * @param {string} options.roomId - The room identifier.
+   * @param {number} [options.limit] - Maximum number of results (optional).
+   * @returns {Promise<BaseMemoryType[]>} - A list of matched memory entries.
+   */
+  getMemoryByIndex(
+    query: string,
+    options: {
+      roomId: string;
+      limit?: number;
+    }
+  ): Promise<BaseMemoryType[]>;
+
+  /**
+   * Retrieves all stored memory entries.
+   * @returns {Promise<BaseMemoryType[]>} - A list of all memory entries.
+   */
+  getAllMemories(): Promise<BaseMemoryType[]>;
+
+  /**
+   * Deletes a memory entry by its unique ID.
+   * @param {string} id - The memory entry identifier.
+   * @returns {Promise<void>}
+   */
+  clearMemoryById(id: string): Promise<void>;
+
+  /**
+   * Clears all stored memory entries.
+   * @returns {Promise<void>}
+   */
+  clearAllMemories(): Promise<void>;
+}

package/memory/adapters/meilisearch/index.ts

@@ -0,0 +1,286 @@
+import { BaseMemoryService } from "@/interfaces";
+import { BaseMemory } from "@/memory";
+import { BaseMemoryType, CreateMemoryInput, MeilisearchConfig } from "@/types";
+
+export class MeilisearchAdapter extends BaseMemory {
+  constructor(
+    private readonly config: MeilisearchConfig,
+    baseMemoryService: BaseMemoryService
+  ) {
+    super(baseMemoryService);
+  }
+
+  private async makeRequest(path: string, options?: RequestInit) {
+    try {
+      const url = `${this.config.host}${path}`;
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+          ...options?.headers,
+        },
+      });
+
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new Error(
+          `HTTP ${response.status}: ${errorBody || response.statusText}`
+        );
+      }
+
+      return response.json();
+    } catch (error) {
+      if (error instanceof TypeError && error.message === "Failed to fetch") {
+        throw new Error(
+          `Network error: Unable to connect to Meilisearch at ${this.config.host}`
+        );
+      }
+      throw error;
+    }
+  }
+
+  async initializeStorage(roomId: string): Promise<void> {
+    try {
+      let indexExists = false;
+
+      try {
+        // Check if index exists
+        await this.makeRequest(`/indexes/${roomId}`);
+        indexExists = true;
+      } catch (error) {
+        // Only continue if the error is "Not found"
+        if (!(error instanceof Error && error.message.includes("Not found"))) {
+          throw error;
+        }
+      }
+
+      if (!indexExists) {
+        // Create new index
+        await this.makeRequest("/indexes", {
+          method: "POST",
+          body: JSON.stringify({
+            uid: roomId,
+            primaryKey: "id",
+          }),
+        });
+
+        // Wait for index creation
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+
+      // Update settings
+      await this.makeRequest(`/indexes/${roomId}/settings`, {
+        method: "PATCH",
+        body: JSON.stringify({
+          searchableAttributes: this.config.searchableAttributes || [
+            "data",
+            "query",
+          ],
+          sortableAttributes: this.config.sortableAttributes || ["createdAt"],
+        }),
+      });
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      console.error(
+        `Error initializing storage for index ${roomId}:`,
+        errorMessage
+      );
+      throw new Error(
+        `Failed to initialize storage for index ${roomId}: ${errorMessage}`
+      );
+    }
+  }
+
+  async addDocuments(
+    documents: BaseMemoryType[],
+    roomId: string
+  ): Promise<void> {
+    await this.makeRequest(`/indexes/${roomId}/documents`, {
+      method: "POST",
+      body: JSON.stringify(documents),
+    });
+  }
+
+  async search(
+    query: string,
+    roomId: string,
+    options?: { limit?: number; threshold?: number }
+  ): Promise<SearchResult[]> {
+    const searchResults = await this.makeRequest(`/indexes/${roomId}/search`, {
+      method: "POST",
+      body: JSON.stringify({
+        q: query,
+        limit: options?.limit || 10,
+      }),
+    });
+
+    return searchResults.hits.map((hit: any) => ({
+      document: {
+        id: hit.id,
+        data: hit.data,
+        query: hit.query,
+        embedding: hit.embedding,
+        roomId: hit.roomId,
+        createdAt: hit.createdAt,
+      },
+      score: hit._score || 0,
+    }));
+  }
+
+  async deleteStorage(roomId: string): Promise<void> {
+    await this.makeRequest(`/indexes/${roomId}`, {
+      method: "DELETE",
+    });
+  }
+
+  // Required BaseMemory implementations
+  async init(): Promise<void> {
+    try {
+      // Initialize the default "memories" index
+      await this.initializeStorage("memories");
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      console.error("Failed to initialize default index:", errorMessage);
+      throw new Error(`Failed to initialize default index: ${errorMessage}`);
+    }
+  }
+
+  async createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined> {
+    // Initialize storage for this roomId if needed
+    await this.initializeStorage(input.roomId);
+
+    // Search for existing memory with same data and query
+    const searchResults = await this.search(input.data, input.roomId, {
+      limit: 1,
+    });
+    const existingMemory = searchResults.find(
+      (result) =>
+        result.document.data === input.data &&
+        result.document.query === input.query &&
+        result.document.roomId === input.roomId
+    );
+
+    // If found, return existing memory
+    if (existingMemory) {
+      return existingMemory.document;
+    }
+
+    // If not found, create new memory
+    const memory: BaseMemoryType = {
+      id: crypto.randomUUID(),
+      data: input.data,
+      query: input.query,
+      embedding: input.embedding || null,
+      roomId: input.roomId,
+      createdAt: new Date(),
+    };
+
+    await this.addDocuments([memory], input.roomId);
+    return memory;
+  }
+
+  async getMemoryById(
+    id: string,
+    roomId: string
+  ): Promise<BaseMemoryType | null> {
+    try {
+      const result = await this.makeRequest(
+        `/indexes/${roomId}/documents/${id}`
+      );
+      return result
+        ? {
+            id: result.id,
+            data: result.data,
+            query: result.query,
+            embedding: result.embedding,
+            roomId: result.roomId,
+            createdAt: result.createdAt,
+          }
+        : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]> {
+    const results = await this.search(query, options.roomId, {
+      limit: options.limit,
+    });
+    return results
+      .filter((result) => result.document.roomId === options.roomId)
+      .map((result) => ({
+        id: result.document.id,
+        data: result.document.data,
+        query: result.document.query,
+        embedding: result.document.embedding,
+        roomId: result.document.roomId,
+        createdAt: result.document.createdAt,
+      }));
+  }
+
+  async getAllMemories(roomId: string): Promise<BaseMemoryType[]> {
+    const results = await this.makeRequest(`/indexes/${roomId}/documents`);
+    return results.map((doc: any) => ({
+      id: doc.id,
+      data: doc.data,
+      query: doc.query,
+      embedding: doc.embedding,
+      roomId: doc.roomId,
+      createdAt: doc.createdAt,
+    }));
+  }
+
+  async clearMemoryById(id: string, roomId: string): Promise<void> {
+    try {
+      // Ensure the index exists before attempting to delete
+      await this.initializeStorage(roomId);
+
+      await this.makeRequest(`/indexes/${roomId}/documents/${id}`, {
+        method: "DELETE",
+      });
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      console.error(
+        `Error clearing memory ${id} from index ${roomId}:`,
+        errorMessage
+      );
+      throw new Error(
+        `Failed to clear memory ${id} from index ${roomId}: ${errorMessage}`
+      );
+    }
+  }
+
+  async clearAllMemories(): Promise<void> {
+    try {
+      // Get all indexes
+      const response = await this.makeRequest("/indexes");
+      const indexes = response.results || [];
+
+      // Delete each index
+      for (const index of indexes) {
+        await this.deleteStorage(index.uid);
+      }
+
+      // Reinitialize the default index
+      await this.init();
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`Failed to clear all memories: ${errorMessage}`);
+    }
+  }
+}
+
+interface SearchResult {
+  document: BaseMemoryType;
+  score: number;
+}

package/memory/adapters/redis/index.ts

@@ -0,0 +1,103 @@
+import { BaseMemoryService } from "@/interfaces";
+import { BaseMemoryType } from "@/types";
+import { createClient } from "redis";
+
+export class RedisAdapter implements BaseMemoryService {
+  private redis;
+  private readonly cachePrefix: string;
+  private readonly cacheTTL: number;
+
+  constructor(
+    private readonly redisUrl: string,
+    options: {
+      cachePrefix?: string;
+      cacheTTL?: number;
+    }
+  ) {
+    this.cachePrefix = options.cachePrefix || "memory:";
+    this.cacheTTL = options.cacheTTL || 3600;
+    this.redis = createClient({
+      url: redisUrl,
+      socket: {
+        tls: true,
+        rejectUnauthorized: true,
+      },
+    });
+  }
+
+  async initializeConnection(): Promise<void> {
+    this.redis.on("error", (err) => console.error("Redis Client Error:", err));
+    await this.redis.connect();
+  }
+
+  async createMemory(memory: BaseMemoryType, ttl?: number): Promise<void> {
+    const key = memory.roomId
+      ? `${this.cachePrefix}${memory.roomId}:${memory.id}`
+      : `${this.cachePrefix}${memory.id}`;
+
+    await this.redis.set(key, JSON.stringify(memory), {
+      EX: ttl || this.cacheTTL,
+    });
+  }
+
+  async getMemoryById(
+    id: string,
+    roomId?: string
+  ): Promise<BaseMemoryType | null> {
+    const key = roomId
+      ? `${this.cachePrefix}${roomId}:${id}`
+      : `${this.cachePrefix}${id}`;
+
+    const data = await this.redis.get(key);
+    return data ? JSON.parse(data) : null;
+  }
+
+  async getMemoryByIndex(
+    query: string,
+    options: {
+      roomId?: string;
+      limit?: number;
+    } = {}
+  ): Promise<BaseMemoryType[]> {
+    const pattern = options.roomId
+      ? `${this.cachePrefix}${options.roomId}:*`
+      : `${this.cachePrefix}*`;
+
+    const keys = await this.redis.keys(pattern);
+    const memories = await Promise.all(
+      keys.map(async (key) => {
+        const data = await this.redis.get(key);
+        return data ? JSON.parse(data) : null;
+      })
+    );
+    return memories.filter(Boolean).slice(0, options.limit || 10);
+  }
+
+  async getAllMemories(): Promise<BaseMemoryType[]> {
+    const keys = await this.redis.keys(`${this.cachePrefix}*`);
+    const memories = await Promise.all(
+      keys.map(async (key) => {
+        const data = await this.redis.get(key);
+        return data ? JSON.parse(data) : null;
+      })
+    );
+    return memories.filter(Boolean);
+  }
+
+  async clearMemoryById(id: string): Promise<void> {
+    await this.redis.del(`${this.cachePrefix}${id}`);
+  }
+
+  async clearAllMemories(): Promise<void> {
+    const keys = await this.redis.keys(`${this.cachePrefix}*`);
+    if (keys.length > 0) {
+      await this.redis.del(keys);
+    }
+  }
+
+  async quit(): Promise<void> {
+    if (this.redis) {
+      await this.redis.quit();
+    }
+  }
+}

package/memory/index.ts

@@ -0,0 +1,22 @@
+import { BaseMemoryService } from "@/interfaces";
+import { BaseMemoryType, CreateMemoryInput } from "@/types";
+
+export abstract class BaseMemory {
+  constructor(protected readonly cacheService: BaseMemoryService) {}
+
+  abstract init(): Promise<void>;
+  abstract createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined>;
+  abstract getMemoryById(
+    id: string,
+    roomId: string
+  ): Promise<BaseMemoryType | null>;
+  abstract getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]>;
+  abstract getAllMemories(roomId: string): Promise<BaseMemoryType[]>;
+  abstract clearMemoryById(id: string, roomId: string): Promise<void>;
+  abstract clearAllMemories(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai.ntellect/core",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "",
   "main": "dist/index.js",
   "scripts": {
@@ -24,6 +24,7 @@
     "readline": "^1.3.0",
     "redis": "^4.7.0",
     "rss-parser": "^3.13.0",
+    "sinon": "^19.0.2",
     "ws": "^8.18.0",
     "zod": "^3.24.1"
   },
@@ -31,12 +32,16 @@
     "@jest/globals": "^29.7.0",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.0",
+    "@types/sinon": "^17.0.3",
     "@types/ws": "^8.5.14",
     "chai": "^4.5.0",
     "mocha": "^10.0.0",
     "ts-node": "^10.9.0",
     "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "meilisearch": "^0.37.0",
+    "redis": "^4.6.13",
+    "dotenv": "^16.4.5"
   },
   "repository": {
     "type": "git",