basics

API_DOCUMENTATION.md

@@ -0,0 +1,340 @@
+# Piclets 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.
+
+## 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
+
+## API Endpoints
+
+### 1. Save Piclet
+**Endpoint**: `/save_piclet_api`
+**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
+
+**Response Format**:
+```json
+{
+  "success": true,
+  "piclet_id": "uuid-string",
+  "message": "Piclet saved successfully"
+}
+```
+
+**Error Response**:
+```json
+{
+  "success": false,
+  "error": "Error description"
+}
+```
+
+### 2. Get Piclet
+**Endpoint**: `/get_piclet_api`
+**Method**: Gradio function call
+**Purpose**: Retrieve a Piclet by ID
+
+**Input Parameters**:
+- `piclet_id` (string): Unique Piclet identifier
+
+**Response Format**:
+```json
+{
+  "success": true,
+  "piclet": {
+    "id": "uuid-string",
+    "name": "Piclet Name",
+    "description": "Description",
+    "tier": "medium",
+    "primaryType": "space",
+    "baseStats": { ... },
+    "movepool": [ ... ],
+    "created_at": "2024-07-26T10:30:00"
+  }
+}
+```
+
+### 3. List Piclets
+**Endpoint**: `/list_piclets_api`
+**Method**: Gradio function call
+**Purpose**: Get a list of all saved Piclets
+
+**Input Parameters**:
+- `limit` (integer): Maximum number of results (1-100, default: 50)
+
+**Response Format**:
+```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
+}
+```
+
+### 4. Get Piclet Image
+**Endpoint**: `/get_piclet_image_api`
+**Method**: Gradio function call
+**Purpose**: Retrieve the image associated with a Piclet
+
+**Input Parameters**:
+- `piclet_id` (string): Unique Piclet identifier
+
+**Response**: Image file or None if not found
+
+## Required JSON Format for Piclets
+
+When saving a Piclet, the JSON must include these required fields:
+
+```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": [
+    {
+      "name": "Star Strike",
+      "type": "space",
+      "power": 75,
+      "accuracy": 90,
+      "pp": 15,
+      "priority": 0,
+      "flags": [],
+      "effects": [
+        {
+          "type": "damage",
+          "target": "opponent",
+          "amount": "normal"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 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)
+
+#### 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
+
+#### Move Object Format
+```json
+{
+  "name": "Move Name",
+  "type": "attack_type",
+  "power": 75,
+  "accuracy": 90,
+  "pp": 15,
+  "priority": 0,
+  "flags": ["contact", "bite"],
+  "effects": [
+    {
+      "type": "damage",
+      "target": "opponent",
+      "amount": "normal"
+    }
+  ]
+}
+```
+
+## Frontend Integration
+
+### Using Gradio Client (JavaScript)
+
+```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]);
+}
+
+// Get a Piclet
+async function getPiclet(picletId) {
+  const result = await client.predict("/get_piclet_api", [picletId]);
+  return JSON.parse(result.data[0]);
+}
+
+// List Piclets
+async function listPiclets(limit = 20) {
+  const result = await client.predict("/list_piclets_api", [limit]);
+  return JSON.parse(result.data[0]);
+}
+
+// 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
+}
+```
+
+### Example Usage
+
+```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);
+}
+```
+
+## Storage Structure
+
+The server uses a file-based storage system:
+
+```
+data/
+├── piclets/           # Individual Piclet JSON files
+│   ├── uuid1.json
+│   ├── uuid2.json
+│   └── ...
+├── images/            # Piclet images
+│   ├── uuid1.png
+│   ├── uuid2.jpg
+│   └── ...
+└── collections/       # Future: Shared collections
+    └── ...
+```
+
+## Error Handling
+
+All API endpoints return consistent error formats:
+
+```json
+{
+  "success": false,
+  "error": "Descriptive error message"
+}
+```
+
+### 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
+
+## 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

app.py

@@ -0,0 +1,538 @@
+import gradio as gr
+import json
+import os
+import uuid
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple
+import hashlib
+from pathlib import Path
+
+# Create data directories
+DATA_DIR = Path("data")
+PICLETS_DIR = DATA_DIR / "piclets"
+COLLECTIONS_DIR = DATA_DIR / "collections"
+IMAGES_DIR = DATA_DIR / "images"
+
+for dir_path in [DATA_DIR, PICLETS_DIR, COLLECTIONS_DIR, IMAGES_DIR]:
+    dir_path.mkdir(exist_ok=True)
+
+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)
+        """
+        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
+            
+        except Exception as e:
+            return False, f"Error saving Piclet: {str(e)}"
+    
+    @staticmethod
+    def get_piclet(piclet_id: str) -> Tuple[bool, dict]:
+        """
+        Retrieve a Piclet by ID
+        Returns: (success, piclet_data_or_error_message)
+        """
+        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)}"}
+    
+    @staticmethod
+    def list_piclets(limit: int = 50) -> Tuple[bool, List[dict]]:
+        """
+        List all saved Piclets with basic info
+        Returns: (success, list_of_piclet_summaries)
+        """
+        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
+                    }
+                    piclets.append(summary)
+                    
+                except Exception as e:
+                    print(f"Error reading {piclet_file}: {e}")
+                    continue
+            
+            return True, piclets
+            
+        except Exception as e:
+            return False, [{"error": f"Error listing Piclets: {str(e)}"}]
+    
+    @staticmethod
+    def get_piclet_image(piclet_id: str):
+        """Get the image file for a Piclet"""
+        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
+            
+        except Exception as e:
+            print(f"Error getting image for {piclet_id}: {e}")
+            return None
+
+def save_piclet_api(piclet_json: str, image_file=None) -> str:
+    """
+    API endpoint to save a 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}"
+                })
+        
+        # Save the Piclet
+        success, result = PicletStorage.save_piclet(piclet_data, image_file)
+        
+        if success:
+            return json.dumps({
+                "success": True,
+                "piclet_id": result,
+                "message": "Piclet saved successfully"
+            })
+        else:
+            return json.dumps({
+                "success": False,
+                "error": result
+            })
+            
+    except json.JSONDecodeError:
+        return json.dumps({
+            "success": False,
+            "error": "Invalid JSON format"
+        })
+    except Exception as e:
+        return json.dumps({
+            "success": False,
+            "error": f"Unexpected error: {str(e)}"
+        })
+
+def get_piclet_api(piclet_id: str) -> str:
+    """
+    API endpoint to retrieve a Piclet by ID
+    """
+    try:
+        if not piclet_id.strip():
+            return json.dumps({
+                "success": False,
+                "error": "Piclet ID is required"
+            })
+        
+        success, result = PicletStorage.get_piclet(piclet_id.strip())
+        
+        if success:
+            return json.dumps({
+                "success": True,
+                "piclet": result
+            })
+        else:
+            return json.dumps({
+                "success": False,
+                "error": result.get("error", "Unknown error")
+            })
+            
+    except Exception as e:
+        return json.dumps({
+            "success": False,
+            "error": f"Unexpected error: {str(e)}"
+        })
+
+def list_piclets_api(limit: int = 50) -> str:
+    """
+    API endpoint to list all saved Piclets
+    """
+    try:
+        limit = max(1, min(limit, 100))  # Limit between 1 and 100
+        
+        success, result = PicletStorage.list_piclets(limit)
+        
+        if success:
+            return json.dumps({
+                "success": True,
+                "piclets": result,
+                "count": len(result)
+            })
+        else:
+            return json.dumps({
+                "success": False,
+                "error": "Failed to list Piclets"
+            })
+            
+    except Exception as e:
+        return json.dumps({
+            "success": False,
+            "error": f"Unexpected error: {str(e)}"
+        })
+
+def get_piclet_image_api(piclet_id: str):
+    """
+    API endpoint to get a Piclet's image
+    """
+    try:
+        if not piclet_id.strip():
+            return None
+        
+        image_path = PicletStorage.get_piclet_image(piclet_id.strip())
+        return image_path
+        
+    except Exception as e:
+        print(f"Error in get_piclet_image_api: {e}")
+        return None
+
+# 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)
+
+# Create the Gradio interface
+with gr.Blocks(title="Piclets Server API", theme=gr.themes.Soft()) 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
+    """)
+    
+    with gr.Tabs():
+        # Save Piclet Tab
+        with gr.Tab("💾 Save Piclet"):
+            gr.Markdown("### Save a new Piclet with optional image")
+            
+            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
+            )
+        
+        # API Documentation Tab
+        with gr.Tab("📖 API Documentation"):
+            gr.Markdown("""
+            ## API Endpoints
+            
+            This Gradio interface provides the following API endpoints that can be accessed programmatically:
+            
+            ### 1. Save Piclet
+            - **Function**: `save_piclet_api(piclet_json, image_file=None)`
+            - **Input**: JSON string with Piclet data, optional image file
+            - **Output**: JSON response with success status and Piclet ID
+            
+            ### 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"
+                    }
+                  ]
+                }
+              ]
+            }
+            ```
+            
+            ## Usage from Frontend
+            
+            ```javascript
+            // Connect to this Gradio space
+            const client = await window.gradioClient.Client.connect("your-space-name");
+            
+            // Save a Piclet
+            const saveResult = await client.predict("/save_piclet_api", [
+                JSON.stringify(picletData),  // Piclet JSON
+                imageFile  // Optional image file
+            ]);
+            
+            // Get a Piclet
+            const getResult = await client.predict("/get_piclet_api", [
+                picletId  // Piclet ID string
+            ]);
+            
+            // List Piclets
+            const listResult = await client.predict("/list_piclets_api", [
+                20  // Maximum results
+            ]);
+            ```
+            
+            ## 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.
+            """)
+
+# Launch the app
+if __name__ == "__main__":
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False
+    )

requirements.txt

@@ -0,0 +1,2 @@
+gradio==5.38.2
+Pillow>=9.0.0