Publish validated Clover Image Tiny research preview

README.md

@@ -14,15 +14,28 @@ tags:
 
 # Clover Image Tiny — Research Preview
 
-This is **Clover Image Tiny**, an early conventional knowledge-distillation
-checkpoint released as a research preview. It is a production-data pilot, not
-a release-ready model. It uses the compact BK-SDM-Tiny-2M architecture, a
-conventional 50-step PNDM schedule, 512×512 output, and classifier-free
-guidance 7.5.
-
-The checkpoint is useful for inspecting an early, licensed-data quality-refresh
-experiment. It is not a finished Clover release, a quality benchmark, or a
-claim of uniformly better output than its starting model.
+**Clover Image Tiny** is a compact, consumer-runnable text-to-image model with
+a 323,384,964-parameter denoiser and a complete Diffusers package of about
+1.67 GB. It generates locally on Apple silicon, NVIDIA CUDA systems, or CPU;
+no hosted inference API is required. Its examples have the recognizable,
+playful fidelity that can reasonably be described informally as
+**DALL·E mini-ish**. That phrase is a qualitative analogy, not a benchmark or
+claim of equivalent architecture, training scale, or measured quality.
+
+This exact artifact is a conventional knowledge-distillation checkpoint
+released as a research preview. Clover trained the checkpoint for 500 optimizer
+steps on an exact licensed 1,000-pair calibration set, so it is a genuinely
+modified model rather than a rename of unchanged upstream weights. It was
+**not trained from random initialization**: it starts from BK-SDM-Tiny-2M and
+was distilled with a frozen Stable Diffusion v1.4 teacher. Calling it "trained
+from scratch" would therefore be inaccurate. The validated reference recipe
+uses 50-step PNDM, 512×512 output, classifier-free guidance 7.5, and an empty
+negative prompt.
+
+The checkpoint is a production-data quality-refresh pilot, not a release-ready
+model or a controlled quality benchmark. Its compact size, coherent example
+outputs, exact lineage, and local runner make it useful today for creative
+experimentation and compact-model research.
 
 ## Exact artifact identity
 
@@ -37,10 +50,11 @@ claim of uniformly better output than its starting model.
 | Checkpoint-bundle SHA-256 | `384b6515f5f26838aea33ec9a941e06610a20764f0b8637c8b7b0667bfc0d447` |
 | Resolved-config SHA-256 | `80cf9395d1f587dc0c1d440d9f5b55c55c20703187998509bb306d19d463f597` |
 | Dataset-manifest SHA-256 | `50c1249f1cb0d8d690a9acc451ca10c9432eb5a7f4e26f34acb5462096e72322` |
-| Package bytes | `1671492371` |
+| Denoiser parameters | `323,384,964` |
+| Package bytes | `1671502657` |
 | Package files | `30` |
 | Validated Stage B source-package checksums SHA-256 | `d9a28d5fe6f5b675ee1b9db52e6d0493c8d3d357bb824eac590911acbd5c3ebc` |
-| Builder source commit | `e6079eec2b91c5d026bfb461fd6c844a98b888ec` |
+| Builder source commit | `647bac81f3713a0238eb21abf1844a8cd8d48f11` |
 
 The checkpoint completed 500 optimizer steps, 4,000 microsteps, and 4,000
 sample presentations. All 500 recorded training rows were finite and had a
@@ -61,8 +75,10 @@ With the pinned Diffusers 0.39.0 scheduler, those 50 requested PNDM steps use
 All eight Stage B gallery images were finite, nonblank, nonblack, and returned
 clear from the packaged upstream safety checker in that measured run. This
 small engineering subset is not a general safety or quality evaluation. The
-changes are modest and not uniformly better: the bottle example loses prompt
-fidelity, hands remain weak, and some details change without clear improvement.
+examples demonstrate recognizable objects, people, animals, landscapes,
+interiors, food, and night scenes. Results are not uniformly better than the
+starting model: the bottle example loses prompt fidelity, hands remain weak,
+and some details change without clear improvement.
 
 ## Run locally
 
