Migrate to Next.js & FastAPI Architecture with Premium UI

- Decouples monolithic Gradio app into FastAPI backend (`api.py`) and Next.js frontend (`frontend/`).
- Implements Stitch MCP-inspired 'Alchemist's Workshop' aesthetic with glassmorphism and Cinzel typography.
- Replaces generic Gradio grids with precisely constrained, center-aligned HTML forms using Tailwind v4.
- Preserves 100% functional parity including JSON Save/Load, Example Characters, and Image Generation.
- Updates README documentation to reflect the new decoupled setup instructions.

.gemini-commit-msg.txt

@@ -0,0 +1,7 @@
+Migrate to Next.js & FastAPI Architecture with Premium UI
+
+- Decouples monolithic Gradio app into FastAPI backend (`api.py`) and Next.js frontend (`frontend/`).
+- Implements Stitch MCP-inspired 'Alchemist's Workshop' aesthetic with glassmorphism and Cinzel typography.
+- Replaces generic Gradio grids with precisely constrained, center-aligned HTML forms using Tailwind v4.
+- Preserves 100% functional parity including JSON Save/Load, Example Characters, and Image Generation.
+- Updates README documentation to reflect the new decoupled setup instructions.

README.md

@@ -11,7 +11,7 @@ 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.
+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.
@@ -32,47 +32,43 @@ RPGPortrait is a Gradio-based web application that helps users build highly deta
 - **🛡️ 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
+## Installation & Setup
 
-1. **Clone the repository** (or navigate to the project folder).
-2. **Create a virtual environment**:
+### 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. **Activate the environment**:
-   - Windows: `.\venv\Scripts\activate`
-   - Linux/Mac: `source venv/bin/activate`
-4. **Install dependencies**:
+3. Install dependencies:
    ```bash
    pip install -r requirements.txt
+   pip install fastapi uvicorn
    ```
-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
+4. Set up `.env` with API keys (GEMINI_API_KEY, HF_TOKEN, etc.).
+5. Run the FastAPI server:
+   ```bash
+   python api.py
    ```
 
-## Usage
-
-1. **Run the application**:
+### 2. Frontend (Next.js)
+1. Open a new terminal and navigate to the `frontend/` directory.
+2. Install npm dependencies:
    ```bash
-   python app.py
+   npm install
    ```
-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.
+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
 

api.py

@@ -0,0 +1,155 @@
+import os
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from typing import List, Optional, Any
+
+from modules.config import FEATURE_SEQUENCE, SECTIONS
+from modules.core_logic import (
+    generate_prompt as core_generate_prompt,
+    handle_regeneration as core_handle_regeneration,
+    save_character as core_save_character,
+    load_character as core_load_character
+)
+from modules.integrations import (
+    refine_master,
+    generate_name_master,
+    generate_image_master,
+    get_ollama_models,
+    check_comfy_availability
+)
+from modules.name_generator import generate_fantasy_name
+
+app = FastAPI(title="Chronicle Portrait Studio API")
+
+# Setup CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"], # Since frontend might run on different port
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+class PromptRequest(BaseModel):
+    character_name: str
+    features: List[str]
+    randomization: List[bool]
+    extra_info: List[str]
+
+    def to_args(self):
+        return [self.character_name] + self.features + self.randomization + self.extra_info
+
+class NamingRequest(BaseModel):
+    race: str
+
+class RegenerationRequest(BaseModel):
+    current_values: List[str]
+    checkboxes: List[bool]
+    
+    def to_args(self):
+        return self.current_values + self.checkboxes
+
+class RefinementRequest(BaseModel):
+    prompt: str
+    backend: str
+    ollama_model: Optional[str] = None
+    hf_text_model: Optional[str] = None
+    hf_text_provider: Optional[str] = None
+    manual_token: Optional[str] = None
+    character_name: Optional[str] = None
+
+class ImageGenerationRequest(BaseModel):
+    refined_prompt: str
+    technical_prompt: str
+    aspect_ratio: str
+    backend: str
+    hf_image_model: Optional[str] = None
+    hf_image_provider: Optional[str] = None
+    manual_token: Optional[str] = None
+    character_name: Optional[str] = None
+
+@app.get("/api/config")
+def get_config():
+    """Returns static config info needed by frontend to render dropdowns, etc."""
+    from modules.core_logic import features_data, get_example_list
+    return {
+        "features_data": features_data,
+        "feature_sequence": FEATURE_SEQUENCE,
+        "sections": SECTIONS,
+        "ollama_models": get_ollama_models(),
+        "comfy_active": check_comfy_availability(),
+        "examples": get_example_list()
+    }
+
+@app.get("/api/example/{filename}")
+def get_example(filename: str):
+    from modules.config import EXAMPLES_DIR
+    import os
+    path = os.path.join(EXAMPLES_DIR, filename)
+    if os.path.exists(path):
+        return FileResponse(path, media_type="application/json")
+    raise HTTPException(status_code=404, detail="Example not found")
+
+@app.post("/api/generate_prompt")
+def generate_prompt(req: PromptRequest):
+    args = req.to_args()
+    prompt = core_generate_prompt(*args)
+    return {"prompt": prompt}
+
+@app.post("/api/regenerate_features")
+def regenerate_features(req: RegenerationRequest):
+    args = req.to_args()
+    new_values = core_handle_regeneration(*args)
+    return {"new_values": new_values}
+
+@app.post("/api/generate_name")
+def proxy_generate_name(req: NamingRequest):
+    name = generate_fantasy_name(req.race)
+    return {"name": name}
+
+@app.post("/api/refine_prompt")
+def refine_prompt(req: RefinementRequest):
+    result, error_msg = refine_master(
+        req.prompt, 
+        req.backend, 
+        req.ollama_model, 
+        req.hf_text_model, 
+        req.hf_text_provider, 
+        req.manual_token, 
+        req.character_name
+    )
+    # result can be a gr.update() if it fails, and error_msg will have content
+    if error_msg:
+        raise HTTPException(status_code=400, detail=error_msg)
+    return {"refined_prompt": result}
+
+@app.post("/api/generate_image")
+def generate_image(req: ImageGenerationRequest):
+    img, img_path, status_msg = generate_image_master(
+        req.refined_prompt,
+        req.technical_prompt,
+        req.aspect_ratio,
+        req.backend,
+        req.hf_image_model,
+        req.hf_image_provider,
+        req.manual_token,
+        req.character_name
+    )
+    if img_path and os.path.exists(img_path):
+        return FileResponse(img_path, media_type="image/png", headers={"X-Status-Msg": status_msg})
+    else:
+        raise HTTPException(status_code=500, detail=status_msg or "Failed to generate image.")
+
+@app.post("/api/save_character")
+def save_character(req: PromptRequest):
+    args = req.to_args()
+    file_path = core_save_character(*args)
+    if file_path and os.path.exists(file_path):
+         return FileResponse(file_path, media_type="application/json", filename=os.path.basename(file_path))
+    raise HTTPException(status_code=500, detail="Failed to save character state.")
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("api:app", host="127.0.0.1", port=8000, reload=True)

