feat: integrate HF Router and enhance UI workflow

- Switched Hugging Face integration to the OpenAI-compatible Router.
- Refactored `modules/integrations.py` to use `openai` SDK.
- Updated `modules/config.py` with `HF_BASE_URL` and `Qwen/Qwen2.5-72B-Instruct` model.
- Implemented dynamic backend availability checking for Ollama and ComfyUI at startup.
- Fixed refined prompt persistence issue when loading characters.
- Fixed aspect ratio handling for Hugging Face image generation.
- Renamed "Settings & Generation" section to "AI Backend Configuration" and relocated "Refine Prompt" button for better workflow.
- Updated `requirements.txt` with `openai` and `python-dotenv`.

features.yaml

@@ -42,6 +42,13 @@ appearance:
     Blue: "deep sapphire blue"
     Green: "forest green"
     Purple: "regal purple"
+    Salt and Pepper: "salt and pepper"
+    Dirty Blonde: "dusty dirty blonde"
+    Auburn: "rich auburn"
+    Copper: "burnished copper"
+    Platinum: "pale platinum blonde"
+    Pink: "soft pastel pink"
+    Teal: "vibrant teal"
   hair_style:
     Short: "neatly trimmed short"
     Long: "flowing long"
@@ -51,6 +58,9 @@ appearance:
     Ponytail: "tied back in a ponytail"
     Bun: "styled in a tight bun"
     Curly: "thickly curly"
+    Mohawk: "a sharp, jagged mohawk"
+    Undercut: "a stylish undercut"
+    Dreadlocks: "thick, well-maintained dreadlocks"
   eye_color:
     Brown: "warm brown"
     Blue: "piercing blue"
@@ -59,6 +69,9 @@ appearance:
     Amber: "glowing amber"
     Red: "intense crimson red"
     Violet: "mysterious violet"
+    Heterochromia: "mismatched, with one blue and one brown eye"
+    Cloudy: "milky white and cloudy, suggesting blindness"
+    Black: "solid, ink-black voids"
   build:
     Athletic: "an athletic and toned"
     Muscular: "a powerful, muscular"
@@ -66,6 +79,7 @@ appearance:
     Stocky: "a solid and stocky"
     Average: "a well-proportioned"
     Scrawny: "a thin and scrawny"
+    Towering: "a towering and massive"
   skin_tone:
     Pale: "porcelain pale"
     Fair: "smooth fair"
@@ -73,6 +87,9 @@ appearance:
     Olive: "warm olive"
     Dark: "rich dark"
     Deep: "deep ebony"
+    Alabaster: "ghostly alabaster"
+    Vitiligo: "mottled with striking vitiligo patterns"
+    Ashen: "pale, ashen grey"
   distinguishing_feature:
     Scars: "a collection of jagged battle scars across the face"
     Tattoos: "intricate glowing tattoos covering the neck and arms"
@@ -80,6 +97,9 @@ appearance:
     Cybernetic Eye: "a glowing cybernetic eye that whirrs softly"
     Glowing Runes: "mystical runes etched into the skin that pulse with light"
     Jeweled Bindi: "a shimmering jeweled bindi placed between the brows"
+    Mechanical Jaw: "a heavy, reinforced mechanical jaw"
+    Third Eye: "a mystical third eye centered on the forehead"
+    Burn Marks: "faint, web-like burn marks tracing down the neck"
     None: "no particularly distinguishing facial features"
 
 expression_pose:
@@ -98,6 +118,13 @@ expression_pose:
     Ready Stance: "crouched in a dynamic ready stance"
     Meditating: "seated in a peaceful meditating position"
     Action: "frozen in the middle of a powerful action"
+    Kneeling: "humbly kneeling on one knee"
+    Floating: "magically floating inches above the ground"
+    Weapon Maintenance: "focused on meticulously sharpening their weapon"
+    Casting: "with hands glowing, in the middle of casting a powerful spell"
+    Defending: "braced firmly behind a raised shield"
+    Sitting: "seated regally upon an ornate throne"
+    Crouching: "crouched low, blending into the shadows"
 
 equipment:
   armor:
@@ -156,6 +183,14 @@ environment:
     Mountains: "rugged mountain peak against a dramatic sky"
     City Street: "bustling medieval city street with cobblestones"
     Abstract Magic: "swirling vortex of abstract magical energy"
+    Desert: "vast desert with shifting orange sands"
+    Arctic: "frozen arctic tundra under a pale sun"
+    Steampunk Lab: "cluttered steampunk laboratory with hissing brass pipes"
+    Volcanic Cave: "dark volcanic cave with rivers of molten lava"
+    Enchanted Grove: "ethereal grove filled with giant glowing mushrooms"
+    Ruined Temple: "ancient ruined temple overgrown with thick ivy"
+    Cyberpunk Street: "rain-slicked cyberpunk street with neon holographic signs"
+    Undersea: "majestic undersea city surrounded by coral and bubbles"
   lighting:
     Natural Sunlight: "bathed in warm, natural sunlight"
     Dim Torchlight: "illuminated by the flickering glow of dim torchlight"

