@agentica/core 0.44.0-dev.20260313-2 → 0.44.0

package/src/structures/IMcpTool.ts

@@ -1,60 +1,60 @@
-import type { OpenApiV3_2 } from "@typia/interface";
-
-/**
- * MCP tool type.
- *
- * `IMcpTool` is an interface representing a tool type defined in the MCP (Model
- * Context Protocol).
- *
- * Note that, don't be confused with {@link IMcpLlmFunction} type, that is used
- * for {@link McpLlm.application} which converts this `IMcpTool` type to the
- * {@link IMcpLlmFunction} type.
- *
- * @author Samchon
- * @warning Don't be confused with {@link IMcpLlmFunction}
- */
-export interface IMcpTool {
-  /**
-   * Name of the tool.
-   *
-   * @maxLength 64
-   */
-  name: string;
-
-  /** Description of the tool. */
-  description?: string | undefined;
-
-  /**
-   * Input schema of the tool.
-   *
-   * The input schema, parameters of the tool.
-   *
-   * As MCP (Model Context Protocol) does not restrict the JSON schema
-   * specification, `@typia/interface` has defined it to be universal structure
-   * {@link OpenApiV3_2.IJsonSchema} which can cover every JSON schema
-   * specification.
-   */
-  inputSchema: IMcpTool.IParameters;
-
-  outputSchema?: IMcpTool.IParameters | undefined;
-}
-export namespace IMcpTool {
-
-  /**
-   * Input and output schema of the tool.
-   *
-   * The input and output schemas, parameters of the tool.
-   *
-   * As MCP (Model Context Protocol) does not restrict the JSON schema
-   * specification, `@typia/interface` has defined it to be universal structure
-   * {@link OpenApiV3_2.IJsonSchema} which can cover every JSON schema
-   * specification.
-   */
-  export type IParameters = (
-    | OpenApiV3_2.IJsonSchema.IObject
-    | OpenApiV3_2.IJsonSchema.IReference
-  ) & {
-    /** Collection of the named schemas. */
-    $defs?: Record<string, OpenApiV3_2.IJsonSchema>;
-  };
-}
+import type { OpenApiV3_2 } from "@typia/interface";
+
+/**
+ * MCP tool type.
+ *
+ * `IMcpTool` is an interface representing a tool type defined in the MCP (Model
+ * Context Protocol).
+ *
+ * Note that, don't be confused with {@link IMcpLlmFunction} type, that is used
+ * for {@link McpLlm.application} which converts this `IMcpTool` type to the
+ * {@link IMcpLlmFunction} type.
+ *
+ * @author Samchon
+ * @warning Don't be confused with {@link IMcpLlmFunction}
+ */
+export interface IMcpTool {
+  /**
+   * Name of the tool.
+   *
+   * @maxLength 64
+   */
+  name: string;
+
+  /** Description of the tool. */
+  description?: string | undefined;
+
+  /**
+   * Input schema of the tool.
+   *
+   * The input schema, parameters of the tool.
+   *
+   * As MCP (Model Context Protocol) does not restrict the JSON schema
+   * specification, `@typia/interface` has defined it to be universal structure
+   * {@link OpenApiV3_2.IJsonSchema} which can cover every JSON schema
+   * specification.
+   */
+  inputSchema: IMcpTool.IParameters;
+
+  outputSchema?: IMcpTool.IParameters | undefined;
+}
+export namespace IMcpTool {
+
+  /**
+   * Input and output schema of the tool.
+   *
+   * The input and output schemas, parameters of the tool.
+   *
+   * As MCP (Model Context Protocol) does not restrict the JSON schema
+   * specification, `@typia/interface` has defined it to be universal structure
+   * {@link OpenApiV3_2.IJsonSchema} which can cover every JSON schema
+   * specification.
+   */
+  export type IParameters = (
+    | OpenApiV3_2.IJsonSchema.IObject
+    | OpenApiV3_2.IJsonSchema.IReference
+  ) & {
+    /** Collection of the named schemas. */
+    $defs?: Record<string, OpenApiV3_2.IJsonSchema>;
+  };
+}

package/src/structures/IMicroAgenticaConfig.ts

