@ai.ntellect/core 1.0.0 → 1.1.1

package/agent/agent.ts

@@ -0,0 +1,183 @@
+import { Checkpoint, CheckpointConfig } from "@/types";
+import { GraphFlow } from "../execution/index";
+import { ICheckpointAdapter } from "../interfaces";
+import {
+  AgentConfig,
+  AgentContext,
+  AgentContextSchema,
+} from "../types/agent";
+import { BaseAgent } from "./base";
+import { GenericExecutor } from "./generic-executor";
+import { AgentLogger } from "./tools/logger";
+import { buildAgentWorkflow } from "./agent-workflow";
+import { EntityIndex } from "./entity-resolver/entity-index";
+import { EntityResolver } from "./entity-resolver/resolver";
+import { ExploreStrategy } from "./entity-resolver/explore-strategy";
+
+/**
+ * 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" }
+ *   tools: []
+ * });
+ */
+export class Agent {
+  private executor: GenericExecutor;
+  private workflow: GraphFlow<typeof AgentContextSchema>;
+  public logger: AgentLogger;
+
+  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,
+    });
+
+    const maxIterations = config.maxIterations || 5;
+    this.logger = new AgentLogger(config.verbose ?? true);
+
+    this.executor = new GenericExecutor(agent, config.tools, {
+      llmConfig: config.llmConfig,
+      verbose: config.verbose,
+    }, this.logger, {
+      dynamicGoal: config.dynamicGoal,
+      dynamicGoalPrompt: config.dynamicGoalPrompt,
+      dynamicNext: config.dynamicNext,
+      dynamicNextPrompt: config.dynamicNextPrompt,
+      enableSchedule: config.enableSchedule,
+      agenda: config.agenda,
+    });
+    this.executor.setLogger(this.logger);
+
+    const entityIndex = new EntityIndex(config.entityStore);
+    if (config.entityStore) {
+      entityIndex.hydrate().catch((err: any) =>
+        this.logger.log("warn", "agent", `Entity store hydration failed: ${err}`)
+      );
+    }
+    const entityResolver = new EntityResolver(entityIndex);
+    const exploreStrategy = new ExploreStrategy(entityIndex);
+    this.executor.setEntityIndex(entityIndex);
+
+    this.workflow = buildAgentWorkflow({
+      executor: this.executor,
+      baseAgent: agent,
+      logger: this.logger,
+      maxIterations,
+      enableClone: config.enableClone ?? false,
+      entityResolver: {
+        resolve: (ctx: any) => entityResolver.resolve(ctx),
+        getIndex: () => entityIndex,
+      },
+      exploreStrategy: {
+        plan: (candidates: any[], cwd: string) => exploreStrategy.plan(candidates, cwd),
+      },
+    });
+  }
+
+  /**
+   * Processes an input string through the agent's workflow
+   * @param {string} input - The input string to process
+   * @returns {Promise<AgentContext>} The resulting context after processing
+   */
+  public async process(input: string): Promise<AgentContext> {
+    await this.workflow.execute("defineGoal", {
+      input: { raw: input },
+      cwd: process.cwd(),
+      actions: [],
+      response: "",
+      scratchpad: [],
+      memories: [],
+    });
+
+    return this.workflow.getContext() as unknown as AgentContext;
+  }
+
+  public getWorkflow(): GraphFlow<typeof AgentContextSchema> {
+    return this.workflow;
+  }
+
+  public async processWithCheckpoint(
+    input: string,
+    adapter: ICheckpointAdapter,
+    config: CheckpointConfig = {}
+  ): Promise<{ context: AgentContext; checkpointId: string }> {
+    const result = await this.workflow.executeWithCheckpoint(
+      "defineGoal",
+      adapter,
+      {
+        ...config,
+        breakpoints: config.breakpoints || ["execute"],
+        initialContext: {
+          input: { raw: input },
+          cwd: process.cwd(),
+          scratchpad: [],
+          memories: [],
+          entityState: config.initialContext?.entityState || {
+            currentTarget: undefined,
+            lastEntityType: null,
+            pendingResolutions: [],
+            resolutionTrace: [],
+            explored: false,
+          },
+          conversationState: config.initialContext?.conversationState || {
+            currentGoal: "",
+            currentTarget: null,
+            lastResolvedEntity: null,
+            lastResolvedType: null,
+            pendingTask: null,
+            turnCount: 0,
+            pendingIntent: null,
+          },
+          explorationBudget: config.initialContext?.explorationBudget || {
+            maxSteps: 12,
+            maxExplorations: 2,
+            maxToolCalls: 8,
+            stepsUsed: 0,
+            explorationsUsed: 0,
+            toolCallsUsed: 0,
+          },
+          ...config.initialContext,
+        },
+      }
+    );
+    return {
+      context: result.context as unknown as AgentContext,
+      checkpointId: result.checkpointId,
+    };
+  }
+
+  public async resumeFromCheckpoint(
+    checkpointId: string,
+    adapter: ICheckpointAdapter,
+    contextModifications?: Record<string, any>
+  ): Promise<AgentContext> {
+    const result = await this.workflow.resumeFromCheckpoint(
+      checkpointId,
+      adapter,
+      contextModifications
+    );
+    return result as unknown as AgentContext;
+  }
+
+  public async listCheckpoints(
+    adapter: ICheckpointAdapter
+  ): Promise<Checkpoint<typeof AgentContextSchema>[]> {
+    return this.workflow.listCheckpoints(adapter);
+  }
+
+  public async getCheckpointHistory(
+    runId: string,
+    adapter: ICheckpointAdapter
+  ): Promise<Checkpoint<typeof AgentContextSchema>[]> {
+    return this.workflow.getCheckpointHistory(runId, adapter);
+  }
+}

