@agentica/core 0.43.2 → 0.44.0-dev.20260313

package/src/structures/IAgenticaConfig.ts

@@ -1,83 +1,83 @@
-import type { AgenticaContext } from "../context/AgenticaContext";
-
-import type { IAgenticaConfigBase } from "./IAgenticaConfigBase";
-import type { IAgenticaExecutor } from "./IAgenticaExecutor";
-import type { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
-
-/**
- * Configuration for Agentic Agent.
- *
- * `IAgenticaConfig` is an interface that defines the configuration
- * properties of the {@link Agentica}. With this configuration, you
- * can set the user's {@link locale}, {@link timezone}, and some of
- * {@link systemPrompt 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 AI 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 extends IAgenticaConfigBase {
-  /**
-   * 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
-   * @default ChatGptAgent.execute
-   */
-  executor?:
-    | Partial<IAgenticaExecutor>
-    | ((ctx: AgenticaContext) => Promise<void>);
-
-  /**
-   * System prompt messages.
-   *
-   * System prompt messages if you want to customize the system prompt
-   * messages for each situation.
-   */
-  systemPrompt?: IAgenticaSystemPrompt;
-
-  /**
-   * 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;
-}
+import type { AgenticaContext } from "../context/AgenticaContext";
+
+import type { IAgenticaConfigBase } from "./IAgenticaConfigBase";
+import type { IAgenticaExecutor } from "./IAgenticaExecutor";
+import type { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
+
+/**
+ * Configuration for Agentic Agent.
+ *
+ * `IAgenticaConfig` is an interface that defines the configuration
+ * properties of the {@link Agentica}. With this configuration, you
+ * can set the user's {@link locale}, {@link timezone}, and some of
+ * {@link systemPrompt 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 AI 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 extends IAgenticaConfigBase {
+  /**
+   * 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
+   * @default ChatGptAgent.execute
+   */
+  executor?:
+    | Partial<IAgenticaExecutor>
+    | ((ctx: AgenticaContext) => Promise<void>);
+
+  /**
+   * System prompt messages.
+   *
+   * System prompt messages if you want to customize the system prompt
+   * messages for each situation.
+   */
+  systemPrompt?: IAgenticaSystemPrompt;
+
+  /**
+   * 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;
+}

package/src/structures/IAgenticaConfigBase.ts

@@ -1,87 +1,87 @@
-/**
- * Configuration for Agentic Agent.
- *
- * `IAgenticaConfig` is an interface that defines the configuration
- * properties of the {@link Agentica}. With this configuration, you
- * can set the user's {@link locale}, {@link timezone}, and some of
- * {@link systemPrompt 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 AI 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 sunrabbit123
- */
-export interface IAgenticaConfigBase {
-
-  /**
-   * 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;
-
-  /**
-   * Backoff strategy.
-   *
-   * If OpenAI SDK fails to connect LLM API Server, this Backoff factor
-   * would be used to retry for the next connection.
-   *
-   * If the function returns `true`, the retry would be stopped.
-   * Otherwise, the retry would be continued.
-   *
-   * @default (props) => throw props.error
-   * @returns {number} The number of milliseconds to wait before the next retry
-   * @throws {Error} If the function want to stop the retry, you can throw an error
-   */
-  backoffStrategy?: (props: {
-    count: number;
-    error: unknown;
-  }) => number;
-
-  /**
-   * Whether to enable streaming.
-   *
-   * If you set this property to `true`, the A.I. chatbot will enable streaming.
-   *
-   * If you set this property to `false`, the A.I. chatbot will not enable streaming.
-   *
-   * @default true
-   */
-  stream?: boolean;
-}
+/**
+ * Configuration for Agentic Agent.
+ *
+ * `IAgenticaConfig` is an interface that defines the configuration
+ * properties of the {@link Agentica}. With this configuration, you
+ * can set the user's {@link locale}, {@link timezone}, and some of
+ * {@link systemPrompt 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 AI 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 sunrabbit123
+ */
+export interface IAgenticaConfigBase {
+
+  /**
+   * 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;
+
+  /**
+   * Backoff strategy.
+   *
+   * If OpenAI SDK fails to connect LLM API Server, this Backoff factor
+   * would be used to retry for the next connection.
+   *
+   * If the function returns `true`, the retry would be stopped.
+   * Otherwise, the retry would be continued.
+   *
+   * @default (props) => throw props.error
+   * @returns {number} The number of milliseconds to wait before the next retry
+   * @throws {Error} If the function want to stop the retry, you can throw an error
+   */
+  backoffStrategy?: (props: {
+    count: number;
+    error: unknown;
+  }) => number;
+
+  /**
+   * Whether to enable streaming.
+   *
+   * If you set this property to `true`, the A.I. chatbot will enable streaming.
+   *
+   * If you set this property to `false`, the A.I. chatbot will not enable streaming.
+   *
+   * @default true
+   */
+  stream?: boolean;
+}

package/src/structures/IAgenticaController.ts

@@ -1,151 +1,143 @@
-import type {
-  IHttpConnection,
-  IHttpLlmApplication,
-  IHttpLlmFunction,
-  IHttpResponse,
-  ILlmApplication,
-  ILlmFunction,
-  IMcpLlmApplication,
-} from "@samchon/openapi";
-
-/**
- * Controller of the Agentica Agent.
- *
- * `IAgenticaController` is a type represents a controller of the
- * {@link Agentica}, which serves a set of functions to be called
- * by A.I. chatbot from LLM function calling.
- *
- * Also, `IAgenticaController` is an union type which can specify
- * a subtype by checking the {@link protocol} property.
- *
- * - HTTP server: {@link IAgenticaController.IHttp}
- * - TypeScript class: {@link IAgenticaController.IClass}
- * - MCP Server: {@link IAgenticaController.IMcp}
- *
- * @author Samchon
- */
-export type IAgenticaController =
-  | IAgenticaController.IHttp
-  | IAgenticaController.IClass
-  | IAgenticaController.IMcp;
-
-export namespace IAgenticaController {
-  /**
-   * HTTP controller.
-   *
-   * You can make it by {@link validateHttpLlmApplication} function with
-   * the Swagger or OpenAPI document.
-   */
-  export interface IHttp extends IBase<"http", IHttpLlmApplication> {
-    /**
-     * 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;
-
-      /**
-       * Function schema.
-       */
-      function: IHttpLlmFunction;
-
-      /**
-       * 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", ILlmApplication> {
-    /**
-     * Executor of the class function.
-     *
-     * Executor of the class function, by target class instance
-     * or callback function with given schema and arguments
-     * information.
-     */
-    execute:
-      | object
-      | ((props: {
-        /**
-         * Target application schema.
-         */
-        application: ILlmApplication;
-
-        /**
-         * Target function schema.
-         */
-        function: ILlmFunction;
-
-        /**
-         * Arguments of the function calling.
-         */
-        arguments: object;
-      }) => Promise<unknown>);
-  }
-
-  /**
-   * MCP Server controller.
-   */
-  export interface IMcp extends IBase<"mcp", IMcpLlmApplication> {
-    /**
-     * MCP client for connection.
-     *
-     * @warning You have to install `@modelcontextprotocol/sdk` package
-     *          to use this type properly. If not, this type would work
-     *          as an `any` type, so that you can't validate it.
-     */
-    // @ts-ignore Type checking only when `@modelcontextprotocol/sdk` is installed.
-    //            This strategy is useful for someone who does not need MCP,
-    //            for someone who has not installed `@modelcontextprotocol/sdk`.
-    client: import("@modelcontextprotocol/sdk/client/index.d.ts").Client;
-  }
-
-  interface IBase<Protocol, Application> {
-    /**
-     * Protocol discrminator.
-     */
-    protocol: Protocol;
-
-    /**
-     * Name of the controller.
-     */
-    name: string;
-
-    /**
-     * Application schema of function calling.
-     */
-    application: Application;
-  }
-}
+import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, ILlmApplication, ILlmFunction } from "@typia/interface";
+
+/**
+ * Controller of the Agentica Agent.
+ *
+ * `IAgenticaController` is a type represents a controller of the
+ * {@link Agentica}, which serves a set of functions to be called
+ * by A.I. chatbot from LLM function calling.
+ *
+ * Also, `IAgenticaController` is an union type which can specify
+ * a subtype by checking the {@link protocol} property.
+ *
+ * - HTTP server: {@link IAgenticaController.IHttp}
+ * - TypeScript class: {@link IAgenticaController.IClass}
+ * - MCP Server: {@link IAgenticaController.IMcp}
+ *
+ * @author Samchon
+ */
+export type IAgenticaController
+  = | IAgenticaController.IHttp
+    | IAgenticaController.IClass
+    | IAgenticaController.IMcp;
+
+export namespace IAgenticaController {
+  /**
+   * HTTP controller.
+   *
+   * You can make it by {@link validateHttpLlmApplication} function with
+   * the Swagger or OpenAPI document.
+   */
+  export interface IHttp extends IBase<"http", IHttpLlmApplication> {
+    /**
+     * 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;
+
+      /**
+       * Function schema.
+       */
+      function: IHttpLlmFunction;
+
+      /**
+       * 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", ILlmApplication> {
+    /**
+     * Executor of the class function.
+     *
+     * Executor of the class function, by target class instance
+     * or callback function with given schema and arguments
+     * information.
+     */
+    execute:
+      | object
+      | ((props: {
+        /**
+         * Target application schema.
+         */
+        application: ILlmApplication;
+
+        /**
+         * Target function schema.
+         */
+        function: ILlmFunction;
+
+        /**
+         * Arguments of the function calling.
+         */
+        arguments: object;
+      }) => Promise<unknown>);
+  }
+
+  /**
+   * MCP Server controller.
+   */
+  export interface IMcp extends IBase<"mcp", ILlmApplication> {
+    /**
+     * MCP client for connection.
+     *
+     * @warning You have to install `@modelcontextprotocol/sdk` package
+     *          to use this type properly. If not, this type would work
+     *          as an `any` type, so that you can't validate it.
+     */
+    // @ts-ignore Type checking only when `@modelcontextprotocol/sdk` is installed.
+    //            This strategy is useful for someone who does not need MCP,
+    //            for someone who has not installed `@modelcontextprotocol/sdk`.
+    client: import("@modelcontextprotocol/sdk/client/index.d.ts").Client;
+  }
+
+  interface IBase<Protocol, Application> {
+    /**
+     * Protocol discrminator.
+     */
+    protocol: Protocol;
+
+    /**
+     * Name of the controller.
+     */
+    name: string;
+
+    /**
+     * Application schema of function calling.
+     */
+    application: Application;
+  }
+}