lcode-cli 0.41.0__py3-none-any.whl → 0.43.0__py3-none-any.whl

lcode/__init__.py

@@ -3,7 +3,7 @@
 From a program: `from lcode import Session` (see lcode.api).
 """
 
-__version__ = "0.41.0"
+__version__ = "0.43.0"
 
 API = ("Session", "Result", "Options", "SetupError")
 

lcode/agent.py

@@ -309,6 +309,7 @@ class Settings:
     comfyui_path: str | None = None  # a ComfyUI install lcode doesn't find by itself (lcode.comfy)
     media_dir: str = ".lcode/media"  # where image and video mode save their files (lcode.media)
     image_model: str = "flux2-klein-4b"  # the media catalog's model image mode uses (lcode.media_catalog)
+    preview: str = "auto"  # images in the terminal: auto, kitty, iterm, blocks or off (lcode.preview)
     num_batch: int | None = None
     keep_alive: str = "30m"
     think: bool = True
@@ -375,6 +376,12 @@ class Agent:
         self.interactive = True  # False for `lcode -p`: no end-of-session questions
         self.comfy_process = None  # the ComfyUI lcode started for image and video mode, stopped when it exits
         self.no_coding_model = ""  # why there's no coding model, when lcode started in image or video mode without
+        from lcode.imageopts import Options as ImageOptions
+
+        self.image_options = ImageOptions()  # image mode's defaults for this session (/options)
+        self.media_results: list[dict] = []  # the session's images, numbered (/gallery, /vary, /open)
+        self.last_request: dict | None = None  # what /again repeats (lcode.media.redo)
+        self.image_refs: list[str] = []  # images every next request follows (/use)
         self.reflected = 0  # messages before this index were already checked for notes to remember
         self._memory: memory_notes.Memory | None = None
         self._agent_types: tuple[Path, dict[str, subagents.AgentType], list[str]] | None = None
@@ -679,8 +686,10 @@ class Agent:
         return any(m.get("role") == "user" for m in self.messages)
 
     def save(self) -> None:
-        if not (self.has_conversation() or self.session_name):
+        if not (self.has_conversation() or self.session_name or self.media_results):
             return  # nothing worth resuming
+        if not self.session_title and not self.has_conversation() and self.media_results:
+            self.session_title = " ".join(self.media_results[0]["prompt"].split())[:60]  # an image session
         self.session_title = self.session_title or sessions.title_from(self.messages)
         f = self.session_file()
         f.parent.mkdir(parents=True, exist_ok=True)
@@ -689,6 +698,7 @@ class Agent:
             "model": self.settings.model,
             "mode": self.settings.mode,
             "image_model": self.settings.image_model,
+            "media": {"results": self.media_results, "options": self.image_options.to_json(), "refs": self.image_refs},
             "name": self.session_name,
             "title": self.session_title,
             "messages": self.messages,
@@ -739,6 +749,10 @@ class Agent:
             self.settings.mode = data["mode"]  # a session belongs to the mode it was made in
         if isinstance(data.get("image_model"), str):
             self.settings.image_model = data["image_model"]
+        media = data.get("media") or {}
+        self.media_results = [r for r in media.get("results") or [] if isinstance(r, dict) and "path" in r]
+        self.image_options = type(self.image_options).from_json(media.get("options") or {})
+        self.image_refs = [r for r in media.get("refs") or [] if isinstance(r, str)]
         self.session_title = data.get("title") or sessions.title_from(self.messages)
         self.tools.read_mtimes.clear()  # files may have changed since; the model must read them again
         self.tools.todos = list(data.get("todos") or [])

lcode/api.py

@@ -201,6 +201,7 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
         comfyui_path=cfg["comfyui_path"],
         media_dir=cfg["media_dir"],
         image_model=cfg["image_model"],
+        preview=cfg["preview"],
         web=switch(options.web, cfg["web"], "on"),
         search_backend=cfg["search_backend"],
         searxng_url=cfg["searxng_url"],

lcode/cli.py

@@ -812,7 +812,7 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
         api.close_agent(agent)
         sys.exit(2)
     try:
-        made = media.generate_image(agent, prompt)
+        made = media.request(agent, prompt)
     except (media.MediaError, KeyboardInterrupt) as e:
         message = str(e) or "Cancelled."
         if quiet:
@@ -826,12 +826,13 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
             "type": "result",
             "status": "success",
             "mode": "image",
-            "files": [str(path) for path in made.files],
-            "model": made.model,
-            "seed": made.seed,
-            "width": made.width,
-            "height": made.height,
-            "seconds": round(made.seconds, 1),
+            "files": [str(path) for one in made for path in one.files],
+            "model": made[0].model,
+            "seed": made[0].seed,
+            "seeds": [one.seed for one in made],
+            "width": made[0].width,
+            "height": made[0].height,
+            "seconds": round(sum(one.seconds for one in made), 1),
         }
         print(json.dumps(result, ensure_ascii=False), flush=True)
     api.close_agent(agent)
@@ -1106,9 +1107,13 @@ def cmd_media(args) -> None:
         f"ComfyUI at {server.url}" if running else (f"{install.path} (not running)" if install else "no ComfyUI found")
     )
     console.print(f"[dim]{hw.describe()} · {where} · image model: {cfg['image_model']}[/]\n")
-    for mode in ("image", "video"):
+    for mode in ("image", "video", "tool"):
         models = cat.for_mode(mode)
-        console.print(f"[bold]{mode.capitalize()} models[/]")
+        console.print(
+            "[bold]Tools for images[/] [dim](/upscale, /nobg)[/]"
+            if mode == "tool"
+            else f"[bold]{mode.capitalize()} models[/]"
+        )
         if not models:
             console.print(f"  [dim]{media.SOON[mode]}[/]\n")
             continue

lcode/comfy.py

@@ -336,8 +336,9 @@ def describe_rejection(r: requests.Response) -> str:
     lines = [str((data.get("error") or {}).get("message") or "ComfyUI refused the workflow")]
     for node, info in (data.get("node_errors") or {}).items():
         for err in info.get("errors", [])[:3]:
-            detail = err.get("details") or err.get("message") or ""
-            lines.append(f"{info.get('class_type', 'node')} ({node}): {detail}")
+            message, detail = err.get("message") or "", err.get("details") or ""
+            why = f"{message}: {detail}" if message and detail and detail not in message else (detail or message)
+            lines.append(f"{info.get('class_type', 'node')} ({node}): {why}")
     return "; ".join(lines)
 
 
@@ -560,13 +561,15 @@ def describe_history_error(entry: dict) -> str:
 
 
 def save(server: Server, outputs: dict, folder: Path, stem: str, meta: dict) -> list[Path]:
-    """Fetch the job's files into `folder`: stem-1.png, … with stem-1.json next to each."""
+    """Fetch the job's files into `folder`: stem.png (stem-2.png if that's taken), or stem-1.png, … for several,
+    each with its settings in a .json next to it."""
     folder.mkdir(parents=True, exist_ok=True)
     items = [item for node in outputs.values() for kind in OUTPUT_KINDS for item in node.get(kind, [])]
