import { tags } from "..";
import { IJsonParseResult } from "./IJsonParseResult";
import { ILlmSchema } from "./ILlmSchema";
import { IValidation } from "./IValidation";
/**
 * LLM function calling schema for TypeScript functions.
 *
 * Generated by `typia.llm.application<App>()` as part of
 * {@link ILlmApplication}.
 *
 * - {@link name}: Function identifier (max 64 chars for OpenAI)
 * - {@link parameters}: Input schema, {@link output}: Return schema
 * - {@link description}: Guides LLM function selection
 * - {@link parse}: Lenient JSON parser with type coercion
 * - {@link validate}: Argument validator for LLM error correction
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface ILlmFunction {
    /**
     * Function name for LLM invocation.
     *
     * The identifier used by the LLM to call this function. Must be unique within
     * the application.
     *
     * OpenAI limits function names to 64 characters.
     */
    name: string & tags.MaxLength<64>;
    /**
     * Schema for function parameters.
     *
     * Defines the expected argument types as a JSON Schema object. Contains
     * `$defs` for shared type definitions and `properties` for each named
     * parameter.
     */
    parameters: ILlmSchema.IParameters;
    /**
     * Schema for the return type.
     *
     * Defines the expected output type as an object parameters schema, wrapping
     * the return type in an {@link ILlmSchema.IParameters} object with `$defs` for
     * shared type definitions and `properties` for the structured output.
     *
     * `undefined` when the function returns `void` or has no meaningful return
     * value.
     */
    output?: ILlmSchema.IParameters | undefined;
    /**
     * Human-readable function description.
     *
     * Explains what the function does, when to use it, and any important
     * considerations. This description is crucial for LLMs to understand when to
     * invoke this function. Extracted from JSDoc comments.
     */
    description?: string | undefined;
    /**
     * Whether this function is deprecated.
     *
     * When `true`, indicates the function should no longer be used. LLMs may
     * still invoke deprecated functions but should prefer non-deprecated
     * alternatives when available.
     */
    deprecated?: boolean | undefined;
    /**
     * Category tags for function organization.
     *
     * Extracted from `@tag` JSDoc annotations. Useful for grouping related
     * functions and filtering the function list.
     */
    tags?: string[] | undefined;
    /**
     * Lenient JSON parser with 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
     *
     * Also coerces double-stringified values (`"42"` → `42`) using the
     * {@link parameters} schema.
     *
     * 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 to apply
     * schema-based type coercion without re-parsing.
     *
     * @param str Raw JSON string from LLM output
     * @returns Parse result with data on success, or partial data with errors
     */
    parse: (str: string) => IJsonParseResult<unknown>;
    /**
     * Coerce pre-parsed arguments to match expected schema types.
     *
     * **Use this only when the SDK (e.g., LangChain, Vercel AI, MCP) 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 data Pre-parsed arguments object from SDK
     * @returns Coerced arguments with corrected types
     */
    coerce: (data: unknown) => unknown;
    /**
     * Validates LLM-generated arguments against the schema.
     *
     * LLMs frequently make type errors such as returning strings instead of
     * numbers or missing required properties. Use this validator to check
     * arguments before execution.
     *
     * 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 args The arguments generated by the LLM
     * @returns Validation result with success status and any errors
     * @see stringifyValidationFailure Format errors for LLM auto-correction
     */
    validate: (args: unknown) => IValidation<unknown>;
}