LlmCall.Codec behaviour (llm_call v0.1.0)

Copy Markdown View Source

The behaviour every dialect adapter implements.

A codec turns a canonical request into one protocol's wire request, and one provider's response terms into canonical responses and stream events. It does no IO: transports parse framing and decode JSON, codecs only map terms.

Streaming callbacks are optional so a non-streaming codec need not implement dummy functions; LlmCall returns a typed error when a caller asks a codec for streaming it does not implement.

Streaming state is passed as LlmCall.StreamState, which the codec reads with LlmCall.StreamState.data/1 and rebuilds with LlmCall.StreamState.new/2.

Summary

Callbacks

capabilities(t, t)

@callback capabilities(
  LlmCall.Request.t(),
  LlmCall.Config.t()
) :: LlmCall.Capabilities.t()

decode_error(wire_value, t)

@callback decode_error(
  LlmCall.wire_value(),
  LlmCall.Config.t()
) :: LlmCall.Error.t()

decode_response(wire_value, t)

@callback decode_response(
  LlmCall.wire_value(),
  LlmCall.Config.t()
) :: {:ok, LlmCall.Response.t()} | {:error, LlmCall.Error.t()}

decode_stream_event(wire_value, t, t)

(optional)
@callback decode_stream_event(
  LlmCall.wire_value(),
  LlmCall.Config.t(),
  LlmCall.StreamState.t()
) ::
  {:ok, [LlmCall.StreamEvent.t()], LlmCall.StreamState.t()}
  | {:done, LlmCall.StreamState.t()}
  | {:error, LlmCall.Error.t()}

encode_request(t, t)

@callback encode_request(
  LlmCall.Request.t(),
  LlmCall.Config.t()
) :: {:ok, LlmCall.EncodedRequest.t()} | {:error, LlmCall.Error.t()}

finish_stream(t, t)

(optional)
@callback finish_stream(
  LlmCall.StreamState.t(),
  LlmCall.Config.t()
) ::
  {:ok, [LlmCall.StreamEvent.t()], LlmCall.StreamState.t()}
  | {:error, LlmCall.Error.t()}

info()

@callback info() :: LlmCall.Codec.Info.t()

init_stream(t, t)

(optional)
@callback init_stream(
  LlmCall.Request.t(),
  LlmCall.Config.t()
) :: {:ok, LlmCall.StreamState.t()} | {:error, LlmCall.Error.t()}

validate_request(t, t)

@callback validate_request(
  LlmCall.Request.t(),
  LlmCall.Config.t()
) :: :ok | {:error, LlmCall.Error.t()}