@agentica/core 0.10.0-dev.20250302 → 0.10.0

package/src/structures/IAgenticaConfig.ts

@@ -1,123 +1,123 @@
-import { ILlmSchema } from "@samchon/openapi";
-
-import { IAgenticaContext } from "./IAgenticaContext";
-import { IAgenticaExecutor } from "./IAgenticaExecutor";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
-import { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
-
-/**
- * Configuration for Nestia Agent.
- *
- * `IAgenticaConfig` is an interface that defines the configuration
- * properties of the {@link Agentica}. 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 Samchon
- */
-export interface IAgenticaConfig<Model extends ILlmSchema.Model> {
-  /**
-   * Locale of the A.I. chatbot.
-   *
-   * If you configure this property, the A.I. chatbot will conversate with
-   * the given locale. You can get the locale value by
-   *
-   * - Browser: `navigator.language`
-   * - NodeJS: `process.env.LANG.split(".")[0]`
-   *
-   * @default your_locale
-   */
-  locale?: string;
-
-  /**
-   * Timezone of the A.I. chatbot.
-   *
-   * If you configure this property, the A.I. chatbot will consider the
-   * given timezone. You can get the timezone value by
-   * `Intl.DateTimeFormat().resolvedOptions().timeZone`.
-   *
-   * @default your_timezone
-   */
-  timezone?: string;
-
-  /**
-   * 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 IAgenticaProps.applications} is too much greater,
-   * the A.I. chatbot often fallen into the hallucination.
-   *
-   * In that case, if you configure this property value, `Agentica`
-   * 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 100
-   */
-  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?: IAgenticaSystemPrompt<Model>;
-
-  /**
-   * Agent executor.
-   *
-   * Executor function of Agentic AI's iteration plan to internal agents
-   * running by the {@link Agentica.conversate} function.
-   *
-   * If you want to customize the agent execution plan, you can do it
-   * by assigning you logic function of entire or partial to this property.
-   * When customizing it, it would better to reference the
-   * {@link ChatGptAgent.execute} function.
-   *
-   * @param ctx Context of the agent
-   * @returns Lit of prompts generated by the executor
-   * @default ChatGptAgent.execute
-   */
-  executor?:
-    | Partial<IAgenticaExecutor<Model>>
-    | ((ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>);
-}
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaContext } from "./IAgenticaContext";
+import { IAgenticaExecutor } from "./IAgenticaExecutor";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+import { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
+
+/**
+ * Configuration for Nestia Agent.
+ *
+ * `IAgenticaConfig` is an interface that defines the configuration
+ * properties of the {@link Agentica}. 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 Samchon
+ */
+export interface IAgenticaConfig<Model extends ILlmSchema.Model> {
+  /**
+   * Locale of the A.I. chatbot.
+   *
+   * If you configure this property, the A.I. chatbot will conversate with
+   * the given locale. You can get the locale value by
+   *
+   * - Browser: `navigator.language`
+   * - NodeJS: `process.env.LANG.split(".")[0]`
+   *
+   * @default your_locale
+   */
+  locale?: string;
+
+  /**
+   * Timezone of the A.I. chatbot.
+   *
+   * If you configure this property, the A.I. chatbot will consider the
+   * given timezone. You can get the timezone value by
+   * `Intl.DateTimeFormat().resolvedOptions().timeZone`.
+   *
+   * @default your_timezone
+   */
+  timezone?: string;
+
+  /**
+   * 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 IAgenticaProps.applications} is too much greater,
+   * the A.I. chatbot often fallen into the hallucination.
+   *
+   * In that case, if you configure this property value, `Agentica`
+   * 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 100
+   */
+  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?: IAgenticaSystemPrompt<Model>;
+
+  /**
+   * Agent executor.
+   *
+   * Executor function of Agentic AI's iteration plan to internal agents
+   * running by the {@link Agentica.conversate} function.
+   *
+   * If you want to customize the agent execution plan, you can do it
+   * by assigning you logic function of entire or partial to this property.
+   * When customizing it, it would better to reference the
+   * {@link ChatGptAgent.execute} function.
+   *
+   * @param ctx Context of the agent
+   * @returns Lit of prompts generated by the executor
+   * @default ChatGptAgent.execute
+   */
+  executor?:
+    | Partial<IAgenticaExecutor<Model>>
+    | ((ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>);
+}

package/src/structures/IAgenticaContext.ts

@@ -1,129 +1,129 @@
-import { ILlmSchema } from "@samchon/openapi";
-import OpenAI from "openai";
-
-import { AgenticaSource } from "../typings/AgenticaSource";
-import { IAgenticaConfig } from "./IAgenticaConfig";
-import { IAgenticaEvent } from "./IAgenticaEvent";
-import { IAgenticaOperationCollection } from "./IAgenticaOperationCollection";
-import { IAgenticaOperationSelection } from "./IAgenticaOperationSelection";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
-
-/**
- * Context of the Nestia A.I. agent.
- *
- * `IAgenticaContext` is a structure defining the context of the
- * internal agents composing the {@link Agentica}, like function
- * selector, executor, and describer, and so on. For example, if an
- * agent has been configured to utilize the OpenAI, the context will
- * be delivered to the below components.
- *
- * - {@link ChatGptAgent}
- *   - {@link ChatGptInitializeFunctionAgent}
- *   - {@link ChatGptSelectFunctionAgent}
- *   - {@link ChatGptExecuteFunctionAgent}
- *   - {@link ChatGptDescribeFunctionAgent}
- *   - {@link ChatGptCancelFunctionAgent}
- *
- * Also, as its name is context, it contains every information that
- * is required to interact with the AI vendor like OpenAI. It
- * contains every operations for LLM function calling, and
- * configuration used for the agent construction. And it contains
- * the prompt histories, and facade controller functions for
- * interacting with the {@link Agentica} like {@link dispatch}.
- *
- * In such reasons, if you're planning to customize some internal
- * agents, or add new agents with new process routine, you have to
- * understand this context structure. Otherwise you don't have any
- * plan to customize the internal agents, this context information is
- * not important for you.
- *
- * @author Samchon
- */
-export interface IAgenticaContext<Model extends ILlmSchema.Model> {
-  //----
-  // APPLICATION
-  //----
-  /**
-   * Collection of operations.
-   *
-   * Collection of operations from every controllers, and their
-   * groups composed by the divide and conquer rule for the
-   * efficient operation selection if configured.
-   */
-  operations: IAgenticaOperationCollection<Model>;
-
-  /**
-   * Configuration of the agent.
-   *
-   * Configuration of the agent, that is used when constructing the
-   * {@link Agentica} instance.
-   *
-   * @todo Write detaily after supporting the agent customization feature
-   */
-  config: IAgenticaConfig<Model> | undefined;
-
-  //----
-  // STATES
-  //----
-  /**
-   * Prompt histories.
-   */
-  histories: IAgenticaPrompt<Model>[];
-
-  /**
-   * Stacked operations.
-   *
-   * In other words, list of candidate operations for the LLM function calling.
-   */
-  stack: IAgenticaOperationSelection<Model>[];
-
-  /**
-   * Text prompt of the user.
-   *
-   * Text conversation written the by user through the
-   * {@link Agentica.conversate} function.
-   */
-  prompt: IAgenticaPrompt.IText<"user">;
-
-  /**
-   * Whether the agent is ready.
-   *
-   * Returns a boolean value indicates whether the agent is ready to
-   * perform the function calling.
-   *
-   * If the agent has called the {@link IAgenticaContext.initialize},
-   * it returns `true`. Otherwise the {@link initialize} has never been
-   * called, returns `false`.
-   */
-  ready: () => boolean;
-
-  //----
-  // HANDLERS
-  //----
-  /**
-   * Dispatch event.
-   *
-   * Dispatch event so that the agent can be handle the event
-   * through the {@link Agentica.on} function.
-   *
-   * @param event Event to deliver
-   */
-  dispatch: (event: IAgenticaEvent<Model>) => Promise<void>;
-
-  /**
-   * Request to the OpenAI server.
-   *
-   * @param source The source agent of the agent
-   * @param body The request body to the OpenAI server
-   * @returns Response from the OpenAI server
-   */
-  request: (
-    source: AgenticaSource,
-    body: Omit<OpenAI.ChatCompletionCreateParamsNonStreaming, "model">,
-  ) => Promise<OpenAI.ChatCompletion>;
-
-  /**
-   * Initialize the agent.
-   */
-  initialize: () => Promise<void>;
-}
+import { ILlmSchema } from "@samchon/openapi";
+import OpenAI from "openai";
+
+import { AgenticaSource } from "../typings/AgenticaSource";
+import { IAgenticaConfig } from "./IAgenticaConfig";
+import { IAgenticaEvent } from "./IAgenticaEvent";
+import { IAgenticaOperationCollection } from "./IAgenticaOperationCollection";
+import { IAgenticaOperationSelection } from "./IAgenticaOperationSelection";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+
+/**
+ * Context of the Nestia A.I. agent.
+ *
+ * `IAgenticaContext` is a structure defining the context of the
+ * internal agents composing the {@link Agentica}, like function
+ * selector, executor, and describer, and so on. For example, if an
+ * agent has been configured to utilize the OpenAI, the context will
+ * be delivered to the below components.
+ *
+ * - {@link ChatGptAgent}
+ *   - {@link ChatGptInitializeFunctionAgent}
+ *   - {@link ChatGptSelectFunctionAgent}
+ *   - {@link ChatGptExecuteFunctionAgent}
+ *   - {@link ChatGptDescribeFunctionAgent}
+ *   - {@link ChatGptCancelFunctionAgent}
+ *
+ * Also, as its name is context, it contains every information that
+ * is required to interact with the AI vendor like OpenAI. It
+ * contains every operations for LLM function calling, and
+ * configuration used for the agent construction. And it contains
+ * the prompt histories, and facade controller functions for
+ * interacting with the {@link Agentica} like {@link dispatch}.
+ *
+ * In such reasons, if you're planning to customize some internal
+ * agents, or add new agents with new process routine, you have to
+ * understand this context structure. Otherwise you don't have any
+ * plan to customize the internal agents, this context information is
+ * not important for you.
+ *
+ * @author Samchon
+ */
+export interface IAgenticaContext<Model extends ILlmSchema.Model> {
+  //----
+  // APPLICATION
+  //----
+  /**
+   * Collection of operations.
+   *
+   * Collection of operations from every controllers, and their
+   * groups composed by the divide and conquer rule for the
+   * efficient operation selection if configured.
+   */
+  operations: IAgenticaOperationCollection<Model>;
+
+  /**
+   * Configuration of the agent.
+   *
+   * Configuration of the agent, that is used when constructing the
+   * {@link Agentica} instance.
+   *
+   * @todo Write detaily after supporting the agent customization feature
+   */
+  config: IAgenticaConfig<Model> | undefined;
+
+  //----
+  // STATES
+  //----
+  /**
+   * Prompt histories.
+   */
+  histories: IAgenticaPrompt<Model>[];
+
+  /**
+   * Stacked operations.
+   *
+   * In other words, list of candidate operations for the LLM function calling.
+   */
+  stack: IAgenticaOperationSelection<Model>[];
+
+  /**
+   * Text prompt of the user.
+   *
+   * Text conversation written the by user through the
+   * {@link Agentica.conversate} function.
+   */
+  prompt: IAgenticaPrompt.IText<"user">;
+
+  /**
+   * Whether the agent is ready.
+   *
+   * Returns a boolean value indicates whether the agent is ready to
+   * perform the function calling.
+   *
+   * If the agent has called the {@link IAgenticaContext.initialize},
+   * it returns `true`. Otherwise the {@link initialize} has never been
+   * called, returns `false`.
+   */
+  ready: () => boolean;
+
+  //----
+  // HANDLERS
+  //----
+  /**
+   * Dispatch event.
+   *
+   * Dispatch event so that the agent can be handle the event
+   * through the {@link Agentica.on} function.
+   *
+   * @param event Event to deliver
+   */
+  dispatch: (event: IAgenticaEvent<Model>) => Promise<void>;
+
+  /**
+   * Request to the OpenAI server.
+   *
+   * @param source The source agent of the agent
+   * @param body The request body to the OpenAI server
+   * @returns Response from the OpenAI server
+   */
+  request: (
+    source: AgenticaSource,
+    body: Omit<OpenAI.ChatCompletionCreateParamsNonStreaming, "model">,
+  ) => Promise<OpenAI.ChatCompletion>;
+
+  /**
+   * Initialize the agent.
+   */
+  initialize: () => Promise<void>;
+}