Document HQ architecture and held-out quality gate

README.md

@@ -1,7 +1,9 @@
 ---
 library_name: diffusers
 pipeline_tag: image-to-image
-base_model: neonforestmist/Clover-Image-Tiny
+base_model:
+  - neonforestmist/Clover-Image-Tiny
+  - stable-diffusion-v1-5/stable-diffusion-inpainting
 license: creativeml-openrail-m
 tags:
   - clover-image
@@ -10,24 +12,20 @@ tags:
   - coreml
 ---
 
-# Clover Image Tiny Inpaint 🍀
+# Clover Image Tiny Inpaint HQ
 
-Clover Image Tiny Inpaint is a compact, context-aware inpainting model for the
-SD 1.4-class 512×512 architecture. Paint the region to replace in white; black
-pixels are preserved. This v2 checkpoint was selected from bounded
-teacher-distillation sweeps for semantic prompt following, reconstruction, and
-clean mask-edge blending.
+Clover Image Tiny Inpaint HQ is the high-quality, context-aware inpainting
+pipeline for Clover. It combines the complete Stable Diffusion 1.5 inpainting
+U-Net with Clover Image Tiny's tokenizer, text encoder, VAE, and scheduler.
+This preserves Clover compatibility while replacing the compact inpainting
+denoiser that frequently produced blurry or unrecognizable masked objects.
 
-The model uses the standard nine-channel inpainting contract:
+The pipeline uses the standard nine-channel inpainting contract:
 
 ```text
 [noisy latent (4), mask (1), masked-image latent (4)]
 ```
 
-The text encoder, VAE, scheduler, safety checker, and tokenizer remain
-compatible with Clover Image Tiny. A VAE encoder is additionally required to
-prepare the masked-image latent.
-
 ## Diffusers example
 
 ```python
@@ -41,7 +39,7 @@ pipe = AutoPipelineForInpainting.from_pretrained(
 ).to("cuda")
 pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config)
 
-result = pipe(
+image = pipe(
     prompt="a glossy red enamel kettle resting naturally on the countertop",
     negative_prompt="blurry, distorted, low detail",
     image=load_image("source.png"),
@@ -50,108 +48,74 @@ result = pipe(
     guidance_scale=6.0,
     padding_mask_crop=96,
 ).images[0]
-result.save("clover-inpaint.png")
+image.save("clover-inpaint.png")
 ```
 
-Recommended interactive defaults are DPM-Solver++, 20 steps, CFG 6.0, and
-`padding_mask_crop=96`. Keep runs at or below 50 steps. For production UI,
-composite the generated image through the exact binary mask so that every
-unmasked source pixel remains unchanged.
-
-## Inpainting examples
-
-All examples below use the selected v2 checkpoint, CFG 6.0, 30 evaluation
-steps, and a 96-pixel context crop. White is the region regenerated by Clover.
-
-### Context-aware object insertion
-
-Prompt: `a tabby cat sitting naturally on the wooden park bench`
-
-| Source | White mask | Result |
-|:---:|:---:|:---:|
-| ![Park bench source](examples/cat-source.png) | ![Cat edit mask](examples/cat-mask.png) | ![Cat inpaint result](examples/cat-result.png) |
-
-Prompt: `a glossy red enamel kettle resting naturally on the countertop`
+Recommended interactive defaults are DPM-Solver++, 20 steps, CFG 6.0, and a
+96-pixel context crop. Composite the generated result through the exact binary
+mask when unchanged source pixels must remain byte-for-byte untouched.
 
-| Source | White mask | Result |
-|:---:|:---:|:---:|
-| ![Kitchen source](examples/kettle-source.png) | ![Kettle edit mask](examples/kettle-mask.png) | ![Kettle inpaint result](examples/kettle-result.png) |
+## Quality gate
 
-### Irregular mask replacement
+The release was evaluated on 24 deterministic, held-out, human-rated
+InpaintCOCO edits. Every output was also reviewed in three visual contact
+sheets before release.
 
-Prompt: `a bright red bicycle standing naturally on the city street`
+| Metric | Previous Clover inpaint | HQ release | SD 1.5 inpaint teacher |
+|---|---:|---:|---:|
+| Masked prompt CLIP similarity (higher) | 0.2642 | **0.2768** | 0.2820 |
+| Masked target MAE (lower) | 0.2510 | **0.2231** | 0.2156 |
+| Changed pixels outside the mask | 0 | **0** | 0 |
 
-| Source | White mask | Result |
-|:---:|:---:|:---:|
-| ![Street source](examples/bicycle-source.png) | ![Bicycle edit mask](examples/bicycle-mask.png) | ![Bicycle inpaint result](examples/bicycle-result.png) |
+The HQ release improves prompt alignment by 4.8% and reduces masked target
+error by 11.1% relative to the previous Clover inpainting release. The visual
+gate showed recognizable buses, dogs, trains, furniture, signs, and
+scene-consistent lighting where the compact candidates often collapsed into
+amorphous fills.
 
