server

API_DOCUMENTATION.md

@@ -1,8 +1,8 @@
-# Piclets Server API Documentation
+# Piclets Discovery Server API Documentation
 
 ## Overview
 
-The Piclets Server provides a Gradio-based API for saving and sharing AI-generated creatures (Piclets) from the Piclets game. This backend supports the main game client with persistent storage and sharing capabilities.
+The Piclets Discovery Server provides a Gradio-based API for the Piclets discovery game. Each real-world object has ONE canonical Piclet, with variations tracked based on attributes. All data is stored in a public HuggingFace Dataset.
 
 ## Quick Start
 
@@ -16,325 +16,376 @@ python app.py
 - **Web Interface**: http://localhost:7860
 - **Programmatic Access**: Use Gradio Client to connect to the space
 
+### Frontend Integration
+```javascript
+import { Client } from "@gradio/client";
+
+const client = await Client.connect("Fraser/piclets-server");
+const result = await client.predict("/search_piclet", {
+  object_name: "pillow",
+  attributes: ["velvet"]
+});
+```
+
 ## API Endpoints
 
-### 1. Save Piclet
-**Endpoint**: `/save_piclet_api`
+### 1. Search Piclet
+**Endpoint**: `/search_piclet`
+**Purpose**: Search for canonical Piclet or variations
 **Method**: Gradio function call
-**Purpose**: Save a new Piclet with optional image
 
 **Input Parameters**:
-- `piclet_json` (string): JSON-formatted Piclet data
-- `image_file` (file, optional): Image file for the Piclet
+```json
+{
+  "object_name": "pillow",
+  "attributes": ["velvet", "blue"]
+}
+```
+
+**Response Types**:
 
-**Response Format**:
+**New Object** (no Piclet exists):
 ```json
 {
-  "success": true,
-  "piclet_id": "uuid-string",
-  "message": "Piclet saved successfully"
+  "status": "new",
+  "message": "No Piclet found for 'pillow'",
+  "piclet": null
 }
 ```
 
-**Error Response**:
+**Existing Canonical** (exact match):
 ```json
 {
-  "success": false,
-  "error": "Error description"
+  "status": "existing",
+  "message": "Found canonical Piclet for 'pillow'",
+  "piclet": {
+    "objectName": "pillow",
+    "typeId": "pillow_canonical",
+    "discoveredBy": "user123",
+    "discoveredAt": "2024-07-26T10:30:00",
+    "scanCount": 42,
+    "picletData": { /* full Piclet data */ }
+  }
+}
+```
+
+**Variation Found**:
+```json
+{
+  "status": "variation",
+  "message": "Found variation of 'pillow'",
+  "piclet": { /* variation data */ },
+  "canonicalId": "pillow_canonical"
 }
 ```
 
-### 2. Get Piclet
-**Endpoint**: `/get_piclet_api`
+**New Variation Suggested**:
+```json
+{
+  "status": "new_variation",
+  "message": "No variation found for 'pillow' with attributes ['velvet', 'blue']",
+  "canonicalId": "pillow_canonical",
+  "piclet": null
+}
+```
+
+### 2. Create Canonical
+**Endpoint**: `/create_canonical`
+**Purpose**: Register the first discovery of an object
 **Method**: Gradio function call
-**Purpose**: Retrieve a Piclet by ID
 
 **Input Parameters**:
-- `piclet_id` (string): Unique Piclet identifier
+```json
+{
+  "object_name": "pillow",
+  "piclet_data": "{ /* JSON string of Piclet instance */ }",
+  "username": "discoverer123"
+}
+```
 
-**Response Format**:
+**Success Response**:
 ```json
 {
   "success": true,
+  "message": "Created canonical Piclet for 'pillow'",
   "piclet": {
-    "id": "uuid-string",
-    "name": "Piclet Name",
-    "description": "Description",
-    "tier": "medium",
-    "primaryType": "space",
-    "baseStats": { ... },
-    "movepool": [ ... ],
-    "created_at": "2024-07-26T10:30:00"
+    "objectName": "pillow",
+    "typeId": "pillow_canonical",
+    "discoveredBy": "discoverer123",
+    "discoveredAt": "2024-07-26T10:30:00",
+    "scanCount": 1,
+    "picletData": { /* full Piclet data */ }
   }
 }
 ```
 
-### 3. List Piclets
-**Endpoint**: `/list_piclets_api`
+**Error Response**:
+```json
+{
+  "success": false,
+  "error": "Failed to save canonical Piclet"
+}
+```
+
+### 3. Create Variation
+**Endpoint**: `/create_variation`
+**Purpose**: Add a variation to an existing canonical Piclet
 **Method**: Gradio function call
-**Purpose**: Get a list of all saved Piclets
 
 **Input Parameters**:
-- `limit` (integer): Maximum number of results (1-100, default: 50)
+```json
+{
+  "canonical_id": "pillow_canonical",
+  "attributes": ["velvet", "blue"],
+  "piclet_data": "{ /* JSON string of variation data */ }",
+  "username": "player456",
+  "object_name": "pillow"
+}
+```
 
-**Response Format**:
+**Success Response**:
 ```json
 {
   "success": true,
-  "piclets": [
-    {
-      "id": "uuid-string",
-      "name": "Piclet Name",
-      "primaryType": "space",
-      "tier": "medium",
-      "created_at": "2024-07-26T10:30:00",
-      "has_image": true
-    }
-  ],
-  "count": 1
+  "message": "Created variation of 'pillow'",
+  "piclet": {
+    "typeId": "pillow_001",
+    "attributes": ["velvet", "blue"],
+    "discoveredBy": "player456",
+    "discoveredAt": "2024-07-26T11:00:00",
+    "scanCount": 1,
+    "picletData": { /* variation data */ }
+  }
 }
 ```
 
-### 4. Get Piclet Image
-**Endpoint**: `/get_piclet_image_api`
+### 4. Increment Scan Count
+**Endpoint**: `/increment_scan_count`
+**Purpose**: Track how many times a Piclet has been discovered
 **Method**: Gradio function call
-**Purpose**: Retrieve the image associated with a Piclet
 
 **Input Parameters**:
-- `piclet_id` (string): Unique Piclet identifier
+```json
+{
+  "piclet_id": "pillow_canonical",
+  "object_name": "pillow"
+}
+```
 
-**Response**: Image file or None if not found
+**Success Response**:
+```json
+{
+  "success": true,
+  "scanCount": 43
+}
+```
 
-## Required JSON Format for Piclets
+### 5. Get Recent Activity
+**Endpoint**: `/get_recent_activity`
+**Purpose**: Get global discovery feed
+**Method**: Gradio function call
 
-When saving a Piclet, the JSON must include these required fields:
+**Input Parameters**:
+```json
+{
+  "limit": 20
+}
+```
 
+**Response**:
 ```json
 {
-  "name": "Stellar Wolf",
-  "description": "A majestic wolf creature infused with cosmic energy",
-  "tier": "medium",
-  "primaryType": "space",
-  "secondaryType": "beast",
-  "baseStats": {
-    "hp": 85,
-    "attack": 90,
-    "defense": 70,
-    "speed": 80
-  },
-  "nature": "Bold",
-  "specialAbility": {
-    "name": "Cosmic Howl",
-    "description": "Increases attack when health is low"
-  },
-  "movepool": [
+  "success": true,
+  "activities": [
+    {
+      "type": "discovery",
+      "objectName": "pillow",
+      "typeId": "pillow_canonical",
+      "discoveredBy": "user123",
+      "discoveredAt": "2024-07-26T10:30:00",
+      "scanCount": 42
+    },
     {
-      "name": "Star Strike",
-      "type": "space",
-      "power": 75,
-      "accuracy": 90,
-      "pp": 15,
-      "priority": 0,
-      "flags": [],
-      "effects": [
-        {
-          "type": "damage",
-          "target": "opponent",
-          "amount": "normal"
-        }
-      ]
+      "type": "variation",
+      "objectName": "pillow",
+      "typeId": "pillow_001",
+      "attributes": ["velvet", "blue"],
+      "discoveredBy": "user456",
+      "discoveredAt": "2024-07-26T11:00:00",
+      "scanCount": 5
     }
   ]
 }
 ```
 
-### Field Specifications
-
-#### Required Fields
-- **name**: String - Piclet's name
-- **primaryType**: String - One of: beast, bug, aquatic, flora, mineral, space, machina, structure, culture, cuisine
-- **baseStats**: Object with hp, attack, defense, speed (integers)
-- **movepool**: Array of move objects (minimum 1 move)
+### 6. Get Leaderboard
+**Endpoint**: `/get_leaderboard`
+**Purpose**: Get top discoverers by rarity score
+**Method**: Gradio function call
 
-#### Optional Fields
-- **description**: String - Flavor text
-- **tier**: String - low, medium, high, legendary
-- **secondaryType**: String - Same options as primaryType or null
-- **nature**: String - Personality trait
-- **specialAbility**: Object with name and description
+**Input Parameters**:
+```json
+{
+  "limit": 10
+}
+```
 
