# AGENTS.md

Guidance for AI coding agents working in this repository.

## What this is

`upscale-qt`: single-file PyQt6 desktop app (`upscale-qt`, no `.py`
extension) to upscale an image with an ESRGAN model through `sd-cli`
(stable-diffusion.cpp), compare before/after with a slider wipe, then save
as a new file or overwrite the original. A small vision model (imajev, run
one-shot through `llama-mtmd-cli`) suggests which upscaler to use. The only
Python dependency is PyQt6; everything else is stdlib plus the two external
binaries. Keep it a single file and do not add dependencies.

Design spec: `docs/superpowers/specs/2026-10-30-upscale-qt-design.md`.

## External tools

- Upscale: `sd-cli -M upscale --upscale-model <model> -i <in> -o <out.png>`.
  Models are `.pth`/`.safetensors`/`.gguf` files in the upscalers dir.
- Suggestion: `llama-mtmd-cli -m <imajev gguf> --mmproj <mmproj gguf>
  --image <in> -p <prompt>`. Its answer is free text and gets matched to a
  filename from the upscalers dir; never trust it as a path.
- Both run through `QProcess` so the UI never blocks.
- `sd-cli` loads ESRGAN (RRDBNet) and MoSR models only, detected from the
  weights. SwinIR, HAT, DAT, SPAN, Compact and face restorers do not load.
- Model choice, measured on 4x crops of a clean portrait, a landscape and a
  noisy 2009 phone JPEG: the 4x foolhardy model is best on clean photos
  (people and nature), `RealESRGAN_x4plus` on noisy or compressed sources
  (smooth, slightly waxy skin), `RealESRGAN_x4plus_anime_6B` for anime and
  art only. Rejected after testing: 4xNomos2_hq_mosr (amplifies JPEG
  blocks), 4xNomos8kSC (artifacts on noisy input), 4xLSDIRplusR (plastic
  on clean input), 4xLSDIRplusC (close to the foolhardy model, not better).
- Timing: an RRDBNet model takes about 25 s per megapixel of input, so a
  10 MP photo takes about 4 minutes and outputs a 160 MP image. imajev
  answers in about 7 s.

## Conventions

- Images are held in a list of jobs internally even though the UI shows one
  at a time, so batch mode can be added without a rewrite.
- Non-GUI logic lives in module-level functions so it can be tested without
  a display.
- Overwrite always asks for confirmation and keeps the original's format.
- Placeholders only in code, docs, tests and commits.

## Testing

No test suite yet.

## Repo facts

- License: GPLv2 only (`LICENSE`, header in each source file).
- Work directly on master.