@agentica/core 0.22.0 → 0.24.0

package/src/utils/ChatGptCompletionMessageUtil.spec.ts

@@ -0,0 +1,320 @@
+import type {
+  ChatCompletion,
+  ChatCompletionChunk,
+  ChatCompletionMessageToolCall,
+} from "openai/resources";
+
+import { ChatGptCompletionMessageUtil } from "./ChatGptCompletionMessageUtil";
+
+describe("chatGptCompletionMessageUtil", () => {
+  describe("transformCompletionChunk", () => {
+    it("should transform string chunk to ChatCompletionChunk", () => {
+      const chunk = {
+        id: "test-id",
+        choices: [{
+          index: 0,
+          delta: { content: "Hello" },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion.chunk",
+      };
+
+      const result = ChatGptCompletionMessageUtil.transformCompletionChunk(JSON.stringify(chunk));
+      expect(result).toEqual(chunk);
+    });
+
+    it("should transform Uint8Array chunk to ChatCompletionChunk", () => {
+      const chunk = {
+        id: "test-id",
+        choices: [{
+          index: 0,
+          delta: { content: "Hello" },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion.chunk",
+      };
+
+      const uint8Array = new TextEncoder().encode(JSON.stringify(chunk));
+      const result = ChatGptCompletionMessageUtil.transformCompletionChunk(uint8Array);
+      expect(result).toEqual(chunk);
+    });
+
+    it("should handle invalid JSON", () => {
+      expect(() => {
+        ChatGptCompletionMessageUtil.transformCompletionChunk("invalid json");
+      }).toThrow();
+    });
+  });
+
+  describe("accumulate", () => {
+    it("should accumulate content from chunks", () => {
+      const origin: ChatCompletion = {
+        id: "test-id",
+        choices: [{
+          index: 0,
+          // @ts-expect-error - refusal is not required
+          message: { role: "assistant", content: "Hello" },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion",
+      };
+
+      const chunk: ChatCompletionChunk = {
+        id: "test-id",
+        // @ts-expect-error - finish_reason is not required
+        choices: [{
+          index: 0,
+          delta: { content: " World" },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion.chunk",
+      };
+
+      const result = ChatGptCompletionMessageUtil.accumulate(origin, chunk);
+      expect(result.choices[0]?.message.content).toBe("Hello World");
+    });
+
+    it("should accumulate tool calls", () => {
+      const origin: ChatCompletion = {
+        id: "test-id",
+        choices: [{
+          index: 0,
+          // @ts-expect-error - finish_reason is not required
+          message: {
+            role: "assistant",
+            content: null,
+            tool_calls: [{
+              id: "call_1",
+              type: "function",
+              function: {
+                name: "test",
+                arguments: "{\"arg\": \"value\"}",
+              },
+            }],
+          },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion",
+      };
+
+      const chunk: ChatCompletionChunk = {
+        id: "test-id",
+        // @ts-expect-error - finish_reason is not required
+        choices: [{
+          index: 0,
+          delta: {
+            tool_calls: [{
+              index: 0,
+              id: "call_1",
+              function: {
+                name: "_function",
+                arguments: "{\"arg2\": \"value2\"}",
+              },
+            }],
+          },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion.chunk",
+      };
+
+      const result = ChatGptCompletionMessageUtil.accumulate(origin, chunk);
+      expect(result.choices[0]?.message.tool_calls?.[0]?.function.name).toBe("test_function");
+      expect(result.choices[0]?.message.tool_calls?.[0]?.function.arguments).toBe("{\"arg\": \"value\"}{\"arg2\": \"value2\"}");
+    });
+
+    it("should handle usage aggregation", () => {
+      const origin: ChatCompletion = {
+        id: "test-id",
+        choices: [{
+          index: 0,
+          // @ts-expect-error - finish_reason is not required
+          message: { role: "assistant", content: "Hello" },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion",
+        usage: {
+          prompt_tokens: 10,
+          completion_tokens: 5,
+          total_tokens: 15,
+        },
+      };
+
+      const chunk: ChatCompletionChunk = {
+        id: "test-id",
+        // @ts-expect-error - finish_reason is not required
+        choices: [{
+          index: 0,
+          delta: { content: " World" },
+        }],
+        created: 1234567890,
+        model: "gpt-4",
+        object: "chat.completion.chunk",
+        usage: {
+          prompt_tokens: 0,
+          completion_tokens: 6,
+          total_tokens: 6,
+        },
+      };
+
+      const result = ChatGptCompletionMessageUtil.accumulate(origin, chunk);
+      expect(result.usage).toEqual({
+        prompt_tokens: 10,
+        completion_tokens: 11,
+        total_tokens: 21,
+        completion_tokens_details: {
+          accepted_prediction_tokens: 0,
+          reasoning_tokens: 0,
+          rejected_prediction_tokens: 0,
+        },
+        prompt_tokens_details: {
+          audio_tokens: 0,
+          cached_tokens: 0,
+        },
+      });
+    });
+  });
+
+  describe("merge", () => {
+    it("should merge multiple chunks into completion", () => {
+      const chunks: ChatCompletionChunk[] = [
+        {
+          id: "test-id",
+          // @ts-expect-error - finish_reason is not required
+          choices: [{
+            index: 0,
+            delta: { content: "Hello" },
+          }],
+          created: 1234567890,
+          model: "gpt-4",
+          object: "chat.completion.chunk",
+        },
+        {
+          id: "test-id",
+          // @ts-expect-error - finish_reason is not required
+          choices: [{
+            index: 0,
+            delta: { content: " World" },
+          }],
+          created: 1234567890,
+          model: "gpt-4",
+          object: "chat.completion.chunk",
+        },
+      ];
+
+      const result = ChatGptCompletionMessageUtil.merge(chunks);
+      expect(result.choices[0]?.message.content).toBe("Hello World");
+    });
+
+    it("should throw error for empty chunks array", () => {
+      expect(() => {
+        ChatGptCompletionMessageUtil.merge([]);
+      }).toThrow("No chunks received");
+    });
+  });
+
+  describe("mergeChoice", () => {
+    it("should merge finish reason", () => {
+      const acc: ChatCompletion.Choice = {
+        index: 0,
+        // @ts-expect-error - finish_reason is not required
+        message: { role: "assistant", content: "Hello" },
+      };
+
+      const cur: ChatCompletionChunk.Choice = {
+        index: 0,
+        delta: {},
+        finish_reason: "stop",
+      };
+
+      const result = ChatGptCompletionMessageUtil.mergeChoice(acc, cur);
+      expect(result.finish_reason).toBe("stop");
+    });
+
+    it("should merge content", () => {
+      const acc: ChatCompletion.Choice = {
+        index: 0,
+        // @ts-expect-error - refusal is not required
+        message: { role: "assistant", content: "Hello" },
+      };
+
+      // @ts-expect-error - finish_reason is not required
+      const cur: ChatCompletionChunk.Choice = {
+        index: 0,
+        delta: { content: " World" },
+      };
+
+      const result = ChatGptCompletionMessageUtil.mergeChoice(acc, cur);
+      expect(result.message.content).toBe("Hello World");
+    });
+
+    it("should merge refusal", () => {
+      // @ts-expect-error - finish_reason is not required
+      const acc: ChatCompletion.Choice = {
+        index: 0,
+        message: { role: "assistant", content: null, refusal: "I cannot" },
+      };
+
+      // @ts-expect-error - finish_reason is not required
+      const cur: ChatCompletionChunk.Choice = {
+        index: 0,
+        delta: { refusal: " do that" },
+      };
+
+      const result = ChatGptCompletionMessageUtil.mergeChoice(acc, cur);
+      expect(result.message.refusal).toBe("I cannot do that");
+    });
+  });
+
+  describe("mergeToolCalls", () => {
+    it("should merge tool call function arguments", () => {
+      const acc: ChatCompletionMessageToolCall = {
+        id: "call_1",
+        type: "function",
+        function: {
+          name: "test",
+          arguments: "{\"arg\": \"value\"}",
+        },
+      };
+
+      const cur: ChatCompletionChunk.Choice.Delta.ToolCall = {
+        index: 0,
+        id: "call_1",
+        function: {
+          arguments: "{\"arg2\": \"value2\"}",
+        },
+      };
+
+      const result = ChatGptCompletionMessageUtil.mergeToolCalls(acc, cur);
+      expect(result.function.arguments).toBe("{\"arg\": \"value\"}{\"arg2\": \"value2\"}");
+    });
+
+    it("should merge tool call function name", () => {
+      const acc: ChatCompletionMessageToolCall = {
+        id: "call_1",
+        type: "function",
+        function: {
+          name: "test",
+          arguments: "",
+        },
+      };
+
+      const cur: ChatCompletionChunk.Choice.Delta.ToolCall = {
+        index: 0,
+        id: "call_1",
+        function: {
+          name: "_function",
+        },
+      };
+
+      const result = ChatGptCompletionMessageUtil.mergeToolCalls(acc, cur);
+      expect(result.function.name).toBe("test_function");
+    });
+  });
+});

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;