@@ -72,6 +88,58 @@ space for the model itself. Mac MPS is the only local runtime measured for this
 preview; Windows/Linux CUDA and CPU execution are supported by the runner but
 their performance is not claimed here.
 
+### Generation controls
+
+The bundled runner exposes the ordinary Diffusers controls below. Its defaults
+exactly preserve the measured gallery recipe.
+
+| Argument | Accepted values | Default | Effect |
+|---|---|---|---|
+| `--steps` | 4–100 | `50` | Conventional diffusion inference steps; more steps usually take longer |
+| `--guidance-scale` | 0.0–20.0 | `7.5` | Strength of text guidance |
+| `--negative-prompt` | Text, or empty | Empty | Content or traits to discourage |
+| `--width` | 256–768, divisible by 64 | `512` | Output width |
+| `--height` | 256–768, divisible by 64 | `512` | Output height |
+| `--scheduler` | `pndm`, `ddim`, `euler`, `euler-a`, `dpmpp-2m` | `pndm` | Sampling algorithm |
+| `--num-images` | 1–4 | `1` | Images generated in one invocation |
+| `--seed` | 0–(2⁶³−1) | `1337` | Starting deterministic seed |
+
+Only **PNDM + 50 steps + guidance 7.5 + 512×512 + an empty negative
+prompt** is the validated gallery and local-MPS recipe. Other combinations are
+deliberately available for exploration, but no comparative quality or speed
+claim is attached to them. These are conventional diffusion steps, **not** the
+separate 1–4 Clover Leaf Steps system, which is not part of this package. In
+particular, selecting four or eight inference steps does not turn this
+checkpoint into a distilled four- or eight-step model.
+
+For example, this asks for two 512×512 images using 30 Euler steps, stronger
+guidance, and an explicit negative prompt:
+
+```bash
+python model/examples/generate.py \
+  --model model \
+  --device auto \
+  --local-files-only \
+  --prompt "a tiny glass greenhouse glowing in a moonlit garden, detailed photography" \
+  --negative-prompt "blurry, distorted, low detail" \
+  --steps 30 \
+  --guidance-scale 8.5 \
+  --scheduler euler \
+  --width 512 \
+  --height 512 \
+  --num-images 2 \
+  --seed 1337 \
+  --output greenhouse.png
+```
+
+For multiple images, the first is saved to the requested output and subsequent
+images use numbered names such as `greenhouse-02.png`. Seeds advance
+consecutively from the requested seed. One `greenhouse.png.json` sidecar records
+the resolved controls and every output filename and seed. The runner refuses to
+overwrite an existing planned image or sidecar. Resolution and batch size
+multiply memory use; reduce `--num-images`, width, or height if a consumer GPU
+runs out of memory.
+
 ### macOS Apple silicon — MPS
 
 These commands download a complete local copy, install the pinned runtime in