+    items = [it for it in items if it.get("type", "output") == "output"]
     saved = []
-    for i, item in enumerate((it for it in items if it.get("type", "output") == "output"), 1):
+    for i, item in enumerate(items, 1):
         ext = Path(item["filename"]).suffix or ".png"
-        path = unique(folder / f"{stem}-{i}{ext}")
+        path = unique(folder / (f"{stem}{ext}" if len(items) == 1 else f"{stem}-{i}{ext}"))
         data = server.fetch(item)
         if ext.lower() == ".png":
             data = with_text(data, "lcode", json.dumps(meta, ensure_ascii=False))

lcode/config.py

@@ -46,6 +46,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "comfyui_path": (None, str, "your ComfyUI folder, if lcode doesn't find it (lcode starts it when needed)"),
     "media_dir": (".lcode/media", str, "where images and videos go: a folder in the project, or an absolute path"),
     "image_model": ("flux2-klein-4b", str, "the model image mode uses: a key from `lcode media`"),
+    "preview": ("auto", str, "images in the terminal: auto | kitty | iterm | blocks (colour text) | off"),
     "think": (True, bool, "let the model reason before answering (slower, better)"),
     "web": ("on", str, "web search and page fetching for the model: on | ask | off"),
     "search_backend": ("auto", str, "auto | ollama | brave | tavily | searxng (keys come from environment variables)"),
