PhoenixKitAI.Images.Operations (PhoenixKitAI v0.23.0)

Copy Markdown View Source

The named image operations PhoenixKitAI.Images.process/4 composes into one edit prompt.

An operation is a prompt template plus, optionally, parameters it needs, request options it implies (a transparent cutout wants background: "transparent" and a PNG), a fallback template for when those options are not available on the model, presets for a parameter, and whether it needs reference images after the subject.

Built-ins

operationparametersnotes
:instructiontextfree text; a bare string in the list means this
:clean_backgroundcolor (default "white")plain studio backdrop
:blur_backgroundshallow depth of field
:remove_backgroundtransparent PNG; falls back to plain white
:replace_backgroundwithdescribed new background
:remove_reflectionsglare and specular highlights
:remove_objectswhatremove and fill
:enhanceexposure, white balance, sharpness
:upscaleresolution (default "2K")asks for a bigger output
:relightlight (preset atom or text):day, :evening, :night, :studio, :golden_hour, :overcast
:recolorwhat, colorone element's colour
:straightenlevel horizon, vertical verticals
:crop_to_subjecttight crop, even margins
:restyleneeds reference images; borrows their materials and mood

Extending

A host adds or overrides operations in config:

config :phoenix_kit_ai, image_operations: %{
  product_shot: %{
    description: "Catalogue product shot",
    prompt: "Place the product on a seamless white sweep with soft studio light.",
    options: %{aspect_ratio: "1:1"}
  }
}

And an admin can override any operation's wording without a deploy: a saved prompt named Image op <name> — its slug, derived from the name, is image-op-<name> with dashes, e.g. a prompt called "Image op remove background" — replaces the built-in template; its {{Variables}} are filled from the operation's parameters.

Summary

Types

name()
params()
spec()

Functions

all()

Every operation: built-ins under the host's :image_operations.

fetch(name)

One operation's spec.

label(name)

The translated label of a built-in operation (its description for a host-defined one). The literals here are what the extractor sees, so every built-in name lands in the catalogue.

names()

Operation names, built-ins first.

normalize(operations)

Turns the caller's list into [{name, params}].

options(pairs)

The request options the operations imply (later operations win).

references_required?(pairs)

Whether any operation in the list needs reference images.

render(name, params, opts \\ [])

The sentence(s) for one operation. fallback: true picks the operation's fallback wording (its implied options were not available). A saved prompt whose slug is image-op-<name> (a prompt named "Image op <name>") overrides the template unless prompt_overrides: false.

Types

name()

@type name() :: atom()

params()

@type params() :: %{optional(atom()) => term()}

spec()

@type spec() :: %{
  :prompt => String.t(),
  optional(:description) => String.t(),
  optional(:params) => [atom()],
  optional(:defaults) => params(),
  optional(:options) => map(),
  optional(:fallback_prompt) => String.t(),
  optional(:presets) => %{optional(atom()) => String.t()},
  optional(:references) => :none | :optional | :required,
  optional(:group) => atom()
}

Functions

all()

@spec all() :: %{required(name()) => spec()}

Every operation: built-ins under the host's :image_operations.

fetch(name)

@spec fetch(name()) :: {:ok, spec()} | :error

One operation's spec.

label(name)

@spec label(name()) :: String.t()

The translated label of a built-in operation (its description for a host-defined one). The literals here are what the extractor sees, so every built-in name lands in the catalogue.

names()

@spec names() :: [name()]

Operation names, built-ins first.

normalize(operations)

@spec normalize([term()]) ::
  {:ok, [{name(), params()}]}
  | {:error,
     {:unknown_operation, term()}
     | {:missing_parameter, name(), atom()}
     | {:conflicting_operations, name(), name()}}

Turns the caller's list into [{name, params}].

Accepts atoms (:enhance), tuples with keyword or map parameters ({:relight, light: :night}), bare strings (a free-form instruction), and {:custom, "text"}. Unknown names, missing parameters and two operations from one exclusive group (two background treatments, say) are errors before anything is sent.

options(pairs)

@spec options([{name(), params()}]) :: map()

The request options the operations imply (later operations win).

references_required?(pairs)

@spec references_required?([{name(), params()}]) :: boolean()

Whether any operation in the list needs reference images.

render(name, params, opts \\ [])

@spec render(name(), params(), keyword()) :: {:ok, String.t()} | {:error, term()}

The sentence(s) for one operation. fallback: true picks the operation's fallback wording (its implied options were not available). A saved prompt whose slug is image-op-<name> (a prompt named "Image op <name>") overrides the template unless prompt_overrides: false.