README.md

---
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](API_DOCUMENTATION.md) - Complete API reference with examples
- [CLAUDE.md](CLAUDE.md) - Technical implementation details

## Quick Start

### Local Development
```bash
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**:
```bash
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
```javascript
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
```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](https://huggingface.co/docs/hub/spaces-config-reference).