@agentica/core 0.43.2 → 0.44.0-dev.20260313

package/src/factory/index.ts

@@ -1,3 +1,3 @@
-export * from "./events";
-export * from "./histories";
-export * from "./operations";
+export * from "./events";
+export * from "./histories";
+export * from "./operations";

package/src/factory/operations.ts

@@ -1,16 +1,16 @@
-import type { AgenticaOperation } from "../context/AgenticaOperation";
-import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
-
-export function createOperationSelection(props: {
-  operation: AgenticaOperation;
-  reason: string;
-}): AgenticaOperationSelection {
-  return {
-    operation: props.operation,
-    reason: props.reason,
-    toJSON: () => ({
-      operation: props.operation.toJSON(),
-      reason: props.reason,
-    }),
-  };
-}
+import type { AgenticaOperation } from "../context/AgenticaOperation";
+import type { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+
+export function createOperationSelection(props: {
+  operation: AgenticaOperation;
+  reason: string;
+}): AgenticaOperationSelection {
+  return {
+    operation: props.operation,
+    reason: props.reason,
+    toJSON: () => ({
+      operation: props.operation.toJSON(),
+      reason: props.reason,
+    }),
+  };
+}

package/src/functional/assertHttpController.ts

@@ -1,104 +1,106 @@
-import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@samchon/openapi";
-
-import { HttpLlm, OpenApi } from "@samchon/openapi";
-import typia from "typia";
-
-import type { IAgenticaController } from "../structures/IAgenticaController";
-
-/**
- * Create an HTTP controller with type assertion.
- *
- * Create an {@link IAgenticaController.IHttp} instance which represents
- * the HTTP controller from the given Swagger/OpenAPI document and the
- * target LLM model with connection information.
- *
- * By the way, even though this `assertHttpController` function
- * supports every version of Swagger/OpenAPI specification, there can
- * be a type error in the given document. In that case, the function
- * will throw an error with detailed type error tracing information.
- *
- * @param props Properties to create the HTTP controller instance
- * @returns HTTP controller instance
- * @throws {@link TypeGuardError} when the given document is invalid
- * @author Samchon
- */
-export function assertHttpController(props: {
-  /**
-   * Name of the controller.
-   */
-  name: string;
-
-  /**
-   * Swagger/OpenAPI document.
-   */
-  document:
-    | SwaggerV2.IDocument
-    | OpenApiV3.IDocument
-    | OpenApiV3_1.IDocument
-    | OpenApi.IDocument
-    | unknown;
-
-  /**
-   * Connection to the server.
-   *
-   * Connection to the API server including the URL and headers.
-   */
-  connection: IHttpConnection;
-
-  /**
-   * Options for the LLM function calling schema composition.
-   */
-  config?: Partial<IHttpLlmApplication.IConfig>;
-
-  /**
-   * Executor of the API function.
-   *
-   * @param props Properties of the API function call
-   * @returns HTTP response of the API function call
-   */
-  execute?: (props: {
-    /**
-     * Connection to the server.
-     */
-    connection: IHttpConnection;
-
-    /**
-     * Application schema.
-     */
-    application: IHttpLlmApplication;
-
-    /**
-     * Function schema.
-     */
-    function: IHttpLlmFunction;
-
-    /**
-     * Arguments of the function calling.
-     *
-     * It is an object of key-value pairs of the API function's parameters.
-     * The property keys are composed by below rules:
-     *
-     * - parameter names
-     * - query parameter as an object type if exists
-     * - body parameter if exists
-     */
-    arguments: object;
-  }) => Promise<IHttpResponse>;
-}): IAgenticaController.IHttp {
-  const document = OpenApi.convert(typia.assert<
-    | SwaggerV2.IDocument
-    | OpenApiV3.IDocument
-    | OpenApiV3_1.IDocument
-    | OpenApi.IDocument
-  >(props.document));
-  return {
-    protocol: "http",
-    name: props.name,
-    application: HttpLlm.application({
-      document,
-      config: props.config,
-    }),
-    execute: props.execute,
-    connection: props.connection,
-  };
-}
+import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, OpenApi, OpenApiV3, OpenApiV3_1, OpenApiV3_2, SwaggerV2 } from "@typia/interface";
+
+import { HttpLlm, OpenApiConverter } from "@typia/utils";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an HTTP controller with type assertion.
+ *
+ * Create an {@link IAgenticaController.IHttp} instance which represents
+ * the HTTP controller from the given Swagger/OpenAPI document and the
+ * target LLM model with connection information.
+ *
+ * By the way, even though this `assertHttpController` function
+ * supports every version of Swagger/OpenAPI specification, there can
+ * be a type error in the given document. In that case, the function
+ * will throw an error with detailed type error tracing information.
+ *
+ * @param props Properties to create the HTTP controller instance
+ * @returns HTTP controller instance
+ * @throws {@link TypeGuardError} when the given document is invalid
+ * @author Samchon
+ */
+export function assertHttpController(props: {
+  /**
+   * Name of the controller.
+   */
+  name: string;
+
+  /**
+   * Swagger/OpenAPI document.
+   */
+  document:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApiV3_2.IDocument
+    | OpenApi.IDocument
+    | unknown;
+
+  /**
+   * Connection to the server.
+   *
+   * Connection to the API server including the URL and headers.
+   */
+  connection: IHttpConnection;
+
+  /**
+   * Options for the LLM function calling schema composition.
+   */
+  config?: Partial<IHttpLlmApplication.IConfig>;
+
+  /**
+   * Executor of the API function.
+   *
+   * @param props Properties of the API function call
+   * @returns HTTP response of the API function call
+   */
+  execute?: (props: {
+    /**
+     * Connection to the server.
+     */
+    connection: IHttpConnection;
+
+    /**
+     * Application schema.
+     */
+    application: IHttpLlmApplication;
+
+    /**
+     * Function schema.
+     */
+    function: IHttpLlmFunction;
+
+    /**
+     * Arguments of the function calling.
+     *
+     * It is an object of key-value pairs of the API function's parameters.
+     * The property keys are composed by below rules:
+     *
+     * - parameter names
+     * - query parameter as an object type if exists
+     * - body parameter if exists
+     */
+    arguments: object;
+  }) => Promise<IHttpResponse>;
+}): IAgenticaController.IHttp {
+  const document = OpenApiConverter.upgradeDocument(typia.assert<
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApiV3_2.IDocument
+    | OpenApi.IDocument
+  >(props.document));
+  return {
+    protocol: "http",
+    name: props.name,
+    application: HttpLlm.application({
+      document,
+      config: props.config,
+    }),
+    execute: props.execute,
+    connection: props.connection,
+  };
+}

