@agentica/core 0.43.3 → 0.44.0-dev.20260313

package/src/constants/AgenticaConstant.ts

@@ -1,4 +1,4 @@
-export namespace AgenticaConstant {
-  export const RETRY = 3;
-  export const ELITICISM = true;
-}
+export namespace AgenticaConstant {
+  export const RETRY = 3;
+  export const ELITICISM = true;
+}

package/src/constants/AgenticaDefaultPrompt.ts

@@ -1,44 +1,44 @@
-import { is_node } from "tstl";
-
-import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
-import type { IMicroAgenticaConfig } from "../structures/IMicroAgenticaConfig";
-import type { IMicroAgenticaSystemPrompt } from "../structures/IMicroAgenticaSystemPrompt";
-
-import { Singleton } from "../utils/Singleton";
-
-import { AgenticaSystemPrompt } from "./AgenticaSystemPrompt";
-
-/**
- * @TODO maybe replace `process` property for lint pass
- */
-const getLocale = new Singleton(() =>
-  is_node()
-    // eslint-disable-next-line node/prefer-global/process
-    ? (process.env.LANG?.split(".")[0] ?? "en-US")
-    : navigator.language,
-);
-
-const getTimezone = new Singleton(
-  () => Intl.DateTimeFormat().resolvedOptions().timeZone,
-);
-
-export function write(config?: IAgenticaConfig | IMicroAgenticaConfig): string {
-  if (config?.systemPrompt?.common !== undefined) {
-    return (config.systemPrompt as IMicroAgenticaSystemPrompt).common!(config as unknown as IMicroAgenticaConfig);
-  }
-
-  const locale: string = config?.locale ?? getLocale.get();
-  const timezone: string = config?.timezone ?? getTimezone.get();
-
-  return AgenticaSystemPrompt.COMMON
-  // intended code
-
-    .replace("${locale}", locale)
-
-    .replace("${timezone}", timezone)
-
-    .replace("${datetime}", new Date().toISOString());
-}
-export const AgenticaDefaultPrompt = {
-  write,
-};
+import { is_node } from "tstl";
+
+import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
+import type { IMicroAgenticaConfig } from "../structures/IMicroAgenticaConfig";
+import type { IMicroAgenticaSystemPrompt } from "../structures/IMicroAgenticaSystemPrompt";
+
+import { Singleton } from "../utils/Singleton";
+
+import { AgenticaSystemPrompt } from "./AgenticaSystemPrompt";
+
+/**
+ * @TODO maybe replace `process` property for lint pass
+ */
+const getLocale = new Singleton(() =>
+  is_node()
+    // eslint-disable-next-line node/prefer-global/process
+    ? (process.env.LANG?.split(".")[0] ?? "en-US")
+    : navigator.language,
+);
+
+const getTimezone = new Singleton(
+  () => Intl.DateTimeFormat().resolvedOptions().timeZone,
+);
+
+export function write(config?: IAgenticaConfig | IMicroAgenticaConfig): string {
+  if (config?.systemPrompt?.common !== undefined) {
+    return (config.systemPrompt as IMicroAgenticaSystemPrompt).common!(config as unknown as IMicroAgenticaConfig);
+  }
+
+  const locale: string = config?.locale ?? getLocale.get();
+  const timezone: string = config?.timezone ?? getTimezone.get();
+
+  return AgenticaSystemPrompt.COMMON
+  // intended code
+
+    .replace("${locale}", locale)
+
+    .replace("${timezone}", timezone)
+
+    .replace("${datetime}", new Date().toISOString());
+}
+export const AgenticaDefaultPrompt = {
+  write,
+};

package/src/constants/AgenticaSystemPrompt.ts

