cool stuff

.gitignore

@@ -0,0 +1 @@
+*.pyc

CLAUDE.md

@@ -4,9 +4,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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.
+This is a Hugging Face Space that serves as the **complete backend** for the Piclets Discovery game. It orchestrates AI services, handles Piclet generation, and manages 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").
+**Core Concept**: Each real-world object has ONE canonical Piclet! Players scan objects with photos, and the server generates Pokemon-style creatures using AI, tracking canonical discoveries and variations (e.g., "velvet pillow" is a variation of the canonical "pillow").
+
+**Architecture Philosophy**: The server handles ALL AI orchestration securely. The frontend is a pure UI that makes a single API call. This prevents client-side manipulation and ensures fair play.
 
 ## Architecture
 
@@ -66,37 +68,85 @@ Examples:
 
 ## API Endpoints
 
-### Discovery Endpoints
+The frontend only needs these **5 public endpoints**:
+
+### 1. **generate_piclet** (Scanner)
+Complete Piclet generation workflow - the main endpoint.
+
+- **Input**:
+  - `image`: User's photo (File)
+  - `hf_token`: User's HuggingFace OAuth token (string)
+- **Process**:
+  1. Verifies `hf_token` → gets user info
+  2. Uses token to connect to **JoyCaption** → generates detailed image description
+  3. Uses token to call **GPT-OSS-120B** → generates Pokemon concept (object, variation, stats, description)
+  4. Parses concept to extract structured data
+  5. Uses token to call **Flux-Schnell** → generates Piclet image
+  6. Checks dataset for canonical/variation match
+  7. Saves to dataset with user attribution
+  8. Updates user profile (discoveries, rarity score)
+- **Returns**:
+  ```json
+  {
+    "success": true,
+    "piclet": {/* complete Piclet data */},
+    "discoveryStatus": "new" | "variation" | "existing",
+    "canonicalId": "pillow_canonical",
+    "message": "Congratulations! You discovered the first pillow Piclet!"
+  }
+  ```
+- **Security**: Uses user's token to call AI services, consuming THEIR GPU quota (not the server's)
+
+### 2. **get_user_piclets** (User Collection)
+Get user's discovered Piclets and stats.
+
+- **Input**: `hf_token` (string)
+- **Returns**:
+  ```json
+  {
+    "success": true,
+    "piclets": [{/* list of discoveries */}],
+    "stats": {
+      "username": "...",
+      "totalFinds": 42,
+      "uniqueFinds": 15,
+      "rarityScore": 1250
+    }
+  }
+  ```
 
-1. **search_piclet**: Find canonical or variation Piclets
-   - Input: `object_name`, `attributes[]`
-   - Returns: `status` (new/existing/variation), `piclet` data
+### 3. **get_object_details** (Object Data)
+Get complete object information (canonical + all variations).
 
-2. **create_canonical**: Register first discovery of an object
-   - Input: `object_name`, `piclet_data`, `username`
-   - Returns: Created canonical Piclet
+- **Input**: `object_name` (string, e.g., "pillow", "macbook")
+- **Returns**:
+  ```json
+  {
+    "success": true,
+    "objectName": "pillow",
+    "canonical": {/* canonical data */},
+    "variations": [{/* variation 1 */}, {/* variation 2 */}],
+    "totalScans": 157,
+    "variationCount": 8
+  }
+  ```
 
-3. **create_variation**: Add variation to existing canonical
-   - Input: `canonical_id`, `attributes[]`, `piclet_data`, `username`, `object_name`
-   - Returns: Created variation
+### 4. **get_recent_activity** (Activity Feed)
+Recent discoveries across all users.
 
-4. **increment_scan_count**: Track popularity
-   - Input: `piclet_id`, `object_name`
-   - Returns: Updated scan count
+- **Input**: `limit` (int, default 20)
+- **Returns**: List of recent discoveries with timestamps
 
-### Social Endpoints
+### 5. **get_leaderboard** (Top Users)
+Top discoverers by rarity score.
 
-5. **get_recent_activity**: Global discovery feed
-   - Input: `limit` (default 20)
-   - Returns: Recent discoveries with metadata
+- **Input**: `limit` (int, default 10)
+- **Returns**: Ranked users with stats
 
-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
+**Internal Functions** (not exposed to frontend):
+- `search_piclet()`, `create_canonical()`, `create_variation()`, `increment_scan_count()` - Used internally by `generate_piclet()`
 
 ## Rarity System
 
@@ -128,26 +178,49 @@ Rarity scoring for leaderboard:
 
 ## Integration with Frontend
 
