OpenAI.Responses.Stream (openai_responses v0.2.1)

Utilities for working with OpenAI streaming responses.

This module provides functions for transforming and consuming streamed responses from the OpenAI API.

Examples

# Get text deltas as they arrive
stream = OpenAI.Responses.stream("gpt-4o", "Tell me a story")
text_stream = OpenAI.Responses.Stream.text_deltas(stream)

# Print each text delta in real-time without duplication
text_stream
|> Stream.each(fn delta -> 
  IO.write(delta)
end)
|> Stream.run()

# Collect a complete response from a stream
stream = OpenAI.Responses.stream("gpt-4o", "Tell me a story")
response = OpenAI.Responses.Stream.collect(stream)

Summary

Functions

Collects all streaming events into a final response.

Creates a new stream handler for OpenAI streaming responses.

Extracts text chunks from a stream as they arrive (legacy function).

Extracts text deltas from a stream as they arrive.

Transforms a stream with a callback function.

Functions

collect(stream)

@spec collect(Enumerable.t()) :: map()

Collects all streaming events into a final response.

This is useful for consuming a stream and building a complete response object, similar to what would be returned by a non-streaming API call. The function processes all events from the stream and combines them into a single coherent response object.

Parameters

  • stream - The stream from OpenAI.Responses.stream/3

Returns

  • The complete response map

Examples

# Get a streaming response
stream = OpenAI.Responses.stream("gpt-4o", "Tell me a story")

# Collect all events into a single response object
response = OpenAI.Responses.Stream.collect(stream)

# Process the complete response
text = OpenAI.Responses.Helpers.output_text(response)
IO.puts(text)

new(stream, opts \\ [])

@spec new(
  Enumerable.t(),
  keyword()
) :: map()

Creates a new stream handler for OpenAI streaming responses.

This function is maintained for backward compatibility. For new code, use the stream transformation functions directly.

Parameters

  • stream - The stream from OpenAI.Responses.stream/3
  • opts - Options for the stream handler

Returns

  • A stream handler struct

text_chunks(map)

@spec text_chunks(map()) :: Enumerable.t(String.t())

Extracts text chunks from a stream as they arrive (legacy function).

This function is maintained for backward compatibility. For new code, use text_deltas/1 instead.

Parameters

  • stream_handler - The stream handler from new/2

Returns

  • A stream of text chunks

text_deltas(stream)

@spec text_deltas(Enumerable.t()) :: Enumerable.t(String.t())

Extracts text deltas from a stream as they arrive.

This returns a stream of text chunks that can be consumed as they arrive, rather than waiting for the full response. The implementation avoids duplicating content when the API sends both incremental deltas and a final complete text.

Parameters

  • stream - The stream from OpenAI.Responses.stream/3

Returns

  • A stream of text chunks

Examples

stream = OpenAI.Responses.stream("gpt-4o", "Tell me a story")
text_stream = OpenAI.Responses.Stream.text_deltas(stream)

# Print text deltas as they arrive (real-time output)
text_stream
|> Stream.each(fn delta -> 
  IO.write(delta)
end)
|> Stream.run()
IO.puts("")  # Add a newline at the end

transform(map, callback)

@spec transform(map(), function()) :: Enumerable.t()

Transforms a stream with a callback function.

Parameters

  • stream_handler - The stream handler from new/2
  • callback - The callback function to apply to each event

Returns

  • A transformed stream