@agentica/core 0.43.2 → 0.44.0-dev.20260313

package/src/context/internal/AgenticaTokenUsageAggregator.ts

@@ -1,66 +1,66 @@
-import type { CompletionUsage } from "openai/resources";
-
-import type { IAgenticaTokenUsageJson } from "../../json/IAgenticaTokenUsageJson";
-import type { AgenticaTokenUsage } from "../AgenticaTokenUsage";
-
-export function aggregate(props: {
-  kind: Exclude<keyof IAgenticaTokenUsageJson, "aggregate">;
-  completionUsage: CompletionUsage;
-  usage: AgenticaTokenUsage;
-}): void {
-  // ----
-  // COMPONENT
-  // ----
-  const component: AgenticaTokenUsage.IComponent = props.usage[props.kind];
-
-  // TOTAL
-  component.total += props.completionUsage.total_tokens;
-
-  // PROMPT
-  component.input.total += props.completionUsage.prompt_tokens;
-  component.input.total
-      += props.completionUsage.prompt_tokens_details?.audio_tokens ?? 0;
-  component.input.cached
-      += props.completionUsage.prompt_tokens_details?.cached_tokens ?? 0;
-
-  // COMPLETION
-  component.output.total += props.completionUsage.completion_tokens;
-  component.output.accepted_prediction
-      += props.completionUsage.completion_tokens_details
-      ?.accepted_prediction_tokens ?? 0;
-  component.output.reasoning
-      += props.completionUsage.completion_tokens_details?.reasoning_tokens ?? 0;
-  component.output.rejected_prediction
-      += props.completionUsage.completion_tokens_details
-      ?.rejected_prediction_tokens ?? 0;
-
-  // ----
-  // RE-AGGREGATE
-  // ----
-  const sum = (getter: (comp: AgenticaTokenUsage.IComponent) => number) =>
-    (
-      Object.entries(props.usage) as [
-        keyof AgenticaTokenUsage,
-        AgenticaTokenUsage.IComponent,
-      ][]
-    )
-      .filter(([key]) => key !== "aggregate")
-      .map(([, comp]) => getter(comp))
-      .reduce((a, b) => a + b, 0);
-  const aggregate: AgenticaTokenUsage.IComponent = props.usage.aggregate;
-  aggregate.total = sum(comp => comp.total);
-  aggregate.input.total = sum(comp => comp.input.total);
-  aggregate.input.cached = sum(comp => comp.input.cached);
-  aggregate.output.total = sum(comp => comp.output.total);
-  aggregate.output.reasoning = sum(comp => comp.output.reasoning);
-  aggregate.output.accepted_prediction = sum(
-    comp => comp.output.accepted_prediction,
-  );
-  aggregate.output.rejected_prediction = sum(
-    comp => comp.output.rejected_prediction,
-  );
-}
-
-export const AgenticaTokenUsageAggregator = {
-  aggregate,
-};
+import type { CompletionUsage } from "openai/resources";
+
+import type { IAgenticaTokenUsageJson } from "../../json/IAgenticaTokenUsageJson";
+import type { AgenticaTokenUsage } from "../AgenticaTokenUsage";
+
+export function aggregate(props: {
+  kind: Exclude<keyof IAgenticaTokenUsageJson, "aggregate">;
+  completionUsage: CompletionUsage;
+  usage: AgenticaTokenUsage;
+}): void {
+  // ----
+  // COMPONENT
+  // ----
+  const component: AgenticaTokenUsage.IComponent = props.usage[props.kind];
+
+  // TOTAL
+  component.total += props.completionUsage.total_tokens;
+
+  // PROMPT
+  component.input.total += props.completionUsage.prompt_tokens;
+  component.input.total
+    += props.completionUsage.prompt_tokens_details?.audio_tokens ?? 0;
+  component.input.cached
+    += props.completionUsage.prompt_tokens_details?.cached_tokens ?? 0;
+
+  // COMPLETION
+  component.output.total += props.completionUsage.completion_tokens;
+  component.output.accepted_prediction
+    += props.completionUsage.completion_tokens_details
+      ?.accepted_prediction_tokens ?? 0;
+  component.output.reasoning
+    += props.completionUsage.completion_tokens_details?.reasoning_tokens ?? 0;
+  component.output.rejected_prediction
+    += props.completionUsage.completion_tokens_details
+      ?.rejected_prediction_tokens ?? 0;
+
+  // ----
+  // RE-AGGREGATE
+  // ----
+  const sum = (getter: (comp: AgenticaTokenUsage.IComponent) => number) =>
+    (
+      Object.entries(props.usage) as [
+        keyof AgenticaTokenUsage,
+        AgenticaTokenUsage.IComponent,
+      ][]
+    )
+      .filter(([key]) => key !== "aggregate")
+      .map(([, comp]) => getter(comp))
+      .reduce((a, b) => a + b, 0);
+  const aggregate: AgenticaTokenUsage.IComponent = props.usage.aggregate;
+  aggregate.total = sum(comp => comp.total);
+  aggregate.input.total = sum(comp => comp.input.total);
+  aggregate.input.cached = sum(comp => comp.input.cached);
+  aggregate.output.total = sum(comp => comp.output.total);
+  aggregate.output.reasoning = sum(comp => comp.output.reasoning);
+  aggregate.output.accepted_prediction = sum(
+    comp => comp.output.accepted_prediction,
+  );
+  aggregate.output.rejected_prediction = sum(
+    comp => comp.output.rejected_prediction,
+  );
+}
+
+export const AgenticaTokenUsageAggregator = {
+  aggregate,
+};