@@ -11,7 +11,7 @@ export const AgenticaSystemPrompt = {
   INITIALIZE:
     "You are a helpful assistant.\n\nUse the supplied tools to assist the user.",
   JSON_PARSE_ERROR:
-    "# JSON Parsing Error - Function Call Arguments Invalid\n\n## 🚨 Critical Error: Invalid JSON Format\n\nThe `arguments` field in your function call contains invalid JSON syntax and cannot be parsed.\n\n### Error Message\n\nHere is the `Error.message` occurred from the `JSON.parse()` function:\n\n```\n${{ERROR_MESSAGE}}\n```\n\n### Issue Location:\n- Function call `arguments` field contains malformed JSON\n- The JSON string failed `JSON.parse()` validation\n- Function execution cannot proceed\n\n### Required Action:\n- Review the error message above and determine whether the JSON is recoverable\n- If the syntax error is minor (e.g. trailing comma, missing quote), fix it and retry\n- If the JSON is severely malformed or structurally broken, **discard the previous output entirely** and reconstruct the `arguments` from scratch based on the function's parameter schema\n- Do not attempt to patch heavily corrupted JSON — rebuilding from zero is faster and more reliable\n\n### Common JSON Syntax Requirements:\n- Use double quotes for all keys and string values\n- Remove trailing commas\n- Use lowercase `true`/`false` for booleans\n- Use lowercase `null` for null values\n- Properly escape special characters in strings\n\n**Retry the function call immediately with valid JSON.**",
+    "# JSON Parse Failure in Function Call Arguments\n\n## Error Report\n\nThe `arguments` field in your function call contains invalid JSON that could not be fully parsed. Below is the `IJsonParseResult.IFailure` object describing what went wrong.\n\n### Failure Details\n\n- `success`: Always `false` — indicates parsing did not fully succeed.\n- `data`: Partially recovered data from the malformed JSON. May be incomplete or `undefined` if nothing could be salvaged.\n- `input`: The original raw JSON string you produced, preserved for reference.\n- `errors`: List of specific issues found during parsing.\n  - `path`: Dot-notation path from root (`$input`) to the error location (e.g. `$input.user.email`).\n  - `expected`: What the parser expected at that position (e.g. `quoted string`, `\":\"`, `JSON value`).\n  - `description`: Human-readable explanation of what was actually found and what went wrong.\n\n```json\n${{FAILURE}}\n```\n\n## Recovery Instructions\n\n- Review each error above and determine whether the JSON is recoverable.\n- If the syntax error is minor (e.g. trailing comma, missing quote), fix it and retry.\n- If the JSON is severely malformed or structurally broken, **discard the previous output entirely** and reconstruct the `arguments` from scratch based on the function's parameter schema.\n- Do not attempt to patch heavily corrupted JSON — rebuilding from zero is faster and more reliable.\n\n## Common JSON Syntax Requirements\n\n- Use double quotes for all keys and string values.\n- Remove trailing commas.\n- Use lowercase `true`/`false` for booleans and `null` for null values.\n- Properly escape special characters in strings.\n\n**Retry the function call immediately with valid JSON.**",
   SELECT:
     "You are a helpful assistant for selecting functions to call.\n\nUse the supplied tools to select some functions of `getApiFunctions()` returned.\n\nWhen selecting functions to call, pay attention to the relationship between functions. In particular, check the prerequisites between each function.\n\nIf you can't find any proper function to select, just type your own message. By the way, when typing your own message, please consider the user's language locale code. If your message is different with the user's language, please translate it to the user's.",
   VALIDATE:

package/src/constants/index.ts

@@ -1,2 +1,2 @@
-export * from "./AgenticaDefaultPrompt";
-export * from "./AgenticaSystemPrompt";
+export * from "./AgenticaDefaultPrompt";
+export * from "./AgenticaSystemPrompt";

package/src/context/AgenticaContext.ts

@@ -1,136 +1,136 @@
-import type OpenAI from "openai";
-
-import type { AgenticaEvent } from "../events/AgenticaEvent";
-import type { AgenticaEventSource } from "../events/AgenticaEventSource";
-import type { AgenticaHistory } from "../histories/AgenticaHistory";
-import type { AgenticaUserMessageHistory } from "../histories/AgenticaUserMessageHistory";
-import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
-
-import type { AgenticaContextRequestResult } from "./AgenticaContextRequestResult";
-import type { AgenticaOperationCollection } from "./AgenticaOperationCollection";
-import type { AgenticaOperationSelection } from "./AgenticaOperationSelection";
-
-/**
- * Context of the Agentic AI agent.
- *
- * `AgenticaContext` 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 orchestrate.execute}
- *   - {@link orchestrate.initialize}
- *   - {@link orchestrate.select}
- *   - {@link orchestrate.call}
- *   - {@link orchestrate.describe}
- *   - {@link orchestrate.cancel}
- *
- * 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 AgenticaContext {
-  // ----
-  // 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: AgenticaOperationCollection;
-
-  /**
-   * 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 | undefined;
-
-  // ----
-  // STATES
-  // ----
-  /**
-   * Prompt histories.
-   */
-  histories: AgenticaHistory[];
-
-  /**
-   * Stacked operations.
-   *
-   * In other words, list of candidate operations for the LLM function calling.
-   */
-  stack: AgenticaOperationSelection[];
-
-  /**
-   * The user input history.
-   *
-   * The user input history written by the user through the
-   * {@link Agentica.conversate} function.
-   */
-  prompt: AgenticaUserMessageHistory;
-
-  /**
-   * Abort signal.
-   */
-  abortSignal?: AbortSignal;
-
-  /**
-   * 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 AgenticaContext.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: AgenticaEvent) => 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: AgenticaEventSource,
-    body: Omit<OpenAI.ChatCompletionCreateParamsStreaming, "model" | "stream">,
-  ) => Promise<AgenticaContextRequestResult>;
-
-  /**
-   * Initialize the agent.
-   */
-  initialize: () => Promise<void>;
-}
+import type OpenAI from "openai";
+
+import type { AgenticaEvent } from "../events/AgenticaEvent";
+import type { AgenticaEventSource } from "../events/AgenticaEventSource";
+import type { AgenticaHistory } from "../histories/AgenticaHistory";
+import type { AgenticaUserMessageHistory } from "../histories/AgenticaUserMessageHistory";
+import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
+
+import type { AgenticaContextRequestResult } from "./AgenticaContextRequestResult";
+import type { AgenticaOperationCollection } from "./AgenticaOperationCollection";
+import type { AgenticaOperationSelection } from "./AgenticaOperationSelection";
+
+/**
+ * Context of the Agentic AI agent.
+ *
+ * `AgenticaContext` 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 orchestrate.execute}
+ *   - {@link orchestrate.initialize}
+ *   - {@link orchestrate.select}
+ *   - {@link orchestrate.call}
+ *   - {@link orchestrate.describe}
+ *   - {@link orchestrate.cancel}
+ *
+ * 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 AgenticaContext {
+  // ----
+  // 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: AgenticaOperationCollection;
+
+  /**
+   * 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 | undefined;
+
+  // ----
+  // STATES
+  // ----
+  /**
+   * Prompt histories.
+   */
+  histories: AgenticaHistory[];
+
+  /**
+   * Stacked operations.
+   *
+   * In other words, list of candidate operations for the LLM function calling.
+   */
+  stack: AgenticaOperationSelection[];
+
+  /**
+   * The user input history.
+   *
+   * The user input history written by the user through the
+   * {@link Agentica.conversate} function.
+   */
+  prompt: AgenticaUserMessageHistory;
+
+  /**
+   * Abort signal.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * 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 AgenticaContext.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: AgenticaEvent) => 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: AgenticaEventSource,
+    body: Omit<OpenAI.ChatCompletionCreateParamsStreaming, "model" | "stream">,
+  ) => Promise<AgenticaContextRequestResult>;
+
+  /**
+   * Initialize the agent.
+   */
+  initialize: () => Promise<void>;
+}