package/agent/base/executor.ts

@@ -0,0 +1,103 @@
+import { BaseAgent } from ".";
+import { GraphFlow } from "../../execution";
+import {
+  ActionSchema,
+  AgentContext,
+  DecisionOutput,
+} from "../../types/agent";
+
+/**
+ * Abstract base class for agent executors that handle action execution
+ * @abstract
+ * @class AgentExecutor
+ */
+export abstract class AgentExecutor {
+  protected agent: BaseAgent;
+  protected availableGraphs: Map<string, GraphFlow<any>>;
+
+  /**
+   * Creates an instance of AgentExecutor
+   * @param {BaseAgent} agent - The agent instance this executor is tied to
+   * @param {GraphFlow<any>[]} graphs - Array of available graph flows that can be executed
+   */
+  constructor(agent: BaseAgent, graphs: GraphFlow<any>[]) {
+    this.agent = agent;
+    this.availableGraphs = new Map(graphs.map((g) => [g.name, g]));
+  }
+
+  /**
+   * Makes a decision based on the current context
+   * @abstract
+   * @param {any} context - The context to base the decision on
+   * @returns {Promise<DecisionOutput>} The decision output containing actions and response
+   */
+  abstract makeDecision(context: any): Promise<DecisionOutput>;
+
+  /**
+   * Executes a list of actions in the given context
+   * @param {ActionSchema[]} actions - Array of actions to execute
+   * @param {AgentContext} context - The context in which to execute the actions
+   * @returns {Promise<void>}
+   */
+  async executeActions(
+    actions: ActionSchema[],
+    context: AgentContext
+  ): Promise<void> {
+    const workflowsToExecute: GraphFlow<any>[] = [];
+    const startNodes: string[] = [];
+    const inputs: any[] = [];
+
+    for (const action of actions) {
+      const workflow = this.availableGraphs.get(action.name);
+      if (!workflow) continue;
+
+      workflowsToExecute.push(workflow);
+      startNodes.push(workflow.getNodes()[0].name);
+      inputs.push(this.prepareActionInputs(action.parameters));
+    }
+
+    if (workflowsToExecute.length > 0) {
+      await this.executeWorkflows(
+        workflowsToExecute,
+        startNodes,
+        inputs,
+        context
+      );
+    }
+  }
+
+  /**
+   * Prepares the input parameters for an action
+   * @private
+   * @param {Array<{name: string, value: any}> | Record<string, any>} parameters - Array of parameter objects or direct object
+   * @returns {Record<string, any>} Object with parameter names as keys and their values
+   */
+  private prepareActionInputs(
+    parameters: Array<{ name: string; value: any }> | Record<string, any>
+  ): Record<string, any> {
+    if (Array.isArray(parameters)) {
+      return parameters.reduce((acc, param) => {
+        acc[param.name] = param.value;
+        return acc;
+      }, {} as Record<string, any>);
+    }
+    return parameters as Record<string, any>;
+  }
+
+  /**
+   * Executes multiple workflows with their respective inputs
+   * @protected
+   * @abstract
+   * @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 abstract executeWorkflows(
+    workflows: GraphFlow<any>[],
+    startNodes: string[],
+    inputs: any[],
+    context: AgentContext
+  ): Promise<void>;
+}

package/agent/base/index.ts

@@ -0,0 +1,87 @@
+import { AgentConfig } from "@/types/agent";
+import { BaseMemoryType } from "../../types";
+import { Memory } from "../../modules/memory";
+
+/**
+ * Base agent class that handles role, goal, and personality management
+ * @class BaseAgent
+ */
+export class BaseAgent {
+  private config: AgentConfig;
+  private memory?: Memory;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.memory = config.memory;
+  }
+
+  async execute(context: any, inputs?: any): Promise<any> {
+    // Log execution if verbose
+    if (this.config.verbose) {
+      console.log(`Agent ${this.config.role} executing...`);
+      console.log("Context:", context);
+      console.log("Inputs:", inputs);
+    }
+
+    // Store context in memory if available
+    if (this.memory) {
+      await this.storeInMemory({
+        type: "execution",
+        content: JSON.stringify({ context, inputs }),
+        metadata: {
+          role: this.config.role,
+          timestamp: new Date().toISOString(),
+        },
+      });
+    }
+
+    return context;
+  }
+
+  private async storeInMemory(data: {
+    type: string;
+    content: string;
+    metadata?: Record<string, any>;
+  }): Promise<BaseMemoryType | undefined> {
+    if (!this.memory) return;
+
+    return this.memory.createMemory({
+      content: data.content,
+      metadata: data.metadata,
+      roomId: "default",
+    });
+  }
+
+  public async recall(query: string): Promise<BaseMemoryType[]> {
+    if (!this.memory) return [];
+
+    return this.memory.getMemoryByIndex(query, {
+      roomId: "default",
+      limit: 10,
+    });
+  }
+
+  /**
+   * Get the agent's role - what function/job it performs
+   * @returns {string} The agent's role
+   */
+  public getRole(): string {
+    return this.config.role;
+  }
+
+  /**
+   * Get the agent's goal - what it tries to achieve
+   * @returns {string} The agent's goal
+   */
+  public getGoal(): string {
+    return this.config.goal;
+  }
+
+  /**
+   * Get the agent's backstory - its personality and behavioral traits
+   * @returns {string} The agent's backstory
+   */
+  public getBackstory(): string {
+    return this.config.backstory;
+  }
+}

