# allm v0.6.1 - Table of Contents

Provider-neutral LLM execution for Elixir with first-class streaming, tool calling, and serializable sessions.

## Pages

- [ALLM](readme.md)
- [CHANGELOG](changelog.md)

- Guides
  - [Getting started](getting_started.md)
  - [Streaming](streaming.md)
  - [Tools](tools.md)
  - [Sessions](sessions.md)
  - [Vision input](vision.md)
  - [Image generation](image_generation.md)
  - [Embeddings](embeddings.md)
  - [Content moderation](moderation.md)
  - [Typed classification](classification.md)
  - [Audio: speech and transcription](audio.md)
  - [Errors and retries](errors_and_retries.md)
  - [Multi-tenant keys (BYOK)](multi_tenant_keys.md)
  - [Testing with Fake](fakes.md)

## Modules

- Facade
  - [ALLM](ALLM.md): Provider-neutral LLM execution for Elixir, with first-class streaming and
serializable conversation state.

- Sessions
  - [ALLM.Session](ALLM.Session.md): A stateful, serializable chat session — Layer A data + Layer D
continuation operations.
  - [ALLM.Session.StreamReducer](ALLM.Session.StreamReducer.md): Folds an `ALLM.stream/3` (or `ALLM.stream_step/3`) event stream into
both an updated `%ALLM.Session{}` and a terminal `%ALLM.ChatResult{}`
(or `%ALLM.StepResult{}`) in one pass.

- Behaviours
  - [ALLM.Adapter](ALLM.Adapter.md): Non-streaming provider adapter contract.
  - [ALLM.ClassificationAdapter](ALLM.ClassificationAdapter.md): Typed-classification provider adapter contract.
  - [ALLM.EmbeddingAdapter](ALLM.EmbeddingAdapter.md): Text-embedding provider adapter contract.
  - [ALLM.ImageAdapter](ALLM.ImageAdapter.md): Image-generation provider adapter contract.
  - [ALLM.ModerationAdapter](ALLM.ModerationAdapter.md): Content-moderation provider adapter contract.
  - [ALLM.SpeechAdapter](ALLM.SpeechAdapter.md): Text-to-speech provider adapter contract.
  - [ALLM.SpeechStreamAdapter](ALLM.SpeechStreamAdapter.md): Streaming text-to-speech contract: audio arrives as it is synthesized.
  - [ALLM.StreamAdapter](ALLM.StreamAdapter.md): Streaming provider adapter contract.
  - [ALLM.ToolExecutor](ALLM.ToolExecutor.md): Tool-handler invocation contract.
  - [ALLM.ToolResultEncoder](ALLM.ToolResultEncoder.md): Serialize a tool's return value into a string the model can consume.
  - [ALLM.TranscriptionAdapter](ALLM.TranscriptionAdapter.md): Speech-to-text provider adapter contract.
  - [ALLM.TranscriptionStreamAdapter](ALLM.TranscriptionStreamAdapter.md): Realtime speech-to-text contract: transcripts arrive while audio is still
being sent.

- Providers
  - [ALLM.Providers.Anthropic](ALLM.Providers.Anthropic.md): Anthropic provider adapter — Layer B.
  - [ALLM.Providers.ElevenLabs.Speech](ALLM.Providers.ElevenLabs.Speech.md): ElevenLabs text-to-speech adapter. Implements `ALLM.SpeechAdapter`
against `POST /v1/text-to-speech/{voice_id}`.
  - [ALLM.Providers.ElevenLabs.Transcription](ALLM.Providers.ElevenLabs.Transcription.md): ElevenLabs speech-to-text adapter (Scribe). Implements
`ALLM.TranscriptionAdapter` against `POST /v1/speech-to-text` and
`ALLM.TranscriptionStreamAdapter` against the realtime WebSocket
`wss://<host>/v1/speech-to-text/realtime` (see `stream_transcribe/3`).
  - [ALLM.Providers.Fake](ALLM.Providers.Fake.md): Deterministic, scripted adapter for testing. Implements both `ALLM.Adapter`
and `ALLM.StreamAdapter`.
  - [ALLM.Providers.Fake.Script](ALLM.Providers.Fake.Script.md): Script shape detection, validation, and interpretation for
`ALLM.Providers.Fake`.
  - [ALLM.Providers.FakeClassification](ALLM.Providers.FakeClassification.md): Deterministic, scripted adapter for typed-classification testing.
