Describes the value expected from text generation.

Output descriptors are additive request values for ReqLLM.generate_text/3 and ReqLLM.stream_text/3. Omitting :output, or passing text/0, keeps the existing text-generation path. Structured descriptors reuse ReqLLM's existing object-generation path and preserve the returned ReqLLM.Response or ReqLLM.StreamResponse shape.

Use ReqLLM.Response.output/2 to project a buffered response. For streaming, materialize once with ReqLLM.StreamResponse.to_response/1, then project that response so the parsed output remains beside usage and provider metadata. Raw generated text and structured tool-call arguments remain available through their existing response accessors.

Streaming responses continue to expose the existing one-consumer stream of ReqLLM.StreamChunk values. Content and structured tool-call chunks are partial transport values and are not claimed to satisfy the final schema.

Examples

output = ReqLLM.Output.object(
  [name: [type: :string, required: true]],
  name: "person",
  description: "A generated person"
)

{:ok, response} = ReqLLM.generate_text(model, "Generate a person", output: output)
ReqLLM.Response.output(response, output)
#=> %{"name" => "Ada"}

output = ReqLLM.Output.array(
  Zoi.object(%{name: Zoi.string()}),
  name: "people"
)

output = ReqLLM.Output.choice(["sunny", "rainy", "snowy"])
output = ReqLLM.Output.json(description: "Any valid JSON value")

Omitting :output_validation retains the current V1 validation and repair behavior. :compatible, :warn, and :strict make local final validation explicit without changing provider requests. Partial stream values are never final-schema validation evidence; streaming policies apply when the stream is materialized.

Result and error semantics

ReqLLM.Response.output/2 returns text for text/0, a map for object/2, a list for array/2, a string for choice/2, and any JSON-compatible value for json/1. It returns nil when the existing provider path did not materialize a structured value.

ReqLLM.Response.output_result/3 exposes the retained raw output, projected value, final validity, validation errors, warnings, extraction source, repair attempts, and provider metadata separately. It is local and never triggers a follow-up model call.

Constructors raise ArgumentError for invalid descriptor metadata options. Schema and choice contracts are checked before an HTTP request; generation returns {:error, %ReqLLM.Error.Invalid.Parameter{}} when a contract cannot be compiled. output_validation: :strict turns an invalid complete value into a validation error. :warn returns the response with structured warnings, and :compatible reports validity while retaining V1 success behavior.

:output_repair accepts a callback returning {:ok, candidate} or {:error, reason}. It runs locally at most once after invalid final output, and a candidate replaces the value only after it passes the same final validation. Existing light json_repair remains enabled by default and is reported when detected.