-The frontend (`../piclets/`) connects using Gradio Client:
+The frontend (`../piclets/`) uses these **5 simple API calls**:
 
 ```javascript
-// Frontend connection
+// Connect to server
 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"]
+// 1. Scanner - Generate complete Piclet (ONE CALL - server does everything!)
+const scanResult = await client.predict("/generate_piclet", {
+  image: imageFile,
+  hf_token: userToken
+});
+const { success, piclet, discoveryStatus, message } = scanResult.data[0];
+
+// 2. User Collection - Get user's Piclets + stats
+const myPiclets = await client.predict("/get_user_piclets", {
+  hf_token: userToken
+});
+const { piclets, stats } = myPiclets.data[0];
+
+// 3. Object Details - Get object info (canonical + variations)
+const objectInfo = await client.predict("/get_object_details", {
+  object_name: "pillow"
 });
+const { canonical, variations, totalScans } = objectInfo.data[0];
 
-// Create canonical
-const created = await client.predict("/create_canonical", {
-  object_name: "pillow",
-  piclet_data: JSON.stringify(picletData),
-  username: "player123"
+// 4. Activity Feed - Get recent discoveries
+const activity = await client.predict("/get_recent_activity", {
+  limit: 20
+});
+
+// 5. Leaderboard - Get top users
+const leaders = await client.predict("/get_leaderboard", {
+  limit: 10
 });
 ```
 
