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

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:

{
  "success": true,
  "piclet_id": "uuid-string",
  "message": "Piclet saved successfully"
}

Error Response:

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

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

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

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

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

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

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

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

Push to Repository: The space automatically deploys when you push to the connected git repository
Environment: Python 3.9+ with Gradio 5.38.2
Persistent Storage: Data persists between space restarts
Public Access: The API is accessible to anyone with the space URL

Space Configuration (in README.md)

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

Check the error messages in API responses
Verify JSON format matches the specification
Ensure all required fields are present
Test with the example data provided