@agentica/core 0.13.4 → 0.14.0

package/src/Agentica.ts

@@ -1,5 +1,4 @@
 import type { ILlmSchema } from "@samchon/openapi";
-
 import type { AgenticaContext } from "./context/AgenticaContext";
 import type { AgenticaOperation } from "./context/AgenticaOperation";
 import type { AgenticaOperationCollection } from "./context/AgenticaOperationCollection";
@@ -10,18 +9,19 @@ import type { IAgenticaConfig } from "./structures/IAgenticaConfig";
 import type { IAgenticaController } from "./structures/IAgenticaController";
 import type { IAgenticaProps } from "./structures/IAgenticaProps";
 import type { IAgenticaVendor } from "./structures/IAgenticaVendor";
-import { ChatGptAgent } from "./chatgpt/ChatGptAgent";
-import { ChatGptCompletionMessageUtil } from "./chatgpt/ChatGptCompletionMessageUtil";
+import type { AgenticaTextPrompt } from "./prompts/AgenticaTextPrompt";
+import type { AgenticaRequestEvent } from "./events/AgenticaRequestEvent";
+
+import { ChatGptAgent } from "./orchestrate/ChatGptAgent";
+import { ChatGptCompletionMessageUtil } from "./orchestrate/ChatGptCompletionMessageUtil";
 import { AgenticaTokenUsage } from "./context/AgenticaTokenUsage";
 import { AgenticaTokenUsageAggregator } from "./context/internal/AgenticaTokenUsageAggregator";
-import { AgenticaInitializeEvent } from "./events/AgenticaInitializeEvent";
-import { AgenticaRequestEvent } from "./events/AgenticaRequestEvent";
-import { AgenticaTextEvent } from "./events/AgenticaTextEvent";
 import { __map_take } from "./internal/__map_take";
 import { AgenticaOperationComposer } from "./internal/AgenticaOperationComposer";
 import { StreamUtil } from "./internal/StreamUtil";
-import { AgenticaTextPrompt } from "./prompts/AgenticaTextPrompt";
 import { AgenticaPromptTransformer } from "./transformers/AgenticaPromptTransformer";
