API Reference allm v#0.6.1

Provider-neutral LLM execution for Elixir, with first-class streaming and serializable conversation state.

Non-streaming provider adapter contract.

A serializable audio value, used as transcription input and as speech synthesis output. Layer A serializable data.

Reducers and adapters for streamed audio. Layer C, pure functions over enumerables.

Layer-B optional model-catalog integration via the LLMDB Hex package.

The result of a full chat loop — Layer A serializable data.

Typed-classification provider adapter contract.

The typed answer to one ALLM.ClassificationQuestion — Layer A serializable data.

One typed question inside an ALLM.ClassificationRequest — Layer A serializable data.

A typed-classification request — Layer A serializable data.

A typed-classification response — Layer A serializable data.

A single embedding vector — Layer A serializable data.

Text-embedding provider adapter contract.

A text-embedding request — Layer A serializable data.

A text-embedding response — 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 returned by typed-classification adapters.

Errors returned by ALLM.EmbeddingAdapter implementations.

Errors raised by engine-level operations before any adapter call.

Errors returned by ALLM.ImageAdapter implementations.

Errors returned by ALLM.ModerationAdapter implementations.

Session-state error. Returned (or raised) by ALLM.Session operations.

Errors returned by speech-synthesis adapters.

Errors that surface mid-stream.

Errors from tool handler execution.

Errors returned by transcription adapters.

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 or editing — Layer A serializable data.

An image generation or edit response — Layer A serializable data.

Image-side usage and cost summary — Layer A serializable data.

Shared helpers for JSON-Schema maps consumed by adapters.

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.

Content-moderation provider adapter contract.

A content-moderation request — Layer A serializable data.

A content-moderation response — Layer A serializable data.

One content-moderation verdict — Layer A serializable data.

Anthropic provider adapter — Layer B.

ElevenLabs text-to-speech adapter. Implements ALLM.SpeechAdapter against POST /v1/text-to-speech/{voice_id}.

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).

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 typed-classification testing. Implements ALLM.ClassificationAdapter.

Deterministic, scripted adapter for text-embedding testing. Implements ALLM.EmbeddingAdapter.

Deterministic, scripted adapter for image-generation testing. Implements ALLM.ImageAdapter.

Deterministic, scripted adapter for content-moderation testing. Implements ALLM.ModerationAdapter.

Deterministic, scripted adapter for text-to-speech testing. Implements ALLM.SpeechAdapter and ALLM.SpeechStreamAdapter, including the optional input-streaming callback.

Deterministic, scripted adapter for speech-to-text testing. Implements ALLM.TranscriptionAdapter and ALLM.TranscriptionStreamAdapter.

Google Gemini provider adapter — Layer B. (bundled adapters).

Google Gemini text-embeddings provider adapter — implements ALLM.EmbeddingAdapter against batchEmbedContents.

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]`. Any other operation 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 in `generate/2` of `lib/allm/providers/openai/images.ex`. ## 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 `decode_with_candidates/2` in `lib/allm/providers/gemini.ex`, 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.

Google Gemini speech-to-text adapter. Implements ALLM.TranscriptionAdapter against generateContent.

OpenAI provider adapter — Layer B.

OpenAI text-embeddings provider adapter — implements ALLM.EmbeddingAdapter against OpenAI's POST /v1/embeddings endpoint.

OpenAI Images provider adapter — implements ALLM.ImageAdapter against OpenAI's /v1/images/generations and /v1/images/edits endpoints.

OpenAI content-moderation provider adapter — implements ALLM.ModerationAdapter against OpenAI's POST /v1/moderations endpoint.

OpenAI text-to-speech adapter. Implements ALLM.SpeechAdapter and ALLM.SpeechStreamAdapter against POST /v1/audio/speech.

OpenAI speech-to-text adapter. Implements ALLM.TranscriptionAdapter against POST /v1/audio/transcriptions.

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.

Shared HTTP-header builder for Gemini provider adapters. See spec (bundled adapters) and the design's the documented contract.

Provider-neutral HTTP helpers shared by the bundled Req-based adapters.

Per-provider MIME and size validation for ALLM.ImagePart content.

Reduces a caller-supplied input enumerable in a helper process and hands its elements to an owner process under a credit window.

Shared HTTP-header builder for OpenAI provider adapters. the documented contract.

Per-provider credential redactors shared by the bundled adapters.

Stateless line-buffered Server-Sent Events (SSE) decoder.

The shared half of the bundled ALLM.SpeechAdapter and ALLM.SpeechStreamAdapter implementations that speak HTTP.

The shared half of the bundled ALLM.TranscriptionAdapter implementations.

Shared HTTP-transport option handling and Finch async plumbing for the streaming provider adapters.

The WebSocket transport seam the streaming audio adapters are written against.

The owner-side loop shared by the WebSocket input-stream adapters: a socket that speaks while an ALLM.Providers.Support.InputPump feeds it.

The default ALLM.Providers.Support.WebSocket implementation, over Mint.WebSocket.

TypeSafe typed-classification adapter (Jev). Implements ALLM.ClassificationAdapter.

Voyage AI text-embeddings provider adapter — and the Anthropic track.

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.

Per-process engine resolution for tests — Layer B test-injection helper.

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.

Text-to-speech provider adapter contract.

Closed tagged-tuple union emitted by a streaming speech-synthesis call. Layer A data.

A text-to-speech request. Layer A serializable data.

A text-to-speech response. Layer A serializable data.

Streaming text-to-speech contract: audio arrives as it is synthesized.

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.

Compact tool disclosure: stub projection, on-demand help, and the built-in tool_help meta-tool.

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.

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.

Speech-to-text provider adapter contract.

Closed tagged-tuple union emitted by a streaming transcription call. Layer A data.

A speech-to-text request. Layer A serializable data.

A speech-to-text response. Layer A serializable data.

Realtime speech-to-text contract: transcripts arrive while audio is still being sent.

The configuration of a streaming (realtime) transcription session. Layer A serializable data.

Token and cost usage for a single response — Layer A serializable data.

Pure validators for Layer A input shapes.