@@ -191,6 +259,9 @@ python examples/generate.py \
   --output clover-image-tiny.png
 ```
 
+Run `python examples/generate.py --help` for the complete control reference and
+accepted ranges.
+
 Seeded generation is repeatable only within the limits of the selected runtime.
 Different devices, dtypes, kernels, and dependency builds can produce different
 pixels. The bundled Mac example below was measured locally on an Apple M4 Pro
@@ -236,6 +307,8 @@ RAIL-M terms, and the package checksums for the portable evidence included here.
 
 - Research and inspection of compact Stable Diffusion knowledge distillation
 - Reproducing the fixed conventional 50-step engineering examples
+- Exploring step count, guidance, negative prompting, resolution, schedulers,
+  and small batches through the bundled local runner
 - Comparing this early calibration checkpoint with its pinned starting student
 - Non-consequential creative experimentation subject to the model license
 
@@ -257,6 +330,12 @@ gallery run, but it is not a complete safety system and can miss harmful output
 or over-filter benign output. Applications should add appropriate prompt and
 output controls, human review, and policy enforcement.
 
+The bundled runner keeps that checker enabled and does not expose a bypass
+flag. A flagged result may be returned as a black placeholder; its sidecar sets
+`nsfw_content_detected` for the corresponding image so the condition is not
+silent. Developers integrating the raw Diffusers pipeline are responsible for
+providing an appropriate moderation system for their application.
+
 Do not use this preview for consequential decisions, identity claims, medical
 or legal conclusions, harassment, exploitation, illegal activity, or any use
 prohibited by CreativeML OpenRAIL-M. Review outputs before sharing them.

checksums.json

@@ -4,16 +4,16 @@
   "LICENSE-CODE": "e26a0375b714267325c27905ba947fdc41ebc0b7a36940a49ae12379ed6208d6",
   "LICENSE-MODEL-CREATIVEML-OPENRAIL-M.txt": "be351ebe7ac01bcdbb018639aadcfd38f136b7dc3f2a3d4d3a24db51d1b210ef",
   "MODEL_DATA_LICENSES.md": "8f6b712826f9904561fb32038635612722be61cfd776da58fb61a4848a03148e",
-  "README.md": "0200ca5dddc849ea3ce88861990f91254e04957f50f2ac96b6802e9efbc2698a",
+  "README.md": "020e0c921afca2a8cd4378e20032dc80c9974fc39351f74e1b5762ff28bbd07f",
   "assets/clover-image-tiny-local-mps-library-seed-1469.png": "f8830346f2a9c2b9a8c2a01d8f90e6925c93d667c1bcf998aa904a150589a742",
   "assets/clover-image-tiny-paired-contact-sheet.png": "8653d1105b7b0c56e2385a127336dbe9b3a1a03c8518edb4934353a9d8e13bfa",
   "evidence/clover-image-tiny-local-mps-library-seed-1469.json": "1ddd86de0be992987214266720e0f341f25791402aae637065d6d09a6ea67b27",
   "evidence/stage-b-inference-checksums.json": "d9a28d5fe6f5b675ee1b9db52e6d0493c8d3d357bb824eac590911acbd5c3ebc",
-  "examples/generate.py": "bba645e9a5ac0959da22e1ef61fd1ab24a2974221e77a95c6fdb4c4c03715840",
+  "examples/generate.py": "fcea598655f7e144bc1ccce9be6d4e9e166915a3ad3c26fc0aa6c8ade00b49f1",
   "feature_extractor/preprocessor_config.json": "205d45875859846dc1ca211b9a19f5db72f47e953b396954ee34d48d8e95c3c6",
   "model_index.json": "792073e269e5caff40b3f8c553387540c17a5d900ed0e9cbfab309d650e708dd",
   "requirements.txt": "9dbb74869a34e3b610f737bce8a9d2a20691fd0fa416cf6bb42354b78e0a3861",
-  "research_preview.json": "335222a4369df359b01bb403eae165831cf3269a14b7b1c3a458c3bd1b9c4f38",
+  "research_preview.json": "e9906a1cbac490e08c8a72cc4669cacffb4fab0b1a944334a6bd74424d13416c",
   "safety_checker/config.json": "241bd8fb1ba6feff0d7421f7af0f85743711c5d76353626f71f7e2cc8009ac7c",
   "safety_checker/model.safetensors": "57ecdfa243b170f9b4cb3eefaf0f64552ef78fc0bf0eb1c5b9675308447184f6",
   "scheduler/scheduler_config.json": "184bc33ed887951dd86e37f20c878710c4e18e1c5fd4461256a3825679b53d15",

examples/generate.py

@@ -1,14 +1,44 @@
 #!/usr/bin/env python3
-"""Generate one conventional 50-step Clover Image Tiny preview image."""
+"""Generate configurable conventional Clover Image Tiny preview images."""
 
 from __future__ import annotations
 
 import argparse
+import hashlib
+import io
 import json
+import math
 from pathlib import Path
+from typing import Any
 
 import torch
-from diffusers import DiffusionPipeline, PNDMScheduler
+from diffusers import (
+    DDIMScheduler,
+    DiffusionPipeline,
+    DPMSolverMultistepScheduler,
+    EulerAncestralDiscreteScheduler,
+    EulerDiscreteScheduler,
+    PNDMScheduler,
+)
+
+DEFAULT_STEPS = 50
+DEFAULT_GUIDANCE_SCALE = 7.5
+DEFAULT_RESOLUTION = 512
+MIN_STEPS = 4
+MAX_STEPS = 100
+MIN_RESOLUTION = 256
+MAX_RESOLUTION = 768
+RESOLUTION_MULTIPLE = 64
+MAX_IMAGES = 4
+MAX_TEXT_LENGTH = 2_000
+MAX_SEED = 2**63 - 1
+SCHEDULERS: dict[str, type[Any]] = {
+    "pndm": PNDMScheduler,
+    "ddim": DDIMScheduler,
+    "euler": EulerDiscreteScheduler,
+    "euler-a": EulerAncestralDiscreteScheduler,
+    "dpmpp-2m": DPMSolverMultistepScheduler,
+}
 
 
 def _runtime(requested: str) -> tuple[torch.device, torch.dtype]:
@@ -31,62 +61,206 @@ def _runtime(requested: str) -> tuple[torch.device, torch.dtype]:
 
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        description="Run Clover Image Tiny with its fixed conventional preview settings."
+        description=(
+            "Run Clover Image Tiny with configurable conventional Diffusers settings. "
+            "The defaults reproduce the validated 50-step preview recipe."
+        )
     )
     parser.add_argument("--model", required=True, help="Hub repository ID or local directory")
     parser.add_argument("--prompt", required=True)
+    parser.add_argument("--negative-prompt", default="")
     parser.add_argument("--seed", type=int, default=1337)
+    parser.add_argument(
+        "--steps",
+        type=int,
+        default=DEFAULT_STEPS,
+        help=f"requested inference steps ({MIN_STEPS}..{MAX_STEPS})",
+    )
+    parser.add_argument(
+        "--guidance-scale",
+        type=float,
+        default=DEFAULT_GUIDANCE_SCALE,
+        help="classifier-free guidance scale (0.0..20.0)",
+    )
+    parser.add_argument(
+        "--width",
+        type=int,
+        default=DEFAULT_RESOLUTION,
+        help=(
+            f"output width ({MIN_RESOLUTION}..{MAX_RESOLUTION}, multiple of {RESOLUTION_MULTIPLE})"
+        ),
+    )
+    parser.add_argument(
+        "--height",
+        type=int,
+        default=DEFAULT_RESOLUTION,
+        help=(
+            f"output height ({MIN_RESOLUTION}..{MAX_RESOLUTION}, multiple of {RESOLUTION_MULTIPLE})"
+        ),
+    )
+    parser.add_argument(
+        "--scheduler",
+        choices=tuple(SCHEDULERS),
+        default="pndm",
+    )
+    parser.add_argument(
+        "--num-images",
+        type=int,
+        default=1,
+        help=f"number of images (1..{MAX_IMAGES}); seeds increment from --seed",
+    )
     parser.add_argument("--output", type=Path, default=Path("clover-image-tiny.png"))
     parser.add_argument("--device", choices=("auto", "cuda", "mps", "cpu"), default="auto")
     parser.add_argument("--local-files-only", action="store_true")
     return parser
 
 
+def _validate_args(args: argparse.Namespace) -> None:
+    if not isinstance(args.prompt, str) or not args.prompt.strip():
+        raise ValueError("--prompt must not be empty")
+    if len(args.prompt) > MAX_TEXT_LENGTH:
+        raise ValueError(f"--prompt must contain at most {MAX_TEXT_LENGTH} characters")
+    if len(args.negative_prompt) > MAX_TEXT_LENGTH:
+        raise ValueError(f"--negative-prompt must contain at most {MAX_TEXT_LENGTH} characters")
+    if not MIN_STEPS <= args.steps <= MAX_STEPS:
+        raise ValueError(f"--steps must be between {MIN_STEPS} and {MAX_STEPS}")
+    if not math.isfinite(args.guidance_scale) or not 0.0 <= args.guidance_scale <= 20.0:
+        raise ValueError("--guidance-scale must be finite and between 0.0 and 20.0")
+    for name in ("width", "height"):
+        value = int(getattr(args, name))
+        if not MIN_RESOLUTION <= value <= MAX_RESOLUTION or value % RESOLUTION_MULTIPLE != 0:
+            raise ValueError(
+                f"--{name} must be between {MIN_RESOLUTION} and {MAX_RESOLUTION} "
+                f"and divisible by {RESOLUTION_MULTIPLE}"
+            )
+    if not 1 <= args.num_images <= MAX_IMAGES:
+        raise ValueError(f"--num-images must be between 1 and {MAX_IMAGES}")
+    if not 0 <= args.seed <= MAX_SEED or args.seed + args.num_images - 1 > MAX_SEED:
+        raise ValueError("--seed and all incremented image seeds must be in [0, 2**63)")
+    if args.output.suffix.lower() != ".png":
+        raise ValueError("--output must use a .png filename")
+
+
+def _output_paths(output: Path, count: int) -> tuple[list[Path], Path]:
+    images = [output]
+    images.extend(
+        output.with_name(f"{output.stem}-{index:02d}{output.suffix}")
+        for index in range(2, count + 1)
+    )
+    return images, output.with_suffix(output.suffix + ".json")
+
+
+def _write_new(path: Path, payload: bytes) -> None:
+    with path.open("xb") as handle:
+        handle.write(payload)
+
+
 def main() -> int:
-    args = _parser().parse_args()
+    parser = _parser()
+    args = parser.parse_args()
+    try:
+        _validate_args(args)
+    except ValueError as exc:
+        parser.error(str(exc))
     device, dtype = _runtime(args.device)
+    output_paths, metadata_path = _output_paths(args.output, args.num_images)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    for path in (*output_paths, metadata_path):
+        if path.exists() or path.is_symlink():
+            raise FileExistsError(f"planned output already exists: {path}")
     pipe = DiffusionPipeline.from_pretrained(
         args.model,
         torch_dtype=dtype,
         local_files_only=args.local_files_only,
     )
-    pipe.scheduler = PNDMScheduler.from_config(pipe.scheduler.config)
+    scheduler_type = SCHEDULERS[args.scheduler]
+    pipe.scheduler = scheduler_type.from_config(pipe.scheduler.config)
     pipe = pipe.to(device)
     generator_device = "cuda" if device.type == "cuda" else "cpu"
-    generator = torch.Generator(device=generator_device).manual_seed(args.seed)
+    seeds = [args.seed + index for index in range(args.num_images)]
+    generators = [torch.Generator(device=generator_device).manual_seed(seed) for seed in seeds]
+    generator: torch.Generator | list[torch.Generator]
+    generator = generators[0] if len(generators) == 1 else generators
     with torch.inference_mode():
         result = pipe(
-            prompt=args.prompt,
-            negative_prompt="",
-            num_inference_steps=50,
-            guidance_scale=7.5,
-            height=512,
-            width=512,
+            prompt=args.prompt.strip(),
+            negative_prompt=args.negative_prompt,
+            num_inference_steps=args.steps,
+            guidance_scale=args.guidance_scale,
+            height=args.height,
+            width=args.width,
+            num_images_per_prompt=args.num_images,
             generator=generator,
         )
-    if not result.images:
-        raise RuntimeError("the pipeline returned no images")
-    args.output.parent.mkdir(parents=True, exist_ok=True)
-    result.images[0].save(args.output)
+    if not isinstance(result.images, list) or len(result.images) != args.num_images:
+        raise RuntimeError("the pipeline returned an unexpected number of images")
+    safety = getattr(result, "nsfw_content_detected", None)
+    if not isinstance(safety, list) or len(safety) != args.num_images:
+        raise RuntimeError("the pipeline returned an unexpected safety-check result")
+    image_records: list[dict[str, Any]] = []
+    image_payloads: list[bytes] = []
+    for image, output_path, seed, nsfw in zip(
+        result.images,
+        output_paths,
+        seeds,
+        safety,
+        strict=True,
+    ):
+        buffer = io.BytesIO()
+        image.save(buffer, format="PNG")
+        payload = buffer.getvalue()
+        image_payloads.append(payload)
+        image_records.append(
+            {
+                "filename": output_path.name,
+                "seed": seed,
+                "sha256": hashlib.sha256(payload).hexdigest(),
+                "nsfw_content_detected": nsfw,
+            }
+        )
+    validated_gallery_recipe = (
+        args.scheduler == "pndm"
+        and args.steps == DEFAULT_STEPS
+        and args.guidance_scale == DEFAULT_GUIDANCE_SCALE
+        and args.negative_prompt == ""
+        and args.width == DEFAULT_RESOLUTION
+        and args.height == DEFAULT_RESOLUTION
+        and args.num_images == 1
+    )
     metadata = {
         "model": args.model,
-        "prompt": args.prompt,
-        "negative_prompt": "",
+        "prompt": args.prompt.strip(),
+        "negative_prompt": args.negative_prompt,
         "seed": args.seed,
         "scheduler": type(pipe.scheduler).__name__,
-        "num_inference_steps": 50,
-        "guidance_scale": 7.5,
-        "height": 512,
-        "width": 512,
+        "scheduler_key": args.scheduler,
+        "num_inference_steps": args.steps,
+        "guidance_scale": args.guidance_scale,
+        "height": args.height,
+        "width": args.width,
+        "num_images": args.num_images,
+        "images": image_records,
         "device": device.type,
         "dtype": str(dtype).removeprefix("torch."),
-        "nsfw_content_detected": getattr(result, "nsfw_content_detected", None),
+        "nsfw_content_detected": safety,
+        "validated_gallery_recipe": validated_gallery_recipe,
+        "leaf_steps": None,
         "cross_device_pixel_identity_claimed": False,
         "usage_label": "RESEARCH PREVIEW - PRODUCTION PILOT - NOT RELEASE-READY",
     }
-    metadata_path = args.output.with_suffix(args.output.suffix + ".json")
-    metadata_path.write_text(json.dumps(metadata, indent=2) + "\n", encoding="utf-8")
-    print(json.dumps({"output": str(args.output), "metadata": str(metadata_path), **metadata}))
+    for output_path, payload in zip(output_paths, image_payloads, strict=True):
+        _write_new(output_path, payload)
+    _write_new(metadata_path, (json.dumps(metadata, indent=2) + "\n").encode("utf-8"))
+    print(
+        json.dumps(
+            {
+                "output": str(output_paths[0]),
+                "outputs": [str(path) for path in output_paths],
+                "metadata": str(metadata_path),
+                **metadata,
+            }
+        )
+    )
     return 0
 
 

research_preview.json

@@ -1,6 +1,6 @@
 {
   "build": {
-    "repository_commit": "e6079eec2b91c5d026bfb461fd6c844a98b888ec",
+    "repository_commit": "647bac81f3713a0238eb21abf1844a8cd8d48f11",
     "sources": {
       "LICENSE-CODE": {
         "sha256": "e26a0375b714267325c27905ba947fdc41ebc0b7a36940a49ae12379ed6208d6",
@@ -27,11 +27,11 @@
         "tracked_at_commit": true
       },
       "hf/stage_b_preview/README.template.md": {
-        "sha256": "345bf548f79f97dfa2eebc57911f9073416ce558ad5b7e51425cdfe6841e2109",
+        "sha256": "1a38562b255d984609eb38764a5c0f46fdcaaede9abd6c3dc37fa07234529938",
         "tracked_at_commit": true
       },
       "hf/stage_b_preview/examples/generate.py": {
-        "sha256": "bba645e9a5ac0959da22e1ef61fd1ab24a2974221e77a95c6fdb4c4c03715840",
+        "sha256": "fcea598655f7e144bc1ccce9be6d4e9e166915a3ad3c26fc0aa6c8ade00b49f1",
         "tracked_at_commit": true
       },
       "hf/stage_b_preview/requirements.txt": {
@@ -116,7 +116,7 @@
     "human_review": "not_measured",
     "quality_evaluation": "not_measured"
   },
-  "metadata_sha256": "5e6874ce0dd7a762fe0ef043fed3311299e2f191f48e20f4c022a584d803cfe3",
+  "metadata_sha256": "3c4ef00fbdff6bf23dc24feadd71965b520920bef4e61f9cf2f3632c756334c0",
   "release_ready": false,
   "runtime_contract": {
     "denoiser_calls": 51,