responses

Codec for the OpenAI Responses API (/v1/responses) and the equivalent ChatGPT Codex route (/codex/responses).

Pure JSON in, structured Gleam out. No IO. Composed by callers with pig_protocol/auth, pig_protocol/transport, and pig_protocol/sse.

Values

build_request_body

</>

pub fn build_request_body(
  messages: List(message.Message),
  tools: List(tool_definition.ToolDefinition),
  model: String,
  instructions: option.Option(String),
) -> String

Build the JSON request body for the OpenAI Responses API.

Messages are mapped to the Responses input format:

User -> input message with input_text content.
System -> ignored; pass system prompt via instructions.
Assistant -> input assistant message with output_text content.
Tool -> function_call_output item. Pure function — no IO.

build_request_body_with_thinking

</>

pub fn build_request_body_with_thinking(
  messages: List(message.Message),
  tools: List(tool_definition.ToolDefinition),
  model: String,
  instructions: option.Option(String),
  thinking_level: option.Option(thinking.ThinkingLevel),
) -> String

Build a Responses API request with an optional thinking level.

OpenAI receives this as reasoning.effort. When thinking is enabled the request also asks for an automatic provider-generated reasoning summary. Unsupported levels are reported by the provider API.

build_stream_request_body

</>

pub fn build_stream_request_body(
  messages: List(message.Message),
  tools: List(tool_definition.ToolDefinition),
  model: String,
  instructions: option.Option(String),
) -> String

Build a Responses request body for an SSE response.

build_stream_request_body_with_thinking

</>

pub fn build_stream_request_body_with_thinking(
  messages: List(message.Message),
  tools: List(tool_definition.ToolDefinition),
  model: String,
  instructions: option.Option(String),
  thinking_level: option.Option(thinking.ThinkingLevel),
) -> String

Build a streaming Responses request with an optional thinking level.

parse_response

</>

pub fn parse_response(
  raw: String,
) -> Result(inference.InferenceResult, error.AiError)

Parse an OpenAI Responses API JSON response into an InferenceResult. Pure function — no IO.