@agentica/core 0.7.0-dev.20250224

package/src/internal/MathUtil.ts

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

package/src/internal/Singleton.ts

@@ -0,0 +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 = {};

package/src/internal/__map_take.ts

@@ -0,0 +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;
+};

package/src/structures/IAgenticaConfig.ts

@@ -0,0 +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[]>);
+}

package/src/structures/IAgenticaContext.ts

@@ -0,0 +1,128 @@
+import OpenAI from "openai";
+
+import { AgenticaSource } from "../typings/AgenticaSource";
+import { IAgenticaConfig } from "./IAgenticaConfig";
+import { IAgenticaEvent } from "./IAgenticaEvent";
+import { IAgenticaOperationCollection } from "./IAgenticaOperationCollection";
+import { IAgenticaOperationSelection } from "./IAgenticaOperationSelection";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+
+/**
+ * Context of the Nestia A.I. agent.
+ *
+ * `IAgenticaContext` 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 ChatGptAgent}
+ *   - {@link ChatGptInitializeFunctionAgent}
+ *   - {@link ChatGptSelectFunctionAgent}
+ *   - {@link ChatGptExecuteFunctionAgent}
+ *   - {@link ChatGptDescribeFunctionAgent}
+ *   - {@link ChatGptCancelFunctionAgent}
+ *
+ * Also, as its name is context, it contains every information that
+ * is required to interact with the AI provider 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 IAgenticaContext {
+  //----
+  // 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: IAgenticaOperationCollection;
+
+  /**
+   * 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: IAgenticaPrompt[];
+
+  /**
+   * Stacked operations.
+   *
+   * In other words, list of candidate operations for the LLM function calling.
+   */
+  stack: IAgenticaOperationSelection[];
+
+  /**
+   * Text prompt of the user.
+   *
+   * Text conversation written the by user through the
+   * {@link Agentica.conversate} function.
+   */
+  prompt: IAgenticaPrompt.IText<"user">;
+
+  /**
+   * 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 IAgenticaContext.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: IAgenticaEvent) => 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: AgenticaSource,
+    body: Omit<OpenAI.ChatCompletionCreateParamsNonStreaming, "model">,
+  ) => Promise<OpenAI.ChatCompletion>;
+
+  /**
+   * Initialize the agent.
+   */
+  initialize: () => Promise<void>;
+}

package/src/structures/IAgenticaController.ts

@@ -0,0 +1,130 @@
+import {
+  IHttpConnection,
+  IHttpLlmApplication,
+  IHttpLlmFunction,
+  IHttpResponse,
+} from "@samchon/openapi";
+import { ILlmApplicationOfValidate, ILlmFunctionOfValidate } from "typia";
+
+/**
+ * Controller of the Nestia 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}
+ *
+ * @author Samchon
+ */
+export type IAgenticaController =
+  | IAgenticaController.IHttp
+  | IAgenticaController.IClass;
+export namespace IAgenticaController {
+  /**
+   * HTTP controller.
+   *
+   * You can make it by {@link createHttpLlmApplication} function with
+   * the Swagger or OpenAPI document.
+   */
+  export interface IHttp extends IBase<"http", IHttpLlmApplication<"chatgpt">> {
+    /**
+     * 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<"chatgpt">;
+
+      /**
+       * Function schema.
+       */
+      function: IHttpLlmFunction<"chatgpt">;
+
+      /**
+       * 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", ILlmApplicationOfValidate<"chatgpt">> {
+    /**
+     * 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: ILlmApplicationOfValidate<"chatgpt">;
+
+          /**
+           * Target function schema.
+           */
+          function: ILlmFunctionOfValidate<"chatgpt">;
+
+          /**
+           * Arguments of the function calling.
+           */
+          arguments: object;
+        }) => Promise<unknown>);
+  }
+
+  interface IBase<Protocol, Application> {
+    /**
+     * Protocol discrminator.
+     */
+    protocol: Protocol;
+
+    /**
+     * Name of the controller.
+     */
+    name: string;
+
+    /**
+     * Application schema of function calling.
+     */
+    application: Application;
+  }
+}

package/src/structures/IAgenticaEvent.ts

