@agentica/core 0.12.21 → 0.13.1

package/src/index.ts

@@ -1,17 +1,4 @@
-// STRUCTURES
-export * from "./structures/IAgenticaConfig";
-export * from "./structures/IAgenticaController";
-export * from "./structures/IAgenticaExecutor";
-export * from "./structures/IAgenticaProps";
-export * from "./structures/IAgenticaVendor";
-export * from "./structures/IAgenticaSystemPrompt";
-
-export * from "./json/IAgenticaEventJson";
-export * from "./json/IAgenticaOperationJson";
-export * from "./json/IAgenticaOperationSelectionJson";
-export * from "./json/IAgenticaPromptJson";
-export * from "./json/IAgenticaTokenUsageJson";
-
+export * from "./Agentica";
 // CONTEXT
 export * from "./context/AgenticaContext";
 export * from "./context/AgenticaOperation";
@@ -19,19 +6,13 @@ 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";
+// EVENTS
+export * from "./events/AgenticaEvent";
 export * from "./events/AgenticaEventSource";
+
 export * from "./events/AgenticaExecuteEvent";
 export * from "./events/AgenticaRequestEvent";
 export * from "./events/AgenticaResponseEvent";
@@ -41,4 +22,23 @@ export * from "./events/AgenticaTextEvent";
 // FACADE CLASS
 export * from "./functional/assertHttpLlmApplication";
 export * from "./functional/validateHttpLlmApplication";
-export * from "./Agentica";
+export * from "./json/IAgenticaEventJson";
+export * from "./json/IAgenticaOperationJson";
+export * from "./json/IAgenticaOperationSelectionJson";
+export * from "./json/IAgenticaPromptJson";
+
+export * from "./json/IAgenticaTokenUsageJson";
+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/internal/AgenticaDefaultPrompt.ts

@@ -1,28 +1,34 @@
-import { ILlmSchema } from "@samchon/openapi";
+import type { ILlmSchema } from "@samchon/openapi";
 
-import { IAgenticaConfig } from "../structures/IAgenticaConfig";
+import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
 import { AgenticaSystemPrompt } from "./AgenticaSystemPrompt";
 import { Singleton } from "./Singleton";
 
-export namespace AgenticaDefaultPrompt {
-  export const write = <Model extends ILlmSchema.Model>(
-    config?: IAgenticaConfig<Model>,
-  ): string => {
-    if (config?.systemPrompt?.common)
-      return config?.systemPrompt?.common(config);
-
-    const locale: string = config?.locale ?? getLocale.get();
-    const timezone: string = config?.timezone ?? getTimezone.get();
-
-    return AgenticaSystemPrompt.COMMON.replace("${locale}", locale).replace(
-      "${timezone}",
-      timezone,
-    );
-  };
-}
+/**
+ * @TODO maybe this code will rewrite
+ */
+const isNode = new Singleton(() => {
+  const isObject = (obj: any) => typeof obj === "object" && obj !== null;
+  return (
+    // eslint-disable-next-line no-restricted-globals
+    typeof global === "object"
+    // eslint-disable-next-line no-restricted-globals
+    && isObject(global)
+    // eslint-disable-next-line node/prefer-global/process, no-restricted-globals
+    && isObject(global.process)
+    // eslint-disable-next-line node/prefer-global/process, no-restricted-globals
+    && isObject(global.process.versions)
+    // eslint-disable-next-line node/prefer-global/process, no-restricted-globals
+    && typeof global.process.versions.node !== "undefined"
+  );
+});
 
+/**
+ * @TODO maybe replace `process` property for lint pass
+ */
 const getLocale = new Singleton(() =>
   isNode.get()
+    // eslint-disable-next-line node/prefer-global/process
     ? (process.env.LANG?.split(".")[0] ?? "en-US")
     : navigator.language,
 );
@@ -31,13 +37,21 @@ const getTimezone = new Singleton(
   () => Intl.DateTimeFormat().resolvedOptions().timeZone,
 );
 