+**Why This Design?**
+- **Clean API**: Only 5 endpoints, each with a clear purpose
+- **Security**: All AI orchestration happens server-side (can't be manipulated)
+- **Simplicity**: Frontend is pure UI, no complex orchestration logic
+- **Fairness**: Uses user's GPU quota, not server's
+- **Reliability**: Server handles retries and error recovery
+
 ## Development
 
 ### Local Testing
@@ -164,12 +237,35 @@ git add -A && git commit -m "Update" && git push
 ```
 
 ### Environment Variables
-- `HF_TOKEN`: **Required** - HuggingFace write token (set in Space Secrets)
-- `ADMIN_PASSWORD`: **Required** - Password for web UI access (set in Space Secrets)
+- `HF_TOKEN`: **Required** - HuggingFace write token for dataset operations (set in Space Secrets)
+- `ADMIN_PASSWORD`: Optional - Password for web UI access (set in Space Secrets)
 - `DATASET_REPO`: Target dataset (default: "Fraser/piclets")
 
+Note: Users' `hf_token` (passed in API calls) is separate from server's `HF_TOKEN` (for dataset writes).
+
 ## Key Implementation Details
 
+### AI Service Integration
+The server uses `gradio_client` to call external AI services with the user's token:
+
+- **JoyCaption** (`fancyfeast/joy-caption-alpha-two`): Detailed image captioning with brand/model recognition
+- **GPT-OSS-120B** (`amd/gpt-oss-120b-chatbot`): Concept generation and parsing
+- **Flux-Schnell** (`black-forest-labs/FLUX.1-schnell`): Anime-style Piclet image generation
+
+Each service is called with the user's `hf_token`, consuming their GPU quota.
+
+### Concept Parsing
+GPT-OSS generates structured markdown with sections:
+- Canonical Object (specific brand/model, not generic)
+- Variation (distinctive attribute or "canonical")
+- Object Rarity (determines tier)
+- Monster Name, Type, Stats
+- Physical Stats (height, weight)
+- Personality, Description
+- Monster Image Prompt
+
+The parser uses regex to extract each section and clean the data.
+
 ### Variation Matching
 - Uses set intersection to find attribute overlap
 - 50% match threshold for variations
@@ -181,23 +277,30 @@ git add -A && git commit -m "Update" && git push
 - Temporary files for uploads
 
 ### Error Handling
+- Token verification before any operations
 - Graceful fallbacks for missing data
 - Default user profiles for new users
-- Try-catch blocks around all dataset operations
+- Try-catch blocks around all operations
+- Detailed logging for debugging
 
 ## 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
+1. **Background Removal**: Add server-side background removal (currently done on frontend)
+2. **Activity Log**: Separate timeline file for better performance
+3. **Image Storage**: Store Piclet images directly in dataset (currently stores URLs)
+4. **Badges/Achievements**: Track discovery milestones
+5. **Trading System**: Allow users to trade variations
+6. **Seasonal Events**: Time-limited discoveries
+7. **Rate Limiting**: Per-user rate limits to prevent abuse
+8. **Caching**: Cache AI responses for identical images
 
 ## 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
+- **Token Verification**: All operations verify HF OAuth tokens via `https://huggingface.co/oauth/userinfo`
+- **User Attribution**: Discoveries tracked by stable HF `sub` (user ID), not username
+- **Fair GPU Usage**: Users consume their own GPU quota, not server's
+- **Public Data**: All discovery data is public by design (embracing open discovery)
+- **No Client Manipulation**: AI orchestration happens server-side only
+- **Input Validation**: File uploads and token formats validated
+- **No Sensitive Data**: No passwords or private info stored
+- **Future**: Rate limiting per user to prevent abuse

app.py

@@ -1,4 +1,5 @@
 import gradio as gr
+from gradio_client import Client
 import json
 import os
 import re
@@ -243,6 +244,279 @@ class PicletDiscoveryService:
             print(f"Failed to update global stats: {e}")
             return {}
 
+class PicletGeneratorService:
+    """
+    Orchestrates Piclet generation by calling external AI services
+    Uses user's hf_token to consume their GPU quota
+    """
+
+    # Space endpoints
+    JOY_CAPTION_SPACE = "fancyfeast/joy-caption-alpha-two"
+    GPT_OSS_SPACE = "amd/gpt-oss-120b-chatbot"
+    FLUX_SPACE = "black-forest-labs/FLUX.1-schnell"
+
+    @staticmethod
+    async def generate_enhanced_caption(image_path: str, hf_token: str) -> str:
+        """Generate detailed image description using JoyCaption"""
+        try:
+            print(f"Connecting to JoyCaption space with user token...")
+            client = await Client.connect(
+                PicletGeneratorService.JOY_CAPTION_SPACE,
+                hf_token=hf_token
+            )
+
+            print(f"Generating caption for image...")
+            result = await client.predict(
+                image=image_path,
+                caption_type="Descriptive",
+                caption_length="medium-length",
+                extra_options=[],
+                name_input="",
+                custom_prompt="Describe this image in detail, identifying any recognizable objects, brands, logos, or specific models. Be specific about product names and types.",
+                api_name="/stream_chat"
+            )
+
+            # JoyCaption returns tuple: (image, caption_text)
+            caption = result[1] if isinstance(result, (list, tuple)) and len(result) > 1 else str(result)
+            print(f"Caption generated: {caption[:100]}...")
+            return caption
+
+        except Exception as e:
+            print(f"Failed to generate caption: {e}")
+            raise Exception(f"Caption generation failed: {str(e)}")
+
+    @staticmethod
+    async def generate_text_with_gpt(prompt: str, hf_token: str) -> str:
+        """Generate text using GPT-OSS-120B"""
+        try:
+            print(f"Connecting to GPT-OSS space...")
+            client = await Client.connect(
+                PicletGeneratorService.GPT_OSS_SPACE,
+                hf_token=hf_token
+            )
+
+            print(f"Generating text...")
+            result = await client.predict(
+                message=prompt,
+                history=[],
+                system_prompt="You are a helpful assistant that creates Pokemon-style monster concepts based on real-world objects.",
+                temperature=0.7,
+                api_name="/chat"
+            )
+
+            # Extract response text (GPT-OSS formats with Analysis and Response)
+            response_text = result[0] if isinstance(result, (list, tuple)) else str(result)
+
+            # Try to extract Response section
+            response_match = re.search(r'\*\*💬 Response:\*\*\s*\n\n([\s\S]*)', response_text)
+            if response_match:
+                return response_match.group(1).strip()
+
+            # Fallback: extract after "assistantfinal"
+            final_match = re.search(r'assistantfinal\s*([\s\S]*)', response_text)
+            if final_match:
+                return final_match.group(1).strip()
+
+            return response_text
+
+        except Exception as e:
+            print(f"Failed to generate text: {e}")
+            raise Exception(f"Text generation failed: {str(e)}")
+
+    @staticmethod
+    async def generate_piclet_concept(caption: str, hf_token: str) -> dict:
+        """
+        Generate complete Piclet concept from image caption
+        Returns parsed concept with object name, variation, stats, etc.
+        """
+        concept_prompt = f"""You are analyzing an image to create a Pokemon-style creature. Here's the image description:
+
+"{caption}"
+
+Your task:
+1. Identify the PRIMARY PHYSICAL OBJECT with SPECIFICITY (e.g., "macbook" not "laptop", "eiffel tower" not "tower", "iphone" not "phone", "starbucks mug" not "mug")
+2. Determine if there's a meaningful VARIATION (e.g., "silver", "pro", "night", "gaming", "vintage")
+3. Assess rarity based on uniqueness
+4. Create a complete Pokemon-style monster concept
+
+Format your response EXACTLY as follows:
+```md
+# Canonical Object
+{{Specific object name: "macbook", "eiffel tower", "iphone", "tesla", "le creuset mug", "nintendo switch"}}
+{{NOT generic terms like: "laptop", "tower", "phone", "car", "mug", "console"}}
+{{Include brand/model/landmark name when identifiable}}
+
+# Variation
+{{OPTIONAL: one distinctive attribute like "silver", "pro", "night", "gaming", OR use "canonical" if this is the standard/default version with no special variation}}
+
+# Object Rarity
+{{common, uncommon, rare, epic, or legendary based on object uniqueness}}
+
+# Monster Name
+{{Creative 8-11 letter name based on the SPECIFIC object, e.g., "Macbyte" for MacBook, "Towerfell" for Eiffel Tower}}
+
+# Primary Type
+{{beast, bug, aquatic, flora, mineral, space, machina, structure, culture, or cuisine}}
+
+# Physical Stats
+Height: {{e.g., "1.2m" or "3'5\\""}}
+Weight: {{e.g., "15kg" or "33 lbs"}}
+
+# Personality
+{{1-2 sentences describing personality traits}}
+
+# Monster Description
+{{2-3 paragraphs describing how the SPECIFIC object's features translate into monster features. Reference the actual object by name. This is the creature's bio.}}
+
+# Monster Image Prompt
+{{Concise visual description for anime-style image generation focusing on colors, shapes, and key features inspired by the specific object}}
+```
+
+CRITICAL RULES:
+- Canonical Object MUST be SPECIFIC: "macbook" not "laptop", "big ben" not "clock tower", "coca cola" not "soda"
+- If you can identify a brand, model, or proper name from the description, USE IT
+- Variation should be meaningful and distinctive (material, style, color, context, or model variant)
+- Monster Description must describe the CREATURE with references to the specific object's features
+- Primary Type must match the object category (machina for electronics, structure for buildings, etc.)"""
+
+        response_text = await PicletGeneratorService.generate_text_with_gpt(concept_prompt, hf_token)
+
+        # Parse the concept
+        return PicletGeneratorService.parse_concept(response_text)
+
+    @staticmethod
+    def parse_concept(concept_text: str) -> dict:
+        """Parse structured concept text into dict"""
+        # Remove code block markers if present
+        if '```' in concept_text:
+            code_block_match = re.search(r'```(?:md|markdown)?\s*\n([\s\S]*?)```', concept_text)
+            if code_block_match:
+                concept_text = code_block_match.group(1).strip()
+
+        def extract_section(text: str, section: str) -> str:
+            """Extract content of a markdown section"""
+            pattern = rf'\*{{0,2}}#\s*{re.escape(section)}\s*\*{{0,2}}\s*\n([\s\S]*?)(?=^\*{{0,2}}#|$)'
+            match = re.search(pattern, text, re.MULTILINE)
+            if match:
+                content = match.group(1).strip()
+                # Remove curly braces and quotes that GPT sometimes adds
+                content = re.sub(r'^[{"]|["}]$', '', content)
+                content = re.sub(r'^.*:\s*["\']|["\']$', '', content)
+                return content.strip()
+            return ''
+
+        # Extract all sections
+        object_name = extract_section(concept_text, 'Canonical Object').lower()
+        variation_text = extract_section(concept_text, 'Variation')
+        rarity_text = extract_section(concept_text, 'Object Rarity').lower()
+        monster_name = extract_section(concept_text, 'Monster Name')
+        primary_type = extract_section(concept_text, 'Primary Type').lower()
+        description = extract_section(concept_text, 'Monster Description')
+        image_prompt = extract_section(concept_text, 'Monster Image Prompt')
+
+        # Parse physical stats
+        physical_stats_text = extract_section(concept_text, 'Physical Stats')
+        height_match = re.search(r'Height:\s*(.+)', physical_stats_text, re.IGNORECASE)
+        weight_match = re.search(r'Weight:\s*(.+)', physical_stats_text, re.IGNORECASE)
+        height = height_match.group(1).strip() if height_match else None
+        weight = weight_match.group(1).strip() if weight_match else None
+
+        personality = extract_section(concept_text, 'Personality')
+
+        # Clean monster name
+        if monster_name:
+            monster_name = re.sub(r'\*+', '', monster_name)  # Remove asterisks
+            if ',' in monster_name:
+                monster_name = monster_name.split(',')[0]
+            if len(monster_name) > 12:
+                monster_name = monster_name[:12]
+
+        # Parse variation
+        attributes = []
+        if variation_text and variation_text.lower() not in ['none', 'canonical', '']:
+            attributes = [variation_text.lower()]
+
+        # Map rarity to tier
+        tier = 'medium'
+        if 'common' in rarity_text:
+            tier = 'low'
+        elif 'uncommon' in rarity_text:
+            tier = 'medium'
+        elif 'rare' in rarity_text and 'epic' not in rarity_text:
+            tier = 'high'
+        elif 'legendary' in rarity_text or 'epic' in rarity_text or 'mythical' in rarity_text:
+            tier = 'legendary'
+
+        return {
+            'objectName': object_name,
+            'attributes': attributes,
+            'concept': concept_text,
+            'stats': {
+                'name': monster_name or 'Unknown',
+                'description': description,
+                'tier': tier,
+                'primaryType': primary_type or 'beast',
+                'height': height,
+                'weight': weight,
+                'personality': personality
+            },
+            'imagePrompt': image_prompt
+        }
+
+    @staticmethod
+    async def generate_piclet_image(image_prompt: str, tier: str, hf_token: str) -> dict:
+        """Generate Piclet image using Flux"""
+        try:
+            print(f"Connecting to Flux space...")
+            client = await Client.connect(
+                PicletGeneratorService.FLUX_SPACE,
+                hf_token=hf_token
+            )
+
+            tier_descriptions = {
+                'low': 'simple and iconic design',
+                'medium': 'detailed and well-crafted design',
+                'high': 'highly detailed and impressive design with special effects',
+                'legendary': 'highly detailed and majestic design with dramatic lighting and aura effects'
+            }
+
+            full_prompt = f"{image_prompt}\nNow generate an Pokémon Anime image of the monster in an idle pose with a plain dark-grey background. This is a {tier} tier monster with a {tier_descriptions.get(tier, tier_descriptions['medium'])}. The monster should not be attacking or in motion. The full monster must be visible within the frame."
+
+            print(f"Generating image with prompt: {full_prompt[:100]}...")
+            result = await client.predict(
+                prompt=full_prompt,
+                seed=0,
+                randomize_seed=True,
+                width=1024,
+                height=1024,
+                num_inference_steps=4,
+                api_name="/infer"
+            )
+
+            # Extract image URL and seed
+            image_data = result[0] if isinstance(result, (list, tuple)) else result
+            seed = result[1] if isinstance(result, (list, tuple)) and len(result) > 1 else 0
+
+            # Handle different return formats
+            image_url = None
+            if isinstance(image_data, str):
+                image_url = image_data
+            elif isinstance(image_data, dict):
+                image_url = image_data.get('url') or image_data.get('path')
+
+            if not image_url:
+                raise Exception("Failed to extract image URL from Flux response")
+
+            return {
+                'imageUrl': image_url,
+                'seed': seed,
+                'prompt': image_prompt
+            }
+
+        except Exception as e:
+            print(f"Failed to generate image: {e}")
+            raise Exception(f"Image generation failed: {str(e)}")
+
 # API Endpoints
 
 def search_piclet(object_name: str, attributes: List[str]) -> dict:
@@ -502,6 +776,357 @@ def increment_scan_count(piclet_id: str, object_name: str) -> dict:
             "error": str(e)
         }
 
