Spaces:
Sleeping
Sleeping
| title: Piclets Discovery Server | |
| emoji: 🔮 | |
| colorFrom: purple | |
| colorTo: indigo | |
| sdk: gradio | |
| sdk_version: 5.49.0 | |
| app_file: app.py | |
| pinned: false | |
| short_description: Backend for the Piclets monster-discovery game | |
| # 🔮 Piclets Discovery Server | |
| The backend for **Piclets**, a photo-to-monster discovery game. Photograph a real | |
| object, and this server turns it into a collectible creature and saves it to a | |
| shared, public database — so the first person to scan a given object *discovers* | |
| its canonical monster, and everyone else who scans it finds the same one. | |
| This Space does **only two things**: | |
| 1. **Orchestrates the AI pipeline** for a scan, forwarding the *player's* Hugging | |
| Face token to three ZeroGPU Spaces so the GPU time is billed to the player, not | |
| to this server: | |
| ``` | |
| photo ──▶ identify object (VLM) ──▶ design monster as JSON (LLM) ──▶ art (T2I) | |
| ``` | |
| 2. **Writes new monsters** to a public HF Dataset in a single commit, and keeps the | |
| small aggregate index files (dex / feed / leaderboard / stats) in sync. | |
| Everything the frontend *reads* — the dex, the feed, the leaderboard, a player's | |
| collection — is fetched **directly from the dataset CDN**, never through this | |
| server. That asymmetry is the whole design; see **[ARCHITECTURE.md](ARCHITECTURE.md)**. | |
| > **Note on `hf_oauth`:** this server does **not** set `hf_oauth`. The *frontend* | |
| > Space runs "Sign in with Hugging Face" and forwards the resulting access token | |
| > here as a parameter; this server just verifies it against the HF userinfo | |
| > endpoint. OAuth config belongs on the frontend, not here. | |
| ## Setup | |
| 1. **Create the dataset** (the shared database). Run once, locally, with a token | |
| that has write access: | |
| ```bash | |
| HF_TOKEN=hf_xxx DATASET_REPO=<you>/piclets python init_dataset.py | |
| ``` | |
| 2. **Create this Space** (Gradio SDK, free CPU basic) and push these files. | |
| 3. **Add secrets** in *Space Settings → Variables and secrets*: | |
| | Name | Type | Purpose | | |
| | -------------- | ------ | -------------------------------------------------- | | |
| | `HF_TOKEN` | secret | **This server's** write token for the dataset. | | |
| | `DATASET_REPO` | var | The dataset id, e.g. `you/piclets`. | | |
| | `ADMIN_TOKEN` | secret | *(optional)* guards the `/admin_*` endpoints. | | |
| Optional tuning vars: `CAPTION_SPACE`, `CONCEPT_SPACE`, `IMAGE_SPACE`, | |
| `MAX_IMAGE_BYTES`, `OUTPUT_IMAGE_MAX`, `SCAN_MAX_IN_WINDOW`, `SCAN_WINDOW_S`, | |
| `CONCURRENCY`. | |
| 4. **Verify** the AI Space signatures before trusting a scan (they change over | |
| time). See [ARCHITECTURE.md → *Swapping the AI Spaces*](ARCHITECTURE.md). Quick | |
| check: | |
| ```python | |
| from gradio_client import Client | |
| Client("multimodalart/Qwen-Image-Fast").view_api() | |
| ``` | |
| ## API | |
| One write endpoint (the UI on this page is just for manual testing): | |
| - **`/scan`** — inputs `image` (file) and `hf_token` (the player's OAuth access | |
| token). Returns: | |
| ```json | |
| {"success": true, "status": "new", "descriptor": "...", "monster": { ... }, | |
| "message": "You discovered ...!"} | |
| ``` | |
| `status` is `"new"` (a monster was created and committed) or `"existing"` (the | |
| object was already discovered — returned read-only, no commit, minimal GPU). | |
| - **`/admin_delete`**, **`/admin_rebuild`** — moderation tools, gated by `ADMIN_TOKEN`. | |
| Read paths for the frontend (direct from the CDN): | |
| ``` | |
| https://huggingface.co/datasets/<DATASET_REPO>/resolve/main/index/monsters.json | |
| https://huggingface.co/datasets/<DATASET_REPO>/resolve/main/index/feed.json | |
| https://huggingface.co/datasets/<DATASET_REPO>/resolve/main/index/leaderboard.json | |
| https://huggingface.co/datasets/<DATASET_REPO>/resolve/main/index/stats.json | |
| https://huggingface.co/datasets/<DATASET_REPO>/resolve/main/monsters/<key>.json | |
| https://huggingface.co/datasets/<DATASET_REPO>/resolve/main/images/<key>.webp | |
| ``` | |
| ## Limits worth knowing | |
| - **Per-player GPU quota** (ZeroGPU, daily): ~2 min anonymous, ~5 min free, ~40 min | |
| Pro. A scan is three GPU calls, so a free player gets on the order of a handful of | |
| *new* discoveries per day. Repeat scans of known objects are deduped before the | |
| expensive stages and cost almost nothing. | |
| - **Write ceiling:** every discovery commits under this server's single token, and | |
| HF rate-limits commits (the exact number is undocumented). `huggingface_hub` | |
| ≥ 1.2.0 auto-retries on 429. New-monster writes naturally slow as common objects | |
| get claimed. | |
| - **Free CPU Space** sleeps after 48h idle and wakes on the next visit (cold start | |
| up to ~a minute). It's a single replica — which is why one in-process lock is | |
| enough to serialize all writes. | |
| Full reasoning, the exact numbers, and how to stress-test them are in | |
| **[ARCHITECTURE.md](ARCHITECTURE.md)**. Development notes are in **[CLAUDE.md](CLAUDE.md)**. | |