package/src/functional/assertHttpLlmApplication.ts

@@ -1,57 +1,52 @@
-import type {
-  IHttpLlmApplication,
-  OpenApiV3,
-  OpenApiV3_1,
-  SwaggerV2,
-} from "@samchon/openapi";
-
-import {
-  HttpLlm,
-  OpenApi,
-} from "@samchon/openapi";
-import typia from "typia";
-
-/**
- * Create an HTTP LLM application instance with type assertion.
- *
- * Create an {@link IHttpLlmApplication} instance which represents
- * the LLM (Large Language Model) function calling application schema
- * from the given Swagger/OpenAPI document and the target LLM model.
- *
- * By the way, even though this `assertHttpLlmApplication` function
- * supports every version of Swagger/OpenAPI specification, there can
- * be a type error in the given document. In that case, the function
- * will throw an error with detailed type error tracing information.
- *
- * @param props Properties to create the HTTP LLM application instance
- * @returns  HTTP LLM application instance
- * @throws {@link TypeGuardError} when the given document is invalid
- * @author Samchon
- * @deprecated Use {@link assertHttpController} instead.
- */
-export function assertHttpLlmApplication(props: {
-  /**
-   * Swagger/OpenAPI document.
-   */
-  document:
-    | SwaggerV2.IDocument
-    | OpenApiV3.IDocument
-    | OpenApiV3_1.IDocument
-    | OpenApi.IDocument
-    | unknown;
-
-  /**
-   * Options for the LLM function calling schema composition.
-   */
-  config?: Partial<IHttpLlmApplication.IConfig>;
-}): IHttpLlmApplication {
-  return HttpLlm.application({
-    document: OpenApi.convert(typia.assert<
-      | SwaggerV2.IDocument
-      | OpenApiV3.IDocument
-      | OpenApiV3_1.IDocument
-      | OpenApi.IDocument
-    >(props.document)),
-    config: props.config,
-  });
-}
+import type { IHttpLlmApplication, OpenApiV3, OpenApiV3_1, OpenApiV3_2, SwaggerV2 } from "@typia/interface";
+import type { OpenApi } from "typia";
+
+import { HttpLlm, OpenApiConverter } from "@typia/utils";
+import typia from "typia";
+
+/**
+ * Create an HTTP LLM application instance with type assertion.
+ *
+ * Create an {@link IHttpLlmApplication} instance which represents
+ * the LLM (Large Language Model) function calling application schema
+ * from the given Swagger/OpenAPI document and the target LLM model.
+ *
+ * By the way, even though this `assertHttpLlmApplication` function
+ * supports every version of Swagger/OpenAPI specification, there can
+ * be a type error in the given document. In that case, the function
+ * will throw an error with detailed type error tracing information.
+ *
+ * @param props Properties to create the HTTP LLM application instance
+ * @returns  HTTP LLM application instance
+ * @throws {@link TypeGuardError} when the given document is invalid
+ * @author Samchon
+ * @deprecated Use {@link assertHttpController} instead.
+ */
+export function assertHttpLlmApplication(props: {
+  /**
+   * Swagger/OpenAPI document.
+   */
+  document:
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApiV3_2.IDocument
+    | OpenApi.IDocument
+    | unknown;
+
+  /**
+   * Options for the LLM function calling schema composition.
+   */
+  config?: Partial<IHttpLlmApplication.IConfig>;
+}): IHttpLlmApplication {
+  return HttpLlm.application({
+    document: OpenApiConverter.upgradeDocument(typia.assert<
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument
+      | OpenApiV3_1.IDocument
+      | OpenApiV3_2.IDocument
+      | OpenApi.IDocument
+    >(props.document)),
+    config: props.config,
+  });
+}

