@typia/utils 12.0.0-dev.20260312 → 12.0.0-dev.20260312-3

package/src/http/HttpLlm.ts

@@ -1,166 +1,166 @@
-import {
-  IHttpConnection,
-  IHttpLlmApplication,
-  IHttpLlmController,
-  IHttpLlmFunction,
-  IHttpMigrateApplication,
-  IHttpResponse,
-  OpenApi,
-  OpenApiV3,
-  OpenApiV3_1,
-  SwaggerV2,
-} from "@typia/interface";
-
-import { HttpMigration } from "./HttpMigration";
-import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
-import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
-
-/**
- * LLM function calling utilities for OpenAPI documents.
- *
- * `HttpLlm` converts OpenAPI documents into LLM function calling applications
- * and executes them. Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0,
- * 3.1) through automatic conversion to {@link OpenApi} format.
- *
- * Main functions:
- *
- * - {@link controller}: Create {@link IHttpLlmController} from OpenAPI document
- * - {@link application}: Convert OpenAPI document to {@link IHttpLlmApplication}
- * - {@link execute}: Call an LLM function and return the response body
- * - {@link propagate}: Call an LLM function and return full HTTP response
- * - {@link mergeParameters}: Merge LLM-filled and human-filled parameters
- *
- * Typical workflow:
- *
- * 1. Load OpenAPI document (JSON/YAML)
- * 2. Call `HttpLlm.application()` to get function schemas
- * 3. Send function schemas to LLM for function selection
- * 4. Call `HttpLlm.execute()` with LLM's chosen function and arguments
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export namespace HttpLlm {
-  /* -----------------------------------------------------------
-    COMPOSERS
-  ----------------------------------------------------------- */
-  /**
-   * Create HTTP LLM controller from OpenAPI document.
-   *
-   * Composes {@link IHttpLlmController} from OpenAPI document with connection
-   * info. The controller can be used with {@link registerMcpControllers} to
-   * register all API operations as MCP tools at once.
-   *
-   * @param props Controller properties
-   * @returns HTTP LLM controller
-   */
-  export const controller = (props: {
-    /** Identifier name of the controller. */
-    name: string;
-
-    /** OpenAPI document to convert. */
-    document:
-      | OpenApi.IDocument
-      | SwaggerV2.IDocument
-      | OpenApiV3.IDocument
-      | OpenApiV3_1.IDocument;
-
-    /** Connection to the API server. */
-    connection: IHttpConnection;
-
-    /** LLM schema conversion configuration. */
-    config?: Partial<IHttpLlmApplication.IConfig>;
-
-    /**
-     * Custom executor of the API function.
-     *
-     * Default executor is {@link HttpLlm.execute} function.
-     */
-    execute?: IHttpLlmController["execute"];
-  }): IHttpLlmController => ({
-    protocol: "http",
-    name: props.name,
-    application: application({
-      document: props.document,
-      config: props.config,
-    }),
-    connection: props.connection,
-    execute: props.execute,
-  });
-
-  /**
-   * Convert OpenAPI document to LLM function calling application.
-   *
-   * Converts API operations to LLM-callable functions.
-   *
-   * @param props Composition properties
-   * @returns LLM function calling application
-   */
-  export const application = (props: {
-    /** OpenAPI document to convert. */
-    document:
-      | OpenApi.IDocument
-      | SwaggerV2.IDocument
-      | OpenApiV3.IDocument
-      | OpenApiV3_1.IDocument;
-
-    /** LLM schema conversion configuration. */
-    config?: Partial<IHttpLlmApplication.IConfig>;
-  }): IHttpLlmApplication => {
-    // MIGRATE
-    const migrate: IHttpMigrateApplication = HttpMigration.application(
-      props.document,
-    );
-    return HttpLlmApplicationComposer.application({
-      migrate,
-      config: {
-        strict: props.config?.strict ?? false,
-        maxLength: props.config?.maxLength ?? 64,
-        equals: props.config?.equals ?? false,
-      },
-    });
-  };
-
-  /* -----------------------------------------------------------
-    FETCHERS
-  ----------------------------------------------------------- */
-  /** Properties for LLM function call. */
-  export interface IFetchProps {
-    /** LLM function calling application. */
-    application: IHttpLlmApplication;
-
-    /** Function to call. */
-    function: IHttpLlmFunction;
-
-    /** HTTP connection info. */
-    connection: IHttpConnection;
-
-    /** Function arguments. */
-    input: object;
-  }
-
-  /**
-   * Execute LLM function call.
-   *
-   * Calls API endpoint and returns response body. Throws {@link HttpError} on
-   * non-2xx status.
-   *
-   * @param props Function call properties
-   * @returns Response body
-   * @throws HttpError on non-2xx status
-   */
-  export const execute = (props: IFetchProps): Promise<unknown> =>
-    HttpLlmFunctionFetcher.execute(props);
-
-  /**
-   * Propagate LLM function call.
-   *
-   * Calls API endpoint and returns full response including non-2xx. Use when
-   * you need to handle error responses yourself.
-   *
-   * @param props Function call properties
-   * @returns Full HTTP response
-   * @throws Error only on connection failure
-   */
-  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
-    HttpLlmFunctionFetcher.propagate(props);
-}
+import {
+  IHttpConnection,
+  IHttpLlmApplication,
+  IHttpLlmController,
+  IHttpLlmFunction,
+  IHttpMigrateApplication,
+  IHttpResponse,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  SwaggerV2,
+} from "@typia/interface";
+
+import { HttpMigration } from "./HttpMigration";
+import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
+import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
+
+/**
+ * LLM function calling utilities for OpenAPI documents.
+ *
+ * `HttpLlm` converts OpenAPI documents into LLM function calling applications
+ * and executes them. Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0,
+ * 3.1) through automatic conversion to {@link OpenApi} format.
+ *
+ * Main functions:
+ *
+ * - {@link controller}: Create {@link IHttpLlmController} from OpenAPI document
+ * - {@link application}: Convert OpenAPI document to {@link IHttpLlmApplication}
+ * - {@link execute}: Call an LLM function and return the response body
+ * - {@link propagate}: Call an LLM function and return full HTTP response
+ * - {@link mergeParameters}: Merge LLM-filled and human-filled parameters
+ *
+ * Typical workflow:
+ *
+ * 1. Load OpenAPI document (JSON/YAML)
+ * 2. Call `HttpLlm.application()` to get function schemas
+ * 3. Send function schemas to LLM for function selection
+ * 4. Call `HttpLlm.execute()` with LLM's chosen function and arguments
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace HttpLlm {
+  /* -----------------------------------------------------------
+    COMPOSERS
+  ----------------------------------------------------------- */
+  /**
+   * Create HTTP LLM controller from OpenAPI document.
+   *
+   * Composes {@link IHttpLlmController} from OpenAPI document with connection
+   * info. The controller can be used with {@link registerMcpControllers} to
+   * register all API operations as MCP tools at once.
+   *
+   * @param props Controller properties
+   * @returns HTTP LLM controller
+   */
+  export const controller = (props: {
+    /** Identifier name of the controller. */
+    name: string;
+
+    /** OpenAPI document to convert. */
+    document:
+      | OpenApi.IDocument
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument
+      | OpenApiV3_1.IDocument;
+
+    /** Connection to the API server. */
+    connection: IHttpConnection;
+
+    /** LLM schema conversion configuration. */
+    config?: Partial<IHttpLlmApplication.IConfig>;
+
+    /**
+     * Custom executor of the API function.
+     *
+     * Default executor is {@link HttpLlm.execute} function.
+     */
+    execute?: IHttpLlmController["execute"];
+  }): IHttpLlmController => ({
+    protocol: "http",
+    name: props.name,
+    application: application({
+      document: props.document,
+      config: props.config,
+    }),
+    connection: props.connection,
+    execute: props.execute,
+  });
+
+  /**
+   * Convert OpenAPI document to LLM function calling application.
+   *
+   * Converts API operations to LLM-callable functions.
+   *
+   * @param props Composition properties
+   * @returns LLM function calling application
+   */
+  export const application = (props: {
+    /** OpenAPI document to convert. */
+    document:
+      | OpenApi.IDocument
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument
+      | OpenApiV3_1.IDocument;
+
+    /** LLM schema conversion configuration. */
+    config?: Partial<IHttpLlmApplication.IConfig>;
+  }): IHttpLlmApplication => {
+    // MIGRATE
+    const migrate: IHttpMigrateApplication = HttpMigration.application(
+      props.document,
+    );
+    return HttpLlmApplicationComposer.application({
+      migrate,
+      config: {
+        strict: props.config?.strict ?? false,
+        maxLength: props.config?.maxLength ?? 64,
+        equals: props.config?.equals ?? false,
+      },
+    });
+  };
+
+  /* -----------------------------------------------------------
+    FETCHERS
+  ----------------------------------------------------------- */
+  /** Properties for LLM function call. */
+  export interface IFetchProps {
+    /** LLM function calling application. */
+    application: IHttpLlmApplication;
+
+    /** Function to call. */
+    function: IHttpLlmFunction;
+
+    /** HTTP connection info. */
+    connection: IHttpConnection;
+
+    /** Function arguments. */
+    input: object;
+  }
+
+  /**
+   * Execute LLM function call.
+   *
+   * Calls API endpoint and returns response body. Throws {@link HttpError} on
+   * non-2xx status.
+   *
+   * @param props Function call properties
+   * @returns Response body
+   * @throws HttpError on non-2xx status
+   */
+  export const execute = (props: IFetchProps): Promise<unknown> =>
+    HttpLlmFunctionFetcher.execute(props);
+
+  /**
+   * Propagate LLM function call.
+   *
+   * Calls API endpoint and returns full response including non-2xx. Use when
+   * you need to handle error responses yourself.
+   *
+   * @param props Function call properties
+   * @returns Full HTTP response
+   * @throws Error only on connection failure
+   */
+  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
+    HttpLlmFunctionFetcher.propagate(props);
+}