# allm v0.3.0 - API Reference

## Modules

- Facade
  - [ALLM](ALLM.md): Top-level facade for the ALLM library — provider-neutral LLM execution with
first-class streaming and serializable conversation state.

- Sessions
  - [ALLM.Session](ALLM.Session.md): A stateful, serializable chat session. See spec §5.7 and §11.
  - [ALLM.Session.StreamReducer](ALLM.Session.StreamReducer.md): Folds an `ALLM.Chat.stream/3` (or `ALLM.Chat.stream_step/3`) event
stream into both an updated `%ALLM.Session{}` and a terminal
`%ALLM.ChatResult{}` (or `%ALLM.StepResult{}`) in one pass. See spec
§13.2 and `steering/PHASE_8_DESIGN.md` Decision #15.

- Behaviours
  - [ALLM.Adapter](ALLM.Adapter.md): Non-streaming provider adapter contract. See spec §7.1.
  - [ALLM.ImageAdapter](ALLM.ImageAdapter.md): Image-generation provider adapter contract. See spec §35.3.
  - [ALLM.StreamAdapter](ALLM.StreamAdapter.md): Streaming provider adapter contract. See spec §7.2.
  - [ALLM.ToolExecutor](ALLM.ToolExecutor.md): Tool-handler invocation contract. See spec §7.3 and §5.2.
  - [ALLM.ToolResultEncoder](ALLM.ToolResultEncoder.md): Serialize a tool's return value into a string the model can consume. See
spec §7.4 and §18.

- Providers
  - [ALLM.Providers.Anthropic](ALLM.Providers.Anthropic.md): Anthropic provider adapter — Layer B. See spec §6.4, §7.1, §20, §32.1.
  - [ALLM.Providers.Fake](ALLM.Providers.Fake.md): Deterministic, scripted adapter for testing. Implements both `ALLM.Adapter`
and `ALLM.StreamAdapter`. See spec §31, §7.1, §7.2, §8.
  - [ALLM.Providers.Fake.Script](ALLM.Providers.Fake.Script.md): Script shape detection, validation, and interpretation for
`ALLM.Providers.Fake`. See spec §31.
  - [ALLM.Providers.FakeImages](ALLM.Providers.FakeImages.md): Deterministic, scripted adapter for image-generation testing. Implements
`ALLM.ImageAdapter`. See spec §35.8.
  - [ALLM.Providers.Gemini](ALLM.Providers.Gemini.md): Google Gemini provider adapter — Layer B. See spec §6.4, §7.1, §20,
§32.1 (bundled adapters).
  - [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").
See spec §35.3, §35.7 and `steering/GEMINI_DESIGN.md` Phase 16.5.
  - [ALLM.Providers.OpenAI](ALLM.Providers.OpenAI.md): OpenAI provider adapter — Layer B. See spec §6.4, §7.1, §20, §32.1.
  - [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. See spec §35.7.
  - [ALLM.Providers.Support.GeminiHeaders](ALLM.Providers.Support.GeminiHeaders.md): Shared HTTP-header builder for Gemini provider adapters. See spec
§32.1 (bundled adapters) and the Phase 16 design's Decision #2.
  - [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. See spec §35.7
Decision #11.
  - [ALLM.Providers.Support.SSE](ALLM.Providers.Support.SSE.md): Stateless line-buffered Server-Sent Events (SSE) decoder.

- 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. See spec §5.9.
  - [ALLM.Event](ALLM.Event.md): Closed tagged-tuple union emitted by stream runners. See spec §8.
  - [ALLM.Image](ALLM.Image.md): A serializable image value used by image generation, editing, and vision
inputs. See spec §35.2.1.
  - [ALLM.ImagePart](ALLM.ImagePart.md): An image content part used in multimodal `ALLM.Message{:content}` lists.
See spec §35.6.
  - [ALLM.ImageRequest](ALLM.ImageRequest.md): A request for image generation, editing, or variation. See spec §35.2.2.
  - [ALLM.ImageResponse](ALLM.ImageResponse.md): An image generation/edit/variation response. See spec §35.2.3.
  - [ALLM.ImageUsage](ALLM.ImageUsage.md): Image-side usage and cost summary. See spec §35.2.4.
  - [ALLM.Message](ALLM.Message.md): A chat message. See spec §5.1 and §35.6.
  - [ALLM.ModelRef](ALLM.ModelRef.md): Layer A — model reference returned by the optional `LLMDB` catalog.
  - [ALLM.Request](ALLM.Request.md): A single LLM request. See spec §5.4.
  - [ALLM.Response](ALLM.Response.md): A single LLM response. See spec §5.5.
  - [ALLM.StepResult](ALLM.StepResult.md): The result of a single chat step. See spec §5.8.
  - [ALLM.TextPart](ALLM.TextPart.md): A text content part used in multimodal `ALLM.Message{:content}` lists. See
spec §35.6.
  - [ALLM.Thread](ALLM.Thread.md): An ordered message log. See spec §5.6 and §14.
  - [ALLM.Tool](ALLM.Tool.md): A tool the model may call. See spec §5.2 and §15.
  - [ALLM.ToolCall](ALLM.ToolCall.md): A provider-emitted tool call. See spec §5.3.
  - [ALLM.Usage](ALLM.Usage.md): Token and cost usage for a single response. See spec §5.9a.

- 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 — see spec §6.
  - [ALLM.Keys](ALLM.Keys.md): API key resolution per spec §6.4. Keys never appear on the engine.
  - [ALLM.Retry](ALLM.Retry.md): Internal — Layer B retry helper consumed by adapters.
  - [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{}`. See spec §13.1.
  - [ALLM.Telemetry](ALLM.Telemetry.md): Internal — 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. See spec §16 and Phase 1 design
sub-phase 1.4.

- Internals
  - [ALLM.Chat](ALLM.Chat.md): Internal — use `ALLM.step/3` / `ALLM.stream_step/3` / `ALLM.chat/3` /
`ALLM.stream/3` instead. See spec §17.
  - [ALLM.Runner](ALLM.Runner.md): Internal — use `ALLM.generate/3` instead. See spec §17.
  - [ALLM.StreamRunner](ALLM.StreamRunner.md): Internal — use `ALLM.stream_generate/3` instead. See spec §17.
  - [ALLM.ToolRunner](ALLM.ToolRunner.md): Internal — use `ALLM.step/3` / `ALLM.stream_step/3` instead. See spec §17.

- Errors
  - [ALLM.Error.AdapterError](ALLM.Error.AdapterError.md): Errors returned by `ALLM.Adapter` / `ALLM.StreamAdapter` 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 Phase 8's `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.