Documentation of @nestia/agent

samchon · samchon · commit 15e8aa4b043c · 2025-01-07T03:44:32.000+09:00
diff --git a/packages/agent/src/NestiaChatAgent.ts b/packages/agent/src/NestiaChatAgent.ts
@@ -6,44 +6,189 @@ import { INestiaChatAgent } from "./structures/INestiaChatAgent";
 import { INestiaChatEvent } from "./structures/INestiaChatEvent";
 import { INestiaChatPrompt } from "./structures/INestiaChatPrompt";
 
+/**
+ * Nestia A.I. chatbot agent.
+ *
+ * `NestiaChatAgent` is a facade class for the A.I. chatbot agent
+ * which performs the {@link converstate user's conversation function}
+ * with LLM (Large Language Model) function calling and manages the
+ * {@link getHistories prompt histories}.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export class NestiaChatAgent implements INestiaChatAgent {
+  /**
+   * @hidden
+   */
   private readonly agent: INestiaChatAgent;
 
+  /**
+   * Initializer constructor.
+   *
+   * @param props Properties to construct the agent
+   */
   public constructor(props: NestiaChatAgent.IProps) {
     this.agent = new ChatGptAgent(props);
   }
 
+  /**
+   * Conversate with the A.I. chatbot.
+   *
+   * User talks to the A.I. chatbot with the content.
+   *
+   * When the user's conversation implies the A.I. chatbot to execute a
+   * function calling, the returned chat prompts will contain the
+   * function calling information like {@link INestiaChatPrompt.IExecute}.
+   *
+   * @param content The content to talk
+   * @returns List of newly created chat prompts
+   */
   public conversate(content: string): Promise<INestiaChatPrompt[]> {
     return this.agent.conversate(content);
   }
 
+  /**
+   * Get the chatbot's history.
+   *
+   * Get list of chat prompts that the chatbot has been conversated.
+   *
+   * @returns List of chat prompts
+   */
   public getHistories(): INestiaChatPrompt[] {
     return this.agent.getHistories();
   }
 
+  /**
+   * Add an event listener.
+   *
+   * Add an event listener to be called whenever the event is emitted.
+   *
+   * @param type Type of event
+   * @param listener Callback function to be called whenever the event is emitted
+   */
   public on<Type extends INestiaChatEvent.Type>(
     type: Type,
-    listener: (event: INestiaChatEvent.Mapper[Type]) => void,
+    listener: (event: INestiaChatEvent.Mapper[Type]) => void | Promise<void>,
   ): void {
     this.agent.on(type, listener);
   }
