Documentation of @nestia/agent

packages/agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/agent",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
   "typings": "lib/index.d.ts",

packages/agent/src/NestiaAgent.ts

@@ -18,11 +18,28 @@ import { INestiaAgentTokenUsage } from "./structures/INestiaAgentTokenUsage";
 /**
  * Nestia A.I. chatbot agent.
  *
- * `NestiaChatAgent` is a facade class for the A.I. chatbot agent
+ * `NestiaChatAgent` is a facade class for the super A.I. chatbot agent
  * which performs the {@link converstate user's conversation function}
  * with LLM (Large Language Model) function calling and manages the
  * {@link getPromptHistories prompt histories}.
  *
+ * To understand and compose the `NestiaAgent` class exactly, reference
+ * below types concentrating on the documentation comments please.
+ * Especially, you have to be careful about the {@link INestiaAgentProps}
+ * type which is used in the {@link constructor} function.
+ *
+ * - Constructors
+ *   - {@link INestiaAgentProps}
+ *   - {@link INestiaAgentProvider}
+ *   - {@link INestiaAgentController}
+ *   - {@link INestiaAgentConfig}
+ *   - {@link INestiaAgentSystemPrompt}
+ * - Accessors
+ *   - {@link INestiaAgentOperation}
+ *   - {@link INestiaAgentPrompt}
+ *   - {@link INestiaAgentEvent}
+ *   - {@link INestiaAgentTokenUsage}
+ *
  * @author Jeongho Nam - https://github.com/samchon
  */
 export class NestiaAgent {

packages/agent/src/structures/INestiaAgentConfig.ts

@@ -3,6 +3,17 @@ import { INestiaAgentSystemPrompt } from "./INestiaAgentSystemPrompt";
 /**
  * Configuration for Nestia Agent.
  *
+ * `INestiaAgentConfig` is an interface that defines the configuration
+ * properties of the {@link NestiaAgent}. With this configuration, you
+ * can set the user's locale, timezone, and some of system prompts.
+ *
+ * Also, you can affect to the LLM function selecing/calling logic by
+ * configuring additional properties. For an example, if you configure the
+ * {@link capacity} property, the A.I. chatbot 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.
+ *
  * @author Jeongho Nam - https://github.com/samchon
  */
 export interface INestiaAgentConfig {

packages/agent/src/structures/INestiaAgentController.ts

@@ -6,30 +6,122 @@ import {
 } from "@samchon/openapi";
 import { ILlmApplicationOfValidate, ILlmFunctionOfValidate } from "typia";
 
+/**
+ * Controller of the Nestia Agent.
+ *
+ * `INestiaAgentController` is a type represents a controller of the
+ * {@link NestiaAgent}, which serves a set of functions to be called
+ * by A.I. chatbot from LLM function calling.
+ *
+ * Also, `INestiaAgentController` is an union type which can specify
+ * a subtype by checking the {@link protocol} property.
+ *
+ * - HTTP server: {@link INestiaAgentController..IHttp}
+ * - TypeScript class: {@link INestiaAgentController.IClass}
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type INestiaAgentController =
   | INestiaAgentController.IHttp
   | INestiaAgentController.IClass;
 export namespace INestiaAgentController {
+  /**
+   * HTTP controller.
+   *
+   * You can make it by {@link createHttpLlmApplication} function with
+   * the Swagger or OpenAPI document.
+   */
   export interface IHttp extends IBase<"http", IHttpLlmApplication<"chatgpt">> {
+    /**
+     * Connection to the server.
+     *
+     * Connection to the API server including the URL and headers.
+     */
     connection: IHttpConnection;
+
+    /**
+     * Executor of the API function.
+     *
+     * @param props Properties of the API function call
+     * @returns HTTP response of the API function call
+     */
     execute?: (props: {
+      /**
+       * Connection to the server.
+       */
       connection: IHttpConnection;
+
+      /**
+       * Application schema.
+       */
       application: IHttpLlmApplication<"chatgpt">;
+
+      /**
+       * Function schema.
+       */
       function: IHttpLlmFunction<"chatgpt">;
+
+      /**
+       * Arguments of the function calling.
+       *
+       * It is an object of key-value pairs of the API function's parameters.
+       * The property keys are composed by below rules:
+       *
+       * - parameter names
+       * - query parameter as an object type if exists
+       * - body parameter if exists
+       */
       arguments: object;
     }) => Promise<IHttpResponse>;
   }
+
+  /**
+   * TypeScript class controller.
+   *
+   * You can make it by `typia.llm.application<App, Model>()` function.
+   *
+   * - https://typia.io/docs/llm/application
+   */
   export interface IClass
     extends IBase<"class", ILlmApplicationOfValidate<"chatgpt">> {
+    /**
+     * Executor of the class function.
+     *
+     * @param props Properties of the function call.
+     * @returns Return value of the function call.
+     */
     execute: (props: {
+      /**
+       * Target application schema.
+       */
       application: ILlmApplicationOfValidate<"chatgpt">;
+
+      /**
+       * Target function schema.
+       */
       function: ILlmFunctionOfValidate<"chatgpt">;
+
+      /**
+       * Arguments of the function calling.
+       */
       arguments: object;
     }) => Promise<unknown>;
   }
+
   interface IBase<Protocol, Application> {
+    /**
+     * Protocol discrminator.
+     */
     protocol: Protocol;
+
+    /**
+     * Name of the controller.
+     */
     name: string;
+
+    /**
+     * Application schema of function calling.
+     */
     application: Application;
   }
 }

packages/agent/src/structures/INestiaAgentEvent.ts

@@ -8,7 +8,8 @@ import { INestiaAgentPrompt } from "./INestiaAgentPrompt";
  * Nestia A.I. chatbot event.
  *
  * `INestiaAgentEvent` is an union type of all possible events that can
- * be emitted by the A.I. chatbot of the {@link NestiaAgent} class.
+ * be emitted by the A.I. chatbot of the {@link NestiaAgent} class. You
+ * can discriminate the subtype by checking the {@link type} property.
  *
  * @author Jeongho Nam - https://github.com/samchon
  */

packages/agent/src/structures/INestiaAgentOperation.ts

@@ -3,16 +3,37 @@ import { ILlmFunctionOfValidate } from "typia";
 
 import { INestiaAgentController } from "./INestiaAgentController";
 
+/**
+ * Operation information in the Nestia Agent.
+ *
+ * `INestiaAgentOperation` is a type represents an operation that would
+ * be selected by the A.I. chatbot of {@link NestiaAgent} class to
+ * perform the LLM (Large Language Model) function calling.
+ *
+ * Also, it is an union type that is discriminated by the {@link protocol}
+ * property. If the protocol value is `http`, it means that the HTTP API
+ * operation would be called by the A.I. chatbot. Otherwise, if the protocol
+ * value is `class`, it means that the operation has come from a
+ * TypeScript class.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export type INestiaAgentOperation =
   | INestiaAgentOperation.IHttp
   | INestiaAgentOperation.IClass;
 export namespace INestiaAgentOperation {
+  /**
+   * HTTP API operation.
+   */
   export type IHttp = IBase<
     "http",
     INestiaAgentController.IHttp,
     IHttpLlmFunction<"chatgpt">
   >;
 
+  /**
+   * TypeScript class operation.
+   */
   export type IClass = IBase<
     "class",
     INestiaAgentController.IClass,

packages/agent/src/structures/INestiaAgentOperationCollection.ts

@@ -1,8 +1,50 @@
 import { INestiaAgentOperation } from "./INestiaAgentOperation";
 
+/**
+ * Collection of operations used in the Nestia Agent.
+ *
+ * `INestiaAgentOperationCollection` is an interface type representing
+ * a collection of operations for several purposes used in the
+ * {@link NestiaAgent} internally.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface INestiaAgentOperationCollection {
+  /**
+   * List of every operations.
+   */
   array: INestiaAgentOperation[];
+
+  /**
+   * Divided operations.
+   *
+   * If you've configured the {@link INestiaAgentConfig.capacity} property,
+   * the  A.I. chatbot ({@link NestiaAgent}) will separate the operations
+   * into the several groups to divide and conquer and LLM function selecting
+   * for accuracy.
+   *
+   * In that case, this property `divided`'s length would be dtermined by
+   * dividing the number of operations ({@link array}'s length) by the
+   * {@link INestiaAgentConfig.capacity}.
+   *
+   * Otherwise, if the {@link INestiaAgentConfig.capacity} has not been
+   * configured, this `divided` property would be the `undefined` value.
+   */
   divided?: INestiaAgentOperation[][] | undefined;
+
+  /**
+   * Flat dictionary of operations.
+   *
+   * Dictionary of operations with their {@link INestiaAgentOperation.name}.
+   */
   flat: Map<string, INestiaAgentOperation>;
+
+  /**
+   * Group dictionary of operations.
+   *
+   * Dictionary of operations with their
+   * {@link INestiaAgentOperation.controller.name} and
+   * {@link INestiaAgentOperation.function.name}.
+   */
   group: Map<string, Map<string, INestiaAgentOperation>>;
 }

