@agentica/core 0.8.2 → 0.8.3-dev.20250227

package/src/internal/AgenticaTokenUsageAggregator.ts

@@ -1,123 +1,115 @@
-import OpenAI from "openai";
-
-import { IAgenticaTokenUsage } from "../structures/IAgenticaTokenUsage";
-
-export namespace AgenticaTokenUsageAggregator {
-  export const aggregate = (props: {
-    kind: Exclude<keyof IAgenticaTokenUsage, "aggregate">;
-    completion: OpenAI.ChatCompletion;
-    usage: IAgenticaTokenUsage;
-  }): void => {
-    if (!props.completion.usage) return;
-
-    //----
-    // COMPONENT
-    //----
-    const component: IAgenticaTokenUsage.IComponent<any> =
-      props.usage[props.kind];
-
-    // TOTAL
-    component.total += props.completion.usage.total_tokens;
-
-    // PROMPT
-    component.input.total += props.completion.usage.prompt_tokens;
-    props.completion.usage.prompt_tokens_details?.audio_tokens ?? 0;
-    component.input.cached +=
-      props.completion.usage.prompt_tokens_details?.cached_tokens ?? 0;
-
-    // COMPLETION
-    component.output.total += props.completion.usage.total_tokens;
-    component.output.accepted_prediction +=
-      props.completion.usage.completion_tokens_details
-        ?.accepted_prediction_tokens ?? 0;
-    component.output.reasoning +=
-      props.completion.usage.completion_tokens_details?.reasoning_tokens ?? 0;
-    component.output.rejected_prediction +=
-      props.completion.usage.completion_tokens_details
-        ?.rejected_prediction_tokens ?? 0;
-
-    //----
-    // RE-AGGREGATE
-    //----
-    const sum = (
-      getter: (comp: IAgenticaTokenUsage.IComponent<any>) => number,
-    ) =>
-      Object.entries(props.usage)
-        .filter(([key]) => key !== "aggregate")
-        .map(([_, comp]) => getter(comp))
-        .reduce((a, b) => a + b, 0);
-    const aggregate: IAgenticaTokenUsage.IComponent<"aggregate"> =
-      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 plus = (
-    x: IAgenticaTokenUsage,
-    y: IAgenticaTokenUsage,
-  ): IAgenticaTokenUsage => {
-    const component = <Kind extends string>(
-      a: IAgenticaTokenUsage.IComponent<Kind>,
-      b: IAgenticaTokenUsage.IComponent<Kind>,
-    ): IAgenticaTokenUsage.IComponent<Kind> => ({
-      type: a.type,
-      total: a.total + b.total,
-      input: {
-        total: a.input.total + b.input.total,
-        cached: a.input.cached + b.input.cached,
-      },
-      output: {
-        total: a.output.total + b.output.total,
-        reasoning: a.output.reasoning + b.output.reasoning,
-        accepted_prediction:
-          a.output.accepted_prediction + b.output.accepted_prediction,
-        rejected_prediction:
-          a.output.rejected_prediction + b.output.rejected_prediction,
-      },
-    });
-    return {
-      aggregate: component(x.aggregate, y.aggregate),
-      initialize: component(x.initialize, y.initialize),
-      select: component(x.select, y.select),
-      cancel: component(x.cancel, y.cancel),
-      call: component(x.call, y.call),
-      describe: component(x.describe, y.describe),
-    };
-  };
-
-  export const zero = (): IAgenticaTokenUsage => {
-    const component = <Kind extends string>(
-      kind: Kind,
-    ): IAgenticaTokenUsage.IComponent<Kind> => ({
-      type: kind,
-      total: 0,
-      input: {
-        total: 0,
-        cached: 0,
-      },
-      output: {
-        total: 0,
-        reasoning: 0,
-        accepted_prediction: 0,
-        rejected_prediction: 0,
-      },
-    });
-    return {
-      aggregate: component("aggregate"),
-      initialize: component("initialize"),
-      select: component("select"),
-      cancel: component("cancel"),
-      call: component("call"),
-      describe: component("describe"),
-    };
-  };
-}
+import OpenAI from "openai";
+
+import { IAgenticaTokenUsage } from "../structures/IAgenticaTokenUsage";
+
+export namespace AgenticaTokenUsageAggregator {
+  export const aggregate = (props: {
+    kind: Exclude<keyof IAgenticaTokenUsage, "aggregate">;
+    completion: OpenAI.ChatCompletion;
+    usage: IAgenticaTokenUsage;
+  }): void => {
+    if (!props.completion.usage) return;
+
+    //----
+    // COMPONENT
+    //----
+    const component: IAgenticaTokenUsage.IComponent = props.usage[props.kind];
+
+    // TOTAL
+    component.total += props.completion.usage.total_tokens;
+
+    // PROMPT
+    component.input.total += props.completion.usage.prompt_tokens;
+    props.completion.usage.prompt_tokens_details?.audio_tokens ?? 0;
+    component.input.cached +=
+      props.completion.usage.prompt_tokens_details?.cached_tokens ?? 0;
+
+    // COMPLETION
+    component.output.total += props.completion.usage.total_tokens;
+    component.output.accepted_prediction +=
+      props.completion.usage.completion_tokens_details
+        ?.accepted_prediction_tokens ?? 0;
+    component.output.reasoning +=
+      props.completion.usage.completion_tokens_details?.reasoning_tokens ?? 0;
+    component.output.rejected_prediction +=
+      props.completion.usage.completion_tokens_details
+        ?.rejected_prediction_tokens ?? 0;
+
+    //----
+    // RE-AGGREGATE
+    //----
+    const sum = (getter: (comp: IAgenticaTokenUsage.IComponent) => number) =>
+      Object.entries(props.usage)
+        .filter(([key]) => key !== "aggregate")
+        .map(([_, comp]) => getter(comp))
+        .reduce((a, b) => a + b, 0);
+    const aggregate: IAgenticaTokenUsage.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 plus = (
+    x: IAgenticaTokenUsage,
+    y: IAgenticaTokenUsage,
+  ): IAgenticaTokenUsage => {
+    const component = (
+      a: IAgenticaTokenUsage.IComponent,
+      b: IAgenticaTokenUsage.IComponent,
+    ): IAgenticaTokenUsage.IComponent => ({
+      total: a.total + b.total,
+      input: {
+        total: a.input.total + b.input.total,
+        cached: a.input.cached + b.input.cached,
+      },
+      output: {
+        total: a.output.total + b.output.total,
+        reasoning: a.output.reasoning + b.output.reasoning,
+        accepted_prediction:
+          a.output.accepted_prediction + b.output.accepted_prediction,
+        rejected_prediction:
+          a.output.rejected_prediction + b.output.rejected_prediction,
+      },
+    });
+    return {
+      aggregate: component(x.aggregate, y.aggregate),
+      initialize: component(x.initialize, y.initialize),
+      select: component(x.select, y.select),
+      cancel: component(x.cancel, y.cancel),
+      call: component(x.call, y.call),
+      describe: component(x.describe, y.describe),
+    };
+  };
+
+  export const zero = (): IAgenticaTokenUsage => {
+    const component = (): IAgenticaTokenUsage.IComponent => ({
+      total: 0,
+      input: {
+        total: 0,
+        cached: 0,
+      },
+      output: {
+        total: 0,
+        reasoning: 0,
+        accepted_prediction: 0,
+        rejected_prediction: 0,
+      },
+    });
+    return {
+      aggregate: component(),
+      initialize: component(),
+      select: component(),
+      cancel: component(),
+      call: component(),
+      describe: component(),
+    };
+  };
+}

package/src/internal/MathUtil.ts

@@ -1,3 +1,3 @@
-export namespace MathUtil {
-  export const round = (value: number): number => Math.floor(value * 100) / 100;
-}
+export namespace MathUtil {
+  export const round = (value: number): number => Math.floor(value * 100) / 100;
+}

package/src/internal/Singleton.ts

@@ -1,22 +1,22 @@
-/**
- * @internal
- */
-export class Singleton<T, Args extends any[] = []> {
-  private readonly closure_: (...args: Args) => T;
-  private value_: T | object;
-
-  public constructor(closure: (...args: Args) => T) {
-    this.closure_ = closure;
-    this.value_ = NOT_MOUNTED_YET;
-  }
-
-  public get(...args: Args): T {
-    if (this.value_ === NOT_MOUNTED_YET) this.value_ = this.closure_(...args);
-    return this.value_ as T;
-  }
-}
-
-/**
- * @internal
- */
-const NOT_MOUNTED_YET = {};
+/**
+ * @internal
+ */
+export class Singleton<T, Args extends any[] = []> {
+  private readonly closure_: (...args: Args) => T;
+  private value_: T | object;
+
+  public constructor(closure: (...args: Args) => T) {
+    this.closure_ = closure;
+    this.value_ = NOT_MOUNTED_YET;
+  }
+
+  public get(...args: Args): T {
+    if (this.value_ === NOT_MOUNTED_YET) this.value_ = this.closure_(...args);
+    return this.value_ as T;
+  }
+}
+
+/**
+ * @internal
+ */
+const NOT_MOUNTED_YET = {};

package/src/internal/__map_take.ts

@@ -1,15 +1,15 @@
-/**
- * @internal
- */
-export const __map_take = <Key, T>(
-  dict: Map<Key, T>,
-  key: Key,
-  generator: () => T,
-): T => {
-  const oldbie: T | undefined = dict.get(key);
-  if (oldbie) return oldbie;
-
-  const value: T = generator();
-  dict.set(key, value);
-  return value;
-};
+/**
+ * @internal
+ */
+export const __map_take = <Key, T>(
+  dict: Map<Key, T>,
+  key: Key,
+  generator: () => T,
+): T => {
+  const oldbie: T | undefined = dict.get(key);
+  if (oldbie) return oldbie;
+
+  const value: T = generator();
+  dict.set(key, value);
+  return value;
+};

package/src/structures/IAgenticaConfig.ts

@@ -1,121 +1,121 @@
-import { IAgenticaContext } from "./IAgenticaContext";
-import { IAgenticaExecutor } from "./IAgenticaExecutor";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
-import { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
-
-/**
- * Configuration for Nestia Agent.
- *
- * `IAgenticaConfig` is an interface that defines the configuration
- * properties of the {@link Agentica}. With this configuration, you
- * can set the user's locale, timezone, and some of 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 A.I. 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 {
-  /**
-   * 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;
-
-  /**
-   * 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;
-
-  /**
-   * System prompt messages.
-   *
-   * System prompt messages if you want to customize the system prompt
-   * messages for each situation.
-   */
-  systemPrompt?: IAgenticaSystemPrompt;
-
-  /**
-   * 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?:
-    | Partial<IAgenticaExecutor>
-    | ((ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>);
-}
+import { IAgenticaContext } from "./IAgenticaContext";
+import { IAgenticaExecutor } from "./IAgenticaExecutor";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+import { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
+
+/**
+ * Configuration for Nestia Agent.
+ *
+ * `IAgenticaConfig` is an interface that defines the configuration
+ * properties of the {@link Agentica}. With this configuration, you
+ * can set the user's locale, timezone, and some of 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 A.I. 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 {
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * System prompt messages.
+   *
+   * System prompt messages if you want to customize the system prompt
+   * messages for each situation.
+   */
+  systemPrompt?: IAgenticaSystemPrompt;
+
+  /**
+   * 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?:
+    | Partial<IAgenticaExecutor>
+    | ((ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>);
+}