+
+  /**
+   * Erase an event listener.
+   *
+   * Erase an event listener to stop calling the callback function.
+   *
+   * @param type Type of event
+   * @param listener Callback function to erase
+   */
+  public off<Type extends INestiaChatEvent.Type>(
+    type: Type,
+    listener: (event: INestiaChatEvent.Mapper[Type]) => void | Promise<void>,
+  ): void {
+    this.agent.off(type, listener);
+  }
 }
 export namespace NestiaChatAgent {
+  /**
+   * Properties of the A.I. chatbot agent.
+   */
   export interface IProps {
+    /**
+     * Application instance for LLM function calling.
+     */
     application: IHttpLlmApplication<"chatgpt">;
+
+    /**
+     * Service of the ChatGPT (OpenAI) API.
+     */
     service: IChatGptService;
+
+    /**
+     * HTTP connection to the backend server.
+     */
     connection: IHttpConnection;
+
+    /**
+     * Initial chat prompts.
+     *
+     * If you configure this property, the chatbot will start the
+     * pre-defined conversations.
+     */
     histories?: INestiaChatPrompt[] | undefined;
+
+    /**
+     * Configuration for the A.I. chatbot.
+     */
     config?: IConfig | undefined;
   }
 
+  /**
+   * Configuration for the A.I. chatbot.
+   */
   export interface IConfig {
+    /**
+     * Retry count.
+     *
+     * If LLM function calling composed arguments are invalid,
+     * the A.I. chatbot will retry to call the function with
+     * the modified arguments.
+     *
+     * By the way, if you configure it to 0 or 1, the A.I. chatbot
+     * will not retry the LLM function calling for correcting the
+     * arguments.
+     *
+     * @default 3
+     */
     retry?: number;
+
+    /**
+     * Capacity of the LLM function selecting.
+     *
+     * When the A.I. chatbot selects a proper function to call, if the
+     * number of functions registered in the {@link IProps.application}
+     * is too much greater, the A.I. chatbot often fallen into the
+     * hallucination.
+     *
+     * In that case, if you configure this property value, `NestiaChatAgent`
+     * will divide the functions into the several groups with the configured
+     * capacity and select proper functions to call by operating the multiple
+     * LLM function selecting agents parallelly.
+     *
+     * @default 0
+     */
     capacity?: number;
+
+    /**
+     * Eliticism for the LLM function selecting.
+     *
+     * If you configure {@link capacity}, the A.I. chatbot will complete
+     * the candidate functions to call which are selected by the multiple
+     * LLM function selecting agents.
+     *
+     * Otherwise you configure this property as `false`, the A.I. chatbot
+     * will not complete the candidate functions to call and just accept
+     * every candidate functions to call which are selected by the multiple
+     * LLM function selecting agents.
+     *
+     * @default true
+     */
     eliticism?: boolean;
+
+    /**
+     * System prompt messages.
+     *
+     * System prompt messages if you want to customize the system prompt
+     * messages for each situation.
+     */
     systemPrompt?: Partial<ISytemPrompt>;
   }
 
+  /**
+   * System prompt messages.
+   *
+   * System prompt messages if you want to customize the system prompt
+   * messages for each situation.
+   */
   export interface ISytemPrompt {
     initial?: (histories: INestiaChatPrompt[]) => string;
     select?: (histories: INestiaChatPrompt[]) => string;
diff --git a/packages/agent/src/chatgpt/ChatGptAgent.ts b/packages/agent/src/chatgpt/ChatGptAgent.ts
@@ -146,6 +146,17 @@ export class ChatGptAgent implements INestiaChatAgent {
     take(this.listeners_, type, () => new Set()).add(listener);
   }
 
+  public off<Type extends INestiaChatEvent.Type>(
+    type: Type,
+    listener: (event: INestiaChatEvent.Mapper[Type]) => void,
+  ): void {
+    const set: Set<Function> | undefined = this.listeners_.get(type);
+    if (set) {
+      set.delete(listener);
+      if (set.size === 0) this.listeners_.delete(type);
+    }
+  }
+
   private async dispatch<Event extends INestiaChatEvent>(
     event: Event,
   ): Promise<void> {
diff --git a/packages/agent/src/structures/IChatGptService.ts b/packages/agent/src/structures/IChatGptService.ts
@@ -1,7 +1,21 @@
 import OpenAI from "openai";
 
+/**
+ * Service of the ChatGPT (OpenAI) API.
+ */
 export interface IChatGptService {
+  /**
+   * OpenAI API instance.
+   */
   api: OpenAI;
+
+  /**
+   * Chat model to be used.
+   */
   model: OpenAI.ChatModel;
+
+  /**
+   * Options for the request.
+   */
   options?: OpenAI.RequestOptions | undefined;
 }
diff --git a/packages/agent/src/structures/INestiaChatAgent.ts b/packages/agent/src/structures/INestiaChatAgent.ts
@@ -3,9 +3,16 @@ import { INestiaChatPrompt } from "./INestiaChatPrompt";
 
 export interface INestiaChatAgent {
   conversate(content: string): Promise<INestiaChatPrompt[]>;
+
   getHistories(): INestiaChatPrompt[];
+
   on<Type extends INestiaChatEvent.Type>(
     type: Type,
-    listener: (event: INestiaChatEvent.Mapper[Type]) => void,
+    listener: (event: INestiaChatEvent.Mapper[Type]) => void | Promise<void>,
+  ): void;
+
+  off<Type extends INestiaChatEvent.Type>(
+    type: Type,
+    listener: (event: INestiaChatEvent.Mapper[Type]) => void | Promise<void>,
   ): void;
 }
diff --git a/packages/agent/src/structures/INestiaChatEvent.ts b/packages/agent/src/structures/INestiaChatEvent.ts
@@ -1,38 +1,116 @@
 import { IHttpLlmFunction, IHttpResponse } from "@samchon/openapi";
 
+/**
+ * Nestia A.I. chatbot event.
+ *
+ * `INestiaChatEvent` is an union type of all possible events that can
+ * be emitted by the A.I. chatbot of the {@link NestiaChatAgent} class.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type INestiaChatEvent =
   | INestiaChatEvent.IIintializeEvent
   | INestiaChatEvent.ISelectFunctionEvent
   | INestiaChatEvent.ICancelFunctionEvent
   | INestiaChatEvent.ICallFunctionEvent
   | INestiaChatEvent.IFunctionCompleteEvent;
 export namespace INestiaChatEvent {
+  /**
+   * Event of initializing the chatbot.
+   */
   export interface IIintializeEvent {
     type: "initialize";
   }
 
+  /**
+   * Event of selecting a function to call.
+   */
   export interface ISelectFunctionEvent {
     type: "select";
+
+    /**
+     * Selected function.
+     *
+     * Function that has been selected to prepare LLM function calling.
+     */
     function: IHttpLlmFunction<"chatgpt">;
+
+    /**
+     * Reason of selecting the function.
+     *
+     * The A.I. chatbot will fill this property describing why the function
+     * has been selected.
+     */
     reason: string;
   }
 
+  /**
+   * Event of canceling a function calling.
+   */
   export interface ICancelFunctionEvent {
     type: "cancel";
+
+    /**
+     * Selected function to cancel.
+     *
+     * Function that has been selected to prepare LLM function calling,
+     * but canceled due to no more required.
+     */
     function: IHttpLlmFunction<"chatgpt">;
+
+    /**
+     * Reason of selecting the function.
+     *
+     * The A.I. chatbot will fill this property describing why the function
+     * has been cancelled.
+     *
+     * For reference, if the A.I. chatbot successfully completes the LLM
+     * function calling, the reason of the fnction cancellation will be
+     * "complete".
+     */
     reason: string;
   }
 
+  /**
+   * Event of calling a function.
+   */
   export interface ICallFunctionEvent {
     type: "call";
+
+    /**
+     * Target function to call.
+     */
     function: IHttpLlmFunction<"chatgpt">;
+
+    /**
+     * Arguments of the function calling.
+     *
+     * If you modify this {@link arguments} property, it actually modifies
+     * the backend server's request. Therefore, be careful when you're
+     * trying to modify this property.
+     */
     arguments: object;
   }
 
+  /**
+   * Event of completing a function calling.
+   */
   export interface IFunctionCompleteEvent {
     type: "complete";
+
+    /**
+     * Target funtion that has been called.
+     */
     function: IHttpLlmFunction<"chatgpt">;
+
+    /**
+     * Arguments of the function calling.
+     */
     arguments: object;
+
+    /**
+     * Response of the function calling.
+     */
     response: IHttpResponse;
   }
 
diff --git a/packages/agent/src/structures/INestiaChatFunctionSelection.ts b/packages/agent/src/structures/INestiaChatFunctionSelection.ts
@@ -1,6 +1,21 @@
 import { IHttpLlmFunction } from "@samchon/openapi";
 
+/**
+ * Nestia A.I. chatbot function selection.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface INestiaChatFunctionSelection {
+  /**
+   * Target function.
+   *
+   * Function that has been selected to prepare LLM function calling,
+   * or canceled due to no more required.
+   */
   function: IHttpLlmFunction<"chatgpt">;
+
+  /**
+   * The reason of the function selection or cancellation.
+   */
   reason: string;
 }
diff --git a/packages/agent/src/structures/INestiaChatPrompt.ts b/packages/agent/src/structures/INestiaChatPrompt.ts
