Automatic Exact-Tile Prompt + Cache

Every tile in the Smart Upscaler pack gets its own prompt, written after looking at that tile's own pixels plus the whole-image context from SmartCachedTextGenerate. This is the node that does the writing: it captions each tile, validates what it's about to say, and assembles the final positive/negative prompt pair your image model will actually read. Cached per tile, so reruns are nearly free.

The whole trick of this pack is that the prompts are verified local rather than guessed. A tile showing a patch of lake is told it's part of the larger lake, using the same wording as its neighbours, so the seam doesn't disagree. A tile is never told about an object the scene pass placed somewhere else unless the tile's own pixels confirm it. That's the mechanism that stops tile-to-tile drift on flat surfaces - the thing that kills most tiled upscales.

How it works

The vision model (Qwen3-VL 4B FP8, same krea2 CLIPLoader setup as the whole-image node) gets the exact output-scale crop - unpadded, no mask, no colored locator border. That's deliberate: the pack's contract says literal edit models will describe diagnostic overlays as source content and reproduce them in your final image, so tiles are captioned bare.

The local pass returns a caption plus what the pack calls the target_prompt - the tile description with the task applied. Validation then decides what's safe to cache:

• Never cached without repair: empty/placeholder captions, black or generic backgrounds, missing targets, template echo, or anything matching your confirmed false detections.
• If a false concept slips through, deterministic code removes that clause and revalidates.

The result is a prompt that states what should be there, never the defect - "clean rendered wall", not "cracked, smeared wall".

Inputs that matter

Wired correctly in the shipped workflow; you'll touch almost nothing here on day one.

• clip, image, instruction, tile_reference, prompt_system - the vision model, the tile crop, the task brief from the Prompt Director, the tile's ID (T001, T002…), and the master prompt contract.
• negative_prompt_fallback - the deterministic negative, default changed geometry, duplicated objects, artifacts, seams. Fine as-is.
• cache_mode / cache_tag - per-tile caching. read_write is the default; bump cache_tag after changing the caption contract or the template.
• caption_max_side (optional, default 1344) - longest side of the tile sent to the vision model. 768–1024 saves VRAM with a small fine-detail cost; 0 sends the full tile.

Outputs: positive_prompt and negative_prompt (what the sampler reads), prompt_audit (the raw caption + which corrections fired), tile_reference, and cache_status. The prompts feed the sampler via SmartSamplerTileSelector; the audit strings feed SmartTilePromptAuditLog.

The trap: edit models vs denoise models

The README's most repeated warning, and it produces bad results with no error message. The prompt style is chosen by the Prompt Director's sampler_prompt_style setting, but know the split:

• Edit models (Flux 2 Klein, Qwen Edit) want an edit command plus a tile description.
• Denoise models (Z-Image Turbo, SDXL, Flux) want a plain description only.

Hand a denoise model an edit command and it paints your command words into the picture, because denoise models render every noun they're given. This pack is built around Z-Image Turbo with a Tile ControlNet, which is the denoise side - if you swap in an edit model, change the style setting with it.

Install and dependencies

Install the pack via ComfyUI Manager (search "ComfyUI-Smart-Upscaler") or:

cd ComfyUI/custom_nodes
git clone https://github.com/HallettVisual/ComfyUI-Smart-Upscaler

then restart. You also need ComfyUI-KJNodes and rgthree-comfy for the shipped workflow's wires and comparison sliders. No Python deps beyond ComfyUI; the models in docs/MODELS.md total about 13 GB, and the captioner (this node's engine) is the 4.9 GB Qwen3-VL file.

Common issues

• Empty or generic prompts - CLIPLoader type is not krea2. The vision tower isn't loaded, so the captioner is blind.
• Stale captions after a model change - change vision_model_id, not just cache_tag.
• Bad tile, no idea why - read the tile's prompt first (the SmartTileInspector is built for exactly this). It's almost always the instruction in the Prompt Director, fixable there rather than by changing models.

One prompt per tile, grounded in pixels, cached. It's the node that makes "exact-tile prompting" more than a marketing phrase.