@@ -0,0 +1,224 @@
+import OpenAI from "openai";
+
+import { AgenticaSource } from "../typings/AgenticaSource";
+import { IAgenticaOperation } from "./IAgenticaOperation";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+
+/**
+ * Nestia A.I. chatbot event.
+ *
+ * `IAgenticaEvent` is an union type of all possible events that can
+ * be emitted by the A.I. chatbot of the {@link Agentica} class. You
+ * can discriminate the subtype by checking the {@link type} property.
+ *
+ * @author Samchon
+ */
+export type IAgenticaEvent =
+  | IAgenticaEvent.IInitialize
+  | IAgenticaEvent.ISelect
+  | IAgenticaEvent.ICancel
+  | IAgenticaEvent.ICall
+  | IAgenticaEvent.IExecute
+  | IAgenticaEvent.IDescribe
+  | IAgenticaEvent.IText
+  | IAgenticaEvent.IRequest
+  | IAgenticaEvent.IResponse;
+export namespace IAgenticaEvent {
+  export type Type = IAgenticaEvent["type"];
+  export type Mapper = {
+    initialize: IInitialize;
+    select: ISelect;
+    cancel: ICancel;
+    call: ICall;
+    execute: IExecute;
+    describe: IDescribe;
+    text: IText;
+    request: IRequest;
+    response: IResponse;
+  };
+
+  /**
+   * Event of initializing the chatbot.
+   */
+  export interface IInitialize extends IBase<"initialize"> {}
+
+  /**
+   * Event of selecting a function to call.
+   */
+  export interface ISelect extends IBase<"select"> {
+    /**
+     * Selected operation.
+     *
+     * Operation that has been selected to prepare LLM function calling.
+     */
+    operation: IAgenticaOperation;
+
+    /**
+     * Reason of selecting the function.
+     *
+     * The A.I. chatbot will fill this property describing why the function
+     * has been selected.
+     */
+    reason: string;
+  }
+
+  /**
+   * Event of canceling a function calling.
+   */
+  export interface ICancel extends IBase<"cancel"> {
+    /**
+     * Selected operation to cancel.
+     *
+     * Operation that has been selected to prepare LLM function calling,
+     * but canceled due to no more required.
+     */
+    operation: IAgenticaOperation;
+
+    /**
+     * Reason of selecting the function.
+     *
+     * The A.I. chatbot will fill this property describing why the function
+     * has been cancelled.
+     *
+     * For reference, if the A.I. chatbot successfully completes the LLM
+     * function calling, the reason of the function cancellation will be
+     * "complete".
+     */
+    reason: string;
+  }
+
+  /**
+   * Event of calling a function.
+   */
+  export interface ICall extends IBase<"call"> {
+    /**
+     * ID of the tool calling.
+     */
+    id: string;
+
+    /**
+     * Target operation to call.
+     */
+    operation: IAgenticaOperation;
+
+    /**
+     * 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: object;
+  }
+
+  /**
+   * Event of function calling execution.
+   */
+  export interface IExecute extends IBase<"execute"> {
+    /**
+     * ID of the tool calling.
+     */
+    id: string;
+
+    /**
+     * Target operation had called.
+     */
+    operation: IAgenticaOperation;
+
+    /**
+     * Arguments of the function calling.
+     */
+    arguments: object;
+
+    /**
+     * Return value.
+     */
+    value: any;
+  }
+
+  /**
+   * Event of description.
+   *
+   * Event describing return values of LLM function callings.
+   */
+  export interface IDescribe extends IBase<"describe"> {
+    /**
+     * Executions of the LLM function calling.
+     *
+     * This prompt describes the return value of them.
+     */
+    executions: IAgenticaPrompt.IExecute[];
+
+    /**
+     * Description text.
+     */
+    text: string;
+  }
+
+  /**
+   * Event of text message.
+   */
+  export interface IText extends IBase<"text"> {
+    /**
+     * Role of the orator.
+     */
+    role: "assistant" | "user";
+
+    /**
+     * The text content.
+     */
+    text: string;
+  }
+
+  /**
+   * Request event of LLM provider API.
+   */
+  export interface IRequest extends IBase<"request"> {
+    /**
+     * The source agent of the request.
+     */
+    source: AgenticaSource;
+
+    /**
+     * Request body.
+     */
+    body: OpenAI.ChatCompletionCreateParamsNonStreaming;
+
+    /**
+     * Options for the request.
+     */
+    options?: OpenAI.RequestOptions | undefined;
+  }
+
+  /**
+   * Response event of LLM provider API.
+   */
+  export interface IResponse extends IBase<"response"> {
+    /**
+     * The source agent of the response.
+     */
+    source: AgenticaSource;
+
+    /**
+     * Request body.
+     */
+    body: OpenAI.ChatCompletionCreateParamsNonStreaming;
+
+    /**
+     * Options for the request.
+     */
+    options?: OpenAI.RequestOptions | undefined;
+
+    /**
+     * Return value from the LLM provider API.
+     */
+    value: OpenAI.ChatCompletion;
+  }
+
+  interface IBase<Type extends string> {
+    /**
+     * Discriminator type.
+     */
+    type: Type;
+  }
+}