package/src/context/internal/__IChatCancelFunctionsApplication.ts

@@ -1,23 +1,23 @@
-import type { __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 type { __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/context/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[];
+  }
+}

package/src/context/internal/__IChatInitialApplication.ts

@@ -1,15 +1,15 @@
-import type { IHttpLlmFunction } from "@samchon/openapi";
-
-export interface __IChatInitialApplication {
-  /**
-   * Get list of API functions.
-   *
-   * If user seems like to request some function calling except this one,
-   * call this `getApiFunctions()` to get the list of candidate API functions
-   * provided from this application.
-   *
-   * Also, user just wants to list up every remote API functions that can be
-   * called from the backend server, utilize this function too.
-   */
-  getApiFunctions: (props: object) => Promise<Array<IHttpLlmFunction>>;
-}
+import type { IHttpLlmFunction } from "@typia/interface";
+
+export interface __IChatInitialApplication {
+  /**
+   * Get list of API functions.
+   *
+   * If user seems like to request some function calling except this one,
+   * call this `getApiFunctions()` to get the list of candidate API functions
+   * provided from this application.
+   *
+   * Also, user just wants to list up every remote API functions that can be
+   * called from the backend server, utilize this function too.
+   */
+  getApiFunctions: (props: object) => Promise<Array<IHttpLlmFunction>>;
+}

package/src/context/internal/__IChatSelectFunctionsApplication.ts

@@ -1,24 +1,24 @@
-import type { __IChatFunctionReference } from "./__IChatFunctionReference";
-
-export interface __IChatSelectFunctionsApplication {
-  /**
-   * Select proper API functions to call.
-   *
-   * If you A.I. agent has found some proper API functions to call
-   * from the conversation with user, please select the API functions
-   * just by calling this function.
-   *
-   * When user wants to call a same function multiply, you A.I. agent must
-   * list up it multiply in the `functions` property. Otherwise the user has
-   * requested to call many different functions, you A.I. agent have to assign
-   * them all into the `functions` property.
-   *
-   * Also, if you A.I. agent can't specify a specific function to call due to lack
-   * of specificity or homogeneity of candidate functions, just assign all of them
-   * by in the` functions` property` too. Instead, when you A.I. agent can specify
-   * a specific function to call, the others would be eliminated.
-   *
-   * @param props Properties of the function
-   */
-  selectFunctions: (props: __IChatFunctionReference.IProps) => Promise<void>;
-}
+import type { __IChatFunctionReference } from "./__IChatFunctionReference";
+
+export interface __IChatSelectFunctionsApplication {
+  /**
+   * Select proper API functions to call.
+   *
+   * If you A.I. agent has found some proper API functions to call
+   * from the conversation with user, please select the API functions
+   * just by calling this function.
+   *
+   * When user wants to call a same function multiply, you A.I. agent must
+   * list up it multiply in the `functions` property. Otherwise the user has
+   * requested to call many different functions, you A.I. agent have to assign
+   * them all into the `functions` property.
+   *
+   * Also, if you A.I. agent can't specify a specific function to call due to lack
+   * of specificity or homogeneity of candidate functions, just assign all of them
+   * by in the` functions` property` too. Instead, when you A.I. agent can specify
+   * a specific function to call, the others would be eliminated.
+   *
+   * @param props Properties of the function
+   */
+  selectFunctions: (props: __IChatFunctionReference.IProps) => Promise<void>;
+}

package/src/context/internal/isAgenticaContext.ts

@@ -1,11 +1,11 @@
-import type { AgenticaContext } from "../AgenticaContext";
-import type { MicroAgenticaContext } from "../MicroAgenticaContext";
-
-/**
- * @internal
- */
-export function isAgenticaContext(
-  ctx: AgenticaContext | MicroAgenticaContext,
-): ctx is AgenticaContext {
-  return typeof (ctx as AgenticaContext).initialize === "function";
-}
+import type { AgenticaContext } from "../AgenticaContext";
+import type { MicroAgenticaContext } from "../MicroAgenticaContext";
+
+/**
+ * @internal
+ */
+export function isAgenticaContext(
+  ctx: AgenticaContext | MicroAgenticaContext,
+): ctx is AgenticaContext {
+  return typeof (ctx as AgenticaContext).initialize === "function";
+}