package/src/functional/assertMcpController.ts

@@ -1,44 +1,47 @@
-import type { IMcpLlmApplication, IMcpTool } from "@samchon/openapi";
-
-import { McpLlm } from "@samchon/openapi";
-import typia from "typia";
-
-import type { IAgenticaController } from "../structures/IAgenticaController";
-
-/**
- * Create an MCP controller with type assertion.
- *
- * Create an {@link IAgenticaController.IMcp} instance which represents
- * an MCP (Model Context Protocol) controller with LLM function calling
- * schemas and client connection.
- *
- * @param props Properties to create the MCP controller
- * @param props.name Name of the MCP implementation.
- * @param props.client Client connection to the MCP implementation.
- * @param props.model Model schema of the LLM function calling.
- * @param props.options Options to create the MCP controller.
- * @returns MCP LLM application instance
- * @author sunrabbit123
- */
-export async function assertMcpController(props: {
-  name: string;
-  client: IAgenticaController.IMcp["client"];
-  config?: Partial<IMcpLlmApplication.IConfig>;
-}): Promise<IAgenticaController.IMcp> {
-  // for peerDependencies
-  const { ListToolsResultSchema } = await import("@modelcontextprotocol/sdk/types.js");
-
-  // get list of tools
-  const { tools } = await props.client.request({ method: "tools/list" }, ListToolsResultSchema);
-
-  const application: IMcpLlmApplication = McpLlm.application({
-    tools: typia.assert<Array<IMcpTool>>(tools),
-  });
-
-  return {
-    protocol: "mcp",
-    name: props.name,
-    client: props.client,
-    application,
-  };
-}
+import type { ILlmApplication } from "typia";
+
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+import type { IMcpTool } from "../structures/IMcpTool";
+
+import { createMcpLlmApplication } from "./createMcpLlmApplication";
+
+/**
+ * Create an MCP controller with type assertion.
+ *
+ * Create an {@link IAgenticaController.IMcp} instance which represents
+ * an MCP (Model Context Protocol) controller with LLM function calling
+ * schemas and client connection.
+ *
+ * @param props Properties to create the MCP controller
+ * @param props.name Name of the MCP implementation.
+ * @param props.client Client connection to the MCP implementation.
+ * @param props.model Model schema of the LLM function calling.
+ * @param props.options Options to create the MCP controller.
+ * @returns MCP LLM application instance
+ * @author sunrabbit123
+ */
+export async function assertMcpController(props: {
+  name: string;
+  client: IAgenticaController.IMcp["client"];
+  config?: Partial<ILlmApplication.IConfig>;
+}): Promise<IAgenticaController.IMcp> {
+  // for peerDependencies
+  const { ListToolsResultSchema } = await import("@modelcontextprotocol/sdk/types.js");
+
+  // get list of tools
+  const { tools } = await props.client.request({ method: "tools/list" }, ListToolsResultSchema);
+
+  const application: ILlmApplication
+    = createMcpLlmApplication({
+      tools: typia.assert<Array<IMcpTool>>(tools),
+      config: props.config,
+    });
+  return {
+    protocol: "mcp",
+    name: props.name,
+    client: props.client,
+    application,
+  };
+}