Implements `ALLM.ClassificationAdapter`.
  - [ALLM.Providers.FakeEmbeddings](ALLM.Providers.FakeEmbeddings.md): Deterministic, scripted adapter for text-embedding testing. Implements
`ALLM.EmbeddingAdapter`.
  - [ALLM.Providers.FakeImages](ALLM.Providers.FakeImages.md): Deterministic, scripted adapter for image-generation testing. Implements
`ALLM.ImageAdapter`.
  - [ALLM.Providers.FakeModeration](ALLM.Providers.FakeModeration.md): Deterministic, scripted adapter for content-moderation testing. Implements
`ALLM.ModerationAdapter`.
  - [ALLM.Providers.FakeSpeech](ALLM.Providers.FakeSpeech.md): Deterministic, scripted adapter for text-to-speech testing. Implements
`ALLM.SpeechAdapter` and `ALLM.SpeechStreamAdapter`, including the
optional input-streaming callback.
  - [ALLM.Providers.FakeTranscription](ALLM.Providers.FakeTranscription.md): Deterministic, scripted adapter for speech-to-text testing. Implements
`ALLM.TranscriptionAdapter` and `ALLM.TranscriptionStreamAdapter`.
  - [ALLM.Providers.Gemini](ALLM.Providers.Gemini.md): Google Gemini provider adapter — Layer B.
 (bundled adapters).
  - [ALLM.Providers.Gemini.Embeddings](ALLM.Providers.Gemini.Embeddings.md): Google Gemini text-embeddings provider adapter — implements
`ALLM.EmbeddingAdapter` against `batchEmbedContents`.
  - [ALLM.Providers.Gemini.Images](ALLM.Providers.Gemini.Images.md): Google Gemini native image-out adapter — implements `ALLM.ImageAdapter`
against `generateContent` with `responseModalities: ["TEXT", "IMAGE"]`
on the Gemini-native image preview models (`gemini-3.1-flash-image-preview`
/ "Nano Banana 2", `gemini-3-pro-image-preview` / "Nano Banana Pro").
and ``.
  - [ALLM.Providers.Gemini.Transcription](ALLM.Providers.Gemini.Transcription.md): Google Gemini speech-to-text adapter. Implements `ALLM.TranscriptionAdapter`
against `generateContent`.
  - [ALLM.Providers.OpenAI](ALLM.Providers.OpenAI.md): OpenAI provider adapter — Layer B.
  - [ALLM.Providers.OpenAI.Embeddings](ALLM.Providers.OpenAI.Embeddings.md): OpenAI text-embeddings provider adapter — implements `ALLM.EmbeddingAdapter`
against OpenAI's `POST /v1/embeddings` endpoint.
  - [ALLM.Providers.OpenAI.Images](ALLM.Providers.OpenAI.Images.md): OpenAI Images provider adapter — implements `ALLM.ImageAdapter` against
OpenAI's `/v1/images/generations` and `/v1/images/edits` endpoints.
  - [ALLM.Providers.OpenAI.Moderation](ALLM.Providers.OpenAI.Moderation.md): OpenAI content-moderation provider adapter — implements
`ALLM.ModerationAdapter` against OpenAI's `POST /v1/moderations` endpoint.
  - [ALLM.Providers.OpenAI.Speech](ALLM.Providers.OpenAI.Speech.md): OpenAI text-to-speech adapter. Implements `ALLM.SpeechAdapter` and
`ALLM.SpeechStreamAdapter` against `POST /v1/audio/speech`.
  - [ALLM.Providers.OpenAI.Transcription](ALLM.Providers.OpenAI.Transcription.md): OpenAI speech-to-text adapter. Implements `ALLM.TranscriptionAdapter`
against `POST /v1/audio/transcriptions`.
  - [ALLM.Providers.Support.ElevenLabs](ALLM.Providers.Support.ElevenLabs.md): The half of the ElevenLabs audio adapters that both of them share:
