@spec cursor_index(pid()) :: non_neg_integer()

Read the current cursor index for an Agent-backed cursor. Used in tests to assert how many calls have been consumed.

@spec generate(
  ALLM.ImageRequest.t(),
  keyword()
) :: {:ok, ALLM.ImageResponse.t()} | {:error, ALLM.Error.ImageAdapterError.t()}

Execute a scripted image-generation request. See spec §35.3.

Returns {:error, %ImageAdapterError{reason: :unsupported_operation, metadata: %{operation: op}}} BEFORE consulting the script when request.operation not in supported_operations() (entry-point gate per the conformance contract).

Otherwise reads the script from opts[:adapter_opts][:image_script], advances the process-local cursor, and returns the entry verbatim. Empty / exhausted script returns {:error, %ImageAdapterError{reason: :unknown, metadata: %{cause: :no_scripted_image}}}.

Propagates opts[:request_id] onto response.request_id when the script does not already populate it. Round-trips request.metadata onto response.metadata when the script does not populate it.

When opts[:adapter_opts][:capture_pid] is a pid, sends {ALLM.Providers.FakeImages, :call, %{request: request, opts: opts}} to that pid BEFORE the operation gate fires (so even rejected calls are captured). Side-channel only — does not affect the response.

Examples

iex> img = ALLM.Image.from_url("https://example.com/x.png")
iex> req = ALLM.ImageRequest.new(prompt: "a kestrel")
iex> opts = [adapter_opts: [image_script: [{:ok, [img]}]]]
iex> {:ok, resp} = ALLM.Providers.FakeImages.generate(req, opts)
iex> resp.usage.images
1

iex> img = ALLM.Image.from_binary(<<1>>, "image/png")
iex> req = ALLM.ImageRequest.new(prompt: "a kestrel")
iex> opts = [adapter_opts: [image_script: [{:ok, [img]}], capture_pid: self()]]
iex> {:ok, _} = ALLM.Providers.FakeImages.generate(req, opts)
iex> receive do
...>   {ALLM.Providers.FakeImages, :call, %{request: ^req}} -> :ok
...> after
...>   0 -> :no_message
...> end
:ok

@spec script([script_entry()]) :: :ok

Document and validate the script grammar for adapter_opts[:image_script].

Each entry is one of:

• {:ok, [%Image{}, ...]} — return the listed images plus a default %ImageUsage{images: length(images)}.
• {:ok, [%Image{}, ...], usage: %ImageUsage{}} — return the listed images plus the supplied usage.
• {:error, %ImageAdapterError{}} — return the struct verbatim.

Returns :ok when the script is well-formed; raises ArgumentError on the first invalid entry. (Validation is opt-in — the runtime generate/2 path tolerates a mix of legal entries and surfaces a cursor-exhausted shape on nil lookups.)

Examples

iex> img = ALLM.Image.from_binary(<<1>>, "image/png")
iex> ALLM.Providers.FakeImages.script([{:ok, [img]}])
:ok

@spec start_script_cursor() :: pid()

Start an Agent-backed script cursor for cross-process multi-call scripting and for disambiguating content-equal scripts in the same process.

Pass the returned pid as adapter_opts[:script_cursor]; subsequent calls increment the cursor on the Agent rather than on the process dictionary.

Examples

iex> pid = ALLM.Providers.FakeImages.start_script_cursor()
iex> ALLM.Providers.FakeImages.cursor_index(pid)
0

@spec supported_operations() :: [ALLM.ImageRequest.operation()]

Return the list of operations FakeImages can perform.

Defaults to all three image operations; tests asserting per-adapter rejection paths typically construct a custom @behaviour ALLM.ImageAdapter module rather than narrowing this list.

Examples

iex> ALLM.Providers.FakeImages.supported_operations()
[:generate, :edit, :variation]