@agentica/core 0.13.5 → 0.14.0

package/src/events/AgenticaSelectEvent.ts

@@ -1,37 +1,13 @@
 import type { ILlmSchema } from "@samchon/openapi";
 import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
-
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import { v4 } from "uuid";
-import { AgenticaSelectPrompt } from "../prompts/AgenticaSelectPrompt";
-import { AgenticaEventBase } from "./AgenticaEventBase";
+import type { AgenticaSelectPrompt } from "../prompts/AgenticaSelectPrompt";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
 
-export class AgenticaSelectEvent<
+export interface AgenticaSelectEvent<
   Model extends ILlmSchema.Model,
 > extends AgenticaEventBase<"select"> {
-  public readonly selection: AgenticaOperationSelection<Model>;
-
-  public constructor(props: AgenticaSelectEvent.IProps<Model>) {
-    super("select");
-    this.selection = props.selection;
-  }
-
-  public toJSON(): IAgenticaEventJson.ISelect {
-    return {
-      type: "select",
-      selection: this.selection.toJSON(),
-    };
-  }
-
-  public toPrompt(): AgenticaSelectPrompt<Model> {
-    return new AgenticaSelectPrompt({
-      id: v4(),
-      selections: [this.selection],
-    });
-  }
-}
-export namespace AgenticaSelectEvent {
-  export interface IProps<Model extends ILlmSchema.Model> {
-    selection: AgenticaOperationSelection<Model>;
-  }
+  selection: AgenticaOperationSelection<Model>;
+  toJSON: () => IAgenticaEventJson.ISelect;
+  toPrompt: () => AgenticaSelectPrompt<Model>;
 }

package/src/events/AgenticaTextEvent.ts

