@agentica/core 0.8.3 → 0.9.0-dev.20250302

package/src/structures/IAgenticaProvider.ts

@@ -1,45 +1,39 @@
-import OpenAI from "openai";
-
-/**
- * LLM Provider for Nestia Chat.
- *
- * `IAgenticaProvider` is a type represents an LLM
- * (Large Language Model) provider of the {@link Agentica}.
- *
- * Currently, {@link Agentica} 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 Samchon
- */
-export type IAgenticaProvider = IAgenticaProvider.IChatGpt;
-export namespace IAgenticaProvider {
-  /**
-   * OpenAI provider.
-   */
-  export interface IChatGpt {
-    /**
-     * Discriminator type.
-     */
-    type: "chatgpt";
-
-    /**
-     * OpenAI API instance.
-     */
-    api: OpenAI;
-
-    /**
-     * Chat model to be used.
-     */
-    model: OpenAI.ChatModel;
-
-    /**
-     * Options for the request.
-     */
-    options?: OpenAI.RequestOptions | undefined;
-  }
-}
+import OpenAI from "openai";
+
+/**
+ * LLM Provider for Nestia Chat.
+ *
+ * `IAgenticaProvider` is a type represents an LLM
+ * (Large Language Model) provider of the {@link Agentica}.
+ *
+ * Currently, {@link Agentica} supports OpenAI SDK. However, it does
+ * not mean that you can use only OpenAI's GPT model in the
+ * {@link Agentica}. The OpenAI SDK is just a connection tool to the
+ * LLM provider's API, and you can use other LLM providers by configuring
+ * its `baseURL` and API key.
+ *
+ * Therefore, if you want to use another LLM provider like Claude or
+ * Gemini, please configure the `baseURL` to the {@link api}, and
+ * set {@link IAgenticaController}'s schema model as "cluade" or
+ * "gemini".
+ *
+ * @author Samchon
+ */
+export interface IAgenticaProvider {
+  /**
+   * OpenAI API instance.
+   */
+  api: OpenAI;
+
+  /**
+   * Chat model to be used.
+   *
+   * `({}) & string` means to support third party hosting cloud(eg. openRouter, aws)
+   */
+  model: OpenAI.ChatModel | ({} & string);
+
+  /**
+   * Options for the request.
+   */
+  options?: OpenAI.RequestOptions | undefined;
+}

package/src/structures/IAgenticaSystemPrompt.ts

