@typia/utils 12.0.0-dev.20260306 → 12.0.0-dev.20260307-2

package/src/converters/LlmSchemaConverter.ts

@@ -1,17 +1,14 @@
 import {
   IJsonSchemaAttribute,
   IJsonSchemaTransformError,
-  ILlmFunction,
   ILlmSchema,
   IResult,
   OpenApi,
 } from "@typia/interface";
 
-import { NamingConvention } from "../utils/NamingConvention";
 import { JsonDescriptor } from "../utils/internal/JsonDescriptor";
 import { LlmTypeChecker } from "../validators/LlmTypeChecker";
 import { OpenApiTypeChecker } from "../validators/OpenApiTypeChecker";
-import { OpenApiValidator } from "../validators/OpenApiValidator";
 import { LlmDescriptionInverter } from "./internal/LlmDescriptionInverter";
 import { LlmParametersFinder } from "./internal/LlmParametersComposer";
 import { OpenApiConstraintShifter } from "./internal/OpenApiConstraintShifter";
@@ -28,7 +25,6 @@ import { OpenApiConstraintShifter } from "./internal/OpenApiConstraintShifter";
  *
  * - {@link parameters}: Convert object schema to {@link ILlmSchema.IParameters}
  * - {@link schema}: Convert any schema to {@link ILlmSchema}
- * - {@link separate}: Split parameters into LLM-fillable vs human-required
  * - {@link invert}: Extract constraints from description back to schema
  *
  * Configuration options ({@link ILlmSchema.IConfig}):
@@ -624,279 +620,6 @@ export namespace LlmSchemaConverter {
             }),
     } satisfies OpenApi.IJsonSchema;
   };