-#### Move Object Format
+**Response**:
 ```json
 {
-  "name": "Move Name",
-  "type": "attack_type",
-  "power": 75,
-  "accuracy": 90,
-  "pp": 15,
-  "priority": 0,
-  "flags": ["contact", "bite"],
-  "effects": [
+  "success": true,
+  "leaderboard": [
+    {
+      "rank": 1,
+      "username": "explorer123",
+      "totalFinds": 156,
+      "uniqueFinds": 45,
+      "rarityScore": 2340
+    },
     {
-      "type": "damage",
-      "target": "opponent",
-      "amount": "normal"
+      "rank": 2,
+      "username": "hunter456",
+      "totalFinds": 134,
+      "uniqueFinds": 38,
+      "rarityScore": 1890
     }
   ]
 }
 ```
 
-## Frontend Integration
-
-### Using Gradio Client (JavaScript)
+### 7. Get User Profile
+**Endpoint**: `/get_user_profile`
+**Purpose**: Get individual user's discovery statistics
+**Method**: Gradio function call
 
-```javascript
-// Connect to the Piclets server
-const client = await window.gradioClient.Client.connect("your-hf-space-name");
-
-// Save a Piclet
-async function savePiclet(picletData, imageFile = null) {
-  const result = await client.predict("/save_piclet_api", [
-    JSON.stringify(picletData),
-    imageFile
-  ]);
-  return JSON.parse(result.data[0]);
+**Input Parameters**:
+```json
+{
+  "username": "player123"
 }
+```
 
-// Get a Piclet
-async function getPiclet(picletId) {
-  const result = await client.predict("/get_piclet_api", [picletId]);
-  return JSON.parse(result.data[0]);
+**Response**:
+```json
+{
+  "success": true,
+  "profile": {
+    "username": "player123",
+    "joinedAt": "2024-07-01T10:00:00",
+    "discoveries": ["pillow_canonical", "chair_002", "lamp_canonical"],
+    "uniqueFinds": 2,
+    "totalFinds": 3,
+    "rarityScore": 250
+  }
 }
+```
 
-// List Piclets
-async function listPiclets(limit = 20) {
-  const result = await client.predict("/list_piclets_api", [limit]);
-  return JSON.parse(result.data[0]);
-}
+## Object Normalization Rules
 
-// Get Piclet Image
-async function getPicletImage(picletId) {
-  const result = await client.predict("/get_piclet_image_api", [picletId]);
-  return result.data[0]; // Returns image path or null
-}
-```
+The server normalizes object names for consistent storage:
 
-### Example Usage
+1. Convert to lowercase
+2. Remove articles (the, a, an)
+3. Handle pluralization:
+   - `pillows` → `pillow`
+   - `berries` → `berry`
+   - `leaves` → `leaf`
+   - `boxes` → `box`
+4. Replace spaces with underscores
+5. Remove special characters
 
-```javascript
-// Example Piclet data
-const picletData = {
-  name: "Thunder Drake",
-  primaryType: "space",
-  baseStats: { hp: 90, attack: 85, defense: 75, speed: 95 },
-  movepool: [
-    {
-      name: "Lightning Bolt",
-      type: "space",
-      power: 80,
-      accuracy: 95,
-      pp: 15,
-      priority: 0,
-      flags: [],
-      effects: [{ type: "damage", target: "opponent", amount: "normal" }]
-    }
-  ]
-};
-
-// Save the Piclet
-const saveResult = await savePiclet(picletData);
-if (saveResult.success) {
-  console.log(`Piclet saved with ID: ${saveResult.piclet_id}`);
-  
-  // Retrieve it back
-  const retrievedPiclet = await getPiclet(saveResult.piclet_id);
-  console.log(retrievedPiclet);
-}
-```
+Examples:
+- `"The Blue Pillow"` → `pillow`
+- `"wooden chairs"` → `wooden_chair`
+- `"A pair of glasses"` → `pair_of_glass`
 
-## Storage Structure
+## Rarity Tiers
 
-The server uses a file-based storage system:
+Based on scan count:
+- **Legendary**: ≤ 5 scans
+- **Epic**: 6-20 scans
+- **Rare**: 21-50 scans
+- **Uncommon**: 51-100 scans
+- **Common**: > 100 scans
 
-```
-data/
-├── piclets/           # Individual Piclet JSON files
-│   ├── uuid1.json
-│   ├── uuid2.json
-│   └── ...
-├── images/            # Piclet images
-│   ├── uuid1.png
-│   ├── uuid2.jpg
-│   └── ...
-└── collections/       # Future: Shared collections
-    └── ...
-```
+## Scoring System
+
+- **Canonical Discovery**: +100 rarity points
+- **Variation Discovery**: +50 rarity points
+- **Scan Bonus**: Additional points based on rarity tier
 
 ## Error Handling
 
-All API endpoints return consistent error formats:
+All endpoints return consistent error structures:
 
 ```json
 {
   "success": false,
-  "error": "Descriptive error message"
+  "error": "Description of what went wrong"
 }
 ```
 
-### Common Errors
-- **Missing required field**: When JSON is missing name, primaryType, baseStats, or movepool
-- **Invalid JSON format**: When the input string is not valid JSON
-- **Piclet not found**: When requesting a non-existent Piclet ID
-- **File system errors**: Issues with saving/reading files
-
-## Deployment to Hugging Face Spaces
-
-1. **Push to Repository**: The space automatically deploys when you push to the connected git repository
-2. **Environment**: Python 3.9+ with Gradio 5.38.2
-3. **Persistent Storage**: Data persists between space restarts
-4. **Public Access**: The API is accessible to anyone with the space URL
-
-### Space Configuration (in README.md)
-```yaml
----
-title: Piclets Server
-emoji: 🦀
-colorFrom: yellow
-colorTo: pink
-sdk: gradio
-sdk_version: 5.38.2
-app_file: app.py
-pinned: false
----
-```
-
-## Future Enhancements
-
-### Planned Features
-- **Collections**: Save and share groups of Piclets
-- **User Authentication**: Personal Piclet collections
-- **Battle Statistics**: Track battle performance
-- **Online Multiplayer**: Real-time battle coordination
-- **Search and Filtering**: Find Piclets by type, tier, name
-- **Import/Export**: Bulk operations
-
-### API Extensions
-- `create_collection_api(name, piclet_ids)`
-- `get_collection_api(collection_id)`
-- `search_piclets_api(query, filters)`
-- `get_battle_stats_api(piclet_id)`
-
-## Security Considerations
-
-- **Input Validation**: All JSON inputs are validated
-- **File Size Limits**: Images are limited by Gradio defaults
-- **Rate Limiting**: Handled by Hugging Face Spaces infrastructure
-- **Content Filtering**: Future enhancement for inappropriate content
+Common error scenarios:
+- Piclet not found
+- Invalid JSON data
+- Failed to save to dataset
+- Network/connection errors
+
+## Rate Limiting
+
+Currently no rate limiting implemented. For production:
+- Consider adding per-user rate limits
+- Implement cooldowns for discoveries
+- Cache frequent requests
+
+## Authentication
+
+**Current**: Username-based (no passwords)
+- Users provide username in requests
+- All data is publicly visible
+- No sensitive information stored
+
+**Future Options**:
+- HuggingFace OAuth integration
+- API keys for verified users
+- Session-based authentication
+
+## Data Storage
+
+All data stored in HuggingFace Dataset:
+- Repository: `Fraser/piclets`
+- Type: Public dataset
+- Structure:
+  - `piclets/` - Canonical and variation data
+  - `users/` - User profiles
+  - `metadata/` - Global statistics
+
+## Best Practices
+
+1. **Always normalize object names** before searching
+2. **Check for existing Piclets** before creating new ones
+3. **Increment scan counts** when rediscovering
+4. **Cache responses** on the client side
+5. **Handle network errors** gracefully
+6. **Validate JSON data** before sending
+
+## Example Workflow
+
+1. User scans an object (e.g., pillow)
+2. Extract object name and attributes from caption
+3. Search for existing Piclet
+4. If new:
+   - Create canonical Piclet
+   - Award discovery bonus
+5. If variation:
+   - Create or retrieve variation
+   - Update scan count
+6. Update user profile
+7. Refresh activity feed
 
 ## Support
 
 For issues or questions:
-1. Check the error messages in API responses
-2. Verify JSON format matches the specification
-3. Ensure all required fields are present
-4. Test with the example data provided
+- Check CLAUDE.md for implementation details
+- Review example code in app.py
+- Open an issue in the repository

CLAUDE.md

