@agentica/core 0.7.0-dev.20250224

package/src/structures/IAgenticaExecutor.ts

@@ -0,0 +1,152 @@
+import { IAgenticaContext } from "./IAgenticaContext";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+
+/**
+ * Executor of the Agentic AI.
+ *
+ * `IAgenticaExecutor` represents an executor of the {@link Agentica},
+ * composing its internal agents to accomplish the Agentic AI through
+ * the LLM (Large Language Model) function calling.
+ *
+ * You can customize one of these internal agents by configuring
+ * properties of the `IAgenticaExecutor` type, and assigning it to the
+ * {@link IAgenticaConfig.executor} property. If you set the
+ * {@link initialize} as `null` value, the {@link Agentica} will skip
+ * the initialize process and directly go to the {@link select} process.
+ *
+ * By the way, when customizing the executor member, it would better to
+ * reference the guide documents of `@agentica/core`, and internal
+ * agents' implementation code. It's because if you take some mistake on
+ * the executor logic, it can entirely break the {@link Agentica}'s
+ * operation.
+ *
+ * @reference https://github.com/wrtnlabs/agentica?tab=readme-ov-file#principles
+ * @reference https://github.com/wrtnlabs/agentica/blob/main/packages/agent/src/chatgpt/ChatGptAgent.ts
+ * @author Samchon
+ */
+export interface IAgenticaExecutor {
+  /**
+   * Initializer agent listing up functions.
+   *
+   * `initialize` agent is the first agent that {@link Agentica}
+   * would meet  which judges whether the user's conversation implies
+   * to call some function or not.
+   *
+   * And if the `initialize` agent judges the user's conversation
+   * implies to call some function, the `initialize` agent will
+   * call the {@link IAgenticaContext.initialize} function, and
+   * inform every functions enrolled in the {@link IAgenticaController}
+   * to the AI agent. And then, the `initialize` agent will not never
+   * be called again, and let {@link Agentica} to go to the next
+   * {@link select} agent.
+   *
+   * Otherwise the user's conversation does not imply the request of
+   * function calling, it would just work like plain chatbot, and just
+   * conversate with the user.
+   *
+   * By the way, if you wanna skip the `initialize` agent, you can
+   * do it by configuring the {@link IAgenticaConfig.executor} as
+   * `null` value. In that case, the `initialize` agent will never be
+   * called, and {@link Agentica} just starts from the {@link select}
+   * agent.
+   *
+   * @param ctx Context of the agent
+   * @returns List of prompts generated by the initializer
+   */
+  initialize: null | ((ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>);
+
+  /**
+   * Function selector agent.
+   *
+   * `Select` agent finds candidate functions to call from the
+   * conversation context with the user. And the candidate functions
+   * would be enrolled to the {@link IAgenticaContext.stack}, and the
+   * next {@link call} agent will perform the LLM (Large Language Model)
+   * function calling.
+   *
+   * Note that, the `select` agent does not perform the LLM function
+   * calling. It ends with just finding the candidate functions to call.
+   *
+   * By the way, if the `select` agent can't specify a certain function
+   * to call due to lack of conversation context or homogeneity between
+   * heterogeneous functions, how `select` agent works? In that case,
+   * `select` agent it will just enroll every candidate functions to
+   * the stack, and let the next {@link call} agent to determine the
+   * proper function to call. And then let {@link cancel} agent to erase
+   * the other candidate functions from the stack.
+   *
+   * Additionally, if `select` agent could not find any candidate
+   * function from the conversation context with user, it would just
+   * act like plain chatbot conversating with the user.
+   *
+   * @param ctx Context of the agent
+   * @returns List of prompts generated by the selector
+   */
+  select: (ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>;
+
+  /**
+   * Function caller agent.
+   *
+   * `Call` agent performs the LLM (Large Language Model) function
+   * calling from the candidate functions enrolled in the
+   * {@link IAgenticaContext.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: IAgenticaContext) => Promise<IAgenticaPrompt[]>;
+
+  /**
+   * Describer agent of the function calling result.
+   *
+   * `Describe` agent explains the results of the function callings
+   * to the user as markdown content.
+   *
+   * @param ctx Context of the agent
+   * @param executes List of function calling results
+   * @returns List of prompts generated by the describer
+   */
+  describe: (
+    ctx: IAgenticaContext,
+    executes: IAgenticaPrompt.IExecute[],
+  ) => Promise<IAgenticaPrompt[]>;
+
+  /**
+   * Function canceler agent.
+   *
+   * `Cancel` agent erases the candidate functions from the
+   * {@link IAgenticaContext.stack} by analyzing the conversation
+   * context with the user.
+   *
+   * For reference, the first reason of the cancelation is explicit
+   * order from user to the previous requested function. For example,
+   * user had requested to send an email to the agent, but suddenly
+   * user says to cancel the email sending.
+   *
+   * The seconod reason n of the cancelation is the multiple candidate
+   * functions had been selected at once by the {@link select} agent
+   * due to lack of conversation context or homogeneity between the
+   * heterogeneous functions. And in the multiple candidate functions,
+   * one thing is clearly determined by the {@link call} agent, so that
+   * drop the other candidate functions.
+   *
+   * @param ctx Context of the agent
+   * @returns List of prompts generated by the canceler
+   */
+  cancel: (ctx: IAgenticaContext) => Promise<IAgenticaPrompt[]>;
+}

package/src/structures/IAgenticaOperation.ts

@@ -0,0 +1,64 @@
+import { IHttpLlmFunction } from "@samchon/openapi";
+import { ILlmFunctionOfValidate } from "typia";
+
+import { IAgenticaController } from "./IAgenticaController";
+
+/**
+ * Operation information in the Nestia Agent.
+ *
+ * `IAgenticaOperation` 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 IAgenticaOperation =
+  | IAgenticaOperation.IHttp
+  | IAgenticaOperation.IClass;
+export namespace IAgenticaOperation {
+  /**
+   * HTTP API operation.
+   */
+  export type IHttp = IBase<
+    "http",
+    IAgenticaController.IHttp,
+    IHttpLlmFunction<"chatgpt">
+  >;
+
+  /**
+   * TypeScript class operation.
+   */
+  export type IClass = IBase<
+    "class",
+    IAgenticaController.IClass,
+    ILlmFunctionOfValidate<"chatgpt">
+  >;
+
+  interface IBase<Protocol, Application, Function> {
+    /**
+     * Protocol discriminator.
+     */
+    protocol: Protocol;
+
+    /**
+     * Belonged controller of the target function.
+     */
+    controller: Application;
+
+    /**
+     * Target function to call.
+     */
+    function: Function;
+
+    /**
+     * Identifier name.
+     */
+    name: string;
+  }
+}

package/src/structures/IAgenticaOperationCollection.ts

@@ -0,0 +1,50 @@
+import { IAgenticaOperation } from "./IAgenticaOperation";
+
+/**
+ * Collection of operations used in the Nestia Agent.
+ *
+ * `IAgenticaOperationCollection` is an interface type representing
+ * a collection of operations for several purposes used in the
+ * {@link Agentica} internally.
+ *
+ * @author Samchon
+ */
+export interface IAgenticaOperationCollection {
+  /**
+   * List of every operations.
+   */
+  array: IAgenticaOperation[];
+
+  /**
+   * Divided operations.
+   *
+   * If you've configured the {@link IAgenticaConfig.capacity} property,
+   * the  A.I. chatbot ({@link Agentica}) will separate the operations
+   * into the several groups to divide and conquer and LLM function selecting
+   * for accuracy.
+   *
+   * In that case, this property `divided`'s length would be dtermined by
+   * dividing the number of operations ({@link array}'s length) by the
+   * {@link IAgenticaConfig.capacity}.
+   *
+   * Otherwise, if the {@link IAgenticaConfig.capacity} has not been
+   * configured, this `divided` property would be the `undefined` value.
+   */
+  divided?: IAgenticaOperation[][] | undefined;
+
+  /**
+   * Flat dictionary of operations.
+   *
+   * Dictionary of operations with their {@link IAgenticaOperation.name}.
+   */
+  flat: Map<string, IAgenticaOperation>;
+
+  /**
+   * Group dictionary of operations.
+   *
+   * Dictionary of operations with their
+   * {@link IAgenticaOperation.controller.name} and
+   * {@link IAgenticaOperation.function.name}.
+   */
+  group: Map<string, Map<string, IAgenticaOperation>>;
+}

package/src/structures/IAgenticaOperationSelection.ts

@@ -0,0 +1,69 @@
+import { IHttpLlmFunction } from "@samchon/openapi";
+import { ILlmFunctionOfValidate } from "typia";
+
+import { IAgenticaController } from "./IAgenticaController";
+
+/**
+ * Nestia agent operation selection.
+ *
+ * `IAgenticaOperationSelection` is a type represents an operation
+ * which has been selected by the A.I. chatbot of {@link Agentica}
+ * class for the LLM (Large Language Model) function calling with
+ * detailed {@link reason} of the selection (or cancellation).
+ *
+ * Also, `IAgenticaOperationSelection` is an union type that can
+ * specify a subtype by checking the {@link protocol} property.
+ *
+ * @author Samchon
+ */
+export type IAgenticaOperationSelection =
+  | IAgenticaOperationSelection.IHttp
+  | IAgenticaOperationSelection.IClass;
+export namespace IAgenticaOperationSelection {
+  export type IHttp = IBase<
+    "http",
+    IAgenticaController.IHttp,
+    IHttpLlmFunction<"chatgpt">
+  >;
+
+  export type IClass = IBase<
+    "class",
+    IAgenticaController.IClass,
+    ILlmFunctionOfValidate<"chatgpt">
+  >;
+
+  interface IBase<Protocol, Controller, Function> {
+    /**
+     * Discriminator protocol.
+     */
+    protocol: Protocol;
+
+    /**
+     * Belonged controller of the target function.
+     */
+    controller: Controller;
+
+    /**
+     * Target function.
+     *
+     * Function that has been selected to prepare LLM function calling,
+     * or canceled due to no more required.
+     */
+    function: Function;
+
+    /**
+     * Identifier name of the target function.
+     *
+     * If {@link Agentica} has multiple {@link IAgenticaController}s,
+     * the `name` can be different from target function's name.
+     */
+    name: string;
+
+    /**
+     * The reason of the function selection or cancellation.
+     */
+    reason: string;
+
+    toJSON(): Omit<IBase<Protocol, string, string>, "toJSON">;
+  }
+}

package/src/structures/IAgenticaPrompt.ts

@@ -0,0 +1,173 @@
+import { IHttpLlmFunction, IHttpResponse } from "@samchon/openapi";
+import { ILlmFunctionOfValidate } from "typia";
+
+import { IAgenticaController } from "./IAgenticaController";
+import { IAgenticaOperationSelection } from "./IAgenticaOperationSelection";
+
+/**
+ * Nestia A.I. chatbot prompt.
+ *
+ * `IWrtnChatPrompt` is an union type of all possible prompts that can
+ * be generated by the A.I. chatbot of the {@link Agentica} class.
+ *
+ * In other words, `IWrtnChatPrompt` is a type of chat history that
+ * is occurred during the conversation between the user and the A.I. chatbot
+ * in the {@link Agentica} class.
+ *
+ * If you want to continue the previous A.I. chatbot session, you can
+ * accomplish it by assigning the {@link IAgenticaProps.histories}
+ * property when creating a new {@link Agentica} instance.
+ *
+ * @author Samchon
+ */
+export type IAgenticaPrompt =
+  | IAgenticaPrompt.IText
+  | IAgenticaPrompt.ISelect
+  | IAgenticaPrompt.ICancel
+  | IAgenticaPrompt.IExecute
+  | IAgenticaPrompt.IDescribe;
+export namespace IAgenticaPrompt {
+  /**
+   * Select prompt.
+   *
+   * Selection prompt about candidate functions to call.
+   */
+  export interface ISelect extends IBase<"select"> {
+    /**
+     * ID of the LLM tool call result.
+     */
+    id: string;
+
+    /**
+     * Operations that have been selected.
+     */
+    operations: IAgenticaOperationSelection[];
+  }
+
+  /**
+   * Cancel prompt.
+   *
+   * Cancellation prompt about the candidate functions to be discarded.
+   */
+  export interface ICancel extends IBase<"cancel"> {
+    /**
+     * ID of the LLM tool call result.
+     */
+    id: string;
+
+    /**
+     * Operations that have been cancelled.
+     */
+    operations: IAgenticaOperationSelection[];
+  }
+
+  /**
+   * Execute prompt.
+   *
+   * Execution prompt about the LLM function calling.
+   */
+  export type IExecute = IExecute.IHttp | IExecute.IClass;
+  export namespace IExecute {
+    export type IHttp = IBase<
+      "http",
+      IAgenticaController.IHttp,
+      IHttpLlmFunction<"chatgpt">,
+      IHttpResponse
+    >;
+    export type IClass = IBase<
+      "class",
+      IAgenticaController.IClass,
+      ILlmFunctionOfValidate<"chatgpt">,
+      any
+    >;
+    interface IBase<Protocol, Controller, Function, Value> {
+      /**
+       * Discriminator type.
+       */
+      type: "execute";
+
+      /**
+       * Protocol discriminator.
+       */
+      protocol: Protocol;
+
+      /**
+       * Belonged controller of the target function.
+       */
+      controller: Controller;
+
+      /**
+       * Target function to call.
+       */
+      function: Function;
+
+      /**
+       * ID of the LLM tool call result.
+       */
+      id: string;
+
+      /**
+       * Identifier name of the function.
+       *
+       * If {@link Agentica} has multiple {@link IAgenticaController}s,
+       * the `name` can be different from target function's name.
+       */
+      name: string;
+
+      /**
+       * Arguments of the LLM function calling.
+       */
+      arguments: object;
+
+      /**
+       * Return value.
+       */
+      value: Value;
+
+      toJSON(): Omit<IBase<Protocol, string, string, Value>, "toJSON">;
+    }
+  }
+
+  /**
+   * Description prompt.
+   *
+   * Description prompt about the return value of the LLM function calling.
+   */
+  export interface IDescribe extends IBase<"describe"> {
+    /**
+     * Executions of the LLM function calling.
+     *
+     * This prompt describes the return value of them.
+     */
+    executions: IExecute[];
+
+    /**
+     * Description text.
+     */
+    text: string;
+  }
+
+  /**
+   * Text prompt.
+   */
+  export interface IText<
+    Role extends "assistant" | "user" = "assistant" | "user",
+  > extends IBase<"text"> {
+    /**
+     * Role of the orator.
+     */
+    role: Role;
+
+    /**
+     * The text content.
+     */
+    text: string;
+  }
+
+  interface IBase<Type extends string> {
+    /**
+     * Discriminator type.
+     */
+    type: Type;
+  }
+}

package/src/structures/IAgenticaProps.ts

@@ -0,0 +1,64 @@
+import { Primitive } from "typia";
+
+import { IAgenticaConfig } from "./IAgenticaConfig";
+import { IAgenticaController } from "./IAgenticaController";
+import { IAgenticaPrompt } from "./IAgenticaPrompt";
+import { IAgenticaProvider } from "./IAgenticaProvider";
+
+/**
+ * Properties of the Nestia Agent.
+ *
+ * `IAgenticaProps` is an interface that defines the properties
+ * of the {@link Agentica.constructor}. In the `IAgenticaProps`,
+ * there're everything to prepare to create a Super A.I. chatbot
+ * performing the LLM (Large Language Model) function calling.
+ *
+ * At first, you have to specify the LLM service {@link provider} 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 IAgenticaProps {
+  /**
+   * LLM service provider.
+   */
+  provider: IAgenticaProvider;
+
+  /**
+   * 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/samchon/nestia/tree/master/packages/agent/prompts
+   */
+  config?: IAgenticaConfig;
+
+  /**
+   * Prompt histories.
+   *
+   * If you're starting the conversation from an existing session,
+   * assign the previouis prompt histories to this property.
+   */
+  histories?: Primitive<IAgenticaPrompt>[];
+}