hf_example.py

@@ -1,23 +0,0 @@
-import os
-from openai import OpenAI
-from dotenv import load_dotenv
-
-# Load environment variables
-load_dotenv()
-
-client = OpenAI(
-    base_url="https://router.huggingface.co/v1",
-    api_key=os.environ["HF_TOKEN"],
-)
-
-completion = client.completions.create(
-    model="mistralai/Mixtral-8x22B-Instruct-v0.1:fireworks-ai",
-    messages=[
-        {
-            "role": "user",
-            "content": "Calculate the weight of the earth."
-        }
-    ],
-)
-
-print(completion.choices[0].message)

hf_hub_example.py

@@ -1,13 +0,0 @@
-import os
-from huggingface_hub import InferenceClient
-
-client = InferenceClient(
-    provider="replicate",
-    api_key=os.environ["HF_TOKEN"],
-)
-
-# output is a PIL.Image object
-image = client.text_to_image(
-    "Astronaut riding a horse",
-    model="ByteDance/SDXL-Lightning",
-)

modules/config.py

@@ -15,8 +15,9 @@ OLLAMA_HOST = os.getenv("OLLAMA_HOST", "127.0.0.1")
 OLLAMA_PORT = os.getenv("OLLAMA_PORT", "11434")
 OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "llama3")
 HF_TOKEN = os.getenv("HF_TOKEN")
-HF_TEXT_MODEL = "mistralai/Mistral-7B-Instruct-v0.2"
-HF_IMAGE_MODEL = "black-forest-labs/FLUX.1-schnell"
+HF_BASE_URL = "https://router.huggingface.co/v1"
+HF_TEXT_MODEL = "Qwen/Qwen2.5-72B-Instruct"
+HF_IMAGE_MODEL = "black-forest-labs/FLUX.1-dev"
 
 # Gemini Settings
 GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

modules/integrations.py

@@ -2,6 +2,7 @@ import os
 import requests
 import json
 import gradio as gr
+from openai import OpenAI
 import uuid
 import time
 import io
@@ -16,7 +17,7 @@ from google import genai
 from google.genai import types
 from .config import (
     GEMINI_API_KEY, OLLAMA_HOST, OLLAMA_PORT, COMFY_URL, 
-    COMFY_WORKFLOW_FILE, PROMPTS_FILE, HF_TOKEN, 
+    COMFY_WORKFLOW_FILE, PROMPTS_FILE, HF_TOKEN, HF_BASE_URL,
     HF_TEXT_MODEL, HF_IMAGE_MODEL, GEMINI_TEXT_MODEL, 
     GEMINI_IMAGE_MODEL
 )
@@ -31,6 +32,17 @@ if GEMINI_API_KEY:
     except Exception as e:
         print(f"Error initializing Gemini: {e}")
 
+# Setup Hugging Face Router
+hf_client = None
+if HF_TOKEN:
+    try:
+        hf_client = OpenAI(
+            base_url=HF_BASE_URL,
+            api_key=HF_TOKEN,
+        )
+    except Exception as e:
+        print(f"Error initializing HF Client: {e}")
+
 def load_system_prompt(key="refinement"):
     """Loads a system prompt from prompts.yaml."""
     try:
@@ -53,6 +65,14 @@ def get_ollama_models():
     except Exception:
         return []
 
+def check_comfy_availability():
+    """Checks if ComfyUI is running by pinging the URL."""
+    try:
+        response = requests.get(f"{COMFY_URL}/system_stats", timeout=2)
+        return response.status_code == 200
+    except Exception:
+        return False
+
 def refine_with_gemini(prompt, mode="refinement"):
     if not gemini_active:
         return "Gemini API key not found in .env file."
@@ -104,22 +124,32 @@ def refine_with_ollama(prompt, model, mode="refinement"):
         return f"Error refining prompt with Ollama: {e}"
 
 def refine_with_hf(prompt, token=None, mode="refinement"):
-    """Refines the prompt using Hugging Face Inference API."""
-    active_token = token if token else HF_TOKEN
-    if not active_token:
+    """Refines the prompt using Hugging Face Router (OpenAI compatible)."""
+    active_client = hf_client
+    
+    # If a manual token is provided, create a temporary client
+    if token:
+        try:
+            active_client = OpenAI(
+                base_url=HF_BASE_URL,
+                api_key=token,
+            )
+        except Exception as e:
+            return f"Error initializing manual HF Client: {e}"
+            
+    if not active_client:
         return "Error: Hugging Face token not found. Please log in or provide a token."
     
     system_prompt = load_system_prompt(mode)
     model_id = HF_TEXT_MODEL
     
     try:
-        client = InferenceClient(api_key=active_token)
         messages = [
             {"role": "system", "content": system_prompt},
             {"role": "user", "content": f"Original Prompt: {prompt}"}
         ]
         
