agency-lang 0.26.0 → 0.26.1

package/dist/lib/cli/diffusersImageRules.py

@@ -64,6 +64,7 @@ FIELDS = [
     "control_invert",
     "images",
     "start_image",
+    "mask_image",
     "strength",
 ]
 
@@ -105,8 +106,10 @@ MAX_REFERENCE_ASPECT = 8
 
 # The images a request can carry, one row per request field. The field a
 # request carries decides its mode; a request with no image is in "plain"
-# mode. `LOCAL_IMAGE_FIELDS` in lib/stdlib/localImageInputs.ts is the same
-# table for the stdlib, and a test compares the two.
+# mode. A field with `goes_with` comes only with that other field, and the
+# pair decides the mode: a start image with a mask is "inpaint".
+# `LOCAL_IMAGE_FIELDS` in lib/stdlib/localImageInputs.ts is the same table
+# for the stdlib, and a test compares the two.
 #
 #   mode       the mode the field puts a request in. A family takes a mode
 #              when its row in FAMILIES has a pipeline for it.
@@ -121,8 +124,9 @@ MAX_REFERENCE_ASPECT = 8
 #              many and leaves a smaller one as it is, and "cover" scales
 #              it to cover the output and crops the overflow evenly from
 #              both sides
-#   on_white   True: a transparent image is pasted onto white before it is
-#              made RGB. False: its pixels are kept as drawn.
+#   background the color a transparent image is pasted onto before it is
+#              made RGB: "white" or "black". None: its color channels are
+#              kept as stored, and the alpha band is dropped.
 #   refusal    the message for a family with no pipeline for the mode, with
 #              {label} for the family and {families} for those that have one
 #   prepare    optional: the name of a step the server runs on a decoded
@@ -130,6 +134,12 @@ MAX_REFERENCE_ASPECT = 8
 #              when the request asks.
 #   check      optional: the name of a check in CHECKS the server runs on a
 #              decoded image's size. It returns a refusal or None.