package/agent/entity-resolver/confidence.ts

@@ -0,0 +1,54 @@
+import { ScoredCandidate, Confidence } from "./types";
+
+const HIGH_GAP = 0.3;
+const MEDIUM_GAP = 0.15;
+
+export function computeConfidence(candidates: ScoredCandidate[]): Confidence {
+  if (candidates.length === 0) {
+    return { level: "low", score: 0, gap: 0, reason: "no candidates found" };
+  }
+
+  if (candidates.length === 1) {
+    const score = candidates[0].breakdown.total;
+    if (score >= 0.7) {
+      return { level: "high", score, gap: 1, reason: "single candidate with high score" };
+    }
+    return { level: "medium", score, gap: 1, reason: "single candidate but low score" };
+  }
+
+  const top = candidates[0].breakdown.total;
+  const second = candidates[1].breakdown.total;
+  const gap = top - second;
+
+  if (gap >= HIGH_GAP) {
+    return {
+      level: "high",
+      score: top,
+      gap,
+      reason: `gap ${gap.toFixed(2)} >= ${HIGH_GAP}, clear winner: ${candidates[0].entity.filename}`,
+    };
+  }
+
+  if (gap >= MEDIUM_GAP) {
+    return {
+      level: "medium",
+      score: top,
+      gap,
+      reason: `gap ${gap.toFixed(2)} >= ${MEDIUM_GAP}, ambiguous: ${candidates[0].entity.filename} vs ${candidates[1].entity.filename}`,
+    };
+  }
+
+  return {
+    level: "low",
+    score: top,
+    gap,
+    reason: `gap ${gap.toFixed(2)} < ${MEDIUM_GAP}, too close: ${candidates.map(c => c.entity.filename).join(", ")}`,
+  };
+}
+
+export function confidenceImproved(
+  before: Confidence,
+  after: Confidence
+): boolean {
+  return after.score > before.score;
+}

