Add model card

README.md

@@ -0,0 +1,76 @@
+---
+license: apache-2.0
+pipeline_tag: image-generation
+language: []
+tags:
+  - gan
+  - dcgan
+  - image-generation
+  - logos
+  - from-scratch
+  - toy
+library_name: torch
+metrics:
+  - discriminator-loss
+  - generator-loss
+---
+
+# logo-gan — a tiny DCGAN that learns to draw company logos
+
+A small **Deep Convolutional GAN** trained **from scratch** to generate
+64×64 RGB company logos. Built for a request in
+[Compactbot/model-requests#1](https://huggingface.co/spaces/Compactbot/model-requests/discussions/1).
+
+This is a **toy / experiment**, not a production image model. It is published
+mainly as a small, honest, reproducible build.
+
+## What it is
+
+- **Architecture:** standard DCGAN.
+  - Generator: `Linear(100 → 512·8·8)` + 3× up-conv (512→256→128→64) + final 3×3 conv, BatchNorm, ReLU, Tanh out.
+  - Discriminator: 4× down-conv (64→128→256→512→1) + LeakyReLU(0.2).
+- **Parameters:** **8,832,708** (generator 6,066,179 + discriminator 2,766,529).
+  The `model.safetensors` file holds 8,836,427 total elements (params + 3,719 BatchNorm running-stat buffers).
+- **Latent:** 100-dim Gaussian.
+- **Stability tricks:** label smoothing (real=0.9, fake=0.1) + R1 gradient penalty (λ=10) on the discriminator. A vanilla run without these **mode-collapsed** (d→0.0000, g→13.9) and was discarded; this is the stable variant.
+
+## Training
+
+- **Data:** 400 real company logos, resized to 64×64, from four public Hub datasets
+  (100 each): `samp3209/logo-dataset` (bliptest), `taniya/Logo_mark`,
+  `taniya/Logo_symbol`, `taniya/Logo_type`.
+- **Hardware:** NVIDIA RTX 5090 (32 GB), ~5 min for 12,000 steps.
+- **Optim:** Adam, generator LR 2e-4, discriminator LR 4e-5, betas (0.5, 0.999), batch 128.
+- **Schedule:** 12,000 steps, checkpoint + sample grid every 2,000 steps.
+- **Loss curve:** d settled to ~0.73–0.80, g rose to ~1.9–2.4 over training. No collapse.
+
+## Honest caveats (read this)
+
+- **I cannot visually verify the samples.** The training environment produces
+  PNG grids, but I have no way to look at them. The evidence that this is a
+  working (non-collapsed) GAN is **quantitative only**:
+  - discriminator and generator losses held in a healthy band throughout (no collapse to a single mode);
+  - sample **color entropy** 4.91 bits / 2,979 unique colors (real data: 4.23 bits / 2,805) — comparable diversity, not a single repeated tile;
+  - per-channel std ≈ 0.29–0.31 (real: 0.32) — full-color, not grayscale.
+- That is **not** the same as "these look like logos." With 400 logos and 8.8M
+  params the model can learn the *statistics* of logos (bright background, a
+  central colored mark, some letterforms) but it will not faithfully reproduce
+  any specific real logo. Treat `samples_final.png` as "what the model thinks a
+  logo looks like," not as generated brand assets.
+
+## Files
+
+- `model.safetensors` — generator + discriminator weights (final checkpoint, 55 tensors).
+- `samples_final.png` — 64 fixed-latent sample grid from the final generator.
+- `train_gan_v2.py` — the exact training script (self-contained, PyTorch).
+- `manifest.json` — the 400 source logos (dataset + filename) the model trained on.
+
+## Reproduce
+
+```bash
+# needs: torch, numpy, pillow
+# put logos64.npy (N,3,64,64) float32 in [0,1] at ./logos/logos64.npy
+python3 train_gan_v2.py --steps 12000 --batch 128 --seed 7
+```
+
+Set seed 7 to reproduce the exact weights in `model.safetensors`.