# allm v0.5.0 - 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)
  - [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.EmbeddingAdapter](ALLM.EmbeddingAdapter.md): Text-embedding provider adapter contract.
  - [ALLM.ImageAdapter](ALLM.ImageAdapter.md): Image-generation provider adapter contract.
  - [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.

- Providers
  - [ALLM.Providers.Anthropic](ALLM.Providers.Anthropic.md): Anthropic provider adapter — Layer B.
  - [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.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.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.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`, `/v1/images/edits`, and
`/v1/images/variations` endpoints.
  - [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.ImageMime](ALLM.Providers.Support.ImageMime.md): Per-provider MIME and size validation for `ALLM.ImagePart` content.
  - [ALLM.Providers.Support.OpenAIHeaders](ALLM.Providers.Support.OpenAIHeaders.md): Shared HTTP-header builder for OpenAI provider adapters.
the documented contract.
  - [ALLM.Providers.Support.SSE](ALLM.Providers.Support.SSE.md): Stateless line-buffered Server-Sent Events (SSE) decoder.
  - [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.ChatResult](ALLM.ChatResult.md): The result of a full chat loop — 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, editing, or variation — Layer A
serializable data.
  - [ALLM.ImageResponse](ALLM.ImageResponse.md): An image generation/edit/variation 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.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.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.Usage](ALLM.Usage.md): Token and cost usage for a single response — Layer A serializable data.

- Runtime
  - [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.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.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.SessionError](ALLM.Error.SessionError.md): Session-state error. Returned (or raised) by `ALLM.Session` operations.
  - [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.ValidationError](ALLM.Error.ValidationError.md): Errors returned by `ALLM.Validate` functions.