@agentica/core 0.23.0 → 0.25.0

package/src/utils/ChatGptTokenUsageAggregator.spec.ts

@@ -0,0 +1,226 @@
+import type { CompletionUsage } from "openai/resources";
+
+import { ChatGptTokenUsageAggregator } from "./ChatGptTokenUsageAggregator";
+
+describe("chatGptTokenUsageAggregator", () => {
+  describe("sum", () => {
+    it("should sum basic token usage", () => {
+      const usage1: CompletionUsage = {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+      };
+
+      const usage2: CompletionUsage = {
+        prompt_tokens: 20,
+        completion_tokens: 10,
+        total_tokens: 30,
+      };
+
+      const result = ChatGptTokenUsageAggregator.sum(usage1, usage2);
+
+      expect(result).toEqual({
+        prompt_tokens: 30,
+        completion_tokens: 15,
+        total_tokens: 45,
+        completion_tokens_details: {
+          accepted_prediction_tokens: 0,
+          reasoning_tokens: 0,
+          rejected_prediction_tokens: 0,
+        },
+        prompt_tokens_details: {
+          audio_tokens: 0,
+          cached_tokens: 0,
+        },
+      });
+    });
+
+    it("should handle undefined values", () => {
+      const usage1: CompletionUsage = {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+      };
+
+      const usage2: CompletionUsage = {
+      // @ts-expect-error - intended to be undefined
+        prompt_tokens: undefined,
+        // @ts-expect-error - intended to be undefined
+        completion_tokens: undefined,
+        // @ts-expect-error - intended to be undefined
+        total_tokens: undefined,
+      };
+
+      const result = ChatGptTokenUsageAggregator.sum(usage1, usage2);
+
+      expect(result).toEqual({
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+        completion_tokens_details: {
+          accepted_prediction_tokens: 0,
+          reasoning_tokens: 0,
+          rejected_prediction_tokens: 0,
+        },
+        prompt_tokens_details: {
+          audio_tokens: 0,
+          cached_tokens: 0,
+        },
+      });
+    });
+
+    it("should sum completion token details", () => {
+      const usage1: CompletionUsage = {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+        completion_tokens_details: {
+          accepted_prediction_tokens: 3,
+          reasoning_tokens: 1,
+          rejected_prediction_tokens: 1,
+        },
+      };
+
+      const usage2: CompletionUsage = {
+        prompt_tokens: 20,
+        completion_tokens: 10,
+        total_tokens: 30,
+        completion_tokens_details: {
+          accepted_prediction_tokens: 7,
+          reasoning_tokens: 2,
+          rejected_prediction_tokens: 1,
+        },
+      };
+
+      const result = ChatGptTokenUsageAggregator.sum(usage1, usage2);
+
+      expect(result.completion_tokens_details).toEqual({
+        accepted_prediction_tokens: 10,
+        reasoning_tokens: 3,
+        rejected_prediction_tokens: 2,
+      });
+    });
+
+    it("should handle undefined completion token details", () => {
+      const usage1: CompletionUsage = {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+        completion_tokens_details: {
+          accepted_prediction_tokens: 3,
+          reasoning_tokens: 1,
+          rejected_prediction_tokens: 1,
+        },
+      };
+
+      const usage2: CompletionUsage = {
+        prompt_tokens: 20,
+        completion_tokens: 10,
+        total_tokens: 30,
+      };
+
+      const result = ChatGptTokenUsageAggregator.sum(usage1, usage2);
+
+      expect(result.completion_tokens_details).toEqual({
+        accepted_prediction_tokens: 3,
+        reasoning_tokens: 1,
+        rejected_prediction_tokens: 1,
+      });
+    });
+
+    it("should sum prompt token details", () => {
+      const usage1: CompletionUsage = {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+        prompt_tokens_details: {
+          audio_tokens: 3,
+          cached_tokens: 2,
+        },
+      };
+
+      const usage2: CompletionUsage = {
+        prompt_tokens: 20,
+        completion_tokens: 10,
+        total_tokens: 30,
+        prompt_tokens_details: {
+          audio_tokens: 7,
+          cached_tokens: 3,
+        },
+      };
+
+      const result = ChatGptTokenUsageAggregator.sum(usage1, usage2);
+
+      expect(result.prompt_tokens_details).toEqual({
+        audio_tokens: 10,
+        cached_tokens: 5,
+      });
+    });
+
+    it("should handle undefined prompt token details", () => {
+      const usage1: CompletionUsage = {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+        prompt_tokens_details: {
+          audio_tokens: 3,
+          cached_tokens: 2,
+        },
+      };
+
+      const usage2: CompletionUsage = {
+        prompt_tokens: 20,
+        completion_tokens: 10,
+        total_tokens: 30,
+      };
+
+      const result = ChatGptTokenUsageAggregator.sum(usage1, usage2);
+
+      expect(result.prompt_tokens_details).toEqual({
+        audio_tokens: 3,
+        cached_tokens: 2,
+      });
+    });
+
+    it("should handle all undefined values", () => {
+      const usage1: CompletionUsage = {
+      // @ts-expect-error - intended to be undefined
+        prompt_tokens: undefined,
+        // @ts-expect-error - intended to be undefined
+        completion_tokens: undefined,
+        // @ts-expect-error - intended to be undefined
+        total_tokens: undefined,
+        completion_tokens_details: undefined,
+        prompt_tokens_details: undefined,
+      };
+
+      const usage2: CompletionUsage = {
+      // @ts-expect-error - intended to be undefined
+        prompt_tokens: undefined,
+        // @ts-expect-error - intended to be undefined
+        completion_tokens: undefined,
+        // @ts-expect-error - intended to be undefined
+        total_tokens: undefined,
+        completion_tokens_details: undefined,
+        prompt_tokens_details: undefined,
+      };
+
+      const result = ChatGptTokenUsageAggregator.sum(usage1, usage2);
+
+      expect(result).toEqual({
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        total_tokens: 0,
+        completion_tokens_details: {
+          accepted_prediction_tokens: 0,
+          reasoning_tokens: 0,
+          rejected_prediction_tokens: 0,
+        },
+        prompt_tokens_details: {
+          audio_tokens: 0,
+          cached_tokens: 0,
+        },
+      });
+    });
+  });
+});

