@agentica/core 0.16.8 → 0.17.0

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

@@ -0,0 +1,314 @@
+import type { IHttpLlmFunction, ILlmFunction, IValidation } from "@samchon/openapi";
+
+import type { IAgenticaConfig } from "../../structures/IAgenticaConfig";
+import type { IAgenticaController } from "../../structures/IAgenticaController";
+import type { IMcpLlmFunction } from "../../structures/mcp/IMcpLlmFunction";
+
+import { compose, divide, getOperations, toClassOperations, toHttpOperations, toMcpOperations } from "./AgenticaOperationComposer";
+
+// test helper functions
+function createMockHttpFunction(name: string, method: "get" | "post" | "patch" | "put" | "delete", path: string): IHttpLlmFunction<any> {
+  return {
+    name,
+    method,
+    path,
+    validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+    operation: () => ({}),
+    route: () => ({
+      method,
+      path,
+      emendedPath: path,
+      accessor: [name],
+      body: null,
+      query: null,
+      parameters: [],
+      headers: null,
+      success: null,
+      exceptions: {},
+      comment: () => "OK",
+      operation: () => ({}),
+    }),
+    parameters: {},
+    output: {},
+  };
+}
+
+function createMockHttpController(name: string, functions: IHttpLlmFunction<any>[]): IAgenticaController.IHttp<any> {
+  return {
+    name,
+    protocol: "http",
+    connection: { host: "https://example.com" },
+    application: {
+      model: "chatgpt",
+      options: {},
+      functions,
+      errors: [],
+    },
+  };
+}
+
+function createMockClassController(name: string, functions: ILlmFunction<any>[]): IAgenticaController.IClass<any> {
+  return {
+    name,
+    protocol: "class",
+    application: {
+      model: "chatgpt",
+      options: {},
+      functions,
+    },
+    execute: {},
+  };
+}
+
+function createMockMcpController(name: string, functions: IMcpLlmFunction[]): IAgenticaController.IMcp {
+  return {
+    name,
+    protocol: "mcp",
+    application: {
+      transport: {
+        type: "sse",
+        url: new URL("https://example.com"),
+      },
+      functions,
+    },
+  };
+}
+
+describe("a AgenticaOperationComposer", () => {
+  describe("compose", () => {
+    it("should compose operations from controllers", () => {
+      // Mock controllers
+      const mockHttpController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+      ]);
+
+      const mockClassController = createMockClassController("classController", [
+        {
+          name: "function3",
+          validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+          parameters: {},
+          output: {},
+        },
+      ]);
+
+      const mockMcpController = createMockMcpController("mcpController", [
+        {
+          name: "function4",
+          parameters: {},
+        },
+      ]);
+
+      const controllers = [mockHttpController, mockClassController, mockMcpController];
+
+      const result = compose({ controllers });
+
+      expect(result.array).toHaveLength(4);
+      expect(result.flat).toBeInstanceOf(Map);
+      expect(result.group).toBeInstanceOf(Map);
+      expect(result.divided).toBeUndefined();
+    });
+
+    it("should divide operations when capacity is provided", () => {
+      // Mock controllers
+      const mockController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+        createMockHttpFunction("function3", "put", "/api/function3"),
+        createMockHttpFunction("function4", "delete", "/api/function4"),
+        createMockHttpFunction("function5", "patch", "/api/function5"),
+      ]);
+
+      const config: IAgenticaConfig<any> = {
+        capacity: 2,
+      };
+
+      const result = compose({ controllers: [mockController], config });
+
+      expect(result.array).toHaveLength(5);
+      expect(result.divided).toBeDefined();
+      expect(result.divided).toHaveLength(3); // 5 items with capacity 2 should be divided into 3 groups
+    });
+  });
+
+  describe("getOperations", () => {
+    it("should get operations from http controllers", () => {
+      const mockController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+      ]);
+
+      const result = getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(2);
+      expect(result[0]?.protocol).toBe("http");
+      expect(result[0]?.name).toBe("_0_function1");
+      expect(result[1]?.name).toBe("_0_function2");
+    });
+
+    it("should get operations from class controllers", () => {
+      const mockController = createMockClassController("classController", [
+        {
+          name: "function1",
+          validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+          parameters: {},
+          output: {},
+        },
+      ]);
+
+      const result = getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("class");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+
+    it("should get operations from mcp controllers", () => {
+      const mockController = createMockMcpController("mcpController", [
+        {
+          name: "function1",
+          parameters: {},
+        },
+      ]);
+
+      const result = getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("mcp");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+
+    it("should throw error for unsupported protocol", () => {
+      const mockController: IAgenticaController.IHttp<any> = {
+        name: "unsupportedController",
+        protocol: "unsupported" as unknown as "http",
+        connection: { host: "https://example.com" },
+        application: { } as unknown as IAgenticaController.IHttp<any>["application"],
+      };
+
+      expect(() => getOperations({ controllers: [mockController], naming: (func, idx) => `_${idx}_${func}` })).toThrow("Unsupported protocol: unsupported");
+    });
+  });
+
+  describe("toHttpOperations", () => {
+    it("should convert http controller to operations", () => {
+      const mockController = createMockHttpController("httpController", [
+        createMockHttpFunction("function1", "get", "/api/function1"),
+        createMockHttpFunction("function2", "post", "/api/function2"),
+      ]);
+
+      const result = toHttpOperations({ controller: mockController, index: 0, naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(2);
+      expect(result[0]?.protocol).toBe("http");
+      expect(result[0]?.name).toBe("_0_function1");
+      expect(result[1]?.name).toBe("_0_function2");
+    });
+  });
+
+  describe("toClassOperations", () => {
+    it("should convert class controller to operations", () => {
+      const mockController = createMockClassController("classController", [
+        {
+          name: "function1",
+          validate: () => ({ success: true, data: {} } as IValidation<unknown>),
+          parameters: {},
+          output: {},
+        },
+      ]);
+
+      const result = toClassOperations({ controller: mockController, index: 0, naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("class");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+  });
+
+  describe("toMcpOperations", () => {
+    it("should convert mcp controller to operations", () => {
+      const mockController = createMockMcpController("mcpController", [
+        {
+          name: "function1",
+          parameters: {},
+        },
+      ]);
+
+      const result = toMcpOperations({ controller: mockController, index: 0, naming: (func, idx) => `_${idx}_${func}` });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]?.protocol).toBe("mcp");
+      expect(result[0]?.name).toBe("_0_function1");
+    });
+  });
+  describe("divide with invalid capacity", () => {
+    it("should throw error when capacity is 0", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = 0;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+
+    it("should throw error when capacity is negative", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = -3;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+
+    it("should throw error when capacity is decimal", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = 2.5;
+      const result = divide({ array, capacity });
+      expect(result).toEqual([[1, 2, 3], [4, 5]]);
+    });
+
+    it("should throw error when capacity is Infinity", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = Infinity;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+
+    it("should throw error when capacity is NaN", () => {
+      const array = [1, 2, 3, 4, 5];
+      const capacity = Number.NaN;
+
+      expect(() => divide({ array, capacity })).toThrow("Capacity must be a positive integer");
+    });
+  });
+
+  describe("divide", () => {
+    it("should divide array into chunks based on capacity", () => {
+      const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+      const capacity = 3;
+
+      const result = divide({ array, capacity });
+
+      expect(result).toHaveLength(4); // 10 items with capacity 3 should be divided into 4 groups
+      expect(result[0]).toEqual([1, 2, 3]);
+      expect(result[1]).toEqual([4, 5, 6]);
+      expect(result[2]).toEqual([7, 8, 9]);
+      expect(result[3]).toEqual([10]);
+    });
+
+    it("should handle empty array", () => {
+      const array: number[] = [];
+      const capacity = 3;
+
+      const result = divide({ array, capacity });
+
+      expect(result).toHaveLength(0);
+    });
+
+    it("should handle array smaller than capacity", () => {
+      const array = [1, 2];
+      const capacity = 3;
+
+      const result = divide({ array, capacity });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual([1, 2]);
+    });
+  });
+});

package/src/context/internal/AgenticaOperationComposer.ts

@@ -8,59 +8,27 @@ import type { AgenticaOperationCollection } from "../AgenticaOperationCollection
 
 import { __map_take } from "../../utils/__map_take";
 
+/**
+ * Compose the agentica operation collection.
+ *
+ * Compose the {@link AgenticaOperationCollection} from the given
+ * controllers and config.
+ *
+ * @internal
+ */
 export function compose<Model extends ILlmSchema.Model>(props: {
   controllers: IAgenticaController<Model>[];
   config?: IAgenticaConfig<Model> | IMicroAgenticaConfig<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 =>
-                ({
-                  protocol: "http",
-                  controller,
-                  function: func,
-                  name: naming(func.name, ci),
-                  toJSON: () => ({
-                    protocol: "http",
-                    controller: controller.name,
-                    function: func.name,
-                    name: naming(func.name, ci),
-                  }),
-                }) satisfies AgenticaOperation.Http<Model>,
-          )
-        : controller.application.functions.map(
-            func =>
-                ({
-                  protocol: "class",
-                  controller,
-                  function: func,
-                  name: naming(func.name, ci),
-                  toJSON: () => ({
-                    protocol: "class",
-                    controller: controller.name,
-                    function: func.name,
-                    name: naming(func.name, ci),
-                  }),
-                }) satisfies AgenticaOperation.Class<Model>,
-          ),
-    )
-    .flat();
+  const unique: boolean = (props.controllers.length === 1 || (() => {
+    const names = props.controllers.map(controllers => controllers.application.functions.map(func => func.name)).flat();
+    return new Set(names).size === names.length;
+  })());
 
+  const array: AgenticaOperation<Model>[] = getOperations({
+    controllers: props.controllers,
+    naming: (func: string, controllerIndex: number) => unique ? func : `_${controllerIndex}_${func}`,
+  });
   const capacity: number | undefined = (props.config as IAgenticaConfig<Model>)?.capacity;
   const divided: AgenticaOperation<Model>[][] | undefined
       = capacity !== undefined && array.length > capacity
@@ -87,10 +55,112 @@ export function compose<Model extends ILlmSchema.Model>(props: {
   };
 }
 
-function divide<T>(props: {
+/**
+ * @internal
+ */
+export function getOperations<Model extends ILlmSchema.Model>(props: {
+  controllers: IAgenticaController<Model>[];
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controllers.flatMap((controller, idx) => {
+    switch (controller.protocol) {
+      case "http":{
+        return toHttpOperations({ controller, index: idx, naming: props.naming }); }
+      case "class":{
+        return toClassOperations({ controller, index: idx, naming: props.naming }); }
+      case "mcp": {
+        return toMcpOperations({ controller, index: idx, naming: props.naming });
+      }
+      default:
+        controller satisfies never;
+        throw new Error(`Unsupported protocol: ${(controller as { protocol: string }).protocol}`);
+    }
+  });
+}
+
+/**
+ * @internal
+ */
+export function toHttpOperations<Model extends ILlmSchema.Model>(props: {
+  controller: IAgenticaController.IHttp<Model>;
+  index: number;
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controller.application.functions.map(func => ({
+    protocol: "http",
+    controller: props.controller,
+    function: func,
+    name: props.naming(func.name, props.index),
+    toJSON: () => ({
+      protocol: "http",
+      controller: props.controller.name,
+      function: func.name,
+      name: props.naming(func.name, props.index),
+    }),
+  }));
+}
+
+/**
+ * @internal
+ */
+export function toClassOperations<Model extends ILlmSchema.Model>(props: {
+  controller: IAgenticaController.IClass<Model>;
+  index: number;
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controller.application.functions.map(func => ({
+    protocol: "class",
+    controller: props.controller,
+    function: func,
+    name: props.naming(func.name, props.index),
+    toJSON: () => ({
+      protocol: "class",
+      controller: props.controller.name,
+      function: func.name,
+      name: props.naming(func.name, props.index),
+    }),
+  }));
+}
+
+/**
+ * @internal
+ */
+export function toMcpOperations<Model extends ILlmSchema.Model>(props: {
+  controller: IAgenticaController.IMcp;
+  index: number;
+  naming: (func: string, controllerIndex: number) => string;
+}): AgenticaOperation<Model>[] {
+  return props.controller.application.functions.map(func => ({
+    protocol: "mcp",
+    controller: props.controller,
+    function: func,
+    name: props.naming(func.name, props.index),
+    toJSON: () => ({
+      protocol: "mcp",
+      controller: props.controller.name,
+      function: func.name,
+      name: props.naming(func.name, props.index),
+    }),
+  }));
+}
+
+/**
+ * @internal
+ */
+export function divide<T>(props: {
   array: T[];
   capacity: number;
 }): T[][] {
+  if (props.capacity <= 0) {
+    throw new Error("Capacity must be a positive integer");
+  }
+  if (Number.isNaN(props.capacity)) {
+    throw new TypeError("Capacity must be a positive integer");
+  }
+  if (props.capacity === Infinity) {
+    throw new Error("Capacity must be a positive integer");
+  }
+
   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();

package/src/events/AgenticaDescribeEvent.ts

@@ -10,7 +10,7 @@ export interface AgenticaDescribeEvent<
   Model extends ILlmSchema.Model,
 > extends AgenticaEventBase<"describe"> {
   executes: AgenticaExecuteHistory<Model>[];
-  stream: ReadableStream<string>;
+  stream: AsyncGenerator<string, undefined, undefined>;
 
   join: () => Promise<string>;
   toJSON: () => IAgenticaEventJson.IDescribe;

package/src/events/AgenticaResponseEvent.ts

@@ -17,7 +17,7 @@ export interface AgenticaResponseEvent extends AgenticaEventBase<"response"> {
   /**
    * The text content stream.
    */
-  stream: ReadableStream<OpenAI.ChatCompletionChunk>;
+  stream: AsyncGenerator<OpenAI.ChatCompletionChunk, undefined, undefined>;
 
   /**
    * Options for the request.

package/src/events/AgenticaTextEvent.ts

@@ -7,7 +7,7 @@ export interface AgenticaTextEvent<
   Role extends "assistant" | "user" = "assistant" | "user",
 > extends AgenticaEventBase<"text"> {
   role: Role;
-  stream: ReadableStream<string>;
+  stream: AsyncGenerator<string, undefined, undefined>;
   join: () => Promise<string>;
   toJSON: () => IAgenticaEventJson.IText;
   toHistory: () => AgenticaTextHistory;

package/src/factory/events.ts

@@ -136,7 +136,7 @@ export function createExecuteEvent<Model extends ILlmSchema.Model>(props: {
 ----------------------------------------------------------- */
 export function createTextEvent<Role extends "user" | "assistant">(props: {
   role: Role;
-  stream: ReadableStream<string>;
+  stream: AsyncGenerator<string, undefined, undefined>;
   done: () => boolean;
   get: () => string;
   join: () => Promise<string>;
@@ -167,7 +167,7 @@ export function createTextEvent<Role extends "user" | "assistant">(props: {
 
 export function createDescribeEvent<Model extends ILlmSchema.Model>(props: {
   executes: AgenticaExecuteHistory<Model>[];
-  stream: ReadableStream<string>;
+  stream: AsyncGenerator<string, undefined, undefined>;
   done: () => boolean;
   get: () => string;
   join: () => Promise<string>;
@@ -216,7 +216,7 @@ export function createResponseEvent(props: {
   source: AgenticaEventSource;
   body: OpenAI.ChatCompletionCreateParamsStreaming;
   options?: OpenAI.RequestOptions | undefined;
-  stream: ReadableStream<OpenAI.ChatCompletionChunk>;
+  stream: AsyncGenerator<OpenAI.ChatCompletionChunk, undefined, undefined>;
   join: () => Promise<OpenAI.ChatCompletion>;
 }): AgenticaResponseEvent {
   return {

package/src/functional/assertMcpLlmApplication.ts

@@ -0,0 +1,48 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
+
+import type { IMcpLlmApplication, IMcpLlmTransportProps } from "../structures/mcp";
+/**
+ * Create an MCP LLM application instance with type assertion.
+ *
+ * Create an {@link IMcpLlmApplication} instance which represents
+ * an MCP (Model Context Protocol) LLM application.
+ *
+ * @param props Properties to create the MCP LLM application instance
+ * @param props.name Name of the MCP implementation.
+ * @param props.url URL of the MCP server.
+ * @param props.version Describes version of an MCP implementation.
+ * @returns MCP LLM application instance
+ * @author Samchon
+ */
+export async function assertMcpLlmApplication(props: IMcpLlmTransportProps): Promise<IMcpLlmApplication> {
+  const client = new Client({
+    name: "get_tool_list",
+    version: "1.0.0",
+  });
+
+  const transport = (() => {
+    switch (props.type) {
+      case "sse":
+        return new SSEClientTransport(props.url);
+      case "stdio":
+        return new StdioClientTransport(props);
+      default:
+        props satisfies never;
+        throw new Error("Invalid transport type");
+    }
+  })();
+  await client.connect(transport);
+
+  const toolList = await client.request({ method: "tools/list" }, ListToolsResultSchema);
+  return {
+    functions: toolList.tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema,
+    })),
+    transport: props,
+  };
+}

package/src/index.ts

@@ -6,9 +6,9 @@ export * from "./context/AgenticaOperation";
 export * from "./context/AgenticaOperationCollection";
 export * from "./context/AgenticaOperationSelection";
 export * from "./context/AgenticaTokenUsage";
+
 export * from "./events/AgenticaCallEvent";
 export * from "./events/AgenticaCancelEvent";
-
 export * from "./events/AgenticaDescribeEvent";
 export * from "./events/AgenticaEvent";
 export * from "./events/AgenticaEventSource";
@@ -19,10 +19,14 @@ export * from "./events/AgenticaSelectEvent";
 export * from "./events/AgenticaTextEvent";
 export * from "./events/AgenticaValidateEvent";
 export * from "./events/MicroAgenticaEvent";
+
 export * as factory from "./factory";
-export * from "./functional/assertHttpLlmApplication";
 
+export * from "./functional/assertHttpLlmApplication";
+export * from "./functional/assertMcpLlmApplication";
 export * from "./functional/validateHttpLlmApplication";
+// @TODO: implement validateMcpLlmApplication
+
 export * from "./histories/AgenticaCancelHistory";
 export * from "./histories/AgenticaDescribeHistory";
 export * from "./histories/AgenticaExecuteHistory";

package/src/json/IAgenticaOperationJson.ts

@@ -17,7 +17,7 @@ export interface IAgenticaOperationJson {
   /**
    * Protocol discriminator.
    */
-  protocol: "class" | "http";
+  protocol: "class" | "http" | "mcp";
 
   /**
    * Belonged controller of the target function.