airflow.providers.common.ai.batch.output_schema¶

Provider-neutral structured-output layer for @task.llm_batch.

This module knows nothing about any provider – it only knows Pydantic. It turns output_type into a JSON Schema adapters can translate into their own request shape (OutputSpec), and turns an adapter’s extracted response back into a validated value or an explicit failure (ValidationOutcome).

Deliberately does not call rehydrate_pydantic_output(): that helper’s failure mode is “validation failed -> return the raw string unchanged”, which is correct for the HITL round-trip it was built for but wrong here – a batch item that fails validation must be recorded as failed (status: "invalid_output"), never silently downgraded into a string that merely looks like a success.

Classes¶

`OutputSpec`	The translation of `output_type` into a provider-agnostic structured-output request.
`ValidationOutcome`	The result of validating one item's `ExtractedOutput` against an `OutputSpec`.

Functions¶

`build_output_spec`(output_type)	Build the `OutputSpec` for a `@task.llm_batch` `output_type`.
`validate_extracted_output`(extracted, spec)	Validate one item's extracted output against `spec`, never raising.

Module Contents¶

class airflow.providers.common.ai.batch.output_schema.OutputSpec[source]¶

The translation of output_type into a provider-agnostic structured-output request.

Built once per task execution (the schema is identical for every request in the batch), then passed to the adapter’s build_output_directive() and, on the way back, to validate_extracted_output().

output_type: type[source]¶

is_structured: bool[source]¶

json_schema: dict[str, Any][source]¶

schema_name: str[source]¶

type_adapter: pydantic.TypeAdapter[Any][source]¶

wrapped: bool = False[source]¶

airflow.providers.common.ai.batch.output_schema.build_output_spec(output_type)[source]¶

Build the OutputSpec for a @task.llm_batch output_type.

output_type is str (the default) produces an unstructured spec: no schema is generated and adapters skip build_output_directive / extract_output validation entirely. Any other type – a BaseModel subclass, or another type TypeAdapter supports (int, list[str], …), matching what @task.llm’s output_type already accepts – produces a JSON Schema.

Raises:: LLMBatchOutputTypeError – output_type cannot produce a JSON Schema at all (e.g. a bare class with no Pydantic-compatible fields). Raised eagerly, before any request is built or submitted.

class airflow.providers.common.ai.batch.output_schema.ValidationOutcome[source]¶

The result of validating one item’s ExtractedOutput against an OutputSpec.

ok: bool[source]¶

value: Any | None = None[source]¶

raw_text: str | None = None[source]¶

error_message: str | None = None[source]¶

airflow.providers.common.ai.batch.output_schema.validate_extracted_output(extracted, spec)[source]¶

Validate one item’s extracted output against spec, never raising.

“The model returned something that doesn’t match output_type” is batch data, not an exception – the caller records ok=False items as status: "invalid_output" and keeps processing the rest of the stream.

When spec.is_structured is False (output_type is str), the text passes through unchanged with no validation at all.