@@ -1,56 +1,56 @@
-import type { IAgenticaConfigBase } from "./IAgenticaConfigBase";
-import type { IMicroAgenticaExecutor } from "./IMicroAgenticaExecutor";
-import type { IMicroAgenticaSystemPrompt } from "./IMicroAgenticaSystemPrompt";
-
-/**
- * Configuration for Micro Agentic Agent.
- *
- * `INicroAgenticaConfig` is an interface that defines the configuration
- * properties of the {@link MicroAgentica}. With this configuration, you
- * can set the user's {@link locale}, {@link timezone}, and some of
- * {@link systemPrompt system prompts}.
- *
- * @author Samchon
- */
-export interface IMicroAgenticaConfig 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
-   * @returns Lit of prompts generated by the executor
-   * @default ChatGptAgent.execute
-   */
-  executor?:
-    | undefined
-    | Partial<IMicroAgenticaExecutor>;
-
-  /**
-   * System prompt messages.
-   *
-   * System prompt messages if you want to customize the system prompt
-   * messages for each situation.
-   */
-  systemPrompt?: IMicroAgenticaSystemPrompt;
-
-  /**
-   * Whether to throw an exception when execution fails.
-   *
-   * If you set this property to `true` or define nothing, the A.I. chatbot
-   * will throw an exception when {@link AgenticaExecuteHistory.success} is
-   * `false`.
-   *
-   * Otherwise, the execution failure will be handled silently without
-   * throwing an exception.
-   *
-   * @default true
-   */
-  throw?: boolean;
-}
+import type { IAgenticaConfigBase } from "./IAgenticaConfigBase";
+import type { IMicroAgenticaExecutor } from "./IMicroAgenticaExecutor";
+import type { IMicroAgenticaSystemPrompt } from "./IMicroAgenticaSystemPrompt";
+
+/**
+ * Configuration for Micro Agentic Agent.
+ *
+ * `INicroAgenticaConfig` is an interface that defines the configuration
+ * properties of the {@link MicroAgentica}. With this configuration, you
+ * can set the user's {@link locale}, {@link timezone}, and some of
+ * {@link systemPrompt system prompts}.
+ *
+ * @author Samchon
+ */
+export interface IMicroAgenticaConfig 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
+   * @returns Lit of prompts generated by the executor
+   * @default ChatGptAgent.execute
+   */
+  executor?:
+    | undefined
+    | Partial<IMicroAgenticaExecutor>;
+
+  /**
+   * System prompt messages.
+   *
+   * System prompt messages if you want to customize the system prompt
+   * messages for each situation.
+   */
+  systemPrompt?: IMicroAgenticaSystemPrompt;
+
+  /**
+   * Whether to throw an exception when execution fails.
+   *
+   * If you set this property to `true` or define nothing, the A.I. chatbot
+   * will throw an exception when {@link AgenticaExecuteHistory.success} is
+   * `false`.
+   *
+   * Otherwise, the execution failure will be handled silently without
+   * throwing an exception.
+   *
+   * @default true
+   */
+  throw?: boolean;
+}

package/src/structures/IMicroAgenticaExecutor.ts

@@ -1,67 +1,67 @@
-import type { MicroAgenticaContext } from "../context/MicroAgenticaContext";
-import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
-
-/**
- * Executor of the Micro Agentic AI.
- *
- * `IMicroAgenticaExecutor` represents an executor of the
- * {@link MicroAgentica}, composing its internal agents to accomplish
- * the Agentic AI through the LLM (Large Language Model) function
- * calling.
- *
- * You can customize one of these intnernal agents by configuring
- * properties of the `IMicroAgenticaExecutor` type, and assigning
- * it to the {@link IMicroAgenticaConfig.executor} property.
- *
- * @author Samchon
- */
-export interface IMicroAgenticaExecutor {
-  /**
-   * Function caller agent.
-   *
-   * `Call` agent performs the LLM (Large Language Model) function
-   * calling from the candidate functions enrolled in the
-   * {@link AgenticaContext.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: MicroAgenticaContext) => Promise<AgenticaExecuteHistory[]>;
-
-  /**
-   * Describer agent of the function calling result.
-   *
-   * `Describe` agent explains the results of the function callings
-   * to the user as markdown content.
-   *
-   * If you configure this property as `false` or `null`, the describer
-   * agent never be used.
-   *
-   * @param ctx Context of the agent
-   * @param executes List of function calling results
-   * @returns List of prompts generated by the describer
-   * @default false
-   */
-  describe:
-    | boolean
-    | null
-    | ((
-      ctx: MicroAgenticaContext,
-      executes: AgenticaExecuteHistory[],
-    ) => Promise<void>);
-}
+import type { MicroAgenticaContext } from "../context/MicroAgenticaContext";
+import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
+
+/**
+ * Executor of the Micro Agentic AI.
+ *
+ * `IMicroAgenticaExecutor` represents an executor of the
+ * {@link MicroAgentica}, composing its internal agents to accomplish
+ * the Agentic AI through the LLM (Large Language Model) function
+ * calling.
+ *
+ * You can customize one of these intnernal agents by configuring
+ * properties of the `IMicroAgenticaExecutor` type, and assigning
+ * it to the {@link IMicroAgenticaConfig.executor} property.
+ *
+ * @author Samchon
+ */
+export interface IMicroAgenticaExecutor {
+  /**
+   * Function caller agent.
+   *
+   * `Call` agent performs the LLM (Large Language Model) function
+   * calling from the candidate functions enrolled in the
+   * {@link AgenticaContext.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: MicroAgenticaContext) => Promise<AgenticaExecuteHistory[]>;
+
+  /**
+   * Describer agent of the function calling result.
+   *
+   * `Describe` agent explains the results of the function callings
+   * to the user as markdown content.
+   *
+   * If you configure this property as `false` or `null`, the describer
+   * agent never be used.
+   *
+   * @param ctx Context of the agent
+   * @param executes List of function calling results
+   * @returns List of prompts generated by the describer
+   * @default false
+   */
+  describe:
+    | boolean
+    | null
+    | ((
+      ctx: MicroAgenticaContext,
+      executes: AgenticaExecuteHistory[],
+    ) => Promise<void>);
+}

