Protocol for decoding provider responses and SSE events to canonical ReqLLM structures.

This protocol handles both non-streaming response decoding and streaming SSE event processing, converting provider-specific formats to canonical ReqLLM structures.

Default Implementation

The Map implementation provides baseline OpenAI-compatible decoding for common providers that use the ChatCompletions API format (OpenAI, Groq, OpenRouter, xAI):

# Non-streaming response decoding
ReqLLM.Response.Codec.decode_response(response_json, model)
#=> {:ok, %ReqLLM.Response{message: %ReqLLM.Message{...}, usage: %{...}}}

# Streaming SSE event decoding
ReqLLM.Response.Codec.decode_sse_event(sse_event, model) 
#=> [%ReqLLM.StreamChunk{type: :content, text: "Hello"}]

Provider-Specific Overrides

Providers with unique response formats implement their own protocol:

defimpl ReqLLM.Response.Codec, for: MyProvider.Response do
  def decode_response(data, model) do
    # Custom decoding logic for provider-specific format
  end

  def decode_sse_event(event, model) do
    # Custom SSE event processing
  end
end

Response Pipeline

1. Raw provider response → decode_response/2 → ReqLLM.Response struct
2. SSE event → decode_sse_event/2 → List of StreamChunk structs