README.md

---
title: Chronicle Portrait Studio
emoji: ⚔️
colorFrom: indigo
colorTo: gray
sdk: docker
pinned: false
hf_oauth: true
hf_oauth_scopes:
 - inference-api
---

# RPGPortrait Prompt Builder Pro

RPGPortrait is a decoupled Next.js + FastAPI web application that helps users build highly detailed prompts and generate character portraits using advanced AI like Gemini, Hugging Face, and local models.

## 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)**.
- **⚙️ Configuration Hub**: A dedicated center for managing AI engines, models, and API tokens with real-time status detection.
- **🍪 Milk and Cookies Persistence**: All character selections and engine configurations are locally persisted and survive page refreshes.
- **🔦 Full-Resolution Lightbox**: View your masterpieces in high-definition with a premium blur-in effect and direct download button.
- **🖼️ Multi-Backend Image Gen**: Toggle between **Gemini (Cloud)**, **Hugging Face (Cloud)**, and **ComfyUI (Local)**.
- **⚡ Hugging Face Pro Features**: 
    - Support for advanced models (e.g., FLUX.1-dev).
    - Manual **Inference Provider** support (e.g., `fal-ai`, `replicate`) to bypass rate limits.
- **🔍 Dynamic Model Discovery**: Automatically pings local Ollama and ComfyUI servers to reflect availability in the UI.
- **💾 Save & Load**: Export character configurations as JSON and import them to restore your exact studio state.
- **🎒 Dual Accessories & Exotic Arsenal**: Deep customization for your hero's gear and artifacts.
- **🛡️ Robust Error Handling**: Clear, non-intrusive status messages for AI synthesis and refinement errors.
- **YAML Data Storage**: Flexible character features and prompt templates managed via `features.yaml` and `prompts.yaml`.

## Installation & Setup

### 1. Backend (FastAPI)
1. Navigate to the project root directory.
2. Create and activate a virtual environment:
   ```bash
   python -m venv venv
   .\venv\Scripts\activate   # Windows
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   pip install fastapi uvicorn
   ```
4. Set up `.env` with API keys (GEMINI_API_KEY, HF_TOKEN, etc.).
5. Run the FastAPI server:
   ```bash
   python api.py
   ```

### 2. Frontend (Next.js)
1. Open a new terminal and navigate to the `frontend/` directory.
2. Install npm dependencies:
   ```bash
   npm install
   ```
3. Run the Next.js developer server (Tailwind v4):
   ```bash
   npm run dev
   ```
4. Access the premium UI at `http://localhost:3000`.

## Usage
1. **Build your prompt**: Select features in the left column; the prompt updates on the right.
2. **Refine Prompt**: Use the "Enhance Narrative" feature to intelligently polish your description.
3. **Generate Image**: Click Synthesize to create your character icon or render using your selected AI backend.
4. **Save/Load**: Use the Load and Save buttons in the sidebar state management to back up configurations.

## License

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