@agentica/core 0.27.3 → 0.29.0

package/src/Agentica.ts

@@ -1,11 +1,17 @@
 import type { ILlmSchema } from "@samchon/openapi";
+import type OpenAI from "openai";
+
+import { Semaphore } from "tstl";
+import { v4 } from "uuid";
 
 import type { AgenticaContext } from "./context/AgenticaContext";
 import type { AgenticaOperation } from "./context/AgenticaOperation";
 import type { AgenticaOperationCollection } from "./context/AgenticaOperationCollection";
 import type { AgenticaOperationSelection } from "./context/AgenticaOperationSelection";
+import type { AgenticaEventSource } from "./events";
 import type { AgenticaEvent } from "./events/AgenticaEvent";
 import type { AgenticaRequestEvent } from "./events/AgenticaRequestEvent";
+import type { AgenticaUserMessageEvent } from "./events/AgenticaUserMessageEvent";
 import type { AgenticaUserMessageContent } from "./histories";
 import type { AgenticaHistory } from "./histories/AgenticaHistory";
 import type { AgenticaUserMessageHistory } from "./histories/AgenticaUserMessageHistory";
@@ -17,7 +23,6 @@ import type { IAgenticaVendor } from "./structures/IAgenticaVendor";
 import { AgenticaTokenUsage } from "./context/AgenticaTokenUsage";
 import { AgenticaOperationComposer } from "./context/internal/AgenticaOperationComposer";
 import { AgenticaTokenUsageAggregator } from "./context/internal/AgenticaTokenUsageAggregator";
-import { createUserMessageHistory } from "./factory";
 import { createInitializeEvent, createRequestEvent, createUserMessageEvent } from "./factory/events";
 import { execute } from "./orchestrate/execute";
 import { transformHistory } from "./transformers/transformHistory";
