@agentica/core 0.10.3 → 0.11.0

package/src/events/AgenticaTextEvent.ts

@@ -0,0 +1,57 @@
+import { 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_();
+  }
+  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 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>;
+  }
+}

package/src/index.ts

@@ -1,18 +1,42 @@
-// TYPES
+// STRUCTURES
 export * from "./structures/IAgenticaConfig";
-export * from "./structures/IAgenticaContext";
 export * from "./structures/IAgenticaController";
-export * from "./structures/IAgenticaEvent";
 export * from "./structures/IAgenticaExecutor";
-export * from "./structures/IAgenticaOperation";
-export * from "./structures/IAgenticaOperationCollection";
-export * from "./structures/IAgenticaOperationSelection";
-export * from "./structures/IAgenticaPrompt";
 export * from "./structures/IAgenticaProps";
 export * from "./structures/IAgenticaVendor";
 export * from "./structures/IAgenticaSystemPrompt";
-export * from "./structures/IAgenticaTokenUsage";
-export * from "./typings/AgenticaSource";
+
+export * from "./json/IAgenticaEventJson";
+export * from "./json/IAgenticaOperationJson";
+export * from "./json/IAgenticaOperationSelectionJson";
+export * from "./json/IAgenticaPromptJson";
+export * from "./json/IAgenticaTokenUsageJson";
+
+// CONTEXT
+export * from "./context/AgenticaContext";
+export * from "./context/AgenticaOperation";
+export * from "./context/AgenticaOperationCollection";
+export * from "./context/AgenticaOperationSelection";
+export * from "./context/AgenticaTokenUsage";
+
+export * from "./prompts/AgenticaPrompt";
+export * from "./prompts/AgenticaCancelPrompt";
+export * from "./prompts/AgenticaDescribePrompt";
+export * from "./prompts/AgenticaExecutePrompt";
+export * from "./prompts/AgenticaSelectPrompt";
+export * from "./prompts/AgenticaTextPrompt";
+
+// EVENTS
+export * from "./events/AgenticaEvent";
+export * from "./events/AgenticaCallEvent";
+export * from "./events/AgenticaCancelEvent";
+export * from "./events/AgenticaDescribeEvent";
+export * from "./events/AgenticaEventSource";
+export * from "./events/AgenticaExecuteEvent";
+export * from "./events/AgenticaRequestEvent";
+export * from "./events/AgenticaResponseEvent";
+export * from "./events/AgenticaSelectEvent";
+export * from "./events/AgenticaTextEvent";
 
 // FACADE CLASS
 export * from "./functional/createHttpLlmApplication";

package/src/internal/AgenticaOperationComposer.ts

@@ -1,16 +1,16 @@
 import { ILlmSchema } from "@samchon/openapi";
 
+import { AgenticaOperation } from "../context/AgenticaOperation";
+import { AgenticaOperationCollection } from "../context/AgenticaOperationCollection";
 import { IAgenticaConfig } from "../structures/IAgenticaConfig";
 import { IAgenticaController } from "../structures/IAgenticaController";
-import { IAgenticaOperation } from "../structures/IAgenticaOperation";
-import { IAgenticaOperationCollection } from "../structures/IAgenticaOperationCollection";
 import { __map_take } from "./__map_take";
 
 export namespace AgenticaOperationComposer {
   export const compose = <Model extends ILlmSchema.Model>(props: {
     controllers: IAgenticaController<Model>[];
     config?: IAgenticaConfig<Model> | undefined;
-  }): IAgenticaOperationCollection<Model> => {
+  }): AgenticaOperationCollection<Model> => {
     const unique: boolean =
       props.controllers.length === 1 ||
       (() => {
@@ -24,7 +24,7 @@ export namespace AgenticaOperationComposer {
     const naming = (func: string, ci: number) =>
       unique ? func : `_${ci}_${func}`;
 
-    const array: IAgenticaOperation<Model>[] = props.controllers
+    const array: AgenticaOperation<Model>[] = props.controllers
       .map((controller, ci) =>
         controller.protocol === "http"
           ? controller.application.functions.map(
@@ -34,7 +34,13 @@ export namespace AgenticaOperationComposer {
                   controller: controller,
                   function: func,
                   name: naming(func.name, ci),
-                }) satisfies IAgenticaOperation.IHttp<Model>,
+                  toJSON: () => ({
+                    protocol: "http",
+                    controller: controller.name,
+                    function: func.name,
+                    name: naming(func.name, ci),
+                  }),
+                }) satisfies AgenticaOperation.Http<Model>,
             )
           : controller.application.functions.map(
               (func) =>
@@ -43,11 +49,17 @@ export namespace AgenticaOperationComposer {
                   controller,
                   function: func,
                   name: naming(func.name, ci),
-                }) satisfies IAgenticaOperation.IClass<Model>,
+                  toJSON: () => ({
+                    protocol: "class",
+                    controller: controller.name,
+                    function: func.name,
+                    name: naming(func.name, ci),
+                  }),
+                }) satisfies AgenticaOperation.Class<Model>,
             ),
       )
       .flat();
