@agentica/core 0.9.0 → 0.10.0-dev.20250302

package/src/structures/IAgenticaExecutor.ts

@@ -1,156 +1,156 @@
-import { ILlmSchema } from "@samchon/openapi";
-
-import { IAgenticaContext } from "./IAgenticaContext";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
-
-/**
- * Executor of the Agentic AI.
- *
- * `IAgenticaExecutor` represents an executor of the {@link Agentica},
- * composing its internal agents to accomplish the Agentic AI through
- * the LLM (Large Language Model) function calling.
- *
- * You can customize one of these internal agents by configuring
- * properties of the `IAgenticaExecutor` type, and assigning it to the
- * {@link IAgenticaConfig.executor} property. If you set the
- * {@link initialize} as `null` value, the {@link Agentica} will skip
- * the initialize process and directly go to the {@link select} process.
- *
- * By the way, when customizing the executor member, it would better to
- * reference the guide documents of `@agentica/core`, and internal
- * agents' implementation code. It's because if you take some mistake on
- * the executor logic, it can entirely break the {@link Agentica}'s
- * operation.
- *
- * @reference https://github.com/wrtnlabs/agentica?tab=readme-ov-file#principles
- * @reference https://github.com/wrtnlabs/agentica/blob/main/packages/agent/src/chatgpt/ChatGptAgent.ts
- * @author Samchon
- */
-export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
-  /**
-   * Initializer agent listing up functions.
-   *
-   * `initialize` agent is the first agent that {@link Agentica}
-   * would meet  which judges whether the user's conversation implies
-   * to call some function or not.
-   *
-   * And if the `initialize` agent judges the user's conversation
-   * implies to call some function, the `initialize` agent will
-   * call the {@link IAgenticaContext.initialize} function, and
-   * inform every functions enrolled in the {@link IAgenticaController}
-   * to the AI agent. And then, the `initialize` agent will not never
-   * be called again, and let {@link Agentica} to go to the next
-   * {@link select} agent.
-   *
-   * Otherwise the user's conversation does not imply the request of
-   * function calling, it would just work like plain chatbot, and just
-   * conversate with the user.
-   *
-   * By the way, if you wanna skip the `initialize` agent, you can
-   * do it by configuring the {@link IAgenticaConfig.executor} as
-   * `null` value. In that case, the `initialize` agent will never be
-   * called, and {@link Agentica} just starts from the {@link select}
-   * agent.
-   *
-   * @param ctx Context of the agent
-   * @returns List of prompts generated by the initializer
-   */
-  initialize:
-    | null
-    | ((ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>);
-
-  /**
-   * Function selector agent.
-   *
-   * `Select` agent finds candidate functions to call from the
-   * conversation context with the user. And the candidate functions
-   * would be enrolled to the {@link IAgenticaContext.stack}, and the
-   * next {@link call} agent will perform the LLM (Large Language Model)
-   * function calling.
-   *
-   * Note that, the `select` agent does not perform the LLM function
-   * calling. It ends with just finding the candidate functions to call.
-   *
-   * By the way, if the `select` agent can't specify a certain function
-   * to call due to lack of conversation context or homogeneity between
-   * heterogeneous functions, how `select` agent works? In that case,
-   * `select` agent it will just enroll every candidate functions to
-   * the stack, and let the next {@link call} agent to determine the
-   * proper function to call. And then let {@link cancel} agent to erase
-   * the other candidate functions from the stack.
-   *
-   * Additionally, if `select` agent could not find any candidate
-   * function from the conversation context with user, it would just
-   * act like plain chatbot conversating with the user.
-   *
-   * @param ctx Context of the agent
-   * @returns List of prompts generated by the selector
-   */
-  select: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
-
-  /**
-   * Function caller agent.
-   *
-   * `Call` agent performs the LLM (Large Language Model) function
-   * calling from the candidate functions enrolled in the
-   * {@link IAgenticaContext.stack}. And the scope of function calling
-   * is, not only just arguments filling, but also actual executing
-   * the function and returning the result.
-   *
-   * By the way, conversation context with user can be not enough to
-   * filling the arguments of the candidate functions. In that case,
-   * the `call` agent will ask the user to fill the missing arguments.
-   *
-   * Otherwise the cpnversation context is enough, so that succeeded
-   * to call some candidate functions, the `call` agent will step to
-   * the {@link describe} agent to explain the result of the function
-   * calling to the user as markdown content.
-   *
-   * @param ctx Context of the agent
-   * @returns List of prompts generated by the caller
-   * @warning Recommend not to customize, due to its validation
-   *          feedback strategy is working very well, and the `call`
-   *          agent is the most general topic which can be universally
-   *          applied to all domain fields.
-   */
-  call: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
-
-  /**
-   * Describer agent of the function calling result.
-   *
-   * `Describe` agent explains the results of the function callings
-   * to the user as markdown content.
-   *
-   * @param ctx Context of the agent
-   * @param executes List of function calling results
-   * @returns List of prompts generated by the describer
-   */
-  describe: (
-    ctx: IAgenticaContext<Model>,
-    executes: IAgenticaPrompt.IExecute<Model>[],
-  ) => Promise<IAgenticaPrompt<Model>[]>;
-
-  /**
-   * Function canceler agent.
-   *
-   * `Cancel` agent erases the candidate functions from the
-   * {@link IAgenticaContext.stack} by analyzing the conversation
-   * context with the user.
-   *
-   * For reference, the first reason of the cancelation is explicit
-   * order from user to the previous requested function. For example,
-   * user had requested to send an email to the agent, but suddenly
-   * user says to cancel the email sending.
-   *
-   * The seconod reason n of the cancelation is the multiple candidate
-   * functions had been selected at once by the {@link select} agent
-   * due to lack of conversation context or homogeneity between the
-   * heterogeneous functions. And in the multiple candidate functions,
-   * one thing is clearly determined by the {@link call} agent, so that
-   * drop the other candidate functions.
-   *
-   * @param ctx Context of the agent
-   * @returns List of prompts generated by the canceler
-   */
-  cancel: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
-}
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaContext } from "./IAgenticaContext";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+
+/**
+ * Executor of the Agentic AI.
+ *
+ * `IAgenticaExecutor` represents an executor of the {@link Agentica},
+ * composing its internal agents to accomplish the Agentic AI through
+ * the LLM (Large Language Model) function calling.
+ *
+ * You can customize one of these internal agents by configuring
+ * properties of the `IAgenticaExecutor` type, and assigning it to the
+ * {@link IAgenticaConfig.executor} property. If you set the
+ * {@link initialize} as `null` value, the {@link Agentica} will skip
+ * the initialize process and directly go to the {@link select} process.
+ *
+ * By the way, when customizing the executor member, it would better to
+ * reference the guide documents of `@agentica/core`, and internal
+ * agents' implementation code. It's because if you take some mistake on
+ * the executor logic, it can entirely break the {@link Agentica}'s
+ * operation.
+ *
+ * @reference https://github.com/wrtnlabs/agentica?tab=readme-ov-file#principles
+ * @reference https://github.com/wrtnlabs/agentica/blob/main/packages/agent/src/chatgpt/ChatGptAgent.ts
+ * @author Samchon
+ */
+export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
+  /**
+   * Initializer agent listing up functions.
+   *
+   * `initialize` agent is the first agent that {@link Agentica}
+   * would meet  which judges whether the user's conversation implies
+   * to call some function or not.
+   *
+   * And if the `initialize` agent judges the user's conversation
+   * implies to call some function, the `initialize` agent will
+   * call the {@link IAgenticaContext.initialize} function, and
+   * inform every functions enrolled in the {@link IAgenticaController}
+   * to the AI agent. And then, the `initialize` agent will not never
+   * be called again, and let {@link Agentica} to go to the next
+   * {@link select} agent.
+   *
+   * Otherwise the user's conversation does not imply the request of
+   * function calling, it would just work like plain chatbot, and just
+   * conversate with the user.
+   *
+   * By the way, if you wanna skip the `initialize` agent, you can
+   * do it by configuring the {@link IAgenticaConfig.executor} as
+   * `null` value. In that case, the `initialize` agent will never be
+   * called, and {@link Agentica} just starts from the {@link select}
+   * agent.
+   *
+   * @param ctx Context of the agent
+   * @returns List of prompts generated by the initializer
+   */
+  initialize:
+    | null
+    | ((ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>);
+
+  /**
+   * Function selector agent.
+   *
+   * `Select` agent finds candidate functions to call from the
+   * conversation context with the user. And the candidate functions
+   * would be enrolled to the {@link IAgenticaContext.stack}, and the
+   * next {@link call} agent will perform the LLM (Large Language Model)
+   * function calling.
+   *
+   * Note that, the `select` agent does not perform the LLM function
+   * calling. It ends with just finding the candidate functions to call.
+   *
+   * By the way, if the `select` agent can't specify a certain function
+   * to call due to lack of conversation context or homogeneity between
+   * heterogeneous functions, how `select` agent works? In that case,
+   * `select` agent it will just enroll every candidate functions to
+   * the stack, and let the next {@link call} agent to determine the
+   * proper function to call. And then let {@link cancel} agent to erase
+   * the other candidate functions from the stack.
+   *
+   * Additionally, if `select` agent could not find any candidate
+   * function from the conversation context with user, it would just
+   * act like plain chatbot conversating with the user.
+   *
+   * @param ctx Context of the agent
+   * @returns List of prompts generated by the selector
+   */
+  select: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
+
+  /**
+   * Function caller agent.
+   *
+   * `Call` agent performs the LLM (Large Language Model) function
+   * calling from the candidate functions enrolled in the
+   * {@link IAgenticaContext.stack}. And the scope of function calling
+   * is, not only just arguments filling, but also actual executing
+   * the function and returning the result.
+   *
+   * By the way, conversation context with user can be not enough to
+   * filling the arguments of the candidate functions. In that case,
+   * the `call` agent will ask the user to fill the missing arguments.
+   *
+   * Otherwise the cpnversation context is enough, so that succeeded
+   * to call some candidate functions, the `call` agent will step to
+   * the {@link describe} agent to explain the result of the function
+   * calling to the user as markdown content.
+   *
+   * @param ctx Context of the agent
+   * @returns List of prompts generated by the caller
+   * @warning Recommend not to customize, due to its validation
+   *          feedback strategy is working very well, and the `call`
+   *          agent is the most general topic which can be universally
+   *          applied to all domain fields.
+   */
+  call: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
+
+  /**
+   * Describer agent of the function calling result.
+   *
+   * `Describe` agent explains the results of the function callings
+   * to the user as markdown content.
+   *
+   * @param ctx Context of the agent
+   * @param executes List of function calling results
+   * @returns List of prompts generated by the describer
+   */
+  describe: (
+    ctx: IAgenticaContext<Model>,
+    executes: IAgenticaPrompt.IExecute<Model>[],
+  ) => Promise<IAgenticaPrompt<Model>[]>;
+
+  /**
+   * Function canceler agent.
+   *
+   * `Cancel` agent erases the candidate functions from the
+   * {@link IAgenticaContext.stack} by analyzing the conversation
+   * context with the user.
+   *
+   * For reference, the first reason of the cancelation is explicit
+   * order from user to the previous requested function. For example,
+   * user had requested to send an email to the agent, but suddenly
+   * user says to cancel the email sending.
+   *
+   * The seconod reason n of the cancelation is the multiple candidate
+   * functions had been selected at once by the {@link select} agent
+   * due to lack of conversation context or homogeneity between the
+   * heterogeneous functions. And in the multiple candidate functions,
+   * one thing is clearly determined by the {@link call} agent, so that
+   * drop the other candidate functions.
+   *
+   * @param ctx Context of the agent
+   * @returns List of prompts generated by the canceler
+   */
+  cancel: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
+}