the base URL, the auth header, the `output_format` mapping, error
classification and key redaction.
  - [ALLM.Providers.Support.GeminiHeaders](ALLM.Providers.Support.GeminiHeaders.md): Shared HTTP-header builder for Gemini provider adapters. See spec
 (bundled adapters) and the design's the documented contract.
  - [ALLM.Providers.Support.HTTPResponse](ALLM.Providers.Support.HTTPResponse.md): Provider-neutral HTTP helpers shared by the bundled `Req`-based adapters.
  - [ALLM.Providers.Support.ImageMime](ALLM.Providers.Support.ImageMime.md): Per-provider MIME and size validation for `ALLM.ImagePart` content.
  - [ALLM.Providers.Support.InputPump](ALLM.Providers.Support.InputPump.md): Reduces a caller-supplied input enumerable in a helper process and hands
its elements to an owner process under a credit window.
  - [ALLM.Providers.Support.OpenAIHeaders](ALLM.Providers.Support.OpenAIHeaders.md): Shared HTTP-header builder for OpenAI provider adapters.
the documented contract.
  - [ALLM.Providers.Support.Redact](ALLM.Providers.Support.Redact.md): Per-provider credential redactors shared by the bundled adapters.
  - [ALLM.Providers.Support.SSE](ALLM.Providers.Support.SSE.md): Stateless line-buffered Server-Sent Events (SSE) decoder.
  - [ALLM.Providers.Support.SpeechAdapter](ALLM.Providers.Support.SpeechAdapter.md): The shared half of the bundled `ALLM.SpeechAdapter` and
`ALLM.SpeechStreamAdapter` implementations that speak HTTP.
  - [ALLM.Providers.Support.TranscriptionAdapter](ALLM.Providers.Support.TranscriptionAdapter.md): The shared half of the bundled `ALLM.TranscriptionAdapter` implementations.
  - [ALLM.Providers.Support.Transport](ALLM.Providers.Support.Transport.md): Shared HTTP-transport option handling and `Finch` async plumbing for the
streaming provider adapters.
  - [ALLM.Providers.Support.WebSocket](ALLM.Providers.Support.WebSocket.md): The WebSocket transport seam the streaming audio adapters are written
against.
  - [ALLM.Providers.Support.WebSocket.InputLoop](ALLM.Providers.Support.WebSocket.InputLoop.md): The owner-side loop shared by the WebSocket input-stream adapters: a
socket that speaks while an `ALLM.Providers.Support.InputPump` feeds it.
  - [ALLM.Providers.Support.WebSocket.Mint](ALLM.Providers.Support.WebSocket.Mint.md): The default `ALLM.Providers.Support.WebSocket` implementation, over
`Mint.WebSocket`.
  - [ALLM.Providers.TypeSafe.Classification](ALLM.Providers.TypeSafe.Classification.md): TypeSafe typed-classification adapter (Jev). Implements
`ALLM.ClassificationAdapter`.
  - [ALLM.Providers.Voyage.Embeddings](ALLM.Providers.Voyage.Embeddings.md): Voyage AI text-embeddings provider adapter — **and the Anthropic track**.

- Defaults
  - [ALLM.ToolExecutor.Default](ALLM.ToolExecutor.Default.md): Default `ALLM.ToolExecutor` — invokes the tool's `:handler` function
directly, dispatching on arity (1 or 2). Converts raises / exits /
throws / invalid returns / nil handlers to `%ALLM.Error.ToolError{}`;
passes handler-returned values (`{:ok, _}`, `{:error, _}`,
`{:ask_user, _}`, `{:ask_user, _, _}`, `{:halt, _, _}`) through
unchanged.
  - [ALLM.ToolResultEncoder.JSON](ALLM.ToolResultEncoder.JSON.md): Default `ALLM.ToolResultEncoder` — JSON-encodes the tool return value
via `Jason.encode!/1`, with targeted passthrough / unwrap shortcuts so
handlers that pre-format a string for the model aren't double-encoded.

- Data types
  - [ALLM.Audio](ALLM.Audio.md): A serializable audio value, used as transcription input and as speech
synthesis output. Layer A serializable data.
  - [ALLM.ChatResult](ALLM.ChatResult.md): The result of a full chat loop — Layer A serializable data.
  - [ALLM.ClassificationAnswer](ALLM.ClassificationAnswer.md): The typed answer to one `ALLM.ClassificationQuestion` — Layer A
serializable data.
  - [ALLM.ClassificationQuestion](ALLM.ClassificationQuestion.md): One typed question inside an `ALLM.ClassificationRequest` — Layer A