frontend/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

frontend/AGENTS.md

@@ -0,0 +1,5 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

frontend/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

frontend/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

frontend/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

frontend/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;

frontend/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "lucide-react": "^1.6.0",
+    "next": "16.2.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.1",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

frontend/src/app/globals.css

@@ -0,0 +1,66 @@
+@import url('https://fonts.googleapis.com/css2?family=Cinzel:wght@400;600;700&family=Inter:wght@300;400;500;600&display=swap');
+
+@import "tailwindcss";@layer base {
+  html, body {
+    background-color: #080604;
+    color: #E2D1B3;
+    font-family: 'Inter', system-ui, sans-serif;
+    /* Subtle noise texture over the deep dark background */
+    background-image: radial-gradient(circle at 50% 0%, #1a1410 0%, #080604 70%);
+  }
+}
+
+@layer components {
+  .glass-panel {
+    background-color: rgba(20, 16, 12, 0.8);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+    border: 1px solid #2D241A;
+    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+  }
+  
+  .font-cinzel {
+    font-family: 'Cinzel', serif;
+  }
+
+  .gold-gradient-text {
+    background-image: linear-gradient(to right, #DAB062, #F3DE9A, #DAB062);
+    color: transparent;
+    background-clip: text;
+    -webkit-background-clip: text;
+  }
+  
+  .input-alchemist {
+     width: 100%;
+     background-color: #0a0805;
+     border: 1px solid #2D241A;
+     border-radius: 0.5rem;
+     padding: 0.75rem 1.25rem;
+     font-size: 0.875rem;
+     line-height: 1.25rem;
+     color: #E2D1B3;
+     transition: all 150ms;
+     font-weight: 300;
+  }
+
+  .input-alchemist:focus {
+     outline: none;
+     border-color: #DAB062;
+     box-shadow: 0 0 0 1px rgba(218, 176, 98, 0.5);
+  }
+}
+
+/* Custom Scrollbar for premium feel */
+::-webkit-scrollbar {
+  width: 8px;
+}
+::-webkit-scrollbar-track {
+  background: #080604;
+}
+::-webkit-scrollbar-thumb {
+  background: #2D241A;
+  border-radius: 4px;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: #DAB062;
+}

frontend/src/app/layout.tsx

@@ -0,0 +1,15 @@
+import './globals.css';
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+      </body>
+    </html>
+  );
+}

frontend/src/app/page.tsx

@@ -0,0 +1,9 @@
+import ClientApp from '../components/ClientApp';
+
+export default function Home() {
+  return (
+    <main className="min-h-screen p-4">
+      <ClientApp />
+    </main>
+  );
+}

frontend/src/components/ClientApp.tsx

