@typia/utils 12.0.0 → 12.1.0-dev.20260325

package/src/utils/LlmJson.ts

@@ -1,173 +1,173 @@
-import {
-  IJsonParseResult,
-  ILlmSchema,
-  ILlmStructuredOutput,
-  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: unknown,
-    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,
-    });
-  }
-
-  /**
-   * Convert LLM parameters schema to structured output interface.
-   *
-   * Creates an {@link ILlmStructuredOutput} containing everything needed for
-   * handling LLM structured outputs: the parameters schema for prompting, and
-   * functions for parsing, coercing, and validating responses.
-   *
-   * This is useful when you have a parameters schema (e.g., from
-   * `typia.llm.parameters()`) and need the full structured output interface
-   * with all utility functions.
-   *
-   * @template T The expected output type
-   * @param parameters LLM parameters schema
-   * @param equals If `true`, reject extraneous properties not defined in the
-   *   schema during validation. Otherwise, extra properties are ignored.
-   * @returns Structured output interface with parse, coerce, and validate
-   */
-  export function structuredOutput<T>(
-    parameters: ILlmSchema.IParameters,
-    equals?: boolean | undefined,
-  ): ILlmStructuredOutput<T> {
-    const validator = validate(parameters, equals);
-    return {
-      parameters,
-      parse: (str: string): IJsonParseResult<T> => parse(str, parameters),
-      coerce: (input: unknown): T => coerce(input, parameters),
-      validate: (input: unknown): IValidation<T> =>
-        validator(input) as IValidation<T>,
-    };
-  }
-}
+import {
+  IJsonParseResult,
+  ILlmSchema,
+  ILlmStructuredOutput,
+  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: unknown,
+    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,
+    });
+  }
+
+  /**
+   * Convert LLM parameters schema to structured output interface.
+   *
+   * Creates an {@link ILlmStructuredOutput} containing everything needed for
+   * handling LLM structured outputs: the parameters schema for prompting, and
+   * functions for parsing, coercing, and validating responses.
+   *
+   * This is useful when you have a parameters schema (e.g., from
+   * `typia.llm.parameters()`) and need the full structured output interface
+   * with all utility functions.
+   *
+   * @template T The expected output type
+   * @param parameters LLM parameters schema
+   * @param equals If `true`, reject extraneous properties not defined in the
+   *   schema during validation. Otherwise, extra properties are ignored.
+   * @returns Structured output interface with parse, coerce, and validate
+   */
+  export function structuredOutput<T>(
+    parameters: ILlmSchema.IParameters,
+    equals?: boolean | undefined,
+  ): ILlmStructuredOutput<T> {
+    const validator = validate(parameters, equals);
+    return {
+      parameters,
+      parse: (str: string): IJsonParseResult<T> => parse(str, parameters),
+      coerce: (input: unknown): T => coerce(input, parameters),
+      validate: (input: unknown): IValidation<T> =>
+        validator(input) as IValidation<T>,
+    };
+  }
+}