Refine model card positioning and benchmark context

README.md

@@ -11,7 +11,13 @@ tags:
   - stable-diffusion
   - knowledge-distillation
   - compact
+  - small-model
   - local-inference
+  - edge-inference
+  - mobile-inference
+  - core-ml
+  - iphone
+  - sd-1.4-class
 widget:
   - text: "a glass of red wine"
     example_title: "Red wine"
@@ -51,7 +57,7 @@ widget:
       url: examples/prompt-gallery/original/image_81.png
 ---
 
-# Clover Image Tiny 🍀
+# Clover Image Tiny 🍀🤗
 
 ![Clover Image Tiny mosaic banner](assets/clover-image-tiny-banner.png)
 
@@ -61,41 +67,82 @@ Windows, or Linux.
 **323,384,964 denoiser parameters · about 1.67 GB · 4–100 inference steps ·
 PyTorch/Diffusers**
 
-Clover Image Tiny is intentionally a compact, local-first 512×512 model rather
-than a frontier-scale checkpoint. Its denoiser has 323,384,964 parameters; the
-small-model comparison below gives that scale practical runtime context.
+Clover Image Tiny 🤗 is an SD-1.4-class 512×512 diffusion checkpoint distilled
+for compact local inference. It follows the conventional Stable Diffusion 1.x
+text-to-image pipeline contract rather than a modern large-model architecture;
+results vary with the prompt, seed, scheduler, and number of denoising steps.
 
