@ai.ntellect/core 0.7.14 → 0.8.0

package/modules/agent/generic-assistant.ts

@@ -0,0 +1,90 @@
+import { GraphFlow } from "../../graph/index";
+import {
+  AgentConfig,
+  AgentContext,
+  AgentContextSchema,
+} from "../../types/agent";
+import { BaseAgent } from "./base";
+import { GenericExecutor } from "./generic-executor";
+
+/**
+ * A generic assistant that can be configured with different roles, goals, and personalities
+ * @class Agent
+ * @example
+ * const assistant = new Agent({
+ *   role: "Email Assistant",
+ *   goal: "Help users send emails efficiently",
+ *   backstory: "I am a professional and friendly assistant who specializes in email communication",
+ *   llmConfig: { provider: "openai", model: "gpt-4" }
+ * });
+ */
+export class Agent {
+  private executor: GenericExecutor;
+  private workflow: GraphFlow<typeof AgentContextSchema>;
+
+  constructor(config: AgentConfig) {
+    const agent = new BaseAgent({
+      role: config.role,
+      goal: config.goal,
+      backstory: config.backstory,
+      tools: config.tools,
+      memory: config.memory,
+      llmConfig: config.llmConfig,
+    });
+
+    this.executor = new GenericExecutor(agent, config.tools, {
+      llmConfig: config.llmConfig,
+      verbose: config.verbose,
+    });
+
+    this.workflow = this.setupWorkflow();
+  }
+
+  private setupWorkflow(): GraphFlow<typeof AgentContextSchema> {
+    return new GraphFlow("assistant", {
+      name: "assistant",
+      schema: AgentContextSchema,
+      context: {
+        input: { raw: "" },
+        actions: [],
+        response: "",
+        executedActions: [],
+      },
+      nodes: [
+        {
+          name: "process",
+          execute: async (context) => {
+            const agentContext = context as unknown as AgentContext;
+            const decision = await this.executor.makeDecision(agentContext);
+            context.actions = decision.actions;
+            context.response = decision.response;
+          },
+          next: (context) => (context.actions.length > 0 ? ["execute"] : []),
+        },
+        {
+          name: "execute",
+          execute: async (context) => {
+            console.log(`Executing actions:`);
+            console.log(context.actions);
+
+            await this.executor.executeActions(
+              context.actions,
+              context as unknown as AgentContext
+            );
+          },
+          next: ["process"],
+        },
+      ],
+    });
+  }
+
+  public async process(input: string): Promise<AgentContext> {
+    await this.workflow.execute("process", undefined, {
+      input: { raw: input },
+      actions: [],
+      response: "",
+    });
+
+    return this.workflow.getContext() as unknown as AgentContext;
+  }
+}

package/modules/agent/generic-executor.ts