-        response = client.chat.completions.create(
+        response = active_client.chat.completions.create(
             model=model_id,
             messages=messages,
             max_tokens=500,
@@ -127,7 +157,7 @@ def refine_with_hf(prompt, token=None, mode="refinement"):
         )
         return response.choices[0].message.content.strip()
     except Exception as e:
-        return f"Hugging Face Error: {e}"
+        return f"Hugging Face Router Error: {e}"
 
 def refine_master(prompt, backend, ollama_model, manual_token=None, character_name=None):
     """Routes prompt refinement to the selected backend."""
@@ -269,15 +299,24 @@ def generate_image_with_hf(prompt, aspect_ratio, token=None, character_name="Unn
         return None, None, "Error: Hugging Face token not found. Please log in or provide a token."
     
     model_id = HF_IMAGE_MODEL
-    final_prompt = f"{prompt}, aspect ratio {aspect_ratio}"
+    
+    # Resolution mapping
+    res_map = {
+        "1:1": (1024, 1024),
+        "16:9": (1344, 768),
+        "9:16": (768, 1344),
+        "4:3": (1152, 864),
+        "3:4": (864, 1152)
+    }
+    width, height = res_map.get(aspect_ratio, (1024, 1024))
     
     try:
         client = InferenceClient(api_key=active_token)
-        img = client.text_to_image(final_prompt, model=model_id)
+        img = client.text_to_image(prompt, model=model_id, width=width, height=height)
         
         # Embed metadata
         metadata = PngInfo()
-        metadata.add_text("Comment", final_prompt)
+        metadata.add_text("Comment", prompt)
         metadata.add_text("CharacterName", character_name)
         
         safe_name = "".join([c if c.isalnum() else "_" for c in character_name]).strip("_")

modules/ui_layout.py

@@ -5,7 +5,7 @@ from .core_logic import (
     save_character, load_character, get_example_list, load_example_character
 )
 from .integrations import (
-    get_ollama_models, refine_master, generate_image_master
+    get_ollama_models, check_comfy_availability, refine_master, generate_image_master
 )
 from .name_generator import generate_fantasy_name
 
@@ -100,13 +100,18 @@ def build_ui():
                     load_btn = gr.UploadButton("📂 Load Character", file_types=[".json"], variant="secondary", scale=1)
                 
                 with gr.Group():
-                    gr.Markdown("### ⚙️ Settings & Generation")
+                    gr.Markdown("### ⚙️ AI Backend Configuration")
                     with gr.Row():
                         ollama_models = get_ollama_models()
                         ollama_active = len(ollama_models) > 0
+                        comfy_active = check_comfy_availability()
                         
+                        refinement_choices = ["Gemini (Cloud)", "Hugging Face (Cloud)"]
+                        if ollama_active:
+                            refinement_choices.append("Ollama (Local)")
+                            
                         refinement_backend = gr.Radio(
-                            choices=["Gemini (Cloud)", "Hugging Face (Cloud)", "Ollama (Local)"] if ollama_active else ["Gemini (Cloud)", "Hugging Face (Cloud)"],
+                            choices=refinement_choices,
                             value="Gemini (Cloud)",
                             label="Prompt Refinement Backend",
                             scale=2
@@ -121,14 +126,17 @@ def build_ui():
                         )
                     
                     with gr.Row():
+                        img_choices = ["Gemini (Cloud)", "Hugging Face (Cloud)"]
+                        if comfy_active:
+                            img_choices.append("ComfyUI (Local)")
+                            
                         backend_selector = gr.Radio(
-                            choices=["Gemini (Cloud)", "Hugging Face (Cloud)", "ComfyUI (Local)"], 
+                            choices=img_choices, 
                             value="Gemini (Cloud)", 
                             label="Image Generation Backend",
                             scale=2
                         )
                         with gr.Column(scale=1):
-                            refine_btn = gr.Button("🧠 Refine Prompt", variant="primary")
                             gen_img_btn = gr.Button("🖼️ Generate Image", variant="primary")
 
                     with gr.Row():
@@ -145,6 +153,7 @@ def build_ui():
             with gr.Column(scale=1):
                 gr.Markdown("### 📝 Prompts & Output")
                 prompt_output = gr.Textbox(label="Generated Technical Prompt", lines=4, interactive=False, buttons=["copy"])
+                refine_btn = gr.Button("🧠 Refine Prompt", variant="primary")
                 regenerate_btn = gr.Button("✨ Randomize Features", variant="secondary")
                 refined_output = gr.Textbox(label="Refined Artistic Prompt", lines=6, interactive=True, buttons=["copy", "paste", "clear"])
                 
@@ -217,6 +226,9 @@ def build_ui():
             fn=generate_prompt,
             inputs=all_input_components,
             outputs=prompt_output
+        ).then(
+            fn=lambda: "",
+            outputs=refined_output
         )
 
         load_example_btn.click(
@@ -227,6 +239,9 @@ def build_ui():
             fn=generate_prompt,
             inputs=all_input_components,
             outputs=prompt_output
+        ).then(
+            fn=lambda: "",
+            outputs=refined_output
         )
         
         demo.load(fn=generate_prompt, inputs=all_input_components, outputs=prompt_output)

requirements.txt

@@ -6,3 +6,5 @@ requests
 Pillow
 huggingface_hub
 fictional-names
+openai
+python-dotenv