package/src/errors/AgenticaJsonParseError.ts

@@ -1,47 +1,52 @@
-import { AgenticaConstant } from "../constants/AgenticaConstant";
-
-export class AgenticaJsonParseError extends Error {
-  public readonly arguments: string;
-  public readonly reason: string;
-
-  public constructor(props: AgenticaJsonParseError.IProps) {
-    super(`Invalid JSON format. The parsing failed after ${AgenticaConstant.RETRY} retries.`);
-
-    const proto = new.target.prototype;
-
-    // eslint-disable-next-line
-    if (Object.setPrototypeOf) { 
-      Object.setPrototypeOf(this, proto);
-    }
-    else {
-      // eslint-disable-next-line
-      (this as any).__proto__ = proto; 
-    }
-
-    this.arguments = props.arguments;
-    this.reason = props.reason;
-  }
-
-  public get name(): "AgenticaJsonParseError" {
-    return "AgenticaJsonParseError";
-  }
-
-  public toJSON(): AgenticaJsonParseError.IJson {
-    return {
-      name: "AgenticaJsonParseError",
-      message: this.message,
-      arguments: this.arguments,
-      reason: this.reason,
-    };
-  }
-}
-export namespace AgenticaJsonParseError {
-  export interface IProps {
-    arguments: string;
-    reason: string;
-  }
-  export interface IJson extends IProps {
-    name: "AgenticaJsonParseError";
-    message: string;
-  }
-}
+import type { IJsonParseResult } from "typia";
+
+import { dedent } from "@typia/utils";
+
+import { AgenticaConstant } from "../constants/AgenticaConstant";
+
+export class AgenticaJsonParseError extends Error {
+  public readonly failure: IJsonParseResult.IFailure;
+
+  public constructor(failure: IJsonParseResult.IFailure) {
+    super(
+      dedent`
+        Invalid JSON format. The parsing failed after ${AgenticaConstant.RETRY} retries.
+
+        \`\`\`json
+        ${JSON.stringify(failure, null, 2)}
+        \`\`\`
+      `,
+    );
+
+    const proto = new.target.prototype;
+
+    // eslint-disable-next-line
+    if (Object.setPrototypeOf) { 
+      Object.setPrototypeOf(this, proto);
+    }
+    else {
+      // eslint-disable-next-line
+      (this as any).__proto__ = proto; 
+    }
+    this.failure = failure;
+  }
+
+  public get name(): "AgenticaJsonParseError" {
+    return "AgenticaJsonParseError";
+  }
+
+  public toJSON(): AgenticaJsonParseError.IJson {
+    return {
+      name: "AgenticaJsonParseError",
+      failure: this.failure,
+      message: this.message,
+    };
+  }
+}
+export namespace AgenticaJsonParseError {
+  export interface IJson {
+    name: "AgenticaJsonParseError";
+    failure: IJsonParseResult.IFailure;
+    message: string;
+  }
+}

package/src/errors/AgenticaValidationError.ts

@@ -1,49 +1,49 @@
-import type { IValidation } from "@samchon/openapi";
-
-import { AgenticaConstant } from "../constants/AgenticaConstant";
-
-export class AgenticaValidationError extends Error {
-  public readonly arguments: unknown;
-  public readonly errors: IValidation.IError[];
-
-  public constructor(props: AgenticaValidationError.IProps) {
-    super(`Invalid arguments. The validation failed after ${AgenticaConstant.RETRY} retries.`);
-
-    const proto = new.target.prototype;
-
-    // eslint-disable-next-line
-    if (Object.setPrototypeOf) { 
-      Object.setPrototypeOf(this, proto);
-    }
-    else {
-      // eslint-disable-next-line
-      (this as any).__proto__ = proto; 
-    }
-
-    this.arguments = props.arguments;
-    this.errors = props.errors;
-  }
-
-  public get name(): "AgenticaValidationError" {
-    return "AgenticaValidationError";
-  }
-
-  public toJSON(): AgenticaValidationError.IJson {
-    return {
-      name: "AgenticaValidationError",
-      message: this.message,
-      arguments: this.arguments,
-      errors: this.errors,
-    };
-  }
-}
-export namespace AgenticaValidationError {
-  export interface IProps {
-    arguments: unknown;
-    errors: IValidation.IError[];
-  }
-  export interface IJson extends IProps {
-    name: "AgenticaValidationError";
-    message: string;
-  }
-}
+import type { IValidation } from "typia";
+
+import { AgenticaConstant } from "../constants/AgenticaConstant";
+
+export class AgenticaValidationError extends Error {
+  public readonly arguments: unknown;
+  public readonly errors: IValidation.IError[];
+
+  public constructor(props: AgenticaValidationError.IProps) {
+    super(`Invalid arguments. The validation failed after ${AgenticaConstant.RETRY} retries.`);
+
+    const proto = new.target.prototype;
+
+    // eslint-disable-next-line
+    if (Object.setPrototypeOf) { 
+      Object.setPrototypeOf(this, proto);
+    }
+    else {
+      // eslint-disable-next-line
+      (this as any).__proto__ = proto; 
+    }
+
+    this.arguments = props.arguments;
+    this.errors = props.errors;
+  }
+
+  public get name(): "AgenticaValidationError" {
+    return "AgenticaValidationError";
+  }
+
+  public toJSON(): AgenticaValidationError.IJson {
+    return {
+      name: "AgenticaValidationError",
+      message: this.message,
+      arguments: this.arguments,
+      errors: this.errors,
+    };
+  }
+}
+export namespace AgenticaValidationError {
+  export interface IProps {
+    arguments: unknown;
+    errors: IValidation.IError[];
+  }
+  export interface IJson extends IProps {
+    name: "AgenticaValidationError";
+    message: string;
+  }
+}