package/src/utils/Singleton.spec.ts

@@ -0,0 +1,138 @@
+import { Singleton } from "./Singleton";
+
+describe("singleton", () => {
+  describe("basic functionality", () => {
+    it("should create instance only once", () => {
+      const factory = () => ({ value: 42 });
+      const singleton = new Singleton(factory);
+
+      const instance1 = singleton.get();
+      const instance2 = singleton.get();
+
+      expect(instance1).toBe(instance2);
+      expect(instance1.value).toBe(42);
+    });
+
+    it("should create different instances for different singletons", () => {
+      const factory1 = () => ({ value: 42 });
+      const factory2 = () => ({ value: 24 });
+
+      const singleton1 = new Singleton(factory1);
+      const singleton2 = new Singleton(factory2);
+
+      const instance1 = singleton1.get();
+      const instance2 = singleton2.get();
+
+      expect(instance1).not.toBe(instance2);
+      expect(instance1.value).toBe(42);
+      expect(instance2.value).toBe(24);
+    });
+  });
+
+  describe("constructor arguments", () => {
+    it("should pass constructor arguments to factory", () => {
+      const factory = (value: number) => ({ value });
+      const singleton = new Singleton(factory);
+
+      const instance = singleton.get(42);
+      expect(instance.value).toBe(42);
+    });
+
+    it("should use same instance with same constructor arguments", () => {
+      const factory = (value: number) => ({ value });
+      const singleton = new Singleton(factory);
+
+      const instance1 = singleton.get(42);
+      const instance2 = singleton.get(42);
+
+      expect(instance1).toBe(instance2);
+      expect(instance1.value).toBe(42);
+    });
+
+    it("should return same instance even with different constructor arguments", () => {
+      const factory = (value: number) => ({ value });
+      const singleton = new Singleton(factory);
+
+      const instance1 = singleton.get(42);
+      const instance2 = singleton.get(24);
+
+      expect(instance1).toBe(instance2);
+      expect(instance1.value).toBe(42);
+      expect(instance2.value).toBe(42);
+    });
+  });
+
+  describe("complex object types", () => {
+    it("should handle complex objects", () => {
+      interface ComplexObject {
+        id: number;
+        data: { name: string; value: number };
+        timestamp: Date;
+      }
+
+      const factory = (id: number, name: string, value: number) => ({
+        id,
+        data: { name, value },
+        timestamp: new Date(),
+      });
+
+      const singleton = new Singleton<ComplexObject, [number, string, number]>(factory);
+      const instance = singleton.get(1, "test", 42);
+
+      expect(instance.id).toBe(1);
+      expect(instance.data.name).toBe("test");
+      expect(instance.data.value).toBe(42);
+      expect(instance.timestamp).toBeInstanceOf(Date);
+    });
+
+    it("should maintain same complex object instance", () => {
+      const factory = () => ({
+        data: new Map<string, number>([["key", 42]]),
+        array: [1, 2, 3],
+      });
+
+      const singleton = new Singleton(factory);
+      const instance1 = singleton.get();
+      const instance2 = singleton.get();
+
+      expect(instance1).toBe(instance2);
+      expect(instance1.data).toBe(instance2.data);
+      expect(instance1.array).toBe(instance2.array);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle null factory return", () => {
+      const factory = () => null;
+      const singleton = new Singleton(factory);
+
+      const instance = singleton.get();
+      expect(instance).toBeNull();
+    });
+
+    it("should handle undefined factory return", () => {
+      const factory = () => undefined;
+      const singleton = new Singleton(factory);
+
+      const instance = singleton.get();
+      expect(instance).toBeUndefined();
+    });
+
+    it("should handle primitive values", () => {
+      const factory = () => 42;
+      const singleton = new Singleton(factory);
+
+      const instance = singleton.get();
+      expect(instance).toBe(42);
+    });
+
+    it("should handle factory throwing error", () => {
+      const factory = () => {
+        throw new Error("Factory error");
+      };
+      const singleton = new Singleton(factory);
+
+      expect(() => singleton.get()).toThrow("Factory error");
+    });
+  });
+});

