@ai.ntellect/core 1.0.0 → 1.1.0

package/types/agent.ts

@@ -0,0 +1,296 @@
+import { GraphFlow } from "@/execution";
+import { z } from "zod";
+
+/**
+ * Represents an action that has been executed by the agent
+ * @interface ExecutedAction
+ * @property {string} name - The name of the executed action
+ * @property {boolean} isExecuted - Whether the action was successfully executed
+ * @property {string | null} [error] - Optional error message if the action failed
+ * @property {any} result - The result of the action execution
+ * @property {string} timestamp - When the action was executed
+ */
+export type ExecutedAction = {
+  name: string;
+  parameters?: Record<string, any>;
+  isExecuted: boolean;
+  error?: string | null;
+  result: any;
+  timestamp: string;
+};
+
+export type ChatMessage = {
+  role: "user" | "assistant";
+  content: string;
+};
+
+export type ScratchpadEntry = {
+  turn: number;
+  thought: string;
+  action: string;
+  observation: string;
+  timestamp: string;
+};
+
+/**
+ * Represents the context in which an agent operates
+ * @interface AgentContext
+ * @property {Object} input - The input provided to the agent
+ * @property {string} input.raw - The raw input text
+ * @property {number[]} [input.embedding] - Optional vector embedding of the input
+ * @property {ActionSchema[]} actions - List of actions available to the agent
+ * @property {string} response - The agent's response
+ * @property {string} [knowledge] - Optional knowledge base or context
+ * @property {ExecutedAction[]} executedActions - History of executed actions
+ * @property {number} [iteration] - Current iteration count (reset per run)
+ * @property {boolean} [progressed] - Whether progress was made in this iteration
+ * @property {ChatMessage[]} [messages] - Conversation history
+ * @property {ScratchpadEntry[]} scratchpad - Structured journal of thoughts
+ * @property {BaseMemoryType[]} memories - Retrieved episodic memories
+ */
+export type AgentContext = {
+  input: {
+    raw: string;
+    embedding?: number[];
+  };
+  actions: ActionSchema[];
+  response: string;
+  knowledge?: string;
+  executedActions: ExecutedAction[];
+  iteration?: number;
+  progressed?: boolean;
+  messages?: ChatMessage[];
+  toolResults?: Record<string, any>;
+  scratchpad?: ScratchpadEntry[];
+  memories?: any[];
+  entityState?: {
+    currentTarget?: string;
+    lastEntityType?: string | null;
+    pendingResolutions?: any[];
+    resolutionTrace?: any[];
+    explored?: boolean;
+    handles?: Record<string, { id: string; label: string; path: string; category: string }>;
+  };
+  conversationState?: {
+    currentGoal: string;
+    currentTarget: string | null;
+    lastResolvedEntity: string | null;
+    lastResolvedType: string | null;
+    pendingTask: string | null;
+    turnCount: number;
+    pendingIntent: { action: string | null; unresolvedEntity: string | null; originalInput: string; turn: number; failed: boolean } | null;
+  };
+  explorationBudget?: {
+    maxSteps: number;
+    maxExplorations: number;
+    maxToolCalls: number;
+    stepsUsed: number;
+    explorationsUsed: number;
+    toolCallsUsed: number;
+  };
+};
+
+export const AgentContextSchema = z.object({
+  input: z.object({
+    raw: z.string(),
+    embedding: z.array(z.number()).optional(),
+  }),
+  cwd: z.string().optional(),
+  actions: z.array(
+    z.object({
+      name: z.string(),
+      parameters: z.array(
+        z.object({
+          name: z.string(),
+          value: z.any(),
+        })
+      ),
+      isExecuted: z.boolean().optional(),
+      result: z.any().optional(),
+    })
+  ),
+  knowledge: z.string().optional(),
+  response: z.string(),
+  executedActions: z
+    .array(
+      z.object({
+        name: z.string(),
+        result: z.any(),
+        timestamp: z.string(),
+      })
+    )
+    .optional(),
+  iteration: z.number().optional(),
+  progressed: z.boolean().optional(),
+  messages: z
+    .array(
+      z.object({
+        role: z.enum(["user", "assistant"]),
+        content: z.string(),
+      })
+    )
+    .optional(),
+  toolResults: z.record(z.string(), z.unknown()).optional(),
+  scratchpad: z.array(z.object({
+    turn: z.number(),
+    thought: z.string(),
+    action: z.string(),
+    observation: z.string(),
+    timestamp: z.string(),
+  })).optional().default([]),
+  memories: z.array(z.any()).optional().default([]),
+  entityState: z.object({
+    currentTarget: z.string().optional(),
+    lastEntityType: z.string().nullable().optional(),
+    pendingResolutions: z.array(z.any()).optional(),
+    resolutionTrace: z.array(z.any()).optional(),
+    explored: z.boolean().optional(),
+    handles: z.record(z.string(), z.object({ id: z.string(), label: z.string(), path: z.string(), category: z.string() })).optional(),
+  }).optional(),
+  conversationState: z.object({
+    currentGoal: z.string(),
+    currentTarget: z.string().nullable(),
+    lastResolvedEntity: z.string().nullable(),
+    lastResolvedType: z.string().nullable(),
+    pendingTask: z.string().nullable(),
+    turnCount: z.number(),
+    pendingIntent: z.object({
+      action: z.string().nullable(),
+      unresolvedEntity: z.string().nullable(),
+      originalInput: z.string(),
+      turn: z.number(),
+      failed: z.boolean(),
+    }).nullable(),
+  }).optional(),
+  explorationBudget: z.object({
+    maxSteps: z.number(),
+    maxExplorations: z.number(),
+    maxToolCalls: z.number(),
+    stepsUsed: z.number(),
+    explorationsUsed: z.number(),
+    toolCallsUsed: z.number(),
+  }).optional(),
+});
+
+/**
+ * Represents a section of the prompt with a title and content
+ * @interface PromptSection
+ * @property {string} title - The title of the prompt section
+ * @property {string | ((context: AgentContext) => string | Promise<string>)} content - The content or a function to generate content
+ */
+export type PromptSection = {
+  title: string;
+  content: string | ((context: AgentContext) => string | Promise<string>);
+};
+
+/**
+ * Supported LLM providers
+ */
+export type LLMProvider = "openai" | "anthropic" | "ollama" | "groq" | "openrouter" | "google" | "custom";
+
+/**
+ * Supported LLM models
+ */
+export type LLMModel = "gpt-4" | "gpt-3.5-turbo" | "claude-2" | string;
+
+export type ExecutorConfig = {
+  llmConfig: LLMConfig;
+  verbose?: boolean;
+};
+
+/**
+ * Configuration for the Agent
+ * @type AssistantConfig
+ * @extends {Omit<ExecutorConfig, "verbose">}
+ * @property {string} role - The function/job of the assistant (e.g., "Email Assistant")
+ * @property {string} goal - The specific objective the assistant tries to achieve
+ * @property {string} backstory - The personality and behavioral traits of the assistant
+ * @property {any[]} [tools] - Optional tools the assistant can use
+ * @property {any} [memory] - Optional memory system
+ * @property {boolean} [verbose] - Whether to log detailed information
+ */
+export type AgentConfig = {
+  role: string;
+  goal: string;
+  backstory: string;
+  tools: GraphFlow<any>[];
+  memory?: any;
+  verbose?: boolean;
+  maxIterations?: number;
+  llmConfig: ExecutorConfig["llmConfig"];
+  dynamicGoal?: boolean;
+  dynamicGoalPrompt?: string;
+  dynamicNext?: boolean;
+  dynamicNextPrompt?: string;
+  enableSchedule?: boolean;
+  enableClone?: boolean;
+  enableReflection?: boolean;
+  agenda?: any;
+  entityStore?: import("../agent/entity-resolver/entity-index").IEntityStore;
+};
+
+/**
+ * Represents the schema of an action that can be performed by the agent
+ * @interface ActionSchema
+ * @property {string} name - The name of the action
+ * @property {Array<{name: string, value: any}>} parameters - The parameters required for the action
+ */
+export type ActionSchema = {
+  name: string;
+  parameters: Array<{ name: string; value: any }>;
+};
+
+/**
+ * Represents the output of the agent's decision-making process
+ * @interface DecisionOutput
+ * @property {ActionSchema[]} actions - The actions to be executed
+ * @property {string} response - The agent's response message
+ * @property {string} [thought] - The agent's internal reasoning for this turn
+ */
+export type DecisionOutput = {
+  actions: ActionSchema[];
+  response: string;
+  thought?: string;
+};
+
+export type LLMCall = {
+  promptTokens: number;
+  completionTokens: number;
+  duration: number;
+  timestamp: string;
+};
+
+/**
+ * Configuration for the Language Model
+ * @interface LLMConfig
+ * @property {LLMProvider} provider - The LLM provider to use
+ * @property {string} [apiKey] - API key for the provider (not required for Ollama)
+ * @property {LLMModel} model - The specific model to use
+ * @property {number} [temperature] - Optional temperature parameter for response randomness
+ * @property {number} [maxTokens] - Optional maximum tokens for the response
+ * @property {string} [baseUrl] - Optional base URL for local providers (e.g., Ollama)
+ * @property {Function} [customCall] - Optional custom implementation for API calls
+ */
+export type LLMConfig = {
+  provider: LLMProvider;
+  apiKey?: string;
+  model: LLMModel;
+  temperature?: number;
+  maxTokens?: number;
+  baseUrl?: string;
+  customCall?: (
+    prompt: string | PromptInput,
+    schema: z.ZodType<any>
+  ) => Promise<any>;
+};
+
+/**
+ * Structure for prompt input to the LLM
+ * @interface PromptInput
+ * @property {string} system - The system message/context
+ * @property {string} user - The user's input message
+ */
+export type PromptInput = {
+  system: string;
+  user: string;
+};

