ReqLLM.OpenAI.Realtime (ReqLLM v1.19.0)

View Source

Experimental low-level Realtime WebSocket client for OpenAI.

This module exposes a small session-oriented API for Realtime workflows that do not map cleanly onto ReqLLM.stream_text/3. It is intentionally low-level: you connect a session, send JSON events, receive JSON events, and close the socket when you are done.

next_event/2 remains the raw provider-event API. Use next_projected_event/3 or project_event/2 for an additive view that keeps the sanitized native event alongside any exact ReqLLM.StreamEvent overlap. Session, transport, audio, MCP, rate-limit, and other provider-native events are not forced into portable event types.

Summary

Functions

close(session)
connect(model_spec \\ "gpt-realtime", opts \\ [])
next_event(session, timeout \\ 30000)
next_projected_event(session)

Receives one raw event and returns its provider-native and exact portable views.

next_projected_event(session, opts)
next_projected_event(session, timeout, opts)
project_event(event, opts \\ [])

Projects one already-decoded OpenAI Realtime server event.

response_create(session, response_payload \\ %{})
send_event(session, event)
session_update(session, session_payload)

Functions

close(session)

@spec close(ReqLLM.OpenAI.Realtime.Session.t()) :: :ok

connect(model_spec \\ "gpt-realtime", opts \\ [])

@spec connect(
  ReqLLM.model_input() | String.t(),
  keyword()
) :: {:ok, ReqLLM.OpenAI.Realtime.Session.t()} | {:error, term()}

next_event(session, timeout \\ 30000)

@spec next_event(ReqLLM.OpenAI.Realtime.Session.t(), timeout()) ::
  {:ok, map()} | :halt | {:error, term()}

next_projected_event(session)

@spec next_projected_event(ReqLLM.OpenAI.Realtime.Session.t()) ::
  {:ok, ReqLLM.OpenAI.Realtime.Event.t()} | :halt | {:error, term()}

Receives one raw event and returns its provider-native and exact portable views.

Sensitive text, audio transcript, tool, and error payloads are redacted by default. Pass payloads: :raw only when the consumer is authorized to retain model and tool content. This function does not loop, reconnect, execute tools, or continue a response.

next_projected_event(session, opts)

@spec next_projected_event(ReqLLM.OpenAI.Realtime.Session.t(), timeout() | keyword()) ::
  {:ok, ReqLLM.OpenAI.Realtime.Event.t()} | :halt | {:error, term()}

next_projected_event(session, timeout, opts)

@spec next_projected_event(
  ReqLLM.OpenAI.Realtime.Session.t(),
  non_neg_integer(),
  keyword()
) ::
  {:ok, ReqLLM.OpenAI.Realtime.Event.t()} | :halt | {:error, term()}

project_event(event, opts \\ [])

@spec project_event(
  map(),
  keyword()
) :: ReqLLM.OpenAI.Realtime.Event.t()

Projects one already-decoded OpenAI Realtime server event.

The returned ReqLLM.OpenAI.Realtime.Event always retains a native view. stream_events is empty when no exact provider-neutral meaning exists. Supplying the resolved :model allows response.created to project to the canonical :start event.

response_create(session, response_payload \\ %{})

@spec response_create(ReqLLM.OpenAI.Realtime.Session.t(), map()) ::
  :ok | {:error, term()}

send_event(session, event)

@spec send_event(ReqLLM.OpenAI.Realtime.Session.t(), map()) :: :ok | {:error, term()}

session_update(session, session_payload)

@spec session_update(ReqLLM.OpenAI.Realtime.Session.t(), map()) ::
  :ok | {:error, term()}