+async def generate_piclet(image, hf_token: str) -> dict:
+    """
+    Complete Piclet generation workflow - single endpoint
+    Takes user's image and hf_token, returns generated Piclet with discovery status
+
+    Args:
+        image: Uploaded image file (Gradio file input)
+        hf_token: User's HuggingFace OAuth token
+
+    Returns:
+        {
+            "success": bool,
+            "piclet": {complete piclet data},
+            "discoveryStatus": "new" | "variation" | "existing",
+            "canonicalId": str (if variation/existing),
+            "message": str
+        }
+    """
+    try:
+        # Validate token and get user info
+        user_info = verify_hf_token(hf_token)
+        if not user_info:
+            return {
+                "success": False,
+                "error": "Invalid HuggingFace token"
+            }
+
+        print(f"Generating Piclet for user: {user_info.get('preferred_username', 'unknown')}")
+
+        # Get user profile (creates if doesn't exist)
+        user_profile = PicletDiscoveryService.get_or_create_user_profile(user_info)
+
+        # Extract image path from Gradio file input
+        image_path = image if isinstance(image, str) else image.name if hasattr(image, 'name') else str(image)
+
+        # Step 1: Generate caption
+        print("Step 1/5: Generating image caption...")
+        caption = await PicletGeneratorService.generate_enhanced_caption(image_path, hf_token)
+
+        # Step 2: Generate concept
+        print("Step 2/5: Generating Piclet concept...")
+        concept_data = await PicletGeneratorService.generate_piclet_concept(caption, hf_token)
+
+        object_name = concept_data['objectName']
+        attributes = concept_data['attributes']
+        stats = concept_data['stats']
+        image_prompt = concept_data['imagePrompt']
+        concept_text = concept_data['concept']
+
+        # Step 3: Generate image
+        print("Step 3/5: Generating Piclet image...")
+        image_result = await PicletGeneratorService.generate_piclet_image(
+            image_prompt,
+            stats['tier'],
+            hf_token
+        )
+
+        # Step 4: Check for canonical/variation
+        print("Step 4/5: Checking for existing canonical...")
+        existing_data = PicletDiscoveryService.load_piclet_data(object_name)
+
+        discovery_status = 'new'
+        canonical_id = None
+        scan_count = 1
+
+        if existing_data:
+            # Check if this is an exact canonical match (no attributes)
+            if not attributes or len(attributes) == 0:
+                discovery_status = 'existing'
+                canonical_id = existing_data['canonical']['typeId']
+                # Increment scan count
+                existing_data['canonical']['scanCount'] = existing_data['canonical'].get('scanCount', 0) + 1
+                scan_count = existing_data['canonical']['scanCount']
+                PicletDiscoveryService.save_piclet_data(object_name, existing_data)
+            else:
+                # Check for matching variation
+                variations = existing_data.get('variations', [])
+                matched_variation = None
+
+                for variation in variations:
+                    var_attrs = set(variation.get('attributes', []))
+                    search_attrs = set(attributes)
+                    overlap = len(var_attrs.intersection(search_attrs))
+
+                    if overlap >= len(search_attrs) * 0.5:
+                        matched_variation = variation
+                        discovery_status = 'existing'
+                        canonical_id = existing_data['canonical']['typeId']
+                        # Increment variation scan count
+                        variation['scanCount'] = variation.get('scanCount', 0) + 1
+                        scan_count = variation['scanCount']
+                        PicletDiscoveryService.save_piclet_data(object_name, existing_data)
+                        break
+
+                if not matched_variation:
+                    discovery_status = 'variation'
+                    canonical_id = existing_data['canonical']['typeId']
+
+        # Step 5: Save new discovery if needed
+        print("Step 5/5: Saving to dataset...")
+        if discovery_status == 'new':
+            # Create new canonical
+            type_id = f"{PicletDiscoveryService.normalize_object_name(object_name)}_canonical"
+            canonical_data = {
+                "canonical": {
+                    "objectName": object_name,
+                    "typeId": type_id,
+                    "discoveredBy": user_info['preferred_username'],
+                    "discovererSub": user_info['sub'],
+                    "discovererUsername": user_info['preferred_username'],
+                    "discovererName": user_info.get('name'),
+                    "discovererPicture": user_info.get('picture'),
+                    "discoveredAt": datetime.now().isoformat(),
+                    "scanCount": scan_count,
+                    "picletData": {
+                        "typeId": type_id,
+                        "nickname": stats['name'],
+                        "stats": stats,
+                        "imageUrl": image_result['imageUrl'],
+                        "imageCaption": caption,
+                        "concept": concept_text,
+                        "imagePrompt": image_prompt,
+                        "createdAt": datetime.now().isoformat()
+                    }
+                },
+                "variations": []
+            }
+            canonical_id = type_id
+
+            PicletDiscoveryService.save_piclet_data(object_name, canonical_data)
+
+            # Update user profile
+            user_profile["discoveries"].append(type_id)
+            user_profile["uniqueFinds"] = user_profile.get("uniqueFinds", 0) + 1
+            user_profile["totalFinds"] = user_profile.get("totalFinds", 0) + 1
+            user_profile["rarityScore"] = user_profile.get("rarityScore", 0) + 100
+            PicletDiscoveryService.save_user_data(user_info['sub'], user_profile)
+
+        elif discovery_status == 'variation':
+            # Create new variation
+            existing_data = PicletDiscoveryService.load_piclet_data(object_name)
+            variation_id = f"{PicletDiscoveryService.normalize_object_name(object_name)}_{len(existing_data['variations']) + 1:03d}"
+
+            variation_data = {
+                "typeId": variation_id,
+                "attributes": attributes,
+                "discoveredBy": user_info['preferred_username'],
+                "discovererSub": user_info['sub'],
+                "discovererUsername": user_info['preferred_username'],
+                "discovererName": user_info.get('name'),
+                "discovererPicture": user_info.get('picture'),
+                "discoveredAt": datetime.now().isoformat(),
+                "scanCount": scan_count,
+                "picletData": {
+                    "typeId": variation_id,
+                    "nickname": stats['name'],
+                    "stats": stats,
+                    "imageUrl": image_result['imageUrl'],
+                    "imageCaption": caption,
+                    "concept": concept_text,
+                    "imagePrompt": image_prompt,
+                    "createdAt": datetime.now().isoformat()
+                }
+            }
+
+            existing_data['variations'].append(variation_data)
+            PicletDiscoveryService.save_piclet_data(object_name, existing_data)
+
+            # Update user profile
+            user_profile["discoveries"].append(variation_id)
+            user_profile["totalFinds"] = user_profile.get("totalFinds", 0) + 1
+            user_profile["rarityScore"] = user_profile.get("rarityScore", 0) + 50
+            PicletDiscoveryService.save_user_data(user_info['sub'], user_profile)
+
+        # Build complete response
+        piclet_data = {
+            "typeId": canonical_id,
+            "nickname": stats['name'],
+            "stats": stats,
+            "imageUrl": image_result['imageUrl'],
+            "imageCaption": caption,
+            "concept": concept_text,
+            "imagePrompt": image_prompt,
+            "objectName": object_name,
+            "attributes": attributes,
+            "discoveryStatus": discovery_status,
+            "scanCount": scan_count,
+            "createdAt": datetime.now().isoformat()
+        }
+
+        messages = {
+            'new': f"Congratulations! You discovered the first {object_name} Piclet!",
+            'variation': f"You found a new variation of {object_name}!",
+            'existing': f"You encountered a known {object_name} Piclet."
+        }
+
+        return {
+            "success": True,
+            "piclet": piclet_data,
+            "discoveryStatus": discovery_status,
+            "canonicalId": canonical_id,
+            "message": messages.get(discovery_status, "Piclet generated!")
+        }
+
+    except Exception as e:
+        print(f"Failed to generate Piclet: {e}")
+        import traceback
+        traceback.print_exc()
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+def get_object_details(object_name: str) -> dict:
+    """
+    Get complete details for an object (canonical + all variations)
+
+    Args:
+        object_name: The object name (e.g., "pillow", "macbook")
+
+    Returns:
+        {
+            "success": bool,
+            "objectName": str,
+            "canonical": {canonical data},
+            "variations": [list of variations],
+            "totalScans": int
+        }
+    """
+    try:
+        # Load the object data
+        piclet_data = PicletDiscoveryService.load_piclet_data(object_name)
+
+        if not piclet_data:
+            return {
+                "success": False,
+                "error": f"No piclet found for object '{object_name}'",
+                "objectName": object_name
+            }
+
+        # Calculate total scans across canonical and variations
+        total_scans = piclet_data['canonical'].get('scanCount', 0)
+        for variation in piclet_data.get('variations', []):
+            total_scans += variation.get('scanCount', 0)
+
+        return {
+            "success": True,
+            "objectName": object_name,
+            "canonical": piclet_data['canonical'],
+            "variations": piclet_data.get('variations', []),
+            "totalScans": total_scans,
+            "variationCount": len(piclet_data.get('variations', []))
+        }
+
+    except Exception as e:
+        print(f"Failed to get object details: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "objectName": object_name
+        }
+
+def get_user_piclets(hf_token: str) -> dict:
+    """
+    Get all Piclets discovered by a specific user
+
+    Args:
+        hf_token: User's HuggingFace OAuth token
+
+    Returns:
+        {
+            "success": bool,
+            "piclets": [list of piclet discoveries],
+            "stats": {user stats}
+        }
+    """
+    try:
+        # Verify token and get user info
+        user_info = verify_hf_token(hf_token)
+        if not user_info:
+            return {
+                "success": False,
+                "error": "Invalid HuggingFace token",
+                "piclets": []
+            }
+
+        # Load user profile
+        user_profile = PicletDiscoveryService.load_user_data(user_info['sub'])
+
+        # Get list of discoveries
+        discoveries = user_profile.get('discoveries', [])
+        piclets = []
+
+        # Load each discovered piclet
+        for type_id in discoveries:
+            # Extract object name from type_id (e.g., "pillow_canonical" -> "pillow")
+            object_name = type_id.rsplit('_', 1)[0]
+
+            # Load the piclet data
+            piclet_data = PicletDiscoveryService.load_piclet_data(object_name)
+            if piclet_data:
+                # Check if it's canonical or variation
+                if piclet_data['canonical']['typeId'] == type_id:
+                    piclets.append({
+                        'type': 'canonical',
+                        'typeId': type_id,
+                        'objectName': object_name,
+                        'discoveredAt': piclet_data['canonical']['discoveredAt'],
+                        'scanCount': piclet_data['canonical'].get('scanCount', 1),
+                        'picletData': piclet_data['canonical'].get('picletData', {})
+                    })
+                else:
+                    # Find matching variation
+                    for variation in piclet_data.get('variations', []):
+                        if variation['typeId'] == type_id:
+                            piclets.append({
+                                'type': 'variation',
+                                'typeId': type_id,
+                                'objectName': object_name,
+                                'attributes': variation.get('attributes', []),
+                                'discoveredAt': variation['discoveredAt'],
+                                'scanCount': variation.get('scanCount', 1),
+                                'picletData': variation.get('picletData', {})
+                            })
+                            break
+
+        # Sort by discovery date (most recent first)
+        piclets.sort(key=lambda x: x.get('discoveredAt', ''), reverse=True)
+
+        return {
+            "success": True,
+            "piclets": piclets,
+            "stats": {
+                "username": user_info.get('preferred_username'),
+                "name": user_info.get('name'),
+                "picture": user_info.get('picture'),
+                "totalFinds": user_profile.get('totalFinds', 0),
+                "uniqueFinds": user_profile.get('uniqueFinds', 0),
+                "rarityScore": user_profile.get('rarityScore', 0),
+                "joinedAt": user_profile.get('joinedAt')
+            }
+        }
+
+    except Exception as e:
+        print(f"Failed to get user piclets: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "piclets": []
+        }
+
 def get_recent_activity(limit: int = 20) -> dict:
     """
     Get recent discoveries across all users
@@ -617,23 +1242,6 @@ def get_leaderboard(limit: int = 10) -> dict:
             "leaderboard": []
         }
 
-def get_user_profile(username: str) -> dict:
-    """
-    Get user's discovery profile
-    """
-    try:
-        user_data = PicletDiscoveryService.load_user_data(username)
-        return {
-            "success": True,
-            "profile": user_data
-        }
-    except Exception as e:
-        return {
-            "success": False,
-            "error": str(e),
-            "profile": None
-        }
-
 # Create Gradio interface
 with gr.Blocks(title="Piclets Discovery Server") as app:
     gr.Markdown("""
