README.md

---
title: Chronicle Portrait Studio
emoji: ⚔️
colorFrom: indigo
colorTo: gray
sdk: gradio
app_file: app.py
pinned: false
hf_oauth: true
---

# RPGPortrait Prompt Builder Pro

RPGPortrait is a Gradio-based web application that helps users build highly detailed prompts and generate character portraits using advanced AI like Gemini, Hugging Face, and Imagen.

## Features
- **25+ Character Parameters**: Deep customization including Identity, Appearance, Equipment, Environment, VFX, and Technical settings.
- **🧠 AI Refinement**: Intelligent prompt enhancement using **Gemini (Cloud)**, **Curated Hugging Face Models**, or **Ollama (Local)**.
- **🛠️ Externalized Prompts**: Tweak the core AI system instructions by editing `prompts.yaml`.
- **🖼️ Multi-Backend Image Gen**: Toggle between **Gemini (Cloud)**, **Hugging Face (Cloud)**, and **ComfyUI (Local)**.
- **⚡ Hugging Face Pro Features**: 
    - Curated list of 4 text and 4 image models.
    - Manual **Inference Provider** support (e.g., `fal-ai`, `black-forest-labs`) to bypass rate limits or use partner backends.
    - Automated "auto" provider selection by default.
- **🔍 Dynamic Model Discovery**: Automatically pings local Ollama and ComfyUI servers to fetch available models and hide unavailable backends.
- **Workflow Injection**: Automated prompt, resolution, and seed injection into custom ComfyUI workflows.
- **💾 Save & Load**: Export your character configurations as JSON files and import them back to restore your exact selections.
- **⚔️ Exotic Arsenal**: Expanded collection of exotic weapons, armor, and accessories (Katanas, Bone Armor, Arcane Plate, etc.).
- **🎒 Dual Accessories**: Select up to two different accessories for your character.
- **📥 Pro Downloads**: Standard PNG downloads for portraits with friendly filenames.
- **Randomization**: Check individual 🎲 boxes to randomize specific features on regeneration.
- **🛡️ Robust Error Handling**: AI refinement errors are logged to the console and displayed in the UI status area without polluting your current prompt.
- **YAML Data Storage**: Easily add or modify races, classes, backgrounds, and templates in `features.yaml`.

## Installation

1. **Clone the repository** (or navigate to the project folder).
2. **Create a virtual environment**:
   ```bash
   python -m venv venv
   ```
3. **Activate the environment**:
   - Windows: `.\venv\Scripts\activate`
   - Linux/Mac: `source venv/bin/activate`
4. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```
5. **Set up API Keys**:
   - Create a `.env` file in the root directory.
   - Add your keys and connection info:
   ```env
   GEMINI_API_KEY=your_gemini_key
   HF_TOKEN=your_huggingface_token  # Required for Cloud backends
   COMFY_HOST=127.0.0.1
   COMFY_PORT=8188
   OLLAMA_HOST=127.0.0.1
   OLLAMA_PORT=11434
   ```

## Usage

1. **Run the application**:
   ```bash
   python app.py
   ```
2. **Access the UI**: Open your browser and navigate to `http://127.0.0.1:7860`.
3. **Build your prompt**: Select features in the left column; the technical prompt updates in real-time.
4. **Refine Prompt**: 
    - Choose a **Refinement Backend** in the configuration panel.
    - Click **🧠 Refine Prompt** in the right column to polish your description.
5. **Generate Image**:
    - Select an **Image Generation Backend**.
    - Click **🖼️ Generate Image** (located directly under the portrait output) to create your character.
6. **Save/Load**: Use the 💾 and 📂 buttons to manage your character library.

## License

This project is licensed under the [MIT License](LICENSE).