-    const divided: IAgenticaOperation<Model>[][] | undefined =
+    const divided: AgenticaOperation<Model>[][] | undefined =
       !!props.config?.capacity && array.length > props.config.capacity
         ? divideOperations({
             array,
@@ -55,11 +67,8 @@ export namespace AgenticaOperationComposer {
           })
         : undefined;
 
-    const flat: Map<string, IAgenticaOperation<Model>> = new Map();
-    const group: Map<
-      string,
-      Map<string, IAgenticaOperation<Model>>
-    > = new Map();
+    const flat: Map<string, AgenticaOperation<Model>> = new Map();
+    const group: Map<string, Map<string, AgenticaOperation<Model>>> = new Map();
     for (const item of array) {
       flat.set(item.name, item);
       __map_take(group, item.controller.name, () => new Map()).set(
@@ -76,12 +85,12 @@ export namespace AgenticaOperationComposer {
   };
 
   const divideOperations = <Model extends ILlmSchema.Model>(props: {
-    array: IAgenticaOperation<Model>[];
+    array: AgenticaOperation<Model>[];
     capacity: number;
-  }): IAgenticaOperation<Model>[][] => {
+  }): AgenticaOperation<Model>[][] => {
     const size: number = Math.ceil(props.array.length / props.capacity);
     const capacity: number = Math.ceil(props.array.length / size);
-    const replica: IAgenticaOperation<Model>[] = props.array.slice();
+    const replica: AgenticaOperation<Model>[] = props.array.slice();
     return new Array(size).fill(0).map(() => replica.splice(0, capacity));
   };
 }

package/src/internal/ByteArrayUtil.ts

@@ -0,0 +1,5 @@
+export namespace ByteArrayUtil {
+  export const toUtf8 = (byteArray: Uint8Array): string => {
+    return new TextDecoder().decode(byteArray);
+  };
+}

package/src/internal/MPSCUtil.ts

@@ -0,0 +1,75 @@
+export namespace MPSCUtil {
+  export interface Output<T> {
+    consumer: ReadableStream<T>;
+    produce: (chunk: T) => void;
+    close: () => void;
+    waitClose: () => Promise<void>;
+    done: () => boolean;
+  }
+
+  export const create = <T>(): Output<T> => {
+    const queue = new AsyncQueue<T>();
+    const consumer = new ReadableStream<T>({
+      async pull(controller) {
+        const { value, done } = await queue.dequeue();
+        if (done) {
+          controller.close();
+        } else {
+          controller.enqueue(value);
+        }
+      },
+    });
+    return {
+      consumer,
+      produce: (chunk: T) => queue.enqueue(chunk),
+      close: () => queue.close(),
+      done: () => queue.done(),
+      waitClose: () => queue.waitClose(),
+    };
+  };
+
+  export class AsyncQueue<T> {
+    private queue: T[] = [];
+    private resolvers: ((value: IteratorResult<T, undefined>) => void)[] = [];
+    private closeResolvers: (() => void)[] = [];
+
+    private closed = false;
+
+    enqueue(item: T) {
+      this.queue.push(item);
+      if (this.resolvers.length > 0) {
+        this.resolvers.shift()?.({ value: this.queue.shift()!, done: false });
+      }
+    }
+
+    async dequeue(): Promise<IteratorResult<T, undefined>> {
+      if (this.queue.length > 0) {
+        return { value: this.queue.shift()!, done: false };
+      }
+      if (this.closed) return { value: undefined, done: true };
+      return new Promise((resolve) => this.resolvers.push(resolve));
+    }
+
+    done() {
+      return this.closed;
+    }
+
+    close() {
+      this.closed = true;
+      while (this.resolvers.length > 0) {
+        this.resolvers.shift()?.({ value: undefined, done: true });
+      }
+      this.closeResolvers.forEach((resolve) => resolve());
+    }
+
+    waitClose() {
+      if (this.closed) {
+        return Promise.resolve();
+      }
+
+      return new Promise<void>((resolve) => {
+        this.closeResolvers.push(resolve);
+      });
+    }
+  }
+}

package/src/internal/StreamUtil.ts

@@ -0,0 +1,64 @@
+export namespace StreamUtil {
+  export const readAll = async <T>(stream: ReadableStream<T>): Promise<T[]> => {
+    const reader = stream.getReader();
+    const result: T[] = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      result.push(value);
+    }
+    return result;
+  };
+
+  export const reduce = async <T, R = T>(
+    stream: ReadableStream<T>,
+    reducer: (acc: T | R, cur: T) => R,
+    initial?: R,
+  ): Promise<R | null> => {
+    const reader = stream.getReader();
+
+    let acc = (initial ?? null) as R | null | T;
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (acc === null) {
+        acc = value;
+        continue;
+      }
+
+      acc = reducer(acc, value);
+    }
+
+    return acc as R;
+  };
+
+  export const to = <T>(value: T): ReadableStream<T> => {
+    const stream = new ReadableStream<T>({
+      start: (controller) => {
+        controller.enqueue(value);
+        controller.close();
+      },
+    });
+
+    return stream;
+  };
+
+  export const transform = <T, R>(
+    stream: ReadableStream<T>,
+    transformer: (value: T) => R,
+  ): ReadableStream<R> => {
+    const reader = stream.getReader();
+
+    return new ReadableStream<R>({
+      pull: async (controller) => {
+        const { done, value } = await reader.read();
+        if (!done) {
+          controller.enqueue(transformer(value));
+        } else {
+          controller.close();
+        }
+      },
+    });
+  };
+}

