Planck.AI.Stream (Planck.AI v0.1.0)

Copy Markdown View Source

Streaming event types and normalization from req_llm chunks.

req_llm emits %ReqLLM.StreamChunk{} structs with a :type field. from_req_llm/1 maps each chunk type to the canonical event tuples consumed by Planck.Agent and callers of Planck.AI.stream/3.

Tool call arguments arrive as JSON fragments spread across multiple :meta chunks. This module buffers the fragments and emits a single assembled {:tool_call_complete, ...} per tool call when the stream finishes.

Exceptions raised during stream consumption (e.g. ReqLLM.Error.API.Stream on HTTP errors) are caught and emitted as {:error, exception} events, halting the stream gracefully.

Event types

  • {:text_delta, text} — a chunk of assistant text
  • {:thinking_delta, text} — a chunk of extended thinking / reasoning
  • {:tool_call_complete, %{id, name, args}} — a fully assembled tool call
  • {:done, %{stop_reason, usage}} — stream finished; includes token usage
  • {:error, reason} — an error occurred during streaming

Summary

Types

done()
t()
tool_call()
usage()

Functions

from_req_llm(chunks)

Converts a stream of ReqLLM.StreamChunk structs into event tuples.

Types

done()

@type done() :: %{stop_reason: atom(), usage: usage()}

t()

@type t() ::
  {:text_delta, String.t()}
  | {:thinking_delta, String.t()}
  | {:tool_call_complete, tool_call()}
  | {:done, done()}
  | {:error, term()}

tool_call()

@type tool_call() :: %{id: String.t(), name: String.t(), args: map()}

usage()

@type usage() :: %{input_tokens: non_neg_integer(), output_tokens: non_neg_integer()}

Functions

from_req_llm(chunks)

@spec from_req_llm(Enumerable.t()) :: Enumerable.t(t())

Converts a stream of ReqLLM.StreamChunk structs into event tuples.

Examples

iex> chunks = [
...>   %{type: :content, text: "Hello"},
...>   %{type: :meta, metadata: %{finish_reason: :stop, usage: %{input_tokens: 10, output_tokens: 5}}}
...> ]
iex> chunks |> Planck.AI.Stream.from_req_llm() |> Enum.to_list()
[{:text_delta, "Hello"}, {:done, %{stop_reason: :stop, usage: %{input_tokens: 10, output_tokens: 5}}}]