# `ReqLLM.Output`
[🔗](https://github.com/agentjido/req_llm/blob/main/lib/req_llm/output.ex#L1)

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.

# `contract`

```elixir
@type contract() :: %{
  descriptor: t(),
  operation: :chat | :object,
  compiled_schema: map() | nil,
  wrapped?: boolean()
}
```

# `output_type`

```elixir
@type output_type() :: :text | :object | :array | :choice | :json
```

# `repair_callback`

```elixir
@type repair_callback() :: (ReqLLM.Output.Result.t() ->
                        {:ok, term()} | {:error, term()})
```

# `runtime_config`

```elixir
@type runtime_config() :: %{
  enabled?: boolean(),
  policy: validation_policy(),
  repair: repair_callback() | nil
}
```

# `t`

```elixir
@type t() :: %ReqLLM.Output{
  choices: [String.t()] | nil,
  description: String.t() | nil,
  element: term() | nil,
  name: String.t() | nil,
  schema: term() | nil,
  type: output_type()
}
```

# `validation_policy`

```elixir
@type validation_policy() :: :compatible | :warn | :strict
```

# `array`

```elixir
@spec array(term(), keyword()) :: t()
```

Returns an array output descriptor.

`element` is the schema for one array element and accepts the same schema
forms as `object/2`.

# `choice`

```elixir
@spec choice([String.t()], keyword()) :: t()
```

Returns a descriptor requesting one of the provided unique strings.

# `json`

```elixir
@spec json(keyword()) :: t()
```

Returns a descriptor for any JSON value without a shape constraint.

# `object`

```elixir
@spec object(term(), keyword()) :: t()
```

Returns an object output descriptor.

The schema may be a NimbleOptions-style keyword schema, JSON Schema map, or
Zoi schema. Optional `:name` and `:description` values provide provider
guidance where the selected structured-output surface supports it.

# `result`

```elixir
@spec result(ReqLLM.Response.t(), t(), keyword()) :: ReqLLM.Output.Result.t()
```

Computes a complete structured-output result without changing the response.

The default `:compatible` policy reports final validity without converting an
invalid V1 response into an error. Pass `policy: :warn` or `policy: :strict`
to describe the policy used for the projection. Runtime enforcement is
configured on generation calls with `:output_validation`.

# `text`

```elixir
@spec text() :: t()
```

Returns the default plain-text output descriptor.

---

*Consult [api-reference.md](api-reference.md) for complete listing*