package/src/structures/IMicroAgenticaProps.ts

@@ -1,77 +1,77 @@
-import type { AgenticaTokenUsage } from "../context/AgenticaTokenUsage";
-import type { IAgenticaTokenUsageJson } from "../json/IAgenticaTokenUsageJson";
-import type { IMicroAgenticaHistoryJson } from "../json/IMicroAgenticaHistoryJson";
-
-import type { IAgenticaController } from "./IAgenticaController";
-import type { IAgenticaVendor } from "./IAgenticaVendor";
-import type { IMicroAgenticaConfig } from "./IMicroAgenticaConfig";
-
-/**
- * Properties of the Micro Agentica Agent.
- *
- * `IMicroAgenticaProps` is an interface that defines the properties
- * of the {@link MicroAgentica.constructor}. In the `IMicroAgenticaProps`,
- * there're everything to prepare to create a Micro A.I. chatbot
- * performing the LLM (Large Language Model) function calling.
- *
- * At first, you have to specify the LLM service {@link vendor} 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 configure} 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 assigning the previous prompt
- * histories to the {@link histories} property.
- *
- * @author Samchon
- */
-export interface IMicroAgenticaProps {
-  /**
-   * LLM service vendor.
-   */
-  vendor: IAgenticaVendor;
-
-  /**
-   * Controllers serving functions to call.
-   */
-  controllers: IAgenticaController[];
-
-  /**
-   * 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/wrtnlabs/agentica/tree/main/packages/core/prompts
-   */
-  config?: IMicroAgenticaConfig;
-
-  /**
-   * Prompt histories.
-   *
-   * If you're starting the conversation from an existing session,
-   * assign the previouis prompt histories to this property.
-   */
-  histories?: IMicroAgenticaHistoryJson[];
-
-  /**
-   * Token usage information.
-   *
-   * You can start token usage tracing by assigning this property.
-   *
-   * If you assign {@link IAgenticaTokenUsageJson} value, the
-   * token usage tracing would be from the value. Otherwise you
-   * assign the {@link AgenticaTokenUsage} typed instance, the
-   * tracing would be binded to the instance.
-   */
-  tokenUsage?: IAgenticaTokenUsageJson | AgenticaTokenUsage | undefined;
-}
+import type { AgenticaTokenUsage } from "../context/AgenticaTokenUsage";
+import type { IAgenticaTokenUsageJson } from "../json/IAgenticaTokenUsageJson";
+import type { IMicroAgenticaHistoryJson } from "../json/IMicroAgenticaHistoryJson";
+
+import type { IAgenticaController } from "./IAgenticaController";
+import type { IAgenticaVendor } from "./IAgenticaVendor";
+import type { IMicroAgenticaConfig } from "./IMicroAgenticaConfig";
+
+/**
+ * Properties of the Micro Agentica Agent.
+ *
+ * `IMicroAgenticaProps` is an interface that defines the properties
+ * of the {@link MicroAgentica.constructor}. In the `IMicroAgenticaProps`,
+ * there're everything to prepare to create a Micro A.I. chatbot
+ * performing the LLM (Large Language Model) function calling.
+ *
+ * At first, you have to specify the LLM service {@link vendor} 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 configure} 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 assigning the previous prompt
+ * histories to the {@link histories} property.
+ *
+ * @author Samchon
+ */
+export interface IMicroAgenticaProps {
+  /**
+   * LLM service vendor.
+   */
+  vendor: IAgenticaVendor;
+
+  /**
+   * Controllers serving functions to call.
+   */
+  controllers: IAgenticaController[];
+
+  /**
+   * 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/wrtnlabs/agentica/tree/main/packages/core/prompts
+   */
+  config?: IMicroAgenticaConfig;
+
+  /**
+   * Prompt histories.
+   *
+   * If you're starting the conversation from an existing session,
+   * assign the previouis prompt histories to this property.
+   */
+  histories?: IMicroAgenticaHistoryJson[];
+
+  /**
+   * Token usage information.
+   *
+   * You can start token usage tracing by assigning this property.
+   *
+   * If you assign {@link IAgenticaTokenUsageJson} value, the
+   * token usage tracing would be from the value. Otherwise you
+   * assign the {@link AgenticaTokenUsage} typed instance, the
+   * tracing would be binded to the instance.
+   */
+  tokenUsage?: IAgenticaTokenUsageJson | AgenticaTokenUsage | undefined;
+}