README.md

metadata

title: Piclets Discovery Server
emoji: 🔍
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.38.2
app_file: app.py
pinned: false
short_description: Discover unique Piclets for every real-world object!

🔍 Piclets Discovery Server

A Hugging Face Space that serves as the backend for Piclets - a discovery game where each real-world object has ONE unique canonical creature!

Key Features

• Canonical System: Each real-world object has exactly one official Piclet
• Variation Tracking: Discover unique variations based on object attributes
• Discovery Database: Public HuggingFace dataset stores all discoveries
• Leaderboard System: Track top discoverers by rarity score
• Rarity Tiers: From Common to Legendary based on scan counts

Game Flow

1. Scan: Players photograph real-world objects
2. Identify: AI captions extract the object name and attributes
3. Discover: First scanner creates the canonical Piclet
4. Variations: Find unique versions based on visual attributes
5. Track: All discoveries stored in public HuggingFace dataset

Documentation

• API_DOCUMENTATION.md - Complete API reference with examples
• CLAUDE.md - Technical implementation details

Quick Start

Local Development

pip install -r requirements.txt
python app.py
# Server runs at http://localhost:7860

Deploy to Hugging Face Spaces

1. Create the Space:

   • Go to https://huggingface.co/new-space
   • Choose Gradio SDK
   • Set to public

2. Set up secrets:

   • Go to Space Settings → Repository secrets
   • Add HF_TOKEN with write permissions to Fraser/piclets dataset
   • Add ADMIN_PASSWORD with a secure password (protects web UI)

3. Push the code:

git add -A && git commit -m "Initial deployment" && git push

Data Storage

All discoveries are stored in the public dataset: Fraser/piclets

piclets/
  pillow.json         # Canonical Piclet + all variations
  chair.json          # Each file contains one object type
  lamp.json
  ...

users/
  player123.json      # User profile with discoveries
  explorer456.json    # Tracks unique finds and scores
  ...

metadata/
  stats.json          # Global game statistics
  leaderboard.json    # Top discoverers by rarity score

Authentication

Web UI Access: Protected by username/password authentication

• Username: admin
• Password: Set via ADMIN_PASSWORD environment variable
• Prevents casual users from manually creating piclets via the web interface

API Access: Programmatic access via Gradio Client works without authentication

• Your frontend app can call endpoints directly
• No authentication required for API clients
• OAuth tokens verified at the API level for user attribution

Frontend Integration

JavaScript/TypeScript

import { Client } from "@gradio/client";

const client = await Client.connect("Fraser/piclets-server");

// Search for existing Piclet
const result = await client.predict("/search_piclet", {
  object_name: "pillow",
  attributes: ["velvet", "blue"]
});

// Create new canonical Piclet
if (result.status === "new") {
  const created = await client.predict("/create_canonical", {
    object_name: "pillow",
    piclet_data: JSON.stringify(picletData),
    username: "discoverer123"
  });
}

Python

from gradio_client import Client

client = Client("Fraser/piclets-server")

# Search for a Piclet
result = client.predict(
    "pillow",           # object_name
    ["velvet", "blue"], # attributes
    api_name="/search_piclet"
)

Tech Stack

• Gradio: API framework and web interface
• HuggingFace Datasets: Persistent storage backend
• Python: Core server logic

License

Public domain - all discoveries are shared openly!

For more details, check out the Hugging Face Spaces documentation.