@ai.ntellect/core 0.8.3 → 1.1.0

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/{modules/agent → agent}/base/executor.ts

@@ -1,10 +1,10 @@
 import { BaseAgent } from ".";
-import { GraphFlow } from "../../../graph";
+import { GraphFlow } from "../../execution";
 import {
   ActionSchema,
   AgentContext,
   DecisionOutput,
-} from "../../../types/agent";
+} from "../../types/agent";
 
 /**
  * Abstract base class for agent executors that handle action execution
@@ -69,16 +69,19 @@ export abstract class AgentExecutor {
   /**
    * Prepares the input parameters for an action
    * @private
-   * @param {Array<{name: string, value: any}>} parameters - Array of parameter objects
+   * @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 }>
+    parameters: Array<{ name: string; value: any }> | Record<string, any>
   ): Record<string, any> {
-    return parameters.reduce((acc, param) => {
-      acc[param.name] = param.value;
-      return acc;
-    }, {} as 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>;
   }
 
   /**

package/{modules/agent → agent}/base/index.ts

@@ -1,6 +1,6 @@
 import { AgentConfig } from "@/types/agent";
-import { BaseMemoryType } from "../../../types";
-import { Memory } from "../../memory";
+import { BaseMemoryType } from "../../types";
+import { Memory } from "../../modules/memory";
 
 /**
  * Base agent class that handles role, goal, and personality management
@@ -35,18 +35,6 @@ export class BaseAgent {
       });
     }
 
-    // Execute tools if available
-    if (this.config.tools) {
-      for (const tool of this.config.tools) {
-        try {
-          const result = await tool.execute(context, inputs);
-          context = { ...context, ...result };
-        } catch (error) {
-          console.error(`Tool execution failed:`, error);
-        }
-      }
-    }
-
     return context;
   }
 

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;
+  }
+}

package/agent/entity-resolver/explore-strategy.ts

@@ -0,0 +1,82 @@
+import * as path from "path";
+import * as fs from "fs";
+import { ScoredCandidate, Entity } from "./types";
+import { EntityIndex } from "./entity-index";
+
+export type ExploreAction = {
+  type: "directory_lister";
+  path: string;
+  reason: string;
+};
+
+export class ExploreStrategy {
+  constructor(private index: EntityIndex) {}
+
+  plan(candidates: ScoredCandidate[], cwd: string): ExploreAction[] {
+    const actions: ExploreAction[] = [];
+
+    if (candidates.length === 0) {
+      actions.push({ type: "directory_lister", path: cwd, reason: "no candidates, list cwd" });
+      return actions;
+    }
+
+    const topDir = candidates.find(c => c.entity.category === "dir");
+    const topFile = candidates.find(c => c.entity.category === "file");
+
+    if (topDir && topFile) {
+      if (topDir.breakdown.total > topFile.breakdown.total) {
+        actions.push({
+          type: "directory_lister",
+          path: cwd,
+          reason: `top candidate is dir "${topDir.entity.filename}", list cwd to confirm`,
+        });
+      } else {
+        const dirPath = path.dirname(topFile.entity.path);
+        if (dirPath !== cwd && fs.existsSync(dirPath)) {
+          actions.push({
+            type: "directory_lister",
+            path: dirPath,
+            reason: `top candidate is file "${topFile.entity.filename}", list its parent`,
+          });
+        } else {
+          actions.push({
+            type: "directory_lister",
+            path: cwd,
+            reason: "list cwd to disambiguate",
+          });
+        }
+      }
+      return actions;
+    }
+
+    if (topDir) {
+      actions.push({
+        type: "directory_lister",
+        path: topDir.entity.path,
+        reason: `explore dir candidate "${topDir.entity.filename}"`,
+      });
+      return actions;
+    }
+
+    if (topFile) {
+      const dirPath = path.dirname(topFile.entity.path);
+      if (dirPath !== cwd && fs.existsSync(dirPath)) {
+        actions.push({
+          type: "directory_lister",
+          path: dirPath,
+          reason: `explore parent of file candidate "${topFile.entity.filename}"`,
+        });
+      } else {
+        actions.push({
+          type: "directory_lister",
+          path: cwd,
+          reason: `list cwd for file candidate "${topFile.entity.filename}"`,
+        });
+      }
+      return actions;
+    }
+
+    actions.push({ type: "directory_lister", path: cwd, reason: "fallback: list cwd" });
+    return actions;
+  }
+}

package/agent/entity-resolver/index.ts

@@ -0,0 +1,22 @@
+export { EntityIndex } from "./entity-index";
+export type { TargetResolution, LookupMode } from "./entity-index";
+export { scoreEntities } from "./scorer";
+export { computeConfidence, confidenceImproved } from "./confidence";
+export { EntityResolver, findEntityInInput } from "./resolver";
+export { ExploreStrategy, type ExploreAction } from "./explore-strategy";
+
+export type {
+  Entity,
+  EntityCategory,
+  ScoredCandidate,
+  ScoreBreakdown,
+  Confidence,
+  ConfidenceLevel,
+  EntityReference,
+  EntityResolution,
+  ExplorationBudget,
+  PendingIntent,
+  ConversationState,
+  ResolutionTraceEntry,
+  ResolverContext,
+} from "./types";