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

Layer B — runtime. Constructed via ALLM.Engine.new(embed_adapter: ALLM.Providers.OpenAI.Embeddings, model: "text-embedding-3-small") and consumed through ALLM.embed/3. Keys resolve via ALLM.Keys.fetch!(:openai, opts) at request-build time — no key ever lives on the engine.

req = ALLM.EmbeddingRequest.new(input: ["hello"], model: "text-embedding-3-small")
{:ok, resp} = ALLM.Providers.OpenAI.Embeddings.embed(req, api_key: "sk-...")
[[_ | _]] = ALLM.EmbeddingResponse.vectors(resp)

Wire-field map

Adapter-injected defaults

None. The wire requires model, and ALLM.EmbeddingRequest permits model: nil. This adapter does not invent a default model: a nil :model is OMITTED from the body and OpenAI answers with a 400, surfaced as %ALLM.Error.EmbeddingAdapterError{reason: :invalid_request}. Guessing an embedding model would silently produce vectors of an unexpected dimensionality into a caller's vector column, which is unrecoverable after the fact. ALLM.embed/3 stamps the engine's resolved model onto the request before dispatch, so this only arises on a direct adapter call.

:task_type is dropped

ALLM.EmbeddingRequest's provider-neutral :task_type enum has no OpenAI equivalent. The adapter drops the field rather than erroring, and logs the drop at :debug. A caller who needs asymmetric query/document embedding should use a provider that supports it.

Truncation

:truncate is a no-op here, in both directions: OpenAI answers an over-length input with a 400 rather than silently truncating it, so there is no wire field to carry either value. The field is neither sent nor treated as an error.

Token budget vs. batch size

max_batch_size/0 is 2048 — the array-item cap. OpenAI separately caps a single request at 300,000 tokens summed across all inputs, which is reachable far below 2048 items when the inputs are long. That rejection arrives as a 400 and maps to %ALLM.Error.EmbeddingAdapterError{reason: :context_length_exceeded}. ALLM ships no tokenizer and will not guess token counts, so the recovery is yours: lower your effective batch size and re-drive ALLM.embed/3, or chunk against max_batch_size/0 yourself with a smaller stride.

Reduced dimensions

dimensions: is supported only on text-embedding-3 and later. Setting it on text-embedding-ada-002 is rejected pre-flight with %ALLM.Error.EmbeddingAdapterError{reason: :unsupported_feature, metadata: %{feature: :dimensions, model: model}} — the adapter can see the request is malformed without spending a round-trip.

Pre-flight gates

Before any HTTP I/O — and, deliberately, before ALLM.Keys.fetch!/2, so a request that is going to be rejected never needs a valid API key:

1. Empty input. input: [] → :invalid_request.
2. Batch size. length(input) > 2048 → :batch_too_large with metadata: %{count: n, max: 2048}. An :input that is not a list at all — OpenAI's own wire accepts a bare string, so it is the likeliest direct-adapter mistake — is rejected here as :invalid_request with metadata: %{field: :input} rather than raising.
3. Feature support. dimensions: on a model with no such knob → :unsupported_feature.

Capability pre-flight against a model catalog is NOT performed here — it lives in ALLM.embed/3. A direct adapter call bypasses it by design.

Response ordering

data[] is sorted by :index before it becomes :embeddings. OpenAI documents that field precisely because array order is not contractual, and ALLM.EmbeddingResponse's order-correspondence invariant depends on it.

Request-id preservation

opts[:request_id] is reflected onto response.request_id unchanged. When it is absent, the adapter falls back to OpenAI's x-request-id response header. request.metadata round-trips onto response.metadata untouched.

Error-struct hygiene

%ALLM.Error.EmbeddingAdapterError{} derives Jason.Encoder and is commonly logged and persisted, so this adapter never copies a raw response body, a request header, or any Authorization value into :cause, :metadata, or :message. Provider error messages pass through a redactor that replaces key-shaped tokens with [REDACTED] — OpenAI echoes a prefix of the offending key back in its 401 text.

Retry integration

HTTP-error closures return {:retry, delay_ms, error} for 429 (honouring Retry-After), 5xx, timeouts, and transport failures; ALLM.Retry.run/3 is wrapped around each attempt. The closure returns real reason atoms rather than swapping in HTTP status codes, so for :rate_limited, :provider_unavailable, and :network_error the façade's widened retry_on list is what decides — none of them appears in this adapter's own opts[:retry] policy, which defaults to :default.

:timeout is the documented exception: it is a member of both lists, so through ALLM.embed/3 the adapter's inner ALLM.Retry.run/3 and the façade's outer one both retry it and the attempt budgets multiply (3 × 3 = 9 HTTP attempts at the default policy, against 3 for every other retryable reason). A direct embed/2 call takes the inner loop only and makes 3. ALLM.Providers.OpenAI.Images has the byte-identical shape through ALLM.generate_image/3, so this is a pre-existing library-wide characteristic rather than an embeddings one; it is tracked in ASKS.md and binding on 20.5 / 20.6 — do not "fix" it per-adapter, because the correction has to land in the façade and both image adapters at once.

Test-injection escape hatch

embed/2 honours opts[:adapter_opts][:embedding_script] as a documented test-only short-circuit: when the key is present, the call delegates to ALLM.Providers.FakeEmbeddings.embed/2 BEFORE any pre-flight gate runs and returns its result verbatim. This is what lets the injectable ALLM.EmbeddingAdapter conformance suite drive a real adapter without an HTTP stub library.

The switch keys on the presence of that per-call key and nothing else — no environment variable, no application config, no :persistent_term — so it stays confined to an explicit argument. Setting adapter_opts already implies full control of the call. Production callers do not populate it.

prepare_request/2 deliberately does NOT delegate under the same key: a scripted response has no Req.Request analogue, so it returns a stub error instead.