`README.md`

68 lines
# CelebritySignatures

A research dataset of **authentic celebrity signatures** with full source provenance
and legal-risk scoring. Hard rule: **never invent a signature** — every row traces to
a real, fetchable image file with a known license.

See **[SOURCES.md](./SOURCES.md)** for the full source strategy and legal-risk model.

## Categories (target 100 each)
Sports · Politics · Movies · TV · Hollywood (classic/iconic)
**+ a dedicated Declaration of Independence set** (56 signers — the safest possible
bucket: all deceased since the founding era, all public domain).

## How "do not invent" is enforced
Spine = **Wikidata property `P109` ("signature")**, which links a real person to a
real signature **file on Wikimedia Commons**. We never ask an LLM to "find a URL."
We query for people who *already have* a verified signature file, then pull each
file's license from the Commons API and HTTP-verify the image resolves.

## Scripts
| Script | What it does | Endpoint | Status |
|---|---|---|---|
| `scripts/fetch-declaration.mjs` | All 56 Declaration of Independence signers | MediaWiki / Commons / Wikidata-entity | ✅ works anytime |
| `scripts/fetch-wikidata.mjs [cat\|all]` | The 5 celebrity categories, ranked by notability | Wikidata SPARQL (WDQS) | ⏳ runs when WDQS is up (has 1-req/min outage backoff) |
| `scripts/build-collages.py` | Two murals per category (see below) | Wikimedia thumbnailer + `qrcode` | ✅ run via `.venv` |

```bash
node scripts/fetch-declaration.mjs          # → data/declaration.json (56 rows)
node scripts/fetch-wikidata.mjs all         # → data/celebrity_signatures.{json,csv}

# Murals (needs the venv — qrcode[pil] is installed there, not globally):
python3 -m venv .venv && .venv/bin/pip install "qrcode[pil]" Pillow
.venv/bin/python scripts/build-collages.py  # → output/collage-<cat>.png + -named.png
```

### Murals (`output/`)
Each category renders **two** PNGs:
- `collage-<cat>.png` — the displayed mural. **No names** under the signatures, with
  a **QR code in the centre** ("SCAN TO REVEAL NAMES"). This is what the viewer shows.
- `collage-<cat>-named.png` — the labelled "key", same grid with every full name. The
  centre QR links here.

The QR encodes `${PUBLIC_BASE_URL}/output/collage-<cat>-named.png` (default
`PUBLIC_BASE_URL=http://<LAN-IP>:9920`), so a phone on the same wifi opens the named
version while the local viewer (`node server.js`) is running. Set `PUBLIC_BASE_URL`
to a public origin if this ever deploys.

## Schema (per row)
`category, rank, full_name, wikidata, reason_for_ranking, ranking_source_urls,
signature_image_url, signature_source_type, image_license, image_author, deceased,
death_date, risk_level, usable_in_commercial_collage, notes, backup_source`

## Risk model (encoded per row)
- `risk_level`: low / medium / high — `max(license_risk, publicity_risk)`
- `usable_in_commercial_collage`: **yes** (deceased + PD/CC) · **permission-needed**
  (living person → right-of-publicity exposure) · **review**
- Build order: **Politics + historical/deceased first**, then Sports/Movies/TV only
  where Commons/official-archive licensing is explicit. Living celebrities are
  auto-flagged `permission-needed`.

## Collage rules ("keep us out of trouble")
- No single signature rendered larger or more prominent than another (uniform sizing).
- Only `usable_in_commercial_collage == yes` rows go into any commercial composite.
- `permission-needed` rows are research/reference only until rights are cleared.

## Cost
$0 — Wikidata, Wikimedia Commons, and MediaWiki APIs are all free/public.