@@ -62,11 +67,10 @@ export class Agentica<Model extends ILlmSchema.Model> {
   private readonly listeners_: Map<string, Set<(event: AgenticaEvent<Model>) => Promise<void> | void>>;
 
   // STATUS
+  private readonly executor_: (ctx: AgenticaContext<Model>) => Promise<void>;
+  private readonly semaphore_: Semaphore | null;
   private readonly token_usage_: AgenticaTokenUsage;
   private ready_: boolean;
-  private readonly executor_: (
-    ctx: AgenticaContext<Model>,
-  ) => Promise<AgenticaHistory<Model>[]>;
 
   /* -----------------------------------------------------------
     CONSTRUCTOR
@@ -83,7 +87,7 @@ export class Agentica<Model extends ILlmSchema.Model> {
       config: props.config,
     });
 
-    // STATUS
+    // STACK
     this.stack_ = [];
     this.listeners_ = new Map();
     this.histories_ = (props.histories ?? []).map(input =>
@@ -94,16 +98,21 @@ export class Agentica<Model extends ILlmSchema.Model> {
     );
 
     // STATUS
+    this.executor_
+      = typeof props.config?.executor === "function"
+        ? props.config.executor
+        : execute(props.config?.executor ?? null);
+    this.semaphore_ = props.vendor.semaphore != null
+      ? typeof props.vendor.semaphore === "object"
+        ? props.vendor.semaphore
+        : new Semaphore(props.vendor.semaphore)
+      : null;
     this.token_usage_ = this.props.tokenUsage !== undefined
       ? this.props.tokenUsage instanceof AgenticaTokenUsage
         ? this.props.tokenUsage
         : new AgenticaTokenUsage(this.props.tokenUsage)
       : AgenticaTokenUsage.zero();
     this.ready_ = false;
-    this.executor_
-      = typeof props.config?.executor === "function"
-        ? props.config.executor
-        : execute(props.config?.executor ?? null);
   }
 
   /**
@@ -140,7 +149,23 @@ export class Agentica<Model extends ILlmSchema.Model> {
       abortSignal?: AbortSignal;
     } = {},
   ): Promise<AgenticaHistory<Model>[]> {
-    const prompt: AgenticaUserMessageHistory = createUserMessageHistory({
+    const historyGetters: Array<() => Promise<AgenticaHistory<Model>>> = [];
+    const dispatch = (event: AgenticaEvent<Model>): void => {
+      this.dispatch(event).catch(() => {});
+      if ("toHistory" in event) {
+        if ("join" in event) {
+          historyGetters.push(async () => {
+            await event.join();
+            return event.toHistory();
+          });
+        }
+        else {
+          historyGetters.push(async () => event.toHistory());
+        }
+      }
+    };
+
+    const prompt: AgenticaUserMessageEvent = createUserMessageEvent({
       contents: Array.isArray(content)
         ? content
         : typeof content === "string"
@@ -150,22 +175,22 @@ export class Agentica<Model extends ILlmSchema.Model> {
             }]
           : [content],
     });
+    dispatch(prompt);
 
-    this.dispatch(
-      createUserMessageEvent({
-        contents: prompt.contents,
-      }),
-    ).catch(() => {});
-
-    const newbie: AgenticaHistory<Model>[] = await this.executor_(
+    await this.executor_(
       this.getContext({
-        prompt,
+        dispatch,
+        prompt: prompt.toHistory(),
         abortSignal: options.abortSignal,
         usage: this.token_usage_,
       }),
     );
-    this.histories_.push(prompt, ...newbie);
-    return [prompt, ...newbie];
+
+    const completed: AgenticaHistory<Model>[] = await Promise.all(
+      historyGetters.map(async h => h()),
+    );
+    this.histories_.push(...completed);
+    return completed;
   }
 
   /**
@@ -233,9 +258,78 @@ export class Agentica<Model extends ILlmSchema.Model> {
   public getContext(props: {
     prompt: AgenticaUserMessageHistory;
     usage: AgenticaTokenUsage;
+    dispatch: (event: AgenticaEvent<Model>) => void;
     abortSignal?: AbortSignal;
   }): AgenticaContext<Model> {
-    const dispatch = async (event: AgenticaEvent<Model>) => this.dispatch(event);
+    const request = async (
+      source: AgenticaEventSource,
+      body: Omit<OpenAI.ChatCompletionCreateParamsStreaming, "model" | "stream">,
+    ): Promise<ReadableStream<OpenAI.Chat.Completions.ChatCompletionChunk>> => {
+      const event: AgenticaRequestEvent = createRequestEvent({
+        source,
+        body: {
+          ...body,
+          model: this.props.vendor.model,
+          stream: true,
+          stream_options: {
+            include_usage: true,
+          },
+        },
+        options: {
+          ...this.props.vendor.options,
+          signal: props.abortSignal,
+        },
+      });
+      props.dispatch(event);
+
+      // completion
+      const completion = await this.props.vendor.api.chat.completions.create(
+        event.body,
+        event.options,
+      );
+
+      const [streamForEvent, temporaryStream] = StreamUtil.transform(
+        completion.toReadableStream() as ReadableStream<Uint8Array>,
+        value =>
+          ChatGptCompletionMessageUtil.transformCompletionChunk(value),
+      ).tee();
+
+      const [streamForAggregate, streamForReturn] = temporaryStream.tee();
+
+      (async () => {
+        const reader = streamForAggregate.getReader();
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) {
+            break;
+          }
+          if (chunk.value.usage != null) {
+            AgenticaTokenUsageAggregator.aggregate({
+              kind: source,
+              completionUsage: chunk.value.usage,
+              usage: props.usage,
+            });
+          }
+        }
+      })().catch(() => {});
+
+      const [streamForStream, streamForJoin] = streamForEvent.tee();
+      props.dispatch({
+        id: v4(),
+        type: "response",
+        source,
+        stream: streamDefaultReaderToAsyncGenerator(streamForStream.getReader()),
+        body: event.body,
+        options: event.options,
+        join: async () => {
+          const chunks = await StreamUtil.readAll(streamForJoin);
+          return ChatGptCompletionMessageUtil.merge(chunks);
+        },
+        created_at: new Date().toISOString(),
+      });
+      return streamForReturn;
+    };
+
     return {
       // APPLICATION
       operations: this.operations_,
@@ -249,75 +343,21 @@ export class Agentica<Model extends ILlmSchema.Model> {
       abortSignal: props.abortSignal,
 
       // HANDLERS
-      dispatch: async event => this.dispatch(event),
-      request: async (source, body) => {
-        // request information
-        const event: AgenticaRequestEvent = createRequestEvent({
-          source,
-          body: {
-            ...body,
-            model: this.props.vendor.model,
-            stream: true,
-            stream_options: {
-              include_usage: true,
-            },
-          },
-          options: {
-            ...this.props.vendor.options,
-            signal: props.abortSignal,
-          },
-        });
-        await dispatch(event);
-
-        // completion
-        const completion = await this.props.vendor.api.chat.completions.create(
-          event.body,
-          event.options,
-        );
-
-        const [streamForEvent, temporaryStream] = StreamUtil.transform(
-          completion.toReadableStream() as ReadableStream<Uint8Array>,
-          value =>
-            ChatGptCompletionMessageUtil.transformCompletionChunk(value),
-        ).tee();
-
-        const [streamForAggregate, streamForReturn] = temporaryStream.tee();
-
-        (async () => {
-          const reader = streamForAggregate.getReader();
-          while (true) {
-            const chunk = await reader.read();
-            if (chunk.done) {
-              break;
-            }
-            if (chunk.value.usage != null) {
-              AgenticaTokenUsageAggregator.aggregate({
-                kind: source,
-                completionUsage: chunk.value.usage,
-                usage: props.usage,
-              });
-            }
+      dispatch: props.dispatch,
+      request: this.semaphore_ === null
+        ? request
+        : async (source, body) => {
+          await this.semaphore_!.acquire();
+          try {
+            return await request(source, body);
           }
-        })().catch(() => {});
-
-        const [streamForStream, streamForJoin] = streamForEvent.tee();
-        await dispatch({
-          type: "response",
-          source,
-          stream: streamDefaultReaderToAsyncGenerator(streamForStream.getReader()),
-          body: event.body,
-          options: event.options,
-          join: async () => {
-            const chunks = await StreamUtil.readAll(streamForJoin);
-            return ChatGptCompletionMessageUtil.merge(chunks);
-          },
-        });
-
-        return streamForReturn;
-      },
+          finally {
+            void this.semaphore_!.release().catch(() => {});
+          }
+        },
       initialize: async () => {
         this.ready_ = true;
-        await dispatch(createInitializeEvent());
+        props.dispatch(createInitializeEvent());
       },
     };
   }

package/src/MicroAgentica.ts

@@ -1,13 +1,17 @@
 import type { ILlmSchema } from "@samchon/openapi";
+import type OpenAI from "openai";
+
+import { Semaphore } from "tstl";
+import { v4 } from "uuid";
 
 import type { AgenticaOperation } from "./context/AgenticaOperation";
 import type { AgenticaOperationCollection } from "./context/AgenticaOperationCollection";
 import type { MicroAgenticaContext } from "./context/MicroAgenticaContext";
+import type { AgenticaUserMessageEvent } from "./events";
 import type { AgenticaRequestEvent } from "./events/AgenticaRequestEvent";
 import type { MicroAgenticaEvent } from "./events/MicroAgenticaEvent";
 import type { AgenticaUserMessageContent } from "./histories";
 import type { AgenticaExecuteHistory } from "./histories/AgenticaExecuteHistory";
-import type { AgenticaUserMessageHistory } from "./histories/AgenticaUserMessageHistory";
 import type { MicroAgenticaHistory } from "./histories/MicroAgenticaHistory";
 import type { IAgenticaController } from "./structures/IAgenticaController";
 import type { IAgenticaVendor } from "./structures/IAgenticaVendor";
@@ -17,7 +21,6 @@ import type { IMicroAgenticaProps } from "./structures/IMicroAgenticaProps";
 import { AgenticaTokenUsage } from "./context/AgenticaTokenUsage";
 import { AgenticaOperationComposer } from "./context/internal/AgenticaOperationComposer";
 import { AgenticaTokenUsageAggregator } from "./context/internal/AgenticaTokenUsageAggregator";
-import { createUserMessageHistory } from "./factory";
 import { createRequestEvent, createUserMessageEvent } from "./factory/events";
 import { call, describe } from "./orchestrate";
 import { transformHistory } from "./transformers/transformHistory";
@@ -64,6 +67,8 @@ export class MicroAgentica<Model extends ILlmSchema.Model> {
     Set<(event: MicroAgenticaEvent<Model>) => Promise<void>>
   >;
 
+  private readonly semaphore_: Semaphore | null;
+
   /* -----------------------------------------------------------
     CONSTRUCTOR
   ----------------------------------------------------------- */
@@ -89,6 +94,11 @@ export class MicroAgentica<Model extends ILlmSchema.Model> {
         : new AgenticaTokenUsage(this.props.tokenUsage)
       : AgenticaTokenUsage.zero();
     this.listeners_ = new Map();
+    this.semaphore_ = props.vendor.semaphore != null
+      ? typeof props.vendor.semaphore === "object"
+        ? props.vendor.semaphore
+        : new Semaphore(props.vendor.semaphore)
+      : null;
   }
 
   /**
@@ -119,7 +129,23 @@ export class MicroAgentica<Model extends ILlmSchema.Model> {
   public async conversate(
     content: string | AgenticaUserMessageContent | Array<AgenticaUserMessageContent>,
   ): Promise<MicroAgenticaHistory<Model>[]> {
-    const talk = createUserMessageHistory({
+    const histories: Array<() => Promise<MicroAgenticaHistory<Model>>> = [];
+    const dispatch = (event: MicroAgenticaEvent<Model>): void => {
+      this.dispatch(event).catch(() => {});
+      if ("toHistory" in event) {
+        if ("join" in event) {
+          histories.push(async () => {
+            await event.join();
+            return event.toHistory();
+          });
+        }
+        else {
+          histories.push(async () => event.toHistory());
+        }
+      }
+    };
+
+    const prompt: AgenticaUserMessageEvent = createUserMessageEvent({
       contents: Array.isArray(content)
         ? content
         : typeof content === "string"
@@ -129,29 +155,26 @@ export class MicroAgentica<Model extends ILlmSchema.Model> {
             }]
           : [content],
     });
-    this.dispatch(
-      createUserMessageEvent({
-        contents: talk.contents,
-      }),
-    ).catch(() => {});
+    dispatch(prompt);
 
     const ctx: MicroAgenticaContext<Model> = this.getContext({
-      prompt: talk,
+      prompt,
+      dispatch,
       usage: this.token_usage_,
     });
-    const histories: MicroAgenticaHistory<Model>[] = await call(
+    const executes: AgenticaExecuteHistory<Model>[] = await call(
       ctx,
       this.operations_.array,
-    ) as MicroAgenticaHistory<Model>[];
-    const executes: AgenticaExecuteHistory<Model>[] = histories.filter(p => p.type === "execute");
-    if (executes.length
-      && ctx.config?.executor?.describe !== null
-      && ctx.config?.executor?.describe !== false) {
-      histories.push(...await describe(ctx, executes));
+    );
+    if (executes.length) {
+      await describe(ctx, executes);
     }
 
-    this.histories_.push(talk, ...histories);
-    return histories;
+    const completed: MicroAgenticaHistory<Model>[] = await Promise.all(
+      histories.map(async h => h()),
+    );
+    this.histories_.push(...completed);
+    return completed;
   }
 
   /**
@@ -217,79 +240,93 @@ export class MicroAgentica<Model extends ILlmSchema.Model> {
    * @internal
    */
   public getContext(props: {
-    prompt: AgenticaUserMessageHistory;
+    prompt: AgenticaUserMessageEvent;
     usage: AgenticaTokenUsage;
+    dispatch: (event: MicroAgenticaEvent<Model>) => void;
   }): MicroAgenticaContext<Model> {
-    const dispatch = this.dispatch.bind(this);
-    return {
-      operations: this.operations_,
-      config: this.props.config,
-
-      histories: this.histories_,
-      prompt: props.prompt,
-      dispatch,
-      request: async (source, body) => {
-        // request information
-        const event: AgenticaRequestEvent = createRequestEvent({
-          source,
-          body: {
-            ...body,
-            model: this.props.vendor.model,
-            stream: true,
-            stream_options: {
-              include_usage: true,
-            },
+    const request = async (
+      source: MicroAgenticaEvent.Source,
+      body: Omit<OpenAI.ChatCompletionCreateParamsStreaming, "model" | "stream">,
+    ): Promise<ReadableStream<OpenAI.Chat.Completions.ChatCompletionChunk>> => {
+      const event: AgenticaRequestEvent = createRequestEvent({
+        source,
+        body: {
+          ...body,
+          model: this.props.vendor.model,
+          stream: true,
+          stream_options: {
+            include_usage: true,
           },
-          options: this.props.vendor.options,
-        });
-        await dispatch(event);
+        },
+        options: this.props.vendor.options,
+      });
+      props.dispatch(event);
 
-        // completion
-        const completion = await this.props.vendor.api.chat.completions.create(
-          event.body,
-          event.options,
-        );
+      // completion
+      const completion = await this.props.vendor.api.chat.completions.create(
+        event.body,
+        event.options,
+      );
 
-        const [streamForEvent, temporaryStream] = StreamUtil.transform(
-          completion.toReadableStream() as ReadableStream<Uint8Array>,
-          value =>
-            ChatGptCompletionMessageUtil.transformCompletionChunk(value),
-        ).tee();
+      const [streamForEvent, temporaryStream] = StreamUtil.transform(
+        completion.toReadableStream() as ReadableStream<Uint8Array>,
+        value =>
+          ChatGptCompletionMessageUtil.transformCompletionChunk(value),
+      ).tee();
 
-        const [streamForAggregate, streamForReturn] = temporaryStream.tee();
+      const [streamForAggregate, streamForReturn] = temporaryStream.tee();
 
-        void (async () => {
-          const reader = streamForAggregate.getReader();
-          while (true) {
-            const chunk = await reader.read();
-            if (chunk.done) {
-              break;
-            }
-            if (chunk.value.usage != null) {
-              AgenticaTokenUsageAggregator.aggregate({
-                kind: source,
-                completionUsage: chunk.value.usage,
-                usage: props.usage,
-              });
-            }
+      void (async () => {
+        const reader = streamForAggregate.getReader();
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) {
+            break;
           }
-        })();
+          if (chunk.value.usage != null) {
+            AgenticaTokenUsageAggregator.aggregate({
+              kind: source,
+              completionUsage: chunk.value.usage,
+              usage: props.usage,
+            });
+          }
+        }
+      })().catch(() => {});
 
-        const [streamForStream, streamForJoin] = streamForEvent.tee();
-        await dispatch({
-          type: "response",
-          source,
-          stream: streamDefaultReaderToAsyncGenerator(streamForStream.getReader()),
-          body: event.body,
-          options: event.options,
-          join: async () => {
-            const chunks = await StreamUtil.readAll(streamForJoin);
-            return ChatGptCompletionMessageUtil.merge(chunks);
-          },
-        });
+      const [streamForStream, streamForJoin] = streamForEvent.tee();
+      props.dispatch({
+        id: v4(),
+        type: "response",
+        source,
+        stream: streamDefaultReaderToAsyncGenerator(streamForStream.getReader()),
+        body: event.body,
+        options: event.options,
+        join: async () => {
+          const chunks = await StreamUtil.readAll(streamForJoin);
+          return ChatGptCompletionMessageUtil.merge(chunks);
+        },
+        created_at: new Date().toISOString(),
+      });
+      return streamForReturn;
+    };
+    return {
+      operations: this.operations_,
+      config: this.props.config,
 
-        return streamForReturn;
-      },
+      histories: this.histories_,
+      prompt: props.prompt,
+      dispatch: props.dispatch,
+      request: this.semaphore_ === null
+        ? request
+        : async (source, body) => {
+          await this.semaphore_!.acquire();
+          try {
+            return await request(source, body);
+          }
+          finally {
+            void this.semaphore_!.release().catch(() => {});
+          }
+        },
     };
   }
 

package/src/constants/AgenticaDefaultPrompt.ts

@@ -1,5 +1,7 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
+import { is_node } from "tstl";
+
 import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
 import type { IMicroAgenticaConfig } from "../structures/IMicroAgenticaConfig";
 import type { IMicroAgenticaSystemPrompt } from "../structures/IMicroAgenticaSystemPrompt";
@@ -8,30 +10,11 @@ import { Singleton } from "../utils/Singleton";
 
 import { AgenticaSystemPrompt } from "./AgenticaSystemPrompt";
 
-/**
- * @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()
+  is_node()
     // eslint-disable-next-line node/prefer-global/process
     ? (process.env.LANG?.split(".")[0] ?? "en-US")
     : navigator.language,

package/src/context/AgenticaContext.ts

@@ -115,7 +115,7 @@ export interface AgenticaContext<Model extends ILlmSchema.Model> {
    *
    * @param event Event to deliver
    */
-  dispatch: (event: AgenticaEvent<Model>) => Promise<void>;
+  dispatch: (event: AgenticaEvent<Model>) => void;
 
   /**
    * Request to the OpenAI server.

package/src/context/MicroAgenticaContext.ts

@@ -75,11 +75,11 @@ export interface MicroAgenticaContext<Model extends ILlmSchema.Model> {
    * Dispatch event.
    *
    * Dispatch event so that the agent can be handle the event
-   * through the {@link Agentica.on} function.
+   * through the {@link MicroAgentica.on} function.
    *
    * @param event Event to deliver
    */
-  dispatch: (event: MicroAgenticaEvent<Model>) => Promise<void>;
+  dispatch: (event: MicroAgenticaEvent<Model>) => void;
 
   /**
    * Request to the OpenAI server.

package/src/context/internal/AgenticaOperationComposer.spec.ts

@@ -87,7 +87,6 @@ async function createMockMcpController(name: string, functions: IMcpLlmFunction<
 
 describe("a AgenticaOperationComposer", () => {
   beforeAll(async () => {
-    // eslint-disable-next-line ts/no-unsafe-call
     const server = await createServer({
       name: "calculator",
       version: "1.0.0",
@@ -97,7 +96,7 @@ describe("a AgenticaOperationComposer", () => {
 
     await Promise.all([
       client.connect(clientTransport),
-      // eslint-disable-next-line ts/no-unsafe-call
+
       server.connect(serverTransport),
     ]);
   });

package/src/events/AgenticaEventBase.ts

@@ -1,6 +1,18 @@
+import type { tags } from "typia";
+
 export interface AgenticaEventBase<Type extends string> {
+  /**
+   * Primary key of the event.
+   */
+  id: string;
+
   /**
    * Discriminator type.
    */
   type: Type;
+
+  /**
+   * Creation timestamp of the event.
+   */
+  created_at: string & tags.Format<"date-time">;
 }