+import { createTextPrompt } from "./factory/prompts";
+import { createInitializeEvent, createRequestEvent, createTextEvent } from "./factory/events";
 
 /**
  * Nestia A.I. chatbot agent.
@@ -126,12 +126,12 @@ export class Agentica<Model extends ILlmSchema.Model> {
    * @returns List of newly created chat prompts
    */
   public async conversate(content: string): Promise<AgenticaPrompt<Model>[]> {
-    const prompt: AgenticaTextPrompt<"user"> = new AgenticaTextPrompt({
+    const prompt: AgenticaTextPrompt<"user"> = createTextPrompt<"user">({
       role: "user",
       text: content,
     });
     await this.dispatch(
-      new AgenticaTextEvent({
+      createTextEvent({
         role: "user",
         stream: StreamUtil.to(content),
         done: () => true,
@@ -232,7 +232,7 @@ export class Agentica<Model extends ILlmSchema.Model> {
       dispatch: async event => this.dispatch(event),
       request: async (source, body) => {
         // request information
-        const event: AgenticaRequestEvent = new AgenticaRequestEvent({
+        const event: AgenticaRequestEvent = createRequestEvent({
           source,
           body: {
             ...body,
@@ -294,7 +294,7 @@ export class Agentica<Model extends ILlmSchema.Model> {
       },
       initialize: async () => {
         this.ready_ = true;
-        await dispatch(new AgenticaInitializeEvent());
+        await dispatch(createInitializeEvent());
       },
     };
   }

package/src/context/AgenticaCancelPrompt.ts

@@ -1,32 +1,11 @@
 import type { ILlmSchema } from "@samchon/openapi";
-
 import type { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
+import type { AgenticaPromptBase } from "../prompts/AgenticaPromptBase";
 import type { AgenticaOperationSelection } from "./AgenticaOperationSelection";
-import { AgenticaPromptBase } from "../prompts/AgenticaPromptBase";
 
-export class AgenticaCancelPrompt<
+export interface 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>[];
-  }
+  id: string;
+  selections: AgenticaOperationSelection<Model>[];
 }

package/src/context/AgenticaContext.ts

@@ -1,6 +1,5 @@
 import type { ILlmSchema } from "@samchon/openapi";
 import type OpenAI from "openai";
-
 import type { AgenticaEvent } from "../events/AgenticaEvent";
 import type { AgenticaEventSource } from "../events/AgenticaEventSource";
 import type { AgenticaPrompt } from "../prompts/AgenticaPrompt";

package/src/context/AgenticaOperation.ts

@@ -1,5 +1,4 @@
 import type { IHttpLlmFunction, ILlmFunction, ILlmSchema } from "@samchon/openapi";
-
 import type { IAgenticaOperationJson } from "../json/IAgenticaOperationJson";
 import type { IAgenticaController } from "../structures/IAgenticaController";
 

package/src/context/AgenticaOperationCollection.ts

@@ -1,5 +1,4 @@
 import type { ILlmSchema } from "@samchon/openapi";
-
 import type { AgenticaOperation } from "./AgenticaOperation";
 
 /**

package/src/context/AgenticaOperationSelection.ts

@@ -1,27 +1,9 @@
 import type { ILlmSchema } from "@samchon/openapi";
-
 import type { IAgenticaOperationSelectionJson } from "../json/IAgenticaOperationSelectionJson";
 import type { AgenticaOperation } from "./AgenticaOperation";
 
-export class AgenticaOperationSelection<Model extends ILlmSchema.Model> {
-  public readonly operation: AgenticaOperation<Model>;
-  public readonly reason: string;
-
-  public constructor(props: AgenticaOperationSelection.IProps<Model>) {
-    this.operation = props.operation;
-    this.reason = props.reason;
-  }
-
-  public toJSON(): IAgenticaOperationSelectionJson {
-    return {
-      operation: this.operation.toJSON(),
-      reason: this.reason,
-    };
-  }
-}
-export namespace AgenticaOperationSelection {
-  export interface IProps<Model extends ILlmSchema.Model> {
-    operation: AgenticaOperation<Model>;
-    reason: string;
-  }
+export interface AgenticaOperationSelection<Model extends ILlmSchema.Model> {
+  operation: AgenticaOperation<Model>;
+  reason: string;
+  toJSON: () => IAgenticaOperationSelectionJson;
 }

package/src/context/AgenticaTokenUsage.ts

@@ -1,7 +1,7 @@
-import type { IAgenticaTokenUsageJson } from "../json/IAgenticaTokenUsageJson";
-
 import typia from "typia";
 
+import type { IAgenticaTokenUsageJson } from "../json/IAgenticaTokenUsageJson";
+
 export class AgenticaTokenUsage implements IAgenticaTokenUsageJson {
   /**
    * Aggregated token usage.

package/src/context/internal/AgenticaTokenUsageAggregator.ts

@@ -1,5 +1,4 @@
 import type { CompletionUsage } from "openai/resources";
-
 import type { IAgenticaTokenUsageJson } from "../../json/IAgenticaTokenUsageJson";
 import type { AgenticaTokenUsage } from "../AgenticaTokenUsage";
 

package/src/events/AgenticaCallEvent.ts

@@ -1,36 +1,33 @@
 import type { ILlmSchema } from "@samchon/openapi";
-
 import type { AgenticaOperation } from "../context/AgenticaOperation";
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import { AgenticaEventBase } from "./AgenticaEventBase";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 
-export class AgenticaCallEvent<
-  Model extends ILlmSchema.Model,
-> extends AgenticaEventBase<"call"> {
-  public readonly id: string;
-  public readonly operation: AgenticaOperation<Model>;
-  public arguments: Record<string, any>;
+/**
+ * Event of a function calling.
+ *
+ * @author Samchon
+ */
+export interface AgenticaCallEvent<Model extends ILlmSchema.Model>
+  extends AgenticaEventBase<"call"> {
+  /**
+   * ID of the tool calling.
+   */
+  id: string;
 
-  public constructor(props: AgenticaCallEvent.IProps<Model>) {
-    super("call");
-    this.id = props.id;
-    this.operation = props.operation;
-    this.arguments = props.arguments;
-  }
+  /**
+   * Target operation to call.
+   */
+  operation: AgenticaOperation<Model>;
 
-  public toJSON(): IAgenticaEventJson.ICall {
-    return {
-      type: "call",
-      id: this.id,
-      operation: this.operation.toJSON(),
-      arguments: this.arguments,
-    };
-  }
-}
-export namespace AgenticaCallEvent {
-  export interface IProps<Model extends ILlmSchema.Model> {
-    id: string;
-    operation: AgenticaOperation<Model>;
-    arguments: Record<string, any>;
-  }
+  /**
+   * 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,28 +1,11 @@
 import type { ILlmSchema } from "@samchon/openapi";
-
 import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import { AgenticaEventBase } from "./AgenticaEventBase";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 
-export class AgenticaCancelEvent<
+export interface AgenticaCancelEvent<
   Model extends ILlmSchema.Model,
 > extends AgenticaEventBase<"cancel"> {
-  public readonly selection: AgenticaOperationSelection<Model>;
-
-  public constructor(props: AgenticaCancelEvent.IProps<Model>) {
-    super("cancel");
-    this.selection = props.selection;
-  }
-
-  public toJSON(): IAgenticaEventJson.ICancel {
-    return {
-      type: "cancel",
-      selection: this.selection.toJSON(),
-    };
-  }
-}
-export namespace AgenticaCancelEvent {
-  export interface IProps<Model extends ILlmSchema.Model> {
-    selection: AgenticaOperationSelection<Model>;
-  }
+  selection: AgenticaOperationSelection<Model>;
+  toJSON: () => IAgenticaEventJson.ICancel;
 }

package/src/events/AgenticaDescribeEvent.ts

@@ -1,66 +1,17 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import type { AgenticaDescribePrompt } from "../prompts/AgenticaDescribePrompt";
 import type { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
-import { AgenticaDescribePrompt } from "../prompts/AgenticaDescribePrompt";
-import { AgenticaEventBase } from "./AgenticaEventBase";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 
-export class AgenticaDescribeEvent<
+export interface AgenticaDescribeEvent<
   Model extends ILlmSchema.Model,
 > extends AgenticaEventBase<"describe"> {
-  public readonly executes: AgenticaExecutePrompt<Model>[];
-  public readonly stream: ReadableStream<string>;
-  public get text(): string {
-    return this.get_();
-  }
+  executes: AgenticaExecutePrompt<Model>[];
+  stream: ReadableStream<string>;
 
-  /**
-   * Check if the join method can return a response immediately.
-   * Returns true if the response is ready to be returned by the join method.
-   */
-  public get done(): boolean {
-    return this.done_();
-  }
-
-  public constructor(props: AgenticaDescribeEvent.IProps<Model>) {
-    super("describe");
-    this.stream = props.stream;
-    this.executes = props.executes;
-    this.done_ = props.done;
-    this.get_ = props.get;
-    this.join_ = props.join;
-  }
-
-  public async join(): Promise<string> {
-    return this.join_();
-  }
-
-  public toJSON(): IAgenticaEventJson.IDescribe {
-    return {
-      type: "describe",
-      executes: this.executes.map(e => e.toJSON()),
-      text: this.text,
-      done: this.done,
-    };
-  }
-
-  public toPrompt(): AgenticaDescribePrompt<Model> {
-    return new AgenticaDescribePrompt({
-      executes: this.executes,
-      text: this.text,
-    });
-  }
-
-  private readonly done_: () => boolean;
-  private readonly get_: () => string;
-  private readonly join_: () => Promise<string>;
-}
-export namespace AgenticaDescribeEvent {
-  export interface IProps<Model extends ILlmSchema.Model> {
-    executes: AgenticaExecutePrompt<Model>[];
-    stream: ReadableStream<string>;
-    done: () => boolean;
-    get: () => string;
-    join: () => Promise<string>;
-  }
+  join: () => Promise<string>;
+  toJSON: () => IAgenticaEventJson.IDescribe;
+  toPrompt: () => AgenticaDescribePrompt<Model>;
 }

package/src/events/AgenticaEvent.ts

@@ -1,5 +1,4 @@
 import type { ILlmSchema } from "@samchon/openapi";
-
 import type { AgenticaCallEvent } from "./AgenticaCallEvent";
 import type { AgenticaCancelEvent } from "./AgenticaCancelEvent";
 import type { AgenticaDescribeEvent } from "./AgenticaDescribeEvent";
@@ -9,7 +8,18 @@ import type { AgenticaRequestEvent } from "./AgenticaRequestEvent";
 import type { AgenticaResponseEvent } from "./AgenticaResponseEvent";
 import type { AgenticaSelectEvent } from "./AgenticaSelectEvent";
 import type { AgenticaTextEvent } from "./AgenticaTextEvent";
+import type { AgenticaValidateEvent } from "./AgenticaValidateEvent";
 
+/**
+ * Agentica agent event.
+ *
+ * `AgenticaEvent` is an union type of all possible events that can
+ * be emitted by the AI chatbot of the {@link Agentica} class.
+ *
+ * You can discriminate the subtype by checking the {@link type} property.
+ *
+ * @author Samchon
+ */
 export type AgenticaEvent<Model extends ILlmSchema.Model> =
   | AgenticaCallEvent<Model>
   | AgenticaCancelEvent<Model>
@@ -19,7 +29,8 @@ export type AgenticaEvent<Model extends ILlmSchema.Model> =
   | AgenticaRequestEvent
   | AgenticaResponseEvent
   | AgenticaSelectEvent<Model>
-  | AgenticaTextEvent;
+  | AgenticaTextEvent
+  | AgenticaValidateEvent<Model>;
 export namespace AgenticaEvent {
   export type Type = AgenticaEvent<any>["type"];
   export interface Mapper<Model extends ILlmSchema.Model> {
@@ -32,5 +43,6 @@ export namespace AgenticaEvent {
     response: AgenticaResponseEvent;
     select: AgenticaSelectEvent<Model>;
     text: AgenticaTextEvent;
+    validate: AgenticaValidateEvent<Model>;
   }
 }

package/src/events/AgenticaEventBase.ts

@@ -1,7 +1,6 @@
-export abstract class AgenticaEventBase<Type extends string> {
-  public readonly type: Type;
-
-  public constructor(type: Type) {
-    this.type = type;
-  }
+export interface AgenticaEventBase<Type extends string> {
+  /**
+   * Discriminator type.
+   */
+  type: Type;
 }

package/src/events/AgenticaExecuteEvent.ts

@@ -1,50 +1,42 @@
-import type { ILlmSchema } from "@samchon/openapi";
-
+import type { IHttpResponse, ILlmSchema } from "@samchon/openapi";
 import type { AgenticaOperation } from "../context/AgenticaOperation";
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
-import { AgenticaEventBase } from "./AgenticaEventBase";
-
-export class AgenticaExecuteEvent<
-  Model extends ILlmSchema.Model,
-> extends AgenticaEventBase<"execute"> {
-  public readonly id: string;
-  public readonly operation: AgenticaOperation<Model>;
-  public readonly arguments: Record<string, unknown>;
-  public readonly value: unknown;
+import type { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 
-  public constructor(props: AgenticaExecuteEvent.IProps<Model>) {
-    super("execute");
-    this.id = props.id;
-    this.operation = props.operation;
-    this.arguments = props.arguments;
-    this.value = props.value;
-  }
+export type AgenticaExecuteEvent<Model extends ILlmSchema.Model> =
+  | AgenticaExecuteEvent.Class<Model>
+  | AgenticaExecuteEvent.Protocol<Model>;
+export namespace AgenticaExecuteEvent {
+  export interface Class<Model extends ILlmSchema.Model>
+    extends Base<
+      "class",
+      AgenticaOperation.Class<Model>,
+      AgenticaExecutePrompt.Class<Model>,
+      unknown
+    > {}
 
-  public toJSON(): IAgenticaEventJson.IExecute {
-    return {
-      type: "execute",
-      id: this.id,
-      operation: this.operation.toJSON(),
-      arguments: this.arguments,
-      value: this.value,
-    };
-  }
+  export interface Protocol<Model extends ILlmSchema.Model>
+    extends Base<
+      "http",
+      AgenticaOperation.Http<Model>,
+      AgenticaExecutePrompt.Http<Model>,
+      IHttpResponse
+    > {}
 
-  public toPrompt(): AgenticaExecutePrompt<Model> {
-    return new AgenticaExecutePrompt({
-      id: this.id,
-      operation: this.operation,
-      arguments: this.arguments,
-      value: this.value,
-    });
-  }
-}
-export namespace AgenticaExecuteEvent {
-  export interface IProps<Model extends ILlmSchema.Model> {
+  interface Base<
+    Protocol extends "http" | "class",
+    Operation extends AgenticaOperation<any>,
+    Prompt extends AgenticaExecutePrompt<any>,
+    Value,
+  > extends AgenticaEventBase<"execute"> {
+    protocol: Protocol;
     id: string;
-    operation: AgenticaOperation<Model>;
+    operation: Operation;
     arguments: Record<string, unknown>;
-    value: unknown;
+    value: Value;
+
+    toJSON: () => IAgenticaEventJson.IExecute;
+    toPrompt: () => Prompt;
   }
 }

package/src/events/AgenticaInitializeEvent.ts

@@ -1,14 +1,6 @@
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import { AgenticaEventBase } from "./AgenticaEventBase";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 
-export class AgenticaInitializeEvent extends AgenticaEventBase<"initialize"> {
-  public constructor() {
-    super("initialize");
-  }
-
-  public toJSON(): IAgenticaEventJson.IInitialize {
-    return {
-      type: "initialize",
-    };
-  }
+export interface AgenticaInitializeEvent extends AgenticaEventBase<"initialize"> {
+  toJSON: () => IAgenticaEventJson.IInitialize;
 }

package/src/events/AgenticaRequestEvent.ts

@@ -1,45 +1,10 @@
 import type OpenAI from "openai";
 
-import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 import type { AgenticaEventSource } from "./AgenticaEventSource";
-import { AgenticaEventBase } from "./AgenticaEventBase";
 
-export class AgenticaRequestEvent extends AgenticaEventBase<"request"> {
-  public readonly source: AgenticaEventSource;
-  public readonly body: OpenAI.ChatCompletionCreateParamsStreaming;
-  public readonly options?: OpenAI.RequestOptions | undefined;
-
-  public constructor(props: AgenticaRequestEvent.IProps) {
-    super("request");
-    this.source = props.source;
-    this.body = props.body;
-    this.options = props.options;
-  }
-
-  public toJSON(): IAgenticaEventJson.IRequest {
-    return {
-      type: "request",
-      source: this.source,
-      body: this.body,
-      options: this.options,
-    };
-  }
-}
-export namespace AgenticaRequestEvent {
-  export interface IProps {
-    /**
-     * The source agent of the request.
-     */
-    source: AgenticaEventSource;
-
-    /**
-     * Request body.
-     */
-    body: OpenAI.ChatCompletionCreateParamsStreaming;
-
-    /**
-     * Options for the request.
-     */
-    options?: OpenAI.RequestOptions | undefined;
-  }
+export interface AgenticaRequestEvent extends AgenticaEventBase<"request"> {
+  source: AgenticaEventSource;
+  body: OpenAI.ChatCompletionCreateParamsStreaming;
+  options?: OpenAI.RequestOptions | undefined;
 }

package/src/events/AgenticaResponseEvent.ts

@@ -1,48 +1,31 @@
 import type OpenAI from "openai";
 
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 import type { AgenticaEventSource } from "./AgenticaEventSource";
-import { AgenticaEventBase } from "./AgenticaEventBase";
 
-export class AgenticaResponseEvent extends AgenticaEventBase<"response"> {
-  public readonly source: AgenticaEventSource;
-  public readonly body: OpenAI.ChatCompletionCreateParamsStreaming;
-  public readonly stream: ReadableStream<OpenAI.ChatCompletionChunk>;
-  public readonly options?: OpenAI.RequestOptions | undefined;
-  public readonly join: () => Promise<OpenAI.ChatCompletion>;
+export interface AgenticaResponseEvent extends AgenticaEventBase<"response"> {
+  /**
+   * The source agent of the response.
+   */
+  source: AgenticaEventSource;
 
-  public constructor(props: AgenticaResponseEvent.IProps) {
-    super("response");
-    this.source = props.source;
-    this.body = props.body;
-    this.stream = props.stream;
-    this.options = props.options;
-    this.join = props.join;
-  }
-}
-export namespace AgenticaResponseEvent {
-  export interface IProps {
-    /**
-     * The source agent of the response.
-     */
-    source: AgenticaEventSource;
+  /**
+   * Request body.
+   */
+  body: OpenAI.ChatCompletionCreateParamsStreaming;
 
-    /**
-     * Request body.
-     */
-    body: OpenAI.ChatCompletionCreateParamsStreaming;
+  /**
+   * The text content stream.
+   */
+  stream: ReadableStream<OpenAI.ChatCompletionChunk>;
 
-    /**
-     * Options for the request.
-     */
-    options?: OpenAI.RequestOptions | undefined;
-    /**
-     * The text content stream.
-     */
-    stream: ReadableStream<OpenAI.ChatCompletionChunk>;
+  /**
+   * Options for the request.
+   */
+  options?: OpenAI.RequestOptions | undefined;
 
-    /**
-     * Get the description text.
-     */
-    join: () => Promise<OpenAI.ChatCompletion>;
-  }
+  /**
+   * Wait the completion.
+   */
+  join: () => Promise<OpenAI.ChatCompletion>;
 }