package/src/functional/createMcpLlmApplication.ts

@@ -0,0 +1,72 @@
+import type { IJsonSchemaTransformError, IResult } from "@typia/interface";
+import type { ILlmApplication, ILlmFunction, ILlmSchema, OpenApi } from "typia";
+
+import { LlmJson, LlmSchemaConverter, OpenApiConverter, OpenApiTypeChecker } from "@typia/utils";
+
+import type { IMcpTool } from "../structures/IMcpTool";
+
+export function createMcpLlmApplication(props: {
+  tools: Array<IMcpTool>;
+  config?: Partial<ILlmApplication.IConfig> | undefined;
+}): ILlmApplication {
+  const config: ILlmSchema.IConfig = LlmSchemaConverter.getConfig(props.config);
+  const functions: ILlmFunction[] = [];
+
+  props.tools.forEach((tool, i) => {
+    // CONVERT TO EMENDED OPENAPI V3.1 SPECIFICATION
+    const components: OpenApi.IComponents
+      = OpenApiConverter.upgradeComponents({
+        schemas: tool.inputSchema.$defs,
+      });
+    const schema: OpenApi.IJsonSchema = OpenApiConverter.upgradeSchema({
+      components: {
+        schemas: tool.inputSchema.$defs,
+      },
+      schema: tool.inputSchema,
+    });
+    if (components.schemas !== undefined) {
+      const visited: Set<string> = new Set<string>();
+      OpenApiTypeChecker.visit({
+        closure: (schema: OpenApi.IJsonSchema) => {
+          if (OpenApiTypeChecker.isReference(schema)) {
+            visited.add(schema.$ref.split("/").pop()!);
+          }
+        },
+        components,
+        schema,
+      });
+      components.schemas = Object.fromEntries(
+        Object.entries(components.schemas).filter(([key]) =>
+          visited.has(key),
+        ),
+      );
+    }
+
+    // CONVERT TO LLM PARAMETERS
+    const parameters: IResult<ILlmSchema.IParameters, IJsonSchemaTransformError>
+      = LlmSchemaConverter.parameters({
+        config,
+        components,
+        schema: schema as
+        | OpenApi.IJsonSchema.IObject
+        | OpenApi.IJsonSchema.IReference,
+        accessor: `$input.tools[${i}].inputSchema`,
+      });
+    if (parameters.success === false) {
+      return;
+    }
+
+    functions.push({
+      name: tool.name,
+      parameters: parameters.value,
+      description: tool.description,
+      validate: LlmJson.validate(parameters.value),
+      parse: str => LlmJson.parse(str, parameters.value),
+      coerce: input => LlmJson.coerce(input, parameters.value),
+    });
+  });
+  return {
+    functions,
+    config: config as ILlmApplication.IConfig,
+  };
+}

package/src/functional/index.ts

@@ -1,7 +1,7 @@
-export * from "./assertHttpController";
-export * from "./assertHttpLlmApplication"; // deprecated
-export * from "./assertMcpController";
-export * from "./validateHttpController"; // deprecated
-
-export * from "./validateHttpLlmApplication";
-export * from "./validateMcpController";
+export * from "./assertHttpController";
+export * from "./assertHttpLlmApplication"; // deprecated
+export * from "./assertMcpController";
+export * from "./validateHttpController"; // deprecated
+
+export * from "./validateHttpLlmApplication";
+export * from "./validateMcpController";