package/src/context/AgenticaContextRequestResult.ts

@@ -1,14 +1,14 @@
-import type OpenAI from "openai";
-
-export type AgenticaContextRequestResult = AgenticaContextRequestResult.Stream | AgenticaContextRequestResult.NoneStream;
-
-export namespace AgenticaContextRequestResult {
-  export interface Stream {
-    type: "stream";
-    value: ReadableStream<OpenAI.Chat.Completions.ChatCompletionChunk>;
-  }
-  export interface NoneStream {
-    type: "none-stream";
-    value: OpenAI.ChatCompletion;
-  }
-}
+import type OpenAI from "openai";
+
+export type AgenticaContextRequestResult = AgenticaContextRequestResult.Stream | AgenticaContextRequestResult.NoneStream;
+
+export namespace AgenticaContextRequestResult {
+  export interface Stream {
+    type: "stream";
+    value: ReadableStream<OpenAI.Chat.Completions.ChatCompletionChunk>;
+  }
+  export interface NoneStream {
+    type: "none-stream";
+    value: OpenAI.ChatCompletion;
+  }
+}

package/src/context/AgenticaOperation.ts

@@ -1,72 +1,73 @@
-import type { IHttpLlmFunction, ILlmFunction, IMcpLlmFunction } from "@samchon/openapi";
-
-import type { IAgenticaOperationJson } from "../json/IAgenticaOperationJson";
-import type { IAgenticaController } from "../structures/IAgenticaController";
-
-/**
- * Operation information in the Agentica Agent.
- *
- * `AgenticaOperation` 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 AgenticaOperation =
-  | AgenticaOperation.Class
-  | AgenticaOperation.Http
-  | AgenticaOperation.Mcp;
-export namespace AgenticaOperation {
-  export type Class = Base<
-    "class",
-    IAgenticaController.IClass,
-    ILlmFunction
-  >;
-  export type Http = Base<
-    "http",
-    IAgenticaController.IHttp,
-    IHttpLlmFunction
-  >;
-  export type Mcp = Base<
-    "mcp",
-    IAgenticaController.IMcp,
-    IMcpLlmFunction
-  >;
-
-  interface Base<
-    Protocol extends "http" | "class" | "mcp",
-    Controller extends object,
-    Function extends object,
-  > {
-    /**
-     * Protocol discriminator.
-     */
-    protocol: Protocol;
-
-    /**
-     * Belonged controller of the target function.
-     */
-    controller: Controller;
-
-    /**
-     * Target function to call.
-     */
-    function: Function;
-
-    /**
-     * Identifier name.
-     */
-    name: string;
-
-    /**
-     * Convert to primitive JSON object.
-     */
-    toJSON: () => IAgenticaOperationJson;
-  }
-}
+import type { IHttpLlmFunction } from "@typia/interface";
+import type { ILlmFunction } from "typia";
+
+import type { IAgenticaOperationJson } from "../json/IAgenticaOperationJson";
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Operation information in the Agentica Agent.
+ *
+ * `AgenticaOperation` 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 AgenticaOperation
+  = | AgenticaOperation.Class
+    | AgenticaOperation.Http
+    | AgenticaOperation.Mcp;
+export namespace AgenticaOperation {
+  export type Class = Base<
+    "class",
+    IAgenticaController.IClass,
+    ILlmFunction
+  >;
+  export type Http = Base<
+    "http",
+    IAgenticaController.IHttp,
+    IHttpLlmFunction
+  >;
+  export type Mcp = Base<
+    "mcp",
+    IAgenticaController.IMcp,
+    ILlmFunction
+  >;
+
+  interface Base<
+    Protocol extends "http" | "class" | "mcp",
+    Controller extends object,
+    Function extends object,
+  > {
+    /**
+     * Protocol discriminator.
+     */
+    protocol: Protocol;
+
+    /**
+     * Belonged controller of the target function.
+     */
+    controller: Controller;
+
+    /**
+     * Target function to call.
+     */
+    function: Function;
+
+    /**
+     * Identifier name.
+     */
+    name: string;
+
+    /**
+     * Convert to primitive JSON object.
+     */
+    toJSON: () => IAgenticaOperationJson;
+  }
+}