package/src/structures/IAgenticaOperation.ts

@@ -1,64 +1,63 @@
-import { IHttpLlmFunction, ILlmSchema } from "@samchon/openapi";
-import { ILlmFunctionOfValidate } from "typia";
-
-import { IAgenticaController } from "./IAgenticaController";
-
-/**
- * Operation information in the Nestia Agent.
- *
- * `IAgenticaOperation` is a type represents an operation that would
- * be selected by the A.I. chatbot of {@link Agentica} 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 Samchon
- */
-export type IAgenticaOperation<Model extends ILlmSchema.Model> =
-  | IAgenticaOperation.IHttp<Model>
-  | IAgenticaOperation.IClass<Model>;
-export namespace IAgenticaOperation {
-  /**
-   * HTTP API operation.
-   */
-  export type IHttp<Model extends ILlmSchema.Model> = IBase<
-    "http",
-    IAgenticaController.IHttp<Model>,
-    IHttpLlmFunction<Model>
-  >;
-
-  /**
-   * TypeScript class operation.
-   */
-  export type IClass<Model extends ILlmSchema.Model> = IBase<
-    "class",
-    IAgenticaController.IClass<Model>,
-    ILlmFunctionOfValidate<Model>
-  >;
-
-  interface IBase<Protocol, Application, Function> {
-    /**
-     * Protocol discriminator.
-     */
-    protocol: Protocol;
-
-    /**
-     * Belonged controller of the target function.
-     */
-    controller: Application;
-
-    /**
-     * Target function to call.
-     */
-    function: Function;
-
-    /**
-     * Identifier name.
-     */
-    name: string;
-  }
-}
+import { IHttpLlmFunction, ILlmFunction, ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaController } from "./IAgenticaController";
+
+/**
+ * Operation information in the Nestia Agent.
+ *
+ * `IAgenticaOperation` is a type represents an operation that would
+ * be selected by the A.I. chatbot of {@link Agentica} 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 Samchon
+ */
+export type IAgenticaOperation<Model extends ILlmSchema.Model> =
+  | IAgenticaOperation.IHttp<Model>
+  | IAgenticaOperation.IClass<Model>;
+export namespace IAgenticaOperation {
+  /**
+   * HTTP API operation.
+   */
+  export type IHttp<Model extends ILlmSchema.Model> = IBase<
+    "http",
+    IAgenticaController.IHttp<Model>,
+    IHttpLlmFunction<Model>
+  >;
+
+  /**
+   * TypeScript class operation.
+   */
+  export type IClass<Model extends ILlmSchema.Model> = IBase<
+    "class",
+    IAgenticaController.IClass<Model>,
+    ILlmFunction<Model>
+  >;
+
+  interface IBase<Protocol, Application, Function> {
+    /**
+     * Protocol discriminator.
+     */
+    protocol: Protocol;
+
+    /**
+     * Belonged controller of the target function.
+     */
+    controller: Application;
+
+    /**
+     * Target function to call.
+     */
+    function: Function;
+
+    /**
+     * Identifier name.
+     */
+    name: string;
+  }
+}