@@ -642,58 +1250,63 @@ with gr.Blocks(title="Piclets Discovery Server") as app:
     Backend service for the Piclets discovery game. Each real-world object has ONE canonical Piclet!
     """)
 
-    with gr.Tab("Search Piclet"):
+    with gr.Tab("Generate Piclet"):
+        gr.Markdown("""
+        ## 🎮 Complete Piclet Generator
+        Upload an image and provide your HuggingFace token to generate a complete Piclet.
+        This endpoint handles the entire workflow: captioning, concept generation, image creation, and dataset storage.
+        """)
         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")
+                gen_image = gr.Image(label="Upload Image", type="filepath")
+                gen_token = gr.Textbox(label="HuggingFace Token", placeholder="hf_...", type="password")
+                gen_btn = gr.Button("Generate Piclet", variant="primary")
             with gr.Column():
-                search_result = gr.JSON(label="Search Result")
+                gen_result = gr.JSON(label="Generated Piclet 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
+        gen_btn.click(
+            fn=generate_piclet,
+            inputs=[gen_image, gen_token],
+            outputs=gen_result
         )
 
-    with gr.Tab("Create Canonical"):
+    with gr.Tab("My Piclets"):
+        gr.Markdown("""
+        ## 📚 Your Discovery Collection
+        View all Piclets you've discovered (includes your stats).
+        """)
         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")
+                my_token = gr.Textbox(label="HuggingFace Token", placeholder="hf_...", type="password")
+                my_btn = gr.Button("Get My Piclets", variant="primary")
             with gr.Column():
-                canonical_result = gr.JSON(label="Creation Result")
+                my_result = gr.JSON(label="My Piclets")
 
-        canonical_btn.click(
-            fn=create_canonical,
-            inputs=[canonical_object, canonical_data, canonical_user],
-            outputs=canonical_result
+        my_btn.click(
+            fn=get_user_piclets,
+            inputs=my_token,
+            outputs=my_result
         )
 
-    with gr.Tab("Create Variation"):
+    with gr.Tab("Object Details"):
+        gr.Markdown("""
+        ## 🔍 View Object Details
+        Get complete information about an object (canonical + all variations).
+        """)
         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")
+                obj_name = gr.Textbox(label="Object Name", placeholder="e.g., pillow, macbook")
+                obj_btn = gr.Button("Get Details", 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
+                obj_result = gr.JSON(label="Object Details")
+
+        obj_btn.click(
+            fn=get_object_details,
+            inputs=obj_name,
+            outputs=obj_result
         )
 
-    with gr.Tab("Activity Feed"):
+    with gr.Tab("Recent Activity"):
         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")
@@ -715,32 +1328,39 @@ with gr.Blocks(title="Piclets Discovery Server") as app:
             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
+    ## 🔌 Public API Endpoints
+
+    All endpoints return JSON responses. The frontend only needs these 5 endpoints:
+
+    ### 1. **generate_piclet** (Scanner)
+    Complete Piclet generation workflow.
+    - Input: `image` (File), `hf_token` (string)
+    - Output: Generated Piclet with discovery status
+
+    ### 2. **get_user_piclets** (User Collection)
+    Get user's discovered Piclets and stats.
+    - Input: `hf_token` (string)
+    - Output: List of Piclets + user stats (total/unique finds, rarity score)
+
+    ### 3. **get_object_details** (Object Data)
+    Get complete object info (canonical + all variations).
+    - Input: `object_name` (string)
+    - Output: Canonical + variations + total scans
 
-    All endpoints accept JSON and return JSON responses.
+    ### 4. **get_recent_activity** (Activity Feed)
+    Recent discoveries across all users.
+    - Input: `limit` (int, default 20)
+    - Output: Recent discoveries with timestamps
 
-    - **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
+    ### 5. **get_leaderboard** (Top Users)
+    Top discoverers by rarity score.
+    - Input: `limit` (int, default 10)
+    - Output: Ranked users with stats
 
-    See API_DOCUMENTATION.md for detailed usage.
+    ---
+    *Note: Internal helper functions (search_piclet, create_canonical, etc.) are used by generate_piclet but not exposed to frontend.*
     """)
 
 if __name__ == "__main__":

requirements.txt

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