@@ -1,122 +1,124 @@
-import { IAgenticaConfig } from "./IAgenticaConfig";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
-
-/**
- * System prompt collection of the A.I. chatbot.
- *
- * `IAgenticaSystemPrompt` is a type represents a collection of system
- * prompts that would be used by the A.I. chatbot of {@link Agentica}.
- *
- * You can customize the system prompt by configuring the
- * {@link IAgenticaConfig.systemPrompt} property when creating a new
- * {@link Agentica} instance.
- *
- * If you don't configure any system prompts, the default system prompts
- * would be used which are written in the below directory as markdown
- * documents.
- *
- * - https://github.com/samchon/nestia/tree/master/packages/agent/prompts
- *
- * @author Samchon
- */
-export interface IAgenticaSystemPrompt {
-  /**
-   * Common system prompt that would be used in every situation.
-   *
-   * @param config Configuration of the agent
-   * @returns The common system prompt
-   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/common.md
-   */
-  common?: (config?: IAgenticaConfig | undefined) => string;
-
-  /**
-   * Initialize system prompt.
-   *
-   * When the A.I. chatbot has not informed any functions to the agent
-   * yet because the user has not implied any function calling request yet,
-   * {@link Agentica} says that it is a circumstance that nothing has
-   * been initialized yet.
-   *
-   * In that case, the `initialize` system prompt would be used. You can
-   * customize the `initialize` system prompt by assigning this function
-   * with the given {@link IAgenticaPrompt histories} parameter.
-   *
-   * @param histories Histories of the previous prompts
-   * @returns initialize system prompt
-   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/initialize.md
-   */
-  initialize?: (histories: IAgenticaPrompt[]) => string;
-
-  /**
-   * Select system prompt.
-   *
-   * The {@link Agentica} has a process selecting some candidate
-   * functions to call by asking to the A.I. agent with the previous
-   * prompt histories.
-   *
-   * In that case, this `select` system prompt would be used. You can
-   * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
-   *
-   * Note that, the `"select"` means only the function selection. It does
-   * not contain the filling argument or executing the function. It
-   * literally contains only the selection process.
-   *
-   * @param histories Histories of the previous prompts
-   * @returns select system promopt
-   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/select.md
-   */
-  select?: (histories: IAgenticaPrompt[]) => string;
-
-  /**
-   * Cancel system prompt.
-   *
-   * The {@link Agentica} has a process canceling some candidate
-   * functions to call by asking to the A.I. agent with the previous
-   * prompt histories.
-   *
-   * In that case, this `cancel` system prompt would be used. You can
-   * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
-   *
-   * @param histories Histories of the previous prompts
-   * @returns cancel system prompt
-   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/cancel.md
-   */
-  cancel?: (histories: IAgenticaPrompt[]) => string;
-
-  /**
-   * Execute system prompt.
-   *
-   * The {@link Agentica} has a process filling the arguments of some
-   * selected candidate functions by the LLM (Large Language Model)
-   * function calling feature with the previous prompt histories, and
-   * executing the arguments filled function with validation feedback.
-   *
-   * In that case, this `execute` system prompt would be used. You can
-   * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
-   *
-   * @param histories Histories of the previous prompts
-   * @returns execute system prompt
-   * https://github.com/samchon/nestia/blob/master/packages/agent/prompts/execute.md
-   */
-  execute?: (histories: IAgenticaPrompt[]) => string;
-
-  /**
-   * Describe system prompt.
-   *
-   * The {@link Agentica} has a process describing the return values of
-   * the executed functions by requesting to the A.I. agent with the
-   * previous prompt histories.
-   *
-   * In that case, this `describe` system prompt would be used. You can
-   * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
-   *
-   * @param histories Histories of the previous prompts
-   * @returns describe system prompt
-   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/describe.md
-   */
-  describe?: (histories: IAgenticaPrompt.IExecute[]) => string;
-}
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaConfig } from "./IAgenticaConfig";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+
+/**
+ * System prompt collection of the A.I. chatbot.
+ *
+ * `IAgenticaSystemPrompt` is a type represents a collection of system
+ * prompts that would be used by the A.I. chatbot of {@link Agentica}.
+ *
+ * You can customize the system prompt by configuring the
+ * {@link IAgenticaConfig.systemPrompt} property when creating a new
+ * {@link Agentica} instance.
+ *
+ * If you don't configure any system prompts, the default system prompts
+ * would be used which are written in the below directory as markdown
+ * documents.
+ *
+ * - https://github.com/samchon/nestia/tree/master/packages/agent/prompts
+ *
+ * @author Samchon
+ */
+export interface IAgenticaSystemPrompt<Model extends ILlmSchema.Model> {
+  /**
+   * Common system prompt that would be used in every situation.
+   *
+   * @param config Configuration of the agent
+   * @returns The common system prompt
+   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/common.md
+   */
+  common?: (config?: IAgenticaConfig<Model> | undefined) => string;
+
+  /**
+   * Initialize system prompt.
+   *
+   * When the A.I. chatbot has not informed any functions to the agent
+   * yet because the user has not implied any function calling request yet,
+   * {@link Agentica} says that it is a circumstance that nothing has
+   * been initialized yet.
+   *
+   * In that case, the `initialize` system prompt would be used. You can
+   * customize the `initialize` system prompt by assigning this function
+   * with the given {@link IAgenticaPrompt histories} parameter.
+   *
+   * @param histories Histories of the previous prompts
+   * @returns initialize system prompt
+   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/initialize.md
+   */
+  initialize?: (histories: IAgenticaPrompt<Model>[]) => string;
+
+  /**
+   * Select system prompt.
+   *
+   * The {@link Agentica} has a process selecting some candidate
+   * functions to call by asking to the A.I. agent with the previous
+   * prompt histories.
+   *
+   * In that case, this `select` system prompt would be used. You can
+   * customize it by assigning this function with the given
+   * {@link IAgenticaPrompt histories} parameter.
+   *
+   * Note that, the `"select"` means only the function selection. It does
+   * not contain the filling argument or executing the function. It
+   * literally contains only the selection process.
+   *
+   * @param histories Histories of the previous prompts
+   * @returns select system promopt
+   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/select.md
+   */
+  select?: (histories: IAgenticaPrompt<Model>[]) => string;
+
+  /**
+   * Cancel system prompt.
+   *
+   * The {@link Agentica} has a process canceling some candidate
+   * functions to call by asking to the A.I. agent with the previous
+   * prompt histories.
+   *
+   * In that case, this `cancel` system prompt would be used. You can
+   * customize it by assigning this function with the given
+   * {@link IAgenticaPrompt histories} parameter.
+   *
+   * @param histories Histories of the previous prompts
+   * @returns cancel system prompt
+   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/cancel.md
+   */
+  cancel?: (histories: IAgenticaPrompt<Model>[]) => string;
+
+  /**
+   * Execute system prompt.
+   *
+   * The {@link Agentica} has a process filling the arguments of some
+   * selected candidate functions by the LLM (Large Language Model)
+   * function calling feature with the previous prompt histories, and
+   * executing the arguments filled function with validation feedback.
+   *
+   * In that case, this `execute` system prompt would be used. You can
+   * customize it by assigning this function with the given
+   * {@link IAgenticaPrompt histories} parameter.
+   *
+   * @param histories Histories of the previous prompts
+   * @returns execute system prompt
+   * https://github.com/samchon/nestia/blob/master/packages/agent/prompts/execute.md
+   */
+  execute?: (histories: IAgenticaPrompt<Model>[]) => string;
+
+  /**
+   * Describe system prompt.
+   *
+   * The {@link Agentica} has a process describing the return values of
+   * the executed functions by requesting to the A.I. agent with the
+   * previous prompt histories.
+   *
+   * In that case, this `describe` system prompt would be used. You can
+   * customize it by assigning this function with the given
+   * {@link IAgenticaPrompt histories} parameter.
+   *
+   * @param histories Histories of the previous prompts
+   * @returns describe system prompt
+   * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/describe.md
+   */
+  describe?: (histories: IAgenticaPrompt.IExecute<Model>[]) => string;
+}

