lcode-cli 0.40.0__tar.gz → 0.41.0__tar.gz

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.41.0] - 2026-10-23
+
+### Added
+
+- **Image models to choose from, installed by lcode** (#150). lcode's media catalog lists the image
+  models it can run, with their size, license, measured speed and whether they fit your GPU.
+  **Z-Image Turbo** (photorealistic) joins FLUX.2 klein 4B (fast): 17 s and 3.5 s per 1024×1024
+  image on a 12 GB laptop GPU. See
+  [Image models](https://nasser1941.github.io/lcode/modes/#image-models).
+  - **Choose one:** `/models` in image mode (numbered) or `/model z-image-turbo` switches; the
+    `image_model` setting is the default, and sessions keep theirs.
+  - **Installed on demand:** a model that isn't installed downloads with your next image, after you
+    say yes, or ahead with `lcode media install <model>`. lcode downloads only the missing files
+    (models share text encoders and VAEs) into ComfyUI's model folders, checks the disk first,
+    verifies each file's SHA-256, and resumes interrupted downloads. `HF_TOKEN` works for gated
+    models.
+  - **`lcode media`** lists image and video models with what fits and what's installed, and
+    `lcode doctor` says how to install the image model when it's missing.
+
 ## [0.40.0] - 2026-10-23
 
 ### Added
@@ -904,7 +923,8 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.40.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.41.0...HEAD
+[0.41.0]: https://github.com/nasser1941/lcode/compare/v0.40.0...v0.41.0
 [0.40.0]: https://github.com/nasser1941/lcode/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/nasser1941/lcode/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/nasser1941/lcode/compare/v0.37.0...v0.38.0

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.40.0
+Version: 0.41.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/docs/configuration.md

@@ -27,6 +27,7 @@ lcode config path                      # print the file location
 | `comfyui_url` | `http://127.0.0.1:8188` | ComfyUI's address, for image and video mode |
 | `comfyui_path` | (found) | Your ComfyUI folder, if lcode doesn't find it; lcode starts it when needed ([ComfyUI](modes.md#comfyui)) |
 | `media_dir` | `.lcode/media` | Where images and videos go: a folder in the project, or an absolute path |
+| `image_model` | `flux2-klein-4b` | The model image mode uses: a key from `lcode media` ([image models](modes.md#image-models)) |
 | `think` | `true` | Let the model reason before answering |
 | `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |
 | `search_backend` | `auto` | `auto`, `ollama`, `brave`, `tavily` or `searxng`; `auto` uses the first one configured |

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/docs/modes.md

@@ -34,9 +34,8 @@ in code mode even if they're still in your `mcp.json`. It says so once.
 
 In image mode, what you type is a description, and lcode makes the picture. No language model is
 involved: lcode fills in its own ComfyUI workflow for the image model and follows the job itself.
-For now that's one image per request, 1024×1024, with **FLUX.2 klein 4B** (4 steps, about 8 seconds
-on a 12 GB laptop GPU; a 4B model that fits in 8 GB). Choosing models, sizes, seeds and variations
-comes next (#150, #151).
+For now that's one image per request, 1024×1024, with the image model you choose (see
+[Image models](#image-models)). Sizes, seeds and variations come next (#151).
 
 - **Progress:** the status line says what ComfyUI is doing (loading the model, reading the
   prompt, drawing, decoding), the step, the time left and the time so far. If other jobs are ahead
@@ -73,12 +72,67 @@ ComfyUI runs the image and video models; lcode drives it through its API.
   uvx --from comfy-cli comfy install
   ```
 
-- **The image model** has to be in ComfyUI's model folders for now: for FLUX.2 klein 4B,
-  `diffusion_models/flux-2-klein-4b-fp8.safetensors`, `text_encoders/qwen_3_4b.safetensors` and
-  `vae/flux2-vae.safetensors` (from ComfyUI's FLUX.2 klein template). lcode names any that are
-  missing. Installing models from lcode comes with #150.
 - **`lcode doctor`** shows whether ComfyUI is running or found, and whether the image model is
-  there.
+  installed.
+
+## Image models
+
+lcode's media catalog lists the image models it can run, with what each needs and whether it fits
+your machine. `/models` in image mode shows them, numbered; pick one with its number, or `/model
+z-image-turbo`. `lcode config set image_model z-image-turbo` makes one the default.
+
+```text
+image ❯ /models
+  1. ● FLUX.2 klein 4B (flux2-klein-4b)  text-to-image · 12.4 GB · installed · fits (~9 GB of 12 GB GPU memory)
+        1024×1024: 3.5 s per image, 14 s for the first with ComfyUI starting (RTX 4080 Laptop, 12 GB)
+  2.   Z-Image Turbo (z-image-turbo)  text-to-image · 14.6 GB · 6.5 GB to download · fits (~9 GB of 12 GB GPU memory)
+        1024×1024: 17 s per image (1.9 s per step), 23 s for the first (RTX 4080 Laptop, 12 GB)
+  Switch to which model? (number or name, Enter to keep FLUX.2 klein 4B): 2
+Image model: Z-Image Turbo.
+Not installed yet: 6.5 GB download with your next image (you're asked first).
+```
+
+| Model | Made by | License | Steps | Good at |
+|---|---|---|---|---|
+| **FLUX.2 klein 4B** (default) | Black Forest Labs | Apache 2.0 | 4 | Speed: a few seconds per image |
+| **Z-Image Turbo** | Tongyi-MAI (Alibaba) | Apache 2.0 | 8 | Photorealism, text in images; slower |
+
+Measured speeds are in the list (`/models`, `lcode media`) and in [Measured](#measured).
+
+- **Installing:** a model that isn't installed downloads with your next image, after you say yes.
+  You can also install it ahead with `lcode media install z-image-turbo`. lcode downloads only
+  the files ComfyUI doesn't have: models share text encoders and VAEs, so Z-Image Turbo needs
+  6.5 GB once FLUX.2 klein is there. Files go into ComfyUI's model folders, and the folders of
+  `extra_model_paths.yaml` count when ComfyUI is running.
+- **Safe downloads:** lcode checks the disk first and keeps 2 GB free. The progress shows the
+  speed and the time left. Each file is checked against Hugging Face's SHA-256 before it's used.
+- **Interrupted?** Ctrl+C pauses a download, and so does a dropped connection. Run the same install
+  again and it continues where it stopped (a `.part` file holds what arrived).
+- **Gated models:** for a model whose license you must accept on Hugging Face, accept it there
+  and set `HF_TOKEN`. lcode sends the token to huggingface.co only.
+- **Will it fit?** On NVIDIA GPUs the list compares an estimate of the GPU memory the model needs
+  with your GPU: the largest of its files plus 1.5 GB. ComfyUI loads the text encoder, the model and
+  the VAE one after another, so the largest file sets the need. A model too big for the GPU still
+  runs, slower, because ComfyUI keeps part of it in RAM. On Apple Silicon, the list compares it
+  with unified memory.
+
+```bash
+lcode media                        # image and video models, what fits, what's installed
+lcode media install z-image-turbo  # download what's missing (asks first; --yes doesn't)
+```
+
+### Measured
+
+On an RTX 4080 Laptop GPU (12 GB) with 32 GB of RAM, ComfyUI 0.38, 1024×1024, four different
+prompts each:
+
+| Model | First image (ComfyUI starting, model loading) | Each next image | Per step |
+|---|---|---|---|
+| FLUX.2 klein 4B (fp8) | 14.3 s | 3.5 s | 0.6 s (4 steps) |
+| Z-Image Turbo (int8) | 22.9 s | 17.4 s | 1.9 s (8 steps) |
+
+ComfyUI uses whatever GPU memory is free to keep models loaded (11.3 to 11.5 GB here), so the
+memory a model *needs* is lower than what `nvidia-smi` shows while it runs.
 
 ## One model on the GPU at a time
 
@@ -95,8 +149,7 @@ themselves:
 
 Video mode doesn't generate yet: a request there says what's coming instead of going anywhere.
 
-- **#150 Media model catalog:** image and video models that fit your machine, installed on
-  demand.
+- **#150 Media model catalog** (image models done; video models come with video generation).
 - **#151, #152 Image mode:** generating, variations, sizes and seeds, a gallery, editing,
   references, inpainting, upscaling.
 - **#153, #154 Video mode:** from text or a start image, first and last frames, several

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.40.0 — local coding agent           │
+│ lcode v0.41.0 — local coding agent           │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/docs/usage.md

@@ -7,6 +7,7 @@ lcode [options]              # interactive session in the current directory
 lcode setup [model]          # pick, download and configure a model
 lcode models                 # the model catalog and what fits this machine
 lcode doctor                 # check the installation (include this in bug reports)
+lcode media [install MODEL]  # image and video models: what fits here, what's installed; install one
 lcode config [set|unset]     # show or change settings
 lcode bench [models]         # score models on small coding tasks on this machine
 lcode mcp [catalog|add|list] # connect MCP servers: Jira, GitHub, AWS, databases… (see MCP servers)

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/src/lcode/__init__.py

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

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/src/lcode/agent.py

@@ -308,6 +308,7 @@ class Settings:
     comfyui_url: str = "http://127.0.0.1:8188"
     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)
     num_batch: int | None = None
     keep_alive: str = "30m"
     think: bool = True
@@ -687,6 +688,7 @@ class Agent:
             "cwd": str(self.workspace),  # where `lcode -c` there finds it, wherever the shell moved
             "model": self.settings.model,
             "mode": self.settings.mode,
+            "image_model": self.settings.image_model,
             "name": self.session_name,
             "title": self.session_title,
             "messages": self.messages,
@@ -735,6 +737,8 @@ class Agent:
         self.session_name = data.get("name", "")
         if data.get("mode") in ("code", "image", "video"):
             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"]
         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_cli-0.40.0 → lcode_cli-0.41.0}/src/lcode/api.py

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

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/src/lcode/cli.py

@@ -777,9 +777,10 @@ def exit_on_hangup() -> None:
 
 def comfyui_status(cfg: dict) -> tuple[str, bool | None]:
     """lcode doctor's ComfyUI line: running or found, and whether the image model is there."""
-    from lcode import comfy, media
+    from lcode import comfy
+    from lcode import media_catalog as catalog
 
-    workflow = comfy.load_workflow(media.IMAGE_WORKFLOW)
+    model = catalog.load().find(cfg.get("image_model") or "") or catalog.load().models[catalog.DEFAULT_IMAGE]
     server = comfy.Server(cfg["comfyui_url"])
     stats = server.stats()
     install = None if stats else comfy.find_install(cfg["comfyui_path"])
@@ -787,14 +788,13 @@ def comfyui_status(cfg: dict) -> tuple[str, bool | None]:
         return "not found: image mode offers to install it (or lcode config set comfyui_path <folder>)", None
     if stats:
         where = f"{(stats.get('system') or {}).get('comfyui_version', '?')} running at {server.url}"
-        installed = {folder: set(server.models(folder)) for folder in workflow.models}
     else:
         where = f"{install.path} (lcode starts it in image mode)"
-        installed = {folder: set(comfy.local_models(install, folder)) for folder in workflow.models}
-    missing = [f"{f}/{names[0]}" for f, names in workflow.models.items() if not installed[f] & set(names)]
+    _, missing = catalog.chosen_files(model, catalog.lister(server if stats else None, install))
     if missing:
-        return f"{where} · {workflow.name} not installed (missing {', '.join(missing)})", None
-    return f"{where} · image model: {workflow.name}", True
+        size = sum(f.gb for f in missing)
+        return f"{where} · {model.name} not installed: lcode media install {model.key} ({size:.1f} GB)", None
+    return f"{where} · image model: {model.name}", True
 
 
 def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
@@ -909,6 +909,13 @@ def build_subparsers() -> dict[str, argparse.ArgumentParser]:
     subs["setup"] = p
     subs["models"] = argparse.ArgumentParser(prog="lcode models", description="List models and how they fit here.")
     subs["doctor"] = argparse.ArgumentParser(prog="lcode doctor", description="Check the installation.")
+    p = argparse.ArgumentParser(
+        prog="lcode media", description="Image and video models: list them, with how they fit here, or install one."
+    )
+    p.add_argument("action", nargs="?", choices=["list", "install"], default="list")
+    p.add_argument("model", nargs="?", help="with install: a model key from the list, e.g. z-image-turbo")
+    p.add_argument("-y", "--yes", action="store_true", help="don't ask before downloading")
+    subs["media"] = p
     p = argparse.ArgumentParser(prog="lcode config", description="Show or change settings.")
     p.add_argument("action", nargs="?", choices=["show", "set", "unset", "path"], default="show")
     p.add_argument("key", nargs="?", choices=list(config.SETTINGS))
@@ -1065,6 +1072,55 @@ def cmd_index(args) -> None:
     )
 
 
+def cmd_media(args) -> None:
+    """lcode media [list] | install <model>: the media catalog, what's installed in ComfyUI, downloads."""
+    from rich.prompt import Confirm
+
+    from lcode import comfy, media
+    from lcode import media_catalog as catalog
+
+    try:
+        cfg = config.load()
+    except ConfigError as e:
+        fail(str(e))
+    cat, hw = catalog.load(), detect()
+    server = comfy.Server(cfg["comfyui_url"])
+    install = comfy.find_install(cfg["comfyui_path"])
+    running = server.stats() is not None
+    installed = catalog.lister(server if running else None, install) if running or install else None
+    if args.action == "install":
+        model = cat.find(args.model or "")
+        if model is None:
+            fail(f"no media model {args.model!r}: lcode media lists them")
+        if not running and install is None:
+            fail(f"lcode needs ComfyUI to install models into. {comfy.install_hint()}")
+        ask = None if args.yes else (lambda q: Confirm.ask(q, default=True, console=console))
+        try:
+            saved = catalog.install(model, server if running else None, install, console, ask)
+        except catalog.CatalogError as e:
+            fail(str(e))
+        how = f" ({len(saved)} file(s) downloaded)." if saved else "."
+        console.print(f"[green]{model.name} is installed[/]{how}")
+        return
+    where = (
+        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"):
+        models = cat.for_mode(mode)
+        console.print(f"[bold]{mode.capitalize()} models[/]")
+        if not models:
+            console.print(f"  [dim]{media.SOON[mode]}[/]\n")
+            continue
+        for m in models:
+            line = escape(catalog.describe(m, hw, installed))
+            console.print(f"  [bold]{m.key:<16}[/] {escape(m.name)} [dim]· {line}[/]")
+            if m.measured:
+                console.print(f"  {'':<16} [dim]{escape(m.measured)}[/]")
+        console.print()
+    console.print("[dim]Install one: lcode media install <model> · choose in image mode: /model <model>[/]")
+
+
 def cmd_mcp(args) -> None:
     from lcode.mcp.commands import run
 
@@ -1075,6 +1131,7 @@ COMMANDS = {
     "setup": cmd_setup,
     "models": cmd_models,
     "doctor": cmd_doctor,
+    "media": cmd_media,
     "config": cmd_config,
     "bench": cmd_bench,
     "mcp": cmd_mcp,

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/src/lcode/comfy.py

@@ -254,6 +254,14 @@ class Server:
         except (requests.RequestException, ValueError):
             return []
 
+    def folder_paths(self) -> dict[str, list[str]]:
+        """Where ComfyUI keeps each kind of model (its own folders and extra_model_paths.yaml's)."""
+        try:
+            r = requests.get(self.url + "/internal/folder_paths", timeout=10)
+            return r.json() if r.status_code == 200 else {}
+        except (requests.RequestException, ValueError):
+            return {}
+
     def upload(self, path: Path) -> str:
         """Upload an input image; the name to use in a workflow."""
         with path.open("rb") as f:
@@ -420,32 +428,18 @@ class Events:
 
 @dataclass
 class Workflow:
+    """A graph in ComfyUI's API format with `$name` placeholders: the model's files (by role, from media.toml),
+    the prompt, the seed and the settings in `defaults`."""
+
     key: str
-    name: str
-    task: str
-    models: dict[str, list[str]]  # ComfyUI folder -> file names it can use, preferred first
-    defaults: dict
     graph: dict
+    defaults: dict = field(default_factory=dict)
     labels: dict[str, str] = field(default_factory=dict)  # node id -> what it does, for progress
 
 
 def load_workflow(key: str) -> Workflow:
     data = json.loads(resources.files("lcode.workflows").joinpath(f"{key}.json").read_text())
-    return Workflow(key, data["name"], data["task"], data["models"], data.get("defaults", {}), data["graph"],
-                    data.get("labels", {}))  # fmt: skip
-
-
-def choose_files(server: Server, workflow: Workflow) -> tuple[dict[str, str], list[str]]:
-    """For each model the workflow needs, the installed file to use; and the folders where none is installed."""
-    chosen, missing = {}, []
-    for folder, names in workflow.models.items():
-        installed = set(server.models(folder))
-        found = next((n for n in names if n in installed), None)
-        if found:
-            chosen[folder] = found
-        else:
-            missing.append(f"{folder}/{names[0]}")
-    return chosen, missing
+    return Workflow(key, data["graph"], data.get("defaults", {}), data.get("labels", {}))
 
 
 PLACEHOLDER = re.compile(r"^\$([a-z_]+)$")

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/src/lcode/config.py

@@ -45,6 +45,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "comfyui_url": ("http://127.0.0.1:8188", str, "ComfyUI, for image and video mode"),
     "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`"),
     "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)"),
@@ -210,6 +211,12 @@ 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 == "image_model":
+        from lcode import media_catalog
+
+        keys = [m.key for m in media_catalog.load().for_mode("image")]
+        if value not in keys:
+            raise ConfigError(f"image_model must be one of {', '.join(keys)} (see lcode media)")
     if typ is bool and isinstance(value, str):
         if value.lower() not in ("true", "false", "1", "0", "yes", "no", "on", "off"):
             raise ConfigError(f"{key} must be true or false")

{lcode_cli-0.40.0 → lcode_cli-0.41.0}/src/lcode/media.py

@@ -1,7 +1,7 @@
 """Image and video mode: a request becomes media, made by ComfyUI (lcode.comfy) with no language model in between.
 
-For now image mode makes one image per request with FLUX.2 klein 4B, the engine's first workflow; models, sizes,
-variations and a gallery come with #150 and #151, video with #153.
+Image mode makes one image per request with the image model chosen from the media catalog (lcode.media_catalog);
+sizes, variations and a gallery come with #151, video with #153.
 """
 
 from __future__ import annotations
@@ -16,11 +16,12 @@ from typing import TYPE_CHECKING
 from rich.text import Text
 
 from lcode import comfy
+from lcode import media_catalog as catalog
 
 if TYPE_CHECKING:
     from lcode.agent import Agent
 
-IMAGE_WORKFLOW = "flux2-klein-4b-t2i"
+SOON = {"video": "Video models come with video generation (#153)."}
 IGNORED = "# lcode's images and videos: not part of the project unless you add them\n*\n"
 
 
@@ -28,8 +29,19 @@ class MediaError(Exception):
     pass
 
 
-def image_model() -> str:
-    return comfy.load_workflow(IMAGE_WORKFLOW).name
+def installed_lister(agent: Agent) -> catalog.Installed | None:
+    """What ComfyUI has installed: asked from it when it's running, else read from its folders; None: unknown."""
+    server = comfy.Server(agent.settings.comfyui_url)
+    if server.stats():
+        return catalog.lister(server)
+    install = comfy.find_install(agent.settings.comfyui_path)
+    return catalog.lister(install=install) if install else None
+
+
+def current(agent: Agent) -> catalog.MediaModel:
+    """The image model the agent uses (the image_model setting, or /model in image mode)."""
+    cat = catalog.load()
+    return cat.find(agent.settings.image_model) or cat.models[catalog.DEFAULT_IMAGE]
 
 
 @dataclass
@@ -183,6 +195,28 @@ class Line:
         return text
 
 
+def ensure_installed(
+    agent: Agent, model: catalog.MediaModel, server: comfy.Server, ask: Callable[[str], bool] | None
+) -> dict[str, str]:
+    """The model's files (role -> installed name), downloading the missing ones first when the user agrees."""
+    files, missing = catalog.chosen_files(model, catalog.lister(server))
+    if not missing:
+        return files
+    size = sum(f.gb for f in missing)
+    if ask is None:
+        raise MediaError(f"{model.name} isn't installed ({size:.1f} GB to download): lcode media install {model.key}")
+    install = comfy.find_install(agent.settings.comfyui_path)
+    try:
+        catalog.install(model, server=server, install=install, console=agent.console, ask=ask)
+    except catalog.CatalogError as e:
+        raise MediaError(str(e)) from e
+    files, missing = catalog.chosen_files(model, catalog.lister(server))
+    if missing:
+        raise MediaError(f"ComfyUI doesn't see {', '.join(f.name for f in missing)} yet: restart it and try again")
+    agent.say(f"Installed {model.name}.")
+    return files
+
+
 def generate_image(
     agent: Agent, prompt: str, cancelled: Callable[[], bool] = lambda: False, ask: Callable[[str], bool] | None = None
 ) -> Made:
@@ -193,20 +227,17 @@ def generate_image(
     server = engine(agent, ask, cancelled)
     for path in comfy.collect(server):
         agent.say(f"Saved {shown(agent, path)}: it finished while lcode wasn't watching.")
-    workflow = comfy.load_workflow(IMAGE_WORKFLOW)
-    files, missing = comfy.choose_files(server, workflow)
-    if missing:
-        raise MediaError(
-            f"{workflow.name} isn't installed in ComfyUI (missing {', '.join(missing)}). lcode installs image "
-            "models from #150 on; until then put the files in ComfyUI's models folder."
-        )
+    model = current(agent)
+    files = ensure_installed(agent, model, server, ask)
+    workflow = comfy.load_workflow(model.workflow)
     free_gpu(agent)
     seed = random.randrange(2**32)
     values = {**workflow.defaults, **files, "prompt": prompt, "seed": seed}
     graph = comfy.fill(workflow.graph, values)
     meta = {
         "prompt": prompt,
-        "model": workflow.name,
+        "model": model.name,
+        "model_key": model.key,
         "workflow": workflow.key,
         "seed": seed,
         "width": values["width"],
@@ -217,7 +248,7 @@ def generate_image(
     }
     out = folder(agent)
     stem = f"{time.strftime('%Y%m%d-%H%M%S')}-{comfy.slug(prompt)}"
-    line = Line(workflow.name, "Esc or Ctrl+C cancels" if agent.interactive else "")
+    line = Line(model.name, "Esc or Ctrl+C cancels" if agent.interactive else "")
     job = {"id": ""}
 
     def on_event(event: comfy.Event) -> None:
@@ -252,7 +283,7 @@ def generate_image(
     comfy.forget(prompt_id)
     if not saved:
         raise MediaError("ComfyUI finished but returned no image.")
-    made = Made(saved, workflow.name, seed, values["width"], values["height"], time.monotonic() - line.started)
+    made = Made(saved, model.name, seed, values["width"], values["height"], time.monotonic() - line.started)
     for path in saved:
         agent.console.print(
             Text("◆ ", style="green")

lcode_cli-0.41.0/src/lcode/media.toml

@@ -0,0 +1,74 @@
+# Image and video models lcode can run through ComfyUI (lcode.media_catalog).
+#
+# [files.<key>]  one file in ComfyUI's model folders, listed once: models share text encoders and VAEs.
+#   folder        ComfyUI's model folder (diffusion_models, text_encoders, vae, loras, …)
+#   name          the file name there
+#   url           where lcode downloads it from (Hugging Face; HF_TOKEN is used for gated files)
+#   gb            its size in GB (10^9 bytes)
+#   alternatives  other file names that do the same job: an installed one is used instead of downloading
+#
+# [models.<key>]  one model.
+#   mode          image or video
+#   tasks         text-to-image, edit, inpaint, text-to-video, image-to-video, first-last-frame, reference-to-video, audio
+#   workflow      lcode's workflow for it (lcode/workflows/<workflow>.json)
+#   files         role -> file key; the workflow's $role placeholders get the file names
+#   gpu_gb        GPU memory it needs, when known better than lcode's estimate (the largest file + 1.5 GB); ComfyUI
+#                 fills whatever is free with cached models, so nvidia-smi's peak doesn't tell
+#   measured      what it did on real hardware; models without it haven't been run yet
+
+[files.flux-2-klein-4b-fp8]
+folder = "diffusion_models"
+name = "flux-2-klein-4b-fp8.safetensors"
+url = "https://huggingface.co/black-forest-labs/FLUX.2-klein-4b-fp8/resolve/main/flux-2-klein-4b-fp8.safetensors"
+gb = 4.07
+alternatives = ["flux-2-klein-4b.safetensors"]
+
+[files.qwen-3-4b]
+folder = "text_encoders"
+name = "qwen_3_4b.safetensors"
+url = "https://huggingface.co/Comfy-Org/flux2-klein/resolve/main/split_files/text_encoders/qwen_3_4b.safetensors"
+gb = 8.04
+alternatives = ["qwen_3_4b_fp8_mixed.safetensors"]
+
+[files.flux2-vae]
+folder = "vae"
+name = "flux2-vae.safetensors"
+url = "https://huggingface.co/Comfy-Org/flux2-dev/resolve/main/split_files/vae/flux2-vae.safetensors"
+gb = 0.34
+
+[files.z-image-turbo-int8]
+folder = "diffusion_models"
+name = "z_image_turbo_int8_convrot.safetensors"
+url = "https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/diffusion_models/z_image_turbo_int8_convrot.safetensors"
+gb = 6.20
+alternatives = ["z_image_turbo_bf16.safetensors"]
+
+[files.flux-ae]
+folder = "vae"
+name = "ae.safetensors"
+url = "https://huggingface.co/Comfy-Org/z_image_turbo/resolve/main/split_files/vae/ae.safetensors"
+gb = 0.34
+
+[models.flux2-klein-4b]
+name = "FLUX.2 klein 4B"
+mode = "image"
+publisher = "Black Forest Labs"
+license = "Apache 2.0"
+tasks = ["text-to-image"]
+workflow = "flux2-klein-4b-t2i"
+files = { model = "flux-2-klein-4b-fp8", text_encoder = "qwen-3-4b", vae = "flux2-vae" }
+gpu_gb = 0.0
+measured = "1024×1024: 3.5 s per image, 14 s for the first with ComfyUI starting (RTX 4080 Laptop, 12 GB)"
+notes = "fast and small: 4 steps"
+
+[models.z-image-turbo]
+name = "Z-Image Turbo"
+mode = "image"
+publisher = "Tongyi-MAI (Alibaba)"
+license = "Apache 2.0"
+tasks = ["text-to-image"]
+workflow = "z-image-turbo-t2i"
+files = { model = "z-image-turbo-int8", text_encoder = "qwen-3-4b", vae = "flux-ae" }
+gpu_gb = 0.0
+measured = "1024×1024: 17 s per image (1.9 s per step), 23 s for the first (RTX 4080 Laptop, 12 GB)"
+notes = "photorealistic, writes text well: 8 steps"