@@ -1,62 +1,13 @@
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import { AgenticaTextPrompt } from "../prompts/AgenticaTextPrompt";
-import { AgenticaEventBase } from "./AgenticaEventBase";
-
-export class AgenticaTextEvent extends AgenticaEventBase<"text"> {
-  public readonly role: "assistant" | "user";
-  public readonly stream: ReadableStream<string>;
-  public get text(): string {
-    return this.get_();
-  }
-
-  /**
-   * 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: AgenticaTextEvent.IProps) {
-    super("text");
-    this.role = props.role;
-    this.stream = props.stream;
-
-    this.done_ = props.done;
-    this.get_ = props.get;
-    this.join_ = props.join;
-  }
-
-  public async join(): Promise<string> {
-    return this.join_();
-  }
-
-  public toJSON(): IAgenticaEventJson.IText {
-    return {
-      type: "text",
-      role: this.role,
-      text: this.text,
-      done: this.done,
-    };
-  }
-
-  public toPrompt(): AgenticaTextPrompt {
-    return new AgenticaTextPrompt({
-      role: this.role,
-      text: this.text,
-    });
-  }
-
-  private readonly done_: () => boolean;
-  private readonly get_: () => string;
-  private readonly join_: () => Promise<string>;
-}
-export namespace AgenticaTextEvent {
-  export interface IProps {
-    role: "assistant" | "user";
-    stream: ReadableStream<string>;
-    done: () => boolean;
-    get: () => string;
-    join: () => Promise<string>;
-  }
+import type { AgenticaTextPrompt } from "../prompts/AgenticaTextPrompt";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
+
+export interface AgenticaTextEvent<
+  Role extends "assistant" | "user" = "assistant" | "user",
+> extends AgenticaEventBase<"text"> {
+  role: Role;
+  stream: ReadableStream<string>;
+  join: () => Promise<string>;
+  toJSON: () => IAgenticaEventJson.IText;
+  toPrompt: () => AgenticaTextPrompt;
 }

package/src/events/AgenticaValidateEvent.ts

@@ -0,0 +1,31 @@
+import type { ILlmSchema } from "@samchon/openapi";
+import type { IValidation } from "typia";
+import type { AgenticaEventBase } from "./AgenticaEventBase";
+import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+
+/**
+ * Event of a validation feedback.
+ *
+ * @author Samchon
+ */
+export interface AgenticaValidateEvent<
+  Model extends ILlmSchema.Model,
+> extends AgenticaEventBase<"validate"> {
+  /**
+   * ID of the tool calling.
+   */
+  id: string;
+
+  /**
+   * Target operation to call.
+   */
+  operation: AgenticaOperation<Model>;
+
+  /**
+   * Validation result as a failure.
+   */
+  result: IValidation.IFailure;
+
+  toJSON: () => IAgenticaEventJson.IValidate;
+}

package/src/factory/events.ts

@@ -0,0 +1,229 @@
+import { v4 } from "uuid";
+
+import type { ILlmSchema, IValidation } from "@samchon/openapi";
+import type OpenAI from "openai";
+import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import type { AgenticaCallEvent } from "../events/AgenticaCallEvent";
+import type { AgenticaCancelEvent } from "../events/AgenticaCancelEvent";
+import type { AgenticaDescribeEvent } from "../events/AgenticaDescribeEvent";
+import type { AgenticaEventSource } from "../events/AgenticaEventSource";
+import type { AgenticaInitializeEvent } from "../events/AgenticaInitializeEvent";
+import type { AgenticaRequestEvent } from "../events/AgenticaRequestEvent";
+import type { AgenticaResponseEvent } from "../events/AgenticaResponseEvent";
+import type { AgenticaTextEvent } from "../events/AgenticaTextEvent";
+import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import type { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
+import type { AgenticaExecuteEvent } from "../events/AgenticaExecuteEvent";
+import type { AgenticaSelectEvent } from "../events/AgenticaSelectEvent";
+import type { AgenticaValidateEvent } from "../events/AgenticaValidateEvent";
+
+import { createExecutePrompt, createSelectPrompt } from "./prompts";
+
+/* -----------------------------------------------------------
+    FUNCTION SELECTS
+  ----------------------------------------------------------- */
+export function createInitializeEvent(): AgenticaInitializeEvent {
+  const event: IAgenticaEventJson.IInitialize = {
+    type: "initialize",
+  };
+  return {
+    type: event.type,
+    toJSON: () => event,
+  };
+}
+
+export function createSelectEvent<Model extends ILlmSchema.Model>(props: {
+  selection: AgenticaOperationSelection<Model>;
+}): AgenticaSelectEvent<Model> {
+  return {
+    type: "select",
+    selection: props.selection,
+    toJSON: () => ({
+      type: "select",
+      selection: props.selection.toJSON(),
+    }),
+    toPrompt: () => createSelectPrompt({
+      id: v4(),
+      selections: [props.selection],
+    }),
+  };
+}
+
+export function createCancelEvent<Model extends ILlmSchema.Model>(props: {
+  selection: AgenticaOperationSelection<Model>;
+}): AgenticaCancelEvent<Model> {
+  return {
+    type: "cancel",
+    selection: props.selection,
+    toJSON: () => ({
+      type: "cancel",
+      selection: props.selection.toJSON(),
+    }),
+  };
+}
+
+/* -----------------------------------------------------------
+    FUNCTION CALLS
+  ----------------------------------------------------------- */
+export function createCallEvent<Model extends ILlmSchema.Model>(props: {
+  id: string;
+  operation: AgenticaOperation<Model>;
+  arguments: Record<string, any>;
+}): AgenticaCallEvent<Model> {
+  return {
+    type: "call",
+    id: props.id,
+    operation: props.operation,
+    arguments: props.arguments,
+    toJSON: () => ({
+      type: "call",
+      id: props.id,
+      operation: props.operation.toJSON(),
+      arguments: props.arguments,
+    }),
+  };
+}
+
+export function createValidateEvent<Model extends ILlmSchema.Model>(props: {
+  id: string;
+  operation: AgenticaOperation<Model>;
+  result: IValidation.IFailure;
+}): AgenticaValidateEvent<Model> {
+  return {
+    type: "validate",
+    id: props.id,
+    operation: props.operation,
+    result: props.result,
+    toJSON: () => ({
+      type: "validate",
+      id: props.id,
+      operation: props.operation.toJSON(),
+      result: props.result,
+    }),
+  };
+}
+
+export function createExecuteEvent<Model extends ILlmSchema.Model>(props: {
+  id: string;
+  operation: AgenticaOperation<Model>;
+  arguments: Record<string, unknown>;
+  value: unknown;
+}): AgenticaExecuteEvent<Model> {
+  return {
+    type: "execute",
+    protocol: props.operation.protocol as "class",
+    id: props.id,
+    operation: props.operation as AgenticaOperation.Class<Model>,
+    arguments: props.arguments,
+    value: props.value as any,
+    toJSON: () => ({
+      type: "execute",
+      protocol: props.operation.protocol as "class",
+      id: props.id,
+      operation: props.operation.toJSON(),
+      arguments: props.arguments,
+      value: props.value,
+    }),
+    toPrompt: () =>
+      createExecutePrompt(props) as AgenticaExecutePrompt.Class<Model>,
+  };
+}
+
+/* -----------------------------------------------------------
+    TEXT STEAMING
+  ----------------------------------------------------------- */
+export function createTextEvent<Role extends "user" | "assistant">(props: {
+  role: Role;
+  stream: ReadableStream<string>;
+  done: () => boolean;
+  get: () => string;
+  join: () => Promise<string>;
+}): AgenticaTextEvent<Role> {
+  return {
+    type: "text",
+    role: props.role,
+    stream: props.stream,
+    join: props.join,
+    toJSON: () => ({
+      type: "text",
+      role: props.role,
+      done: props.done(),
+      text: props.get(),
+    }),
+    toPrompt: () => ({
+      type: "text",
+      role: props.role,
+      text: props.get(),
+      toJSON: () => ({
+        type: "text",
+        role: props.role,
+        text: props.get(),
+      }),
+    }),
+  };
+}
+
+export function createDescribeEvent<Model extends ILlmSchema.Model>(props: {
+  executes: AgenticaExecutePrompt<Model>[];
+  stream: ReadableStream<string>;
+  done: () => boolean;
+  get: () => string;
+  join: () => Promise<string>;
+}): AgenticaDescribeEvent<Model> {
+  return {
+    type: "describe",
+    executes: props.executes,
+    stream: props.stream,
+    join: props.join,
+    toJSON: () => ({
+      type: "describe",
+      executes: props.executes.map(execute => execute.toJSON()),
+      done: props.done(),
+      text: props.get(),
+    }),
+    toPrompt: () => ({
+      type: "describe",
+      executes: props.executes,
+      text: props.get(),
+      toJSON: () => ({
+        type: "describe",
+        executes: props.executes.map(execute => execute.toJSON()),
+        text: props.get(),
+      }),
+    }),
+  };
+}
+
+/* -----------------------------------------------------------
+    API REQUESTS
+  ----------------------------------------------------------- */
+export function createRequestEvent(props: {
+  source: AgenticaEventSource;
+  body: OpenAI.ChatCompletionCreateParamsStreaming;
+  options?: OpenAI.RequestOptions | undefined;
+}): AgenticaRequestEvent {
+  return {
+    type: "request",
+    source: props.source,
+    body: props.body,
+    options: props.options,
+  };
+}
+
+export function createResponseEvent(props: {
+  source: AgenticaEventSource;
+  body: OpenAI.ChatCompletionCreateParamsStreaming;
+  options?: OpenAI.RequestOptions | undefined;
+  stream: ReadableStream<OpenAI.ChatCompletionChunk>;
+  join: () => Promise<OpenAI.ChatCompletion>;
+}): AgenticaResponseEvent {
+  return {
+    type: "response",
+    source: props.source,
+    body: props.body,
+    options: props.options,
+    stream: props.stream,
+    join: props.join,
+  };
+}

package/src/factory/index.ts

@@ -0,0 +1,3 @@
+export * from "./events";
+export * from "./operations";
+export * from "./prompts";

package/src/factory/operations.ts

@@ -0,0 +1,17 @@
+import type { ILlmSchema } from "@samchon/openapi";
+import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+
+export function createOperationSelection<Model extends ILlmSchema.Model>(props: {
+  operation: AgenticaOperation<Model>;
+  reason: string;
+}): AgenticaOperationSelection<Model> {
+  return {
+    operation: props.operation,
+    reason: props.reason,
+    toJSON: () => ({
+      operation: props.operation.toJSON(),
+      reason: props.reason,
+    }),
+  };
+}

package/src/factory/prompts.ts

@@ -0,0 +1,104 @@
+import type { ILlmSchema } from "@samchon/openapi";
+import type { AgenticaTextPrompt } from "../prompts/AgenticaTextPrompt";
+import type { IAgenticaPromptJson } from "../json/IAgenticaPromptJson";
+import type { AgenticaDescribePrompt } from "../prompts/AgenticaDescribePrompt";
+import type { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
+import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import type { AgenticaSelectPrompt } from "../prompts/AgenticaSelectPrompt";
+import type { AgenticaCancelPrompt } from "../context/AgenticaCancelPrompt";
+import type { AgenticaOperation } from "../context/AgenticaOperation";
+
+/* -----------------------------------------------------------
+    TEXT PROMPTS
+  ----------------------------------------------------------- */
+export function createTextPrompt<Role extends "assistant" | "user" = "assistant" | "user">(props: {
+  role: Role;
+  text: string;
+}): AgenticaTextPrompt<Role> {
+  const prompt: IAgenticaPromptJson.IText<Role> = {
+    type: "text",
+    role: props.role,
+    text: props.text,
+  };
+  return {
+    ...prompt,
+    toJSON: () => prompt,
+  };
+}
+
+export function createDescribePrompt<Model extends ILlmSchema.Model>(props: {
+  executes: AgenticaExecutePrompt<Model>[];
+  text: string;
+}): AgenticaDescribePrompt<Model> {
+  return {
+    type: "describe",
+    text: props.text,
+    executes: props.executes,
+    toJSON: () => ({
+      type: "describe",
+      text: props.text,
+      executes: props.executes.map(execute => execute.toJSON()),
+    }),
+  };
+}
+
+/* -----------------------------------------------------------
+    FUNCTION CALLING PROMPTS
+  ----------------------------------------------------------- */
+export function createSelectPrompt<Model extends ILlmSchema.Model>(props: {
+  id: string;
+  selections: AgenticaOperationSelection<Model>[];
+}): AgenticaSelectPrompt<Model> {
+  return {
+    type: "select",
+    id: props.id,
+    selections: props.selections,
+    toJSON: () => ({
+      type: "select",
+      id: props.id,
+      selections: props.selections.map(selection => selection.toJSON()),
+    }),
+  };
+}
+
+export function createCancelPrompt<Model extends ILlmSchema.Model>(props: {
+  id: string;
+  selections: AgenticaOperationSelection<Model>[];
+}): AgenticaCancelPrompt<Model> {
+  return {
+    type: "cancel",
+    id: props.id,
+    selections: props.selections,
+    toJSON: () => ({
+      type: "cancel",
+      id: props.id,
+      selections: props.selections.map(selection => selection.toJSON()),
+    }),
+  };
+}
+
+export function createExecutePrompt<
+  Model extends ILlmSchema.Model,
+>(props: {
+  id: string;
+  operation: AgenticaOperation<Model>;
+  arguments: Record<string, any>;
+  value: unknown;
+}): AgenticaExecutePrompt<Model> {
+  return {
+    type: "execute",
+    protocol: props.operation.protocol as "class",
+    id: props.id,
+    operation: props.operation as AgenticaOperation.Class<Model>,
+    arguments: props.arguments,
+    value: props.value,
+    toJSON: () => ({
+      type: "execute",
+      protocol: props.operation.protocol,
+      id: props.id,
+      operation: props.operation.toJSON(),
+      arguments: props.arguments,
+      value: props.value,
+    }),
+  };
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 export * from "./Agentica";
-// CONTEXT
+
 export * from "./context/AgenticaContext";
 export * from "./context/AgenticaOperation";
 export * from "./context/AgenticaOperationCollection";
@@ -9,17 +9,15 @@ export * from "./context/AgenticaTokenUsage";
 export * from "./events/AgenticaCallEvent";
 export * from "./events/AgenticaCancelEvent";
 export * from "./events/AgenticaDescribeEvent";
-// EVENTS
 export * from "./events/AgenticaEvent";
 export * from "./events/AgenticaEventSource";
-
 export * from "./events/AgenticaExecuteEvent";
 export * from "./events/AgenticaRequestEvent";
 export * from "./events/AgenticaResponseEvent";
 export * from "./events/AgenticaSelectEvent";
 export * from "./events/AgenticaTextEvent";
+export * as factory from "./factory";
 
-// FACADE CLASS
 export * from "./functional/assertHttpLlmApplication";
 export * from "./functional/validateHttpLlmApplication";
 export * from "./json/IAgenticaEventJson";
@@ -28,17 +26,18 @@ export * from "./json/IAgenticaOperationSelectionJson";
 export * from "./json/IAgenticaPromptJson";
 
 export * from "./json/IAgenticaTokenUsageJson";
+export * as orchestrate from "./orchestrate";
 export * from "./prompts/AgenticaCancelPrompt";
 export * from "./prompts/AgenticaDescribePrompt";
 export * from "./prompts/AgenticaExecutePrompt";
 export * from "./prompts/AgenticaPrompt";
 export * from "./prompts/AgenticaSelectPrompt";
+
 export * from "./prompts/AgenticaTextPrompt";
-// STRUCTURES
 export * from "./structures/IAgenticaConfig";
 export * from "./structures/IAgenticaController";
 export * from "./structures/IAgenticaExecutor";
-
 export * from "./structures/IAgenticaProps";
 export * from "./structures/IAgenticaSystemPrompt";
+
 export * from "./structures/IAgenticaVendor";

package/src/json/IAgenticaEventJson.ts

@@ -1,5 +1,4 @@
 import type OpenAI from "openai";
-
 import type { AgenticaEventSource } from "../events/AgenticaEventSource";
 import type { IAgenticaOperationJson } from "./IAgenticaOperationJson";
 import type { IAgenticaOperationSelectionJson } from "./IAgenticaOperationSelectionJson";
@@ -22,7 +21,8 @@ export type IAgenticaEventJson =
   | IAgenticaEventJson.IInitialize
   | IAgenticaEventJson.IRequest
   | IAgenticaEventJson.ISelect
-  | IAgenticaEventJson.IText;
+  | IAgenticaEventJson.IText
+  | IAgenticaEventJson.IValidate;
 export namespace IAgenticaEventJson {
   export type Type = IAgenticaEventJson["type"];
   export interface Mapper {
@@ -79,6 +79,8 @@ export namespace IAgenticaEventJson {
     arguments: Record<string, any>;
   }
 
+  export interface IValidate extends IBase<"validate"> {}
+
   /**
    * Event of function calling execution.
    */
@@ -96,7 +98,7 @@ export namespace IAgenticaEventJson {
     /**
      * Arguments of the function calling.
      */
-    arguments: object;
+    arguments: Record<string, unknown>;
 
     /**
      * Return value.

package/src/json/IAgenticaPromptJson.ts

@@ -82,7 +82,7 @@ export namespace IAgenticaPromptJson {
     /**
      * Return value.
      */
-    value: any;
+    value: unknown;
   }
 
   /**