@@ -211,6 +212,11 @@ def coerce(key: str, value: object) -> object:
         raise ConfigError(f"permission_mode must be one of {', '.join(PERMISSION_MODES)}")
     if key == "mode" and value not in WORK_MODES:
         raise ConfigError(f"mode must be one of {', '.join(WORK_MODES)}")
+    if key == "preview":
+        from lcode.preview import PROTOCOLS
+
+        if value not in PROTOCOLS:
+            raise ConfigError(f"preview must be one of {', '.join(PROTOCOLS)}")
     if key == "image_model":
         from lcode import media_catalog
 

lcode/edits.py

@@ -0,0 +1,283 @@
+"""Image edits as changes to a ComfyUI workflow: reference images, inpainting through a mask, outpainting.
+
+A model that edits with reference latents (FLUX.2 klein) takes the images through its own text-to-image workflow:
+each image is scaled, encoded by the VAE and attached to both conditionings before the guider, and the instruction is
+the prompt. On top of that:
+
+- **Inpainting** keeps the original outside a mask: the edited picture is pasted into the original only where the
+  mask is white (with a soft edge).
+- **Outpainting** puts the image on a bigger canvas, lets the model fill the new border, and pastes the original back,
+  so it stays exactly as it was.
+"""
+
+from __future__ import annotations
+
+import re
+import struct
+from pathlib import Path
+
+BASE = 8000  # node ids lcode adds start here (the workflows' own are small numbers)
+SIZE_NODE = str(BASE + 9)
+IMAGE_TYPES = (".png", ".jpg", ".jpeg", ".webp", ".bmp")
+EXTEND_HINT = (
+    "Replace the blurry border around the sharp picture with sharp, detailed scenery that continues the picture "
+    "outward, matching its light, perspective and style. Keep the sharp middle exactly as it is. No frame, no bars."
+)
+
+
+class EditError(ValueError):
+    pass
+
+
+def node_of(graph: dict, class_type: str) -> str | None:
+    return next((nid for nid, node in graph.items() if node.get("class_type") == class_type), None)
+
+
+def save_node(graph: dict) -> str:
+    nid = node_of(graph, "SaveImage")
+    if nid is None:
+        raise EditError("the workflow saves no image")
+    return nid
+
+
+def load_images(graph: dict, names: list[str]) -> list[list]:
+    """LoadImage nodes for uploaded images; their IMAGE outputs."""
+    links = []
+    for k, name in enumerate(names):
+        nid = str(BASE + 100 + k)
+        graph[nid] = {"class_type": "LoadImage", "inputs": {"image": name}}
+        links.append([nid, 0])
+    return links
+
+
+def add_references(graph: dict, images: list[list], megapixels: float, size_from_first: bool) -> list:
+    """Attach the images as reference latents to the guider's positive and negative conditionings.
+
+    Each is scaled to `megapixels` first. With `size_from_first`, the picture made has the first image's size
+    (its width and height go to every node of the workflow that takes them). Returns the first scaled image.
+    """
+    guider = node_of(graph, "CFGGuider")
+    vae = node_of(graph, "VAELoader")
+    if guider is None or vae is None:
+        raise EditError("this workflow can't take reference images")
+    positive, negative = graph[guider]["inputs"]["positive"], graph[guider]["inputs"]["negative"]
+    first = None
+    for k, image in enumerate(images):
+        scale, encode, ref_pos, ref_neg = (str(BASE + 10 * (k + 1) + i) for i in range(4))
+        graph[scale] = {
+            "class_type": "ImageScaleToTotalPixels",
+            "inputs": {"image": image, "upscale_method": "lanczos", "megapixels": megapixels, "resolution_steps": 16},
+        }
+        graph[encode] = {"class_type": "VAEEncode", "inputs": {"pixels": [scale, 0], "vae": [vae, 0]}}
+        graph[ref_pos] = {"class_type": "ReferenceLatent", "inputs": {"conditioning": positive, "latent": [encode, 0]}}
+        graph[ref_neg] = {"class_type": "ReferenceLatent", "inputs": {"conditioning": negative, "latent": [encode, 0]}}
+        positive, negative = [ref_pos, 0], [ref_neg, 0]
+        first = first or [scale, 0]
+    graph[guider]["inputs"]["positive"], graph[guider]["inputs"]["negative"] = positive, negative
+    if size_from_first and first:
+        set_size(graph, first)
+    return first
+
+
+def set_size(graph: dict, image: list) -> None:
+    """The picture made takes `image`'s size: its width and height go to every workflow node that takes them."""
+    graph[SIZE_NODE] = {"class_type": "GetImageSize", "inputs": {"image": image}}
+    for nid, node in graph.items():
+        if nid.isdigit() and int(nid) >= BASE:
+            continue  # lcode's own nodes keep their sizes
+        inputs = node.get("inputs", {})
+        for key, out in (("width", 0), ("height", 1)):
+            if key in inputs and not isinstance(inputs[key], list):
+                inputs[key] = [SIZE_NODE, out]
+
+
+def scale_to(graph: dict, image: list, megapixels: float) -> list:
+    nid = str(BASE + 301)
+    graph[nid] = {
+        "class_type": "ImageScaleToTotalPixels",
+        "inputs": {"image": image, "upscale_method": "lanczos", "megapixels": megapixels, "resolution_steps": 16},
+    }
+    return [nid, 0]
+
+
+def mask_from_file(graph: dict, mask_name: str) -> list:
+    """The user's mask image (white: change), at the picture's size, with a soft edge."""
+    if SIZE_NODE not in graph:
+        raise EditError("inpainting needs the picture at the original's size")
+    load, to_image, scale, blur, to_mask = (str(BASE + 200 + i) for i in range(5))
+    graph[load] = {"class_type": "LoadImageMask", "inputs": {"image": mask_name, "channel": "red"}}
+    graph[to_image] = {"class_type": "MaskToImage", "inputs": {"mask": [load, 0]}}
+    graph[scale] = {
+        "class_type": "ImageScale",
+        "inputs": {"image": [to_image, 0], "upscale_method": "bilinear", "width": [SIZE_NODE, 0],
+                   "height": [SIZE_NODE, 1], "crop": "disabled"},
+    }  # fmt: skip
+    graph[blur] = {"class_type": "ImageBlur", "inputs": {"image": [scale, 0], "blur_radius": 8, "sigma": 4.0}}
+    graph[to_mask] = {"class_type": "ImageToMask", "inputs": {"image": [blur, 0], "channel": "red"}}
+    return [to_mask, 0]
+
+
+def mask_scaled(graph: dict, mask: list, megapixels: float) -> list:
+    """A mask brought to the same size as an image scaled to `megapixels` (outpainting's border)."""
+    to_image, scale, to_mask = (str(BASE + 310 + i) for i in range(3))
+    graph[to_image] = {"class_type": "MaskToImage", "inputs": {"mask": mask}}
+    graph[scale] = {
+        "class_type": "ImageScaleToTotalPixels",
+        "inputs": {"image": [to_image, 0], "upscale_method": "bilinear", "megapixels": megapixels,
+                   "resolution_steps": 16},
+    }  # fmt: skip
+    graph[to_mask] = {"class_type": "ImageToMask", "inputs": {"image": [scale, 0], "channel": "red"}}
+    return [to_mask, 0]
+
+
+def sample_inside(graph: dict, image: list, mask: list) -> None:
+    """Start from the image itself and let the sampler change only what the mask covers."""
+    sampler = node_of(graph, "SamplerCustomAdvanced") or node_of(graph, "KSampler")
+    vae = node_of(graph, "VAELoader")
+    if sampler is None or vae is None:
+        raise EditError("this workflow can't paint inside a mask")
+    encode, masked = str(BASE + 400), str(BASE + 401)
+    graph[encode] = {"class_type": "VAEEncode", "inputs": {"pixels": image, "vae": [vae, 0]}}
+    graph[masked] = {"class_type": "SetLatentNoiseMask", "inputs": {"samples": [encode, 0], "mask": mask}}
+    graph[sampler]["inputs"]["latent_image"] = [masked, 0]
+
+
+def paste(graph: dict, destination: list, source: list, mask: list) -> None:
+    """The saved picture becomes `destination` with `source` pasted where the mask is white."""
+    save = save_node(graph)
+    nid = str(BASE + 500)
+    graph[nid] = {
+        "class_type": "ImageCompositeMasked",
+        "inputs": {"destination": destination, "source": source, "x": 0, "y": 0, "resize_source": False,
+                   "mask": mask},
+    }  # fmt: skip
+    graph[save]["inputs"]["images"] = [nid, 0]
+
+
+def inpaint(graph: dict, original: list, mask_name: str) -> None:
+    """Change only where the mask image is white: sampled there from the original, then pasted into it."""
+    mask = mask_from_file(graph, mask_name)
+    sample_inside(graph, original, mask)
+    paste(graph, original, graph[save_node(graph)]["inputs"]["images"], mask)
+
+
+def pad_canvas(graph: dict, image: list, pads: tuple[int, int, int, int]) -> tuple[list, list]:
+    """Outpainting's canvas, bigger by `pads` (left, top, right, bottom); (canvas, mask of the new border).
+
+    The border starts as a blurred, stretched copy of the image rather than flat grey: a fast model keeps a little of
+    what it starts from, and grey would show.
+    """
+    pad, size, stretched, blurred, canvas = (str(BASE + 300 + i) for i in (0, 2, 3, 4, 5))
+    left, top, right, bottom = pads
+    graph[pad] = {
+        "class_type": "ImagePadForOutpaint",
+        "inputs": {"image": image, "left": left, "top": top, "right": right, "bottom": bottom, "feathering": 48},
+    }
+    graph[size] = {"class_type": "GetImageSize", "inputs": {"image": [pad, 0]}}
+    graph[stretched] = {
+        "class_type": "ImageScale",
+        "inputs": {"image": image, "upscale_method": "bilinear", "width": [size, 0], "height": [size, 1],
+                   "crop": "disabled"},
+    }  # fmt: skip
+    graph[blurred] = {"class_type": "ImageBlur", "inputs": {"image": [stretched, 0], "blur_radius": 31, "sigma": 10.0}}
+    graph[canvas] = {
+        "class_type": "ImageCompositeMasked",
+        "inputs": {"destination": [blurred, 0], "source": image, "x": left, "y": top, "resize_source": False},
+    }
+    return [canvas, 0], [pad, 1]
+
+
+def outpaint(graph: dict, canvas_scaled: list, border: list, megapixels: float) -> None:
+    """Fill only the new border, sampled around the original, and keep the original exactly as it was."""
+    mask = mask_scaled(graph, border, megapixels)
+    sample_inside(graph, canvas_scaled, mask)
+    invert = str(BASE + 501)
+    graph[invert] = {"class_type": "InvertMask", "inputs": {"mask": mask}}
+    paste(graph, graph[save_node(graph)]["inputs"]["images"], canvas_scaled, [invert, 0])
+
+
+# ----------------------------------------------------------------------------- sizes and arguments
+
+
+def image_size(path: Path) -> tuple[int, int]:
+    """Width and height from a PNG, JPEG or WebP file's header."""
+    data = path.read_bytes()[:65536]
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return struct.unpack(">II", data[16:24])
+    if data[:2] == b"\xff\xd8":
+        i = 2
+        while i + 9 < len(data):
+            if data[i] != 0xFF:
+                i += 1
+                continue
+            marker = data[i + 1]
+            length = struct.unpack(">H", data[i + 2 : i + 4])[0]
+            if marker in (0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF):
+                h, w = struct.unpack(">HH", data[i + 5 : i + 9])
+                return w, h
+            i += 2 + length
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        kind = data[12:16]
+        if kind == b"VP8X":
+            return int.from_bytes(data[24:27], "little") + 1, int.from_bytes(data[27:30], "little") + 1
+        if kind == b"VP8 ":
+            w, h = struct.unpack("<HH", data[26:30])
+            return w & 0x3FFF, h & 0x3FFF
+        if kind == b"VP8L":
+            bits = int.from_bytes(data[21:25], "little")
+            return (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
+    raise EditError(f"can't read the size of {path.name}: use a PNG, JPEG or WebP image")
+
+
+def pads_for_ratio(width: int, height: int, ratio: str) -> tuple[int, int, int, int]:
+    """Borders that bring the image to an aspect ratio (a:b), split evenly, in steps of 8 pixels."""
+    m = re.fullmatch(r"(\d{1,2}):(\d{1,2})", ratio)
+    if not m or not int(m.group(1)) or not int(m.group(2)):
+        raise EditError("the shape to extend to is a ratio, e.g. --ar 16:9")
+    a, b = int(m.group(1)), int(m.group(2))
+    if abs(width / height - a / b) < 0.01:
+        raise EditError(f"it's {a}:{b} already: choose another shape, or --left/--right/--top/--bottom pixels")
+    if width / height < a / b:  # wider
+        extra = round(height * a / b) - width
+        left = (extra // 2) // 8 * 8
+        return left, 0, (extra - left + 7) // 8 * 8, 0
+    extra = round(width * b / a) - height
+    top = (extra // 2) // 8 * 8
+    return 0, top, 0, (extra - top + 7) // 8 * 8
+
+
+EXTEND_FLAG = re.compile(r"--(left|top|right|bottom)\s+(\d+)")
+
+
+def parse_extend(text: str, width: int, height: int) -> tuple[tuple[int, int, int, int], str]:
+    """`/extend` arguments: --ar 16:9, or --left/--top/--right/--bottom pixels; the rest describes the new part."""
+    sides = {k: int(v) for k, v in EXTEND_FLAG.findall(text)}
+    text = EXTEND_FLAG.sub(" ", text)
+    ratio = re.search(r"--(?:ar|size)\s+(\S+)", text)
+    text = re.sub(r"--(?:ar|size)\s+\S+", " ", text)
+    if ratio and sides:
+        raise EditError("extend by a shape (--ar 16:9) or by sides (--left 256), not both")
+    if ratio:
+        from lcode.imageopts import SIZES
+
+        pads = pads_for_ratio(width, height, SIZES.get(ratio.group(1), ratio.group(1)))
+    elif sides:
+        pads = tuple((sides.get(k, 0) + 7) // 8 * 8 for k in ("left", "top", "right", "bottom"))
+        if any(p > 2048 for p in pads):
+            raise EditError("a side grows by at most 2048 pixels")
+    else:
+        pads = pads_for_ratio(width, height, "16:9" if width <= height * 16 / 9 - 1 else "1:1")
+    return pads, " ".join(text.split())
+
+
+REFERENCE = re.compile(r'(?:^|(?<=\s))@(#\d+|"[^"]+"|\S+)')
+
+
+def split_references(text: str) -> tuple[str, list[str]]:
+    """The prompt without its @references, and the references (#3, or file paths) in order."""
+    refs = [m.group(1).strip('"') for m in REFERENCE.finditer(text)]
+    return " ".join(REFERENCE.sub(" ", text).split()), refs
+
+
+def is_image(path: Path) -> bool:
+    return path.suffix.lower() in IMAGE_TYPES

lcode/imageopts.py

@@ -0,0 +1,207 @@
+"""Image options: how many, what shape, which seed, how good, what to avoid, which style.
+
+They're typed in the request (`a red fox --n 4 --ar 16:9 --seed 42 --quality best --style photo --no "people"`), or
+set for the session with `/options n=4 ar=16:9`. Flags in a request win over the session's options for that request.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import shlex
+from dataclasses import asdict, dataclass, replace
+
+QUALITIES = ("fast", "balanced", "best")
+MAX_COUNT = 8
+SIZES = {  # names for aspect ratios
+    "square": "1:1",
+    "portrait": "3:4",
+    "landscape": "4:3",
+    "wide": "16:9",
+    "tall": "9:16",
+    "photo": "3:2",
+    "cinema": "21:9",
+}
+STYLES = {
+    "photo": "professional photograph, natural light, sharp focus, 35mm lens",
+    "cinematic": "cinematic film still, dramatic lighting, shallow depth of field, color graded",
+    "anime": "anime illustration, clean line art, vibrant cel shading",
+    "watercolor": "watercolor painting, soft washes, visible paper texture",
+    "oil": "oil painting, visible brush strokes, rich colors",
+    "pixel": "pixel art, 16-bit, crisp pixels, limited palette",
+    "3d": "3D render, soft global illumination, studio lighting",
+    "sketch": "pencil sketch, graphite, cross-hatching, on paper",
+    "comic": "comic book art, bold ink outlines, halftone shading",
+    "flat": "flat vector illustration, minimal, bold shapes",
+}
+ALIASES = {
+    "n": "n",
+    "count": "n",
+    "ar": "size",
+    "aspect": "size",
+    "size": "size",
+    "seed": "seed",
+    "quality": "quality",
+    "q": "quality",
+    "no": "negative",
+    "negative": "negative",
+    "style": "style",
+}
+FLAG = re.compile(r"(?:^|\s)--?(" + "|".join(sorted(ALIASES, key=len, reverse=True)) + r")\b(?=[\s=]|$)")
+DIMENSIONS = re.compile(r"^(\d{2,4})\s*[x×]\s*(\d{2,4})$")
+RATIO = re.compile(r"^(\d{1,2})\s*:\s*(\d{1,2})$")
+
+
+class OptionError(ValueError):
+    pass
+
+
+@dataclass
+class Options:
+    n: int = 1
+    size: str = "1:1"  # an aspect ratio (16:9), a name (wide) or pixels (1344x768)
+    seed: int | None = None  # None: a new random seed for each image
+    quality: str = "balanced"
+    negative: str = ""
+    style: str = ""
+
+    def describe(self) -> str:
+        seed = "random" if self.seed is None else str(self.seed)
+        parts = [f"n={self.n}", f"size={self.size}", f"seed={seed}", f"quality={self.quality}"]
+        if self.style:
+            parts.append(f"style={self.style}")
+        if self.negative:
+            parts.append(f"no={self.negative!r}")
+        return " ".join(parts)
+
+    def to_json(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_json(cls, data: dict) -> Options:
+        known = {k: v for k, v in (data or {}).items() if k in cls.__dataclass_fields__}
+        try:
+            return set_values(cls(), known)
+        except OptionError:
+            return cls()
+
+
+def set_values(options: Options, values: dict[str, object]) -> Options:
+    """A copy of `options` with `values` (by name or alias) applied. Raises OptionError saying what's wrong."""
+    out = replace(options)
+    for raw_key, raw in values.items():
+        key = ALIASES.get(str(raw_key).lower().lstrip("-"))
+        if key is None:
+            raise OptionError(f"unknown option {raw_key!r}: use n, ar (or size), seed, quality, style or no")
+        value = str(raw).strip() if raw is not None else ""
+        if key == "n":
+            if not value.isdigit() or not 1 <= int(value) <= MAX_COUNT:
+                raise OptionError(f"n is how many images: 1 to {MAX_COUNT}")
+            out.n = int(value)
+        elif key == "size":
+            out.size = check_size(value)
+        elif key == "seed":
+            if value.lower() in ("random", "none", ""):
+                out.seed = None
+            elif value.isdigit() and int(value) < 2**63:
+                out.seed = int(value)
+            else:
+                raise OptionError("seed is a whole number, or random")
+        elif key == "quality":
+            if value.lower() not in QUALITIES:
+                raise OptionError(f"quality is {', '.join(QUALITIES)}")
+            out.quality = value.lower()
+        elif key == "style":
+            if value.lower() in ("none", "off", ""):
+                out.style = ""
+            elif value.lower() in STYLES:
+                out.style = value.lower()
+            else:
+                raise OptionError(f"style is one of {', '.join(STYLES)} (or none)")
+        elif key == "negative":
+            out.negative = "" if value.lower() in ("none", "off") else value
+    return out
+
+
+def check_size(value: str) -> str:
+    v = value.lower().replace(" ", "")
+    if v in SIZES:
+        return v
+    if RATIO.match(v):
+        w, h = (int(x) for x in RATIO.match(v).groups())
+        if w and h and 1 / 4 <= w / h <= 4:
+            return f"{w}:{h}"
+    m = DIMENSIONS.match(v)
+    if m:
+        w, h = (int(x) for x in m.groups())
+        if 256 <= w <= 2048 and 256 <= h <= 2048:
+            return f"{w}x{h}"
+        raise OptionError("a size in pixels is 256 to 2048 on each side, e.g. 1344x768")
+    raise OptionError(f"size is a ratio (16:9), pixels (1344x768) or one of {', '.join(SIZES)}")
+
+
+def parse(text: str, defaults: Options) -> tuple[str, Options]:
+    """The prompt without its flags, and the options for this request. Raises OptionError."""
+    matches = list(FLAG.finditer(text))
+    if not matches:
+        return text.strip(), defaults
+    prompt = text[: matches[0].start()]
+    values: dict[str, str] = {}
+    for i, m in enumerate(matches):
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        rest = text[m.end() : end].strip().lstrip("=").strip()
+        try:
+            words = shlex.split(rest)
+        except ValueError:
+            words = rest.split()
+        key = ALIASES[m.group(1).lower()]
+        if key == "negative":
+            values[key] = " ".join(words)
+        else:
+            if not words:
+                raise OptionError(f"--{m.group(1)} needs a value")
+            values[key] = words[0]
+            if len(words) > 1:  # words after a flag's value belong to the prompt
+                prompt += " " + " ".join(words[1:])
+    return prompt.strip(), set_values(defaults, values)
+
+
+def parse_assignments(text: str) -> dict[str, str]:
+    """`n=4 ar=16:9 no="blurry, text"` -> {"n": "4", "ar": "16:9", "no": "blurry, text"}."""
+    try:
+        words = shlex.split(text)
+    except ValueError as e:
+        raise OptionError(f"can't read {text!r}: {e}") from e
+    out = {}
+    for word in words:
+        key, sep, value = word.partition("=")
+        if not sep:
+            raise OptionError(f"write options as name=value, e.g. n=4 ar=16:9 (not {word!r})")
+        out[key] = value
+    return out
+
+
+def dimensions(size: str, megapixels: float, multiple: int = 16) -> tuple[int, int]:
+    """Width and height in pixels: from a ratio and the quality's megapixels, or exact pixels as given."""
+    m = DIMENSIONS.match(size)
+    if m:
+        w, h = (int(x) for x in m.groups())
+        return round_to(w, multiple), round_to(h, multiple)
+    ratio = SIZES.get(size, size)
+    w, h = (int(x) for x in ratio.split(":"))
+    area = megapixels * 1024 * 1024
+    width = math.sqrt(area * w / h)
+    return round_to(width, multiple), round_to(width * h / w, multiple)
+
+
+def round_to(value: float, multiple: int) -> int:
+    return max(multiple, round(value / multiple) * multiple)
+
+
+def replace_seed(options: Options, n: int | None = None) -> Options:
+    """The options with a random seed again (for /again and /vary), and optionally another count."""
+    return replace(options, seed=None, n=n or options.n)
+
+
+def styled(prompt: str, style: str) -> str:
+    return f"{prompt}, {STYLES[style]}" if style else prompt