@spec build_prompt([term()], keyword()) :: {:ok, String.t()} | {:error, term()}

The prompt process/4 sends for operations (normalised or not): numbered instructions, the preservation clause (preserve:), the closing line (finish: false drops it). Public so admin pages can preview it and tests can pin it.

@spec compare(PhoenixKitAI.Endpoint.t(), input(), input(), keyword()) ::
  {:ok, map()} | {:error, error()}

Checks an edit against its original with a vision model: did the subject, its text and logos survive, and what changed that was not asked for. intent: describes the edit that was requested.

Returns {:ok, %{passed: boolean, same_subject, text_and_logos_preserved, unwanted_changes, summary, usage, latency_ms, model}}.

@spec default_question() :: String.t()

The question describe/3 asks when the caller gives none.

@spec describe(PhoenixKitAI.Endpoint.t(), [input()], keyword()) ::
  {:ok, map()} | {:error, error()}

Asks a vision-capable chat endpoint about images.

Options: :prompt (default "Describe this image in detail."), :system, :schema (JSON Schema map → the answer is requested and parsed as that object), :json (true → any JSON object), :model, and the chat sampling options (:temperature, :max_tokens, :top_p, :seed).

Returns {:ok, %{text, json, usage, latency_ms, model}}; json is nil unless requested. A JSON answer that does not parse is {:error, {:no_json_in_response, text}}; :on_no_json, a one-arity function, first receives the unparsed result (usage and :prompt included) so the paid call can still be logged.

@spec dimensions(binary()) :: {:ok, {pos_integer(), pos_integer()}} | :error

Pixel dimensions from a PNG, JPEG, WebP or GIF header, without decoding.

@spec extract_text(PhoenixKitAI.Endpoint.t(), [input()] | input(), keyword()) ::
  {:ok, map()} | {:error, error()}

Reads the text in images with a vision model (OCR without an OCR engine): a product label, a receipt, a sign, a page of a document.

Returns {:ok, %{text, blocks, language, confidence, has_illegible_text, fields, json, prompt, usage, latency_ms, model}} — text is everything transcribed in reading order, blocks splits it into typed pieces (%{text, kind, language, page}, kind one of heading / paragraph / label / list / table / caption / code / handwriting / other), fields holds every requested name (nil when the model found nothing, string keys as given), has_illegible_text says some print was visible but unreadable (retake the photo rather than trust the gaps), json is the raw object. Several images are read as pages of one document, in order; page says which image a block came from.

The prompt forbids guessing: vision models will otherwise invent plausible label text (an ingredients line, a net weight) for print they cannot resolve, at full confidence.

Options: fields: — a map of name → description of a value to pull out (%{"ean" => "the barcode digits", "best_before" => "expiry date as YYYY-MM-DD"}, or a list of names), language: — a hint when the script is ambiguous, layout: :markdown — keep tables and lists as Markdown instead of plain lines, instructions: — extra wording for the prompt, schema: — replace the base schema (fields: is still added to it), plus describe/3's :model, :system and sampling options.

@spec fetch_outputs(map(), keyword()) :: {:ok, map()}

Downloads output images a provider returned as URLs (xAI, OpenAI's response_format: "url") so callers always get bytes, and adds width / height to every image whose header can be read. A URL that cannot be fetched stays a URL, with an {:output_not_fetched, url, reason} warning. fetch_outputs: false skips the download.

@spec fit_options(
  map(),
  PhoenixKitAI.Images.ImageModel.t() | nil,
  [atom()],
  boolean()
) ::
  {:ok, map(), [term()]} | {:error, {:unsupported_option, atom(), term()}}

Keeps options inside what the adapter can send (adapter_options) and, when there is a model listing, what the model accepts. Returns the fitted options and a warning per change, {:dropped_option, key, value}, in the canonical option order; with strict: true the first offender is an error instead.

@spec normalize_inputs([input()], keyword()) ::
  {:ok, [String.t()]} | {:error, error()}

Turns caller inputs into what adapters take: data URLs (bytes inlined) or http(s) URLs. Accepts raw bytes (type sniffed), %{data, content_type}, %{url}, and bare data: / http(s): strings. Never hand a provider a permanent URL it could cache — pass bytes.

@spec normalize_mask(map(), input() | nil, keyword()) ::
  {:ok, map()} | {:error, error()}

Normalises a mask: input into the request option adapters receive (a data URL) — the OpenAI adapter sends it as the mask file, the others drop it with a {:dropped_option, :mask, _} warning. Used by process/4 and by the thin PhoenixKitAI.Completion.edit_image/4.

@spec options(PhoenixKitAI.Endpoint.t(), keyword() | map()) :: map()

The option map an adapter receives: the endpoint's stored defaults underneath the caller's keyword options, canonical keys only.

@spec process(PhoenixKitAI.Endpoint.t(), [input()], [term()], keyword()) ::
  {:ok, result() | plan()} | {:error, error()}

Edits images (the first is the subject, the rest are references) with the given operations on endpoint. See the moduledoc.

@spec redact_warning(term()) :: term()

A warning with any long binary payload replaced by its size — a dropped :mask carries a whole data URL; logs and screens get {:dropped_option, :mask, {:bytes, 12345}} instead.

@spec request_options() :: [atom()]

The canonical request option names.

@spec text_schema() :: map()

The JSON Schema extract_text/3 asks the model to fill (before fields: are added).