package/src/structures/IAgenticaOperationCollection.ts

@@ -1,52 +1,52 @@
-import { ILlmSchema } from "@samchon/openapi";
-
-import { IAgenticaOperation } from "./IAgenticaOperation";
-
-/**
- * Collection of operations used in the Nestia Agent.
- *
- * `IAgenticaOperationCollection` is an interface type representing
- * a collection of operations for several purposes used in the
- * {@link Agentica} internally.
- *
- * @author Samchon
- */
-export interface IAgenticaOperationCollection<Model extends ILlmSchema.Model> {
-  /**
-   * List of every operations.
-   */
-  array: IAgenticaOperation<Model>[];
-
-  /**
-   * Divided operations.
-   *
-   * If you've configured the {@link IAgenticaConfig.capacity} property,
-   * the  A.I. chatbot ({@link Agentica}) 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 IAgenticaConfig.capacity}.
-   *
-   * Otherwise, if the {@link IAgenticaConfig.capacity} has not been
-   * configured, this `divided` property would be the `undefined` value.
-   */
-  divided?: IAgenticaOperation<Model>[][] | undefined;
-
-  /**
-   * Flat dictionary of operations.
-   *
-   * Dictionary of operations with their {@link IAgenticaOperation.name}.
-   */
-  flat: Map<string, IAgenticaOperation<Model>>;
-
-  /**
-   * Group dictionary of operations.
-   *
-   * Dictionary of operations with their
-   * {@link IAgenticaOperation.controller.name} and
-   * {@link IAgenticaOperation.function.name}.
-   */
-  group: Map<string, Map<string, IAgenticaOperation<Model>>>;
-}
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaOperation } from "./IAgenticaOperation";
+
+/**
+ * Collection of operations used in the Nestia Agent.
+ *
+ * `IAgenticaOperationCollection` is an interface type representing
+ * a collection of operations for several purposes used in the
+ * {@link Agentica} internally.
+ *
+ * @author Samchon
+ */
+export interface IAgenticaOperationCollection<Model extends ILlmSchema.Model> {
+  /**
+   * List of every operations.
+   */
+  array: IAgenticaOperation<Model>[];
+
+  /**
+   * Divided operations.
+   *
+   * If you've configured the {@link IAgenticaConfig.capacity} property,
+   * the  A.I. chatbot ({@link Agentica}) 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 IAgenticaConfig.capacity}.
+   *
+   * Otherwise, if the {@link IAgenticaConfig.capacity} has not been
+   * configured, this `divided` property would be the `undefined` value.
+   */
+  divided?: IAgenticaOperation<Model>[][] | undefined;
+
+  /**
+   * Flat dictionary of operations.
+   *
+   * Dictionary of operations with their {@link IAgenticaOperation.name}.
+   */
+  flat: Map<string, IAgenticaOperation<Model>>;
+
+  /**
+   * Group dictionary of operations.
+   *
+   * Dictionary of operations with their
+   * {@link IAgenticaOperation.controller.name} and
+   * {@link IAgenticaOperation.function.name}.
+   */
+  group: Map<string, Map<string, IAgenticaOperation<Model>>>;
+}