API_DOCUMENTATION.md

Piclets Discovery Server API Documentation

Overview

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

Running Locally

pip install -r requirements.txt
python app.py

Accessing the API

• Web Interface: http://localhost:7860
• Programmatic Access: Use Gradio Client to connect to the space

Frontend Integration

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. Search Piclet

Endpoint: /search_piclet Purpose: Search for canonical Piclet or variations Method: Gradio function call

Input Parameters:

{
  "object_name": "pillow",
  "attributes": ["velvet", "blue"]
}

Response Types:

New Object (no Piclet exists):

{
  "status": "new",
  "message": "No Piclet found for 'pillow'",
  "piclet": null
}

Existing Canonical (exact match):

{
  "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:

{
  "status": "variation",
  "message": "Found variation of 'pillow'",
  "piclet": { /* variation data */ },
  "canonicalId": "pillow_canonical"
}

New Variation Suggested:

{
  "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

Input Parameters:

{
  "object_name": "pillow",
  "piclet_data": "{ /* JSON string of Piclet instance */ }",
  "username": "discoverer123"
}

Success Response:

{
  "success": true,
  "message": "Created canonical Piclet for 'pillow'",
  "piclet": {
    "objectName": "pillow",
    "typeId": "pillow_canonical",
    "discoveredBy": "discoverer123",
    "discoveredAt": "2024-07-26T10:30:00",
    "scanCount": 1,
    "picletData": { /* full Piclet data */ }
  }
}

Error Response:

{
  "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

Input Parameters:

{
  "canonical_id": "pillow_canonical",
  "attributes": ["velvet", "blue"],
  "piclet_data": "{ /* JSON string of variation data */ }",
  "username": "player456",
  "object_name": "pillow"
}

Success Response:

{
  "success": true,
  "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. Increment Scan Count

Endpoint: /increment_scan_count Purpose: Track how many times a Piclet has been discovered Method: Gradio function call

Input Parameters:

{
  "piclet_id": "pillow_canonical",
  "object_name": "pillow"
}

Success Response:

{
  "success": true,
  "scanCount": 43
}

5. Get Recent Activity

Endpoint: /get_recent_activity Purpose: Get global discovery feed Method: Gradio function call

Input Parameters:

{
  "limit": 20
}

Response:

{
  "success": true,
  "activities": [
    {
      "type": "discovery",
      "objectName": "pillow",
      "typeId": "pillow_canonical",
      "discoveredBy": "user123",
      "discoveredAt": "2024-07-26T10:30:00",
      "scanCount": 42
    },
    {
      "type": "variation",
      "objectName": "pillow",
      "typeId": "pillow_001",
      "attributes": ["velvet", "blue"],
      "discoveredBy": "user456",
      "discoveredAt": "2024-07-26T11:00:00",
      "scanCount": 5
    }
  ]
}

6. Get Leaderboard

Endpoint: /get_leaderboard Purpose: Get top discoverers by rarity score Method: Gradio function call

Input Parameters:

{
  "limit": 10
}

Response:

{
  "success": true,
  "leaderboard": [
    {
      "rank": 1,
      "username": "explorer123",
      "totalFinds": 156,
      "uniqueFinds": 45,
      "rarityScore": 2340
    },
    {
      "rank": 2,
      "username": "hunter456",
      "totalFinds": 134,
      "uniqueFinds": 38,
      "rarityScore": 1890
    }
  ]
}

7. Get User Profile

Endpoint: /get_user_profile Purpose: Get individual user's discovery statistics Method: Gradio function call

Input Parameters:

{
  "username": "player123"
}

Response:

{
  "success": true,
  "profile": {
    "username": "player123",
    "joinedAt": "2024-07-01T10:00:00",
    "discoveries": ["pillow_canonical", "chair_002", "lamp_canonical"],
    "uniqueFinds": 2,
    "totalFinds": 3,
    "rarityScore": 250
  }
}

Object Normalization Rules

The server normalizes object names for consistent storage:

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

Examples:

• "The Blue Pillow" → pillow
• "wooden chairs" → wooden_chair
• "A pair of glasses" → pair_of_glass

Rarity Tiers

Based on scan count:

• Legendary: ≤ 5 scans
• Epic: 6-20 scans
• Rare: 21-50 scans
• Uncommon: 51-100 scans
• Common: > 100 scans

Scoring System

• Canonical Discovery: +100 rarity points
• Variation Discovery: +50 rarity points
• Scan Bonus: Additional points based on rarity tier

Error Handling

All endpoints return consistent error structures:

{
  "success": false,
  "error": "Description of what went wrong"
}

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:

• Check CLAUDE.md for implementation details
• Review example code in app.py
• Open an issue in the repository