@typia/utils 12.0.0-dev.20260225

package/src/http/HttpLlm.ts

@@ -0,0 +1,210 @@
+import {
+  IHttpConnection,
+  IHttpLlmApplication,
+  IHttpLlmController,
+  IHttpLlmFunction,
+  IHttpMigrateApplication,
+  IHttpResponse,
+  ILlmFunction,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  SwaggerV2,
+} from "@typia/interface";
+
+import { HttpMigration } from "./HttpMigration";
+import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
+import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
+import { LlmDataMerger } from "./internal/LlmDataMerger";
+
+/**
+ * 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. Use
+   * {@link mergeParameters} if `separate` option is configured.
+   *
+   * @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: {
+        reference: props.config?.reference ?? true,
+        strict: props.config?.strict ?? false,
+        separate: props.config?.separate ?? null,
+        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);
+
+  /* -----------------------------------------------------------
+    MERGERS
+  ----------------------------------------------------------- */
+  /** Properties for parameter merging. */
+  export interface IMergeProps {
+    /** Target function metadata. */
+    function: ILlmFunction;
+
+    /** LLM-provided arguments. */
+    llm: object | null;
+
+    /** Human-provided arguments. */
+    human: object | null;
+  }
+
+  /**
+   * Merge separated parameters.
+   *
+   * Combines human and LLM parameters when `separate` option was used. Throws
+   * error if `separate` was not configured.
+   *
+   * @param props Merge properties
+   * @returns Merged parameters
+   */
+  export const mergeParameters = (props: IMergeProps): object =>
+    LlmDataMerger.parameters(props);
+
+  /**
+   * Merge two values.
+   *
+   * Objects are merged at property level. Primitives return `y ?? x`.
+   *
+   * @param x First value
+   * @param y Second value (preferred)
+   * @returns Merged value
+   */
+  export const mergeValue = (x: unknown, y: unknown): unknown =>
+    LlmDataMerger.value(x, y);
+}

package/src/http/HttpMigration.ts

@@ -0,0 +1,92 @@
+import {
+  IHttpConnection,
+  IHttpMigrateApplication,
+  IHttpMigrateRoute,
+  IHttpResponse,
+  OpenApi,
+  OpenApiV3,
+  OpenApiV3_1,
+  SwaggerV2,
+} from "@typia/interface";
+
+import { OpenApiConverter } from "../converters/OpenApiConverter";
+import { HttpMigrateApplicationComposer } from "./internal/HttpMigrateApplicationComposer";
+import { HttpMigrateRouteFetcher } from "./internal/HttpMigrateRouteFetcher";
+
+/**
+ * OpenAPI to HTTP migration utilities.
+ *
+ * `HttpMigration` converts OpenAPI documents into executable HTTP routes
+ * ({@link IHttpMigrateApplication}). Unlike {@link HttpLlm} which targets LLM
+ * function calling, this focuses on SDK/client code generation.
+ *
+ * Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0, 3.1) through
+ * automatic conversion to normalized {@link OpenApi} format.
+ *
+ * Main functions:
+ *
+ * - {@link application}: Convert OpenAPI document to
+ *   {@link IHttpMigrateApplication}
+ * - {@link execute}: Call a route and return response body
+ * - {@link propagate}: Call a route and return full HTTP response (including
+ *   non-2xx)
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace HttpMigration {
+  /**
+   * Convert OpenAPI document to migration application.
+   *
+   * @param document OpenAPI document (any version)
+   * @returns Migration application with callable routes
+   */
+  export const application = (
+    document:
+      | OpenApi.IDocument
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument
+      | OpenApiV3_1.IDocument,
+  ): IHttpMigrateApplication =>
+    HttpMigrateApplicationComposer.compose(
+      OpenApiConverter.upgradeDocument(document),
+    );
+
+  /**
+   * Execute HTTP route.
+   *
+   * @param props Fetch properties
+   * @returns Response body
+   * @throws HttpError on non-2xx status
+   */
+  export const execute = (props: IFetchProps): Promise<unknown> =>
+    HttpMigrateRouteFetcher.execute(props);
+
+  /**
+   * Execute HTTP route and return full response.
+   *
+   * @param props Fetch properties
+   * @returns Full HTTP response including non-2xx
+   */
+  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
+    HttpMigrateRouteFetcher.propagate(props);
+
+  /** Properties for HTTP route execution. */
+  export interface IFetchProps {
+    /** HTTP connection info. */
+    connection: IHttpConnection;
+
+    /** Route to execute. */
+    route: IHttpMigrateRoute;
+
+    /** Path parameters. */
+    parameters:
+      | Array<string | number | boolean | bigint | null>
+      | Record<string, string | number | boolean | bigint | null>;
+
+    /** Query parameters. */
+    query?: object | undefined;
+
+    /** Request body. */
+    body?: object | undefined;
+  }
+}