@@ -0,0 +1,196 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Hugging Face Space that serves as a backend server for the Piclets Discovery game. It uses Gradio to provide API endpoints and HuggingFace Datasets for persistent storage.
+
+**Core Concept**: Each real-world object has ONE canonical Piclet! Players discover these by scanning objects, with variations tracked based on attributes (e.g., "velvet pillow" is a variation of the canonical "pillow").
+
+## Architecture
+
+### Storage System
+- **HuggingFace Dataset**: `Fraser/piclets` (public dataset repository)
+- **Structure**:
+  ```
+  piclets/
+    {normalized_object_name}.json  # e.g., pillow.json
+  users/
+    {username}.json                 # User profiles
+  metadata/
+    stats.json                      # Global statistics
+    leaderboard.json               # Top discoverers
+  ```
+
+### Object Normalization
+Objects are normalized for consistent storage:
+- Convert to lowercase
+- Remove articles (the, a, an)
+- Handle pluralization (pillows → pillow)
+- Replace spaces with underscores
+- Remove special characters
+
+Examples:
+- "The Blue Pillow" → `pillow`
+- "wooden chairs" → `wooden_chair`
+- "glasses" → `glass` (special case handling)
+
+### Piclet Data Structure
+```json
+{
+  "canonical": {
+    "objectName": "pillow",
+    "typeId": "pillow_canonical",
+    "discoveredBy": "username",
+    "discoveredAt": "2024-07-26T10:30:00",
+    "scanCount": 42,
+    "picletData": {
+      // Full Piclet instance data
+    }
+  },
+  "variations": [
+    {
+      "typeId": "pillow_001",
+      "attributes": ["velvet", "blue"],
+      "discoveredBy": "username2",
+      "discoveredAt": "2024-07-26T11:00:00",
+      "scanCount": 5,
+      "picletData": {
+        // Full variation data
+      }
+    }
+  ]
+}
+```
+
+## API Endpoints
+
+### Discovery Endpoints
+
+1. **search_piclet**: Find canonical or variation Piclets
+   - Input: `object_name`, `attributes[]`
+   - Returns: `status` (new/existing/variation), `piclet` data
+
+2. **create_canonical**: Register first discovery of an object
+   - Input: `object_name`, `piclet_data`, `username`
+   - Returns: Created canonical Piclet
+
+3. **create_variation**: Add variation to existing canonical
+   - Input: `canonical_id`, `attributes[]`, `piclet_data`, `username`, `object_name`
+   - Returns: Created variation
+
+4. **increment_scan_count**: Track popularity
+   - Input: `piclet_id`, `object_name`
+   - Returns: Updated scan count
+
+### Social Endpoints
+
+5. **get_recent_activity**: Global discovery feed
+   - Input: `limit` (default 20)
+   - Returns: Recent discoveries with metadata
+
+6. **get_leaderboard**: Top discoverers
+   - Input: `limit` (default 10)
+   - Returns: Ranked users by rarity score
+
+7. **get_user_profile**: Individual stats
+   - Input: `username`
+   - Returns: User's discoveries and statistics
+
+## Rarity System
+
+Scan count determines rarity:
+- **Legendary**: ≤ 5 scans
+- **Epic**: 6-20 scans
+- **Rare**: 21-50 scans
+- **Uncommon**: 51-100 scans
+- **Common**: > 100 scans
+
+Rarity scoring for leaderboard:
+- Canonical discovery: +100 points
+- Variation discovery: +50 points
+- Additional bonuses based on rarity tier
+
+## Authentication Strategy
+
+**Username-based system** (no passwords):
+- Users provide username in requests
+- All data is public (embracing open discovery)
+- User profiles track discoveries and stats
+- Future: Could integrate HuggingFace OAuth
+
+## Integration with Frontend
+
+The frontend (`../piclets/`) connects using Gradio Client:
+
+```javascript
+// Frontend connection
+const client = await window.gradioClient.Client.connect("Fraser/piclets-server");
+
+// Search for Piclet
+const result = await client.predict("/search_piclet", {
+  object_name: "pillow",
+  attributes: ["velvet", "blue"]
+});
+
+// Create canonical
+const created = await client.predict("/create_canonical", {
+  object_name: "pillow",
+  piclet_data: JSON.stringify(picletData),
+  username: "player123"
+});
+```
+
+## Development
+
+### Local Testing
+```bash
+pip install -r requirements.txt
+python app.py
+# Access at http://localhost:7860
+```
+
+### Deployment
+Push to HuggingFace Space repository:
+```bash
+git add -A && git commit -m "Update" && git push
+```
+
+### Environment Variables
+- `HF_TOKEN`: **Required** - HuggingFace write token (set in Space Secrets)
+- `DATASET_REPO`: Target dataset (default: "Fraser/piclets")
+
+## Key Implementation Details
+
+### Variation Matching
+- Uses set intersection to find attribute overlap
+- 50% match threshold for variations
+- Attributes are normalized and trimmed
+
+### Caching Strategy
+- Local cache in `cache/` directory
+- HuggingFace hub caching for downloads
+- Temporary files for uploads
+
+### Error Handling
+- Graceful fallbacks for missing data
+- Default user profiles for new users
+- Try-catch blocks around all dataset operations
+
+## Future Enhancements
+
+1. **Activity Log**: Separate timeline file for better performance
+2. **Image Storage**: Store Piclet images in dataset
+3. **Badges/Achievements**: Track discovery milestones
+4. **Trading System**: Allow users to trade variations
+5. **Seasonal Events**: Time-limited discoveries
+6. **OAuth Integration**: Verified HuggingFace accounts
+
+## Security Considerations
+
+- All data is public by design
+- No sensitive information stored
+- Username-only system (no passwords)
+- Input validation on all endpoints
+- Rate limiting should be added for production

README.md

@@ -1,13 +1,132 @@
 ---
-title: Piclets Server
-emoji: 🦀
-colorFrom: yellow
-colorTo: pink
+title: Piclets Discovery Server
+emoji: 🔍
+colorFrom: purple
+colorTo: blue
 sdk: gradio
 sdk_version: 5.38.2
 app_file: app.py
 pinned: false