package/src/utils/Singleton.ts

@@ -5,6 +5,24 @@ const NOT_MOUNTED_YET = {};
 
 /**
  * @internal
+ *
+ * @description
+ * A singleton class that creates a single instance of a class.
+ *
+ * @example
+ * ```ts
+ * const singleton = new Singleton((name: string) => new SomeClass(name));
+ * const instance = singleton.get("test");
+ * ```
+ *
+ * but next case is not work
+ * ```ts
+ * const singleton = new Singleton((name: string) => new SomeClass(name));
+ * const instance = singleton.get("test");
+ * const instance2 = singleton.get("test2");
+ *
+ * expect(instance).toBe(instance2); // true
+ * ```
  */
 export class Singleton<T, Args extends any[] = []> {
   private readonly closure_: (...args: Args) => T;

package/src/utils/__map_take.spec.ts

@@ -0,0 +1,140 @@
+import { __map_take } from "./__map_take";
+
+describe("__map_take", () => {
+  describe("basic functionality", () => {
+    it("should generate value for new key", () => {
+      const map = new Map<string, number>();
+      const generator = () => 42;
+
+      const result = __map_take(map, "test", generator);
+
+      expect(result).toBe(42);
+      expect(map.get("test")).toBe(42);
+    });
+
+    it("should return existing value for existing key", () => {
+      const map = new Map<string, number>();
+      map.set("test", 100);
+
+      const generator = () => 42;
+      const result = __map_take(map, "test", generator);
+
+      expect(result).toBe(100);
+      expect(map.get("test")).toBe(100);
+    });
+  });
+
+  describe("various type tests", () => {
+    it("should handle object type", () => {
+      const map = new Map<string, { value: number }>();
+      const generator = () => ({ value: 42 });
+
+      const result = __map_take(map, "test", generator);
+
+      expect(result).toEqual({ value: 42 });
+      expect(map.get("test")).toEqual({ value: 42 });
+    });
+
+    it("should handle array type", () => {
+      const map = new Map<string, number[]>();
+      const generator = () => [1, 2, 3];
+
+      const result = __map_take(map, "test", generator);
+
+      expect(result).toEqual([1, 2, 3]);
+      expect(map.get("test")).toEqual([1, 2, 3]);
+    });
+
+    it("should handle function type", () => {
+      const map = new Map<string, () => number>();
+      const generator = () => () => 42;
+
+      const result = __map_take(map, "test", generator);
+
+      expect(result()).toBe(42);
+      expect(map.get("test")?.()).toBe(42);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle null key", () => {
+      const map = new Map<null, string>();
+      const generator = () => "test";
+
+      const result = __map_take(map, null, generator);
+
+      expect(result).toBe("test");
+      expect(map.get(null)).toBe("test");
+    });
+
+    it("should handle undefined key", () => {
+      const map = new Map<undefined, string>();
+      const generator = () => "test";
+
+      const result = __map_take(map, undefined, generator);
+
+      expect(result).toBe("test");
+      expect(map.get(undefined)).toBe("test");
+    });
+
+    it("should handle empty string key", () => {
+      const map = new Map<string, string>();
+      const generator = () => "test";
+
+      const result = __map_take(map, "", generator);
+
+      expect(result).toBe("test");
+      expect(map.get("")).toBe("test");
+    });
+  });
+
+  describe("generator function tests", () => {
+    it("should not call generator multiple times", () => {
+      const map = new Map<string, number>();
+      let callCount = 0;
+
+      const generator = () => {
+        callCount++;
+        return 42;
+      };
+
+      __map_take(map, "test", generator);
+      __map_take(map, "test", generator);
+
+      expect(callCount).toBe(1);
+    });
+
+    it("should handle generator throwing error", () => {
+      const map = new Map<string, number>();
+      const generator = () => {
+        throw new Error("Generator error");
+      };
+
+      expect(() => __map_take(map, "test", generator)).toThrow("Generator error");
+    });
+
+    it("should handle generator returning undefined", () => {
+      const map = new Map<string, undefined>();
+      const generator = () => undefined;
+
+      const result = __map_take(map, "test", generator);
+
+      expect(result).toBeUndefined();
+      expect(map.get("test")).toBeUndefined();
+    });
+  });
+
+  describe("concurrency tests", () => {
+    it("should handle concurrent access to same key", () => {
+      const map = new Map<string, number>();
+      const generator = () => 42;
+
+      const result1 = __map_take(map, "test", generator);
+      const result2 = __map_take(map, "test", generator);
+
+      expect(result1).toBe(42);
+      expect(result2).toBe(42);
+      expect(map.get("test")).toBe(42);
+    });
+  });
+});

package/lib/events/AgenticaTextEvent.d.ts

@@ -1,10 +0,0 @@
-import type { AgenticaTextHistory } from "../histories/AgenticaTextHistory";
-import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import type { AgenticaEventBase } from "./AgenticaEventBase";
-export interface AgenticaTextEvent extends AgenticaEventBase<"text"> {
-    role: "assistant";
-    stream: AsyncGenerator<string, undefined, undefined>;
-    join: () => Promise<string>;
-    toJSON: () => IAgenticaEventJson.IText;
-    toHistory: () => AgenticaTextHistory;
-}

package/lib/events/AgenticaTextEvent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"AgenticaTextEvent.js","sourceRoot":"","sources":["../../src/events/AgenticaTextEvent.ts"],"names":[],"mappings":""}