@@ -0,0 +1,259 @@
+import chalk from "chalk";
+import { z } from "zod";
+import { GraphFlow } from "../../graph/index";
+import {
+  ActionSchema,
+  AgentContext,
+  DecisionOutput,
+  ExecutorConfig,
+} from "../../types/agent";
+import { BaseAgent } from "./base";
+import { AgentExecutor } from "./base/executor";
+import { LLMFactory } from "./llm-factory";
+
+/**
+ * Generic executor that handles the interaction between the agent and LLM
+ * Uses a structured prompt format:
+ * - ROLE: The function/job the agent performs
+ * - GOAL: The specific objective to achieve
+ * - BACKSTORY: The personality and behavior traits
+ * - CONTEXT: Current knowledge and state
+ * - AVAILABLE ACTIONS: What the agent can do
+ * - INSTRUCTIONS: How to process and respond
+ * @class GenericExecutor
+ * @extends {AgentExecutor}
+ */
+export class GenericExecutor extends AgentExecutor {
+  private verbose: boolean;
+  private llm: ReturnType<typeof LLMFactory.createLLM>;
+
+  /**
+   * Creates an instance of GenericExecutor
+   * @param {BaseAgent} agent - The agent instance this executor is tied to
+   * @param {GraphFlow<any>[]} graphs - Array of available graph flows
+   * @param {ExecutorConfig} config - Configuration for the executor
+   */
+  constructor(
+    agent: BaseAgent,
+    graphs: GraphFlow<any>[],
+    config: ExecutorConfig
+  ) {
+    super(agent, graphs);
+    this.verbose = config.verbose ?? true;
+    this.llm = LLMFactory.createLLM(config.llmConfig);
+  }
+
+  /**
+   * Logs a message with a specific type if verbose mode is enabled
+   * @private
+   * @param {"info" | "success" | "warning" | "error" | "thinking"} type - The type of log message
+   * @param {string} message - The message to log
+   */
+  private log(
+    type: "info" | "success" | "warning" | "error" | "thinking",
+    message: string
+  ) {
+    if (!this.verbose) return;
+
+    const prefix = {
+      info: chalk.blue("ℹ"),
+      success: chalk.green("✓"),
+      warning: chalk.yellow("⚠"),
+      error: chalk.red("✖"),
+      thinking: chalk.magenta("🤔"),
+    }[type];
+
+    console.log(`${prefix} ${message}`);
+  }
+
+  /**
+   * Generates a string representation of the available action schemas
+   * @private
+   * @returns {string} Formatted string containing all available actions and their parameters
+   */
+  protected generateActionSchema(): string {
+    return Array.from(this.availableGraphs.values())
+      .map((graph) => {
+        const schema = graph.getSchema();
+        const schemaDescription = Object.entries(schema.shape)
+          .map(([key, value]) => {
+            const zodValue = value as z.ZodTypeAny;
+            return `    - ${key}: ${
+              zodValue.description || zodValue._def.typeName
+            }`;
+          })
+          .join("\n");
+
+        return `${graph.name}:
+  Parameters:
+${schemaDescription}
+  Available Operations:
+${graph
+  .getNodes()
+  .map((n) => `    - ${n.name}`)
+  .join("\n")}`;
+      })
+      .join("\n\n");
+  }
+
+  /**
+   * Makes a decision based on the current context using the LLM
+   * @param {AgentContext} context - The context to base the decision on
+   * @returns {Promise<DecisionOutput>} The decision output containing actions and response
+   */
+  async makeDecision(context: AgentContext): Promise<DecisionOutput> {
+    this.log(
+      "thinking",
+      chalk.dim("Analyzing context and available actions...")
+    );
+
+    const memories = await this.agent.recall(context.input.raw);
+    if (memories.length > 0) {
+      this.log("info", chalk.dim("Retrieved relevant memories:"));
+      memories.forEach((m) => this.log("info", chalk.dim(`- ${m.content}`)));
+
+      context.knowledge =
+        (context.knowledge || "") +
+        "\n" +
+        memories.map((m) => m.content).join("\n");
+    }
+
+    const systemPrompt = `
+      ## ROLE
+      ${this.agent.getRole()}
+
+      ## GOAL
+      ${this.agent.getGoal()}
+
+      ## BACKSTORY
+      ${this.agent.getBackstory()}
+
+      ## RECENT ACTIONS
+      ${context.knowledge ? `${context.knowledge}\n` : "None"}
+     
+      ## AVAILABLE ACTIONS
+      ${this.generateActionSchema()}
+
+      ## INSTRUCTIONS
+      - Analyze the user input and what you have done (if no action is needed, just return an empty array)
+      - Choose appropriate actions based on their parameters
+      - Structure parameters according to the action's schema
+      - Look at the goal and the actions you have done, if you have achieved the goal, STOP
+    `;
+
+    this.log("info", chalk.dim("Generating response..."));
+
+    const result = await this.llm.generate(
+      {
+        system: systemPrompt,
+        user: `User input: ${context.input.raw}
+        Actions you have already done: ${
+          context.executedActions
+            ?.map((a) => `\n- ${a.name} => ${JSON.stringify(a.result)}`)
+            .join("") || "None"
+        }`,
+      },
+      z.object({
+        actions: z.array(
+          z.object({
+            name: z.string(),
+            parameters: z.array(
+              z.object({
+                name: z.string(),
+                value: z.any(),
+              })
+            ),
+          })
+        ),
+        response: z.string(),
+      })
+    );
+
+    if (result.object.actions.length > 0) {
+      this.log("success", chalk.green("Decided to take actions:"));
+      result.object.actions.forEach(
+        (action: {
+          name: string;
+          parameters: Array<{ name: string; value: any }>;
+        }) => {
+          this.log("info", chalk.cyan(`Action: ${action.name}`));
+          action.parameters.forEach((param: { name: string; value: any }) => {
+            this.log(
+              "info",
+              chalk.dim(`  - ${param.name}: ${JSON.stringify(param.value)}`)
+            );
+          });
+        }
+      );
+    } else {
+      this.log("info", chalk.yellow("No actions needed"));
+    }
+
+    this.log("success", chalk.green(`Response: ${result.object.response}`));
+
+    return {
+      actions: result.object.actions as unknown as ActionSchema[],
+      response: result.object.response,
+    };
+  }
+
+  /**
+   * Executes multiple workflows with their respective inputs
+   * @protected
+   * @param {GraphFlow<any>[]} workflows - Array of workflows to execute
+   * @param {string[]} startNodes - Array of starting node names for each workflow
+   * @param {any[]} inputs - Array of inputs for each workflow
+   * @param {AgentContext} context - The context in which to execute the workflows
+   * @returns {Promise<void>}
+   */
+  protected async executeWorkflows(
+    workflows: GraphFlow<any>[],
+    startNodes: string[],
+    inputs: any[],
+    context: AgentContext
+  ): Promise<void> {
+    this.log("info", chalk.cyan("Executing workflows:"));
+
+    for (let i = 0; i < workflows.length; i++) {
+      const workflow = workflows[i];
+      const startNode = startNodes[i];
+      const input = inputs[i];
+
+      this.log(
+        "info",
+        chalk.dim(
+          `Executing workflow ${workflow.name} starting at node ${startNode}`
+        )
+      );
+      this.log(
+        "info",
+        chalk.dim(`Input parameters: ${JSON.stringify(input, null, 2)}`)
+      );
+
+      // Initialize workflow context with input
+      const workflowContext = {
+        ...workflow.getContext(),
+        ...input,
+      };
+
+      // Execute with merged context
+      const result = await workflow.execute(
+        startNode,
+        undefined,
+        workflowContext
+      );
+
+      this.log("success", chalk.green(`Workflow ${workflow.name} completed`));
+      this.log("info", chalk.dim(`Result: ${JSON.stringify(result, null, 2)}`));
+
+      if (context.executedActions) {
+        context.executedActions.push({
+          name: workflow.name,
+          result: result,
+          timestamp: new Date().toISOString(),
+          isExecuted: true,
+        });
+      }
+    }
+  }
+}

