@agentica/core 0.23.0 → 0.25.0

package/src/structures/IAgenticaController.ts

@@ -1,4 +1,3 @@
-import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
 import type {
   IHttpConnection,
   IHttpLlmApplication,
@@ -126,7 +125,10 @@ export namespace IAgenticaController {
     /**
      * MCP client for connection.
      */
-    client: Client;
+    // @ts-ignore Type checking only when `@modelcontextprotocol/sdk` is installed.
+    //            This strategy is useful for someone who does not need MCP,
+    //            for someone who has not installed `@modelcontextprotocol/sdk`.
+    client: import("@modelcontextprotocol/sdk/client/index.d.ts").Client;
   }
 
   interface IBase<Protocol, Application> {

package/src/structures/index.ts

@@ -0,0 +1,10 @@
+export * from "./IAgenticaConfig";
+export * from "./IAgenticaController";
+export * from "./IAgenticaExecutor";
+export * from "./IAgenticaProps";
+export * from "./IAgenticaSystemPrompt";
+export * from "./IAgenticaVendor";
+export * from "./IMicroAgenticaConfig";
+export * from "./IMicroAgenticaExecutor";
+export * from "./IMicroAgenticaProps";
+export * from "./IMicroAgenticaSystemPrompt";

package/src/transformers/{AgenticaEventTransformer.ts → transformEvent.ts}

@@ -1,6 +1,8 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
 import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { AgenticaUserMessageEvent, AgenticaValidateEvent } from "../events";
+import type { AgenticaAssistantMessageEvent } from "../events/AgenticaAssistantMessageEvent";
 import type { AgenticaCallEvent } from "../events/AgenticaCallEvent";
 import type { AgenticaCancelEvent } from "../events/AgenticaCancelEvent";
 import type { AgenticaDescribeEvent } from "../events/AgenticaDescribeEvent";
@@ -9,32 +11,16 @@ import type { AgenticaExecuteEvent } from "../events/AgenticaExecuteEvent";
 import type { AgenticaInitializeEvent } from "../events/AgenticaInitializeEvent";
 import type { AgenticaRequestEvent } from "../events/AgenticaRequestEvent";
 import type { AgenticaSelectEvent } from "../events/AgenticaSelectEvent";
-import type { AgenticaTextEvent } from "../events/AgenticaTextEvent";
 import type { IAgenticaEventJson } from "../json/IAgenticaEventJson";
 
-import { createCallEvent, createCancelEvent, createDescribeEvent, createExecuteEvent, createInitializeEvent, createRequestEvent, createSelectEvent, createTextEvent } from "../factory/events";
+import { creatAssistantEvent, createCallEvent, createCancelEvent, createDescribeEvent, createExecuteEvent, createInitializeEvent, createRequestEvent, createSelectEvent, createUserMessageEvent, createValidateEvent } from "../factory/events";
 import { createOperationSelection } from "../factory/operations";
 import { toAsyncGenerator } from "../utils/StreamUtil";
 
-function findOperation<Model extends ILlmSchema.Model>(props: {
-  operations: Map<string, Map<string, AgenticaOperation<Model>>>;
-  input: {
-    controller: string;
-    function: string;
-  };
-}): AgenticaOperation<Model> {
-  const found: AgenticaOperation<Model> | undefined = props.operations
-    .get(props.input.controller)
-    ?.get(props.input.function);
-  if (found === undefined) {
-    throw new Error(
-      `No operation found: (controller: ${props.input.controller}, function: ${props.input.function})`,
-    );
-  }
-  return found;
-}
-
-function transform<Model extends ILlmSchema.Model>(props: {
+/**
+ * @internal
+ */
+export function transformEvent<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson;
 }): AgenticaEvent<Model> {
@@ -76,15 +62,26 @@ function transform<Model extends ILlmSchema.Model>(props: {
       event: props.event,
     });
   }
-  else if (props.event.type === "text") {
-    return transformText({
+  else if (props.event.type === "assistantMessage") {
+    return transformAssistantMessage({
+      event: props.event,
+    });
+  }
+  else if (props.event.type === "userMessage") {
+    return transformUserMessage({
       event: props.event,
     });
   }
-  else { throw new Error("Unknown event type"); }
+  return transformValidateEvent({
+    operations: props.operations,
+    event: props.event,
+  });
 }
 
-function transformCall<Model extends ILlmSchema.Model>(props: {
+/**
+ * @internal
+ */
+export function transformCall<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.ICall;
 }): AgenticaCallEvent<Model> {
@@ -98,7 +95,10 @@ function transformCall<Model extends ILlmSchema.Model>(props: {
   });
 }
 
-export function transformCancel<Model extends ILlmSchema.Model>(props: {
+/**
+ * @internal
+ */
+function transformCancel<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.ICancel;
 }): AgenticaCancelEvent<Model> {
@@ -113,6 +113,9 @@ export function transformCancel<Model extends ILlmSchema.Model>(props: {
   });
 }
 
+/**
+ * @internal
+ */
 function transformDescribe<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.IDescribe;
@@ -131,6 +134,9 @@ function transformDescribe<Model extends ILlmSchema.Model>(props: {
   });
 }
 
+/**
+ * @internal
+ */
 function transformExecute<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.IExecute;
@@ -146,16 +152,25 @@ function transformExecute<Model extends ILlmSchema.Model>(props: {
   });
 }
 
+/**
+ * @internal
+ */
 function transformInitialize(): AgenticaInitializeEvent {
   return createInitializeEvent();
 }
 
+/**
+ * @internal
+ */
 function transformRequest(props: {
   event: IAgenticaEventJson.IRequest;
 }): AgenticaRequestEvent {
   return createRequestEvent(props.event);
 }
 
+/**
+ * @internal
+ */
 function transformSelect<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   event: IAgenticaEventJson.ISelect;
@@ -171,10 +186,13 @@ function transformSelect<Model extends ILlmSchema.Model>(props: {
   });
 }
 
-function transformText(props: {
-  event: IAgenticaEventJson.IText;
-}): AgenticaTextEvent {
-  return createTextEvent({
+/**
+ * @internal
+ */
+function transformAssistantMessage(props: {
+  event: IAgenticaEventJson.IAssistantMessage;
+}): AgenticaAssistantMessageEvent {
+  return creatAssistantEvent({
     stream: toAsyncGenerator(props.event.text),
     done: () => true,
     get: () => props.event.text,
@@ -182,15 +200,49 @@ function transformText(props: {
   });
 }
 
-export const AgenticaEventTransformer = {
-  transform,
-  transformCall,
-  transformCancel,
-  transformDescribe,
-  transformExecute,
-  transformInitialize,
-  transformRequest,
-  transformSelect,
-  transformText,
-  findOperation,
-};
+/**
+ * @internal
+ */
+function transformUserMessage(props: {
+  event: IAgenticaEventJson.IUserMessage;
+}): AgenticaUserMessageEvent {
+  return createUserMessageEvent(props.event);
+}
+
+/**
+ * @internal
+ */
+function transformValidateEvent<Model extends ILlmSchema.Model>(props: {
+  event: IAgenticaEventJson.IValidate;
+  operations: Map<string, Map<string, AgenticaOperation<Model>>>;
+}): AgenticaValidateEvent<Model> {
+  return createValidateEvent({
+    id: props.event.id,
+    operation: findOperation({
+      operations: props.operations,
+      input: props.event.operation,
+    }),
+    result: props.event.result,
+  });
+}
+
+/**
+ * @internal
+ */
+function findOperation<Model extends ILlmSchema.Model>(props: {
+  operations: Map<string, Map<string, AgenticaOperation<Model>>>;
+  input: {
+    controller: string;
+    function: string;
+  };
+}): AgenticaOperation<Model> {
+  const found: AgenticaOperation<Model> | undefined = props.operations
+    .get(props.input.controller)
+    ?.get(props.input.function);
+  if (found === undefined) {
+    throw new Error(
+      `No operation found: (controller: ${props.input.controller}, function: ${props.input.function})`,
+    );
+  }
+  return found;
+}

package/src/transformers/{AgenticaHistoryTransformer.ts → transformHistory.ts}

@@ -1,24 +1,34 @@
 import type { ILlmSchema } from "@samchon/openapi";
 
 import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { AgenticaUserMessageHistory } from "../histories";
+import type { AgenticaAssistantMessageHistory } from "../histories/AgenticaAssistantMessageHistory";
 import type { AgenticaCancelHistory } from "../histories/AgenticaCancelHistory";
 import type { AgenticaDescribeHistory } from "../histories/AgenticaDescribeHistory";
 import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
 import type { AgenticaHistory } from "../histories/AgenticaHistory";
 import type { AgenticaSelectHistory } from "../histories/AgenticaSelectHistory";
-import type { AgenticaTextHistory } from "../histories/AgenticaTextHistory";
 import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
 
-import { createCancelHistory, createDescribeHistory, createExecuteHistory, createSelectHistory, createTextHistory } from "../factory/histories";
+import { createAssistantMessageHistory, createCancelHistory, createDescribeHistory, createExecuteHistory, createSelectHistory, createUserMessageHistory } from "../factory/histories";
 import { createOperationSelection } from "../factory/operations";
 
-function transform<Model extends ILlmSchema.Model>(props: {
+/**
+ * @internal
+ */
+export function transformHistory<Model extends ILlmSchema.Model>(props: {
   operations: Map<string, Map<string, AgenticaOperation<Model>>>;
   history: IAgenticaHistoryJson;
 }): AgenticaHistory<Model> {
-  // TEXT
-  if (props.history.type === "text") {
-    return transformText({
+  // USER
+  if (props.history.type === "userMessage") {
+    return transformUserMessage({
+      history: props.history,
+    });
+  }
+  // ASSISTANT
+  else if (props.history.type === "assistantMessage") {
+    return transformAssistantMessage({
       history: props.history,
     });
   }
@@ -42,19 +52,22 @@ function transform<Model extends ILlmSchema.Model>(props: {
       history: props.history,
     });
   }
-  else if (props.history.type === "describe") {
-    return transformDescribe({
-      operations: props.operations,
-      history: props.history,
-    });
-  }
-  throw new Error("Invalid prompt type.");
+  return transformDescribe({
+    operations: props.operations,
+    history: props.history,
+  });
 }
 
-function transformText(props: {
-  history: IAgenticaHistoryJson.IText;
-}): AgenticaTextHistory {
-  return createTextHistory(props.history);
+function transformAssistantMessage(props: {
+  history: IAgenticaHistoryJson.IAssistantMessage;
+}): AgenticaAssistantMessageHistory {
+  return createAssistantMessageHistory(props.history);
+}
+
+function transformUserMessage(props: {
+  history: IAgenticaHistoryJson.IUserMessage;
+}): AgenticaUserMessageHistory {
+  return createUserMessageHistory(props.history);
 }
 
 function transformSelect<Model extends ILlmSchema.Model>(props: {
@@ -146,12 +159,3 @@ function findOperation<Model extends ILlmSchema.Model>(props: {
   }
   return found;
 }
-
-export const AgenticaHistoryTransformer = {
-  transform,
-  transformText,
-  transformSelect,
-  transformCancel,
-  transformExecute,
-  transformDescribe,
-};

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");
+    });
+  });
+});