# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

Local SDXL-base image generation on an Intel Arc B580 (12GB) under Slackware. Three files:
`imggen` (host bash wrapper) → `docker run` → `generate.py` (in-container, XPU). README.md carries
the full rationale and VRAM measurements; read it before changing behavior.

## Build and run

```
docker build -t imggen:local .        # image tag is hardcoded as imggen:local in the wrapper
cp imggen ~/bin/imggen && chmod +x ~/bin/imggen
imggen "a prompt" --steps 30 --seed 42 -o out.png -n "blurry"
```

No test suite, no lint config. Verification is running `imggen` end to end and checking the PNG.

## Architecture constraints (the whole point of the project)

- **12GB VRAM is the hard limit.** Stock SDXL fp16 OOMs at VAE decode because diffusers upcasts
  the VAE to fp32. The fix is the fp16-fix VAE (`madebyollin/sdxl-vae-fp16-fix`, hardcoded in
  `generate.py`). This one swap is why the pipeline fits. Do not remove it. Peak VRAM in the
  working config is 9.07 GB.
- **Scope is deliberately bounded:** SDXL base, single 1024x1024 image, 25 steps, no refiner,
  no Flux, no batching. Refiner/Flux/heavy work is explicitly out of scope and belongs on a
  RunPod endpoint, not here. Don't add them "to be helpful."
- **XPU only.** `build_pipe()` fails loud (`sys.exit(2)`) if `torch.xpu` is unavailable rather
  than falling back to CPU (which would be minutes per image). Keep that behavior.

## Version pinning is load-bearing

The Dockerfile pins EXACT versions (torch 2.12.1+xpu, diffusers 0.39.0, transformers 5.13.0,
etc.) captured from the known-good container. XPU-for-diffusion is young and fast-moving. Never
`pip install -U` or loosen a pin casually. torch comes from the Intel XPU wheel index
(`download.pytorch.org/whl/xpu`); everything else from PyPI. If you rebuild with newer versions,
keep the old Dockerfile in git to revert.

## Container boundaries

- `imggen` bind-mounts host `$IMGGEN_OUT` (default `~/imggen-out`) → `/out`, and
  `$IMGGEN_CACHE` (default `~/.cache/imggen-models`) → `/models`. `HF_HOME=/models` so the
  ~7.5GB weights download once. Output paths in `generate.py` are all under `/out`.
- All wrapper args pass straight through to `generate.py` argparse. Adding a CLI flag means
  editing `generate.py` only; the wrapper needs no change.
- GPU passthrough is `--device /dev/dri`.