package/src/http/index.ts

@@ -0,0 +1,3 @@
+export * from "./HttpError";
+export * from "./HttpLlm";
+export * from "./HttpMigration";

package/src/http/internal/HttpLlmApplicationComposer.ts

@@ -0,0 +1,308 @@
+import {
+  IHttpLlmApplication,
+  IHttpLlmFunction,
+  IHttpMigrateApplication,
+  IHttpMigrateRoute,
+  IJsonSchemaTransformError,
+  ILlmSchema,
+  IResult,
+  OpenApi,
+} from "@typia/interface";
+
+import { LlmSchemaConverter } from "../../converters";
+import { OpenApiValidator } from "../../validators/OpenApiValidator";
+
+export namespace HttpLlmApplicationComposer {
+  export const application = (props: {
+    migrate: IHttpMigrateApplication;
+    config?: Partial<IHttpLlmApplication.IConfig>;
+  }): IHttpLlmApplication => {
+    // COMPOSE FUNCTIONS
+    const config: IHttpLlmApplication.IConfig = {
+      separate: props.config?.separate ?? null,
+      maxLength: props.config?.maxLength ?? 64,
+      equals: props.config?.equals ?? false,
+      reference: props.config?.reference ?? true,
+      strict: props.config?.strict ?? false,
+    };
+    const errors: IHttpLlmApplication.IError[] = props.migrate.errors
+      .filter((e) => e.operation()["x-samchon-human"] !== true)
+      .map((e) => ({
+        method: e.method,
+        path: e.path,
+        messages: e.messages,
+        operation: () => e.operation(),
+        route: () => undefined,
+      }));
+    const functions: IHttpLlmFunction[] = props.migrate.routes
+      .filter((e) => e.operation()["x-samchon-human"] !== true)
+      .map((route, i) => {
+        if (route.method === "head") {
+          errors.push({
+            method: route.method,
+            path: route.path,
+            messages: ["HEAD method is not supported in the LLM application."],
+            operation: () => route.operation(),
+            route: () => route as any as IHttpMigrateRoute,
+          });
+          return null;
+        } else if (
+          route.body?.type === "multipart/form-data" ||
+          route.success?.type === "multipart/form-data"
+        ) {
+          errors.push({
+            method: route.method,
+            path: route.path,
+            messages: [
+              `The "multipart/form-data" content type is not supported in the LLM application.`,
+            ],
+            operation: () => route.operation(),
+            route: () => route as any as IHttpMigrateRoute,
+          });
+          return null;
+        }
+        const localErrors: string[] = [];
+        const func: IHttpLlmFunction | null = composeFunction({
+          components: props.migrate.document().components,
+          config,
+          route,
+          errors: localErrors,
+          index: i,
+        });
+        if (func === null)
+          errors.push({
+            method: route.method,
+            path: route.path,
+            messages: localErrors,
+            operation: () => route.operation(),
+            route: () => route as any as IHttpMigrateRoute,
+          });
+        return func;
+      })
+      .filter((v): v is IHttpLlmFunction => v !== null);
+
+    const app: IHttpLlmApplication = {
+      config,
+      functions,
+      errors,
+    };
+    shorten(app, props.config?.maxLength ?? 64);
+    return app;
+  };
+
+  const composeFunction = (props: {
+    components: OpenApi.IComponents;
+    route: IHttpMigrateRoute;
+    config: IHttpLlmApplication.IConfig;
+    errors: string[];
+    index: number;
+  }): IHttpLlmFunction | null => {
+    // METADATA
+    const endpoint: string = `$input.paths[${JSON.stringify(props.route.path)}][${JSON.stringify(props.route.method)}]`;
+    const operation: OpenApi.IOperation = props.route.operation();
+    const description: [string | undefined, number] = (() => {
+      if (!operation.summary?.length || !operation.description?.length)
+        return [
+          operation.summary || operation.description,
+          operation.summary?.length ?? operation.description?.length ?? 0,
+        ];
+      const summary: string = operation.summary.endsWith(".")
+        ? operation.summary.slice(0, -1)
+        : operation.summary;
+      const final: string = operation.description.startsWith(summary)
+        ? operation.description
+        : summary + ".\n\n" + operation.description;
+      return [final, final.length];
+    })();
+    if (description[1] > 1_024) {
+      props.errors.push(
+        `The description of the function is too long (must be equal or less than 1,024 characters, but ${description[1].toLocaleString()} length).`,
+      );
+    }
+
+    // FUNCTION NAME
+    const name: string = emend(props.route.accessor.join("_"));
+    const isNameVariable: boolean = /^[a-zA-Z0-9_-]+$/.test(name);
+    const isNameStartsWithNumber: boolean = /^[0-9]/.test(name[0] ?? "");
+    if (isNameVariable === false)
+      props.errors.push(
+        `Elements of path (separated by '/') must be composed with alphabets, numbers, underscores, and hyphens`,
+      );
+
+    //----
+    // CONSTRUCT SCHEMAS
+    //----
+    // PARAMETERS
+    const parameters: OpenApi.IJsonSchema.IObject = {
+      type: "object",
+      properties: Object.fromEntries([
+        ...props.route.parameters.map(
+          (s) =>
+            [
+              s.key,
+              {
+                ...s.schema,
+                description: s.parameter().description ?? s.schema.description,
+              },
+            ] as const,
+        ),
+        ...(props.route.query
+          ? [
+              [
+                props.route.query.key,
+                {
+                  ...props.route.query.schema,
+                  title:
+                    props.route.query.title() ?? props.route.query.schema.title,
+                  description:
+                    props.route.query.description() ??
+                    props.route.query.schema.description,
+                },
+              ] as const,
+            ]
+          : []),
+        ...(props.route.body
+          ? [
+              [
+                props.route.body.key,
+                {
+                  ...props.route.body.schema,
+                  description:
+                    props.route.body.description() ??
+                    props.route.body.schema.description,
+                },
+              ] as const,
+            ]
+          : []),
+      ]),
+    };
+    parameters.required = Object.keys(parameters.properties ?? {});
+
+    const llmParameters: IResult<
+      ILlmSchema.IParameters,
+      IJsonSchemaTransformError
+    > = LlmSchemaConverter.parameters({
+      config: props.config,
+      components: props.components,
+      schema: parameters,
+      accessor: `${endpoint}.parameters`,
+    });
+
+    // RETURN VALUE
+    const output: IResult<ILlmSchema, IJsonSchemaTransformError> | undefined =
+      props.route.success
+        ? LlmSchemaConverter.schema({
+            config: props.config,
+            components: props.components,
+            schema: props.route.success.schema,
+            accessor: `${endpoint}.responses[${JSON.stringify(props.route.success.status)}][${JSON.stringify(props.route.success.type)}].schema`,
+            $defs: llmParameters.success ? llmParameters.value.$defs : {},
+          })
+        : undefined;
+
+    //----
+    // CONVERSION
+    //----
+    if (
+      output?.success === false ||
+      llmParameters.success === false ||
+      isNameVariable === false ||
+      isNameStartsWithNumber === true ||
+      description[1] > 1_024
+    ) {
+      if (output?.success === false)
+        props.errors.push(
+          ...output.error.reasons.map((r) => `${r.accessor}: ${r.message}`),
+        );
+      if (llmParameters.success === false)
+        props.errors.push(
+          ...llmParameters.error.reasons.map((r) => {
+            const accessor: string = r.accessor.replace(
+              `parameters.properties["body"]`,
+              `requestBody.content[${JSON.stringify(props.route.body?.type ?? "application/json")}].schema`,
+            );
+            return `${accessor}: ${r.message}`;
+          }),
+        );
+      return null;
+    }
+    return {
+      method: props.route.method as "get",
+      path: props.route.path,
+      name,
+      parameters: llmParameters.value,
+      separated: props.config.separate
+        ? LlmSchemaConverter.separate({
+            predicate: props.config.separate,
+            parameters: llmParameters.value,
+            equals: props.config.equals ?? false,
+          })
+        : undefined,
+      output: output?.value,
+      description: description[0],
+      deprecated: operation.deprecated,
+      tags: operation.tags,
+      validate: OpenApiValidator.create({
+        components: props.components,
+        schema: parameters,
+        required: true,
+        equals: props.config.equals ?? false,
+      }),
+      route: () => props.route as any,
+      operation: () => props.route.operation(),
+    };
+  };
+
+  export const shorten = (
+    app: IHttpLlmApplication,
+    limit: number = 64,
+  ): void => {
+    const dictionary: Set<string> = new Set();
+    const longFunctions: IHttpLlmFunction[] = [];
+    for (const func of app.functions) {
+      dictionary.add(func.name);
+      if (func.name.length > limit) {
+        longFunctions.push(func);
+      }
+    }
+    if (longFunctions.length === 0) return;
+
+    let index: number = 0;
+    for (const func of longFunctions) {
+      let success: boolean = false;
+      let rename = (str: string) => {
+        dictionary.delete(func.name);
+        dictionary.add(str);
+        func.name = str;
+        success = true;
+      };
+      for (let i: number = 1; i < func.route().accessor.length; ++i) {
+        const shortName: string = func.route().accessor.slice(i).join("_");
+        if (shortName.length > limit - 8) continue;
+        else if (dictionary.has(shortName) === false) rename(shortName);
+        else {
+          const newName: string = `_${index}_${shortName}`;
+          if (dictionary.has(newName) === true) continue;
+          rename(newName);
+          ++index;
+        }
+        break;
+      }
+      if (success === false) rename(randomFormatUuid());
+    }
+  };
+}
+
+const randomFormatUuid = (): string =>
+  "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+
+const emend = (str: string): string => {
+  for (const ch of FORBIDDEN) str = str.split(ch).join("_");
+  return str;
+};
+
+const FORBIDDEN = ["$", "%", "."];