-const isNode = new Singleton(() => {
-  const isObject = (obj: any) => typeof obj === "object" && obj !== null;
-  return (
-    typeof global === "object" &&
-    isObject(global) &&
-    isObject(global.process) &&
-    isObject(global.process.versions) &&
-    typeof global.process.versions.node !== "undefined"
-  );
-});
+export function write<Model extends ILlmSchema.Model>(config?: IAgenticaConfig<Model>): string {
+  if (config?.systemPrompt?.common !== undefined) {
+    return config?.systemPrompt?.common(config);
+  }
+
+  const locale: string = config?.locale ?? getLocale.get();
+  const timezone: string = config?.timezone ?? getTimezone.get();
+
+  return AgenticaSystemPrompt.COMMON
+    // intended code
+    // eslint-disable-next-line no-template-curly-in-string
+    .replace("${locale}", locale)
+    // eslint-disable-next-line no-template-curly-in-string
+    .replace("${timezone}", timezone);
+}
+export const AgenticaDefaultPrompt = {
+  write,
+};

package/src/internal/AgenticaOperationComposer.ts

@@ -1,37 +1,36 @@
-import { ILlmSchema } from "@samchon/openapi";
+import type { 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 type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { AgenticaOperationCollection } from "../context/AgenticaOperationCollection";
+import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
+import type { IAgenticaController } from "../structures/IAgenticaController";
 import { __map_take } from "./__map_take";
 
-export namespace AgenticaOperationComposer {
-  export const compose = <Model extends ILlmSchema.Model>(props: {
-    controllers: IAgenticaController<Model>[];
-    config?: IAgenticaConfig<Model> | undefined;
-  }): AgenticaOperationCollection<Model> => {
-    const unique: boolean =
-      props.controllers.length === 1 ||
-      (() => {
-        const names: string[] = props.controllers
-          .map((controller) =>
-            controller.application.functions.map((func) => func.name),
-          )
-          .flat();
-        return new Set(names).size === names.length;
-      })();
-    const naming = (func: string, ci: number) =>
-      unique ? func : `_${ci}_${func}`;
+export function compose<Model extends ILlmSchema.Model>(props: {
+  controllers: IAgenticaController<Model>[];
+  config?: IAgenticaConfig<Model> | undefined;
+}): AgenticaOperationCollection<Model> {
+  const unique: boolean
+      = props.controllers.length === 1
+        || (() => {
+          const names: string[] = props.controllers
+            .map(controller =>
+              controller.application.functions.map(func => func.name),
+            )
+            .flat();
+          return new Set(names).size === names.length;
+        })();
+  const naming = (func: string, ci: number) =>
+    unique ? func : `_${ci}_${func}`;
 
-    const array: AgenticaOperation<Model>[] = props.controllers
-      .map((controller, ci) =>
-        controller.protocol === "http"
-          ? controller.application.functions.map(
-              (func) =>
+  const array: AgenticaOperation<Model>[] = props.controllers
+    .map((controller, ci) =>
+      controller.protocol === "http"
+        ? controller.application.functions.map(
+            func =>
                 ({
                   protocol: "http",
-                  controller: controller,
+                  controller,
                   function: func,
                   name: naming(func.name, ci),
                   toJSON: () => ({
@@ -41,9 +40,9 @@ export namespace AgenticaOperationComposer {
                     name: naming(func.name, ci),
                   }),
                 }) satisfies AgenticaOperation.Http<Model>,
-            )
-          : controller.application.functions.map(
-              (func) =>
+          )
+        : controller.application.functions.map(
+            func =>
                 ({
                   protocol: "class",
                   controller,
@@ -56,41 +55,44 @@ export namespace AgenticaOperationComposer {
                     name: naming(func.name, ci),
                   }),
                 }) satisfies AgenticaOperation.Class<Model>,
-            ),
-      )
-      .flat();
-    const divided: AgenticaOperation<Model>[][] | undefined =
-      !!props.config?.capacity && array.length > props.config.capacity
-        ? divideOperations({
+          ),
+    )
+    .flat();
+  const divided: AgenticaOperation<Model>[][] | undefined
+      = props.config?.capacity !== undefined && array.length > props.config.capacity
+        ? divide({
             array,
             capacity: props.config.capacity,
           })
         : undefined;
 
-    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(
-        item.name,
-        item,
-      );
-    }
-    return {
-      array,
-      divided,
-      flat,
-      group,
-    };
+  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(
+      item.name,
+      item,
+    );
+  }
+  return {
+    array,
+    divided,
+    flat,
+    group,
   };
+}
 
-  const divideOperations = <Model extends ILlmSchema.Model>(props: {
-    array: AgenticaOperation<Model>[];
-    capacity: number;
-  }): AgenticaOperation<Model>[][] => {
-    const size: number = Math.ceil(props.array.length / props.capacity);
-    const capacity: number = Math.ceil(props.array.length / size);
-    const replica: AgenticaOperation<Model>[] = props.array.slice();
-    return new Array(size).fill(0).map(() => replica.splice(0, capacity));
-  };
+function divide<T>(props: {
+  array: T[];
+  capacity: number;
+}): T[][] {
+  const size: number = Math.ceil(props.array.length / props.capacity);
+  const capacity: number = Math.ceil(props.array.length / size);
+  const replica: T[] = props.array.slice();
+  return Array.from({ length: size }, () => replica.splice(0, capacity));
 }
+
+export const AgenticaOperationComposer = {
+  compose,
+};

package/src/internal/AgenticaSystemPrompt.ts

@@ -1,14 +1,15 @@
-export namespace AgenticaSystemPrompt {
-  export const CANCEL =
-    "You are a helpful assistant for cancelling functions which are prepared to call.\n\nUse the supplied tools to select some functions to cancel of `getApiFunctions()` returned.\n\nIf you can't find any proper function to select, don't talk, don't do anything.";
-  export const COMMON =
-    "At first, the user's language locale code is \"${locale}\". When you are conversating with the user or describing the function calling result, consider it and always translate to the target locale language. Never conversate with different locale language text with the user.\n\nAt second, the user's timezone is \"${timezone}\", and ISO datetime is ${datetime}. When you are conversating with the user, consider current time and user belonged timezone.";
-  export const DESCRIBE =
-    "You are a helpful assistant describing return values of function calls.\n\nAbove messages are the list of function call histories. When describing the return values, please do not too much shortly summarize them. Instead, provide detailed descriptions as much as.\n\nAlso, its content format must be markdown. If required, utilize the mermaid syntax for drawing some diagrams. When image contents are, just put them through the markdown image syntax.\n\nAt last, if user's language locale code is different with your description, please translate it to the user's language.";
-  export const EXECUTE =
-    "You are a helpful assistant for tool calling.\n\nUse the supplied tools to assist the user.\n\nIf previous messages are not enough to compose the arguments, you can ask the user to write more information. By the way, when asking the user to write more information, make the text concise and clear.\n\nFor reference, in the \"tool\" role message content, the `function` property means metadata of the API operation. In other words, it is the function schema describing its purpose, parameters and return value types. And then the `data` property is the return value from the target function calling.";
-  export const INITIALIZE =
-    "You are a helpful assistant.\n\nUse the supplied tools to assist the user.";
-  export const SELECT =
-    "You are a helpful assistant for selecting functions to call.\n\nUse the supplied tools to select some functions of `getApiFunctions()` returned.\n\nWhen selecting functions to call, pay attention to the relationship between functions. In particular, check the prerequisites between each function.\n\nIf you can't find any proper function to select, just type your own message. By the way, when typing your own message, please consider the user's language locale code. If your message is different with the user's language, please translate it to the user's.";
-}
+/* eslint-disable no-template-curly-in-string */
+export const AgenticaSystemPrompt = {
+  CANCEL:
+    "You are a helpful assistant for cancelling functions which are prepared to call.\n\nUse the supplied tools to select some functions to cancel of `getApiFunctions()` returned.\n\nIf you can't find any proper function to select, don't talk, don't do anything.",
+  COMMON:
+    "At first, the user's language locale code is \"${locale}\". When you are conversating with the user or describing the function calling result, consider it and always translate to the target locale language. Never conversate with different locale language text with the user.\n\nAt second, the user's timezone is \"${timezone}\", and ISO datetime is ${datetime}. When you are conversating with the user, consider current time and user belonged timezone.",
+  DESCRIBE:
+    "You are a helpful assistant describing return values of function calls.\n\nAbove messages are the list of function call histories. When describing the return values, please do not too much shortly summarize them. Instead, provide detailed descriptions as much as.\n\nAlso, its content format must be markdown. If required, utilize the mermaid syntax for drawing some diagrams. When image contents are, just put them through the markdown image syntax.\n\nAt last, if user's language locale code is different with your description, please translate it to the user's language.",
+  EXECUTE:
+    "You are a helpful assistant for tool calling.\n\nUse the supplied tools to assist the user.\n\nIf previous messages are not enough to compose the arguments, you can ask the user to write more information. By the way, when asking the user to write more information, make the text concise and clear.\n\nFor reference, in the \"tool\" role message content, the `function` property means metadata of the API operation. In other words, it is the function schema describing its purpose, parameters and return value types. And then the `data` property is the return value from the target function calling.",
+  INITIALIZE:
+    "You are a helpful assistant.\n\nUse the supplied tools to assist the user.",
+  SELECT:
+    "You are a helpful assistant for selecting functions to call.\n\nUse the supplied tools to select some functions of `getApiFunctions()` returned.\n\nWhen selecting functions to call, pay attention to the relationship between functions. In particular, check the prerequisites between each function.\n\nIf you can't find any proper function to select, just type your own message. By the way, when typing your own message, please consider the user's language locale code. If your message is different with the user's language, please translate it to the user's.",
+};

package/src/internal/AsyncQueue.ts

@@ -0,0 +1,67 @@
+export class AsyncQueue<T> {
+  private queue: T[] = [];
+  private resolvers: ((value: IteratorResult<T, undefined>) => void)[] = [];
+  private closeResolvers: (() => void)[] = [];
+  private emptyResolvers: (() => 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) {
+      if (this.emptyResolvers.length > 0) {
+        this.emptyResolvers.forEach(resolve => resolve());
+        this.emptyResolvers = [];
+      }
+      return { value: undefined, done: true };
+    }
+    return new Promise(resolve => this.resolvers.push(resolve));
+  }
+
+  isEmpty() {
+    return this.queue.length === 0;
+  }
+
+  isClosed() {
+    return this.closed;
+  }
+
+  done() {
+    return this.isClosed() && this.isEmpty();
+  }
+
+  close() {
+    this.closed = true;
+    while (this.resolvers.length > 0) {
+      this.resolvers.shift()?.({ value: undefined, done: true });
+    }
+    this.closeResolvers.forEach(resolve => resolve());
+  }
+
+  async waitUntilEmpty() {
+    if (this.isEmpty()) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this.emptyResolvers.push(resolve);
+    });
+  }
+
+  async waitClosed() {
+    if (this.isClosed()) {
+      return Promise.resolve();
+    }
+
+    return new Promise<void>((resolve) => {
+      this.closeResolvers.push(resolve);
+    });
+  }
+}