package/modules/agent/llm-factory.ts

@@ -0,0 +1,47 @@
+import { LLMConfig, PromptInput } from "@/types/agent";
+import { openai } from "@ai-sdk/openai";
+import { generateObject } from "ai";
+import { z } from "zod";
+
+/**
+ * Factory class for creating Language Model instances based on configuration
+ * @class LLMFactory
+ */
+export class LLMFactory {
+  /**
+   * Creates an LLM instance based on the provided configuration
+   * @static
+   * @param {LLMConfig} config - Configuration for the LLM
+   * @returns {Object} An object with a generate method for interacting with the LLM
+   * @throws {Error} When an unsupported provider is specified or custom provider lacks required function
+   */
+  static createLLM(config: LLMConfig) {
+    switch (config.provider) {
+      case "openai":
+        return {
+          generate: async (
+            prompt: string | PromptInput,
+            schema: z.ZodType<any>
+          ) => {
+            return generateObject({
+              model: openai(config.model),
+              temperature: config.temperature ?? 0.7,
+              maxTokens: config.maxTokens,
+              prompt: typeof prompt === "string" ? prompt : prompt.user,
+              system: typeof prompt === "string" ? undefined : prompt.system,
+              schema,
+            });
+          },
+        };
+      case "custom":
+        if (!config.customCall) {
+          throw new Error("Custom LLM provider requires a customCall function");
+        }
+        return {
+          generate: config.customCall,
+        };
+      default:
+        throw new Error(`Unsupported LLM provider: ${config.provider}`);
+    }
+  }
+}

package/modules/agent/prompt-builder.ts