-short_description: Backend for the Piclets game.
+short_description: Discover unique Piclets for every real-world object!
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🔍 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 HF_TOKEN**:
+   - Go to Space Settings → Repository secrets
+   - Add `HF_TOKEN` with write permissions to `Fraser/piclets` dataset
+
+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
+```
+
+## 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).

app.py

@@ -1,947 +1,625 @@
 import gradio as gr
 import json
 import os
-import uuid
+import re
 from datetime import datetime
 from typing import Dict, List, Optional, Tuple
-import hashlib
-import hmac
-import time
+from huggingface_hub import HfApi, hf_hub_download, list_repo_files
 from pathlib import Path
+import tempfile
 
-# Create data directories
-DATA_DIR = Path("data")
-PICLETS_DIR = DATA_DIR / "piclets"
-COLLECTIONS_DIR = DATA_DIR / "collections"
-IMAGES_DIR = DATA_DIR / "images"
+# HuggingFace configuration
+HF_TOKEN = os.getenv("HF_TOKEN")  # Required for writing to dataset
+DATASET_REPO = "Fraser/piclets"  # Public dataset repository
+DATASET_TYPE = "dataset"
 
-for dir_path in [DATA_DIR, PICLETS_DIR, COLLECTIONS_DIR, IMAGES_DIR]:
-    dir_path.mkdir(exist_ok=True)
+# Initialize HuggingFace API with token if available
+api = HfApi(token=HF_TOKEN) if HF_TOKEN else HfApi()
 
-# Secret key for verification (in production, use environment variable)
-SECRET_KEY = os.getenv("PICLET_SECRET_KEY", "piclets-dev-key-change-in-production")
+# Cache directory for local operations
+CACHE_DIR = Path("cache")
+CACHE_DIR.mkdir(exist_ok=True)
+
+class PicletDiscoveryService:
+    """Manages Piclet discovery using HuggingFace datasets"""
 
-class PicletVerification:
-    """Handles Piclet authenticity verification"""
-    
-    @staticmethod
-    def create_signature(piclet_data: dict, timestamp: int, generation_data: dict = None) -> str:
-        """
-        Create a cryptographic signature for a Piclet
-        Uses HMAC-SHA256 with the secret key
-        """
-        # Create deterministic string from core Piclet data
-        core_data = {
-            "name": piclet_data.get("name", ""),
-            "primaryType": piclet_data.get("primaryType", ""),
-            "baseStats": piclet_data.get("baseStats", {}),
-            "movepool": piclet_data.get("movepool", []),
-            "timestamp": timestamp
-        }
-        
-        # Add generation metadata if provided
-        if generation_data:
-            core_data["generation_data"] = generation_data
-        
-        # Create deterministic JSON string (sorted keys)
-        data_string = json.dumps(core_data, sort_keys=True, separators=(',', ':'))
-        
-        # Create HMAC signature
-        signature = hmac.new(
-            SECRET_KEY.encode('utf-8'),
-            data_string.encode('utf-8'),
-            hashlib.sha256
-        ).hexdigest()
-        
-        return signature
-    
-    @staticmethod
-    def verify_signature(piclet_data: dict, provided_signature: str, timestamp: int, generation_data: dict = None) -> bool:
-        """
-        Verify a Piclet's signature
-        Returns True if signature is valid
-        """
-        try:
-            expected_signature = PicletVerification.create_signature(piclet_data, timestamp, generation_data)
-            return hmac.compare_digest(expected_signature, provided_signature)
-        except Exception as e:
-            print(f"Signature verification error: {e}")
-            return False
-    
     @staticmethod
-    def create_verification_data(piclet_data: dict, image_caption: str = None, concept_string: str = None) -> dict:
+    def normalize_object_name(name: str) -> str:
         """
-        Create complete verification data for a Piclet
-        Includes signature, timestamp, and generation metadata
+        Normalize object names for consistent storage and lookup
+        Examples: "The Blue Pillow" -> "pillow", "wooden chairs" -> "wooden_chair"
         """
-        timestamp = int(time.time())
-        
-        # Generation metadata
-        generation_data = {
-            "image_caption": image_caption or "",
-            "concept_string": concept_string or "",
-            "generation_method": "official_app"
-        }
-        
-        # Create signature
-        signature = PicletVerification.create_signature(piclet_data, timestamp, generation_data)
-        
-        return {
-            "signature": signature,
-            "timestamp": timestamp,
-            "generation_data": generation_data,
-            "verification_version": "1.0"
-        }
-    
+        if not name:
+            return "unknown"
+
+        # Convert to lowercase and strip
+        name = name.lower().strip()
+
+        # Remove articles (the, a, an)
+        name = re.sub(r'^(the|a|an)\s+', '', name)
+
+        # Remove special characters except spaces
+        name = re.sub(r'[^a-z0-9\s]', '', name)
+
+        # Handle common plurals (basic pluralization rules)
+        if name.endswith('ies') and len(name) > 4:
+            name = name[:-3] + 'y'  # berries -> berry
+        elif name.endswith('ves') and len(name) > 4:
+            name = name[:-3] + 'f'  # leaves -> leaf
+        elif name.endswith('es') and len(name) > 3:
+            # Check if it's a special case like "glasses"
+            if not name.endswith(('ses', 'xes', 'zes', 'ches', 'shes')):
+                name = name[:-2]  # boxes -> box (but keep glasses)
+        elif name.endswith('s') and len(name) > 2 and not name.endswith('ss'):
+            name = name[:-1]  # chairs -> chair (but keep glass)
+
+        # Replace spaces with underscores
+        name = re.sub(r'\s+', '_', name.strip())
+
+        return name
+
     @staticmethod
-    def is_verified_piclet(piclet_data: dict) -> Tuple[bool, str]:
-        """
-        Check if a Piclet has valid verification
-        Returns: (is_verified, status_message)
-        """
+    def load_piclet_data(object_name: str) -> Optional[dict]:
+        """Load Piclet data from HuggingFace dataset"""
         try:
-            # Check for verification data
-            if "verification" not in piclet_data:
-                return False, "No verification data found"
-            
-            verification = piclet_data["verification"]
-            required_fields = ["signature", "timestamp", "generation_data"]
-            
-            for field in required_fields:
-                if field not in verification:
-                    return False, f"Missing verification field: {field}"
-            
-            # Verify signature
-            is_valid = PicletVerification.verify_signature(
-                piclet_data,
-                verification["signature"],
-                verification["timestamp"],
-                verification["generation_data"]
+            normalized_name = PicletDiscoveryService.normalize_object_name(object_name)
+            file_path = f"piclets/{normalized_name}.json"
+
+            # Download the file from HuggingFace
+            local_path = hf_hub_download(
+                repo_id=DATASET_REPO,
+                filename=file_path,
+                repo_type=DATASET_TYPE,
+                token=HF_TOKEN,
+                cache_dir=str(CACHE_DIR)
             )
-            
-            if not is_valid:
-                return False, "Invalid signature - Piclet may be modified or fake"
-            
-            # Check timestamp (reject if too old - 24 hours)
-            current_time = int(time.time())
-            piclet_time = verification["timestamp"]
-            
-            # Allow some flexibility for testing (24 hours)
-            if current_time - piclet_time > 86400:  # 24 hours
-                return False, "Piclet signature is too old (>24 hours)"
-            
-            return True, "Verified authentic Piclet"
-            
+
+            with open(local_path, 'r') as f:
+                return json.load(f)
         except Exception as e:
-            return False, f"Verification error: {str(e)}"
+            print(f"Could not load piclet data for {object_name}: {e}")
+            return None
 
-class PicletStorage:
-    """Handles saving and retrieving Piclet data using file-based storage"""
-    
     @staticmethod
-    def save_piclet(piclet_data: dict, image_file=None) -> Tuple[bool, str]:
-        """
-        Save a Piclet with optional image file
-        Returns: (success, piclet_id_or_error_message)
-        """
+    def save_piclet_data(object_name: str, data: dict) -> bool:
+        """Save Piclet data to HuggingFace dataset"""
         try:
-            # Generate unique ID
-            piclet_id = str(uuid.uuid4())
-            
-            # Add metadata
-            piclet_data["id"] = piclet_id
-            piclet_data["created_at"] = datetime.now().isoformat()
-            
-            # Handle image file if provided
-            if image_file is not None:
-                # Generate image filename
-                image_ext = Path(image_file.name).suffix if hasattr(image_file, 'name') else '.png'
-                image_filename = f"{piclet_id}{image_ext}"
-                image_path = IMAGES_DIR / image_filename
-                
-                # Save image file
-                if hasattr(image_file, 'save'):
-                    image_file.save(str(image_path))
-                else:
-                    # Handle different image input types
-                    with open(image_path, 'wb') as f:
-                        if hasattr(image_file, 'read'):
-                            f.write(image_file.read())
-                        else:
-                            f.write(image_file)
-                
-                piclet_data["image_filename"] = image_filename
-            
-            # Save Piclet data
-            piclet_file = PICLETS_DIR / f"{piclet_id}.json"
-            with open(piclet_file, 'w') as f:
-                json.dump(piclet_data, f, indent=2)
-            
-            return True, piclet_id
-            
+            normalized_name = PicletDiscoveryService.normalize_object_name(object_name)
+            file_path = f"piclets/{normalized_name}.json"
+
+            # Create a temporary file
+            with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+                json.dump(data, f, indent=2)
+                temp_path = f.name
+
+            # Upload to HuggingFace
+            api.upload_file(
+                path_or_fileobj=temp_path,
+                path_in_repo=file_path,
+                repo_id=DATASET_REPO,
+                repo_type=DATASET_TYPE,
+                commit_message=f"Update piclet: {normalized_name}"
+            )
+
+            # Clean up
+            os.unlink(temp_path)
+            return True
         except Exception as e:
-            return False, f"Error saving Piclet: {str(e)}"
-    
+            print(f"Failed to save piclet data: {e}")
+            return False
+
     @staticmethod
-    def get_piclet(piclet_id: str) -> Tuple[bool, dict]:
-        """
-        Retrieve a Piclet by ID
-        Returns: (success, piclet_data_or_error_message)
-        """
+    def load_user_data(username: str) -> dict:
+        """Load user profile from dataset"""
         try:
-            piclet_file = PICLETS_DIR / f"{piclet_id}.json"
-            if not piclet_file.exists():
-                return False, {"error": "Piclet not found"}
-            
-            with open(piclet_file, 'r') as f:
-                piclet_data = json.load(f)
-            
-            return True, piclet_data
-            
-        except Exception as e:
-            return False, {"error": f"Error retrieving Piclet: {str(e)}"}
-    
+            file_path = f"users/{username.lower()}.json"
+            local_path = hf_hub_download(
+                repo_id=DATASET_REPO,
+                filename=file_path,
+                repo_type=DATASET_TYPE,
+                token=HF_TOKEN,
+                cache_dir=str(CACHE_DIR)
+            )
+
+            with open(local_path, 'r') as f:
+                return json.load(f)
+        except:
+            # Return default user profile if not found
+            return {
+                "username": username,
+                "joinedAt": datetime.now().isoformat(),
+                "discoveries": [],
+                "uniqueFinds": 0,
+                "totalFinds": 0,
+                "rarityScore": 0
+            }
+
     @staticmethod
-    def list_piclets(limit: int = 50) -> Tuple[bool, List[dict]]:
-        """
-        List all saved Piclets with basic info
-        Returns: (success, list_of_piclet_summaries)
-        """
+    def save_user_data(username: str, data: dict) -> bool:
+        """Save user profile to dataset"""
         try:
-            piclets = []
-            piclet_files = list(PICLETS_DIR.glob("*.json"))
-            
-            # Sort by creation time (newest first)
-            piclet_files.sort(key=lambda x: x.stat().st_mtime, reverse=True)
-            
-            for piclet_file in piclet_files[:limit]:
-                try:
-                    with open(piclet_file, 'r') as f:
-                        data = json.load(f)
-                    
-                    # Create summary
-                    summary = {
-                        "id": data.get("id"),
-                        "name": data.get("name", "Unnamed Piclet"),
-                        "primaryType": data.get("primaryType"),
-                        "tier": data.get("tier"),
-                        "created_at": data.get("created_at"),
-                        "has_image": "image_filename" in data,
-                        "verified": data.get("verified", False)
-                    }
-                    piclets.append(summary)
-                    
-                except Exception as e:
-                    print(f"Error reading {piclet_file}: {e}")
-                    continue
-            
-            return True, piclets
-            
+            file_path = f"users/{username.lower()}.json"
+
+            with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+                json.dump(data, f, indent=2)
+                temp_path = f.name
+
+            api.upload_file(
+                path_or_fileobj=temp_path,
+                path_in_repo=file_path,
+                repo_id=DATASET_REPO,
+                repo_type=DATASET_TYPE,
+                commit_message=f"Update user profile: {username}"
+            )
+
+            os.unlink(temp_path)
+            return True
         except Exception as e:
-            return False, [{"error": f"Error listing Piclets: {str(e)}"}]
-    
+            print(f"Failed to save user data: {e}")
+            return False
+
     @staticmethod
-    def get_piclet_image(piclet_id: str):
-        """Get the image file for a Piclet"""
+    def update_global_stats() -> dict:
+        """Update and return global statistics"""
         try:
-            # First get the Piclet data to find image filename
-            success, piclet_data = PicletStorage.get_piclet(piclet_id)
-            if not success:
-                return None
-            
-            if "image_filename" not in piclet_data:
-                return None
-            
-            image_path = IMAGES_DIR / piclet_data["image_filename"]
-            if image_path.exists():
-                return str(image_path)
-            
-            return None
-            
+            # Try to load existing stats
+            try:
+                local_path = hf_hub_download(
+                    repo_id=DATASET_REPO,
+                    filename="metadata/stats.json",
+                    repo_type=DATASET_TYPE,
+                    token=HF_TOKEN,
+                    cache_dir=str(CACHE_DIR)
+                )
+                with open(local_path, 'r') as f:
+                    stats = json.load(f)
+            except:
+                stats = {
+                    "totalDiscoveries": 0,
+                    "uniqueObjects": 0,
+                    "totalVariations": 0,
+                    "lastUpdated": datetime.now().isoformat()
+                }
+
+            return stats
         except Exception as e:
-            print(f"Error getting image for {piclet_id}: {e}")
-            return None
+            print(f"Failed to update global stats: {e}")
+            return {}
+
+# API Endpoints
 
-def save_piclet_api(piclet_json: str, signature: str = "", image_file=None) -> str:
+def search_piclet(object_name: str, attributes: List[str]) -> dict:
     """
-    API endpoint to save a Piclet
+    Search for canonical Piclet or variations
+    Returns matching piclet or None
+    """
+    piclet_data = PicletDiscoveryService.load_piclet_data(object_name)
+
+    if not piclet_data:
+        return {
+            "status": "new",
+            "message": f"No Piclet found for '{object_name}'",
+            "piclet": None
+        }
+
+    # Check if searching for canonical (no attributes)
+    if not attributes or len(attributes) == 0:
+        return {
+            "status": "existing",
+            "message": f"Found canonical Piclet for '{object_name}'",
+            "piclet": piclet_data.get("canonical")
+        }
+
+    # Search for matching variation
+    variations = piclet_data.get("variations", [])
+    for variation in variations:
+        var_attrs = set(variation.get("attributes", []))
+        search_attrs = set(attributes)
+
+        # Check for close match (at least 50% overlap)
+        overlap = len(var_attrs.intersection(search_attrs))
+        if overlap >= len(search_attrs) * 0.5:
+            return {
+                "status": "variation",
+                "message": f"Found variation of '{object_name}'",
+                "piclet": variation,
+                "canonicalId": piclet_data["canonical"]["typeId"]
+            }
+
+    # No variation found, suggest creating one
+    return {
+        "status": "new_variation",
+        "message": f"No variation found for '{object_name}' with attributes {attributes}",
+        "canonicalId": piclet_data["canonical"]["typeId"],
+        "piclet": None
+    }
+
+def create_canonical(object_name: str, piclet_data: str, username: str) -> dict:
+    """
+    Create a new canonical Piclet
     """
     try:
-        # Parse the JSON data
-        piclet_data = json.loads(piclet_json)
-        
-        # Validate required fields
-        required_fields = ["name", "primaryType", "baseStats", "movepool"]
-        for field in required_fields:
-            if field not in piclet_data:
-                return json.dumps({
-                    "success": False,
-                    "error": f"Missing required field: {field}"
-                })
-        
-        # Verify Piclet authenticity
-        is_verified, verification_message = PicletVerification.is_verified_piclet(piclet_data)
-        
-        if not is_verified:
-            return json.dumps({
-                "success": False,
-                "error": f"Verification failed: {verification_message}",
-                "verification_required": True
-            })
-        
-        # Add verification status to stored data
-        piclet_data["verified"] = True
-        piclet_data["verification_message"] = verification_message
-        
-        # Save the Piclet
-        success, result = PicletStorage.save_piclet(piclet_data, image_file)
-        
-        if success:
-            return json.dumps({
+        piclet_json = json.loads(piclet_data) if isinstance(piclet_data, str) else piclet_data
+
+        # Create canonical entry
+        canonical_data = {
+            "canonical": {
+                "objectName": object_name,
+                "typeId": f"{PicletDiscoveryService.normalize_object_name(object_name)}_canonical",
+                "discoveredBy": username,
+                "discoveredAt": datetime.now().isoformat(),
+                "scanCount": 1,
+                "picletData": piclet_json
+            },
+            "variations": []
+        }
+
+        # Save to dataset
+        if PicletDiscoveryService.save_piclet_data(object_name, canonical_data):
+            # Update user profile
+            user_data = PicletDiscoveryService.load_user_data(username)
+            user_data["discoveries"].append(canonical_data["canonical"]["typeId"])
+            user_data["uniqueFinds"] += 1
+            user_data["totalFinds"] += 1
+            user_data["rarityScore"] += 100  # Bonus for canonical discovery
+            PicletDiscoveryService.save_user_data(username, user_data)
+
+            return {
                 "success": True,
-                "piclet_id": result,
-                "message": "Verified Piclet saved successfully",
-                "verified": True
-            })
+                "message": f"Created canonical Piclet for '{object_name}'",
+                "piclet": canonical_data["canonical"]
+            }
         else:
-            return json.dumps({
+            return {
                 "success": False,
-                "error": result
-            })
-            
-    except json.JSONDecodeError:
-        return json.dumps({
-            "success": False,
-            "error": "Invalid JSON format"
-        })
+                "error": "Failed to save canonical Piclet"
+            }
     except Exception as e:
-        return json.dumps({
+        return {
             "success": False,
-            "error": f"Unexpected error: {str(e)}"
-        })
+            "error": str(e)
+        }
 
-def get_piclet_api(piclet_id: str) -> str:
+def create_variation(canonical_id: str, attributes: List[str], piclet_data: str, username: str, object_name: str) -> dict:
     """
-    API endpoint to retrieve a Piclet by ID
+    Create a variation of an existing canonical Piclet
     """
     try:
-        if not piclet_id.strip():
-            return json.dumps({
+        piclet_json = json.loads(piclet_data) if isinstance(piclet_data, str) else piclet_data
+
+        # Load existing data
+        existing_data = PicletDiscoveryService.load_piclet_data(object_name)
+        if not existing_data:
+            return {
                 "success": False,
-                "error": "Piclet ID is required"
-            })
-        
-        success, result = PicletStorage.get_piclet(piclet_id.strip())
-        
-        if success:
-            return json.dumps({
+                "error": f"Canonical Piclet not found for '{object_name}'"
+            }
+
+        # Create variation entry
+        variation_id = f"{PicletDiscoveryService.normalize_object_name(object_name)}_{len(existing_data['variations']) + 1:03d}"
+        variation = {
+            "typeId": variation_id,
+            "attributes": attributes,
+            "discoveredBy": username,
+            "discoveredAt": datetime.now().isoformat(),
+            "scanCount": 1,
+            "picletData": piclet_json
+        }
+
+        # Add to variations
+        existing_data["variations"].append(variation)
+
+        # Save updated data
+        if PicletDiscoveryService.save_piclet_data(object_name, existing_data):
+            # Update user profile
+            user_data = PicletDiscoveryService.load_user_data(username)
+            user_data["discoveries"].append(variation_id)
+            user_data["totalFinds"] += 1
+            user_data["rarityScore"] += 50  # Bonus for variation discovery
+            PicletDiscoveryService.save_user_data(username, user_data)
+
+            return {
                 "success": True,
-                "piclet": result
-            })
+                "message": f"Created variation of '{object_name}'",
+                "piclet": variation
+            }
         else:
-            return json.dumps({
+            return {
                 "success": False,
-                "error": result.get("error", "Unknown error")
-            })
-            
+                "error": "Failed to save variation"
+            }
     except Exception as e:
-        return json.dumps({
+        return {
             "success": False,
-            "error": f"Unexpected error: {str(e)}"
-        })
+            "error": str(e)
+        }
 
-def list_piclets_api(limit: int = 50) -> str:
+def increment_scan_count(piclet_id: str, object_name: str) -> dict:
     """
-    API endpoint to list all saved Piclets
+    Increment the scan count for a Piclet
     """
     try:
-        limit = max(1, min(limit, 100))  # Limit between 1 and 100
-        
-        success, result = PicletStorage.list_piclets(limit)
-        
-        if success:
-            return json.dumps({
+        data = PicletDiscoveryService.load_piclet_data(object_name)
+        if not data:
+            return {
+                "success": False,
+                "error": "Piclet not found"
+            }
+
+        # Check canonical
+        if data["canonical"]["typeId"] == piclet_id:
+            data["canonical"]["scanCount"] = data["canonical"].get("scanCount", 0) + 1
+            scan_count = data["canonical"]["scanCount"]
+        else:
+            # Check variations
+            for variation in data["variations"]:
+                if variation["typeId"] == piclet_id:
+                    variation["scanCount"] = variation.get("scanCount", 0) + 1
+                    scan_count = variation["scanCount"]
+                    break
+            else:
+                return {
+                    "success": False,
+                    "error": "Piclet ID not found"
+                }
+
+        # Save updated data
+        if PicletDiscoveryService.save_piclet_data(object_name, data):
+            return {
                 "success": True,
-                "piclets": result,
-                "count": len(result)
-            })
+                "scanCount": scan_count
+            }
         else:
-            return json.dumps({
+            return {
                 "success": False,
-                "error": "Failed to list Piclets"
-            })
-            
+                "error": "Failed to update scan count"
+            }
     except Exception as e:
-        return json.dumps({
+        return {
             "success": False,
-            "error": f"Unexpected error: {str(e)}"
-        })
+            "error": str(e)
+        }
 
-def get_piclet_image_api(piclet_id: str):
+def get_recent_activity(limit: int = 20) -> dict:
     """
-    API endpoint to get a Piclet's image
+    Get recent discoveries across all users
     """
     try:
-        if not piclet_id.strip():
-            return None
-        
-        image_path = PicletStorage.get_piclet_image(piclet_id.strip())
-        return image_path
-        
+        activities = []
+
+        # List all piclet files
+        try:
+            files = list_repo_files(
+                repo_id=DATASET_REPO,
+                repo_type=DATASET_TYPE,
+                token=HF_TOKEN
+            )
+            piclet_files = [f for f in files if f.startswith("piclets/") and f.endswith(".json")]
+        except:
+            piclet_files = []
+
+        # Load recent piclets (simplified - in production, maintain a separate activity log)
+        for file_path in piclet_files[-limit:]:
+            try:
+                object_name = file_path.replace("piclets/", "").replace(".json", "")
+                data = PicletDiscoveryService.load_piclet_data(object_name)
+
+                if data:
+                    # Add canonical discovery
+                    canonical = data["canonical"]
+                    activities.append({
+                        "type": "discovery",
+                        "objectName": object_name,
+                        "typeId": canonical["typeId"],
+                        "discoveredBy": canonical["discoveredBy"],
+                        "discoveredAt": canonical["discoveredAt"],
+                        "scanCount": canonical.get("scanCount", 1)
+                    })
+
+                    # Add recent variations
+                    for variation in data.get("variations", [])[-5:]:
+                        activities.append({
+                            "type": "variation",
+                            "objectName": object_name,
+                            "typeId": variation["typeId"],
+                            "attributes": variation["attributes"],
+                            "discoveredBy": variation["discoveredBy"],
+                            "discoveredAt": variation["discoveredAt"],
+                            "scanCount": variation.get("scanCount", 1)
+                        })
+            except:
+                continue
+
+        # Sort by discovery date
+        activities.sort(key=lambda x: x.get("discoveredAt", ""), reverse=True)
+
+        return {
+            "success": True,
+            "activities": activities[:limit]
+        }
     except Exception as e:
-        print(f"Error in get_piclet_image_api: {e}")
-        return None
+        return {
+            "success": False,
+            "error": str(e),
+            "activities": []
+        }
 
-def sign_piclet_api(piclet_json: str, image_caption: str = "", concept_string: str = "") -> str:
+def get_leaderboard(limit: int = 10) -> dict:
     """
-    API endpoint to sign a Piclet (for static frontend integration)
-    This allows static sites to generate verified Piclets without exposing the secret key
+    Get top discoverers
     """
     try:
-        # Parse the JSON data
-        piclet_data = json.loads(piclet_json)
-        
-        # Validate required fields
-        required_fields = ["name", "primaryType", "baseStats", "movepool"]
-        for field in required_fields:
-            if field not in piclet_data:
-                return json.dumps({
-                    "success": False,
-                    "error": f"Missing required field: {field}"
+        leaderboard = []
+
+        # List all user files
+        try:
+            files = list_repo_files(
+                repo_id=DATASET_REPO,
+                repo_type=DATASET_TYPE,
+                token=HF_TOKEN
+            )
+            user_files = [f for f in files if f.startswith("users/") and f.endswith(".json")]
+        except:
+            user_files = []
+
+        # Load user data
+        for file_path in user_files:
+            try:
+                username = file_path.replace("users/", "").replace(".json", "")
+                user_data = PicletDiscoveryService.load_user_data(username)
+
+                leaderboard.append({
+                    "username": username,
+                    "totalFinds": user_data.get("totalFinds", 0),
+                    "uniqueFinds": user_data.get("uniqueFinds", 0),
+                    "rarityScore": user_data.get("rarityScore", 0)
                 })
-        
-        # Create verification data using server's secret key
-        verification_data = PicletVerification.create_verification_data(
-            piclet_data,
-            image_caption=image_caption,
-            concept_string=concept_string
-        )
-        
-        # Add verification to Piclet data
-        verified_piclet = {**piclet_data, "verification": verification_data}
-        
-        return json.dumps({
+            except:
+                continue
+
+        # Sort by rarity score
+        leaderboard.sort(key=lambda x: x["rarityScore"], reverse=True)
+
+        # Add ranks
+        for i, entry in enumerate(leaderboard[:limit]):
+            entry["rank"] = i + 1
+
+        return {
             "success": True,
-            "verified_piclet": verified_piclet,
-            "signature": verification_data["signature"],
-            "message": "Piclet signed successfully - ready for storage"
-        })
-        
-    except json.JSONDecodeError:
-        return json.dumps({
-            "success": False,
-            "error": "Invalid JSON format"
-        })
+            "leaderboard": leaderboard[:limit]
+        }
     except Exception as e:
-        return json.dumps({
+        return {
             "success": False,
-            "error": f"Signing error: {str(e)}"
-        })
+            "error": str(e),
+            "leaderboard": []
+        }
 
-def sign_and_save_piclet_api(piclet_json: str, image_caption: str = "", concept_string: str = "", image_file=None) -> str:
+def get_user_profile(username: str) -> dict:
     """
-    API endpoint to sign AND save a Piclet in one step (convenience method)
-    Perfect for static frontends - no secret key needed on client side
+    Get user's discovery profile
     """
     try:
-        # First, sign the Piclet
-        sign_result_json = sign_piclet_api(piclet_json, image_caption, concept_string)
-        sign_result = json.loads(sign_result_json)
-        
-        if not sign_result["success"]:
-            return sign_result_json
-        
-        # Then save the verified Piclet
-        verified_piclet_json = json.dumps(sign_result["verified_piclet"])
-        save_result_json = save_piclet_api(verified_piclet_json, sign_result["signature"], image_file)
-        save_result = json.loads(save_result_json)
-        
-        if save_result["success"]:
-            return json.dumps({
-                "success": True,
-                "piclet_id": save_result["piclet_id"],
-                "message": "Piclet signed and saved successfully",
-                "verified": True,
-                "signature": sign_result["signature"]
-            })
-        else:
-            return save_result_json
-            
+        user_data = PicletDiscoveryService.load_user_data(username)
+        return {
+            "success": True,
+            "profile": user_data
+        }
     except Exception as e:
-        return json.dumps({
+        return {
             "success": False,
-            "error": f"Sign and save error: {str(e)}"
-        })
-
-# Create example Piclet data for testing
-def create_example_piclet() -> str:
-    """Create an example Piclet for testing"""
-    example_piclet = {
-        "name": "Stellar Wolf",
-        "description": "A majestic wolf creature infused with cosmic energy",
-        "tier": "medium",
-        "primaryType": "space",
-        "secondaryType": "beast",
-        "baseStats": {
-            "hp": 85,
-            "attack": 90,
-            "defense": 70,
-            "speed": 80
-        },
-        "nature": "Bold",
-        "specialAbility": {
-            "name": "Cosmic Howl",
-            "description": "Increases attack when health is low"
-        },
-        "movepool": [
-            {
-                "name": "Star Strike",
-                "type": "space",
-                "power": 75,
-                "accuracy": 90,
-                "pp": 15,
-                "priority": 0,
-                "flags": [],
-                "effects": [
-                    {
-                        "type": "damage",
-                        "target": "opponent",
-                        "amount": "normal"
-                    }
-                ]
-            },
-            {
-                "name": "Lunar Bite",
-                "type": "beast",
-                "power": 80,
-                "accuracy": 85,
-                "pp": 12,
-                "priority": 0,
-                "flags": ["contact", "bite"],
-                "effects": [
-                    {
-                        "type": "damage",
-                        "target": "opponent",
-                        "amount": "normal"
-                    }
-                ]
-            }
-        ]
-    }
-    
-    return json.dumps(example_piclet, indent=2)
+            "error": str(e),
+            "profile": None
+        }
 
-# Create the Gradio interface
-with gr.Blocks(title="Piclets Server API", theme=gr.themes.Soft()) as app:
+# Create Gradio interface
+with gr.Blocks(title="Piclets Discovery Server") as app:
     gr.Markdown("""
-    # 🦀 Piclets Server API
-    
-    Backend server for saving and sharing Piclets (AI-generated creatures) from the Piclets game.
-    
-    ## Quick Start
-    1. **Save a Piclet**: Use the JSON format below with optional image upload
-    2. **Retrieve a Piclet**: Enter a Piclet ID to get the full data
-    3. **List Piclets**: See all saved Piclets with summaries
-    4. **Get Images**: Retrieve the original image for any Piclet
+    # 🔍 Piclets Discovery Server
+
+    Backend service for the Piclets discovery game. Each real-world object has ONE canonical Piclet!
     """)
-    
-    with gr.Tabs():
-        # Sign and Save Tab (For Static Frontends)
-        with gr.Tab("✍️ Sign & Save Piclet"):
-            gr.Markdown("### Sign and Save a Piclet (One Step - Perfect for Static Sites)")
-            gr.Markdown("🌟 **For Static Frontends**: No secret key needed! Server signs your Piclet automatically.")
-            
-            with gr.Row():
-                with gr.Column(scale=2):
-                    unsigned_json_input = gr.Textbox(
-                        label="Unsigned Piclet JSON Data",
-                        placeholder="Paste your unsigned Piclet JSON here...",
-                        lines=12,
-                        value=create_example_piclet()
-                    )
-                    
-                    with gr.Row():
-                        caption_input = gr.Textbox(
-                            label="Image Caption",
-                            placeholder="AI-generated image description...",
-                            lines=2
-                        )
-                        concept_input = gr.Textbox(
-                            label="Concept String", 
-                            placeholder="Creature concept from AI...",
-                            lines=2
-                        )
-                
-                with gr.Column(scale=1):
-                    sign_save_image_input = gr.File(
-                        label="Piclet Image (Optional)",
-                        file_types=["image"]
-                    )
-                    
-                    sign_save_btn = gr.Button("✍️ Sign & Save Piclet", variant="primary")
-                    
-                    sign_save_output = gr.JSON(label="Sign & Save Result")
-            
-            sign_save_btn.click(
-                fn=sign_and_save_piclet_api,
-                inputs=[unsigned_json_input, caption_input, concept_input, sign_save_image_input],
-                outputs=sign_save_output
-            )
-        
-        # Sign Only Tab
-        with gr.Tab("🔏 Sign Only"):
-            gr.Markdown("### Sign a Piclet (Two-Step Process)")
-            gr.Markdown("📝 **Advanced**: Sign first, then save separately. Useful for batch operations.")
-            
-            with gr.Row():
-                with gr.Column(scale=2):
-                    sign_json_input = gr.Textbox(
-                        label="Unsigned Piclet JSON Data",
-                        placeholder="Paste your unsigned Piclet JSON here...",
-                        lines=10,
-                        value=create_example_piclet()
-                    )
-                    
-                    with gr.Row():
-                        sign_caption_input = gr.Textbox(
-                            label="Image Caption",
-                            placeholder="AI-generated image description..."
-                        )
-                        sign_concept_input = gr.Textbox(
-                            label="Concept String",
-                            placeholder="Creature concept from AI..."
-                        )
-                
-                with gr.Column(scale=2):
-                    sign_btn = gr.Button("🔏 Sign Piclet", variant="secondary")
-                    sign_output = gr.JSON(label="Signing Result")
-            
-            sign_btn.click(
-                fn=sign_piclet_api,
-                inputs=[sign_json_input, sign_caption_input, sign_concept_input],
-                outputs=sign_output
-            )
-        
-        # Save Piclet Tab (For Pre-Signed)
-        with gr.Tab("💾 Save Pre-Signed"):
-            gr.Markdown("### Save a Pre-Signed Piclet")
-            gr.Markdown("⚠️ **For Advanced Users**: Save a Piclet that was already signed elsewhere.")
-            
-            with gr.Row():
-                with gr.Column(scale=2):
-                    piclet_json_input = gr.Textbox(
-                        label="Piclet JSON Data",
-                        placeholder="Paste your Piclet JSON here...",
-                        lines=15,
-                        value=create_example_piclet()
-                    )
-                    
-                with gr.Column(scale=1):
-                    image_input = gr.File(
-                        label="Piclet Image (Optional)",
-                        file_types=["image"]
-                    )
-                    
-                    save_btn = gr.Button("💾 Save Piclet", variant="primary")
-                    
-                    save_output = gr.JSON(label="Save Result")
-            
-            save_btn.click(
-                fn=save_piclet_api,
-                inputs=[piclet_json_input, image_input],
-                outputs=save_output
-            )
-        
-        # Get Piclet Tab
-        with gr.Tab("🔍 Get Piclet"):
-            gr.Markdown("### Retrieve a Piclet by ID")
-            
-            with gr.Row():
-                with gr.Column(scale=2):
-                    piclet_id_input = gr.Textbox(
-                        label="Piclet ID",
-                        placeholder="Enter Piclet ID here..."
-                    )
-                    
-                    get_btn = gr.Button("🔍 Get Piclet", variant="primary")
-                    
-                with gr.Column(scale=2):
-                    get_output = gr.JSON(label="Piclet Data")
-            
-            get_btn.click(
-                fn=get_piclet_api,
-                inputs=piclet_id_input,
-                outputs=get_output
-            )
-        
-        # List Piclets Tab
-        with gr.Tab("📋 List Piclets"):
-            gr.Markdown("### Browse all saved Piclets")
-            
-            with gr.Row():
-                with gr.Column(scale=1):
-                    limit_input = gr.Slider(
-                        label="Max Results",
-                        minimum=1,
-                        maximum=100,
-                        value=20,
-                        step=1
-                    )
-                    
-                    list_btn = gr.Button("📋 List Piclets", variant="primary")
-                
-                with gr.Column(scale=3):
-                    list_output = gr.JSON(label="Piclets List")
-            
-            list_btn.click(
-                fn=list_piclets_api,
-                inputs=limit_input,
-                outputs=list_output
-            )
-        
-        # Get Image Tab
-        with gr.Tab("🖼️ Get Image"):
-            gr.Markdown("### Retrieve a Piclet's image")
-            
-            with gr.Row():
-                with gr.Column(scale=1):
-                    image_id_input = gr.Textbox(
-                        label="Piclet ID",
-                        placeholder="Enter Piclet ID here..."
-                    )
-                    
-                    get_image_btn = gr.Button("🖼️ Get Image", variant="primary")
-                
-                with gr.Column(scale=2):
-                    image_output = gr.Image(label="Piclet Image")
-            
-            get_image_btn.click(
-                fn=get_piclet_image_api,
-                inputs=image_id_input,
-                outputs=image_output
-            )
-        
-        # Generate Verified Example Tab
-        with gr.Tab("✅ Generate Verified Example"):
-            gr.Markdown("""
-            ### Generate a Verified Example Piclet
-            
-            This creates a properly signed example Piclet that will pass verification.
-            Use this to test the verification system or as a template.
-            """)
-            
-            generate_btn = gr.Button("✅ Generate Verified Example", variant="primary")
-            verified_output = gr.Textbox(
-                label="Verified Piclet JSON",
-                lines=20,
-                show_copy_button=True
-            )
-            
-            generate_btn.click(
-                fn=create_verified_example_api,
-                outputs=verified_output
-            )
-        
-        # API Documentation Tab
-        with gr.Tab("📖 API Documentation & Verification"):
-            gr.Markdown("""
-            ## 🔐 Verification System
-            
-            **All Piclets must be verified to prevent fake or modified creatures.**
-            
-            ### How Verification Works:
-            1. **HMAC-SHA256 Signature**: Each Piclet is signed with a secret key
-            2. **Timestamp Validation**: Signatures expire after 24 hours
-            3. **Generation Metadata**: Includes image caption and concept string
-            4. **Tamper Detection**: Any modification invalidates the signature
-            
-            ### Required Verification Format:
-            ```json
-            {
-              "verification": {
-                "signature": "abc123...",
-                "timestamp": 1690123456,
-                "generation_data": {
-                  "image_caption": "AI-generated description",
-                  "concept_string": "Creature concept",
-                  "generation_method": "official_app"
-                },
-                "verification_version": "1.0"
-              }
-            }
-            ```
-            
-            ## API Endpoints
-            
-            ### 1. Sign & Save Piclet (Recommended for Static Sites)
-            - **Function**: `sign_and_save_piclet_api(piclet_json, image_caption, concept_string, image_file=None)`
-            - **Input**: Unsigned Piclet JSON, image caption, concept string, optional image file
-            - **Output**: JSON response with success status and Piclet ID
-            - **✅ Perfect for**: Static sites (no secret key needed)
-            
-            ### 2. Sign Only
-            - **Function**: `sign_piclet_api(piclet_json, image_caption, concept_string)`
-            - **Input**: Unsigned Piclet JSON, image caption, concept string
-            - **Output**: JSON response with verified Piclet and signature
-            - **Use case**: Two-step process, batch operations
-            
-            ### 3. Save Pre-Signed Piclet
-            - **Function**: `save_piclet_api(piclet_json, signature, image_file=None)`
-            - **Input**: Signed Piclet JSON, signature string, optional image file
-            - **Output**: JSON response with success status and Piclet ID
-            - **⚠️ Requires**: Valid verification signature
-            
-            ### 2. Get Piclet
-            - **Function**: `get_piclet_api(piclet_id)`
-            - **Input**: Piclet ID string
-            - **Output**: JSON response with full Piclet data
-            
-            ### 3. List Piclets
-            - **Function**: `list_piclets_api(limit=50)`
-            - **Input**: Maximum number of results (1-100)
-            - **Output**: JSON response with Piclet summaries
-            
-            ### 4. Get Image
-            - **Function**: `get_piclet_image_api(piclet_id)`
-            - **Input**: Piclet ID string
-            - **Output**: Image file path or None
-            
-            ## Required JSON Format
-            
-            ```json
-            {
-              "name": "Piclet Name",
-              "description": "Description of the creature",
-              "tier": "low|medium|high|legendary",
-              "primaryType": "beast|bug|aquatic|flora|mineral|space|machina|structure|culture|cuisine",
-              "secondaryType": "same options as primaryType or null",
-              "baseStats": {
-                "hp": 85,
-                "attack": 90,
-                "defense": 70,
-                "speed": 80
-              },
-              "nature": "Personality trait",
-              "specialAbility": {
-                "name": "Ability Name",
-                "description": "What the ability does"
-              },
-              "movepool": [
-                {
-                  "name": "Move Name",
-                  "type": "attack type",
-                  "power": 75,
-                  "accuracy": 90,
-                  "pp": 15,
-                  "priority": 0,
-                  "flags": ["contact", "bite", etc.],
-                  "effects": [
-                    {
-                      "type": "damage|heal|modifyStats|etc.",
-                      "target": "opponent|self|all",
-                      "amount": "weak|normal|strong|extreme"
-                    }
-                  ]
-                }
-              ]
-            }
-            ```
-            
-            ## Frontend Integration (JavaScript)
-            
-            ### Include Verification Helper
-            ```html
-            <!-- Include crypto-js for HMAC generation -->
-            <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script>
-            <script src="verification_helper.js"></script>
-            ```
-            
-            ### Static Site Usage (Recommended)
-            ```javascript
-            // Connect to this Gradio space
-            const client = await window.gradioClient.Client.connect("your-space-name");
-            
-            // Sign and save in one step (NO SECRET KEY NEEDED!)
-            const result = await client.predict("/sign_and_save_piclet_api", [
-                JSON.stringify(picletData),     // Unsigned Piclet data
-                imageCaption,                   // AI-generated caption
-                conceptString,                  // Creature concept
-                imageFile                       // Optional image
-            ]);
-            
-            const response = JSON.parse(result.data[0]);
-            if (response.success) {
-                console.log(`Piclet saved with ID: ${response.piclet_id}`);
-            } else {
-                console.error(`Save failed: ${response.error}`);
-            }
-            
-            // Two-step process (sign first, then save)
-            const signResult = await client.predict("/sign_piclet_api", [
-                JSON.stringify(picletData),
-                imageCaption,
-                conceptString
-            ]);
-            
-            const signResponse = JSON.parse(signResult.data[0]);
-            if (signResponse.success) {
-                const saveResult = await client.predict("/save_piclet_api", [
-                    JSON.stringify(signResponse.verified_piclet),
-                    signResponse.signature,
-                    imageFile
-                ]);
-            }
-            ```
-            
-            ### Secret Key Management (Server Only)
-            ```bash
-            # Set environment variable on server (HuggingFace Spaces)
-            PICLET_SECRET_KEY=your-super-secret-64-char-hex-key
-            
-            # Generate secure key:
-            openssl rand -hex 32
-            
-            # ✅ Frontend doesn't need the secret key anymore!
-            # Server handles all signing securely
-            ```
-            
-            ## Storage Structure
-            
-            - **Data Directory**: `./data/`
-            - **Piclets**: `./data/piclets/*.json`
-            - **Images**: `./data/images/*`
-            - **Collections**: `./data/collections/*.json` (future feature)
-            
-            All data is stored locally in the Hugging Face Space persistent storage.
-            
-            ## Security Features
-            
-            ### ✅ Verified Piclets
-            - Generated through official app only
-            - Cryptographically signed with HMAC-SHA256
-            - Include generation metadata (image caption, concept)
-            - Tamper-proof (any modification breaks signature)
-            
-            ### ❌ Rejected Piclets
-            - Missing verification data
-            - Invalid or expired signatures
-            - Modified after generation
-            - Created outside official app
-            
-            ### Environment Variables
-            - `PICLET_SECRET_KEY`: Secret key for verification (change in production)
-            
-            ### Files Included
-            - `app.py`: Main server application
-            - `verification_helper.js`: Frontend helper functions
-            - `requirements.txt`: Python dependencies
-            - `API_DOCUMENTATION.md`: Complete documentation
-            """)
-
-# Launch the app
+
+    with gr.Tab("Search Piclet"):
+        with gr.Row():
+            with gr.Column():
+                search_object = gr.Textbox(label="Object Name", placeholder="e.g., pillow")
+                search_attrs = gr.Textbox(label="Attributes (comma-separated)", placeholder="e.g., velvet, blue")
+                search_btn = gr.Button("Search", variant="primary")
+            with gr.Column():
+                search_result = gr.JSON(label="Search Result")
+
+        search_btn.click(
+            fn=lambda obj, attrs: search_piclet(obj, [a.strip() for a in attrs.split(",")] if attrs else []),
+            inputs=[search_object, search_attrs],
+            outputs=search_result
+        )
+
+    with gr.Tab("Create Canonical"):
+        with gr.Row():
+            with gr.Column():
+                canonical_object = gr.Textbox(label="Object Name")
+                canonical_data = gr.Textbox(label="Piclet Data (JSON)", lines=10)
+                canonical_user = gr.Textbox(label="Username")
+                canonical_btn = gr.Button("Create Canonical", variant="primary")
+            with gr.Column():
+                canonical_result = gr.JSON(label="Creation Result")
+
+        canonical_btn.click(
+            fn=create_canonical,
+            inputs=[canonical_object, canonical_data, canonical_user],
+            outputs=canonical_result
+        )
+
+    with gr.Tab("Create Variation"):
+        with gr.Row():
+            with gr.Column():
+                var_object = gr.Textbox(label="Object Name")
+                var_canonical = gr.Textbox(label="Canonical ID")
+                var_attrs = gr.Textbox(label="Variation Attributes (comma-separated)")
+                var_data = gr.Textbox(label="Piclet Data (JSON)", lines=10)
+                var_user = gr.Textbox(label="Username")
+                var_btn = gr.Button("Create Variation", variant="primary")
+            with gr.Column():
+                var_result = gr.JSON(label="Creation Result")
+
+        var_btn.click(
+            fn=lambda obj, cid, attrs, data, user: create_variation(
+                cid, [a.strip() for a in attrs.split(",")] if attrs else [], data, user, obj
+            ),
+            inputs=[var_object, var_canonical, var_attrs, var_data, var_user],
+            outputs=var_result
+        )
+
+    with gr.Tab("Activity Feed"):
+        activity_limit = gr.Slider(5, 50, value=20, label="Number of Activities")
+        activity_btn = gr.Button("Get Recent Activity")
+        activity_result = gr.JSON(label="Recent Discoveries")
+
+        activity_btn.click(
+            fn=get_recent_activity,
+            inputs=activity_limit,
+            outputs=activity_result
+        )
+
+    with gr.Tab("Leaderboard"):
+        leader_limit = gr.Slider(5, 20, value=10, label="Top N Discoverers")
+        leader_btn = gr.Button("Get Leaderboard")
+        leader_result = gr.JSON(label="Top Discoverers")
+
+        leader_btn.click(
+            fn=get_leaderboard,
+            inputs=leader_limit,
+            outputs=leader_result
+        )
+
+    with gr.Tab("User Profile"):
+        profile_user = gr.Textbox(label="Username")
+        profile_btn = gr.Button("Get Profile")
+        profile_result = gr.JSON(label="User Profile")
+
+        profile_btn.click(
+            fn=get_user_profile,
+            inputs=profile_user,
+            outputs=profile_result
+        )
+
+    # API Documentation
+    gr.Markdown("""
+    ## API Endpoints
+
+    All endpoints accept JSON and return JSON responses.
+
+    - **search_piclet**: Search for canonical or variation Piclets
+    - **create_canonical**: Register a new canonical Piclet
+    - **create_variation**: Add a variation to existing canonical
+    - **increment_scan_count**: Track discovery popularity
+    - **get_recent_activity**: Global discovery feed
+    - **get_leaderboard**: Top discoverers
+    - **get_user_profile**: Individual discovery stats
+
+    See API_DOCUMENTATION.md for detailed usage.
+    """)
+
 if __name__ == "__main__":
-    app.launch(
-        server_name="0.0.0.0",
-        server_port=7860,
-        share=False
-    )
+    app.launch()

requirements.txt

@@ -1,2 +1,4 @@
 gradio==5.38.2
-Pillow>=9.0.0
+Pillow>=9.0.0
+huggingface_hub>=0.20.0
+datasets>=2.15.0