package/src/http/internal/HttpLlmFunctionFetcher.ts

@@ -0,0 +1,37 @@
+import { IHttpMigrateRoute, IHttpResponse } from "@typia/interface";
+
+import type { HttpLlm } from "../HttpLlm";
+import type { HttpMigration } from "../HttpMigration";
+import { HttpMigrateRouteFetcher } from "./HttpMigrateRouteFetcher";
+
+export namespace HttpLlmFunctionFetcher {
+  export const execute = (props: HttpLlm.IFetchProps): Promise<unknown> =>
+    HttpMigrateRouteFetcher.execute(getFetchArguments("execute", props));
+
+  export const propagate = (
+    props: HttpLlm.IFetchProps,
+  ): Promise<IHttpResponse> =>
+    HttpMigrateRouteFetcher.propagate(getFetchArguments("propagate", props));
+
+  const getFetchArguments = (
+    from: string,
+    props: HttpLlm.IFetchProps,
+  ): HttpMigration.IFetchProps => {
+    const route: IHttpMigrateRoute = props.function.route();
+    const input: Record<string, any> = props.input;
+    const valid: boolean = typeof input === "object" && input !== null;
+    if (valid === false)
+      throw new Error(
+        `Error on HttpLlmFunctionFetcher.${from}(): keyworded arguments must be an object`,
+      );
+    return {
+      connection: props.connection,
+      route,
+      parameters: Object.fromEntries(
+        route.parameters.map((p) => [p.key, input[p.key]] as const),
+      ),
+      query: input.query,
+      body: input.body,
+    };
+  };
+}