package/agent/entity-resolver/entity-index.ts

@@ -0,0 +1,241 @@
+import * as path from "path";
+import * as fs from "fs";
+import { Entity, EntityCategory } from "./types";
+
+export interface IEntityStore {
+  upsertMany(entities: Entity[]): Promise<void>;
+  loadAll(scope?: string): Promise<Entity[]>;
+  recordResolution(entityId: string, query: string, confidence: number): Promise<void>;
+  clear(scope?: string): Promise<void>;
+}
+
+function computeStem(filename: string): { stem: string; extension: string | null } {
+  const dotIdx = filename.lastIndexOf(".");
+  if (dotIdx <= 0) return { stem: filename, extension: null };
+  return { stem: filename.slice(0, dotIdx), extension: filename.slice(dotIdx) };
+}
+
+function computeTokens(stem: string): string[] {
+  const parts = stem.split(/[-._\s]+/).filter(Boolean);
+  return [...new Set(parts.map(p => p.toLowerCase()))];
+}
+
+function determineCategory(
+  name: string,
+  isDir: boolean,
+  _entries?: { name: string; type: string }[]
+): EntityCategory {
+  if (isDir) return "dir";
+  const ext = name.includes(".") ? name.slice(name.lastIndexOf(".")).toLowerCase() : "";
+  if (ext === ".test.ts" || ext === ".spec.ts" || name.includes(".test.") || name.includes(".spec."))
+    return "test";
+  return "file";
+}
+
+export type TargetResolution = {
+  target: string;
+  resolvedEntity: Entity | null;
+  path: string | null;
+  entityId: string | null;
+};
+
+export type LookupMode = "exact" | "fuzzy";
+
+export class EntityIndex {
+  private entities = new Map<string, Entity[]>();
+  private byId = new Map<string, Entity>();
+  private allEntities: Entity[] = [];
+
+  constructor(private store?: IEntityStore) {}
+
+  async hydrate(scope?: string): Promise<void> {
+    if (!this.store) return;
+    const stored = await this.store.loadAll(scope);
+    for (const entity of stored) {
+      if (!this.allEntities.some(e => e.id === entity.id)) {
+        this.addEntity(entity);
+      }
+    }
+  }
+
+  private addEntity(entity: Entity): void {
+    const dir = path.dirname(entity.path);
+    if (!this.entities.has(dir)) this.entities.set(dir, []);
+    this.entities.get(dir)!.push(entity);
+
+    this.byId.set(entity.id, entity);
+    this.allEntities.push(entity);
+  }
+
+  ingestDirectory(dirPath: string, entries: { name: string; type: string }[]): void {
+    const absDir = path.resolve(dirPath);
+    const newEntities: Entity[] = [];
+    for (const entry of entries) {
+      const isDir = entry.type === "directory";
+      const fullPath = path.join(absDir, entry.name);
+      const { stem, extension } = computeStem(entry.name);
+      const id = path.relative(process.cwd(), fullPath);
+
+      if (this.allEntities.some(e => e.id === id)) continue;
+
+      const entity: Entity = {
+        id,
+        category: determineCategory(entry.name, isDir),
+        filename: entry.name,
+        stem,
+        extension,
+        tokens: computeTokens(stem),
+        path: fullPath,
+      };
+      this.addEntity(entity);
+      newEntities.push(entity);
+    }
+    if (newEntities.length > 0 && this.store) {
+      this.store.upsertMany(newEntities).catch(() => {});
+    }
+  }
+
+  ingestFile(filePath: string): void {
+    const absPath = path.resolve(filePath);
+    const name = path.basename(absPath);
+    const { stem, extension } = computeStem(name);
+    const isDir = fs.existsSync(absPath) && fs.statSync(absPath).isDirectory();
+    const id = path.relative(process.cwd(), absPath);
+
+    if (this.allEntities.some(e => e.id === id)) return;
+
+    const entity: Entity = {
+      id,
+      category: determineCategory(name, isDir),
+      filename: name,
+      stem,
+      extension,
+      tokens: computeTokens(stem),
+      path: absPath,
+    };
+    this.addEntity(entity);
+    if (this.store) {
+      this.store.upsertMany([entity]).catch(() => {});
+    }
+  }
+
+  lookup(query: string, options: { mode?: LookupMode } = {}): Entity[] {
+    const lower = query.toLowerCase();
+    const mode = options.mode ?? "fuzzy";
+    const results = new Map<string, Entity>();
+
+    for (const entity of this.allEntities) {
+      if (entity.filename.toLowerCase() === lower) {
+        results.set(entity.id, entity);
+        if (mode === "exact") break;
+        continue;
+      }
+      if (mode === "exact") continue;
+      if (entity.stem.toLowerCase() === lower) {
+        results.set(entity.id, entity);
+        continue;
+      }
+      for (const token of entity.tokens) {
+        if (token === lower || token.startsWith(lower) || lower.startsWith(token)) {
+          results.set(entity.id, entity);
+          break;
+        }
+      }
+    }
+    return Array.from(results.values());
+  }
+
+  resolveByTarget(target: string): Entity | null {
+    const lower = target.toLowerCase();
+    const exact = this.allEntities.find(e => e.filename.toLowerCase() === lower);
+    if (exact) return exact;
+
+    const stemMatch = this.allEntities.find(e => e.stem.toLowerCase() === lower);
+    if (stemMatch) return stemMatch;
+
+    const tokenMatch = this.allEntities.find(e => e.tokens.some(t => t === lower));
+    if (tokenMatch) return tokenMatch;
+
+    const anyMatch = this.allEntities.find(e =>
+      e.filename.toLowerCase().includes(lower) ||
+      e.stem.toLowerCase().includes(lower) ||
+      e.tokens.some(t => t.includes(lower) || lower.includes(t))
+    );
+    return anyMatch || null;
+  }
+
+  resolve(target: string, _toolName?: string): TargetResolution {
+    const clean = target.trim();
+
+    if (!clean) {
+      return { target: clean, resolvedEntity: null, path: null, entityId: null };
+    }
+
+    const resolved = this.resolveByTarget(clean);
+
+    if (resolved) {
+      return {
+        target: clean,
+        resolvedEntity: resolved,
+        path: resolved.path,
+        entityId: resolved.id,
+      };
+    }
+
+    return {
+      target: clean,
+      resolvedEntity: null,
+      path: clean,
+      entityId: null,
+    };
+  }
+
+  resolveToolParams(
+    params: Record<string, any>,
+    toolName: string
+  ): Record<string, any> {
+    const result = { ...params };
+
+    if (result.target) {
+      const resolution = this.resolve(result.target, toolName);
+      result.entityId = resolution.entityId;
+      if (resolution.path) {
+        result.path = resolution.path;
+      }
+      result._entityRef = result.target;
+      delete result.target;
+    }
+
+    if (!result.path && result.entityId) {
+      const entity = this.getById(result.entityId);
+      if (entity) {
+        result.path = entity.path;
+      }
+    }
+
+    return result;
+  }
+
+  getByDir(dirPath: string): Entity[] {
+    const absDir = path.resolve(dirPath);
+    return this.entities.get(absDir) || [];
+  }
+
+  getAll(): Entity[] {
+    return [...this.allEntities];
+  }
+
+  getById(id: string): Entity | undefined {
+    return this.byId.get(id) || this.allEntities.find(e => e.id === id);
+  }
+
+  clear(): void {
+    this.entities.clear();
+    this.byId.clear();
+    this.allEntities = [];
+  }
+
+  size(): number {
+    return this.allEntities.length;
+  }
+}