package/src/structures/IAgenticaProvider.ts

@@ -0,0 +1,45 @@
+import OpenAI from "openai";
+
+/**
+ * LLM Provider for Nestia Chat.
+ *
+ * `IAgenticaProvider` is a type represents an LLM
+ * (Large Language Model) provider of the {@link Agentica}.
+ *
+ * Currently, {@link Agentica} is supporting only one provider OpenAI.
+ * You can specify the provider by configuring the `type` property as
+ * `"chatgpt"`. Also, you have to assign the OpenAI API client instance
+ * to the `api` property, and specify the `model` to use.
+ *
+ * If you want to use another LLM provider like Claude or Gemini,
+ * please write an issue or contribute to `nestia` please.
+ *
+ * @author Samchon
+ */
+export type IAgenticaProvider = IAgenticaProvider.IChatGpt;
+export namespace IAgenticaProvider {
+  /**
+   * OpenAI provider.
+   */
+  export interface IChatGpt {
+    /**
+     * Discriminator type.
+     */
+    type: "chatgpt";
+
+    /**
+     * OpenAI API instance.
+     */
+    api: OpenAI;
+
+    /**
+     * Chat model to be used.
+     */
+    model: OpenAI.ChatModel;
+
+    /**
+     * Options for the request.
+     */
+    options?: OpenAI.RequestOptions | undefined;
+  }
+}