@agentica/core 0.10.4 → 0.11.0

package/src/json/IAgenticaPromptJson.ts

@@ -0,0 +1,130 @@
+import { IAgenticaOperationJson } from "./IAgenticaOperationJson";
+import { IAgenticaOperationSelectionJson } from "./IAgenticaOperationSelectionJson";
+
+/**
+ * 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 IAgenticaPromptJson =
+  | IAgenticaPromptJson.IText
+  | IAgenticaPromptJson.ISelect
+  | IAgenticaPromptJson.ICancel
+  | IAgenticaPromptJson.IExecute
+  | IAgenticaPromptJson.IDescribe;
+export namespace IAgenticaPromptJson {
+  /**
+   * 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.
+     */
+    selections: IAgenticaOperationSelectionJson[];
+  }
+
+  /**
+   * 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.
+     */
+    selections: IAgenticaOperationSelectionJson[];
+  }
+
+  /**
+   * Execute prompt.
+   *
+   * Execution prompt about the LLM function calling.
+   */
+  export interface IExecute extends IBase<"execute"> {
+    /**
+     * ID of the LLM tool call result.
+     */
+    id: string;
+
+    /**
+     * Target operation to call.
+     */
+    operation: IAgenticaOperationJson;
+
+    /**
+     * Arguments of the LLM function calling.
+     */
+    arguments: Record<string, any>;
+
+    /**
+     * Return value.
+     */
+    value: any;
+  }
+
+  /**
+   * 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/IAgenticaTokenUsage.ts → json/IAgenticaTokenUsageJson.ts}

@@ -1,12 +1,12 @@
 /**
  * Token usage information from the A.I. chatbot.
  *
- * `IAgenticaTokenUsage` is a structure representing the token usage
+ * `IAgenticaTokenUsageJson` is a structure representing the token usage
  * information from the {@link Agentica} class. And you can get the
  * token usage information by calling the {@link Agentica.getTokenUsage}
  * method.
  *
- * For reference, `IAgenticaTokenUsage` provides only the token usage
+ * For reference, `IAgenticaTokenUsageJson` provides only the token usage
  * information, and does not contain any price or cost information. It is
  * because the price or cost can be changed by below reasons.
  *
@@ -16,38 +16,38 @@
  *
  * @author Samchon
  */