+#   arg        the pipeline argument the field's images are passed as
+#   goes_with  optional: the field this one comes with. A request with this
+#              field and not the other is refused.
+#   same_size_as
+#              optional: the field whose image this one's must match in
+#              width and height, so both are cropped the same way
 INPUT_IMAGES = {
     "control_image": {
         "mode": "control",
@@ -138,9 +148,10 @@ INPUT_IMAGES = {
         # A control image is a drawing to follow, not a picture to keep.
         "sets_size": False,
         "fit": "letterbox",
-        "on_white": False,
+        "background": None,
         "refusal": "{label} does not take a ControlNet. Leave controlnet empty.",
         "prepare": "invert",
+        "arg": "image",
     },
     "images": {
         "mode": "reference",
@@ -149,9 +160,10 @@ INPUT_IMAGES = {
         "sets_size": True,
         # The model only looks at a reference, so it can stay any shape.
         "fit": "shrink",
-        "on_white": True,
+        "background": "white",
         "refusal": "{label} does not take reference images. Only {families} takes them.",
         "check": "reference_problem",
+        "arg": "image",
     },
     "start_image": {
         "mode": "img2img",
@@ -161,9 +173,28 @@ INPUT_IMAGES = {
         # Cropped, not letterboxed: black bands would be part of the
         # picture, and the model would redraw them as black bars.
         "fit": "cover",
-        "on_white": True,
+        "background": "white",
         "refusal": "{label} does not redraw a start image. {families} do.",
         "check": "start_image_problem",
+        "arg": "image",
+    },
+    # White marks the part of the start image to redraw, and black the part
+    # to keep. Grey redraws partly.
+    "mask_image": {
+        "mode": "inpaint",
+        "max_count": 1,
+        "max_bytes": MAX_INPUT_IMAGE_BYTES,
+        # The start image sets the size.
+        "sets_size": False,
+        # Cropped exactly as the start image is, since the two are the same
+        # size.
+        "fit": "cover",
+        # A transparent part of a mask is black, and so kept.
+        "background": "black",
+        "refusal": "{label} does not redraw part of a picture. {families} do.",
+        "arg": "mask_image",
+        "goes_with": "start_image",
+        "same_size_as": "start_image",
     },
 }
 
@@ -173,18 +204,35 @@ MODE_FIELDS = {
     "control": ["controlnet", "control_image", "control_scale", "control_invert"],
     "reference": ["images"],
     "img2img": ["start_image", "strength"],
+    "inpaint": ["start_image", "mask_image", "strength"],
 }
 
+# The modes that start from a start image and take a strength.
+REDRAW_MODES = ["img2img", "inpaint"]
+
+
+def image_fields_of(mode):
+    """The image fields a request in `mode` carries, the one that sets the
+    size first: [] for plain. A field that goes with another brings it
+    along, so inpaint is [start_image, mask_image]."""
+    fields = [field for field, row in INPUT_IMAGES.items() if row["mode"] == mode]
+    partners = [INPUT_IMAGES[field]["goes_with"] for field in fields if "goes_with" in INPUT_IMAGES[field]]
+    return partners + fields
+
 # Room in a request body for everything but its images: the prompt and the
 # settings.
 REQUEST_SETTINGS_BYTES = 64 * 1024
 
 # The largest request body: the settings, plus the base64 of the most image
-# bytes one field may carry. A request carries one image field, never two.
-# `localBodyBytes()` in lib/stdlib/localImageInputs.ts is the same number,
-# and the front door holds image requests to it.
+# bytes one mode's fields may carry. `localBodyBytes()` in
+# lib/stdlib/localImageInputs.ts is the same number, and the front door
+# holds image requests to it.
 MAX_BODY_BYTES = REQUEST_SETTINGS_BYTES + max(
-    base64_length(row["max_count"] * row["max_bytes"]) for row in INPUT_IMAGES.values()
+    sum(
+        base64_length(INPUT_IMAGES[field]["max_count"] * INPUT_IMAGES[field]["max_bytes"])
+        for field in image_fields_of(mode)
+    )
+    for mode in MODE_FIELDS
 )
 
 # The pixel budget of a size taken from a picture: the default size's.
@@ -231,18 +279,29 @@ MAX_LOADED_ADAPTERS = 2
 #                    False: it has no such arguments and draws at the start
 #                    image's size. The server fits the start image to the
 #                    output size first, so the result is the same.
-#   img2img_steps    how the img2img pipeline rounds the steps it runs: a
-#                    key of STEP_FORMULAS
+#   img2img_steps    how the img2img and inpaint pipelines round the steps
+#                    they run: a key of STEP_FORMULAS. A family's two
+#                    pipelines round the same way.
+#   inpaint_default_strength
+#                    how much of the masked part of a start image to redraw
+#                    when the request gives no strength: the inpaint
+#                    pipeline's own default. None for a family with no
+#                    inpaint pipeline.
 #   components       every component model_index.json must name, as
 #                    [library, class]. [None, None] is a slot the file
 #                    lists and leaves empty.
+
 #   settings         the other values model_index.json may carry, which
 #                    from_pretrained passes to the pipeline, each with the
 #                    one value allowed
 FAMILIES = {
     "ZImagePipeline": {
         "label": "Z-Image Turbo",
-        "pipelines": {"plain": "ZImagePipeline", "img2img": "ZImageImg2ImgPipeline"},
+        "pipelines": {
+            "plain": "ZImagePipeline",
+            "img2img": "ZImageImg2ImgPipeline",
+            "inpaint": "ZImageInpaintPipeline",
+        },
         "default_steps": 9,
         "max_steps": 50,
         "default_guidance": 0.0,
@@ -253,18 +312,23 @@ FAMILIES = {
         "default_strength": 0.6,
         "img2img_takes_size": True,
         "img2img_steps": "up",
+        "inpaint_default_strength": 1.0,
         "components": {
-            "scheduler": ["diffusers", "FlowMatchEulerDiscreteScheduler"],
-            "text_encoder": ["transformers", "Qwen3Model"],
-            "tokenizer": ["transformers", "Qwen2Tokenizer"],
-            "transformer": ["diffusers", "ZImageTransformer2DModel"],
-            "vae": ["diffusers", "AutoencoderKL"],
+            "scheduler": [["diffusers", "FlowMatchEulerDiscreteScheduler"]],
+            "text_encoder": [["transformers", "Qwen3Model"]],
+            "tokenizer": [["transformers", "Qwen2Tokenizer"]],
+            "transformer": [["diffusers", "ZImageTransformer2DModel"]],
+            "vae": [["diffusers", "AutoencoderKL"]],
         },
         "settings": {},
     },
     "ChromaPipeline": {
         "label": "Chroma",
-        "pipelines": {"plain": "ChromaPipeline", "img2img": "ChromaImg2ImgPipeline"},
+        "pipelines": {
+            "plain": "ChromaPipeline",
+            "img2img": "ChromaImg2ImgPipeline",
+            "inpaint": "ChromaInpaintPipeline",
+        },
         "default_steps": 40,
         "max_steps": 80,
         "default_guidance": 3.0,
@@ -275,20 +339,25 @@ FAMILIES = {
         "default_strength": 0.9,
         "img2img_takes_size": True,
         "img2img_steps": "up",
+        "inpaint_default_strength": 0.6,
         "components": {
-            "feature_extractor": [None, None],
-            "image_encoder": [None, None],
-            "scheduler": ["diffusers", "FlowMatchEulerDiscreteScheduler"],
-            "text_encoder": ["transformers", "T5EncoderModel"],
-            "tokenizer": ["transformers", "T5Tokenizer"],
-            "transformer": ["diffusers", "ChromaTransformer2DModel"],
-            "vae": ["diffusers", "AutoencoderKL"],
+            "feature_extractor": [[None, None]],
+            "image_encoder": [[None, None]],
+            "scheduler": [["diffusers", "FlowMatchEulerDiscreteScheduler"]],
+            "text_encoder": [["transformers", "T5EncoderModel"]],
+            "tokenizer": [["transformers", "T5Tokenizer"]],
+            "transformer": [["diffusers", "ChromaTransformer2DModel"]],
+            "vae": [["diffusers", "AutoencoderKL"]],
         },
         "settings": {},
     },
     "QwenImagePipeline": {
         "label": "Qwen-Image",
-        "pipelines": {"plain": "QwenImagePipeline", "img2img": "QwenImageImg2ImgPipeline"},
+        "pipelines": {
+            "plain": "QwenImagePipeline",
+            "img2img": "QwenImageImg2ImgPipeline",
+            "inpaint": "QwenImageInpaintPipeline",
+        },
         "default_steps": 50,
         "max_steps": 80,
         "default_guidance": 4.0,
@@ -301,12 +370,13 @@ FAMILIES = {
         "default_strength": 0.6,
         "img2img_takes_size": True,
         "img2img_steps": "up",
+        "inpaint_default_strength": 0.6,
         "components": {
-            "scheduler": ["diffusers", "FlowMatchEulerDiscreteScheduler"],
-            "text_encoder": ["transformers", "Qwen2_5_VLForConditionalGeneration"],
-            "tokenizer": ["transformers", "Qwen2Tokenizer"],
-            "transformer": ["diffusers", "QwenImageTransformer2DModel"],
-            "vae": ["diffusers", "AutoencoderKLQwenImage"],
+            "scheduler": [["diffusers", "FlowMatchEulerDiscreteScheduler"]],
+            "text_encoder": [["transformers", "Qwen2_5_VLForConditionalGeneration"]],
+            "tokenizer": [["transformers", "Qwen2Tokenizer"]],
+            "transformer": [["diffusers", "QwenImageTransformer2DModel"]],
+            "vae": [["diffusers", "AutoencoderKLQwenImage"]],
         },
         "settings": {},
     },
@@ -323,16 +393,18 @@ FAMILIES = {
         "guidance_arg": "guidance_scale",
         "default_negative_prompt": "",
         "takes_lora": False,
-        # klein edits from references instead: it has no img2img pipeline.
+        # klein edits from references instead. diffusers has an inpaint
+        # pipeline for it, but no img2img one, and neither is served yet.
         "default_strength": None,
         "img2img_takes_size": None,
         "img2img_steps": None,
+        "inpaint_default_strength": None,
         "components": {
-            "scheduler": ["diffusers", "FlowMatchEulerDiscreteScheduler"],
-            "text_encoder": ["transformers", "Qwen3ForCausalLM"],
-            "tokenizer": ["transformers", "Qwen2TokenizerFast"],
-            "transformer": ["diffusers", "Flux2Transformer2DModel"],
-            "vae": ["diffusers", "AutoencoderKLFlux2"],
+            "scheduler": [["diffusers", "FlowMatchEulerDiscreteScheduler"]],
+            "text_encoder": [["transformers", "Qwen3ForCausalLM"]],
+            "tokenizer": [["transformers", "Qwen2TokenizerFast"]],
+            "transformer": [["diffusers", "Flux2Transformer2DModel"]],
+            "vae": [["diffusers", "AutoencoderKLFlux2"]],
         },
         # Only the step-distilled checkpoint is served. The base model
         # needs guidance and about 50 steps, which this row does not allow.
@@ -348,6 +420,7 @@ FAMILIES = {
             "plain": "StableDiffusionXLPipeline",
             "control": "StableDiffusionXLControlNetPipeline",
             "img2img": "StableDiffusionXLImg2ImgPipeline",
+            "inpaint": "StableDiffusionXLInpaintPipeline",
         },
         "default_steps": 28,
         "max_steps": 80,
@@ -361,16 +434,24 @@ FAMILIES = {
         "default_strength": 0.6,
         "img2img_takes_size": False,
         "img2img_steps": "down",
+        # Just under 1, so the masked part keeps a trace of the start image.
+        "inpaint_default_strength": 0.9999,
         "components": {
-            "feature_extractor": [None, None],
-            "image_encoder": [None, None],
-            "scheduler": ["diffusers", "EulerDiscreteScheduler"],
-            "text_encoder": ["transformers", "CLIPTextModel"],
-            "text_encoder_2": ["transformers", "CLIPTextModelWithProjection"],
-            "tokenizer": ["transformers", "CLIPTokenizer"],
-            "tokenizer_2": ["transformers", "CLIPTokenizer"],
-            "unet": ["diffusers", "UNet2DConditionModel"],
-            "vae": ["diffusers", "AutoencoderKL"],
+            "feature_extractor": [[None, None]],
+            "image_encoder": [[None, None]],
+            # Many community SDXL finetunes ship the ancestral Euler
+            # sampler. Both classes read the same
+            # scheduler_config.json.
+            "scheduler": [
+                ["diffusers", "EulerDiscreteScheduler"],
+                ["diffusers", "EulerAncestralDiscreteScheduler"],
+            ],
+            "text_encoder": [["transformers", "CLIPTextModel"]],
+            "text_encoder_2": [["transformers", "CLIPTextModelWithProjection"]],
+            "tokenizer": [["transformers", "CLIPTokenizer"]],
+            "tokenizer_2": [["transformers", "CLIPTokenizer"]],
+            "unet": [["diffusers", "UNet2DConditionModel"]],
+            "vae": [["diffusers", "AutoencoderKL"]],
         },
         # Every SDXL checkpoint sets this; it makes an empty negative prompt
         # encode as zeros, as the model was trained.
@@ -421,15 +502,16 @@ def family_of(model_index):
             )
     named = {key: value for key, value in named.items() if key not in rules["settings"]}
     for component, value in named.items():
-        expected = rules["components"].get(component)
-        if expected is None:
+        allowed = rules["components"].get(component)
+        if allowed is None:
             raise ValueError(
                 f'{rules["label"]} has no component "{component}", '
                 "and this model_index.json names one."
             )
-        if value != expected:
+        if value not in allowed:
             raise ValueError(
-                f'{rules["label"]}\'s "{component}" must be {expected}. '
+                f'{rules["label"]}\'s "{component}" must be '
+                f"{join_names([str(pair) for pair in allowed], 'or')}. "
                 f"This model_index.json says {value}."
             )
     missing = [c for c in rules["components"] if c not in named]
@@ -526,17 +608,18 @@ def _negative_prompt_of(rules, body):
 
 def _strength_of(rules, body, mode):
     """How much of the start image to redraw: the request's strength, or
-    the family's default. None outside img2img mode, where mode_of has
-    already refused a strength."""
-    if mode != "img2img":
+    the family's default for the mode. None outside REDRAW_MODES, where
+    mode_of has already refused a strength."""
+    if mode not in REDRAW_MODES:
         return None
+    default = rules["default_strength"] if mode == "img2img" else rules["inpaint_default_strength"]
     strength = body.get("strength")
     if strength is None:
-        return rules["default_strength"]
+        return default
     if not _is_number(strength) or strength <= 0 or strength > 1:
         raise RequestError(
             "strength must be a number above 0 and at most 1. Low keeps the start image close; "
-            f"{rules['label']} uses {rules['default_strength']} when strength is left out."
+            f"{rules['label']} uses {default} when strength is left out."
         )
     return float(strength)
 
@@ -804,16 +887,28 @@ def _check_unknown_fields(body):
 
 def mode_of(rules, body):
     """The request's mode: the mode of the image field it carries, or
-    "plain" when it carries none. Refuses image fields of two modes, a
-    field of a mode the request is not in, and a mode the family has no
-    pipeline for."""
+    "plain" when it carries none. A field that goes with another decides
+    the mode of the pair: a start image with a mask is inpaint. Refuses
+    such a field without its partner, image fields of two modes, a field
+    of a mode the request is not in, and a mode the family has no pipeline
+    for."""
     present = [field for field in INPUT_IMAGES if body.get(field) is not None]
-    if len(present) > 1:
-        raise RequestError(f"a request takes one of {join_names(list(INPUT_IMAGES), 'or')}.")
-    field = present[0] if present else None
+    for field in present:
+        partner = INPUT_IMAGES[field].get("goes_with")
+        if partner is not None and partner not in present:
+            raise RequestError(f"{field} goes with {partner}, and this request has none.")
+    leads = [field for field in present if "goes_with" not in INPUT_IMAGES[field]]
+    if len(leads) > 1:
+        choices = [field for field in INPUT_IMAGES if "goes_with" not in INPUT_IMAGES[field]]
+        raise RequestError(f"a request takes one of {join_names(choices, 'or')}.")
+    deciding = [field for field in present if "goes_with" in INPUT_IMAGES[field]] or leads
+    field = deciding[0] if deciding else None
     mode = "plain" if field is None else INPUT_IMAGES[field]["mode"]
+    allowed = MODE_FIELDS.get(mode, [])
+    # A field of several modes, such as strength, is named with the first
+    # mode that has it.
     for other, fields in MODE_FIELDS.items():
-        stray = [name for name in fields if other != mode and body.get(name) is not None]
+        stray = [name for name in fields if name not in allowed and body.get(name) is not None]
         if stray:
             verb = "goes" if len(stray) == 1 else "go"
             raise RequestError(
@@ -835,6 +930,12 @@ def image_field_of(mode):
     return None
 
 
+def input_images_of(body, fields):
+    """The bytes of each image the request carries, by field, for the image
+    fields of its mode."""
+    return {field: input_bytes(body, field) for field in fields}
+
+
 def input_bytes(body, field):
     """The bytes of each image in the field `field`, from the request's
     base64: a list, empty when `field` is None. Holds the field to its
@@ -1046,6 +1147,18 @@ def start_image_problem(width, height):
     return _shape_problem(width, height, "A start image")
 
 
+def size_match_problem(field, size, other, other_size):
+    """Why an image of `size` in `field` cannot go with one of `other_size`
+    in the field `other`, which its row says it must match, or None. Sizes
+    are (width, height)."""
+    if size == other_size:
+        return None
+    return (
+        f"{field} is {size[0]}x{size[1]} and {other} is {other_size[0]}x{other_size[1]}. "
+        "They must be the same size."
+    )
+
+
 # The checks a row of INPUT_IMAGES names in `check`.
 CHECKS = {"reference_problem": reference_problem, "start_image_problem": start_image_problem}
 
@@ -1081,8 +1194,8 @@ STEP_FORMULAS = {"down": _steps_down, "up": _steps_up}
 
 def steps_run(rules, mode, steps, strength):
     """How many steps the pipeline runs for a request in `mode` that asks
-    for `steps` at `strength`: all of them, except in img2img mode."""
-    if mode != "img2img":
+    for `steps` at `strength`: all of them, except in REDRAW_MODES."""
+    if mode not in REDRAW_MODES:
         return steps
     return STEP_FORMULAS[rules["img2img_steps"]](steps, strength)
 
@@ -1095,13 +1208,13 @@ def check_request(rules, body, adapters_dir=None, controlnets_dir=None):
     model takes instead.
 
     `steps_run` is how many of `steps` the pipeline runs, which is fewer
-    in img2img mode. A request that would run none is refused.
+    in REDRAW_MODES. A request that would run none is refused.
 
     `size` is the (width, height) the request gave, or None: with none,
     the size depends on the first input image, which only the server can
-    open, so output_size decides it there. `image_field` is the image field
-    the request carries, or None in plain mode, and `input_images` holds the
-    bytes of each image in it."""
+    open, so output_size decides it there. `image_fields` lists the image
+    fields the request carries, the one that sets the size first, and
+    `input_images` holds the bytes of each image in each of them."""
     if not isinstance(body, dict):
         raise RequestError("The request body must be a JSON object.")
     _check_unknown_fields(body)
@@ -1111,8 +1224,8 @@ def check_request(rules, body, adapters_dir=None, controlnets_dir=None):
     _check_control_pairing(body)
     mode = mode_of(rules, body)
     control = _controlnet_of(body, controlnets_dir)
-    image_field = image_field_of(mode)
-    input_images = input_bytes(body, image_field)
+    image_fields = image_fields_of(mode)
+    input_images = input_images_of(body, image_fields)
     steps = _steps_of(rules, body)
     strength = _strength_of(rules, body, mode)
     run = steps_run(rules, mode, steps, strength)
@@ -1122,7 +1235,7 @@ def check_request(rules, body, adapters_dir=None, controlnets_dir=None):
         "prompt": _prompt_of(body),
         "size": size,
         "mode": mode,
-        "image_field": image_field,
+        "image_fields": image_fields,
         "input_images": input_images,
         "steps": steps,
         "strength": strength,
@@ -1153,9 +1266,10 @@ def pipeline_args(rules, request, width, height):
         args["negative_prompt"] = negative
     if request["mode"] == "control":
         args["controlnet_conditioning_scale"] = request["control_scale"]
-    if request["mode"] == "img2img":
+    if request["mode"] in REDRAW_MODES:
         args["strength"] = request["strength"]
-        if not rules["img2img_takes_size"]:
+        # Every inpaint pipeline takes a size.
+        if request["mode"] == "img2img" and not rules["img2img_takes_size"]:
             # The pipeline draws at the start image's size, which the
             # server has already fitted to width x height.
             del args["width"], args["height"]

package/dist/lib/cli/diffusersImageServer.py

@@ -54,6 +54,7 @@ from diffusersImageRules import (  # noqa: E402
     join_names,
     output_size,
     pipeline_args,
+    size_match_problem,
     warm_up_request,
 )
 
@@ -80,10 +81,11 @@ def decode_image(data, field):
     MAX_INPUT_IMAGE_PIXELS is refused before its pixels are decoded. A file
     that is cut short or damaged is refused too. The EXIF orientation is
     applied, so a portrait photo from a phone stays upright. When the
-    field's row says on_white, a transparent image is pasted onto white
-    first; converting it directly would turn its background black. Then the
-    check the field's row names, if any, runs on the upright image's
-    size."""
+    field's row names a background, a transparent image is pasted onto that
+    color first. Converting it directly would drop the alpha band and keep
+    whatever color is stored under a transparent pixel, which editors often
+    save as white. Then the check the field's row names, if any, runs on the
+    upright image's size."""
     from PIL import Image, ImageOps
 
     unreadable = RequestError(
@@ -110,10 +112,10 @@ def decode_image(data, field):
     # A palette or RGB image marks its transparent color in `info`, with no
     # alpha band.
     transparent = image.mode in ("RGBA", "LA", "PA") or "transparency" in image.info
-    if INPUT_IMAGES[field]["on_white"] and transparent:
+    background = INPUT_IMAGES[field]["background"]
+    if background is not None and transparent:
         image = image.convert("RGBA")
-        white = Image.new("RGBA", image.size, (255, 255, 255, 255))
-        image = Image.alpha_composite(white, image)
+        image = Image.alpha_composite(Image.new("RGBA", image.size, background), image)
     problem = image_problem(field, image.width, image.height)
     if problem is not None:
         raise RequestError(f"{field}: {problem}")
@@ -155,6 +157,35 @@ def fitted(image, field, width, height):
     canvas.paste(image.resize(size, Image.LANCZOS, box=source_box), position)
     return canvas
 
+def input_images(request):
+    """(width, height, images) for a checked request: the output size, and
+    the request's input images decoded, prepared, and fitted to that size,
+    by the pipeline argument each field's row names. One image when the
+    field takes one, a list otherwise. The first image field sets the size,
+    and a field whose row names `same_size_as` must match that field's
+    picture before either is fitted."""
+    fields = request["image_fields"]
+    decoded = {
+        field: [prepared(decode_image(data, field), field, request) for data in request["input_images"][field]]
+        for field in fields
+    }
+    for field in fields:
+        other = INPUT_IMAGES[field].get("same_size_as")
+        if other is not None:
+            problem = size_match_problem(field, decoded[field][0].size, other, decoded[other][0].size)
+            if problem is not None:
+                raise RequestError(problem)
+    first_size = decoded[fields[0]][0].size if fields else None
+    lead = fields[0] if fields else None
+    width, height = output_size(request["size"], lead, first_size)
+    images = {}
+    for field in fields:
+        row = INPUT_IMAGES[field]
+        fitted_images = [fitted(image, field, width, height) for image in decoded[field]]
+        images[row["arg"]] = fitted_images[0] if row["max_count"] == 1 else fitted_images
+    return width, height, images
+
+
 PIL_FORMATS = {"png": "PNG", "jpeg": "JPEG", "webp": "WEBP"}
 
 
@@ -364,19 +395,13 @@ class Generator:
 
         # Everything up to the lock runs first, so a bad image never waits
         # for the GPU or loads a ControlNet.
-        field = request["image_field"]
-        images = [prepared(decode_image(data, field), field, request) for data in request["input_images"]]
-        first_size = images[0].size if images else None
-        width, height = output_size(request["size"], field, first_size)
-        fitted_images = [fitted(image, field, width, height) for image in images]
+        width, height, images = input_images(request)
         kwargs = {
             **pipeline_args(self.rules, request, width, height),
+            **images,
             "generator": torch.Generator("cpu").manual_seed(request["seed"]),
             "callback_on_step_end": on_step_end,
         }
-        if fitted_images:
-            one = INPUT_IMAGES[field]["max_count"] == 1
-            kwargs["image"] = fitted_images[0] if one else fitted_images
         with self.lock:
             # A client that hung up while it waited for the lock gets
             # nothing started at all.

package/dist/lib/cli/localFlag.js

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { _registerLocalModel, _resolveModel, _mlxServedName } from "../stdlib/localModels.js";
+import { _registerLocalModel, _resolveModel, _mlxServedName, _catalogKind, } from "../stdlib/localModels.js";
 /** Turn `agency run --local <value>` into the shared model-flag shape:
  *  resolve the name, and for a GGUF model download and verify if needed
  *  (progress prints here, in the parent, before the program starts) and pin
@@ -13,6 +13,9 @@ import { _registerLocalModel, _resolveModel, _mlxServedName } from "../stdlib/lo
  *  absolute path also keeps the child process independent of cwd drift. */
 export async function resolveLocalRunFlag(value, draft) {
     const resolved = _resolveModel(value);
+    if (_catalogKind(value) === "controlnet") {
+        throw new Error(`${value} is a ControlNet, which an SDXL image server loads for a request. Pass it to generateImageLocal as the controlnet argument.`);
+    }
     if (resolved.backend === "diffusers") {
         throw new Error(`${value} is an image model. Serve it with agency local serve --image ${value} and call generateImageLocal.`);
     }

package/dist/lib/stdlib/image.js

@@ -5,7 +5,7 @@ import { getRuntimeContext } from "../runtime/asyncContext.js";
 import { success, failure } from "../runtime/result.js";
 import { recordUsage, meteredDispatch } from "../runtime/recordPaidUsage.js";
 import { classifySource } from "./thread.js";
-import { _resolveModel, _mlxServedName } from "./localModels.js";
+import { _resolveModel, _mlxServedName, _catalogKind } from "./localModels.js";
 import { mlxBaseUrl, isNoServerError } from "./mlxServerModels.js";
 import { LOCAL_IMAGE_FORMATS } from "./mlxImage.js";
 import { PROMPT_PREVIEW_MAX } from "../statelogClient.js";
@@ -173,6 +173,12 @@ function checkLocalImageArgs(prompt, model, format) {
     catch (err) {
         return { error: err.message };
     }
+    if (_catalogKind(model) === "controlnet") {
+        return {
+            error: `"${model}" is a ControlNet, not an image model. Pass it as the controlnet ` +
+                "argument, with a controlImage, and name an SDXL image model as the model.",
+        };
+    }
     if (resolved.backend !== "diffusers") {
         const what = resolved.backend === "mlx" ? "an MLX model" : "a GGUF model";
         return {
@@ -182,22 +188,28 @@ function checkLocalImageArgs(prompt, model, format) {
     }
     return { servedName: _mlxServedName(resolved) };
 }
-/** The request field that carries a call's input images, with each file's
+/** The request fields that carry a call's input images, with each file's
  *  bytes as base64: one string when the field takes one image, a list
  *  otherwise. The files are read here, after the Agency side raised
  *  std::readImage for each, so the server never opens a path a request
  *  wrote. `approvedFileBytes` refuses a symlink that appeared while the
  *  prompt was pending, and a file over the field's size cap. */
 function imageFields(inputs) {
-    if (inputs.field === null) {
-        return {};
-    }
-    const row = LOCAL_IMAGE_FIELDS[inputs.field];
-    if (row === undefined) {
-        throw new Error(`${inputs.field} is not an image field of the image server.`);
+    const encoded = {};
+    for (const file of inputs.files) {
+        const row = LOCAL_IMAGE_FIELDS[file.field];
+        if (row === undefined) {
+            throw new Error(`${file.field} is not an image field of the image server.`);
+        }
+        encoded[file.field] = [
+            ...(encoded[file.field] ?? []),
+            approvedFileBytes(file.path, row.maxBytes).toString("base64"),
+        ];
     }
-    const encoded = inputs.files.map((file) => approvedFileBytes(file.path, row.maxBytes).toString("base64"));
-    return { [inputs.field]: row.maxCount === 1 ? encoded[0] : encoded };
+    return Object.fromEntries(Object.entries(encoded).map(([field, images]) => [
+        field,
+        LOCAL_IMAGE_FIELDS[field].maxCount === 1 ? images[0] : images,
+    ]));
 }
 /** The settings a call gives, as the request fields the server takes. A
  *  null setting, or an empty negative prompt, is left out so the server

package/dist/lib/stdlib/localImageInputs.d.ts

@@ -3,7 +3,8 @@
  *  table for the image server, and a test compares the two.
  *
  *  mode      which kind of request the field makes: a ControlNet request,
- *            an edit from reference pictures, or a redraw of a start image
+ *            an edit from reference pictures, a redraw of a start image, or
+ *            a redraw of the part of a start image a mask marks
  *  maxCount  how many images the field takes. One is sent as a base64
  *            string, more as a list of them
  *  maxBytes  the largest file each image may be
@@ -11,14 +12,17 @@
  *  question  what the std::readImage interrupt asks before the file is read
  *  readEachStep  true: the model reads each image at every step, as much
  *            work as one more megapixel of output, and the provider's
- *            timeout budgets for it */
+ *            timeout budgets for it
+ *  goesWith  optional: the field this one comes only with. A mask goes
+ *            with a start image */
 export type LocalImageField = {
-    mode: "control" | "reference" | "img2img";
+    mode: "control" | "reference" | "img2img" | "inpaint";
     maxCount: number;
     maxBytes: number;
     parameter: string;
     question: string;
     readEachStep: boolean;
+    goesWith?: string;
 };
 /** A control image is read up to the size every local server takes. */
 export declare const MAX_CONTROL_IMAGE_BYTES = 50000000;
@@ -31,12 +35,16 @@ export declare const MAX_REFERENCE_IMAGES = 4;
  *  the settings. */
 export declare const REQUEST_SETTINGS_BYTES: number;
 export declare const LOCAL_IMAGE_FIELDS: Record<string, LocalImageField>;
+/** The image fields a request in `mode` carries, the one that sets the size
+ *  first. A field that goes with another brings it along, so inpaint is
+ *  start_image and mask_image. `image_fields_of` in diffusersImageRules.py
+ *  is the same. */
+export declare function imageFieldsOf(mode: LocalImageField["mode"]): string[];
 /** How many characters base64 turns `bytes` bytes into. */
 export declare function base64Length(bytes: number): number;
 /** The largest request body the image server takes: the settings, plus the
- *  base64 of the most image bytes any one field may carry. A request
- *  carries images of one field only. `MAX_BODY_BYTES` in
- *  diffusersImageRules.py is computed the same way. */
+ *  base64 of the most image bytes one mode's fields may carry.
+ *  `MAX_BODY_BYTES` in diffusersImageRules.py is computed the same way. */
 export declare function localBodyBytes(): number;
 /** The image types a local input may be, by extension. */
 export declare const IMAGE_MIME_TYPES: Record<string, string>;
@@ -48,19 +56,19 @@ export declare function isRemoteSource(source: string): boolean;
 export declare function checkedImageFile(spelling: string, maxBytes: number, caller: string): string;
 /** One file a `generateImageLocal` call reads, after the std::readImage
  *  interrupt that shows its folder and name asks `question`. `path` is its
- *  real spelling, the one the interrupt shows. */
+ *  real spelling, the one the interrupt shows, and `field` is the request
+ *  field it goes in. */
 export type LocalImageFile = {
+    field: string;
     path: string;
     dir: string;
     filename: string;
     question: string;
 };
-/** The input images of one `generateImageLocal` call. `field` is the
- *  request field the files go in, or null for a call with none.
- *  `settings` holds the other request fields of the field's mode, such as
- *  `controlnet` and `control_scale`. */
+/** The input images of one `generateImageLocal` call, none for a call
+ *  with none. `settings` holds the other request fields of the call's
+ *  mode, such as `controlnet` and `control_scale`. */
 export type LocalImageInputs = {
-    field: string | null;
     files: LocalImageFile[];
     settings: Record<string, unknown>;
 };
@@ -73,4 +81,4 @@ export declare function referenceCount(inputs: LocalImageInputs): number;
  *  its field's size cap. Returns the files to raise std::readImage for.
  *  Throws with the message to fail with. The messages match the image
  *  server's, with the parameters' names for the request fields'. */
-export declare function _localImageInputs(controlnet: string, controlImage: string, controlScale: number | null, invertControlImage: boolean, images: string[], startImage: string, strength: number | null): LocalImageInputs;
+export declare function _localImageInputs(controlnet: string, controlImage: string, controlScale: number | null, invertControlImage: boolean, images: string[], startImage: string, strength: number | null, mask: string): LocalImageInputs;

package/dist/lib/stdlib/localImageInputs.js

@@ -38,18 +38,42 @@ export const LOCAL_IMAGE_FIELDS = {
         // The model starts from it once, instead of from noise.
         readEachStep: false,
     },
+    mask_image: {
+        mode: "inpaint",
+        maxCount: 1,
+        maxBytes: MAX_INPUT_IMAGE_BYTES,
+        parameter: "mask",
+        question: "Read this mask to choose which part of the picture to redraw?",
+        readEachStep: false,
+        goesWith: "start_image",
+    },
 };
+/** The image fields a request in `mode` carries, the one that sets the size
+ *  first. A field that goes with another brings it along, so inpaint is
+ *  start_image and mask_image. `image_fields_of` in diffusersImageRules.py
+ *  is the same. */
+export function imageFieldsOf(mode) {
+    const fields = Object.keys(LOCAL_IMAGE_FIELDS).filter((field) => LOCAL_IMAGE_FIELDS[field].mode === mode);
+    const partners = fields.flatMap((field) => {
+        const partner = LOCAL_IMAGE_FIELDS[field].goesWith;
+        return partner === undefined ? [] : [partner];
+    });
+    return [...partners, ...fields];
+}
 /** How many characters base64 turns `bytes` bytes into. */
 export function base64Length(bytes) {
     return 4 * Math.ceil(bytes / 3);
 }
 /** The largest request body the image server takes: the settings, plus the
- *  base64 of the most image bytes any one field may carry. A request
- *  carries images of one field only. `MAX_BODY_BYTES` in
- *  diffusersImageRules.py is computed the same way. */
+ *  base64 of the most image bytes one mode's fields may carry.
+ *  `MAX_BODY_BYTES` in diffusersImageRules.py is computed the same way. */
 export function localBodyBytes() {
-    const most = Math.max(...Object.values(LOCAL_IMAGE_FIELDS).map((row) => row.maxCount * row.maxBytes));
-    return REQUEST_SETTINGS_BYTES + base64Length(most);
+    const modes = Object.values(LOCAL_IMAGE_FIELDS).map((row) => row.mode);
+    const most = Math.max(...modes.map((mode) => imageFieldsOf(mode).reduce((total, field) => {
+        const row = LOCAL_IMAGE_FIELDS[field];
+        return total + base64Length(row.maxCount * row.maxBytes);
+    }, 0)));
+    return REQUEST_SETTINGS_BYTES + most;
 }
 /** The image types a local input may be, by extension. */
 export const IMAGE_MIME_TYPES = Object.fromEntries(Object.entries(MIME_TYPES).filter(([, mime]) => mime.startsWith("image/")));
@@ -109,7 +133,8 @@ function refusal(message) {
 /** A local path checked for the row's byte cap, with what its interrupt
  *  shows. A URL or a data URI is refused: the image server never fetches
  *  anything, so every input is a file on this machine. */
-function localImageFile(spelling, row) {
+function localImageFile(spelling, field) {
+    const row = LOCAL_IMAGE_FIELDS[field];
     if (isRemoteSource(spelling)) {
         throw new Error(`${CALLER} reads files on this machine only.`);
     }
@@ -121,6 +146,7 @@ function localImageFile(spelling, row) {
         throw refusal(err.message);
     }
     return {
+        field,
         path: real,
         dir: path.dirname(real),
         filename: path.basename(real),
@@ -130,10 +156,7 @@ function localImageFile(spelling, row) {
 /** How many images of `inputs` the model reads at every step, which the
  *  provider's timeout budgets for. 0 for a call with none. */
 export function referenceCount(inputs) {
-    if (inputs.field === null || !LOCAL_IMAGE_FIELDS[inputs.field].readEachStep) {
-        return 0;
-    }
-    return inputs.files.length;
+    return inputs.files.filter((file) => LOCAL_IMAGE_FIELDS[file.field].readEachStep).length;
 }
 /** Backs the checks `generateImageLocal` makes before it asks anything:
  *  which input images the call has, whether they go together, whether
@@ -141,10 +164,15 @@ export function referenceCount(inputs) {
  *  its field's size cap. Returns the files to raise std::readImage for.
  *  Throws with the message to fail with. The messages match the image
  *  server's, with the parameters' names for the request fields'. */
-export function _localImageInputs(controlnet, controlImage, controlScale, invertControlImage, images, startImage, strength) {
+export function _localImageInputs(controlnet, controlImage, controlScale, invertControlImage, images, startImage, strength, mask) {
     if ((controlnet === "") !== (controlImage === "")) {
         throw refusal("controlnet and controlImage go together: the ControlNet's name, and the image it conditions the generation on.");
     }
+    // The mask is checked first, as the server does, so a call with a mask
+    // and a strength but no start image hears about the mask.
+    if (mask !== "" && startImage === "") {
+        throw refusal("mask goes with startImage, and this call has none.");
+    }
     if (strength !== null && startImage === "") {
         throw refusal("strength goes with startImage, and this call has none.");
     }
@@ -157,29 +185,38 @@ export function _localImageInputs(controlnet, controlImage, controlScale, invert
         control_image: controlImage === "" ? [] : [controlImage],
         images,
         start_image: startImage === "" ? [] : [startImage],
+        mask_image: mask === "" ? [] : [mask],
     };
     // The other request fields of each image field's mode.
     const settingsOf = {
         control_image: controlSettings(controlnet, controlScale, invertControlImage),
         images: {},
         start_image: strengthSettings(strength),
+        mask_image: {},
     };
-    const given = Object.keys(paths).filter((field) => paths[field].length > 0);
+    // A field that goes with another, such as the mask, is not a choice of
+    // its own: it comes along with its partner.
+    const leads = Object.keys(paths).filter((field) => LOCAL_IMAGE_FIELDS[field].goesWith === undefined);
+    const given = leads.filter((field) => paths[field].length > 0);
     if (given.length === 0) {
-        return { field: null, files: [], settings: {} };
+        return { files: [], settings: {} };
     }
     if (given.length > 1) {
-        const names = Object.keys(paths).map((field) => LOCAL_IMAGE_FIELDS[field].parameter);
+        const names = leads.map((field) => LOCAL_IMAGE_FIELDS[field].parameter);
         throw refusal(`a call takes one of ${orList(names)}.`);
     }
-    const field = given[0];
-    const row = LOCAL_IMAGE_FIELDS[field];
-    if (paths[field].length > row.maxCount) {
-        throw refusal(`${row.parameter} takes at most ${row.maxCount} images. This call has ${paths[field].length}.`);
+    const fields = [
+        given[0],
+        ...Object.keys(paths).filter((field) => LOCAL_IMAGE_FIELDS[field].goesWith === given[0] && paths[field].length > 0),
+    ];
+    for (const field of fields) {
+        const row = LOCAL_IMAGE_FIELDS[field];
+        if (paths[field].length > row.maxCount) {
+            throw refusal(`${row.parameter} takes at most ${row.maxCount} images. This call has ${paths[field].length}.`);
+        }
     }
     return {
-        field,
-        files: paths[field].map((spelling) => localImageFile(spelling, row)),
-        settings: settingsOf[field],
+        files: fields.flatMap((field) => paths[field].map((spelling) => localImageFile(spelling, field))),
+        settings: Object.assign({}, ...fields.map((field) => settingsOf[field])),
     };
 }

package/dist/lib/stdlib/localModels.d.ts

@@ -142,7 +142,9 @@ export declare function _removeModel(name: string, cacheDir?: string): boolean;
 export declare function _removeServedModel(backend: ServedBackend, repo: string, cacheDir?: string): boolean;
 /** Where a resolved model's files are on disk, or null when nothing is
  *  there. A GGUF model is found through the download manifest; an MLX model
- *  through its record under the cache, or the directory it points at. */
+ *  through its record under the cache, or the directory it points at.
+ *  `insideCache` is false for a ControlNet, whose files are listed with the
+ *  models but live in `client.controlnetsDir`, where remove cannot reach. */
 export declare function _modelFilesOnDisk(resolved: ResolvedModel, cacheDir?: string): {
     path: string;
     sizeBytes: number;

package/dist/lib/stdlib/localModels.js

@@ -1,4 +1,4 @@
-import { root, wholePath, stat, list, remove, readText, writeText, } from "./contained.js";
+import { root, wholePath, stat, list, remove, readText, writeText, isContained, } from "./contained.js";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -543,7 +543,9 @@ export function _removeServedModel(backend, repo, cacheDir = "") {
 }
 /** Where a resolved model's files are on disk, or null when nothing is
  *  there. A GGUF model is found through the download manifest; an MLX model
- *  through its record under the cache, or the directory it points at. */
+ *  through its record under the cache, or the directory it points at.
+ *  `insideCache` is false for a ControlNet, whose files are listed with the
+ *  models but live in `client.controlnetsDir`, where remove cannot reach. */
 export function _modelFilesOnDisk(resolved, cacheDir = "") {
     const dir = resolveCacheDir(cacheDir);
     const onDisk = _listDownloadedModels(dir);
@@ -551,7 +553,12 @@ export function _modelFilesOnDisk(resolved, cacheDir = "") {
         const f = onDisk.find(match);
         return f === undefined
             ? null
-            : { path: f.path, sizeBytes: f.sizeBytes, insideCache: true, layout: f.layout };
+            : {
+                path: f.path,
+                sizeBytes: f.sizeBytes,
+                insideCache: isContained(f.path, dir),
+                layout: f.layout,
+            };
     };
     if (resolved.backend === "llama-cpp") {
         if (isGgufPath(resolved.target)) {

package/dist/lib/stdlib/mlxImage.js

@@ -73,6 +73,7 @@ const SETTINGS = [
     "control_invert",
     "images",
     "start_image",
+    "mask_image",
     "strength",
 ];
 const MIME = {

package/dist/lib/stdlib/modelCatalog.js

@@ -651,9 +651,11 @@ export const CURATED_LOCAL_MODELS = {
     // Not served: `agency local download` puts one in client.controlnetsDir,
     // and an SDXL image server loads it when a request names it with a
     // control image. Sizes are the config and the one weights file kept.
+    // The backend is diffusers because the download is recorded that way;
+    // `agency local list` only ticks a row whose backend matches its files.
     "controlnet-scribble-sdxl": {
-        backend: "mlx",
-        uri: "mlx:xinsir/controlnet-scribble-sdxl-1.0",
+        backend: "diffusers",
+        uri: "diffusers:xinsir/controlnet-scribble-sdxl-1.0",
         params: "1.3B",
         sizeBytes: 2502140339,
         kind: "controlnet",
@@ -663,8 +665,8 @@ export const CURATED_LOCAL_MODELS = {
         description: "Constrains an SDXL image to a rough line drawing: a stick figure becomes the pose. Give it a scribble as controlImage.",
     },
     "controlnet-openpose-sdxl": {
-        backend: "mlx",
-        uri: "mlx:xinsir/controlnet-openpose-sdxl-1.0",
+        backend: "diffusers",
+        uri: "diffusers:xinsir/controlnet-openpose-sdxl-1.0",
         params: "1.3B",
         sizeBytes: 2502140339,
         kind: "controlnet",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-lang",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "description": "The Agency language",
   "main": "./dist/lib/index.js",
   "bin": {

package/stdlib/docs/stdlib/image.md

@@ -209,6 +209,7 @@ generateImageLocal(
   images: string[] = [],
   startImage: string = "",
   strength: number | null = null,
+  mask: string = "",
 ): Result<LocalImage> raises <std::readImage>
 ```
 
@@ -249,6 +250,9 @@ Generate an image on this machine with a local image model. The model
   scaled to cover `size` and the overflow is cropped from both sides, so a
   4:3 photo redrawn as a square loses a strip at its left and right.
 
+  To redraw only part of the picture, also pass a `mask`: white is
+  redrawn and black is kept.
+
   @param prompt - What to draw
   @param model - The image model: a catalog name such as "z-image-turbo", a diffusers: URI, or a model directory
   @param size - Width and height joined by "x", each a multiple of 16, such as "1024x1024" or "1344x768". Empty is 1024x1024. Leave it empty when editing or redrawing a picture, and the result keeps the picture's shape
@@ -265,7 +269,28 @@ Generate an image on this machine with a local image model. The model
   @param invertControlImage - Swap black and white in the drawing before using it. Set it for dark lines on white with the scribble ControlNet, which reads white lines on black
   @param images - Pictures to edit, as paths to files on this machine. The prompt says what to change: 'add a hat to the character'. Only FLUX.2 [klein] takes them, and at most 4
   @param startImage - A picture to redraw, as a path to a file on this machine. The layout stays and the style changes. Goes with strength. Every model but FLUX.2 [klein] takes one
-  @param strength - How much of startImage to redraw, above 0 and up to 1. Low keeps it close, high changes more. Null uses the model's default
+  @param strength - How much of startImage to redraw, above 0 and up to 1. Low keeps it close, high changes more. Null uses the model's default, which can change when a mask is added: for Z-Image Turbo it goes from 0.6 to 1.0, which redraws the white part from scratch
+  @param mask - A black-and-white picture the same size as startImage, as a path to a file on this machine. White is redrawn and black is kept. Goes with startImage. Every model but FLUX.2 [klein] takes one
+
+Redrawing part of a picture: pass a `mask` with `startImage`. The mask
+is a picture the same size as the start image. White marks the part to
+redraw and black the part to keep, so a white shape over a vase changes
+only the vase:
+
+  ```ts
+  generateImageLocal("a vase of sunflowers", "z-image-turbo",
+    startImage: "photo.png", mask: "vase-mask.png")
+  ```
+
+Grey redraws partly, so a mask whose edge fades from white to black
+blends the new part in, where a hard edge can leave a faint seam. A
+transparent part of a mask counts as black. The mask is read from this
+machine under std::readImage, like the start image.
+
+Each model has its own default strength with a mask, which can differ
+from its default without one. Z-Image Turbo's goes from 0.6 to 1.0, and
+1.0 draws the white part from scratch, keeping nothing of what was
+there. Pass a lower strength to keep some of it.
 
 **Parameters:**
 
@@ -288,12 +313,13 @@ Generate an image on this machine with a local image model. The model
 | images | `string[]` | [] |
 | startImage | `string` | "" |
 | strength | `number \| null` | null |
+| mask | `string` | "" |
 
 **Returns:** `Result<LocalImage>`
 
 **Throws:** `std::readImage`
 
-([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L140))
+([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L159))
 
 ### cropImage
 
@@ -332,7 +358,7 @@ Cut a box out of an image and write it as a new image. Returns the path
 
 **Throws:** `std::cropImage`
 
-([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L247))
+([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L272))
 
 ### imageSize
 
@@ -354,7 +380,7 @@ The width and height of an image in pixels.
 
 **Throws:** `std::readImage`
 
-([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L283))
+([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L308))
 
 ### pasteImages
 
@@ -387,4 +413,4 @@ Lay images out on one white canvas, in rows of `columns`, each at its own
 
 **Throws:** `std::pasteImages`
 
-([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L300))
+([source](https://github.com/egonSchiele/agency-lang/tree/main/packages/agency-lang/stdlib/image.agency#L325))

package/stdlib/image.agency

@@ -137,6 +137,25 @@ export type LocalImage = {
   seed: number
 }
 
+/** Redrawing part of a picture: pass a `mask` with `startImage`. The mask
+is a picture the same size as the start image. White marks the part to
+redraw and black the part to keep, so a white shape over a vase changes
+only the vase:
+
+  ```ts
+  generateImageLocal("a vase of sunflowers", "z-image-turbo",
+    startImage: "photo.png", mask: "vase-mask.png")
+  ```
+
+Grey redraws partly, so a mask whose edge fades from white to black
+blends the new part in, where a hard edge can leave a faint seam. A
+transparent part of a mask counts as black. The mask is read from this
+machine under std::readImage, like the start image.
+
+Each model has its own default strength with a mask, which can differ
+from its default without one. Z-Image Turbo's goes from 0.6 to 1.0, and
+1.0 draws the white part from scratch, keeping nothing of what was
+there. Pass a lower strength to keep some of it. */
 export def generateImageLocal(
   prompt: string,
   model: string,
@@ -155,6 +174,7 @@ export def generateImageLocal(
   images: string[] = [],
   startImage: string = "",
   strength: number | null = null,
+  mask: string = "",
 ): Result<LocalImage> raises <std::readImage> {
   """
   Generate an image on this machine with a local image model. The model
@@ -194,6 +214,9 @@ export def generateImageLocal(
   scaled to cover `size` and the overflow is cropped from both sides, so a
   4:3 photo redrawn as a square loses a strip at its left and right.
 
+  To redraw only part of the picture, also pass a `mask`: white is
+  redrawn and black is kept.
+
   @param prompt - What to draw
   @param model - The image model: a catalog name such as "z-image-turbo", a diffusers: URI, or a model directory
   @param size - Width and height joined by "x", each a multiple of 16, such as "1024x1024" or "1344x768". Empty is 1024x1024. Leave it empty when editing or redrawing a picture, and the result keeps the picture's shape
@@ -210,7 +233,8 @@ export def generateImageLocal(
   @param invertControlImage - Swap black and white in the drawing before using it. Set it for dark lines on white with the scribble ControlNet, which reads white lines on black
   @param images - Pictures to edit, as paths to files on this machine. The prompt says what to change: 'add a hat to the character'. Only FLUX.2 [klein] takes them, and at most 4
   @param startImage - A picture to redraw, as a path to a file on this machine. The layout stays and the style changes. Goes with strength. Every model but FLUX.2 [klein] takes one
-  @param strength - How much of startImage to redraw, above 0 and up to 1. Low keeps it close, high changes more. Null uses the model's default
+  @param strength - How much of startImage to redraw, above 0 and up to 1. Low keeps it close, high changes more. Null uses the model's default, which can change when a mask is added: for Z-Image Turbo it goes from 0.6 to 1.0, which redraws the white part from scratch
+  @param mask - A black-and-white picture the same size as startImage, as a path to a file on this machine. White is redrawn and black is kept. Goes with startImage. Every model but FLUX.2 [klein] takes one
   """
   // Every input path is checked before the first interrupt, so a call that
   // is going to fail asks for nothing.
@@ -222,6 +246,7 @@ export def generateImageLocal(
     images,
     startImage,
     strength,
+    mask,
   )
   if (isFailure(inputs)) {
     return inputs

package/stdlib/image.js

@@ -155,7 +155,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("stdlib/image.agency", "e17a18faa215a773c0a1e013e2d0b1bb305566b35255e5983de5f01c8a7cd986", import.meta.url);
+__registerModuleFingerprint("stdlib/image.agency", "0ec6efc3a40477986a951b0956cb9478a563e76095f8e704b5f7aaf12df68210", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -559,7 +559,7 @@ const generateImage = __AgencyFunction.create({
   exported: true
 }, __toolRegistry);
 const LocalImage = z.object({ "base64": z.string(), "mimeType": z.string(), "seed": z.number() });
-async function __generateImageLocal_impl(prompt, model, size = __UNSET, steps = __UNSET, guidance = __UNSET, seed = __UNSET, negativePrompt = __UNSET, format = __UNSET, lora = __UNSET, loraScale = __UNSET, controlnet = __UNSET, controlImage = __UNSET, controlScale = __UNSET, invertControlImage = __UNSET, images = __UNSET, startImage = __UNSET, strength = __UNSET) {
+async function __generateImageLocal_impl(prompt, model, size = __UNSET, steps = __UNSET, guidance = __UNSET, seed = __UNSET, negativePrompt = __UNSET, format = __UNSET, lora = __UNSET, loraScale = __UNSET, controlnet = __UNSET, controlImage = __UNSET, controlScale = __UNSET, invertControlImage = __UNSET, images = __UNSET, startImage = __UNSET, strength = __UNSET, mask = __UNSET) {
   const __setupData = setupFunction();
   const __stack = __setupData.stack;
   const __step = __setupData.step;
@@ -589,6 +589,7 @@ async function __generateImageLocal_impl(prompt, model, size = __UNSET, steps =
   __stack.args["images"] = images === __UNSET ? [] : images;
   __stack.args["startImage"] = startImage === __UNSET ? `` : startImage;
   __stack.args["strength"] = strength === __UNSET ? null : strength;
+  __stack.args["mask"] = mask === __UNSET ? `` : mask;
   __self.__destructiveRan = __self.__destructiveRan ?? false;
   const runner = new Runner(__ctx, __stack, { state: __stack, moduleId: "stdlib/image.agency", scopeName: "generateImageLocal", threads: __setupData.threads });
   let __resultCheckpointId = -1;
@@ -663,6 +664,10 @@ async function __generateImageLocal_impl(prompt, model, size = __UNSET, steps =
       strength = __overrides["strength"];
       __stack.args["strength"] = strength;
     }
+    if ("mask" in __overrides) {
+      mask = __overrides["mask"];
+      __stack.args["mask"] = mask;
+    }
   }
   try {
     await agencyStore.run({
@@ -693,7 +698,8 @@ async function __generateImageLocal_impl(prompt, model, size = __UNSET, steps =
               invertControlImage,
               images,
               startImage,
-              strength
+              strength,
+              mask
             },
             moduleId: "stdlib/image.agency"
           }
@@ -704,7 +710,7 @@ async function __generateImageLocal_impl(prompt, model, size = __UNSET, steps =
       await runner.step(2, async (runner2) => {
         __stack.locals.inputs = await __tryCall(async () => await __call(_localImageInputs, {
           type: "positional",
-          args: [__stack.args.controlnet, __stack.args.controlImage, __stack.args.controlScale, __stack.args.invertControlImage, __stack.args.images, __stack.args.startImage, __stack.args.strength]
+          args: [__stack.args.controlnet, __stack.args.controlImage, __stack.args.controlScale, __stack.args.invertControlImage, __stack.args.images, __stack.args.startImage, __stack.args.strength, __stack.args.mask]
         }), {
           checkpoint: getRuntimeContext().ctx.getResultCheckpoint(),
           functionName: "generateImageLocal",
@@ -949,6 +955,13 @@ const generateImageLocal = __AgencyFunction.create({
     variadic: false,
     isFunctionTyped: false,
     acceptsResult: false
+  }, {
+    name: "mask",
+    hasDefault: true,
+    defaultValue: void 0,
+    variadic: false,
+    isFunctionTyped: false,
+    acceptsResult: false
   }],
   toolDefinition: {
     name: "generateImageLocal",
@@ -989,6 +1002,9 @@ const generateImageLocal = __AgencyFunction.create({
   scaled to cover \`size\` and the overflow is cropped from both sides, so a
   4:3 photo redrawn as a square loses a strip at its left and right.
 
+  To redraw only part of the picture, also pass a \`mask\`: white is
+  redrawn and black is kept.
+
   @param prompt - What to draw
   @param model - The image model: a catalog name such as "z-image-turbo", a diffusers: URI, or a model directory
   @param size - Width and height joined by "x", each a multiple of 16, such as "1024x1024" or "1344x768". Empty is 1024x1024. Leave it empty when editing or redrawing a picture, and the result keeps the picture's shape
@@ -1005,8 +1021,9 @@ const generateImageLocal = __AgencyFunction.create({
   @param invertControlImage - Swap black and white in the drawing before using it. Set it for dark lines on white with the scribble ControlNet, which reads white lines on black
   @param images - Pictures to edit, as paths to files on this machine. The prompt says what to change: 'add a hat to the character'. Only FLUX.2 [klein] takes them, and at most 4
   @param startImage - A picture to redraw, as a path to a file on this machine. The layout stays and the style changes. Goes with strength. Every model but FLUX.2 [klein] takes one
-  @param strength - How much of startImage to redraw, above 0 and up to 1. Low keeps it close, high changes more. Null uses the model's default`,
-    schema: z.object({ "prompt": z.string(), "model": z.string(), "size": z.string().nullable().describe("Default: "), "steps": z.union([z.number(), z.null()]).describe("Default: null"), "guidance": z.union([z.number(), z.null()]).describe("Default: null"), "seed": z.union([z.number(), z.null()]).describe("Default: null"), "negativePrompt": z.string().nullable().describe("Default: "), "format": z.string().nullable().describe("Default: png"), "lora": z.string().nullable().describe("Default: "), "loraScale": z.union([z.number(), z.null()]).describe("Default: null"), "controlnet": z.string().nullable().describe("Default: "), "controlImage": z.string().nullable().describe("Default: "), "controlScale": z.union([z.number(), z.null()]).describe("Default: null"), "invertControlImage": z.boolean().nullable().describe("Default: false"), "images": z.array(z.string()).nullable().describe("Default: []"), "startImage": z.string().nullable().describe("Default: "), "strength": z.union([z.number(), z.null()]).describe("Default: null") })
+  @param strength - How much of startImage to redraw, above 0 and up to 1. Low keeps it close, high changes more. Null uses the model's default, which can change when a mask is added: for Z-Image Turbo it goes from 0.6 to 1.0, which redraws the white part from scratch
+  @param mask - A black-and-white picture the same size as startImage, as a path to a file on this machine. White is redrawn and black is kept. Goes with startImage. Every model but FLUX.2 [klein] takes one`,
+    schema: z.object({ "prompt": z.string(), "model": z.string(), "size": z.string().nullable().describe("Default: "), "steps": z.union([z.number(), z.null()]).describe("Default: null"), "guidance": z.union([z.number(), z.null()]).describe("Default: null"), "seed": z.union([z.number(), z.null()]).describe("Default: null"), "negativePrompt": z.string().nullable().describe("Default: "), "format": z.string().nullable().describe("Default: png"), "lora": z.string().nullable().describe("Default: "), "loraScale": z.union([z.number(), z.null()]).describe("Default: null"), "controlnet": z.string().nullable().describe("Default: "), "controlImage": z.string().nullable().describe("Default: "), "controlScale": z.union([z.number(), z.null()]).describe("Default: null"), "invertControlImage": z.boolean().nullable().describe("Default: false"), "images": z.array(z.string()).nullable().describe("Default: []"), "startImage": z.string().nullable().describe("Default: "), "strength": z.union([z.number(), z.null()]).describe("Default: null"), "mask": z.string().nullable().describe("Default: ") })
   },
   exported: true
 }, __toolRegistry);
@@ -1902,7 +1919,7 @@ const pasteImages = __AgencyFunction.create({
   exported: true
 }, __toolRegistry);
 var stdin_default = graph;
-const __sourceMap = { "stdlib/image.agency:generateImage": { "2": { "line": 105, "col": 2 }, "3": { "line": 106, "col": 6 }, "4": { "line": 106, "col": 2 }, "5": { "line": 109, "col": 2 }, "6": { "line": 110, "col": 2 }, "7": { "line": 121, "col": 2 }, "4.0": { "line": 107, "col": 4 }, "6.0.0": { "line": 113, "col": 13 }, "6.0.1": { "line": 114, "col": 18 }, "6.0.2": { "line": 112, "col": 6 }, "6.0": { "line": 111, "col": 4 } }, "stdlib/image.agency:generateImageLocal": { "2": { "line": 216, "col": 2 }, "3": { "line": 225, "col": 6 }, "4": { "line": 225, "col": 2 }, "5": { "line": 228, "col": 2 }, "6": { "line": 231, "col": 2 }, "4.0": { "line": 226, "col": 4 }, "5.0": { "line": 229, "col": 4 } }, "stdlib/image.agency:cropImage": { "1": { "line": 265, "col": 2 }, "2": { "line": 266, "col": 6 }, "3": { "line": 266, "col": 2 }, "4": { "line": 269, "col": 2 }, "5": { "line": 270, "col": 6 }, "6": { "line": 270, "col": 2 }, "7": { "line": 274, "col": 9 }, "8": { "line": 275, "col": 14 }, "9": { "line": 276, "col": 12 }, "10": { "line": 277, "col": 17 }, "11": { "line": 273, "col": 2 }, "12": { "line": 279, "col": 2 }, "3.0": { "line": 267, "col": 4 }, "6.0": { "line": 271, "col": 4 } }, "stdlib/image.agency:imageSize": { "1": { "line": 288, "col": 2 }, "2": { "line": 289, "col": 6 }, "3": { "line": 289, "col": 2 }, "4": { "line": 293, "col": 9 }, "5": { "line": 294, "col": 14 }, "6": { "line": 292, "col": 2 }, "7": { "line": 296, "col": 2 }, "3.0": { "line": 290, "col": 4 } }, "stdlib/image.agency:pasteImages": { "2": { "line": 316, "col": 2 }, "3": { "line": 317, "col": 2 }, "4": { "line": 324, "col": 2 }, "5": { "line": 325, "col": 6 }, "6": { "line": 325, "col": 2 }, "7": { "line": 330, "col": 12 }, "8": { "line": 331, "col": 17 }, "9": { "line": 328, "col": 2 }, "10": { "line": 333, "col": 2 }, "3.0": { "line": 318, "col": 4 }, "3.1": { "line": 319, "col": 8 }, "3.2.0": { "line": 320, "col": 6 }, "3.2": { "line": 319, "col": 4 }, "3.3": { "line": 322, "col": 4 }, "6.0": { "line": 326, "col": 4 } } };
+const __sourceMap = { "stdlib/image.agency:generateImage": { "2": { "line": 105, "col": 2 }, "3": { "line": 106, "col": 6 }, "4": { "line": 106, "col": 2 }, "5": { "line": 109, "col": 2 }, "6": { "line": 110, "col": 2 }, "7": { "line": 121, "col": 2 }, "4.0": { "line": 107, "col": 4 }, "6.0.0": { "line": 113, "col": 13 }, "6.0.1": { "line": 114, "col": 18 }, "6.0.2": { "line": 112, "col": 6 }, "6.0": { "line": 111, "col": 4 } }, "stdlib/image.agency:generateImageLocal": { "2": { "line": 240, "col": 2 }, "3": { "line": 250, "col": 6 }, "4": { "line": 250, "col": 2 }, "5": { "line": 253, "col": 2 }, "6": { "line": 256, "col": 2 }, "4.0": { "line": 251, "col": 4 }, "5.0": { "line": 254, "col": 4 } }, "stdlib/image.agency:cropImage": { "1": { "line": 290, "col": 2 }, "2": { "line": 291, "col": 6 }, "3": { "line": 291, "col": 2 }, "4": { "line": 294, "col": 2 }, "5": { "line": 295, "col": 6 }, "6": { "line": 295, "col": 2 }, "7": { "line": 299, "col": 9 }, "8": { "line": 300, "col": 14 }, "9": { "line": 301, "col": 12 }, "10": { "line": 302, "col": 17 }, "11": { "line": 298, "col": 2 }, "12": { "line": 304, "col": 2 }, "3.0": { "line": 292, "col": 4 }, "6.0": { "line": 296, "col": 4 } }, "stdlib/image.agency:imageSize": { "1": { "line": 313, "col": 2 }, "2": { "line": 314, "col": 6 }, "3": { "line": 314, "col": 2 }, "4": { "line": 318, "col": 9 }, "5": { "line": 319, "col": 14 }, "6": { "line": 317, "col": 2 }, "7": { "line": 321, "col": 2 }, "3.0": { "line": 315, "col": 4 } }, "stdlib/image.agency:pasteImages": { "2": { "line": 341, "col": 2 }, "3": { "line": 342, "col": 2 }, "4": { "line": 349, "col": 2 }, "5": { "line": 350, "col": 6 }, "6": { "line": 350, "col": 2 }, "7": { "line": 355, "col": 12 }, "8": { "line": 356, "col": 17 }, "9": { "line": 353, "col": 2 }, "10": { "line": 358, "col": 2 }, "3.0": { "line": 343, "col": 4 }, "3.1": { "line": 344, "col": 8 }, "3.2.0": { "line": 345, "col": 6 }, "3.2": { "line": 344, "col": 4 }, "3.3": { "line": 347, "col": 4 }, "6.0": { "line": 351, "col": 4 } } };
 export {
   GeneratedImage,
   ImageBox,