core.structured_output

Pydantic-validated structured output for LLM responses.

Provides StructuredOutputHandler which converts Pydantic models into JSON Schema instructions, validates LLM output against the schema, and supports retry with error feedback on validation failure.

Pydantic-validated structured output for LLM responses.

Provides StructuredOutputHandler which converts Pydantic models into JSON Schema instructions, validates LLM output against the schema, and supports retry with error feedback on validation failure.

class StructuredResult(parsed, raw_response, attempts, parsing_errors=<factory>)

Bases: object

Outcome of a structured-output validation attempt.

Parameters:

• parsed (BaseModel | None)

• raw_response (str)

• attempts (int)

• parsing_errors (list[str])

parsed

Validated Pydantic model instance, or None on failure.

Type:

pydantic.main.BaseModel | None

raw_response

The original LLM response string.

Type:

str

attempts

Number of validation attempts made.

Type:

int

parsing_errors

List of error strings from failed validations.

Type:

list[str]

parsed: BaseModel | None

raw_response: str

attempts: int

parsing_errors: list[str]

class StructuredOutputHandler(max_retries=2)

Bases: object

Validates LLM responses against Pydantic models.

Parameters:

max_retries (int) – Maximum number of re-prompt attempts after validation failure. Total attempts = max_retries + 1.

build_response_format(model)

Return the Pydantic model class for use as response_format.

LiteLLM’s completion() accepts type[BaseModel] directly in the response_format parameter and handles provider-specific schema translation internally. Returning the model class instead of a hand-built dict avoids incompatible schemas across providers.

Parameters:

model (type[BaseModel]) – A Pydantic BaseModel subclass.

Returns:

The same Pydantic model class, for use as response_format.

Return type:

type[BaseModel]

build_system_suffix(model)

Generate instruction text describing the expected JSON schema.

Intended to be appended to system instructions so the model knows the exact output shape.

Parameters:

model (type[BaseModel]) – A Pydantic BaseModel subclass.

Returns:

Instruction string with embedded JSON Schema.

Return type:

str

validate(response, model)

Parse and validate an LLM response against a Pydantic model.

Uses json_repair for fault-tolerant JSON parsing, then Pydantic validation for type safety.

Parameters:

• response (str) – Raw LLM response text.

• model (type[T]) – Pydantic BaseModel subclass to validate against.

Returns:

StructuredResult with parsed set on success, or parsing_errors populated on failure.

Return type:

StructuredResult

prepare_retry_state(prompt, response_model)

Initialize retry state for a structured output loop.

Parameters:

• prompt (str) – The original resolved prompt.

• response_model (type[BaseModel]) – Pydantic BaseModel subclass.

Returns:

Tuple of (all_errors, current_prompt, best_result).

Return type:

tuple[list[str], str, StructuredResult | None]

process_attempt(response, response_model, prompt, attempt, all_errors, best_result)

Process a single structured output attempt.

Parameters:

• response (str) – The raw LLM response.

• response_model (type[BaseModel]) – Pydantic BaseModel subclass.

• prompt (str) – The original resolved prompt (for feedback).

• attempt (int) – Zero-indexed attempt number.

• all_errors (list[str]) – Accumulated error list.

• best_result (StructuredResult | None) – Best result so far.

Returns:

Tuple of (updated_best_result, next_prompt, updated_errors, should_stop).

Return type:

tuple[StructuredResult | None, str, list[str], bool]

finalize_retry(best_result, all_errors, max_attempts)

Finalize after all retry attempts exhausted.

Parameters:

• best_result (StructuredResult | None) – Last validation result.

• all_errors (list[str]) – All accumulated errors.

• max_attempts (int) – Total attempts made.

Returns:

Final StructuredResult.

Return type:

StructuredResult

build_retry_feedback(errors)

Build a prompt suffix telling the LLM what went wrong.

Parameters:

errors (list[str]) – Validation error strings from the previous attempt.

Returns:

Feedback text to append to the retry prompt.

Return type:

str

Classes

class StructuredOutputHandler(max_retries=2)

Bases: object

Validates LLM responses against Pydantic models.

Parameters:

max_retries (int) – Maximum number of re-prompt attempts after validation failure. Total attempts = max_retries + 1.

build_response_format(model)

Return the Pydantic model class for use as response_format.

LiteLLM’s completion() accepts type[BaseModel] directly in the response_format parameter and handles provider-specific schema translation internally. Returning the model class instead of a hand-built dict avoids incompatible schemas across providers.

Parameters:

model (type[BaseModel]) – A Pydantic BaseModel subclass.

Returns:

The same Pydantic model class, for use as response_format.

Return type:

type[BaseModel]

build_system_suffix(model)

Generate instruction text describing the expected JSON schema.

Intended to be appended to system instructions so the model knows the exact output shape.

Parameters:

model (type[BaseModel]) – A Pydantic BaseModel subclass.

Returns:

Instruction string with embedded JSON Schema.

Return type:

str

validate(response, model)

Parse and validate an LLM response against a Pydantic model.

Uses json_repair for fault-tolerant JSON parsing, then Pydantic validation for type safety.

Parameters:

• response (str) – Raw LLM response text.

• model (type[T]) – Pydantic BaseModel subclass to validate against.

Returns:

StructuredResult with parsed set on success, or parsing_errors populated on failure.

Return type:

StructuredResult

prepare_retry_state(prompt, response_model)

Initialize retry state for a structured output loop.

Parameters:

• prompt (str) – The original resolved prompt.

• response_model (type[BaseModel]) – Pydantic BaseModel subclass.

Returns:

Tuple of (all_errors, current_prompt, best_result).

Return type:

tuple[list[str], str, StructuredResult | None]

process_attempt(response, response_model, prompt, attempt, all_errors, best_result)

Process a single structured output attempt.

Parameters:

• response (str) – The raw LLM response.

• response_model (type[BaseModel]) – Pydantic BaseModel subclass.

• prompt (str) – The original resolved prompt (for feedback).

• attempt (int) – Zero-indexed attempt number.

• all_errors (list[str]) – Accumulated error list.

• best_result (StructuredResult | None) – Best result so far.

Returns:

Tuple of (updated_best_result, next_prompt, updated_errors, should_stop).

Return type:

tuple[StructuredResult | None, str, list[str], bool]

finalize_retry(best_result, all_errors, max_attempts)

Finalize after all retry attempts exhausted.

Parameters:

• best_result (StructuredResult | None) – Last validation result.

• all_errors (list[str]) – All accumulated errors.

• max_attempts (int) – Total attempts made.

Returns:

Final StructuredResult.

Return type:

StructuredResult

build_retry_feedback(errors)

Build a prompt suffix telling the LLM what went wrong.

Parameters:

errors (list[str]) – Validation error strings from the previous attempt.

Returns:

Feedback text to append to the retry prompt.

Return type:

str

class StructuredResult(parsed, raw_response, attempts, parsing_errors=<factory>)

Bases: object

Outcome of a structured-output validation attempt.

Parameters:

• parsed (BaseModel | None)

• raw_response (str)

• attempts (int)

• parsing_errors (list[str])

parsed

Validated Pydantic model instance, or None on failure.

Type:

pydantic.main.BaseModel | None

raw_response

The original LLM response string.

Type:

str

attempts

Number of validation attempts made.

Type:

int

parsing_errors

List of error strings from failed validations.

Type:

list[str]

parsed: BaseModel | None

raw_response: str

attempts: int

parsing_errors: list[str]