@agentica/core 0.22.0 → 0.23.0

package/src/functional/assertHttpLlmApplication.ts

@@ -28,6 +28,7 @@ import typia from "typia";
  * @returns  HTTP LLM application instance
  * @throws {@link TypeGuardError} when the given document is invalid
  * @author Samchon
+ * @deprecated Use {@link assertHttpController} instead.
  */
 export function assertHttpLlmApplication<
   Model extends ILlmSchema.Model,

package/src/functional/assertMcpController.ts

@@ -19,7 +19,7 @@ import type { IAgenticaController } from "../structures/IAgenticaController";
  * @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 Samchon
+ * @author sunrabbit123
  */
 export async function assertMcpController<Model extends ILlmSchema.Model>(props: {
   name: string;
@@ -42,7 +42,6 @@ export async function assertMcpController<Model extends ILlmSchema.Model>(props:
     protocol: "mcp",
     name: props.name,
     client: props.client,
-
     application,
   };
 }

package/src/functional/validateHttpController.ts

@@ -0,0 +1,118 @@
+import type { IHttpConnection, IHttpLlmApplication, IHttpLlmFunction, IHttpResponse, ILlmSchema, IValidation, 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 validation.
+ *
+ * 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 `validateHttpController` function
+ * supports every version of Swagger/OpenAPI specification, there can
+ * be a type error in the given document. In that case, the function
+ * will return {@link IValidation.IFailure} instance with detailed
+ * type error tracing information.
+ *
+ * @param props Properties to create the HTTP controller instance
+ * @returns Validation result of the HTTP controller composition
+ * @author Samchon
+ */
+export function validateHttpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  /**
+   * Name of the controller.
+   */
+  name: string;
+
+  /**
+   * Target LLM model.
+   */
+  model: Model;
+
+  /**
+   * 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.
+   */
+  options?: Partial<IHttpLlmApplication.IOptions<Model>>;
+
+  /**
+   * 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<Model>;
+
+    /**
+     * Function schema.
+     */
+    function: IHttpLlmFunction<Model>;
+
+    /**
+     * 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>;
+}): IValidation<IAgenticaController.IHttp<Model>> {
+  const inspect = typia.validate<
+    | SwaggerV2.IDocument
+    | OpenApiV3.IDocument
+    | OpenApiV3_1.IDocument
+    | OpenApi.IDocument
+  >(props.document);
+  if (inspect.success === false) {
+    return inspect;
+  }
+  return {
+    success: true,
+    data: {
+      protocol: "http",
+      name: props.name,
+      application: HttpLlm.application({
+        model: props.model,
+        document: OpenApi.convert(inspect.data),
+        options: props.options,
+      }),
+      execute: props.execute,
+      connection: props.connection,
+    },
+  };
+}

package/src/functional/validateHttpLlmApplication.ts

@@ -29,6 +29,7 @@ import typia from "typia";
  * @param props Properties to create the HTTP LLM application instance
  * @returns Validation result of the HTTP LLM application composition
  * @author Samchon
+ * @deprecated Use {@link validateHttpController} instead.
  */
 export function validateHttpLlmApplication<
   Model extends ILlmSchema.Model,
@@ -67,7 +68,6 @@ export function validateHttpLlmApplication<
   if (inspect.success === false) {
     return inspect;
   }
-
   return {
     success: true,
     data: HttpLlm.application({

package/src/functional/validateMcpController.ts

@@ -0,0 +1,56 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.d.ts";
+import type { ILlmSchema, IMcpLlmApplication, IMcpTool, IValidation } from "@samchon/openapi";
+
+import { McpLlm } from "@samchon/openapi";
+import typia from "typia";
+
+import type { IAgenticaController } from "../structures/IAgenticaController";
+
+/**
+ * Create an MCP controller with type validation.
+ *
+ * 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 SunRabbit
+ */
+export async function validateMcpController<
+  Model extends ILlmSchema.Model,
+>(props: {
+  name: string;
+  client: Client;
+  model: Model;
+  options?: Partial<IMcpLlmApplication.IOptions<Model>>;
+}): Promise<IValidation<IAgenticaController.IMcp<Model>>> {
+  // 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 inspect = typia.validate<Array<IMcpTool>>(tools);
+  if (inspect.success === false) {
+    return inspect;
+  }
+
+  const application: IMcpLlmApplication<Model> = McpLlm.application<Model>({
+    model: props.model,
+    tools: typia.assert<Array<IMcpTool>>(tools),
+  });
+
+  return {
+    success: true,
+    data: {
+      protocol: "mcp",
+      name: props.name,
+      client: props.client,
+      application,
+    },
+  };
+}

package/src/index.ts

@@ -22,9 +22,12 @@ export * from "./events/MicroAgenticaEvent";
 
 export * as factory from "./factory";
 
+export * from "./functional/assertHttpController";
 export * from "./functional/assertHttpLlmApplication";
 export * from "./functional/assertMcpController";
+export * from "./functional/validateHttpController";
 export * from "./functional/validateHttpLlmApplication";
+export * from "./functional/validateMcpController";
 // @TODO: implement validateMcpLlmApplication
 
 export * from "./histories/AgenticaCancelHistory";