package/types/index.ts

@@ -0,0 +1,387 @@
+import { EventEmitter } from "events";
+import { ZodSchema } from "zod";
+import { IEventEmitter } from "../interfaces";
+
+/* ======================== MEMORY ======================== */
+
+/**
+ * Represents the input structure for creating a memory entry.
+ * @typedef {Object} CreateMemoryInput
+ * @property {string} content - The text content to store.
+ * @property {string} roomId - The room identifier.
+ * @property {string} [id] - Optional stable id.
+ * @property {Record<string, any>} [metadata] - Optional metadata.
+ * @property {number[]} [embedding] - Optional vector embedding.
+ * @property {number} [ttl] - Time-to-live in seconds (optional).
+ */
+export interface CreateMemoryInput {
+  id?: string;
+  content: string;
+  metadata?: Record<string, any>;
+  embedding?: number[];
+  roomId: string;
+  ttl?: number;
+  type?: string;
+}
+
+/**
+ * Represents a stored memory entry.
+ * @typedef {Object} BaseMemoryType
+ * @property {string} id - Unique identifier of the memory entry.
+ * @property {string} content - Stored text content.
+ * @property {number[] | null} embedding - Vector representation of the data.
+ * @property {string} roomId - The associated room ID.
+ * @property {Date} createdAt - Creation date.
+ */
+export interface BaseMemoryType {
+  id: string;
+  content: string;
+  metadata?: Record<string, any>;
+  embedding?: number[];
+  roomId: string;
+  createdAt: Date;
+}
+
+/* ======================== SCHEDULING ======================== */
+
+/**
+ * Type for scheduled request entries
+ * @typedef {Object} ScheduledRequest
+ */
+export type ScheduledRequest = {
+  /** Unique identifier for the scheduled request */
+  id: string;
+  /** The original request string */
+  originalRequest: string;
+  /** The cron expression for scheduling */
+  cronExpression: string;
+  /** Whether the request is recurring */
+  isRecurring: boolean;
+  /** The creation date */
+  createdAt: Date;
+};
+
+/* ======================== GRAPH ======================== */
+
+/**
+ * Utility type for extracting schema type from Zod schema
+ * @template T - Zod schema type
+ */
+export type SchemaType<T> = T extends ZodSchema<infer U> ? U : never;
+
+/**
+ * Type for graph context based on schema
+ * @template T - Schema type
+ */
+export type GraphContext<T extends ZodSchema> = {
+  [key: string]: any;
+};
+
+/**
+ * Configuration for event handling strategies in nodes
+ * @typedef {Object} EventStrategy
+ * @property {"single" | "all" | "correlate"} type - The type of event handling strategy
+ * - single: Waits for any single event from the specified events
+ * - all: Waits for all specified events to occur
+ * - correlate: Uses a correlation function to match related events
+ * @property {(events: any[]) => boolean} [correlation] - Optional correlation function for "correlate" strategy
+ */
+export type EventStrategy = {
+  type: "single" | "all" | "correlate";
+  correlation?: (events: any[]) => boolean;
+};
+
+/**
+ * Configuration for event handling in nodes
+ * @typedef {Object} EventConfig
+ * @property {string[]} events - Array of event names to wait for
+ * @property {number} [timeout] - Optional timeout in milliseconds
+ * @property {EventStrategy} strategy - Strategy for handling multiple events
+ * @property {(events: any[]) => Promise<void>} [onSuccess] - Optional callback when events are successfully received
+ * @property {() => Promise<void>} [onTimeout] - Optional callback when event waiting times out
+ * @example
+ * ```typescript
+ * const eventConfig: EventConfig = {
+ *   events: ["payment.received", "order.validated"],
+ *   timeout: 5000,
+ *   strategy: {
+ *     type: "correlate",
+ *     correlation: (events) => events.every(e => e.transactionId === events[0].transactionId)
+ *   },
+ *   onSuccess: async (events) => {
+ *     console.log("Correlated events received:", events);
+ *   },
+ *   onTimeout: async () => {
+ *     console.log("Event waiting timed out");
+ *   }
+ * };
+ * ```
+ */
+export type EventConfig = {
+  events: string[];
+  timeout?: number;
+  strategy: EventStrategy;
+  onSuccess?: (events: any[]) => Promise<void>;
+  onTimeout?: () => Promise<void>;
+};
+
+/**
+ * Represents an event in the graph system
+ * @template T - Schema type for context validation
+ * @property {string} type - The type/name of the event
+ * @property {any} [payload] - Optional payload data
+ * @property {number} timestamp - Unix timestamp of when the event occurred
+ * @example
+ * ```typescript
+ * const event: GraphEvent<MySchema> = {
+ *   type: "payment.received",
+ *   payload: {
+ *     transactionId: "tx123",
+ *     amount: 100,
+ *     currency: "USD"
+ *   },
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
+export type GraphEvent<T extends ZodSchema> = {
+  type: string;
+  payload?: any;
+  timestamp: number;
+};
+
+/**
+ * Configuration for waiting on multiple events
+ * @template T - Schema type for context validation
+ * @property {string[]} events - Array of event names to wait for
+ * @property {number} [timeout] - Optional timeout in milliseconds
+ * @property {"all" | "any" | "race"} strategy - Strategy for handling multiple events
+ * @property {(context: GraphContext<T>) => Promise<void>} [onSuccess] - Optional success callback
+ * @example
+ * ```typescript
+ * const config: WaitForEvents<MySchema> = {
+ *   events: ["event1", "event2"],
+ *   timeout: 5000,
+ *   strategy: "all",
+ *   onSuccess: async (context) => {
+ *     console.log("All events received");
+ *   }
+ * };
+ * ```
+ */
+export type WaitForEvents<T extends ZodSchema> = {
+  events: string[];
+  timeout?: number;
+  strategy: "all" | "any" | "race";
+  onSuccess?: <T extends ZodSchema>(context: GraphContext<T>) => Promise<void>;
+};
+
+/**
+ * Interface representing a node in the graph
+ * @interface
+ * @template T - Schema type
+ * @template P - Parameters type
+ */
+export interface GraphNodeConfig<T extends ZodSchema, P = any> {
+  /** Name of the node */
+  name: string;
+  /** Description of the node */
+  description?: string;
+  /** Schema for node inputs */
+  params?: P extends void ? never : ZodSchema<P>;
+  /** Execute function for the node */
+  execute: (
+    context: GraphContext<T>,
+    tools?: { eventEmitter: IEventEmitter }
+  ) => Promise<void>;
+  /** Optional condition for node execution */
+  condition?: (context: GraphContext<T>, params?: P) => boolean;
+  /** Array of next node names or objects with conditions */
+  next?:
+    | Array<
+        | string
+        | { node: string; condition: (context: GraphContext<T>) => boolean }
+      >
+    | string
+    | ((context: GraphContext<T>) => string[]);
+  /** Array of event names that trigger this node */
+  events?: string[];
+  /** Event handling configuration */
+  when?: EventConfig;
+  /** Retry configuration */
+  retry?: {
+    maxAttempts: number;
+    delay: number;
+    onRetryFailed?: (error: Error, context: GraphContext<T>) => Promise<void>;
+    continueOnFailed?: boolean;
+  };
+  /** Error handler function */
+  onError?: (error: Error) => void;
+  agent?: string;
+}
+
+/**
+ * Interface for graph definition
+ * @interface
+ * @template T - Schema type
+ */
+export type GraphConfig<T extends ZodSchema> = {
+  /** Name of the graph */
+  name: string;
+  /** Schema for validation */
+  schema: T;
+  /** Initial context */
+  context: SchemaType<T>;
+  /** Array of nodes in the graph */
+  nodes: GraphNodeConfig<T, any>[];
+  /** Global error handler */
+  onError?: (error: Error, context: GraphContext<T>) => void;
+  /** Entry node name */
+  entryNode?: string;
+  /** Event emitter instance */
+  eventEmitter?: IEventEmitter | EventEmitter;
+  /** Array of events */
+  events?: string[];
+};
+
+/**
+ * Type for graph execution result
+ * @template T - Schema type
+ */
+export type GraphExecutionResult<T extends ZodSchema> = {
+  graphName: string;
+  nodeName: string;
+  context: GraphContext<T>;
+};
+
+/* ======================== MEILISEARCH ======================== */
+
+/**
+ * Configuration type for Meilisearch
+ * @typedef {Object} MeilisearchConfig
+ */
+export type MeilisearchConfig = {
+  /** Meilisearch host URL */
+  host: string;
+  /** API key for authentication */
+  apiKey: string;
+  /** Array of searchable attributes */
+  searchableAttributes?: string[];
+  /** Array of sortable attributes */
+  sortableAttributes?: string[];
+};
+
+/**
+ * Settings type for Meilisearch
+ * @typedef {Object} MeilisearchSettings
+ */
+export type MeilisearchSettings = {
+  /** Array of searchable attributes */
+  searchableAttributes?: string[];
+  /** Array of sortable attributes */
+  sortableAttributes?: string[];
+};
+
+/**
+ * Configuration interface for NLP Engine
+ * @interface NLPConfig
+ * @property {any} [corpus] - Training corpus data
+ * @property {Record<string, any>} [responses] - Response templates
+ * @property {Record<string, any>} [entities] - Entity definitions
+ * @property {string} [language] - Language code (default: 'en')
+ * @property {number} [threshold] - Entity recognition threshold (default: 0.5)
+ * @property {string} [path] - Path to save/load model
+ */
+export type NLPConfig = {
+  corpus?: any;
+  responses?: Record<string, any>;
+  entities?: Record<string, any>;
+  language?: string;
+  threshold?: number;
+  path?: string;
+};
+
+/**
+ * Type definition for action handlers
+ * @callback ActionHandler
+ * @param {any} data - Input data for the action
+ * @returns {Promise<any>} Result of the action
+ */
+export type ActionHandler = (data: any) => Promise<any>;
+
+/**
+ * Options for the observer
+ * @typedef {Object} ObserverOptions
+ * @property {number} [debounce] - Debounce time in milliseconds
+ * @property {number} [delay] - Delay time in milliseconds
+ * @property {boolean} [stream] - Whether to stream the response
+ * @property {(string | number)[]} [properties] - Properties to observe
+ */
+export type ObserverOptions = {
+  debounce?: number;
+  delay?: number;
+  stream?: boolean;
+  properties?: (string | number)[];
+  onStreamLetter?: (data: { letter: string; property: string }) => void;
+  onStreamComplete?: () => void;
+};
+
+/* ======================== CHECKPOINT ======================== */
+
+/**
+ * Checkpoint metadata for tracking execution state
+ */
+export type CheckpointMetadata = {
+  createdAt: number;
+  interrupted?: boolean;
+  awaitingApproval?: boolean;
+  rejected?: boolean;
+  error?: string;
+};
+
+/**
+ * Configuration for checkpoint behavior during execution
+ */
+export type CheckpointConfig = {
+  saveEveryNode?: boolean;
+  saveOnComplete?: boolean;
+  checkpointId?: string;
+  breakpoints?: string[];
+  runId?: string;
+  initialContext?: Record<string, any>;
+};
+
+/**
+ * Result of a human-in-the-loop approval
+ */
+export type ApprovalResult = {
+  action: "approved" | "rejected";
+  contextModifications?: Record<string, any>;
+};
+
+/**
+ * Represents a saved execution state of a graph
+ */
+export type Checkpoint<T extends ZodSchema = any> = {
+  id: string;
+  graphName: string;
+  runId?: string;
+  nodeName: string;
+  nextNodes: string[];
+  context: Record<string, any>;
+  metadata: CheckpointMetadata;
+};
+
+/* ======================== PARALLEL & HANDOFF ======================== */
+
+export type {
+  ParallelConfig,
+  Send,
+  SendFunction,
+  Command,
+  ReducerFunction,
+  StateReducer,
+  WorkerConfig,
+  ParallelNodeConfig,
+} from "../execution/types.parallel";
+