Modules
Provider-neutral LLM execution for Elixir, with first-class streaming and serializable conversation state.
Non-streaming provider adapter contract.
Layer-B optional model-catalog integration via the LLMDB Hex package.
The result of a full chat loop — Layer A serializable data.
Layer-B runtime engine — the composition point for an adapter, declared tools, and default request params/context.
Errors returned by ALLM.Adapter / ALLM.StreamAdapter implementations.
Errors raised by engine-level operations before any adapter call.
Errors returned by ALLM.ImageAdapter implementations.
Session-state error. Returned (or raised) by ALLM.Session operations.
Errors that surface mid-stream.
Errors from tool handler execution.
Errors returned by ALLM.Validate functions.
Closed tagged-tuple union emitted by stream runners — Layer A serializable data.
A serializable image value used by image generation, editing, and vision inputs — Layer A serializable data.
Image-generation provider adapter contract.
An image content part used in multimodal ALLM.Message{:content} lists
— Layer A serializable data.
A request for image generation, editing, or variation — Layer A serializable data.
An image generation/edit/variation response — Layer A serializable data.
Image-side usage and cost summary — Layer A serializable data.
API key resolution. Keys never appear on the engine — they resolve at adapter-call time, so a serialized engine is safe to persist.
A chat message — Layer A serializable data.
A model reference returned by an optional model-catalog integration Layer A serializable data.
Anthropic provider adapter — Layer B.
Deterministic, scripted adapter for testing. Implements both ALLM.Adapter
and ALLM.StreamAdapter.
Script shape detection, validation, and interpretation for
ALLM.Providers.Fake.
Deterministic, scripted adapter for image-generation testing. Implements
ALLM.ImageAdapter.
Google Gemini provider adapter — Layer B. (bundled adapters).
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 . Layer B — runtime. Consumed through the `ALLM.generate_image/3` façade. Keys resolve via `ALLM.Keys.fetch!(:gemini, opts)` at request-build time per the documented contract — no key ever lives on the engine. ## Single translator Image generation is `generateContent` with `responseModalities` toggled to `["TEXT", "IMAGE"]`. The request body is built by `ALLM.Providers.Gemini.to_gemini_request_body/2` (the same translator the chat adapter uses). The image adapter then overrides `generationConfig.responseModalities` and adds `generationConfig.imageConfig.aspectRatio` from the the documented contract size-mapping table. The `:edit` operation reuses 's `part_to_block/1` for source-image translation by synthesizing a user-role message with `[%TextPart{}, %ImagePart{},...]` content. ## Aspect-ratio mapping | ALLM `ImageRequest.size` | Gemini `imageConfig.aspectRatio` | |--------------------------|----------------------------------| | `"1024x1024"`, `"512x512"`, `"256x256"`, any square | `"1:1"` | | `"1792x1024"`, any 16:9 | `"16:9"` | | `"1024x1792"`, any 9:16 | `"9:16"` | | `"1024x768"`, any 4:3 | `"4:3"` | | `"768x1024"`, any 3:4 | `"3:4"` | | `nil` | omit `imageConfig` (Gemini default) | | anything else | `{:error, %ImageAdapterError{reason: :invalid_request}}` | Pixel sizing (`imageSize: "1K"|"2K"|"4K"`) is not exposed in v0.2's `ImageRequest.size` field; deferred. Aspect-ratio is the only knob. ## Operation gate `supported_operations/0` returns `[:generate, :edit]`. `:variation` is rejected with `:unsupported_operation` BEFORE any HTTP I/O per `ImageAdapter` invariant 4. ## Test-injection escape hatch `opts[:adapter_opts][:image_script]`, when present, delegates to `ALLM.Providers.FakeImages.generate/2` BEFORE any pre-flight gate runs. Mirrors the OpenAI.Images precedent at `lib/allm/providers/openai/images.ex:251`. ## Shared response decoder (Cross-function invariant) Response bodies are decoded via `ALLM.Providers.Gemini.Decode.candidate_parts/1` — the same helper `Gemini.generate/2` calls (see `lib/allm/providers/gemini.ex:991` post-Phase-16.5 refactor). The image adapter consumes the `image_parts` element of the returned tuple while the chat adapter consumes `text` + `tool_calls`; both walk the parts list once. Per cross-function invariants
lines 217-219.
OpenAI provider adapter — Layer B.
OpenAI Images provider adapter — implements ALLM.ImageAdapter against
OpenAI's /v1/images/generations, /v1/images/edits, and
/v1/images/variations endpoints.
Shared HTTP-header builder for Gemini provider adapters. See spec (bundled adapters) and the design's the documented contract.
Per-provider MIME and size validation for ALLM.ImagePart content.
Shared HTTP-header builder for OpenAI provider adapters. the documented contract.
Stateless line-buffered Server-Sent Events (SSE) decoder.
A single LLM request — Layer A serializable data.
A single LLM response — Layer A serializable data.
Layer-B retry helper consumed by non-streaming adapters and by the image façade.
Tagged JSON encoding and decoding for Layer A structs.
A stateful, serializable chat session — Layer A data + Layer D continuation operations.
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.
The result of a single chat step — Layer A serializable data.
Streaming provider adapter contract.
Reduce a stream of ALLM.Event values into a collected %ALLM.Response{},
%ALLM.StepResult{}, or %ALLM.ChatResult{}.
Layer-B helper that wraps :telemetry.span/3 with ALLM-specific
metadata defaults.
A text content part used in multimodal ALLM.Message{:content} lists
— Layer A serializable data.
An ordered message log — Layer A serializable data.
A tool the model may call — Layer A serializable data plus an optional
runtime :handler.
A provider-emitted tool call — Layer A serializable data.
Tool-handler invocation contract.
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.
Serialize a tool's return value into a string the model can consume.
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.
Token and cost usage for a single response — Layer A serializable data.
Pure validators for Layer A input shapes.