packages/agent/src/structures/INestiaAgentOperationSelection.ts

@@ -6,6 +6,14 @@ import { INestiaAgentController } from "./INestiaAgentController";
 /**
  * Nestia agent operation selection.
  *
+ * `INestiaAgentOperationSelection` is a type represents an operation
+ * which has been selected by the A.I. chatbot of {@link NestiaAgent}
+ * class for the LLM (Large Language Model) function calling with
+ * detailed {@link reason} of the selection (or cancellation).
+ *
+ * Also, `INestiaAgentOperationSelection` is an union type that can
+ * specify a subtype by checking the {@link protocol} property.
+ *
  * @author Jeongho Nam - https://github.com/samchon
  */
 export type INestiaAgentOperationSelection =

packages/agent/src/structures/INestiaAgentPrompt.ts

@@ -10,6 +10,14 @@ import { INestiaAgentOperationSelection } from "./INestiaAgentOperationSelection
  * `INestiaChatPrompt` is an union type of all possible prompts that can
  * be generated by the A.I. chatbot of the {@link NestiaChatAgent} class.
  *
+ * In other words, `INestiaChatPrompt` is a type of chat history that
+ * is occured during the conversation between the user and the A.I. chatbot
+ * in the {@link NestiaChatAgent} class.
+ *
+ * If you want to continue the previous A.I. chatbot session, you can
+ * accomplish it by assigning the {@link INestiaAgentProps.histories}
+ * property when creating a new {@link NestiaAgent} instance.
+ *
  * @author Jeongho Nam - https://github.com/samchon
  */
 export type INestiaAgentPrompt =