package/lib/events/AgenticaUserInputEvent.d.ts

@@ -1,10 +0,0 @@
-import type { AgenticaUserInputHistory } from "../histories/AgenticaUserInputHistory";
-import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
-import type { AgenticaEventBase } from "./AgenticaEventBase";
-export interface AgenticaUserInputEvent extends AgenticaEventBase<"user_input"> {
-    role: "user";
-    contents: Array<AgenticaUserInputHistory.Contents>;
-    join: () => Promise<Array<AgenticaUserInputHistory.Contents>>;
-    toJSON: () => IAgenticaEventJson.IUserInput;
-    toHistory: () => AgenticaUserInputHistory;
-}

package/lib/events/AgenticaUserInputEvent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"AgenticaUserInputEvent.js","sourceRoot":"","sources":["../../src/events/AgenticaUserInputEvent.ts"],"names":[],"mappings":""}

package/lib/histories/AgenticaTextHistory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"AgenticaTextHistory.js","sourceRoot":"","sources":["../../src/histories/AgenticaTextHistory.ts"],"names":[],"mappings":""}

package/lib/histories/AgenticaUserInputHistory.d.ts

@@ -1,80 +0,0 @@
-import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
-import type { AgenticaHistoryBase } from "./AgenticaHistoryBase";
-export interface AgenticaUserInputHistory extends AgenticaHistoryBase<"user_input", IAgenticaHistoryJson.IUserInput> {
-    role: "user";
-    contents: Array<AgenticaUserInputHistory.Contents>;
-}
-export declare namespace AgenticaUserInputHistory {
-    type Contents = Contents.File | Contents.Image | Contents.InputAudio | Contents.Text;
-    namespace Contents {
-        interface ContentsBase<Type extends string> {
-            /**
-             * The type of the content part.
-             */
-            type: Type;
-        }
-        /**
-         * Learn about
-         * [text inputs](https://platform.openai.com/docs/guides/text-generation).
-         */
-        export interface Text extends ContentsBase<"text"> {
-            /**
-             * The text content.
-             */
-            text: string;
-        }
-        /**
-         * Learn about [image inputs](https://platform.openai.com/docs/guides/vision).
-         */
-        export interface Image extends ContentsBase<"image_url"> {
-            image_url: {
-                /**
-                 * Either a URL of the image or the base64 encoded image data.
-                 */
-                url: string;
-                /**
-                 * Specifies the detail level of the image. Learn more in the
-                 * [Vision guide](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding).
-                 */
-                detail?: "auto" | "high" | "low";
-            };
-        }
-        /**
-         * Learn about [audio inputs](https://platform.openai.com/docs/guides/audio).
-         */
-        export interface InputAudio extends ContentsBase<"input_audio"> {
-            input_audio: {
-                /**
-                 * Base64 encoded audio data.
-                 */
-                data: string;
-                /**
-                 * The format of the encoded audio data. Currently supports "wav" and "mp3".
-                 */
-                format: "wav" | "mp3";
-            };
-        }
-        /**
-         * Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text
-         * generation.
-         */
-        export interface File extends ContentsBase<"file"> {
-            file: {
-                /**
-                 * The base64 encoded file data, used when passing the file to the model as a
-                 * string.
-                 */
-                file_data?: string;
-                /**
-                 * The ID of an uploaded file to use as input.
-                 */
-                file_id?: string;
-                /**
-                 * The name of the file, used when passing the file to the model as a string.
-                 */
-                filename?: string;
-            };
-        }
-        export {};
-    }
-}

