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
```bash
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
```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. Search Piclet
**Endpoint**: `/search_piclet`
**Purpose**: Search for canonical Piclet or variations
**Method**: Gradio function call

**Input Parameters**:
```json
{
  "object_name": "pillow",
  "attributes": ["velvet", "blue"]
}
```

**Response Types**:

**New Object** (no Piclet exists):
```json
{
  "status": "new",
  "message": "No Piclet found for 'pillow'",
  "piclet": null
}
```

**Existing Canonical** (exact match):
```json
{
  "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"
}
```

**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

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

**Success Response**:
```json
{
  "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**:
```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

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

**Success Response**:
```json
{
  "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**:
```json
{
  "piclet_id": "pillow_canonical",
  "object_name": "pillow"
}
```

**Success Response**:
```json
{
  "success": true,
  "scanCount": 43
}
```

### 5. Get Recent Activity
**Endpoint**: `/get_recent_activity`
**Purpose**: Get global discovery feed
**Method**: Gradio function call

**Input Parameters**:
```json
{
  "limit": 20
}
```

**Response**:
```json
{
  "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**:
```json
{
  "limit": 10
}
```

**Response**:
```json
{
  "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**:
```json
{
  "username": "player123"
}
```

**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
  }
}
```

## 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:

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