-## Evaluation
+## Selection provenance
 
-The release gate used a deterministic 12-image held-out reconstruction set and
-six context-rich semantic edits with ellipse, rounded-rectangle, polygon, and
-brush masks.
+The release process compared the existing checkpoint, a 30,000-step full-U-Net
+distillation run, two fused context-LoRA refinements, partial weight blends,
+the full Stable Diffusion inpainting reference, and this Clover-component
+hybrid. The 30,000-step and context-LoRA candidates were rejected because they
+did not beat the existing release across both visual and quantitative gates.
+The published HQ architecture was the only Clover-compatible candidate that
+materially improved both prompt alignment and reconstruction.
 
-| Metric | Previous release | v2 |
-|---|---:|---:|
-| Held-out masked-region MAE (lower is better) | 0.3120 | **0.2517** |
-| Mean object-text CLIP similarity | 0.2726 | **0.2890** |
-| Mean CLIP image similarity to the SD inpainting teacher | 0.7651 | **0.8183** |
-| Black-collapse outputs | 0/6 | **0/6** |
-| Changed pixels outside the mask | 0 | **0** |
+- Inpainting U-Net revision:
+  `stable-diffusion-v1-5/stable-diffusion-inpainting@8a4288a76071f7280aedbdb3253bdb9e9d5d84bb`
+- Clover components: `neonforestmist/Clover-Image-Tiny`
+- Evaluation dataset: `phiyodr/InpaintCOCO@1ffac84be2dfc5ad9afccad868522fad64457435`
+- Selection platform: Modal H100
+- Evaluation seed: `20260813`
 
-Masked reconstruction MAE improved by 19.3%. Metrics are useful regression
-signals, not guarantees of photorealism; the visual contact sheet and per-case
-outputs were also reviewed before selection.
+## Core ML and style mixing
 
-## Training provenance
-
-- Warm start: `neonforestmist/Clover-Image-Tiny-Inpaint` at revision
-  `1b6f8ae3db51900520369d5522c7dc7c2a97e21e`
-- Teacher: `stable-diffusion-v1-5/stable-diffusion-inpainting` at revision
-  `8a4288a76071f7280aedbdb3253bdb9e9d5d84bb`
-- Dataset: `prithivMLmods/Caption3o-Opt` at revision
-  `17e893f785fcd3f5d6fc4a5d65a914b9f7b1ff5b`
-- Optimizer steps: 500, with cosine decay after warmup
-- Objective: teacher noise prediction plus ground-truth denoising, Min-SNR
-  weighting, and extra masked-region/boundary weighting
-- Masks: brush, multi-brush, rectangle, ellipse, polygon, multi-region, and
-  outpainting distributions
-- Caption dropout: 0.1
-- Training platform: Modal A10 in the `guccichungus69` workspace
-
-The longer run was rejected after its held-out and semantic gates regressed;
-the published checkpoint is the best-performing bounded sweep, not simply the
-last checkpoint.
-
-## Core ML
-
-The companion SD 1.4-class Core ML resources are published at
+The companion iOS resources are published at
 [`neonforestmist/Clover-Image-Tiny-Inpaint-CoreML`](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint-CoreML).
-The batch-one U-Net accepts `[1, 9, 64, 64]`; classifier-free guidance is run as
-two serial U-Net passes to reduce peak memory.
-
-## LoRA compatibility
-
-Diffusers can load a LoRA trained against this nine-channel inpainting U-Net.
-Regular Clover Image Tiny LoRAs target a four-channel U-Net and are not
-interchangeable. The Core ML package does not dynamically load inpainting
-LoRAs; fuse an inpainting-specific adapter before conversion if needed.
+Its batch-one stateful U-Net supports up to three Clover styles simultaneously
+with independent strengths. The style tensors remain separate downloads and
+are composed exactly at runtime; they are not fused into three full 1.6 GB
+models.
 
 ## Limitations
 
-The model can still distort small, highly structured objects, text, hands, and
-faces. Very small masks may not provide enough latent resolution without the
-recommended context crop. Results depend on the source, mask, prompt, seed,
-and scheduler. This release inherits the limitations and license obligations
-of its base and teacher models.
+Small text, hands, faces, exact logos, and masks below latent resolution can
+still fail. Output quality depends on the source, mask, prompt, scheduler,
+guidance, seed, and step count. This release inherits the limitations and
+license obligations of Clover Image Tiny and Stable Diffusion 1.5 inpainting.
 
 ## Citation
 
 ```bibtex
 @software{lozadaperez2026cloverimagetinyinpaint,
   author = {Lukas Lozada Perez},
-  title = {Clover Image Tiny Inpaint: Compact SD 1.4-Class Image Inpainting},
+  title = {Clover Image Tiny Inpaint HQ: Local Context-Aware Image Inpainting},
   year = {2026},
   url = {https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint}
 }
 ```
+
+Designed and developed independently by Lukas Lozada Perez. Open weights under
+the CreativeML Open RAIL-M license; complete local inference is supported.