package/lib/histories/AgenticaUserInputHistory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"AgenticaUserInputHistory.js","sourceRoot":"","sources":["../../src/histories/AgenticaUserInputHistory.ts"],"names":[],"mappings":""}

package/lib/structures/mcp/IMcpLlmTransportProps.d.ts

@@ -1,11 +0,0 @@
-import type { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.d.ts";
-import type { StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.d.ts";
-export type IMcpLlmTransportProps = IMcpLlmTransportPropsHttp | IMcpLlmTransportPropsStdio;
-export interface IMcpLlmTransportPropsHttp extends IMcpLlmTransportPropsBase<"sse">, SSEClientTransportOptions {
-    url: URL;
-}
-export interface IMcpLlmTransportPropsStdio extends IMcpLlmTransportPropsBase<"stdio">, StdioServerParameters {
-}
-export interface IMcpLlmTransportPropsBase<T extends string> {
-    type: T;
-}

package/lib/structures/mcp/IMcpLlmTransportProps.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=IMcpLlmTransportProps.js.map

package/lib/structures/mcp/IMcpLlmTransportProps.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IMcpLlmTransportProps.js","sourceRoot":"","sources":["../../../src/structures/mcp/IMcpLlmTransportProps.ts"],"names":[],"mappings":""}

package/lib/structures/mcp/index.d.ts

@@ -1 +0,0 @@
-export * from "./IMcpLlmTransportProps";

package/lib/structures/mcp/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/structures/mcp/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC"}