serializable data.
  - [ALLM.ClassificationRequest](ALLM.ClassificationRequest.md): A typed-classification request — Layer A serializable data.
  - [ALLM.ClassificationResponse](ALLM.ClassificationResponse.md): A typed-classification response — Layer A serializable data.
  - [ALLM.Embedding](ALLM.Embedding.md): A single embedding vector — Layer A serializable data.
  - [ALLM.EmbeddingRequest](ALLM.EmbeddingRequest.md): A text-embedding request — Layer A serializable data.
  - [ALLM.EmbeddingResponse](ALLM.EmbeddingResponse.md): A text-embedding response — Layer A serializable data.
  - [ALLM.Event](ALLM.Event.md): Closed tagged-tuple union emitted by stream runners — Layer A
serializable data.
  - [ALLM.Image](ALLM.Image.md): A serializable image value used by image generation, editing, and vision
inputs — Layer A serializable data.
  - [ALLM.ImagePart](ALLM.ImagePart.md): An image content part used in multimodal `ALLM.Message{:content}` lists
— Layer A serializable data.
  - [ALLM.ImageRequest](ALLM.ImageRequest.md): A request for image generation or editing — Layer A serializable data.
  - [ALLM.ImageResponse](ALLM.ImageResponse.md): An image generation or edit response — Layer A serializable data.
  - [ALLM.ImageUsage](ALLM.ImageUsage.md): Image-side usage and cost summary — Layer A serializable data.
  - [ALLM.JsonSchema](ALLM.JsonSchema.md): Shared helpers for JSON-Schema maps consumed by adapters.
  - [ALLM.Message](ALLM.Message.md): A chat message — Layer A serializable data.
  - [ALLM.ModelRef](ALLM.ModelRef.md): A model reference returned by an optional model-catalog integration
Layer A serializable data.
  - [ALLM.ModerationRequest](ALLM.ModerationRequest.md): A content-moderation request — Layer A serializable data.
  - [ALLM.ModerationResponse](ALLM.ModerationResponse.md): A content-moderation response — Layer A serializable data.
  - [ALLM.ModerationResult](ALLM.ModerationResult.md): One content-moderation verdict — Layer A serializable data.
  - [ALLM.Request](ALLM.Request.md): A single LLM request — Layer A serializable data.
  - [ALLM.Response](ALLM.Response.md): A single LLM response — Layer A serializable data.
  - [ALLM.SpeechEvent](ALLM.SpeechEvent.md): Closed tagged-tuple union emitted by a streaming speech-synthesis call.
Layer A data.
  - [ALLM.SpeechRequest](ALLM.SpeechRequest.md): A text-to-speech request. Layer A serializable data.
  - [ALLM.SpeechResponse](ALLM.SpeechResponse.md): A text-to-speech response. Layer A serializable data.
  - [ALLM.StepResult](ALLM.StepResult.md): The result of a single chat step — Layer A serializable data.
  - [ALLM.TextPart](ALLM.TextPart.md): A text content part used in multimodal `ALLM.Message{:content}` lists
— Layer A serializable data.
  - [ALLM.Thread](ALLM.Thread.md): An ordered message log — Layer A serializable data.
  - [ALLM.Tool](ALLM.Tool.md): A tool the model may call — Layer A serializable data plus an optional
runtime `:handler`.
  - [ALLM.ToolCall](ALLM.ToolCall.md): A provider-emitted tool call — Layer A serializable data.
  - [ALLM.TranscriptSpan](ALLM.TranscriptSpan.md): One timed or scored unit of a transcript: a word, the spacing between
two words, a non-speech audio event, or a model token. Layer A
serializable data.
  - [ALLM.TranscriptionEvent](ALLM.TranscriptionEvent.md): Closed tagged-tuple union emitted by a streaming transcription call.
Layer A data.
  - [ALLM.TranscriptionRequest](ALLM.TranscriptionRequest.md): A speech-to-text request. Layer A serializable data.
  - [ALLM.TranscriptionResponse](ALLM.TranscriptionResponse.md): A speech-to-text response. Layer A serializable data.
  - [ALLM.TranscriptionStreamRequest](ALLM.TranscriptionStreamRequest.md): The configuration of a streaming (realtime) transcription session.
Layer A serializable data.
  - [ALLM.Usage](ALLM.Usage.md): Token and cost usage for a single response — Layer A serializable data.

- Runtime
  - [ALLM.AudioStream](ALLM.AudioStream.md): Reducers and adapters for streamed audio. Layer C, pure functions over