@@ -0,0 +1,78 @@
+import { AgentContext, PromptSection } from "../../types/agent";
+
+/**
+ * Builder class for creating structured prompts with multiple sections
+ * @class PromptBuilder
+ */
+export class PromptBuilder {
+  private sections: PromptSection[] = [];
+  private formatFn?: (
+    sections: PromptSection[],
+    context: AgentContext
+  ) => string | Promise<string>;
+
+  /**
+   * Adds a new section to the prompt
+   * @param {string} title - The title of the section
+   * @param {string | ((context: AgentContext) => string | Promise<string>)} content - The content or a function to generate content
+   * @returns {this} The builder instance for method chaining
+   */
+  addSection(
+    title: string,
+    content: string | ((context: AgentContext) => string | Promise<string>)
+  ): this {
+    this.sections.push({ title, content });
+    return this;
+  }
+
+  /**
+   * Sets a custom formatter function for the final prompt
+   * @param {(sections: PromptSection[], context: AgentContext) => string | Promise<string>} formatter - The formatter function
+   * @returns {this} The builder instance for method chaining
+   */
+  setFormatter(
+    formatter: (
+      sections: PromptSection[],
+      context: AgentContext
+    ) => string | Promise<string>
+  ): this {
+    this.formatFn = formatter;
+    return this;
+  }
+
+  /**
+   * Builds the final prompt by resolving all sections and applying formatting
+   * @param {AgentContext} context - The context to use when resolving dynamic content
+   * @returns {Promise<string>} The formatted prompt string
+   */
+  async build(context: AgentContext): Promise<string> {
+    const resolvedSections = await Promise.all(
+      this.sections.map(async (section) => ({
+        title: section.title,
+        content:
+          typeof section.content === "function"
+            ? await section.content(context)
+            : section.content,
+      }))
+    );
+
+    if (this.formatFn) {
+      return this.formatFn(resolvedSections, context);
+    }
+
+    return resolvedSections
+      .map((section) => `## ${section.title}\n${section.content}`)
+      .join("\n\n");
+  }
+}
+
+/**
+ * Default formatter function that formats sections with markdown-style headers
+ * @param {PromptSection[]} sections - The sections to format
+ * @returns {string} The formatted prompt string
+ */
+export const defaultFormatter = (sections: PromptSection[]): string => {
+  return sections
+    .map((section) => `## ${section.title}\n${section.content}`)
+    .join("\n\n");
+};

package/modules/memory/adapters/in-memory/index.ts

@@ -51,7 +51,7 @@ export class InMemoryAdapter implements IMemoryAdapter {
 
     // Check if memory already exists
     const memories = this.storage.get(input.roomId) || [];
-    const existingMemory = memories.find((m) => m.data === input.data);
+    const existingMemory = memories.find((m) => m.content === input.content);
     if (existingMemory) {
       return existingMemory;
     }
@@ -59,7 +59,8 @@ export class InMemoryAdapter implements IMemoryAdapter {
     // Create new memory
     const memory: BaseMemoryType = {
       id: input.id || crypto.randomUUID(),
-      data: input.data,
+      content: input.content,
+      metadata: input.metadata,
       embedding: input.embedding,
       roomId: input.roomId,
       createdAt: new Date(),
@@ -97,7 +98,7 @@ export class InMemoryAdapter implements IMemoryAdapter {
     options: { roomId: string; limit?: number }
   ): Promise<BaseMemoryType[]> {
     const memories = this.storage.get(options.roomId) || [];
-    const filtered = memories.filter((m) => m.data.includes(query));
+    const filtered = memories.filter((m) => m.content.includes(query));
     return filtered.slice(0, options.limit || filtered.length);
   }
 

package/modules/memory/adapters/meilisearch/index.ts

@@ -204,7 +204,7 @@ export class MeilisearchAdapter implements IMemoryAdapter {
     await this.initializeStorage(input.roomId);
 
     // Check if the memory already exists
-    const existingMemory = await this.search(input.data, input.roomId, {
+    const existingMemory = await this.search(input.content, input.roomId, {
       limit: 1,
     });
     if (existingMemory.length > 0) {
@@ -214,7 +214,8 @@ export class MeilisearchAdapter implements IMemoryAdapter {
     // If not found, create new memory
     const memory: BaseMemoryType = {
       id: input.id || crypto.randomUUID(),
-      data: input.data,
+      content: input.content,
+      metadata: input.metadata,
       embedding: input.embedding,
       roomId: input.roomId,
       createdAt: new Date(),
@@ -241,7 +242,8 @@ export class MeilisearchAdapter implements IMemoryAdapter {
       return result
         ? {
             id: result.id,
-            data: result.data,
+            content: result.content,
+            metadata: result.metadata,
             embedding: result.embedding,
             roomId: result.roomId,
             createdAt: result.createdAt,
@@ -271,7 +273,8 @@ export class MeilisearchAdapter implements IMemoryAdapter {
       .filter((result) => result.document.roomId === options.roomId)
       .map((result) => ({
         id: result.document.id,
-        data: result.document.data,
+        content: result.document.content,
+        metadata: result.document.metadata,
         embedding: result.document.embedding,
         roomId: result.document.roomId,
         createdAt: result.document.createdAt,

package/modules/memory/adapters/redis/index.ts

@@ -58,7 +58,8 @@ export class RedisAdapter implements IMemoryAdapter {
   ): Promise<BaseMemoryType | undefined> {
     const memory: BaseMemoryType = {
       id: input.id || crypto.randomUUID(),
-      data: input.data,
+      content: input.content,
+      metadata: input.metadata,
       embedding: input.embedding,
       roomId: input.roomId,
       createdAt: new Date(),