package/src/http/internal/HttpMigrateApplicationComposer.ts

@@ -0,0 +1,56 @@
+import {
+  IHttpMigrateApplication,
+  IHttpMigrateRoute,
+  OpenApi,
+} from "@typia/interface";
+
+import { EndpointUtil } from "../../utils/internal/EndpointUtil";
+import { HttpMigrateRouteAccessor } from "./HttpMigrateRouteAccessor";
+import { HttpMigrateRouteComposer } from "./HttpMigrateRouteComposer";
+
+export namespace HttpMigrateApplicationComposer {
+  export const compose = (
+    document: OpenApi.IDocument,
+  ): IHttpMigrateApplication => {
+    const errors: IHttpMigrateApplication.IError[] = [];
+    const entire: Array<IHttpMigrateRoute | null> = Object.entries({
+      ...(document.paths ?? {}),
+      ...(document.webhooks ?? {}),
+    })
+      .map(([path, collection]) =>
+        (["head", "get", "post", "put", "patch", "delete"] as const)
+          .filter((method) => collection[method] !== undefined)
+          .map((method) => {
+            const operation: OpenApi.IOperation = collection[method]!;
+            const migrated: IHttpMigrateRoute | string[] =
+              HttpMigrateRouteComposer.compose({
+                document,
+                method,
+                path,
+                emendedPath: EndpointUtil.reJoinWithDecimalParameters(path),
+                operation,
+              });
+            if (Array.isArray(migrated)) {
+              errors.push({
+                method,
+                path,
+                operation: () => operation,
+                messages: migrated,
+              });
+              return null;
+            }
+            return migrated;
+          }),
+      )
+      .flat();
+    const operations: IHttpMigrateRoute[] = entire.filter(
+      (o): o is IHttpMigrateRoute => !!o,
+    );
+    HttpMigrateRouteAccessor.overwrite(operations);
+    return {
+      document: () => document,
+      routes: operations,
+      errors,
+    } satisfies IHttpMigrateApplication as IHttpMigrateApplication;
+  };
+}