package/src/internal/ByteArrayUtil.ts

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

package/src/internal/MPSC.ts

@@ -0,0 +1,40 @@
+import { AsyncQueue } from "./AsyncQueue";
+
+export class MPSC<T> {
+  private readonly queue: AsyncQueue<T>;
+  public readonly consumer: ReadableStream<T>;
+
+  public constructor() {
+    this.queue = new AsyncQueue<T>();
+    this.consumer = new ReadableStream<T>({
+      pull: async (controller) => {
+        const { value, done } = await this.queue.dequeue();
+        if (done === true) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(value);
+      },
+    });
+  }
+
+  produce(chunk: T) {
+    this.queue.enqueue(chunk);
+  }
+
+  close() {
+    this.queue.close();
+  }
+
+  done() {
+    return this.queue.done();
+  }
+
+  async waitClosed() {
+    await this.queue.waitClosed();
+  }
+
+  async waitUntilEmpty() {
+    await this.queue.waitUntilEmpty();
+  }
+}

package/src/internal/Singleton.ts

@@ -1,3 +1,8 @@
+/**
+ * @internal
+ */
+const NOT_MOUNTED_YET = {};
+
 /**
  * @internal
  */
@@ -11,12 +16,9 @@ export class Singleton<T, Args extends any[] = []> {
   }
 
   public get(...args: Args): T {
-    if (this.value_ === NOT_MOUNTED_YET) this.value_ = this.closure_(...args);
+    if (this.value_ === NOT_MOUNTED_YET) {
+      this.value_ = this.closure_(...args);
+    }
     return this.value_ as T;
   }
 }