package/src/structures/IAgenticaTokenUsage.ts

@@ -1,107 +1,107 @@
-/**
- * Token usage information from the A.I. chatbot.
- *
- * `IAgenticaTokenUsage` is a structure representing the token usage
- * information from the {@link Agentica} class. And you can get the
- * token usage information by calling the {@link Agentica.getTokenUsage}
- * method.
- *
- * For reference, `IAgenticaTokenUsage` provides only the token usage
- * information, and does not contain any price or cost information. It is
- * because the price or cost can be changed by below reasons.
- *
- * - Type of {@link IAgenticaProps.provider LLM provider}
- * - {@link IAgenticaProvider.model} in the LLM provider.
- * - Just by a policy change of the LLM provider company.
- *
- * @author Samchon
- */
-export interface IAgenticaTokenUsage {
-  /**
-   * Aggregated token usage.
-   */
-  aggregate: IAgenticaTokenUsage.IComponent;
-
-  /**
-   * Token uasge of initializer agent.
-   */
-  initialize: IAgenticaTokenUsage.IComponent;
-
-  /**
-   * Token usage of function selector agent.
-   */
-  select: IAgenticaTokenUsage.IComponent;
-
-  /**
-   * Token usage of function canceler agent.
-   */
-  cancel: IAgenticaTokenUsage.IComponent;
-
-  /**
-   * Token usage of function caller agent.
-   */
-  call: IAgenticaTokenUsage.IComponent;
-
-  /**
-   * Token usage of function calling describer agent.
-   */
-  describe: IAgenticaTokenUsage.IComponent;
-}
-export namespace IAgenticaTokenUsage {
-  export interface IComponent {
-    /**
-     * Total token usage.
-     */
-    total: number;
-
-    /**
-     * Input token usage of detailed.
-     */
-    input: IInput;
-
-    /**
-     * Output token usage of detailed.
-     */
-    output: IOutput;
-  }
-
-  /**
-   * Input token usage of detailed.
-   */
-  export interface IInput {
-    /**
-     * Total amount of input token uasge.
-     */
-    total: number;
-
-    /**
-     * Cached token usage.
-     */
-    cached: number;
-  }
-
-  /**
-   * Output token usage of detailed.
-   */
-  export interface IOutput {
-    /**
-     * Total amount of output token usage.
-     */
-    total: number;
-
-    /**
-     * Reasoning token usage.
-     */
-    reasoning: number;
-
-    /**
-     * Prediction token usage.
-     */
-    accepted_prediction: number;
-
-    /**
-     * Rejected prediction token usage.
-     */
-    rejected_prediction: number;
-  }
-}
+/**
+ * Token usage information from the A.I. chatbot.
+ *
+ * `IAgenticaTokenUsage` is a structure representing the token usage
+ * information from the {@link Agentica} class. And you can get the
+ * token usage information by calling the {@link Agentica.getTokenUsage}
+ * method.
+ *
+ * For reference, `IAgenticaTokenUsage` provides only the token usage
+ * information, and does not contain any price or cost information. It is
+ * because the price or cost can be changed by below reasons.
+ *
+ * - Type of {@link IAgenticaProps.provider LLM provider}
+ * - {@link IAgenticaProvider.model} in the LLM provider.
+ * - Just by a policy change of the LLM provider company.
+ *
+ * @author Samchon
+ */
+export interface IAgenticaTokenUsage {
+  /**
+   * Aggregated token usage.
+   */
+  aggregate: IAgenticaTokenUsage.IComponent;
+
+  /**
+   * Token uasge of initializer agent.
+   */
+  initialize: IAgenticaTokenUsage.IComponent;
+
+  /**
+   * Token usage of function selector agent.
+   */
+  select: IAgenticaTokenUsage.IComponent;
+
+  /**
+   * Token usage of function canceler agent.
+   */
+  cancel: IAgenticaTokenUsage.IComponent;
+
+  /**
+   * Token usage of function caller agent.
+   */
+  call: IAgenticaTokenUsage.IComponent;
+
+  /**
+   * Token usage of function calling describer agent.
+   */
+  describe: IAgenticaTokenUsage.IComponent;
+}
+export namespace IAgenticaTokenUsage {
+  export interface IComponent {
+    /**
+     * Total token usage.
+     */
+    total: number;
+
+    /**
+     * Input token usage of detailed.
+     */
+    input: IInput;
+
+    /**
+     * Output token usage of detailed.
+     */
+    output: IOutput;
+  }
+
+  /**
+   * Input token usage of detailed.
+   */
+  export interface IInput {
+    /**
+     * Total amount of input token uasge.
+     */
+    total: number;
+
+    /**
+     * Cached token usage.
+     */
+    cached: number;
+  }
+
+  /**
+   * Output token usage of detailed.
+   */
+  export interface IOutput {
+    /**
+     * Total amount of output token usage.
+     */
+    total: number;
+
+    /**
+     * Reasoning token usage.
+     */
+    reasoning: number;
+
+    /**
+     * Prediction token usage.
+     */
+    accepted_prediction: number;
+
+    /**
+     * Rejected prediction token usage.
+     */
+    rejected_prediction: number;
+  }
+}

