@spec generate(
  ALLM.Request.t(),
  keyword()
) ::
  {:ok, ALLM.Response.t()}
  | {:error, ALLM.Error.AdapterError.t() | ALLM.Error.ValidationError.t()}

Execute a non-streaming generateContent request synchronously.

Wraps the HTTP call in ALLM.Retry.run/3 with the spec §6.1 default policy (Decision #16). Returns {:ok, %Response{}} on 2xx success or {:error, %AdapterError{}} on every failure shape.

Empty-candidates handling (Decisions #9 + #10)

• promptFeedback.blockReason with empty candidates → {:ok, %Response{finish_reason: :content_filter, content: ""}} (a successful HTTP response is a successful call from the adapter's perspective; the content filter is a finish reason).
• Empty candidates with no promptFeedback.blockReason → {:error, %AdapterError{reason: :malformed_response}}.

Error reasons (Decision #15)

Examples

iex> ALLM.Keys.put(:gemini, "AIza-doctest-gen")
iex> req = ALLM.Request.new([%ALLM.Message{role: :user, content: "x"}], model: "gemini-2.5-flash")
iex> {:error, %ALLM.Error.AdapterError{reason: :authentication_failed}} =
...>   ALLM.Providers.Gemini.generate(req,
...>     retry: false,
...>     adapter_opts: [plug: fn conn ->
...>       conn
...>       |> Plug.Conn.put_resp_content_type("application/json")
...>       |> Plug.Conn.resp(401, ~s({"error":{"code":401,"status":"UNAUTHENTICATED","message":"bad"}}))
...>     end]
...>   )
iex> ALLM.Keys.delete(:gemini)
:ok

@spec parse_finish_reason(String.t() | nil) ::
  {ALLM.Response.finish_reason() | nil, String.t() | nil}

Map a Gemini finishReason string to ALLM's closed Response.finish_reason enum, returning {atom, raw_string_or_nil} per Decision #14.

STOP collapses to {:stop, nil} (the canonical "natural completion" row); every other row preserves the raw string at index 1 so callers can recover provider fidelity from Response.raw_finish_reason.

Examples

iex> ALLM.Providers.Gemini.parse_finish_reason("STOP")
{:stop, nil}

iex> ALLM.Providers.Gemini.parse_finish_reason("MAX_TOKENS")
{:length, "MAX_TOKENS"}

iex> ALLM.Providers.Gemini.parse_finish_reason("SAFETY")
{:content_filter, "SAFETY"}

iex> ALLM.Providers.Gemini.parse_finish_reason("OTHER")
{:other, "OTHER"}

iex> ALLM.Providers.Gemini.parse_finish_reason(nil)
{nil, nil}

@spec prepare_request(
  ALLM.Request.t(),
  keyword()
) :: {:ok, Req.Request.t()} | {:error, ALLM.Error.AdapterError.t()}

Build an unfired %Req.Request{} with the resolved API key injected as x-goog-api-key: <key> (Decision #2).

Per ALLM.Keys.fetch!/2, this function raises %ALLM.Error.EngineError{reason: :missing_key} when no key resolver yields a value.

Honors opts[:request_timeout] (forwarded as Req's :receive_timeout) and opts[:adapter_opts][:endpoint] (URL host override, primarily for testing).

Examples

iex> ALLM.Keys.put(:gemini, "AIza-doctest-prep")
iex> req = ALLM.Request.new([%ALLM.Message{role: :user, content: "hi"}], model: "gemini-2.5-flash")
iex> {:ok, %Req.Request{} = http} = ALLM.Providers.Gemini.prepare_request(req, [])
iex> Req.Request.get_header(http, "x-goog-api-key")
["AIza-doctest-prep"]
iex> ALLM.Keys.delete(:gemini)
:ok

@spec stream(
  ALLM.Request.t(),
  keyword()
) ::
  {:ok, Enumerable.t()}
  | {:error, ALLM.Error.AdapterError.t() | ALLM.Error.ValidationError.t()}

Open an SSE stream against streamGenerateContent?alt=sse.

Returns {:ok, enumerable} on success — the enumerable is lazy; the HTTP request fires on the first reduce. Returns {:error, %AdapterError{}} only for synchronous pre-flight failures (key-resolution failure raises %EngineError{} directly per the Keys.fetch!/2 contract; that is surfaced through the existing with-chain at the call site).

Per CLAUDE.md mid-stream-error invariant, HTTP-shaped errors observed AFTER the consumer starts reducing are folded into a terminating {:error, _} event — the call-site tuple stays {:ok, stream}. This includes 4xx status codes received before the first SSE event (the {:status, code} Finch frame folds via handle_finch_payload/2).

Decision references

• Decision #1 — request body byte-equal to generate/2's. Only the URL path differs (:streamGenerateContent?alt=sse vs :generateContent).
• Decision #3 — ?alt=sse is the ONLY required query parameter; auth still flows via x-goog-api-key.
• Decision #12 — usageMetadata may appear on intermediate chunks; the chunk-mapper emits {:raw_chunk, {:usage, _}} on every appearance and StreamCollector.apply_event/2 overwrites.
• Decision #13 — stream terminates on Finch's :done payload, not a data: [DONE] lookahead. The synthetic :message_completed event is built from accumulated state.

Options

• :stream_timeout (default 60_000 ms) — receive-loop after-clause between chunks.
• :finch_module (default Finch) — test injection seam.
• :finch_name (default ALLM.Finch).
• :finch_stub_ref — opaque ref forwarded to the Finch shim (used only by ALLM.Test.FinchStub).
• :adapter_opts[:endpoint] — endpoint override (testing).

@spec to_gemini_request_body(
  ALLM.Request.t(),
  keyword()
) :: map()

Compose the JSON request body for generateContent from a canonical %Request{}. Pure function; no I/O.

Performs system-message extraction (hoist into top-level systemInstruction), role mapping (:assistant → "model"), and generationConfig composition.

Phase 16.1 surface only — tools (16.3) and image-out (16.5) extend this builder via opts flags without changing the text-only path.

Examples

iex> req = ALLM.Request.new(
...>   [%ALLM.Message{role: :system, content: "Be concise."},
...>    %ALLM.Message{role: :user, content: "Hi"}],
...>   model: "gemini-2.5-flash", max_tokens: 256
...> )
iex> body = ALLM.Providers.Gemini.to_gemini_request_body(req, [])
iex> {body["systemInstruction"], length(body["contents"]), body["generationConfig"]["maxOutputTokens"]}
{%{"parts" => [%{"text" => "Be concise."}]}, 1, 256}

@spec to_gemini_tool_config(ALLM.Request.tool_choice() | {:tool, String.t()}) :: map()

Translate an ALLM canonical tool_choice to Gemini's functionCallingConfig map.

Map shapes (%{"mode" => "AUTO"}, etc.) are passed through verbatim so callers can hand-craft Gemini-specific extensions.

Examples

iex> ALLM.Providers.Gemini.to_gemini_tool_config(:auto)
%{"mode" => "AUTO"}

iex> ALLM.Providers.Gemini.to_gemini_tool_config({:tool, "set_color"})
%{"mode" => "ANY", "allowedFunctionNames" => ["set_color"]}

@spec to_gemini_tools([ALLM.Tool.t()]) :: [map()]

Translate a list of canonical %ALLM.Tool{}s to Gemini's functionDeclarations shape.

Gemini's tools is an array of %{functionDeclarations: [...]} objects, not a flat array of declarations. Each declaration carries :name, :description, and :parameters (Gemini's name for the JSON-Schema field — distinct from OpenAI's parameters key on the tool's function sub-map and Anthropic's input_schema).

Examples

iex> tool = ALLM.Tool.new(name: "get_weather", description: "weather", schema: %{"type" => "object"})
iex> ALLM.Providers.Gemini.to_gemini_tools([tool])
[%{"name" => "get_weather", "description" => "weather", "parameters" => %{"type" => "object"}}]

@spec translate_options(
  keyword(),
  ALLM.Request.t()
) :: keyword()

Identity translator (Decision #18). Gemini accepts ALLM's canonical :max_tokens, :temperature, :top_p, etc. — the camelCase rename and generationConfig nesting happens in to_generation_config/1 at request-build time, not here.

Examples

iex> req = ALLM.Request.new([%ALLM.Message{role: :user, content: "x"}], model: "gemini-2.5-flash")
iex> ALLM.Providers.Gemini.translate_options([max_tokens: 100, temperature: 0.7], req)
[max_tokens: 100, temperature: 0.7]