packages/agent/src/structures/INestiaAgentProps.ts

@@ -5,9 +5,60 @@ import { INestiaAgentController } from "./INestiaAgentController";
 import { INestiaAgentPrompt } from "./INestiaAgentPrompt";
 import { INestiaAgentProvider } from "./INestiaAgentProvider";
 
+/**
+ * Properties of the Nestia Agent.
+ *
+ * `INestiaAgentProps` is an interface that defines the properties
+ * of the {@link NestiaAgent.constructor}. In the `INestiaAgentProps`,
+ * there're everything to prepare to create a Super A.I. chatbot
+ * performing the LLM (Large Language Model) function calling.
+ *
+ * At first, you have to specify the LLM service {@link provider} like
+ * OpenAI with its API key and client API. And then, you have to define
+ * the {@link controllers} serving the functions to call. The controllers
+ * are separated by two protocols; HTTP API and TypeScript class. At last,
+ * you can {@link config}ure the agent by setting the locale, timezone,
+ * and some of system prompts.
+ *
+ * Additionally, if you want to start from the previous A.I. chatbot
+ * session, you can accomplish it by assinging the previous prompt
+ * histories to the {@link histories} property.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface INestiaAgentProps {
-  controllers: INestiaAgentController[];
+  /**
+   * LLM service provider.
+   */
   provider: INestiaAgentProvider;
+
+  /**
+   * Controllers serving functions to call.
+   */
+  controllers: INestiaAgentController[];
+
+  /**
+   * Configuration of agent.
+   *
+   * Configuration of A.I. chatbot agent including the user's locale,
+   * timezone, and some of system prompts. Also, you can affect to the
+   * LLM function selecting/calling logic by configuring additional
+   * properties.
+   *
+   * If you don't configure this property, these values would be default.
+   *
+   * - `locale`: your system's locale and timezone
+   * - `timezone`: your system's timezone
+   * - `systemPrompt`: default prompts written in markdown
+   *   - https://github.com/samchon/nestia/tree/master/packages/agent/prompts
+   */
   config?: INestiaAgentConfig;
+
+  /**
+   * Prompt histories.
+   *
+   * If you're starting the conversation from an existing session,
+   * assign the previouis prompt histories to this property.
+   */
   histories?: Primitive<INestiaAgentPrompt>[];
 }

packages/agent/src/structures/INestiaAgentProvider.ts

@@ -3,10 +3,24 @@ import OpenAI from "openai";
 /**
  * LLM Provider for Nestia Chat.
  *
+ * `INestiaAgentProvider` is a type represents an LLM
+ * (Large Language Model) provider of the {@link NestiaAgent}.
+ *
+ * Currently, {@link NestiaAgent} is supporting only one provider OpenAI.
+ * You can specify the provider by configuring the `type` property as
+ * `"chatgpt"`. Also, you have to assign the OpenAI API client instance
+ * to the `api` property, and specify the `model` to use.
+ *
+ * If you want to use another LLM provider like Claude or Gemini,
+ * please write an issue or contribute to `nestia` please.
+ *
  * @author Jeongho Nam - https://github.com/samchon
  */
 export type INestiaAgentProvider = INestiaAgentProvider.IChatGpt;
 export namespace INestiaAgentProvider {
+  /**
+   * OpenAI provider.
+   */
   export interface IChatGpt {
     /**
      * Discriminator type.