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

A tagged, provider-neutral projection of one streaming event.

Events are computed from the existing `ReqLLM.StreamChunk` stream. They do
not replace chunks in ReqLLM 1.x and are not stored on
`ReqLLM.StreamResponse`.

The event stream begins with `:start` and ends with exactly one of
`:finish`, `:cancelled`, or `:error` when it is consumed to completion.
Output deltas retain their arrival order. Provider-specific metadata is
exposed through `:provider_event` and event metadata without treating raw
provider frames as part of the canonical contract.

## Event types

- `:start` carries the resolved provider and model identity.
- `:text_delta` and `:reasoning_delta` carry string deltas.
- `:tool_call_start` and `:tool_call_delta` carry incremental tool input;
  `:tool_call` carries the assembled call before the terminal event.
- `:tool_result` carries a result already present in provider metadata. It
  does not execute a tool or continue a model loop.
- `:source`, `:file`, and `:output_item` carry
  `ReqLLM.Response.OutputItem` projections.
- `:usage` carries the final usage map and `:warning` carries one warning.
- `:finish`, `:cancelled`, and `:error` are mutually exclusive terminal
  events.
- `:provider_event` carries sanitized extension metadata that has no
  provider-neutral event type.

# `event_type`

```elixir
@type event_type() ::
  :start
  | :text_delta
  | :reasoning_delta
  | :tool_call_start
  | :tool_call_delta
  | :tool_call
  | :tool_result
  | :source
  | :file
  | :output_item
  | :usage
  | :warning
  | :finish
  | :cancelled
  | :error
  | :provider_event
```

# `t`

```elixir
@type t() :: %ReqLLM.StreamEvent{data: term(), metadata: map(), type: event_type()}
```

# `new`

```elixir
@spec new(event_type(), term(), map()) :: t()
```

Builds a canonical stream event.

# `output?`

```elixir
@spec output?(t()) :: boolean()
```

Returns whether an event carries model output or an output delta.

# `schema`

Returns the Zoi schema for canonical stream events.

# `terminal?`

```elixir
@spec terminal?(t()) :: boolean()
```

Returns whether an event is the terminal event for a consumed stream.

# `types`

```elixir
@spec types() :: [event_type()]
```

Returns all stable stream event types.

---

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