enumerables.
  - [ALLM.Capability](ALLM.Capability.md): Layer-B optional model-catalog integration via the `LLMDB` Hex package.
  - [ALLM.Engine](ALLM.Engine.md): Layer-B runtime engine — the composition point for an adapter, declared
tools, and default request params/context.
  - [ALLM.Keys](ALLM.Keys.md): API key resolution. Keys never appear on the engine — they resolve at
adapter-call time, so a serialized engine is safe to persist.
  - [ALLM.Retry](ALLM.Retry.md): Layer-B retry helper consumed by non-streaming adapters and by the
image façade.
  - [ALLM.Sandbox](ALLM.Sandbox.md): Per-process engine resolution for tests — Layer B test-injection helper.
  - [ALLM.Serializer](ALLM.Serializer.md): Tagged JSON encoding and decoding for Layer A structs.
  - [ALLM.StreamCollector](ALLM.StreamCollector.md): Reduce a stream of `ALLM.Event` values into a collected `%ALLM.Response{}`,
`%ALLM.StepResult{}`, or `%ALLM.ChatResult{}`.
  - [ALLM.Telemetry](ALLM.Telemetry.md): Layer-B helper that wraps `:telemetry.span/3` with ALLM-specific
metadata defaults.
  - [ALLM.ToolHelp](ALLM.ToolHelp.md): Compact tool disclosure: stub projection, on-demand help, and the built-in
`tool_help` meta-tool.
  - [ALLM.Validate](ALLM.Validate.md): Pure validators for Layer A input shapes.

- Internals
  - [ALLM.Chat](ALLM.Chat.md): > #### Internal {: .warning}
>
> This module is internal — it's documented for transparency, but call
> sites should use `ALLM.step/3`, `ALLM.stream_step/3`, `ALLM.chat/3`,
> or `ALLM.stream/3` instead.
  - [ALLM.Runner](ALLM.Runner.md): > #### Internal {: .warning}
>
> This module is internal — it's documented for transparency, but
> call sites should use `ALLM.generate/3` instead.
  - [ALLM.StreamRunner](ALLM.StreamRunner.md): > #### Internal {: .warning}
>
> This module is internal — it's documented for transparency, but
> call sites should use `ALLM.stream_generate/3` instead.
  - [ALLM.ToolRunner](ALLM.ToolRunner.md): > #### Internal {: .warning}
>
> This module is internal — it's documented for transparency, but call
> sites should use `ALLM.step/3` / `ALLM.stream_step/3` instead.

- Errors
  - [ALLM.Error.AdapterError](ALLM.Error.AdapterError.md): Errors returned by `ALLM.Adapter` / `ALLM.StreamAdapter` implementations.
  - [ALLM.Error.ClassificationAdapterError](ALLM.Error.ClassificationAdapterError.md): Errors returned by typed-classification adapters.
  - [ALLM.Error.EmbeddingAdapterError](ALLM.Error.EmbeddingAdapterError.md): Errors returned by `ALLM.EmbeddingAdapter` implementations.
  - [ALLM.Error.EngineError](ALLM.Error.EngineError.md): Errors raised by engine-level operations before any adapter call.
  - [ALLM.Error.ImageAdapterError](ALLM.Error.ImageAdapterError.md): Errors returned by `ALLM.ImageAdapter` implementations.
  - [ALLM.Error.ModerationAdapterError](ALLM.Error.ModerationAdapterError.md): Errors returned by `ALLM.ModerationAdapter` implementations.
  - [ALLM.Error.SessionError](ALLM.Error.SessionError.md): Session-state error. Returned (or raised) by `ALLM.Session` operations.
  - [ALLM.Error.SpeechAdapterError](ALLM.Error.SpeechAdapterError.md): Errors returned by speech-synthesis adapters.
  - [ALLM.Error.StreamError](ALLM.Error.StreamError.md): Errors that surface mid-stream.
  - [ALLM.Error.ToolError](ALLM.Error.ToolError.md): Errors from tool handler execution.
  - [ALLM.Error.TranscriptionAdapterError](ALLM.Error.TranscriptionAdapterError.md): Errors returned by transcription adapters.
  - [ALLM.Error.ValidationError](ALLM.Error.ValidationError.md): Errors returned by `ALLM.Validate` functions.

