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>;
}