LemonAi.Providers.OpenAIResponsesShared (lemon_ai v0.1.0)

Shared utilities for OpenAI Responses API family.

This module provides common message conversion, tool conversion, and stream processing logic used by:

OpenAI Responses API
OpenAI Codex Responses API (ChatGPT Plus/Pro)
Azure OpenAI Responses API

Summary

Types

message_options()

reasoning_effort()

reasoning_summary()

stream_options()

tool_options()

Functions

apply_service_tier_pricing(usage, service_tier)

Apply service tier pricing to usage.

calculate_cost(model, usage)

Calculate cost based on model pricing.

clamp_function_call_outputs(params)

Clamp oversized function_call_output payload items in a prebuilt Responses API request.

convert_messages(model, context, allowed_tool_call_providers, opts \\ %{})

Convert context messages to OpenAI Responses API input format.

convert_tools(tools, opts \\ %{})

Convert tools to OpenAI Responses API format.

parse_streaming_json(json)

Parse potentially incomplete JSON for streaming tool arguments. Returns a map with whatever can be parsed.

process_stream(events, output, stream, model, opts \\ %{})

Process OpenAI Responses API stream events and emit to EventStream.

sanitize_surrogates(str)

Sanitize unicode surrogates from a string. Some APIs reject unpaired surrogate characters.

service_tier_cost_multiplier(arg1)

Get cost multiplier for service tier.

short_hash(str)

Fast deterministic hash to shorten long strings. Used for truncating message IDs to fit OpenAI's 64-char limit.

transform_messages(messages, model, allowed_tool_call_providers)

Transform messages for cross-provider compatibility. Normalizes tool call IDs and handles thinking blocks.

Types

message_options()

@type message_options() :: %{optional(:include_system_prompt) => boolean()}

reasoning_effort()

@type reasoning_effort() :: :minimal | :low | :medium | :high | :xhigh | :none

reasoning_summary()

@type reasoning_summary() :: :auto | :detailed | :concise | :off | :on | nil

stream_options()

@type stream_options() :: %{
  optional(:service_tier) => String.t() | nil,
  optional(:apply_service_tier_pricing) => (LemonAi.Types.Usage.t(),
                                            String.t()
                                            | nil ->
                                              LemonAi.Types.Usage.t())
}

tool_options()

@type tool_options() :: %{optional(:strict) => boolean() | nil}

Functions

apply_service_tier_pricing(usage, service_tier)

@spec apply_service_tier_pricing(LemonAi.Types.Usage.t(), String.t() | nil) ::
  LemonAi.Types.Usage.t()

Apply service tier pricing to usage.

calculate_cost(model, usage)

@spec calculate_cost(LemonAi.Types.Model.t(), LemonAi.Types.Usage.t()) ::
  LemonAi.Types.Usage.t()

Calculate cost based on model pricing.

clamp_function_call_outputs(params)

@spec clamp_function_call_outputs(map()) :: map()

Clamp oversized function_call_output payload items in a prebuilt Responses API request.

This is a final safety net for request payloads and complements truncation during message conversion. It prevents provider 400 errors when any input[*].output field exceeds the Responses API maximum string size.

convert_messages(model, context, allowed_tool_call_providers, opts \\ %{})

@spec convert_messages(
  LemonAi.Types.Model.t(),
  LemonAi.Types.Context.t(),
  MapSet.t(atom()),
  message_options()
) :: [map()]

Convert context messages to OpenAI Responses API input format.

Options

:include_system_prompt - Whether to include system prompt (default: true)

convert_tools(tools, opts \\ %{})

@spec convert_tools([LemonAi.Types.Tool.t()], tool_options()) :: [map()]

Convert tools to OpenAI Responses API format.

Options

:strict - Whether to enforce strict mode (default: false, nil means omit)

parse_streaming_json(json)

@spec parse_streaming_json(String.t()) :: map()

Parse potentially incomplete JSON for streaming tool arguments. Returns a map with whatever can be parsed.

process_stream(events, output, stream, model, opts \\ %{})

@spec process_stream(
  Enumerable.t(),
  LemonAi.Types.AssistantMessage.t(),
  LemonAi.EventStream.t(),
  LemonAi.Types.Model.t(),
  stream_options()
) :: {:ok, LemonAi.Types.AssistantMessage.t()} | {:error, term()}

Process OpenAI Responses API stream events and emit to EventStream.

sanitize_surrogates(str)

@spec sanitize_surrogates(String.t()) :: String.t()

Sanitize unicode surrogates from a string. Some APIs reject unpaired surrogate characters.

service_tier_cost_multiplier(arg1)

@spec service_tier_cost_multiplier(String.t() | nil) :: float()

Get cost multiplier for service tier.

short_hash(str)

@spec short_hash(String.t()) :: String.t()

Fast deterministic hash to shorten long strings. Used for truncating message IDs to fit OpenAI's 64-char limit.

transform_messages(messages, model, allowed_tool_call_providers)

@spec transform_messages([map()], LemonAi.Types.Model.t(), MapSet.t(atom())) :: [
  map()
]

Transform messages for cross-provider compatibility. Normalizes tool call IDs and handles thinking blocks.