package/src/structures/internal/__IChatCancelFunctionsApplication.ts

@@ -1,23 +1,23 @@
-import { __IChatFunctionReference } from "./__IChatFunctionReference";
-
-export interface __IChatCancelFunctionsApplication {
-  /**
-   * Cancel a function from the candidate list to call.
-   *
-   * If you A.I. agent has understood that the user wants to cancel
-   * some candidate functions to call from the conversation, please cancel
-   * them through this function.
-   *
-   * Also, when you A.I. find a function that has been selected by the candidate
-   * pooling, cancel the function by calling this function. For reference, the
-   * candidate pooling means that user wants only one function to call, but you A.I.
-   * agent selects multiple candidate functions because the A.I. agent can't specify
-   * only one thing due to lack of specificity or homogeneity of candidate functions.
-   *
-   * Additionally, if you A.I. agent wants to cancel same function multiply, you can
-   * do it by assigning the same function name multiply in the `functions` property.
-   *
-   * @param props Properties of the function
-   */
-  cancelFunctions(props: __IChatFunctionReference.IProps): Promise<void>;
-}
+import { __IChatFunctionReference } from "./__IChatFunctionReference";
+
+export interface __IChatCancelFunctionsApplication {
+  /**
+   * Cancel a function from the candidate list to call.
+   *
+   * If you A.I. agent has understood that the user wants to cancel
+   * some candidate functions to call from the conversation, please cancel
+   * them through this function.
+   *
+   * Also, when you A.I. find a function that has been selected by the candidate
+   * pooling, cancel the function by calling this function. For reference, the
+   * candidate pooling means that user wants only one function to call, but you A.I.
+   * agent selects multiple candidate functions because the A.I. agent can't specify
+   * only one thing due to lack of specificity or homogeneity of candidate functions.
+   *
+   * Additionally, if you A.I. agent wants to cancel same function multiply, you can
+   * do it by assigning the same function name multiply in the `functions` property.
+   *
+   * @param props Properties of the function
+   */
+  cancelFunctions(props: __IChatFunctionReference.IProps): Promise<void>;
+}

package/src/structures/internal/__IChatFunctionReference.ts

@@ -1,21 +1,21 @@
-export interface __IChatFunctionReference {
-  /**
-   * The reason of the function selection.
-   *
-   * Just write the reason why you've determined to select this function.
-   */
-  reason: string;
-
-  /**
-   * Name of the target function to call.
-   */
-  name: string;
-}
-export namespace __IChatFunctionReference {
-  export interface IProps {
-    /**
-     * List of target functions.
-     */
-    functions: __IChatFunctionReference[];
-  }
-}
+export interface __IChatFunctionReference {
+  /**
+   * The reason of the function selection.
+   *
+   * Just write the reason why you've determined to select this function.
+   */
+  reason: string;
+
+  /**
+   * Name of the target function to call.
+   */
+  name: string;
+}
+export namespace __IChatFunctionReference {
+  export interface IProps {
+    /**
+     * List of target functions.
+     */
+    functions: __IChatFunctionReference[];
+  }
+}