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:

  1. 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.
  2. 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.
  3. Otherwise it is vendored here or lives outside. Vendored adapters go under LlmCall.Media.Dialect.* (media) and are listed in LlmCall.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.* or LlmCall.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:

  1. Start from the adapter macro (use LlmCall.Dialect.Adapter, codec: ... with @path/@headers, or use LlmCall.Media.Dialect.Adapter, ... with a modality), then implement every callback it does not inject. Implement init_stream/2, decode_stream_event/3, finish_stream/2 only when the protocol streams.

  2. Return Codec.Info with the correct ir_version and wire version.

  3. Validate before encoding. encode_* returns {:error, %LlmCall.Error{kind: :validation}} for anything the protocol cannot express. Never drop a canonical field silently.

  4. Declare capabilities that match validation. A size you 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: :unsupported must reject every n, and max_references must accept exactly that many references. Both conformance suites check these in both directions.

  5. Use LlmCall.Dialect.Helpers for error formatting, maybe_put, reserved-key checks, and the capture_raw policy, so the suite can assert behaviour consistently. Declare the namespaces you read (@namespaces, or namespaces: on use LlmCall.Media.Dialect.Adapter) and validate them with Helpers.validate_option_map/4: an unknown namespace is a validation error, because a silently ignored provider_options key is a silent drop.

  6. Keep fixtures honest. Elixir maps, no JSON strings, no network. Copy the provider's documented response shape; do not invent one.

  7. 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_raw on 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:

  1. Confirm @source_url in mix.exs. It is an assumption until the repository exists, and Hex freezes the links and source URL for a published version.
  2. mix ci is green on both supported toolchains (Elixir 1.18/OTP 27 and the current toolchain).
  3. mix hex.build shows 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.