All notable changes to this project are documented here. The format follows Keep a Changelog, and the project adheres to Semantic Versioning.
Unreleased
0.1.0 - 2026-11-20
Added
- One-call client:
LlmCall.complete/3,stream/3,generate/3,poll/3,execute/2,fetch/2, withLlmCall.Provider(use LlmCall.Provider) and%LlmCall.Client{}. HTTP is Finch; JSON is theLlmCall.JSONfacade over Elixir's built-inJSON, selected at compile time withjson_library:; Torque, Jason and Poison work directly. Calls acceptheaders:merged after the client headers and before the codec's protocol headers. - A provider-level
query:(or aquery:client option) adds URL parameters to every request, for vendors that key on one — MiniMax'sGroupId, Azure OpenAI'sapi-version. A codec's own parameter wins on the same key, and the Responses WebSocket handshake inherits the same parameters. LlmCall.Error.retry_after_mscarries the parsedRetry-Afterhint; retry policy stays outside the core.LlmCall.Error.reasoncarries the structured transport reason (:econnrefused,:timeout,:unknown_pool, ...), so callers match on it instead of parsing the message.LlmCall.HTTP.build_url/3joins a base URL, a request path and an encoded query on theURIstruct, keeping the base path. The client and the Responses WebSocket handshake both use it, so a caller that owns a transport joins its URLs the way the library does.LlmCall.Codec.Conformance.assert_replays/3pins which decoded content parts a codec accepts back in an assistant message, the contract an agent loop depends on;docs/design.md§8.2 carries the table.config :llm_call, capture_raw: ...sets the compile-time capture default, symmetric withjson_library:;LlmCall.Config.new(capture_raw: ...)still overrides it per client.- Codecs validate the types of known native
provider_optionskeys (access_programs,logprobs,metadata,safetySettings, ...); unknown native keys still pass through. - WebSocket transport: the
LlmCall.WSbehaviour andLlmCall.WS.Mint, with the upgrade, text/binary frames, ping handling and peer close. Mint's HTTP proxy options are forwarded (ws://forward proxy,wss://CONNECT). - Responses WebSocket connection: one socket multiplexed by
stream_id,Connection.response_id/2forprevious_response_id,response.create/response.steer/response.cancel, per-lane event decoding, and reconnect before the 60-minute limit. Reconnect failures keep the connection process alive with exponential backoff; while disconnected, creates return a:transporterror. In-flight responses are reported as interrupted, not silently resumed. No realtime audio session. - Streaming in the library:
LlmCall.SSEframing,LlmCall.Streamas a lazyEnumerable,stream/3'son_event:observer, andLlmCall.HTTP.Errorfor mid-stream failures. - Provider-hosted tools:
ToolSpec{kind: :builtin}forwarded verbatim andCapabilities.builtin_tools. - Canonical wire IR:
Request,Message,Content,ToolSpec,ToolCall,ToolResult,Reasoning,Response,Usage,Error,Capabilities,Config,EncodedRequest. LlmCall.Codecbehaviour and the public dispatch API, with typed errors for every unsupported field.- Reference adapters: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini GenerateContent.
- Adapter authoring macros:
LlmCall.Dialect.Adapterinjects the behaviour, aliases, andencode_request/2;LlmCall.Media.Dialect.Adapteradditionally injects the shared media validation pipeline. Shared rules live inLlmCall.Dialect.Helpers. provider_optionsis validated, not just merged: a codec reserves the wire keys it derives from canonical fields, rejects a namespace it does not read, and refuses aConfigdefault that would override an explicit request.- Streaming primitives (
StreamEvent,StreamDelta,StreamState) and the pureStreamAssembler. - Media IR:
LlmCall.Media.{Request,Response,Capabilities,Codec},LlmCall.Operation, and theencode_media/3…decode_operation/3API for synchronous and long-running generation. - Vendored media adapters: OpenAI Images, Gemini Imagen
predict, Seedance (BytePlus ModelArk), MiniMax Hailuo. - Conformance suites published from
lib/:LlmCall.Codec.ConformanceandLlmCall.Media.Conformance, covering response/error decoding, stream order, the streaming signal on an encoded request, tool-call assembly,capture_raw, and capability↔validation consistency. - Documentation:
docs/design.md(canonical spec) andCONTRIBUTING.md(adapter bar).
Fixed
http_opts: [receive_timeout: ...]was validated and then dropped: the client always forwards the request's own timeout. It is now anArgumentErrorthat points attimeout:, and any key the client would drop is rejected the same way.- A CRLF split across two body chunks ended an SSE event early, which broke the
documented newline join for multi-line
data:fields. ToolCall.arguments_errorcarried the raw arguments in one path and a decoder message in another.raw_argumentsis now the only place the payload lives:{:invalid_json, reason}always carries a message, and a missing decoder is:no_json_decoder.response.steerandresponse.cancelcarriedstream_id, which the provider does not route them by: a steer carriesprevious_response_idand a cancel carriesresponse_id. Steering a lane that has not receivedresponse.createdis a:validationerror instead of an untenanted event.- A Responses connection whose server does not echo
stream_id(the endpoint does for named lanes) no longer accepts a second concurrent lane once an event has proven the echo is missing, because that lane's events could not be routed and the connection would drop every in-flight response with an opaqueunroutable_event. Back-to-back creates before the first event stay allowed. LlmCall.Configmerged provider-option namespaces one level deep, so a nesteddefault_provider_optionskey was dropped as soon as the request set a sibling key inside the same object — for six of the eight codecs; Gemini already deep-merged. The merge is now recursive for every codec.Error.rawcarried the provider error envelope whatevercapture_rawsaid, whileResponse.raw,StreamEvent.rawandOperation.rawhonoured it. It now follows the same policy, so:nonekeeps no provider payload at all. The conformance suites check it for completion and media codecs.LlmCall.Media.Dialect.Gemini.Predictaccepted a non-stringparams.negative_promptand put it on the wire; it is now a:validationerror like its sibling knobs.- A query string in
base_url(https://…/openai?api-version=1) was glued in front of the codec path over HTTP, producing/openai?api-version=1/v1/…on the wire; the WebSocket handshake already merged it. It is now folded into the client'squeryat build time, with an explicitquery:winning. - The Anthropic codec emitted server tools as
{"type": …}alone, but the API requires the callablenameas well (web_searchnext toweb_search_20250305). It is now derived from the type's date suffix and can be overridden throughprovider_options.anthropic. - The Anthropic codec accepted
thinking.budget_tokensfrom 1 upward; the API requires at least 1024 and less thanmax_tokens, so both bounds are validation errors now. Usage.total_tokensfor Anthropic counted onlyinput_tokens + output_tokens, while the API definesinput_tokensas the tokens after the last cache breakpoint: cache creation and cache reads were missing from the total.- The Anthropic
anthropic-versionheader was pinned to2023-06-01; it now sends the version the provider's own SDK sends,2026-10-21. A codec header wins over a client header, so the pin was not overridable. - The OpenAI Chat and Responses codecs rejected
reasoning effort: :xhighand:max, whichReasoningEffortaccepts, and theirUsage.cache_write_tokenswas alwaysnilalthough both usage breakdowns report it (prompt_tokens_details.cache_write_tokens,input_tokens_details.cache_write_tokens). - The OpenAI Responses codec replayed an assistant turn with
output_textcontent parts, which are not valid in an input content list: the documentedinputshape allowsinput_text,input_image, andinput_file, and an assistant turn is either an easy-input message with those parts or the original output item with its id. It now emitsinput_text. - The Gemini codec mapped most
finishReasonvalues to:unknown. The documented set now maps as it reads:CONTINUATION(a resumable token-limit stop) to:max_tokens, the content-policy family (safety, recitation, language, blocklist, prohibited content, SPII, the image variants, escalation) to:content_filter, and the failed-generation reasons (MALFORMED_FUNCTION_CALL,UNEXPECTED_TOOL_CALL,TOO_MANY_TOOL_CALLS,MISSING_THOUGHT_SIGNATURE,MALFORMED_RESPONSE,NO_IMAGE,IMAGE_OTHER,PUP_LIMITED_DISABLED) to:error. - The OpenAI Images codec sent
response_format: "b64_json"todall-e-*models. That parameter is legacy for the retired DALL·E models and is unsupported by the GPT image models, which always return base64; it is now only sent when a caller sets it throughprovider_options.openai. - The Seedance video codec dropped the task's token usage; a finished task reports
completion_tokensandtotal_tokens, which now land onLlmCall.Media.Response.usage.