-
-/**
- * @internal
- */
-const NOT_MOUNTED_YET = {};

package/src/internal/StreamUtil.ts

@@ -1,64 +1,73 @@
-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;
-  };
+/**
+ * @module StreamUtil
+ *
+ * Utility functions for streams.
+ */
 
-  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();
+async function readAll<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;
+}
 
-    let acc = (initial ?? null) as R | null | T;
+async function reduce<T, R = T>(stream: ReadableStream<T>, reducer: (acc: T | R, cur: T) => R, initial?: R): Promise<R | null> {
+  const reader = stream.getReader();
 
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (acc === null) {
-        acc = value;
-        continue;
-      }
+  let acc = (initial ?? null) as R | null | T;
 
-      acc = reducer(acc, value);
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    if (acc === null) {
+      acc = value;
+      continue;
     }
 
-    return acc as R;
-  };
+    acc = reducer(acc, value);
+  }
 
-  export const to = <T>(value: T): ReadableStream<T> => {
-    const stream = new ReadableStream<T>({
-      start: (controller) => {
-        controller.enqueue(value);
-        controller.close();
-      },
-    });
+  return acc as R;
+}
+
+function to<T>(value: T): ReadableStream<T> {
+  const stream = new ReadableStream<T>({
+    start: (controller) => {
+      controller.enqueue(value);
+      controller.close();
+    },
+  });
 
-    return stream;
-  };
+  return stream;
+}
 
-  export const transform = <T, R>(
-    stream: ReadableStream<T>,
-    transformer: (value: T) => R,
-  ): ReadableStream<R> => {
-    const reader = stream.getReader();
+function 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();
-        }
-      },
-    });
-  };
+  return new ReadableStream<R>({
+    pull: async (controller) => {
+      const { done, value } = await reader.read();
+      if (!done) {
+        controller.enqueue(transformer(value));
+      }
+      else {
+        controller.close();
+      }
+    },
+  });
 }
+
+export const StreamUtil = {
+  readAll,
+  reduce,
+  to,
+  transform,
+};

package/src/internal/__map_take.ts

@@ -1,15 +1,13 @@
 /**
  * @internal
  */
-export const __map_take = <Key, T>(
-  dict: Map<Key, T>,
-  key: Key,
-  generator: () => T,
-): T => {
+export function __map_take<Key, T>(dict: Map<Key, T>, key: Key, generator: () => T): T {
   const oldbie: T | undefined = dict.get(key);
-  if (oldbie) return oldbie;
+  if (oldbie !== undefined) {
+    return oldbie;
+  }
 
   const value: T = generator();
   dict.set(key, value);
   return value;
-};
+}