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

Layer B — runtime. FakeEmbeddings is the canonical testing embedding adapter; it ships in lib/ (not test/support/) because users need it for their own application tests, mirroring the ALLM.Providers.Fake and ALLM.Providers.FakeImages precedent.

What FakeEmbeddings is (and isn't)

FakeEmbeddings mostly ignores the %ALLM.EmbeddingRequest{} passed to embed/2. It does inspect :input to enforce the empty-input and batch-size gates that the ALLM.EmbeddingAdapter contract requires of every implementation, and reads :model / :metadata to round-trip onto the response; otherwise the scripted response is produced irrespective of the request. In particular the scripted vectors are not derived from the input strings, and the script — not length(input) — decides how many embeddings come back.

Script shapes

opts[:adapter_opts][:embedding_script] accepts a list of script entries. See script/1 for the full grammar.

adapter_opts: [
  embedding_script: [
    {:ok, [%ALLM.Embedding{...}]},
    {:ok, [%ALLM.Embedding{...}], usage: %ALLM.Usage{...}},
    {:error, %ALLM.Error.EmbeddingAdapterError{reason: :rate_limited}},
    {:retry_until_call, 3}
  ]
]

{:retry_until_call, n} returns a synthetic %ALLM.Error.EmbeddingAdapterError{reason: :rate_limited, retry_after_ms: 0} for the first n - 1 calls against this entry, then advances the cursor to the next entry on call n. Vehicle for testing ALLM.Retry.run/3 integration in ALLM.embed/3. Consecutive {:retry_until_call, _} entries chain: the call that exhausts one entry's budget lands on the next entry and opens its budget, which is how a layered retry budget is scripted.

Multi-call scripting uses the same list — each call advances a process-local cursor (or an explicit Agent cursor passed via adapter_opts[:script_cursor] from start_script_cursor/0).

Cursor behaviour

Multi-call scripts (:embedding_script) advance a per-process cursor on every call. The cursor lives in the process dictionary at {:allm_fake_embeddings_cursor, key_id}, isolated per ExUnit test process (async: true), GC'd on pid-down, zero-setup for the common case. The key_id is chosen by this precedence:

1. adapter_opts[:script_cursor] — an explicit Agent pid (handled separately; see start_script_cursor/0).
2. adapter_opts[:cursor_key] — the engine's stable :id, injected by the façade dispatch chokepoint via ALLM.Engine.put_cursor_key/2.
3. :erlang.phash2(script) — the content-hash fallback for direct adapter calls with no engine.

At the façade the cursor keys on engine identity, so two engines built with content-equal :embedding_script values each read index 0 on their first call, even in the same process. The content-hash footgun remains only for DIRECT adapter calls — ALLM.Providers.FakeEmbeddings.embed(req, opts) invoked without an engine receives no :cursor_key. Workaround for that path: pass distinct adapter_opts[:script_cursor] Agent pids from start_script_cursor/0.

Test-only capture seam

Pass adapter_opts[:capture_pid] with a pid to receive a side-channel message every time embed/2 is invoked, BEFORE any gate runs and before the script is consulted. The message has the form:

{ALLM.Providers.FakeEmbeddings, :call, %{request: request, opts: opts}}

This is purely a side-channel — it does NOT affect the response. It exists so test files can assert on what the adapter received without the Process.register/2 + named-pid pattern (which forces async: false). With :capture_pid in scope, tests stay async: true and use assert_receive {ALLM.Providers.FakeEmbeddings, :call, _} to pattern-match on the captured payload.

Examples

iex> e = ALLM.Embedding.new(vector: [0.1, 0.2])
iex> req = ALLM.EmbeddingRequest.new(input: ["a kestrel"])
iex> opts = [adapter_opts: [embedding_script: [{:ok, [e]}]]]
iex> {:ok, resp} = ALLM.Providers.FakeEmbeddings.embed(req, opts)
iex> ALLM.EmbeddingResponse.vectors(resp)
[[0.1, 0.2]]