-
-  /* -----------------------------------------------------------
-    SEPARATORS
-  ----------------------------------------------------------- */
-  /**
-   * Separate parameters into LLM and human parts.
-   *
-   * Splits parameters based on predicate (human-side if true). Creates separate
-   * schemas for LLM-fillable and human-required fields.
-   *
-   * @param props.parameters Parameters schema to separate
-   * @param props.predicate Returns true for human-side properties
-   * @param props.convention Key naming convention for separated types
-   * @param props.equals Whether to use strict equality validation
-   * @returns Separated LLM and human parameter schemas
-   */
-  export const separate = (props: {
-    parameters: ILlmSchema.IParameters;
-    predicate: (schema: ILlmSchema) => boolean;
-    convention?: (key: string, type: "llm" | "human") => string;
-    equals?: boolean;
-  }): ILlmFunction.ISeparated => {
-    const convention =
-      props.convention ??
-      ((key, type) => `${key}.${NamingConvention.capitalize(type)}`);
-    const [llm, human] = separateObject({
-      predicate: props.predicate,
-      convention,
-      $defs: props.parameters.$defs,
-      schema: props.parameters,
-    });
-    if (llm === null || human === null)
-      return {
-        llm: (llm as ILlmSchema.IParameters | null) ?? {
-          type: "object",
-          properties: {} as Record<string, ILlmSchema>,
-          required: [],
-          additionalProperties: false,
-          $defs: {},
-        },
-        human: human as ILlmSchema.IParameters | null,
-      };
-    const output: ILlmFunction.ISeparated = {
-      llm: {
-        ...llm,
-        $defs: Object.fromEntries(
-          Object.entries(props.parameters.$defs).filter(([key]) =>
-            key.endsWith(".Llm"),
-          ),
-        ),
-        additionalProperties: false,
-      },
-      human: {
-        ...human,
-        $defs: Object.fromEntries(
-          Object.entries(props.parameters.$defs).filter(([key]) =>
-            key.endsWith(".Human"),
-          ),
-        ),
-        additionalProperties: false,
-      },
-    };
-    for (const key of Object.keys(props.parameters.$defs))
-      if (key.endsWith(".Llm") === false && key.endsWith(".Human") === false)
-        delete props.parameters.$defs[key];
-    if (Object.keys(output.llm.properties).length !== 0) {
-      const components: OpenApi.IComponents = {};
-      output.validate = OpenApiValidator.create({
-        components,
-        schema: invert({
-          components,
-          schema: output.llm,
-          $defs: output.llm.$defs,
-        }),
-        required: true,
-        equals: props.equals,
-      });
-    }
-    return output;
-  };
-
-  const separateStation = (props: {
-    predicate: (schema: ILlmSchema) => boolean;
-    convention: (key: string, type: "llm" | "human") => string;
-    $defs: Record<string, ILlmSchema>;
-    schema: ILlmSchema;
-  }): [ILlmSchema | null, ILlmSchema | null] => {
-    if (props.predicate(props.schema) === true) return [null, props.schema];
-    else if (
-      LlmTypeChecker.isUnknown(props.schema) ||
-      LlmTypeChecker.isAnyOf(props.schema)
-    )
-      return [props.schema, null];
-    else if (LlmTypeChecker.isObject(props.schema))
-      return separateObject({
-        predicate: props.predicate,
-        convention: props.convention,
-        $defs: props.$defs,
-        schema: props.schema,
-      });
-    else if (LlmTypeChecker.isArray(props.schema))
-      return separateArray({
-        predicate: props.predicate,
-        convention: props.convention,
-        $defs: props.$defs,
-        schema: props.schema,
-      });
-    else if (LlmTypeChecker.isReference(props.schema))
-      return separateReference({
-        predicate: props.predicate,
-        convention: props.convention,
-        $defs: props.$defs,
-        schema: props.schema,
-      });
-    return [props.schema, null];
-  };
-
-  const separateArray = (props: {
-    predicate: (schema: ILlmSchema) => boolean;
-    convention: (key: string, type: "llm" | "human") => string;
-    $defs: Record<string, ILlmSchema>;
-    schema: ILlmSchema.IArray;
-  }): [ILlmSchema.IArray | null, ILlmSchema.IArray | null] => {
-    const [x, y] = separateStation({
-      predicate: props.predicate,
-      convention: props.convention,
-      $defs: props.$defs,
-      schema: props.schema.items,
-    });
-    return [
-      x !== null
-        ? {
-            ...props.schema,
-            items: x,
-          }
-        : null,
-      y !== null
-        ? {
-            ...props.schema,
-            items: y,
-          }
-        : null,
-    ];
-  };
-
-  const separateObject = (props: {
-    $defs: Record<string, ILlmSchema>;
-    predicate: (schema: ILlmSchema) => boolean;
-    convention: (key: string, type: "llm" | "human") => string;
-    schema: ILlmSchema.IObject;
-  }): [ILlmSchema.IObject | null, ILlmSchema.IObject | null] => {
-    // EMPTY OBJECT
-    if (
-      Object.keys(props.schema.properties ?? {}).length === 0 &&
-      !!props.schema.additionalProperties === false
-    )
-      return [props.schema, null];
-
-    const llm = {
-      ...props.schema,
-      properties: {} as Record<string, ILlmSchema>,
-      additionalProperties: props.schema.additionalProperties,
-    } satisfies ILlmSchema.IObject;
-    const human = {
-      ...props.schema,
-      properties: {} as Record<string, ILlmSchema>,
-    } satisfies ILlmSchema.IObject;
-
-    for (const [key, value] of Object.entries(props.schema.properties ?? {})) {
-      const [x, y] = separateStation({
-        predicate: props.predicate,
-        convention: props.convention,
-        $defs: props.$defs,
-        schema: value,
-      });
-      if (x !== null) llm.properties[key] = x;
-      if (y !== null) human.properties[key] = y;
-    }
-    if (
-      typeof props.schema.additionalProperties === "object" &&
-      props.schema.additionalProperties !== null
-    ) {
-      const [dx, dy] = separateStation({
-        predicate: props.predicate,
-        convention: props.convention,
-        $defs: props.$defs,
-        schema: props.schema.additionalProperties,
-      });
-      llm.additionalProperties = dx ?? false;
-      human.additionalProperties = dy ?? false;
-    }
-    return [
-      !!Object.keys(llm.properties).length || !!llm.additionalProperties
-        ? shrinkRequired(llm)
-        : null,
-      !!Object.keys(human.properties).length || human.additionalProperties
-        ? shrinkRequired(human)
-        : null,
-    ];
-  };
-
-  const separateReference = (props: {
-    predicate: (schema: ILlmSchema) => boolean;
-    convention: (key: string, type: "llm" | "human") => string;
-    $defs: Record<string, ILlmSchema>;
-    schema: ILlmSchema.IReference;
-  }): [ILlmSchema.IReference | null, ILlmSchema.IReference | null] => {
-    const key: string =
-      props.schema.$ref.split("#/$defs/")[1] ??
-      props.schema.$ref.split("/").at(-1)!;
-    const humanKey: string = props.convention(key, "human");
-    const llmKey: string = props.convention(key, "llm");
-
-    // FIND EXISTING
-    if (props.$defs?.[humanKey] || props.$defs?.[llmKey])
-      return [
-        props.$defs?.[llmKey]
-          ? {
-              ...props.schema,
-              $ref: `#/$defs/${llmKey}`,
-            }
-          : null,
-        props.$defs?.[humanKey]
-          ? {
-              ...props.schema,
-              $ref: `#/$defs/${humanKey}`,
-            }
-          : null,
-      ];
-
-    // PRE-ASSIGNMENT
-    props.$defs![llmKey] = {};
-    props.$defs![humanKey] = {};
-
-    // DO COMPOSE
-    const schema: ILlmSchema = props.$defs?.[key]!;
-    const [llm, human] = separateStation({
-      predicate: props.predicate,
-      convention: props.convention,
-      $defs: props.$defs,
-      schema,
-    });
-    if (llm !== null) Object.assign(props.$defs[llmKey], llm);
-    if (human !== null) Object.assign(props.$defs[humanKey], human);
-
-    // ONLY ONE
-    if (llm === null || human === null) {
-      delete props.$defs[llmKey];
-      delete props.$defs[humanKey];
-      return llm === null ? [null, props.schema] : [props.schema, null];
-    }
-
-    // BOTH OF THEM
-    return [
-      llm !== null
-        ? {
-            ...props.schema,
-            $ref: `#/$defs/${llmKey}`,
-          }
-        : null,
-      human !== null
-        ? {
-            ...props.schema,
-            $ref: `#/$defs/${humanKey}`,
-          }
-        : null,
-    ];
-  };
-
-  const shrinkRequired = (s: ILlmSchema.IObject): ILlmSchema.IObject => {
-    s.required = s.required.filter((key) => s.properties?.[key] !== undefined);
-    return s;
-  };
 }
 
 const validateStrict = (

package/src/http/HttpLlm.ts

@@ -5,7 +5,6 @@ import {
   IHttpLlmFunction,
   IHttpMigrateApplication,
   IHttpResponse,
-  ILlmFunction,
   OpenApi,
   OpenApiV3,
   OpenApiV3_1,
@@ -15,7 +14,6 @@ import {
 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.
@@ -92,8 +90,7 @@ export namespace HttpLlm {
   /**
    * Convert OpenAPI document to LLM function calling application.
    *
-   * Converts API operations to LLM-callable functions. Use
-   * {@link mergeParameters} if `separate` option is configured.
+   * Converts API operations to LLM-callable functions.
    *
    * @param props Composition properties
    * @returns LLM function calling application
@@ -118,7 +115,6 @@ export namespace HttpLlm {
       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,
       },
@@ -168,43 +164,4 @@ export namespace HttpLlm {
    */
   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/internal/HttpLlmApplicationComposer.ts

@@ -9,7 +9,8 @@ import {
   OpenApi,
 } from "@typia/interface";
 
-import { LlmSchemaConverter } from "../../converters";
+import { LlmSchemaConverter } from "../../converters/LlmSchemaConverter";
+import { LlmJson } from "../../utils";
 import { OpenApiValidator } from "../../validators/OpenApiValidator";
 
 /**
@@ -33,7 +34,6 @@ export namespace HttpLlmApplicationComposer {
   }): IHttpLlmApplication => {
     // fill in config defaults
     const config: IHttpLlmApplication.IConfig = {
-      separate: props.config?.separate ?? null,
       maxLength: props.config?.maxLength ?? 64,
       equals: props.config?.equals ?? false,
       reference: props.config?.reference ?? true,
@@ -256,17 +256,11 @@ export namespace HttpLlmApplicationComposer {
       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,
       deprecated: operation.deprecated,
       tags: operation.tags,
+      parse: (input: string) => LlmJson.parse(input, llmParameters.value),
       validate: OpenApiValidator.create({
         components: props.components,
         schema: parameters,

package/src/utils/LlmJson.ts

@@ -0,0 +1,141 @@
+import {
+  IJsonParseResult,
+  ILlmSchema,
+  IValidation,
+  OpenApi,
+} from "@typia/interface";
+
+import { LlmSchemaConverter } from "../converters";
+import { OpenApiValidator } from "../validators";
+import { coerceLlmArguments } from "./internal/coerceLlmArguments";
+import { parseLenientJson } from "./internal/parseLenientJson";
+import { stringifyValidationFailure } from "./internal/stringifyValidationFailure";
+
+/**
+ * JSON utilities for LLM function calling.
+ *
+ * - {@link LlmJson.parse}: Lenient JSON parser for incomplete/malformed JSON
+ * - {@link LlmJson.stringify}: Format validation errors for LLM feedback
+ * - {@link LlmJson.validate}: Create a reusable validator from schema
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace LlmJson {
+  /**
+   * Coerce LLM arguments to match expected schema types.
+   *
+   * LLMs often return values with incorrect types (e.g., numbers as strings).
+   * This function recursively coerces values based on the schema:
+   *
+   * - `"42"` → `42` (when schema expects number)
+   * - `"true"` → `true` (when schema expects boolean)
+   * - `"null"` → `null` (when schema expects null)
+   * - `"{...}"` → `{...}` (when schema expects object)
+   * - `"[...]"` → `[...]` (when schema expects array)
+   *
+   * Use this when SDK provides already-parsed objects but values may have
+   * wrong types. For raw JSON strings, use {@link parse} instead.
+   *
+   * @param input Parsed arguments object from LLM
+   * @param parameters LLM function parameters schema for type coercion
+   * @returns Coerced arguments with corrected types
+   */
+  export function coerce<T = unknown>(
+    input: T,
+    parameters: ILlmSchema.IParameters,
+  ): T {
+    return coerceLlmArguments(input, parameters);
+  }
+
+  /**
+   * Parse lenient JSON with optional schema-based coercion.
+   *
+   * Handles incomplete/malformed JSON commonly produced by LLMs:
+   *
+   * - Unclosed brackets, strings, trailing commas
+   * - JavaScript-style comments (`//` and multi-line)
+   * - Unquoted object keys, incomplete keywords (`tru`, `fal`, `nul`)
+   * - Markdown code block extraction, junk prefix skipping
+   *
+   * When `parameters` schema is provided, also coerces double-stringified
+   * values: `"42"` → `42`, `"true"` → `true`, `"{...}"` → `{...}` based on
+   * expected types.
+   *
+   * Type validation is NOT performed - use {@link ILlmFunction.validate}.
+   *
+   * @param input Raw JSON string (potentially incomplete or malformed)
+   * @param parameters Optional LLM parameters schema for type coercion
+   * @returns Parse result with data on success, or partial data with errors
+   */
+  export function parse<T = unknown>(
+    input: string,
+    parameters?: ILlmSchema.IParameters,
+  ): IJsonParseResult<T> {
+    const result: IJsonParseResult<T> = parseLenientJson<T>(input);
+
+    // Apply schema-based coercion if parameters provided and parsing succeeded
+    if (parameters !== undefined && result.success) {
+      return {
+        success: true,
+        data: coerceLlmArguments(result.data, parameters) as T,
+      };
+    }
+    return result;
+  }
+
+  /**
+   * Format validation failure for LLM auto-correction feedback.
+   *
+   * When LLM generates invalid function call arguments, this produces annotated
+   * JSON with inline `// ❌` error comments at each invalid property. The output
+   * is wrapped in a markdown code block so that LLM can understand and correct
+   * its mistakes in the next turn.
+   *
+   * Below is an example of the output format:
+   *
+   * ```json
+   * {
+   *   "name": "John",
+   *   "age": "twenty", // ❌ [{"path":"$input.age","expected":"number & Type<\"uint32\">"}]
+   *   "email": "not-an-email", // ❌ [{"path":"$input.email","expected":"string & Format<\"email\">"}]
+   *   "hobbies": "reading" // ❌ [{"path":"$input.hobbies","expected":"Array<string>"}]
+   * }
+   * ```
+   *
+   * @param failure Validation failure from {@link ILlmFunction.validate}
+   */
+  export function stringify(failure: IValidation.IFailure): string {
+    return stringifyValidationFailure(failure);
+  }
+
+  /**
+   * Create a reusable validator from LLM parameters schema.
+   *
+   * When validation fails, format the failure with {@link stringify} for LLM
+   * auto-correction feedback.
+   *
+   * @param parameters LLM function parameters schema
+   * @param equals If `true`, reject extraneous properties not defined in the
+   *   schema. Otherwise, extra properties are ignored.
+   * @returns Validator function that checks data against the schema
+   */
+  export function validate(
+    parameters: ILlmSchema.IParameters,
+    equals?: boolean | undefined,
+  ) {
+    const components: OpenApi.IComponents = {
+      schemas: {},
+    };
+    const schema: OpenApi.IJsonSchema = LlmSchemaConverter.invert({
+      components,
+      schema: parameters,
+      $defs: parameters.$defs,
+    });
+    return OpenApiValidator.create({
+      components,
+      schema,
+      required: true,
+      equals,
+    });
+  }
+}

package/src/utils/index.ts

@@ -1,8 +1,8 @@
 export * from "./ArrayUtil";
+export * from "./LlmJson";
 export * from "./MapUtil";
 export * from "./NamingConvention";
 export * from "./Singleton";
 export * from "./StringUtil";
 
 export * from "./dedent";
-export * from "./stringifyValidationFailure";