@@ -0,0 +1,537 @@
+"use client";
+
+import React, { useState, useEffect, useRef } from 'react';
+import { User, Sparkles, Sword, Globe, Palette, Settings, Image as ImageIcon, Wand2, Dices, Save, Download, Upload, Copy } from 'lucide-react';
+
+const API_URL = "http://127.0.0.1:8000";
+
+const tabs = [
+  { id: 'identity', label: 'Identity & Race', icon: User },
+  { id: 'appearance', label: 'Physical Traits', icon: Sparkles },
+  { id: 'equipment', label: 'Gear & Weapons', icon: Sword },
+  { id: 'environment', label: 'Atmosphere', icon: Globe },
+  { id: 'style', label: 'Render Style', icon: Palette }
+];
+
+export default function ClientApp() {
+  const [config, setConfig] = useState<any>(null);
+  const [activeTab, setActiveTab] = useState('identity');
+  
+  const [characterName, setCharacterName] = useState("Unnamed Hero");
+  const [features, setFeatures] = useState<string[]>([]);
+  const [randomization, setRandomization] = useState<boolean[]>([]);
+  const [extraInfo, setExtraInfo] = useState<string[]>(Array(5).fill(""));
+  const [promptOutput, setPromptOutput] = useState("");
+  const [refinedOutput, setRefinedOutput] = useState("");
+  const [imageSrc, setImageSrc] = useState<string | null>(null);
+  const [statusMsg, setStatusMsg] = useState("");
+
+  const [refinementBackend, setRefinementBackend] = useState("Gemini (Cloud)");
+  const [imageBackend, setImageBackend] = useState("ComfyUI (Local)");
+  const [ollamaModel, setOllamaModel] = useState("");
+  const [hfTextModel, setHfTextModel] = useState("Qwen/Qwen2.5-72B-Instruct");
+  const [hfTextProvider, setHfTextProvider] = useState("auto");
+  const [hfImageModel, setHfImageModel] = useState("black-forest-labs/FLUX.1-dev");
+  const [hfImageProvider, setHfImageProvider] = useState("auto");
+  const [manualToken, setManualToken] = useState("");
+  
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    fetch(`${API_URL}/api/config`)
+      .then(res => res.json())
+      .then(data => {
+        setConfig(data);
+        const initFeatures = data.feature_sequence.map(([cat, sub]: any) => {
+          const ks = Object.keys(data.features_data[cat]?.[sub] || {});
+          return ks.length > 0 ? ks[0] : "None";
+        });
+        setFeatures(initFeatures);
+        setRandomization(Array(data.feature_sequence.length).fill(false));
+      })
+      .catch(err => console.error("Failed to load config", err));
+  }, []);
+
+  const updatePrompt = async (newFeatures = features, newExtraInfo = extraInfo, newName = characterName) => {
+    if (!config || newFeatures.length === 0) return;
+    try {
+      const res = await fetch(`${API_URL}/api/generate_prompt`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          character_name: newName,
+          features: newFeatures,
+          randomization: randomization,
+          extra_info: newExtraInfo
+        })
+      });
+      const data = await res.json();
+      setPromptOutput(data.prompt);
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  useEffect(() => {
+    if (config && features.length > 0) updatePrompt();
+  }, [features, extraInfo, characterName]);
+
+  const handleFeatureChange = (index: number, val: string) => {
+    const f = [...features];
+    f[index] = val;
+    setFeatures(f);
+  };
+
+  const handleExtraInfoChange = (index: number, val: string) => {
+    const e = [...extraInfo];
+    e[index] = val;
+    setExtraInfo(e);
+  };
+
+  const handleRandomize = async () => {
+    try {
+      setStatusMsg("Randomizing flagged parameters...");
+      const res = await fetch(`${API_URL}/api/regenerate_features`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ current_values: features, checkboxes: randomization })
+      });
+      const data = await res.json();
+      setFeatures(data.new_values);
+      setRefinedOutput("");
+      setStatusMsg("Randomization complete.");
+    } catch (e) { console.error(e); }
+  };
+
+  const applyLoadedData = (data: any) => {
+    if (!config) return;
+    setCharacterName(data.name || "Unnamed Hero");
+    const loadedFeatures = config.feature_sequence.map((seq: any) => data.features?.[seq[2]] || "None");
+    setFeatures(loadedFeatures);
+    
+    const loadedRandom = config.feature_sequence.map((seq: any) => data.randomization?.[seq[2]] || false);
+    setRandomization(loadedRandom);
+
+    const loadedExtra = config.sections.map((sec: string) => data.extra_info?.[sec.toLowerCase()] || "");
+    setExtraInfo(loadedExtra);
+    setStatusMsg(`Loaded ${data.name || "character"} successfully!`);
+  };
+
+  const handleLoadFile = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    const reader = new FileReader();
+    reader.onload = (evt) => {
+      try {
+        const data = JSON.parse(evt.target?.result as string);
+        applyLoadedData(data);
+      } catch (err) { setStatusMsg("Error: Invalid JSON file."); }
+    };
+    reader.readAsText(file);
+    if (fileInputRef.current) fileInputRef.current.value = "";
+  };
+
+  const handleSaveFile = () => {
+    if (!config) return;
+    const data: any = { name: characterName, features: {}, randomization: {}, extra_info: {} };
+    config.feature_sequence.forEach((seq: any, i: number) => {
+        data.features[seq[2]] = features[i];
+        data.randomization[seq[2]] = randomization[i];
+    });
+    config.sections.forEach((sec: string, i: number) => {
+        data.extra_info[sec.toLowerCase()] = extraInfo[i];
+    });
+    
+    const blob = new Blob([JSON.stringify(data, null, 4)], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `${characterName.replace(/[^a-z0-9]/gi, '_').toLowerCase() || 'character'}_data.json`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+    setStatusMsg("Character configuration saved!");
+  };
+
+  const handleLoadExample = async (filename: string) => {
+    if (!filename) return;
+    try {
+        const res = await fetch(`${API_URL}/api/example/${filename}`);
+        if(res.ok) {
+            const data = await res.json();
+            applyLoadedData(data);
+        } else {
+            setStatusMsg("Failed to load example.");
+        }
+    } catch (e) {
+        setStatusMsg("Failed to load example.");
+    }
+  };
+
+  const handleRefine = async () => {
+    setStatusMsg("Refining prompt...");
+    try {
+      const res = await fetch(`${API_URL}/api/refine_prompt`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ prompt: promptOutput, backend: refinementBackend, ollama_model: ollamaModel, hf_text_model: hfTextModel, hf_text_provider: hfTextProvider, manual_token: manualToken, character_name: characterName })
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setRefinedOutput(data.refined_prompt);
+        setStatusMsg("Refinement complete!");
+      } else {
+        const err = await res.json();
+        setStatusMsg(`Error: ${err.detail}`);
+      }
+    } catch (e) { setStatusMsg("Refinement failed."); }
+  };
+
+  const handleGenerateImage = async () => {
+    setStatusMsg("Synthesizing portrait...");
+    setImageSrc(null);
+    try {
+      const aspectIndex = config.feature_sequence.findIndex((seq: any) => seq[2] === "aspect_ratio");
+      const ar = aspectIndex !== -1 ? features[aspectIndex] : "1:1";
+
+      const res = await fetch(`${API_URL}/api/generate_image`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refined_prompt: refinedOutput, technical_prompt: promptOutput, aspect_ratio: ar, backend: imageBackend, hf_image_model: hfImageModel, hf_image_provider: hfImageProvider, manual_token: manualToken, character_name: characterName })
+      });
+      
+      if (res.ok) {
+        const blob = await res.blob();
+        setImageSrc(URL.createObjectURL(blob));
+        setStatusMsg(res.headers.get("X-Status-Msg") || "Synthesis complete!");
+      } else {
+        const err = await res.json();
+        setStatusMsg(`Synthesis Error: ${err.detail}`);
+      }
+    } catch (e) { setStatusMsg("Synthesis failed to initialize."); }
+  };
+
+  const handleDownloadImage = () => {
+    if (!imageSrc) return;
+    const a = document.createElement('a');
+    a.href = imageSrc;
+    a.download = `${characterName.replace(/[^a-z0-9]/gi, '_').toLowerCase() || 'portrait'}.png`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+  };
+
+  const handleCopy = (text: string) => {
+      if(!text) return;
+      navigator.clipboard.writeText(text);
+      setStatusMsg("Copied to clipboard!");
+  };
+
+  const renderFeatureUI = (cat: string, subcat: string, label: string) => {
+    const idx = config.feature_sequence.findIndex((seq: any) => seq[0] === cat && seq[1] === subcat);
+    if (idx === -1) return null;
+    let mappedIdx = idx;
+    if (subcat === 'accessory' && label.includes('2')) mappedIdx = idx + 1;
+    const choices = Object.keys(config.features_data[cat]?.[subcat] || {});
+
+    return (
+      <div className="mb-8 relative group" key={`${cat}-${subcat}-${label}`}>
+        <label className="block text-[10px] uppercase tracking-[0.2em] text-[#DAB062] mb-2 font-bold">{label}</label>
+        <div className="flex items-center gap-3">
+          <select 
+            className="input-alchemist flex-1 appearance-none cursor-pointer"
+            value={features[mappedIdx] || ""} 
+            onChange={(e) => handleFeatureChange(mappedIdx, e.target.value)}
+          >
+            {choices.map(c => <option key={c} value={c}>{c}</option>)}
+          </select>
+          <div className="flex flex-col items-center justify-center">
+             <button
+                onClick={() => {
+                   const r = [...randomization];
+                   r[mappedIdx] = !r[mappedIdx];
+                   setRandomization(r);
+                }}
+                className={`p-2 rounded-md transition-all duration-300 ${randomization[mappedIdx] ? 'bg-[#DAB062] text-[#080604] shadow-[0_0_12px_rgba(218,176,98,0.6)]' : 'bg-[#0a0805] text-[#A89880] hover:text-[#DAB062] border border-[#2D241A] hover:border-[#DAB062]/50'}`}
+                title="Toggle Randomization"
+              >
+                <Dices size={16} />
+              </button>
+          </div>
+        </div>
+      </div>
+    );
+  };
+
+  if (!config) return <div className="h-screen w-full flex items-center justify-center font-cinzel text-2xl text-[#DAB062]">Igniting forge...</div>;
+
+  return (
+    <div className="flex h-screen w-full overflow-hidden text-[#E2D1B3] antialiased">
+      
+      {/* Hidden file input for loading JSON */}
+      <input type="file" accept=".json" className="hidden" ref={fileInputRef} onChange={handleLoadFile} />
+
+      {/* 1. Left Sidebar Navigation */}
+      <div className="w-[300px] border-r border-[#2D241A] bg-[#0a0805]/95 backdrop-blur-xl flex flex-col relative z-20">
+        <div className="p-8 border-b border-[#2D241A] text-center">
+           <h1 className="font-cinzel font-bold text-3xl gold-gradient-text drop-shadow-md mb-2">Chronicle</h1>
+           <p className="text-[#A89880] text-sm uppercase tracking-[0.2em]">Portrait Studio</p>
+        </div>
+        
+        <nav className="flex-1 px-4 py-8 space-y-2 overflow-y-auto custom-scrollbar">
+          <div className="text-[10px] uppercase tracking-widest text-[#665D4F] mb-4 px-4">Creation Aspects</div>
+          {tabs.map(t => {
+            const Icon = t.icon;
+            const isActive = activeTab === t.id;
+            return (
+              <button
+                key={t.id}
+                onClick={() => setActiveTab(t.id)}
+                className={`w-full flex items-center gap-4 px-4 py-3 rounded-lg transition-all duration-300 group
+                  ${isActive ? 'bg-[#18130E] border border-[#3D3224] shadow-[inset_0_0_15px_rgba(218,176,98,0.05)]' : 'border border-transparent hover:bg-[#120E0A]'}`}
+              >
+                <Icon size={20} className={isActive ? 'text-[#DAB062]' : 'text-[#665D4F] group-hover:text-[#A89880]'} />
+                <span className={`text-sm tracking-wide flex-1 text-left ${isActive ? 'text-[#E2D1B3] font-medium' : 'text-[#8C7F6B] group-hover:text-[#A89880]'}`}>
+                  {t.label}
+                </span>
+              </button>
+            );
+          })}
+          
+          <div className="h-4"></div>
+          
+          <div className="text-[10px] uppercase tracking-widest text-[#A89880] mb-4 px-4">State Management</div>
+          <div className="px-2 grid grid-cols-2 gap-2 mb-4">
+             <button onClick={() => fileInputRef.current?.click()} className="flex items-center justify-center gap-2 px-3 py-2 border border-[#2D241A] bg-[#0E151A]/50 rounded font-medium text-[#A89880] hover:text-[#DAB062] hover:border-[#DAB062]/50 transition-colors text-xs tracking-wider">
+                <Upload size={14} /> Load
+             </button>
+             <button onClick={handleSaveFile} className="flex items-center justify-center gap-2 px-3 py-2 border border-[#2D241A] bg-[#0E151A]/50 rounded font-medium text-[#A89880] hover:text-[#DAB062] hover:border-[#DAB062]/50 transition-colors text-xs tracking-wider">
+                <Save size={14} /> Save
+             </button>
+          </div>
+
+          <div className="px-2 mb-6">
+             <label className="text-[10px] block uppercase tracking-widest text-[#A89880] mb-2 px-2">Load Example</label>
+             <select 
+               onChange={(e) => handleLoadExample(e.target.value)} 
+               className="input-alchemist py-2 text-xs" 
+               defaultValue=""
+             >
+                <option value="" disabled>Select a Preset...</option>
+                {config.examples?.map((ex: string) => <option key={ex} value={ex}>{ex.replace('.json', '')}</option>)}
+             </select>
+          </div>
+
+          <div className="text-[10px] uppercase tracking-widest text-[#A89880] mb-4 px-4 border-t border-[#2D241A] pt-6">Global Actions</div>
+          <button onClick={handleRandomize} className="w-full mx-2 flex items-center justify-center gap-3 px-4 py-3 border border-[#3A4E59] bg-[#0E151A] rounded-lg text-[#61C2DF] hover:bg-[#121B22] hover:border-[#61C2DF] transition-all group" style={{ width: 'calc(100% - 1rem)'}}>
+             <Dices size={18} />
+             <span className="text-sm tracking-wide font-medium">Randomize Flags</span>
+          </button>
+        </nav>
+        
+        {/* Backend Quick Config at Bottom */}
+        <div className="p-6 border-t border-[#2D241A] bg-[#080604]">
+            <div className="flex items-center gap-2 mb-4 text-[#A89880]">
+               <Settings size={16} />
+               <span className="text-xs uppercase tracking-wider font-semibold">Active Engines</span>
+            </div>
+            <select value={refinementBackend} onChange={e => setRefinementBackend(e.target.value)} className="input-alchemist mb-3 text-xs" title="Text Backbone">
+              <option>Gemini (Cloud)</option>
+              <option>Hugging Face (Cloud)</option>
+              <option>Ollama (Local)</option>
+            </select>
+            <select value={imageBackend} onChange={e => setImageBackend(e.target.value)} className="input-alchemist text-xs" title="Image Engine">
+              <option>ComfyUI (Local)</option>
+              <option>Gemini (Cloud)</option>
+              <option>Hugging Face (Cloud)</option>
+            </select>
+        </div>
+      </div>
+
+      {/* 2. Main Middle Area (Form Aspects) */}
+      <div className="flex-1 flex flex-col relative z-10 overflow-y-auto shadow-inner custom-scrollbar bg-[#0f0c08]">
+        <div className="sticky top-0 h-12 bg-gradient-to-b from-[#080604] to-transparent z-10 pointer-events-none w-full"></div>
+        
+        <div className="max-w-2xl mx-auto w-full px-8 pb-24">
+           {/* Section Headers */}
+           <div className="mb-10 pl-2">
+              <h2 className="font-cinzel text-3xl text-[#E2D1B3] mb-3">{tabs.find(t => t.id === activeTab)?.label}</h2>
+              <div className="w-16 h-1 bg-[#DAB062] rounded-full opacity-50"></div>
+           </div>
+
+           <div className="glass-panel rounded-2xl p-10 mb-8 relative overflow-hidden group">
+              <div className="absolute top-0 right-0 w-96 h-96 bg-[#DAB062]/5 rounded-full blur-3xl -mr-32 -mt-32 pointer-events-none transition-all duration-700 group-hover:bg-[#DAB062]/10"></div>
+              
+              <div className="relative z-10 w-full">
+                {activeTab === 'identity' && (
+                  <div className="w-full">
+                     <div className="mb-10 p-6 bg-[#0a0805] border border-[#2D241A] rounded-xl shadow-inner relative group">
+                       <label className="block text-[10px] uppercase tracking-[0.2em] text-[#DAB062] mb-3 font-bold">Subject Name</label>
+                       <input type="text" value={characterName} onChange={e => setCharacterName(e.target.value)} className="w-full bg-[#120E0A] border border-[#3D3224] text-[#E2D1B3] font-cinzel text-xl font-semibold rounded-lg px-4 py-3 outline-none focus:border-[#DAB062] focus:ring-1 focus:ring-[#DAB062]/50 transition-all placeholder-[#E2D1B3]/20" placeholder="Enter name..."/>
+                     </div>
+                     <div className="grid grid-cols-2 gap-x-12 gap-y-8">
+                       {renderFeatureUI('identity', 'race', 'Race')}
+                       {renderFeatureUI('identity', 'class', 'Class')}
+                       {renderFeatureUI('identity', 'gender', 'Gender')}
+                       {renderFeatureUI('identity', 'age', 'Age')}
+                     </div>
+                     <div className="mt-10">
+                       <label className="block text-xs uppercase tracking-widest text-[#A89880] mb-4">Lore / Background Text</label>
+                       <textarea value={extraInfo[0]} onChange={e => handleExtraInfoChange(0, e.target.value)} className="input-alchemist h-32 resize-none leading-relaxed"></textarea>
+                     </div>
+                     
+                     <div className="my-12 border-t border-[#2D241A]/50"></div>
+                     
+                     <h3 className="font-cinzel text-2xl text-[#DAB062] mb-8 drop-shadow-sm">Expression & Stance</h3>
+                     <div className="grid grid-cols-2 gap-x-12 gap-y-8">
+                       {renderFeatureUI('expression_pose', 'expression', 'Expression')}
+                       {renderFeatureUI('expression_pose', 'pose', 'Pose')}
+                     </div>
+                  </div>
+                )}
+                
+                {activeTab === 'appearance' && (
+                  <div className="w-full">
+                    <div className="grid grid-cols-2 gap-x-16 gap-y-12">
+                       {renderFeatureUI('appearance', 'hair_color', 'Hair Color')}
+                       {renderFeatureUI('appearance', 'hair_style', 'Hair Style')}
+                       {renderFeatureUI('appearance', 'eye_color', 'Eye Color')}
+                       {renderFeatureUI('appearance', 'build', 'Build')}
+                       {renderFeatureUI('appearance', 'skin_tone', 'Skin Tone')}
+                       {renderFeatureUI('appearance', 'distinguishing_feature', 'Main Feature')}
+                     </div>
+                     <div className="mt-10">
+                       <label className="block text-xs uppercase tracking-widest text-[#A89880] mb-4">Additional Visuals</label>
+                       <textarea value={extraInfo[1]} onChange={e => handleExtraInfoChange(1, e.target.value)} className="input-alchemist h-32 resize-none leading-relaxed"></textarea>
+                     </div>
+                  </div>
+                )}
+
+                {activeTab === 'equipment' && (
+                  <div className="w-full">
+                    <div className="grid grid-cols-2 gap-x-16 gap-y-12">
+                       {renderFeatureUI('equipment', 'armor', 'Primary Gear')}
+                       {renderFeatureUI('equipment', 'weapon', 'Weapon Variant')}
+                       {renderFeatureUI('equipment', 'accessory', 'Acc. 1')}
+                       {renderFeatureUI('equipment', 'accessory', 'Acc. 2')}
+                       {renderFeatureUI('equipment', 'material', 'Material Finish')}
+                     </div>
+                     <div className="mt-10">
+                       <label className="block text-xs uppercase tracking-widest text-[#A89880] mb-4">Custom Equipment Description</label>
+                       <textarea value={extraInfo[2]} onChange={e => handleExtraInfoChange(2, e.target.value)} className="input-alchemist h-32 resize-none leading-relaxed"></textarea>
+                     </div>
+                  </div>
+                )}
+
+                {activeTab === 'environment' && (
+                  <div className="w-full">
+                    <div className="grid grid-cols-2 gap-x-16 gap-y-12">
+                       {renderFeatureUI('environment', 'background', 'Backdrop')}
+                       {renderFeatureUI('environment', 'lighting', 'Illumination')}
+                       {renderFeatureUI('environment', 'atmosphere', 'Atmosphere')}
+                     </div>
+                     <div className="mt-10">
+                       <label className="block text-xs uppercase tracking-widest text-[#A89880] mb-4">Custom Environment Info</label>
+                       <textarea value={extraInfo[3]} onChange={e => handleExtraInfoChange(3, e.target.value)} className="input-alchemist h-32 resize-none leading-relaxed"></textarea>
+                     </div>
+                  </div>
+                )}
+
+                {activeTab === 'style' && (
+                  <div className="w-full">
+                    <div className="grid grid-cols-2 gap-x-16 gap-y-12">
+                       {renderFeatureUI('vfx_style', 'vfx', 'Particle Effects')}
+                       {renderFeatureUI('vfx_style', 'style', 'Illustration Style')}
+                       {renderFeatureUI('vfx_style', 'mood', 'Color Grading/Mood')}
+                       {renderFeatureUI('vfx_style', 'camera', 'Camera Setup')}
+                       {renderFeatureUI('technical', 'aspect_ratio', 'Aspect Ratio')}
+                     </div>
+                     <div className="mt-10">
+                       <label className="block text-xs uppercase tracking-widest text-[#A89880] mb-4">Additional Technical Prompts</label>
+                       <textarea value={extraInfo[4]} onChange={e => handleExtraInfoChange(4, e.target.value)} className="input-alchemist h-32 resize-none leading-relaxed"></textarea>
+                     </div>
+                  </div>
+                )}
+              </div>
+           </div>
+        </div>
+      </div>
+
+      {/* 3. Right Crucible Area (Output & Synthesis) */}
+      <div className="w-[450px] border-l border-[#2D241A] bg-[#0C0A08] flex flex-col flex-shrink-0 shadow-[-10px_0_30px_rgba(0,0,0,0.5)] z-30">
+        
+        {/* Output Image Canvas */}
+        <div className="h-[45%] p-6 border-b border-[#2D241A] relative flex items-center justify-center overflow-hidden">
+           <div className="absolute inset-0 bg-[url('https://www.transparenttextures.com/patterns/dark-matter.png')] opacity-10 pointer-events-none"></div>
+           
+           {imageSrc ? (
+             <div className="relative w-full h-full flex items-center justify-center rounded-lg overflow-hidden group">
+               <div className="absolute inset-0 border border-[#DAB062] opacity-30 pointer-events-none z-10 rounded-lg"></div>
+               <img src={imageSrc} alt="Portrait" className="max-w-full max-h-full object-contain drop-shadow-[0_0_20px_rgba(218,176,98,0.2)] transition-transform duration-700 ease-in-out group-hover:scale-[1.02]" />
+               
+               {/* Context menu mock overlay */}
+               <div className="absolute top-3 right-3 flex gap-2 opacity-0 group-hover:opacity-100 transition-opacity">
+                  <button onClick={handleDownloadImage} title="Download Portrait" className="bg-black/60 backdrop-blur-md text-[#E2D1B3] p-2 rounded-md hover:text-[#DAB062] hover:bg-black/80 border border-[#2D241A] transition-all"><Download size={18}/></button>
+               </div>
+             </div>
+           ) : (
+             <div className="flex flex-col items-center justify-center text-center opacity-40">
+                <ImageIcon size={56} className="text-[#A89880] mb-4 stroke-1" />
+                <p className="font-cinzel text-[#A89880] tracking-widest text-sm">Visual Synthesis Pending</p>
+             </div>
+           )}
+        </div>
+
+        {/* Action Panel */}
+        <div className="flex-1 p-6 flex flex-col overflow-y-auto custom-scrollbar">
+           
+           <div className="flex-1 flex flex-col group relative shrink-0 min-h-[160px]">
+              <div className="flex items-center justify-between mb-4">
+                 <label className="text-xs uppercase tracking-widest text-[#A89880] font-medium flex items-center gap-2"><Sparkles size={14} className="text-[#61C2DF]" /> Narrative Prompt</label>
+                 <button onClick={() => handleCopy(refinedOutput || promptOutput)} title="Copy Narrative" className="p-1.5 rounded-lg bg-transparent border border-[#1A2E38] hover:bg-[#1A2E38]/50 text-[#A89880] hover:text-[#61C2DF] transition-all"><Copy size={14} /></button>
+              </div>
+              <textarea 
+                value={refinedOutput} 
+                onChange={e => setRefinedOutput(e.target.value)} 
+                placeholder="Click refine to generate an artistic prompt... or type manually."
+                className="flex-1 bg-[#12181C] border border-[#1A2E38] rounded-xl p-4 text-sm text-[#E0F2FE] tracking-wide resize-none focus:outline-none focus:border-[#61C2DF] focus:ring-1 focus:ring-[#61C2DF]/30 custom-scrollbar shadow-inner transition-colors group-hover:border-[#223F4D]"
+              ></textarea>
+              <button 
+                onClick={handleRefine} 
+                className="mt-4 w-full shrink-0 relative overflow-hidden group bg-gradient-to-r from-[#1A3F4D] via-[#2F657D] to-[#1A3F4D] text-[#E0F2FE] font-cinzel font-bold text-sm tracking-widest py-3.5 rounded-xl shadow-[0_0_15px_rgba(97,194,223,0.15)] transition-all hover:shadow-[0_0_25px_rgba(97,194,223,0.3)]"
+              >
+                <div className="absolute inset-0 bg-white/10 translate-x-[-100%] group-hover:translate-x-[100%] transition-transform duration-1000 ease-out"></div>
+                <span className="relative z-10 flex items-center justify-center gap-3">
+                   <Sparkles size={18} /> Enhance Narrative
+                </span>
+              </button>
+           </div>
+           
+           <div className="my-4 border-t border-[#2D241A]/30"></div>
+           
+           <div className="flex flex-col group relative shrink-0">
+             <div className="flex items-center justify-between mb-4">
+                 <label className="text-xs uppercase tracking-widest text-[#A89880] font-medium">Autogenerated Base Prompt</label>
+                 <button onClick={() => handleCopy(promptOutput)} title="Copy Base Prompt" className="p-1.5 rounded-lg bg-transparent border border-[#2D241A] hover:bg-[#2D241A]/50 text-[#A89880] hover:text-[#DAB062] transition-all"><Copy size={14} /></button>
+             </div>
+             <textarea readOnly value={promptOutput} className="h-40 bg-[#080604] border border-[#1A2E38] rounded-xl p-4 text-xs text-[#E2D1B3] resize-none custom-scrollbar shadow-inner outline-none leading-relaxed"></textarea>
+           </div>
+           
+           <div className="text-center text-[#DAB062] font-cinzel text-xs tracking-[0.2em] my-5 min-h-[20px]">{statusMsg}</div>
+
+           <button 
+             onClick={handleGenerateImage} 
+             className="w-full shrink-0 relative overflow-hidden group bg-gradient-to-r from-[#8C6D3B] via-[#DAB062] to-[#8C6D3B] text-[#0a0805] font-cinzel font-bold text-base tracking-widest py-4 rounded-xl shadow-[0_0_20px_rgba(218,176,98,0.2)] transition-all hover:shadow-[0_0_30px_rgba(218,176,98,0.4)]"
+           >
+              <div className="absolute inset-0 bg-white/20 translate-x-[-100%] group-hover:translate-x-[100%] transition-transform duration-1000 ease-out"></div>
+              <span className="relative z-10 flex items-center justify-center gap-3">
+                 <Wand2 size={22} /> Synthesize 
+              </span>
+           </button>
+
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

oauth_doc.md

@@ -0,0 +1,129 @@
+# Adding a Sign-In with HF button to your Space
+
+You can enable a built-in sign-in flow in your Space by seamlessly creating and associating an [OAuth/OpenID connect](https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc) app so users can log in with their HF account.
+
+This enables new use cases for your Space. For instance, when combined with [Persistent Storage](https://huggingface.co/docs/hub/spaces-storage), a generative AI Space could allow users to log in to access their previous generations, only accessible to them.
+
+> [!TIP]
+> This guide will take you through the process of integrating a *Sign-In with HF* button into any Space. If you're seeking a fast and simple method to implement this in a **Gradio** Space, take a look at its [built-in integration](https://www.gradio.app/guides/sharing-your-app#o-auth-login-via-hugging-face).
+
+> [!TIP]
+> You can also use the HF OAuth flow to create a "Sign in with HF" flow in any website or App, outside of Spaces. [Read our general OAuth page](./oauth).
+
+## Create an OAuth app
+
+All you need to do is add `hf_oauth: true` to your Space's metadata inside your `README.md` file.
+
+Here's an example of metadata for a Gradio Space:
+
+```yaml
+title: Gradio Oauth Test
+emoji: 🏆
+colorFrom: pink
+colorTo: pink
+sdk: gradio
+sdk_version: 3.40.0
+python_version: 3.10.6
+app_file: app.py
+
+hf_oauth: true
+# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
+hf_oauth_expiration_minutes: 480
+# optional, see "Scopes" below. "openid profile" is always included.
+hf_oauth_scopes:
+ - read-repos
+ - write-repos
+ - manage-repos
+ - inference-api
+# optional, restrict access to members of specific organizations
+hf_oauth_authorized_org: ORG_NAME
+hf_oauth_authorized_org:
+  - ORG_NAME1
+  - ORG_NAME2
+```
+
+You can check out the [configuration reference docs](./spaces-config-reference) for more information.
+
+This will add the following [environment variables](https://huggingface.co/docs/hub/spaces-overview#helper-environment-variables) to your space:
+
+- `OAUTH_CLIENT_ID`: the client ID of your OAuth app (public)
+- `OAUTH_CLIENT_SECRET`: the client secret of your OAuth app
+- `OAUTH_SCOPES`: scopes accessible by your OAuth app.
+- `OPENID_PROVIDER_URL`: The URL of the OpenID provider. The OpenID metadata will be available at [`{OPENID_PROVIDER_URL}/.well-known/openid-configuration`](https://huggingface.co/.well-known/openid-configuration).
+
+As for any other environment variable, you can use them in your code by using `os.getenv("OAUTH_CLIENT_ID")`, for example.
+
+## Redirect URLs 
+
+You can use any redirect URL you want, as long as it targets your Space.
+
+Note that `SPACE_HOST` is [available](https://huggingface.co/docs/hub/spaces-overview#helper-environment-variables) as an environment variable.
+
+For example, you can use `https://{SPACE_HOST}/login/callback` as a redirect URI.
+
+## Scopes
+
+The following scopes are always included for Spaces:
+
+- `openid`: Get the ID token in addition to the access token.
+- `profile`: Get the user's profile information (username, avatar, etc.)
+
+Those scopes are optional and can be added by setting `hf_oauth_scopes` in your Space's metadata:
+
+- `email`: Get the user's email address.
+- `read-billing`: Know whether the user has a payment method set up.
+- `read-repos`: Get read access to the user's personal repos.
+- `contribute-repos`: Can create repositories and access those created by this app. Cannot access any other repositories unless additional permissions are granted.
+- `write-repos`: Get write/read access to the user's personal repos.
+- `manage-repos`: Get full access to the user's personal repos. Also grants repo creation and deletion.
+- `inference-api`: Get access to the [Inference Providers](https://huggingface.co/docs/inference-providers/index), you will be able to make inference requests on behalf of the user.
+- `jobs`: Run [jobs](https://huggingface.co/docs/huggingface_hub/main/en/guides/jobs) 
+- `webhooks`: Manage [webhooks](https://huggingface.co/docs/huggingface_hub/main/en/guides/webhooks)
+- `write-discussions`: Open discussions and Pull Requests on behalf of the user as well as interact with discussions (including reactions, posting/editing comments, closing discussions, ...). To open Pull Requests on private repos, you need to request the `read-repos` scope as well.
+
+## Accessing organization resources
+
+By default, the oauth app does not need to access organization resources.
+
+But some scopes like `read-repos` or `read-billing` apply to organizations as well.
+
+The user can select which organizations to grant access to when authorizing the app. If you require access to a specific organization, you can add `orgIds=ORG_ID` as a query parameter to the OAuth authorization URL. You have to replace `ORG_ID` with the organization ID, which is available in the `organizations.sub` field of the userinfo response.
+
+## Adding the button to your Space
+
+You now have all the information to add a "Sign-in with HF" button to your Space. Some libraries ([Python](https://github.com/lepture/authlib), [NodeJS](https://github.com/panva/node-openid-client)) can help you implement the OpenID/OAuth protocol. 
+
+Gradio and huggingface.js also provide **built-in support**, making implementing the Sign-in with HF button a breeze; you can check out the associated guides with [gradio](https://www.gradio.app/guides/sharing-your-app#o-auth-login-via-hugging-face) and with [huggingface.js](https://huggingface.co/docs/huggingface.js/hub/README#oauth-login).
+
+Basically, you need to:
+
+- Redirect the user to `https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}`, where `STATE` is a random string that you will need to verify later.
+- Handle the callback on `/auth/callback` or `/login/callback` (or your own custom callback URL) and verify the `state` parameter.
+- Use the `code` query parameter to get an access token and id token from `https://huggingface.co/oauth/token` (POST request with `client_id`, `code`, `grant_type=authorization_code` and `redirect_uri` as form data, and with `Authorization: Basic {base64(client_id:client_secret)}` as a header).
+
+> [!WARNING]
+> You should use `target=_blank` on the button to open the sign-in page in a new tab, unless you run the space outside its `iframe`. Otherwise, you might encounter issues with cookies on some browsers.
+
+## Examples:
+
+- [Gradio test app](https://huggingface.co/spaces/Wauplin/gradio-oauth-test)
+- [HuggingChat (NodeJS/SvelteKit)](https://huggingface.co/spaces/huggingchat/chat-ui)
+- [Inference Widgets (Auth.js/SvelteKit)](https://huggingface.co/spaces/huggingfacejs/inference-widgets), uses the `inference-api` scope to make inference requests on behalf of the user.
+- [Client-Side in a Static Space (huggingface.js)](https://huggingface.co/spaces/huggingfacejs/client-side-oauth) - very simple JavaScript example.
+
+JS Code example:
+
+```js
+import { oauthLoginUrl, oauthHandleRedirectIfPresent } from "@huggingface/hub";
+
+const oauthResult = await oauthHandleRedirectIfPresent();
+
+if (!oauthResult) {
+  // If the user is not logged in, redirect to the login page
+  window.location.href = await oauthLoginUrl();
+}
+
+// You can use oauthResult.accessToken, oauthResult.userInfo among other things
+console.log(oauthResult);
+```
+

requirements.txt

@@ -7,4 +7,7 @@ Pillow
 huggingface_hub
 fictional-names
 openai
-python-dotenv
+fastapi
+uvicorn
+pydantic
+python-multipart