Which behaviour to implement
- A completion endpoint (messages, system prompt, tools) →
use LlmCall.Dialect.Adapter(LlmCall.Codec). - A dedicated media endpoint (image/video generation, possibly long-running) →
use LlmCall.Media.Dialect.Adapter(LlmCall.Media.Codec).
Both macros inject the behaviour, the canonical aliases, @codec, and the shared
validation entry point; see docs/design.md (§10, §23.5).
A third kind of contribution is a seam implementation: LlmCall.JSON
(encode/1, decode/1, tagged tuples). It is a behaviour with a default; a
replacement must keep the error shapes documented in docs/design.md §8.9,
because callers branch on kind. HTTP is Finch, and a WebSocket transport
implements LlmCall.WS.
Where an adapter belongs
Three questions, in order:
- Does it need a canonical concept the IR lacks? Then it is a design
discussion in core first; the adapter waits for the IR. Do not smuggle a new
concept through
provider_options. - Is it the first implementation of a dialect family — an envelope shape other providers copy? Then it is a candidate for a core reference adapter. Adding one requires the same justification as adding an IR field: it teaches the IR something the current set cannot express.
- Otherwise it is vendored here or lives outside. Vendored adapters go under
LlmCall.Media.Dialect.*(media) and are listed inLlmCall.Media; anything else is your own module or a third-party package.
Reference adapters are OpenAI Chat, OpenAI Responses, Anthropic Messages, and Gemini GenerateContent. Vendored media adapters are OpenAI Images, Gemini Imagen, Seedance, and MiniMax. Everything else — Bedrock, Cohere, Ollama, Mistral, Sora, Veo — is written outside this repository.
Namespace rules
- Vendored adapters live under
LlmCall.Media.Dialect.*and are documented as vendored: they ship with the library but are not part of the stable API surface, because a provider API can change independently of the IR. - Out-of-tree adapters use their own top-level namespace; never define
LlmCall.Dialect.*orLlmCall.Media.Dialect.*, which core owns. - No canonical struct changes from an adapter. If the IR is wrong, that is a core discussion.
The quality bar
Every adapter must:
Start from the adapter macro (
use LlmCall.Dialect.Adapter, codec: ...with@path/@headers, oruse LlmCall.Media.Dialect.Adapter, ...with a modality), then implement every callback it does not inject. Implementinit_stream/2,decode_stream_event/3,finish_stream/2only when the protocol streams.Return
Codec.Infowith the correctir_versionand wireversion.Validate before encoding.
encode_*returns{:error, %LlmCall.Error{kind: :validation}}for anything the protocol cannot express. Never drop a canonical field silently.Declare capabilities that match validation. A
sizeyou declare must be accepted; a knob you reject must be absent from the declaration. For media, a modality you declare must be accepted,max_n: :unsupportedmust reject everyn, andmax_referencesmust accept exactly that many references. Both conformance suites check these in both directions.Use
LlmCall.Dialect.Helpersfor error formatting,maybe_put, reserved-key checks, and thecapture_rawpolicy, so the suite can assert behaviour consistently. Declare the namespaces you read (@namespaces, ornamespaces:onuse LlmCall.Media.Dialect.Adapter) and validate them withHelpers.validate_option_map/4: an unknown namespace is a validation error, because a silently ignoredprovider_optionskey is a silent drop.Keep fixtures honest. Elixir maps, no JSON strings, no network. Copy the provider's documented response shape; do not invent one.
Run the conformance suite in your own tests:
LlmCall.Codec.Conformance.assert_info(MyCodec) LlmCall.Codec.Conformance.assert_capabilities(MyCodec, stream_request, config) LlmCall.Codec.Conformance.assert_path(MyCodec, request, "/v1/my-endpoint") LlmCall.Codec.Conformance.assert_stream_request(MyCodec, request) LlmCall.Codec.Conformance.assert_reserved_options(MyCodec, request, config, [ %{my_codec: %{"model" => "evil"}} ]) LlmCall.Codec.Conformance.assert_decode_response(MyCodec, response_fixture) LlmCall.Codec.Conformance.assert_invalid_response(MyCodec, %{"unexpected" => true}) LlmCall.Codec.Conformance.assert_decode_error(MyCodec, error_fixture, code: "rate_limit", retryable?: true) LlmCall.Codec.Conformance.assert_stream(MyCodec, stream_request, chunks) LlmCall.Codec.Conformance.assert_stream_capture_raw(MyCodec, stream_request, chunks) LlmCall.Codec.Conformance.assert_tool_call_assembly(MyCodec, stream_request, tool_chunks, 1) LlmCall.Codec.Conformance.assert_capability_consistency(MyCodec, request, config) LlmCall.Codec.Conformance.assert_capture_raw(MyCodec, response_fixture) LlmCall.Codec.Conformance.assert_stream_roundtrip(MyCodec, stream_request) LlmCall.Codec.Conformance.assert_stream_state_ownership(MyCodec, OtherCodec, request) LlmCall.Codec.Conformance.assert_rejects(MyCodec, invalid_request, %LlmCall.Config{}) LlmCall.Codec.Conformance.assert_replays(MyCodec, request, text: :ok, tool_call: :ok, thinking: :rejected, raw: :rejected)or, for media,
LlmCall.Media.Conformance(assert_info/1,assert_capabilities/3,assert_capability_consistency/3,assert_submit_path/3,assert_capture_raw/2,assert_operation/1,assert_operation_capture_raw/3,assert_sync_rejects_operation/1— see the module docs).The suites check the IR boundary (canonical parts, stop reasons, usage shapes), typed invalid-response and provider-error decoding, stream event shape and order, that a streaming request actually asks the provider to stream, tool-call assembly through
LlmCall.StreamAssembler,capture_rawon responses, errors and operations, which decoded parts a request accepts back, and capability declarations agreeing with validation in both directions. What they cannot check is usage mapping — which provider field lands in which counter — so pin that with your own fixture assertions.
Tests
Run the full quality gate before finishing:
mix ci
It compiles with warnings as errors, checks formatting, runs the suite,
credo --strict, Dialyzer, SpecLint (with warnings as errors), ExDNA at a zero
clone budget, and the Reach architecture policy. The vendored media adapters run
the media conformance suite in the same mix test.
The client and streaming paths run against LlmCall.TestHTTPServer, and the
WebSocket transport against LlmCall.TestWSServer; both bind 127.0.0.1 on an
ephemeral port. LlmCall.MarkerJSON proves the JSON seam is honoured.
mix ci runs ExDNA with a zero clone budget (see mix.exs): the protocol
adapters are deliberately parallel, but any logic clone fails the build, so a
shared rule belongs in LlmCall.Dialect.Helpers.
Publishing
Before the first mix hex.publish:
- Confirm
@source_urlinmix.exs. It is an assumption until the repository exists, and Hex freezes the links and source URL for a published version. mix ciis green on both supported toolchains (Elixir 1.18/OTP 27 and the current toolchain).mix hex.buildshows the expected package name, license, and file list.
The zero clone budget in mix.exs applies to published versions too: a new clone
fails the gate, so shared logic belongs in LlmCall.Dialect.Helpers.
Documentation
Every module under lib/ and test/support/ has a moduledoc — no
@moduledoc false. A test enforces this.