-export interface IAgenticaTokenUsage {
+export interface IAgenticaTokenUsageJson {
   /**
    * Aggregated token usage.
    */
-  aggregate: IAgenticaTokenUsage.IComponent;
+  aggregate: IAgenticaTokenUsageJson.IComponent;
 
   /**
    * Token uasge of initializer agent.
    */
-  initialize: IAgenticaTokenUsage.IComponent;
+  initialize: IAgenticaTokenUsageJson.IComponent;
 
   /**
    * Token usage of function selector agent.
    */
-  select: IAgenticaTokenUsage.IComponent;
+  select: IAgenticaTokenUsageJson.IComponent;
 
   /**
    * Token usage of function canceler agent.
    */
-  cancel: IAgenticaTokenUsage.IComponent;
+  cancel: IAgenticaTokenUsageJson.IComponent;
 
   /**
    * Token usage of function caller agent.
    */
-  call: IAgenticaTokenUsage.IComponent;
+  call: IAgenticaTokenUsageJson.IComponent;
 
   /**
    * Token usage of function calling describer agent.
    */
-  describe: IAgenticaTokenUsage.IComponent;
+  describe: IAgenticaTokenUsageJson.IComponent;
 }
-export namespace IAgenticaTokenUsage {
+export namespace IAgenticaTokenUsageJson {
   export interface IComponent {
     /**
      * Total token usage.

package/src/prompts/AgenticaCancelPrompt.ts

@@ -0,0 +1,32 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
+import { AgenticaPromptBase } from "./AgenticaPromptBase";
+
+export class AgenticaCancelPrompt<
+  Model extends ILlmSchema.Model,
+> extends AgenticaPromptBase<"cancel", IAgenticaPromptJson.ICancel> {
+  public readonly id: string;
+  public readonly selections: AgenticaOperationSelection<Model>[];
+
+  public constructor(props: AgenticaCancelPrompt.IProps<Model>) {
+    super("cancel");
+    this.id = props.id;
+    this.selections = props.selections;
+  }
+
+  public toJSON(): IAgenticaPromptJson.ICancel {
+    return {
+      type: this.type,
+      id: this.id,
+      selections: this.selections.map((s) => s.toJSON()),
+    };
+  }
+}
+export namespace AgenticaCancelPrompt {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    id: string;
+    selections: AgenticaOperationSelection<Model>[];
+  }
+}

package/src/prompts/AgenticaDescribePrompt.ts

@@ -0,0 +1,41 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
+import { AgenticaExecutePrompt } from "./AgenticaExecutePrompt";
+import { AgenticaPromptBase } from "./AgenticaPromptBase";
+
+export class AgenticaDescribePrompt<
+  Model extends ILlmSchema.Model,
+> extends AgenticaPromptBase<"describe", IAgenticaPromptJson.IDescribe> {
+  /**
+   * Executions of the LLM function calling.
+   *
+   * This prompt describes the return value of them.
+   */
+  public readonly executes: AgenticaExecutePrompt<Model>[];
+
+  /**
+   * Description text.
+   */
+  public readonly text: string;
+
+  public constructor(props: AgenticaDescribePrompt.IProps<Model>) {
+    super("describe");
+    this.executes = props.executes;
+    this.text = props.text;
+  }
+
+  public toJSON(): IAgenticaPromptJson.IDescribe {
+    return {
+      type: this.type,
+      executions: this.executes.map((e) => e.toJSON()),
+      text: this.text,
+    };
+  }
+}
+export namespace AgenticaDescribePrompt {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    executes: AgenticaExecutePrompt<Model>[];
+    text: string;
+  }
+}

package/src/prompts/AgenticaExecutePrompt.ts

@@ -0,0 +1,52 @@
+import { IHttpResponse, ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaOperation } from "../context/AgenticaOperation";
+import { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
+import { AgenticaPromptBase } from "./AgenticaPromptBase";
+
+export class AgenticaExecutePrompt<
+  Model extends ILlmSchema.Model,
+  Protocol extends "http" | "class" = any,
+> extends AgenticaPromptBase<"execute", IAgenticaPromptJson.IExecute> {
+  public readonly id: string;
+  public readonly operation: Protocol extends "http"
+    ? AgenticaOperation.Http<Model>
+    : Protocol extends "class"
+      ? AgenticaOperation.Class<Model>
+      : AgenticaOperation<Model>;
+  public readonly arguments: Record<string, any>;
+  public readonly value: Protocol extends "http" ? IHttpResponse : any;
+
+  public constructor(props: AgenticaExecutePrompt.IProps<Model, Protocol>) {
+    super("execute");
+    this.id = props.id;
+    this.operation = props.operation;
+    this.arguments = props.arguments;
+    this.value = props.value;
+  }
+
+  public toJSON(): IAgenticaPromptJson.IExecute {
+    return {
+      type: this.type,
+      id: this.id,
+      operation: this.operation.toJSON(),
+      arguments: this.arguments,
+      value: this.value,
+    };
+  }
+}
+export namespace AgenticaExecutePrompt {
+  export interface IProps<
+    Model extends ILlmSchema.Model,
+    Protocol extends "http" | "class" = any,
+  > {
+    id: string;
+    operation: Protocol extends "http"
+      ? AgenticaOperation.Http<Model>
+      : Protocol extends "class"
+        ? AgenticaOperation.Class<Model>
+        : AgenticaOperation<Model>;
+    arguments: Record<string, any>;
+    value: Protocol extends "http" ? IHttpResponse : any;
+  }
+}

package/src/prompts/AgenticaPrompt.ts

@@ -0,0 +1,14 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaCancelPrompt } from "../context/AgenticaCancelPrompt";
+import { AgenticaDescribePrompt } from "./AgenticaDescribePrompt";
+import { AgenticaExecutePrompt } from "./AgenticaExecutePrompt";
+import { AgenticaSelectPrompt } from "./AgenticaSelectPrompt";
+import { AgenticaTextPrompt } from "./AgenticaTextPrompt";
+
+export type AgenticaPrompt<Model extends ILlmSchema.Model> =
+  | AgenticaCancelPrompt<Model>
+  | AgenticaDescribePrompt<Model>
+  | AgenticaExecutePrompt<Model>
+  | AgenticaSelectPrompt<Model>
+  | AgenticaTextPrompt;

package/src/prompts/AgenticaPromptBase.ts

@@ -0,0 +1,27 @@
+/**
+ * Base class for all prompts in Agentica.
+ *
+ * `AgenticaPromptBase` is a base class for every prompt classes
+ * in Agentica. It is generated by {@link Agentica.conversate} function,
+ * and used for restoring the previous conversation history when
+ * constructing the {@link Agentica} instance.
+ *
+ * @template Type Discriminator type
+ * @template Json Primitive type of the prompt
+ * @author Samchon
+ */
+export abstract class AgenticaPromptBase<
+  Type extends string,
+  Json extends { type: Type },
+> {
+  /**
+   * Discriminator type.
+   */
+  public readonly type: Type;
+
+  protected constructor(type: Type) {
+    this.type = type;
+  }
+
+  public abstract toJSON(): Json;
+}

package/src/prompts/AgenticaSelectPrompt.ts

@@ -0,0 +1,32 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
+import { AgenticaPromptBase } from "./AgenticaPromptBase";
+
+export class AgenticaSelectPrompt<
+  Model extends ILlmSchema.Model,
+> extends AgenticaPromptBase<"select", IAgenticaPromptJson.ISelect> {
+  public readonly id: string;
+  public readonly selections: AgenticaOperationSelection<Model>[];
+
+  public constructor(props: AgenticaSelectPrompt.IProps<Model>) {
+    super("select");
+    this.id = props.id;
+    this.selections = props.selections;
+  }
+
+  public toJSON(): IAgenticaPromptJson.ISelect {
+    return {
+      type: this.type,
+      id: this.id,
+      selections: this.selections.map((s) => s.toJSON()),
+    };
+  }
+}
+export namespace AgenticaSelectPrompt {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    id: string;
+    selections: AgenticaOperationSelection<Model>[];
+  }
+}

package/src/prompts/AgenticaTextPrompt.ts

@@ -0,0 +1,31 @@
+import { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
+import { AgenticaPromptBase } from "./AgenticaPromptBase";
+
+export class AgenticaTextPrompt<
+  Role extends "assistant" | "user" = "assistant" | "user",
+> extends AgenticaPromptBase<"text", IAgenticaPromptJson.IText> {
+  public readonly role: Role;
+  public readonly text: string;
+
+  public constructor(props: AgenticaTextPrompt.IProps<Role>) {
+    super("text");
+    this.role = props.role;
+    this.text = props.text;
+  }
+
+  public toJSON(): IAgenticaPromptJson.IText<Role> {
+    return {
+      type: this.type,
+      role: this.role,
+      text: this.text,
+    };
+  }
+}
+export namespace AgenticaTextPrompt {
+  export interface IProps<
+    Role extends "assistant" | "user" = "assistant" | "user",
+  > {
+    role: Role;
+    text: string;
+  }
+}

package/src/structures/IAgenticaConfig.ts

@@ -1,8 +1,8 @@
 import { ILlmSchema } from "@samchon/openapi";
 
-import { IAgenticaContext } from "./IAgenticaContext";
+import { AgenticaContext } from "../context/AgenticaContext";
+import { AgenticaPrompt } from "../prompts/AgenticaPrompt";
 import { IAgenticaExecutor } from "./IAgenticaExecutor";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
 import { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
 
 /**
@@ -119,5 +119,5 @@ export interface IAgenticaConfig<Model extends ILlmSchema.Model> {
    */
   executor?:
     | Partial<IAgenticaExecutor<Model>>
-    | ((ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>);
+    | ((ctx: AgenticaContext<Model>) => Promise<AgenticaPrompt<Model>[]>);
 }

package/src/structures/IAgenticaExecutor.ts

@@ -1,7 +1,8 @@
 import { ILlmSchema } from "@samchon/openapi";
 
-import { IAgenticaContext } from "./IAgenticaContext";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
+import { AgenticaContext } from "../context/AgenticaContext";
+import { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
+import { AgenticaPrompt } from "../prompts/AgenticaPrompt";
 
 /**
  * Executor of the Agentic AI.
@@ -36,7 +37,7 @@ export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
    *
    * 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
+   * call the {@link AgenticaContext.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
@@ -57,14 +58,14 @@ export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
    */
   initialize:
     | null
-    | ((ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>);
+    | ((ctx: AgenticaContext<Model>) => Promise<AgenticaPrompt<Model>[]>);
 
   /**
    * 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
+   * would be enrolled to the {@link AgenticaContext.stack}, and the
    * next {@link call} agent will perform the LLM (Large Language Model)
    * function calling.
    *
@@ -86,14 +87,14 @@ export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
    * @param ctx Context of the agent
    * @returns List of prompts generated by the selector
    */
-  select: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
+  select: (ctx: AgenticaContext<Model>) => Promise<AgenticaPrompt<Model>[]>;
 
   /**
    * 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
+   * {@link AgenticaContext.stack}. And the scope of function calling
    * is, not only just arguments filling, but also actual executing
    * the function and returning the result.
    *
@@ -113,7 +114,7 @@ export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
    *          agent is the most general topic which can be universally
    *          applied to all domain fields.
    */
-  call: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
+  call: (ctx: AgenticaContext<Model>) => Promise<AgenticaPrompt<Model>[]>;
 
   /**
    * Describer agent of the function calling result.
@@ -126,15 +127,15 @@ export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
    * @returns List of prompts generated by the describer
    */
   describe: (
-    ctx: IAgenticaContext<Model>,
-    executes: IAgenticaPrompt.IExecute<Model>[],
-  ) => Promise<IAgenticaPrompt<Model>[]>;
+    ctx: AgenticaContext<Model>,
+    executes: AgenticaExecutePrompt<Model>[],
+  ) => Promise<AgenticaPrompt<Model>[]>;
 
   /**
    * Function canceler agent.
    *
    * `Cancel` agent erases the candidate functions from the
-   * {@link IAgenticaContext.stack} by analyzing the conversation
+   * {@link AgenticaContext.stack} by analyzing the conversation
    * context with the user.
    *
    * For reference, the first reason of the cancelation is explicit
@@ -152,5 +153,5 @@ export interface IAgenticaExecutor<Model extends ILlmSchema.Model> {
    * @param ctx Context of the agent
    * @returns List of prompts generated by the canceler
    */
-  cancel: (ctx: IAgenticaContext<Model>) => Promise<IAgenticaPrompt<Model>[]>;
+  cancel: (ctx: AgenticaContext<Model>) => Promise<AgenticaPrompt<Model>[]>;
 }

package/src/structures/IAgenticaProps.ts

@@ -1,9 +1,8 @@
 import { ILlmSchema } from "@samchon/openapi";
-import { Primitive } from "typia";
 
+import { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
 import { IAgenticaConfig } from "./IAgenticaConfig";
 import { IAgenticaController } from "./IAgenticaController";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
 import { IAgenticaVendor } from "./IAgenticaVendor";
 
 /**
@@ -66,5 +65,5 @@ export interface IAgenticaProps<Model extends ILlmSchema.Model> {
    * If you're starting the conversation from an existing session,
    * assign the previouis prompt histories to this property.
    */
-  histories?: Primitive<IAgenticaPrompt<Model>>[];
+  histories?: IAgenticaPromptJson[];
 }

package/src/structures/IAgenticaSystemPrompt.ts

@@ -1,7 +1,8 @@
 import { ILlmSchema } from "@samchon/openapi";
 
+import { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
+import { AgenticaPrompt } from "../prompts/AgenticaPrompt";
 import { IAgenticaConfig } from "./IAgenticaConfig";
-import { IAgenticaPrompt } from "./IAgenticaPrompt";
 
 /**
  * System prompt collection of the A.I. chatbot.
@@ -41,13 +42,13 @@ export interface IAgenticaSystemPrompt<Model extends ILlmSchema.Model> {
    *
    * In that case, the `initialize` system prompt would be used. You can
    * customize the `initialize` system prompt by assigning this function
-   * with the given {@link IAgenticaPrompt histories} parameter.
+   * with the given {@link AgenticaPrompt histories} parameter.
    *
    * @param histories Histories of the previous prompts
    * @returns initialize system prompt
    * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/initialize.md
    */
-  initialize?: (histories: IAgenticaPrompt<Model>[]) => string;
+  initialize?: (histories: AgenticaPrompt<Model>[]) => string;
 
   /**
    * Select system prompt.
@@ -58,7 +59,7 @@ export interface IAgenticaSystemPrompt<Model extends ILlmSchema.Model> {
    *
    * In that case, this `select` system prompt would be used. You can
    * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
+   * {@link AgenticaPrompt histories} parameter.
    *
    * Note that, the `"select"` means only the function selection. It does
    * not contain the filling argument or executing the function. It
@@ -68,7 +69,7 @@ export interface IAgenticaSystemPrompt<Model extends ILlmSchema.Model> {
    * @returns select system promopt
    * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/select.md
    */
-  select?: (histories: IAgenticaPrompt<Model>[]) => string;
+  select?: (histories: AgenticaPrompt<Model>[]) => string;
 
   /**
    * Cancel system prompt.
@@ -79,13 +80,13 @@ export interface IAgenticaSystemPrompt<Model extends ILlmSchema.Model> {
    *
    * In that case, this `cancel` system prompt would be used. You can
    * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
+   * {@link AgenticaPrompt histories} parameter.
    *
    * @param histories Histories of the previous prompts
    * @returns cancel system prompt
    * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/cancel.md
    */
-  cancel?: (histories: IAgenticaPrompt<Model>[]) => string;
+  cancel?: (histories: AgenticaPrompt<Model>[]) => string;
 
   /**
    * Execute system prompt.
@@ -97,13 +98,13 @@ export interface IAgenticaSystemPrompt<Model extends ILlmSchema.Model> {
    *
    * In that case, this `execute` system prompt would be used. You can
    * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
+   * {@link AgenticaPrompt histories} parameter.
    *
    * @param histories Histories of the previous prompts
    * @returns execute system prompt
    * https://github.com/samchon/nestia/blob/master/packages/agent/prompts/execute.md
    */
-  execute?: (histories: IAgenticaPrompt<Model>[]) => string;
+  execute?: (histories: AgenticaPrompt<Model>[]) => string;
 
   /**
    * Describe system prompt.
@@ -114,11 +115,11 @@ export interface IAgenticaSystemPrompt<Model extends ILlmSchema.Model> {
    *
    * In that case, this `describe` system prompt would be used. You can
    * customize it by assigning this function with the given
-   * {@link IAgenticaPrompt histories} parameter.
+   * {@link AgenticaPrompt histories} parameter.
    *
    * @param histories Histories of the previous prompts
    * @returns describe system prompt
    * @default https://github.com/samchon/nestia/blob/master/packages/agent/prompts/describe.md
    */
-  describe?: (histories: IAgenticaPrompt.IExecute<Model>[]) => string;
+  describe?: (histories: AgenticaExecutePrompt<Model>[]) => string;
 }