package/src/errors/index.ts

@@ -1,2 +1,2 @@
-export * from "./AgenticaJsonParseError";
-export * from "./AgenticaValidationError";
+export * from "./AgenticaJsonParseError";
+export * from "./AgenticaValidationError";

package/src/events/AgenticaAssistantMessageEvent.ts

@@ -1,12 +1,12 @@
-import type { AgenticaAssistantMessageHistory } from "../histories/AgenticaAssistantMessageHistory";
-import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-
-import type { AgenticaEventBase } from "./AgenticaEventBase";
-
-export interface AgenticaAssistantMessageEvent
-  extends AgenticaEventBase<"assistantMessage"> {
-  stream: AsyncGenerator<string, undefined, undefined>;
-  join: () => Promise<string>;
-  toJSON: () => IAgenticaEventJson.IAssistantMessage;
-  toHistory: () => AgenticaAssistantMessageHistory;
-}
+import type { AgenticaAssistantMessageHistory } from "../histories/AgenticaAssistantMessageHistory";
+import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+
+import type { AgenticaEventBase } from "./AgenticaEventBase";
+
+export interface AgenticaAssistantMessageEvent
+  extends AgenticaEventBase<"assistantMessage"> {
+  stream: AsyncGenerator<string, undefined, undefined>;
+  join: () => Promise<string>;
+  toJSON: () => IAgenticaEventJson.IAssistantMessage;
+  toHistory: () => AgenticaAssistantMessageHistory;
+}

package/src/events/AgenticaCallEvent.ts

@@ -1,27 +1,27 @@
-import type { AgenticaOperation } from "../context/AgenticaOperation";
-import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-
-import type { AgenticaEventBase } from "./AgenticaEventBase";
-
-/**
- * Event of a function calling.
- *
- * @author Samchon
- */
-export interface AgenticaCallEvent extends AgenticaEventBase<"call"> {
-  /**
-   * Target operation to call.
-   */
-  operation: AgenticaOperation;
-
-  /**
-   * Arguments of the function calling.
-   *
-   * If you modify this {@link arguments} property, it actually modifies
-   * the backend server's request. Therefore, be careful when you're
-   * trying to modify this property.
-   */
-  arguments: Record<string, any>;
-
-  toJSON: () => IAgenticaEventJson.ICall;
-}
+import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+
+import type { AgenticaEventBase } from "./AgenticaEventBase";
+
+/**
+ * Event of a function calling.
+ *
+ * @author Samchon
+ */
+export interface AgenticaCallEvent extends AgenticaEventBase<"call"> {
+  /**
+   * Target operation to call.
+   */
+  operation: AgenticaOperation;
+
+  /**
+   * Arguments of the function calling.
+   *
+   * If you modify this {@link arguments} property, it actually modifies
+   * the backend server's request. Therefore, be careful when you're
+   * trying to modify this property.
+   */
+  arguments: Record<string, any>;
+
+  toJSON: () => IAgenticaEventJson.ICall;
+}

package/src/events/AgenticaCancelEvent.ts

@@ -1,9 +1,9 @@
-import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
-import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-
-import type { AgenticaEventBase } from "./AgenticaEventBase";
-
-export interface AgenticaCancelEvent extends AgenticaEventBase<"cancel"> {
-  selection: AgenticaOperationSelection;
-  toJSON: () => IAgenticaEventJson.ICancel;
-}
+import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+
+import type { AgenticaEventBase } from "./AgenticaEventBase";
+
+export interface AgenticaCancelEvent extends AgenticaEventBase<"cancel"> {
+  selection: AgenticaOperationSelection;
+  toJSON: () => IAgenticaEventJson.ICancel;
+}