-Clover Image Tiny is the public PyTorch/Diffusers checkpoint release behind
-these examples. Its output has a recognizable, playful
-**DALL·E mini-ish** character. That is a visual description, not a claim of
-equivalent architecture, training scale, or benchmark performance.
+The small-model comparison below is intentionally candid: Clover is not
+presented as a quality winner. Its distinction is the complete, practical
+package around a compact denoiser—local Python inference, Core ML/iPhone
+integration, linked style adapters, prompt-linked examples, and a model card
+with enough provenance to reproduce the documented paths.
 
 [**Try Clover Image Tiny in the live ZeroGPU demo →**](https://huggingface.co/spaces/neonforestmist/Clover-Image-Tiny-Demo)
 
-[**Download the native iPhone project →**](Clover-iOS/)
+[**Explore the native iPhone/Core ML implementation →**](Clover-iOS/)
 
 The demo exposes prompt, negative prompt, seed, guidance, dimensions,
 scheduler, and 4–100 conventional Diffusers inference steps. It creates one
-image per request and keeps the packaged safety checker enabled.
+image per request and keeps the packaged safety checker enabled. The Hugging
+Face model pages carry the model cards, tags, prompt galleries, and links to
+the corresponding LoRA and Core ML releases.
+
+## 1. Overview
+
+### Model profile
+
+| Profile | Value |
+|---|---:|
+| Published PyTorch/Diffusers package | **~1.67 GB** |
+| Denoiser / U-Net | **323,384,964 parameters** · ~646.8 MB |
+| Text encoder | ~246.1 MB |
+| VAE | ~167.3 MB |
+| Safety checker | ~608.0 MB |
+| Native output | 512×512 |
+| Inference range | 4–100 steps |
+| Published formats | PyTorch/Diffusers + Core ML adapters |
+
+The package figure includes the text encoder, VAE, tokenizer/configuration, and
+the enabled upstream safety checker; it is therefore larger than the denoiser
+alone. The component sizes are a practical way to understand the footprint,
+not a claim that every byte is active in every runtime.
+
+### Why it stands out
+
+- **A small-model target with a complete workflow.** The 323.4M-parameter
+  denoiser is paired with a conventional Diffusers API, deterministic seeds,
+  scheduler controls, a safety path, and offline generation after the initial
+  download.
+- **Designed for local surfaces.** The same release is documented for Apple
+  silicon, CUDA, CPU, and an iPhone/Core ML path, with the heavier resources
+  split into versioned Hugging Face repositories.
+- **An extensible style family.** Monet, Pointillism, and Watercolor Anime
+  adapters are linked directly from the examples and published as both
+  Diffusers LoRAs and Core ML variants.
+- **Clear trade-offs.** The benchmark makes the quality/runtime limits visible
+  instead of hiding them behind a frontier-model comparison. The value here is
+  compactness, portability, and an unusually integrated 🤗 release surface.
 
 ## Contents
 
-1. [Examples](#1-examples)
-2. [Small-model benchmark](#2-small-model-benchmark)
-3. [iPhone and Core ML](#3-iphone-and-core-ml)
-4. [Run locally](#4-run-locally)
-5. [Generation controls](#5-generation-controls)
-6. [Hardware and operating systems](#6-hardware-and-operating-systems)
-7. [Python API](#7-python-api)
-8. [About this release](#8-about-this-release)
-9. [Quality and known behavior](#9-quality-and-known-behavior)
-10. [Safety](#10-safety)
-11. [Training lineage and data](#11-training-lineage-and-data)
-12. [Citation](#12-citation)
-13. [Licenses](#13-licenses)
-14. [Reproducibility and artifact identity](#14-reproducibility-and-artifact-identity)
-
-## 1. Examples
+1. [Overview](#1-overview)
+2. [Examples](#2-examples)
+3. [Small-model benchmark](#3-small-model-benchmark)
+4. [iPhone and Core ML](#4-iphone-and-core-ml)
+5. [Run locally](#5-run-locally)
+6. [Generation controls](#6-generation-controls)
+7. [Hardware and operating systems](#7-hardware-and-operating-systems)
+8. [Python API](#8-python-api)
+9. [About this release](#9-about-this-release)
+10. [Quality and known behavior](#10-quality-and-known-behavior)
+11. [Safety](#11-safety)
+12. [Training lineage and data](#12-training-lineage-and-data)
+13. [Citation](#13-citation)
+14. [Licenses](#14-licenses)
+15. [Reproducibility and artifact identity](#15-reproducibility-and-artifact-identity)
+
+## 2. Examples
 
 ### Prompt gallery
 
@@ -114,38 +161,24 @@ style adapters. These are visual references for the corresponding LoRA cards.
 |---|---|---|---|
 | [![Base model greenhouse](examples/normal-to-lora/normal.png)](https://huggingface.co/neonforestmist/Clover-Image-Tiny) | [![Monet greenhouse](examples/normal-to-lora/monet.png)](https://huggingface.co/neonforestmist/clover-image-tiny-monet-lora) | [![Pointillism greenhouse](examples/normal-to-lora/pointillism.png)](https://huggingface.co/neonforestmist/clover-image-tiny-pointillism-lora) | [![Watercolor Anime greenhouse](examples/normal-to-lora/watercolor_anime.png)](https://huggingface.co/neonforestmist/clover-image-tiny-watercolor-anime-lora) |
 
-### Reproducible baseline
-
-![Eight paired baseline and Clover Image Tiny examples](assets/clover-image-tiny-paired-contact-sheet.png)
-
-Each row uses the same prompt and seed. The left column is the pinned
-BK-SDM-Tiny-2M starting model; the right column is Clover Image Tiny. The
-gallery used an NVIDIA L4 in bfloat16, 50 PNDM steps, guidance 7.5, an empty
-negative prompt, and 512×512 output. With Diffusers 0.39.0, 50 requested PNDM
-steps use 51 U-Net calls because PLMS repeats its first retained timestep.
-
-All eight Clover images were finite, nonblank, nonblack, and cleared by the
-packaged upstream safety checker in this run. The set covers objects, a person,
-an animal, a landscape, an interior, food, a product, and a night scene.
-
-The local MPS reference used “a compact modern library with arched windows,”
-seed 1469, and the same 50-step configuration:
-
-![Clover Image Tiny local MPS library example](assets/clover-image-tiny-local-mps-library-seed-1469.png)
-
-## 2. Small-model benchmark
+## 3. Small-model benchmark
 
 Clover is compared with its pinned BK-SDM-Tiny-2M base and two public
 same-family references using 16 prompts, identical seeds, 512×512 output, 30
 DDIM steps, guidance 7.5, and a shared NVIDIA A10G runtime. The measurement is
 an engineering comparison, not a human-preference leaderboard.
 
-| Model | U-Net parameters | Mean latency | Peak CUDA | Mean CLIP cosine |
-|---|---:|---:|---:|---:|
-| [Clover Image Tiny](https://huggingface.co/neonforestmist/Clover-Image-Tiny) | 323.4M | 1.024 s | 2,233 MB | 0.3195 |
-| [BK-SDM-Tiny-2M](https://huggingface.co/nota-ai/bk-sdm-tiny-2m) | 323.4M | 1.027 s | 2,230 MB | 0.3246 |
-| [Segmind Tiny-SD](https://huggingface.co/segmind/tiny-sd) | 323.4M | 1.028 s | 1,649 MB | 0.3345 |
-| [BK-SDM-v2-Tiny](https://huggingface.co/nota-ai/bk-sdm-v2-tiny) | 326.8M | 0.957 s | 2,067 MB | 0.3303 |
+| Model | U-Net parameters | Loaded pipeline parameters | Mean latency | Peak CUDA | Mean CLIP cosine |
+|---|---:|---:|---:|---:|---:|
+| [Clover Image Tiny](https://huggingface.co/neonforestmist/Clover-Image-Tiny) | 323.4M | 834.1M | 1.024 s | 2,233 MB | 0.3195 |
+| [BK-SDM-Tiny-2M](https://huggingface.co/nota-ai/bk-sdm-tiny-2m) | 323.4M | 834.1M | 1.027 s | 2,230 MB | 0.3246 |
+| [Segmind Tiny-SD](https://huggingface.co/segmind/tiny-sd) | 323.4M | 530.1M | 1.028 s | 1,649 MB | 0.3345 |
+| [BK-SDM-v2-Tiny](https://huggingface.co/nota-ai/bk-sdm-v2-tiny) | 326.8M | 750.9M | 0.957 s | 2,067 MB | 0.3303 |
+
+The table keeps denoiser size and loaded pipeline size separate. The former is
+the most useful apples-to-apples model comparison; the latter includes the
+text encoder, VAE, and other loaded components and is runtime context rather
+than a download-size metric.
 
 CLIP cosine is only a prompt-adherence proxy. It is not a human-quality score,
 FID, safety evaluation, or evidence that these models are interchangeable.
@@ -155,7 +188,7 @@ The complete protocol, machine-readable results, and generated examples are in
 
 ![Four-prompt small-model comparison](benchmarks/text-to-image/results/clover-small-model-comparison-20260825/contact-sheet.png)
 
-## 3. iPhone and Core ML
+## 4. iPhone and Core ML
 
 The SwiftUI app in [`Clover-iOS`](Clover-iOS/) follows Apple platform
 conventions and exposes prompt, negative prompt, steps, guidance, seed, image
@@ -180,7 +213,7 @@ own Core ML picker download:
 See [`COREML.md`](COREML.md) for conversion details and
 [`training/README.md`](training/README.md) for the pinned LoRA jobs.
 
-### 3.1 Inpainting track
+### 4.1 Inpainting track
 
 The 9-channel SD 1.4-class inpainting adaptation is trained and packaged separately:
 [`neonforestmist/Clover-Image-Tiny-Inpaint`](https://huggingface.co/neonforestmist/Clover-Image-Tiny-Inpaint).
@@ -196,12 +229,12 @@ diverse free-form and object-like masks. It improved held-out masked MAE by
 96-pixel mask-context crop; the runtime composites through the exact mask so
 unmasked pixels remain unchanged.
 
-## 4. Run locally
+## 5. Run locally
 
 Download once, then generate offline with the bundled runner. Python 3.11 and
 3.12 are supported.
 
-### 4.1 macOS — Apple silicon
+### 5.1 macOS — Apple silicon
 
 ~~~bash
 mkdir clover-image-tiny-local
@@ -232,7 +265,7 @@ open clover-image-tiny.png
 
 Use `python3.11` instead if that is the installed supported Python.
 
-### 4.2 Windows — PowerShell
+### 5.2 Windows — PowerShell
 
 ~~~powershell
 mkdir clover-image-tiny-local
@@ -264,7 +297,7 @@ Invoke-Item .\clover-image-tiny.png
 Use `py -3.11` if needed. With `--device auto`, the runner selects an
 available NVIDIA CUDA GPU and otherwise uses CPU.
 
-### 4.3 Linux
+### 5.3 Linux
 
 ~~~bash
 mkdir clover-image-tiny-local
@@ -293,7 +326,7 @@ python model/examples/generate.py \
 uses CPU. After the first download, `--local-files-only` prevents network
 access during generation.
 
-## 5. Generation controls
+## 6. Generation controls
 
 The command above is ready to copy. Change these flags to explore the model:
 
@@ -324,7 +357,7 @@ outputs are never overwritten.
 
 Run `python model/examples/generate.py --help` for the complete CLI reference.
 
-## 6. Hardware and operating systems
+## 7. Hardware and operating systems
 
 | System | Automatic backend | Precision | Current evidence |
 |---|---|---|---|
@@ -344,7 +377,7 @@ image in 18.21 seconds with fp16 MPS. Its process-lifetime maximum RSS was
 631,341,056 bytes. This is a measured point, not a minimum-RAM claim. No Core
 ML package is required for the Python path.
 
-## 7. Python API
+## 8. Python API
 
 ~~~python
 import torch
@@ -380,7 +413,7 @@ image.save("clover-image-tiny.png")
 Seeded generation is repeatable within the selected runtime. Different
 devices, dtypes, kernels, and dependency builds can produce different pixels.
 
-## 8. About this release
+## 9. About this release
 
 Clover Image Tiny is a conventional knowledge-distillation checkpoint trained
 for 500 optimizer steps on an exact licensed 1,000-pair calibration set. The
@@ -399,7 +432,7 @@ reproducible Core ML conversion and iPhone app source. The downloadable Core ML
 artifacts and style adapters are versioned in the separate repositories linked
 above.
 
-## 9. Quality and known behavior
+## 10. Quality and known behavior
 
 - The included gallery demonstrates recognizable subjects across colorful
   scenes, products, food, an animal, a landscape, and an interior.
@@ -407,11 +440,11 @@ above.
   steps increase runtime but do not guarantee a better result.
 - Hands, anatomy, exact counts and relationships, and readable text can be
   difficult.
-- The paired eight-prompt gallery is a reproducible engineering sample, not a
-  controlled benchmark or broad human-preference study.
+- The small-model comparison is an engineering benchmark with a CLIP
+  prompt-adherence proxy, not a controlled human-preference study.
 - Resolution and batch size multiply memory use.
 
-## 10. Safety
+## 11. Safety
 
 The upstream safety checker is packaged and enabled in both the supported
 runner and hosted demo. A flagged output may be returned as a black placeholder;
@@ -424,7 +457,7 @@ outputs before sharing them. Do not use the model for consequential decisions,
 identity claims, medical or legal conclusions, harassment, exploitation,
 illegal activity, or uses prohibited by CreativeML OpenRAIL-M.
 
-## 11. Training lineage and data
+## 12. Training lineage and data
 
 - Clover fine-tuning data: exactly 1,000 accepted image-caption pairs from
   `Spawning/PD3M@2a5eb24a8dccf245acd8e56341761aee06da0bdf`
@@ -444,7 +477,7 @@ for all foundational pretraining is not available to this project.
 See `DATA_PROVENANCE.md` for the portable manifest identity and
 `MODEL_DATA_LICENSES.md` for the complete component ledger.
 
-## 12. Citation
+## 13. Citation
 
 If Clover Image Tiny is useful in your work, please cite the model release:
 
@@ -457,7 +490,7 @@ If Clover Image Tiny is useful in your work, please cite the model release:
 }
 ```
 
-## 13. Licenses
+## 14. Licenses
 
 The model weights are a derivative under **CreativeML OpenRAIL-M**. The example
 runner and packaging code are under **Apache-2.0**. Dataset and item-level terms
@@ -469,7 +502,7 @@ request for display in this public model repository. It is not benchmark
 evidence, its panel-generation provenance is not claimed, and this package
 does not grant a downstream reuse license for it.
 
-## 14. Reproducibility and artifact identity
+## 15. Reproducibility and artifact identity
 
 | Field | Value |
 |---|---|