package/src/json/IAgenticaEventJson.ts

@@ -0,0 +1,178 @@
+import OpenAI from "openai";
+
+import { AgenticaEventSource } from "../events/AgenticaEventSource";
+import { IAgenticaOperationJson } from "./IAgenticaOperationJson";
+import { IAgenticaOperationSelectionJson } from "./IAgenticaOperationSelectionJson";
+import { IAgenticaPromptJson } from "./IAgenticaPromptJson";
+
+/**
+ * Nestia A.I. chatbot event.
+ *
+ * `IAgenticaEventJson` 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 IAgenticaEventJson =
+  | IAgenticaEventJson.ICall
+  | IAgenticaEventJson.ICancel
+  | IAgenticaEventJson.IDescribe
+  | IAgenticaEventJson.IExecute
+  | IAgenticaEventJson.IInitialize
+  | IAgenticaEventJson.IRequest
+  | IAgenticaEventJson.ISelect
+  | IAgenticaEventJson.IText;
+export namespace IAgenticaEventJson {
+  export type Type = IAgenticaEventJson["type"];
+  export type Mapper = {
+    initialize: IInitialize;
+    select: ISelect;
+    cancel: ICancel;
+    call: ICall;
+    execute: IExecute;
+    describe: IDescribe;
+    text: IText;
+    request: IRequest;
+  };
+
+  /**
+   * Event of initializing the chatbot.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface IInitialize extends IBase<"initialize"> {}
+
+  /**
+   * Event of selecting a function to call.
+   */
+  export interface ISelect extends IBase<"select"> {
+    selection: IAgenticaOperationSelectionJson;
+  }
+
+  /**
+   * Event of canceling a function calling.
+   */
+  export interface ICancel extends IBase<"cancel"> {
+    selection: IAgenticaOperationSelectionJson;
+  }
+
+  /**
+   * Event of calling a function.
+   */
+  export interface ICall extends IBase<"call"> {
+    /**
+     * ID of the tool calling.
+     */
+    id: string;
+
+    /**
+     * Target operation to call.
+     */
+    operation: IAgenticaOperationJson;
+
+    /**
+     * 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>;
+  }
+
+  /**
+   * Event of function calling execution.
+   */
+  export interface IExecute extends IBase<"execute"> {
+    /**
+     * ID of the tool calling.
+     */
+    id: string;
+
+    /**
+     * Target operation had called.
+     */
+    operation: IAgenticaOperationJson;
+
+    /**
+     * 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.
+     */
+    executes: IAgenticaPromptJson.IExecute[];
+
+    /**
+     * Description text.
+     */
+    text: string;
+
+    /**
+     * Whether the streaming is completed or not.
+     */
+    done: boolean;
+  }
+
+  /**
+   * Event of text message.
+   */
+  export interface IText extends IBase<"text"> {
+    /**
+     * Role of the orator.
+     */
+    role: "assistant" | "user";
+
+    /**
+     * Conversation text.
+     */
+    text: string;
+
+    /**
+     * Whether the streaming is completed or not.
+     */
+    done: boolean;
+  }
+
+  /**
+   * Request event of LLM vendor API.
+   */
+  export interface IRequest extends IBase<"request"> {
+    /**
+     * The source agent of the request.
+     */
+    source: AgenticaEventSource;
+
+    /**
+     * Request body.
+     */
+    body: OpenAI.ChatCompletionCreateParamsStreaming;
+
+    /**
+     * Options for the request.
+     */
+    options?: OpenAI.RequestOptions | undefined;
+  }
+
+  interface IBase<Type extends string> {
+    /**
+     * Discriminator type.
+     */
+    type: Type;
+  }
+}

package/src/json/IAgenticaOperationJson.ts

@@ -0,0 +1,36 @@
+/**
+ * Operation information in the Agentica 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 interface IAgenticaOperationJson {
+  /**
+   * Protocol discriminator.
+   */
+  protocol: "class" | "http";
+
+  /**
+   * Belonged controller of the target function.
+   */
+  controller: string;
+
+  /**
+   * Target function to call.
+   */
+  function: string;
+
+  /**
+   * Identifier name.
+   */
+  name: string;
+}

package/src/json/IAgenticaOperationSelectionJson.ts

@@ -0,0 +1,19 @@
+import { IAgenticaOperationJson } from "./IAgenticaOperationJson";
+
+/**
+ * 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 interface IAgenticaOperationSelectionJson {
+  reason: string;
+  operation: IAgenticaOperationJson;
+}