llm

defmodule LLM.Stream.Stop do
  @moduledoc """
  Stop event from a streaming response.

  Emitted when the stream ends. Contains the reason generation stopped and
  optionally the final usage statistics.

  ## Fields

  - `:reason` — why generation stopped:
    - `:stop` — natural end of response
    - `:length` — hit max_tokens limit
    - `:tool_calls` — model wants to call tools
    - `:content_filter` — content was filtered
    - `:max_tokens` — provider-specific max tokens reached
  - `:usage` — final `LLM.Usage.t()` with token counts (may be `nil`)

  ## Example

      %LLM.Stream.Stop{
        reason: :stop,
        usage: %LLM.Usage{input_tokens: 10, output_tokens: 50, total_tokens: 60}
      }
  """

  @type t :: %__MODULE__{
          reason: atom(),
          usage: LLM.Usage.t() | nil
        }

  defstruct [:reason, :usage]
end