@typia/interface 12.0.0-dev.20260310 → 12.0.0-dev.20260312

package/src/openapi/index.ts

@@ -1,4 +1,5 @@
-export * from "./OpenApi";
-export * from "./OpenApiV3";
-export * from "./OpenApiV3_1";
-export * from "./SwaggerV2";
+export * from "./OpenApi";
+export * from "./OpenApiV3";
+export * from "./OpenApiV3_1";
+export * from "./OpenApiV3_2";
+export * from "./SwaggerV2";

package/src/schema/ILlmApplication.ts

@@ -13,7 +13,6 @@ import { IValidation } from "./IValidation";
  *
  * - {@link ILlmApplication.IConfig.validate}: Custom validation per method
  * - {@link ILlmSchema.IConfig.strict}: OpenAI structured output mode
- * - {@link ILlmSchema.IConfig.reference}: Control `$ref` inlining behavior
  *
  * @author Jeongho Nam - https://github.com/samchon
  * @template Class Source class/interface type
@@ -32,7 +31,7 @@ export interface ILlmApplication<Class extends object = any> {
    * Configuration used to generate this application.
    *
    * Contains the settings that were applied during schema generation, including
-   * reference handling, strict mode, and parameter separation.
+   * strict mode and any custom validation hooks.
    */
   config: ILlmApplication.IConfig<Class>;
 

package/src/schema/ILlmSchema.ts

@@ -36,20 +36,9 @@ export namespace ILlmSchema {
    * Configuration options for LLM schema generation.
    *
    * Controls how TypeScript types are converted to LLM-compatible JSON schemas.
-   * These settings affect reference handling and OpenAI structured output
-   * compatibility.
+   * These settings affect OpenAI structured output compatibility.
    */
   export interface IConfig {
-    /**
-     * Whether to allow `$ref` references everywhere.
-     *
-     * When `false`, references are inlined except for recursive types.
-     * References reduce token cost but may cause hallucination.
-     *
-     * @default true
-     */
-    reference: boolean;
-
     /**
      * Whether to enable strict mode (OpenAI structured output).
      *

package/src/schema/ILlmStructuredOutput.ts

@@ -0,0 +1,112 @@
+import { IJsonParseResult } from "./IJsonParseResult";
+import { ILlmSchema } from "./ILlmSchema";
+import { IValidation } from "./IValidation";
+
+/**
+ * LLM structured output schema with parsing and validation utilities.
+ *
+ * `ILlmStructuredOutput<T>` is generated by `typia.llm.structuredOutput<T>()`
+ * to provide everything needed for handling LLM structured outputs: the JSON
+ * schema for prompting, and functions for parsing, coercing, and validating
+ * responses.
+ *
+ * Structured outputs allow LLMs to generate data conforming to a predefined
+ * schema instead of free-form text. This is useful for:
+ *
+ * - Extracting structured data from conversations
+ * - Generating typed responses for downstream processing
+ * - Ensuring consistent output formats across LLM calls
+ *
+ * Workflow:
+ *
+ * 1. Pass {@link parameters} schema to LLM provider
+ * 2. Receive LLM response (JSON string or pre-parsed object)
+ * 3. Use {@link parse} for raw strings or {@link coerce} for pre-parsed objects
+ * 4. Use {@link validate} to check the result and get detailed errors
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template T The expected output type
+ */
+export interface ILlmStructuredOutput<T = unknown> {
+  /**
+   * JSON schema for the structured output.
+   *
+   * Pass this schema to LLM providers (OpenAI, Anthropic, Google, etc.) to
+   * constrain the output format. The schema includes `$defs` for shared type
+   * definitions and `properties` for the output structure.
+   *
+   * Most LLM providers accept this directly in their structured output or
+   * response format configuration.
+   */
+  parameters: ILlmSchema.IParameters;
+
+  /**
+   * Lenient JSON parser with schema-based type coercion.
+   *
+   * Handles incomplete or 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
+   *
+   * Also coerces double-stringified 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)
+   *
+   * Type validation is NOT performed — use {@link validate} after parsing.
+   *
+   * If the SDK (e.g., LangChain, Vercel AI, MCP) already parses JSON internally
+   * and provides a pre-parsed object, use {@link coerce} instead.
+   *
+   * @param input Raw JSON string from LLM output
+   * @returns Parse result with data on success, or partial data with errors
+   */
+  parse: (input: string) => IJsonParseResult<T>;
+
+  /**
+   * Coerce pre-parsed output to match expected schema types.
+   *
+   * **Use this only when the SDK already parses JSON internally.** For raw JSON
+   * strings from LLM output, use {@link parse} instead — it handles both lenient
+   * parsing and type coercion in one step.
+   *
+   * LLMs often return values with incorrect types even after parsing:
+   *
+   * - `"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)
+   *
+   * This function recursively coerces these double-stringified values based on
+   * the {@link parameters} schema.
+   *
+   * Type validation is NOT performed — use {@link validate} after coercion.
+   *
+   * @param input Pre-parsed output object from SDK
+   * @returns Coerced output with corrected types
+   */
+  coerce: (input: unknown) => T;
+
+  /**
+   * Validates LLM-generated output against the schema.
+   *
+   * LLMs frequently make type errors such as returning strings instead of
+   * numbers or missing required properties. Use this validator to check output
+   * before further processing.
+   *
+   * When validation fails, use {@link LlmJson.stringify} from `@typia/utils` to
+   * format the error for LLM feedback. The formatted output shows the invalid
+   * JSON with inline error comments, helping the LLM understand and correct its
+   * mistakes in the next turn.
+   *
+   * @param input The output generated by the LLM
+   * @returns Validation result with success status and any errors
+   */
+  validate: (input: unknown) => IValidation<T>;
+}

package/src/schema/index.ts

@@ -1,14 +1,15 @@
-export * from "./IResult";
-export * from "./IValidation";
-
-export * from "./IJsonSchemaTransformError";
-export * from "./IJsonSchemaApplication";
-export * from "./IJsonSchemaCollection";
-export * from "./IJsonSchemaUnit";
-export * from "./IJsonSchemaAttribute";
-
-export * from "./ILlmController";
-export * from "./ILlmApplication";
-export * from "./ILlmFunction";
-export * from "./ILlmSchema";
-export * from "./IJsonParseResult";
+export * from "./IResult";
+export * from "./IValidation";
+
+export * from "./IJsonSchemaTransformError";
+export * from "./IJsonSchemaApplication";
+export * from "./IJsonSchemaCollection";
+export * from "./IJsonSchemaUnit";
+export * from "./IJsonSchemaAttribute";
+
+export * from "./ILlmController";
+export * from "./ILlmApplication";
+export * from "./ILlmFunction";
+export * from "./ILlmSchema";
+export * from "./ILlmStructuredOutput";
+export * from "./IJsonParseResult";