feat: refine AI backend options and UI layout

- Curated Hugging Face model lists (4 text, 4 image models).
- Added manual Inference Provider support for HF backend (e.g., fal-ai).
- Set default HF provider to 'auto' for robust model discovery.
- Relocated 'Generate Image' button to the right column for better UX.
- Improved error handling for prompt refinement to prevent UI प्रदूषण.
- Added MIT License and updated README with new features and usage info.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Topguy (and contributors)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -15,9 +15,13 @@ RPGPortrait is a Gradio-based web application that helps users build highly deta
 
 ## Features
 - **25+ Character Parameters**: Deep customization including Identity, Appearance, Equipment, Environment, VFX, and Technical settings.
-- **🧠 AI Refinement**: Intelligent prompt enhancement using **Gemini (Cloud)**, **Hugging Face (Cloud)**, or **Ollama (Local)**.
+- **🧠 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.
@@ -25,6 +29,7 @@ RPGPortrait is a Gradio-based web application that helps users build highly deta
 - **🎒 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
@@ -41,19 +46,17 @@ RPGPortrait is a Gradio-based web application that helps users build highly deta
    ```bash
    pip install -r requirements.txt
    ```
-5. **Set up Gemini API**:
+5. **Set up API Keys**:
    - Create a `.env` file in the root directory.
    - Add your keys and connection info:
    ```env
-   GEMINI_API_KEY=your_api_key_here
+   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
-   OLLAMA_MODEL=llama3
    ```
- 6. **Configure AI Prompts**:
-    - Modify `prompts.yaml` to adjust the refinement logic without changing code.
 
 ## Usage
 
@@ -62,13 +65,15 @@ RPGPortrait is a Gradio-based web application that helps users build highly deta
    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 and watch the technical prompt update in real-time.
-4. **Refine & Generate**: 
-    - Choose a **Refinement Backend** (Gemini or Ollama).
-    - If using Ollama, select your model.
-    - Click **🧠 Refine with Gemini** (or Ollama depending on selection) to polish your prompt.
-    - Click **🖼️ Generate Image** to create your portrait.
-5. **Save/Load**: Use the 💾 and 📂 buttons to manage your character library.
+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.
 
-## Configuration
-All dropdown options and the final prompt template are defined in `features.yaml`. You can customize the behavior of the prompt generator without touching the Python code.
+## License
+
+This project is licensed under the [MIT License](LICENSE).

modules/config.py

@@ -19,6 +19,19 @@ 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"
 
+HF_TEXT_MODELS = [
+    "Qwen/Qwen2.5-72B-Instruct",
+    "meta-llama/Llama-3.1-70B-Instruct",
+    "mistralai/Mistral-7B-Instruct-v0.3",
+    "microsoft/Phi-3-mini-4k-instruct"
+]
+
+HF_IMAGE_MODELS = [
+    "black-forest-labs/FLUX.1-dev",
+    "Tongyi-MAI/Z-Image-Turbo",
+    "Qwen/Qwen-Image-2512"
+]
+
 # Gemini Settings
 GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
 GEMINI_TEXT_MODEL = "gemini-3-pro-preview"

modules/integrations.py

@@ -96,7 +96,9 @@ def refine_with_gemini(prompt, mode="refinement"):
         )
         return response.text.strip()
     except Exception as e:
-        return f"Error refining prompt with Gemini: {e}"
+        print(f"Gemini Refinement Error: {e}")
+        traceback.print_exc()
+        return None
 
 def refine_with_ollama(prompt, model, mode="refinement"):
     """Refines the prompt using a local Ollama instance."""
@@ -121,9 +123,10 @@ def refine_with_ollama(prompt, model, mode="refinement"):
             text = "\n".join(lines).strip()
         return text
     except Exception as e:
-        return f"Error refining prompt with Ollama: {e}"
+        print(f"Ollama Refinement Error: {e}")
+        return None
 
-def refine_with_hf(prompt, token=None, mode="refinement"):
+def refine_with_hf(prompt, model_id=None, provider=None, token=None, mode="refinement"):
     """Refines the prompt using Hugging Face Router (OpenAI compatible)."""
     active_client = hf_client
     
@@ -141,7 +144,8 @@ def refine_with_hf(prompt, token=None, mode="refinement"):
         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
+    active_model = model_id if model_id else HF_TEXT_MODEL
+    active_provider = provider if provider and provider.strip() else "auto"
     
     try:
         messages = [
@@ -149,17 +153,21 @@ def refine_with_hf(prompt, token=None, mode="refinement"):
             {"role": "user", "content": f"Original Prompt: {prompt}"}
         ]
         
+        # Note: Provider for Chat Completions is currently handled by the route or specific model naming conventions.
+        # But we pass it if the client supports it or for future use.
         response = active_client.chat.completions.create(
-            model=model_id,
+            model=active_model,
             messages=messages,
             max_tokens=500,
-            temperature=0.7
+            temperature=0.7,
+            extra_body={"provider": active_provider}
         )
         return response.choices[0].message.content.strip()
     except Exception as e:
-        return f"Hugging Face Router Error: {e}"
+        print(f"HF Refinement Error: {e}")
+        return None
 
-def refine_master(prompt, backend, ollama_model, manual_token=None, character_name=None):
+def refine_master(prompt, backend, ollama_model, hf_text_model, hf_text_provider, manual_token=None, character_name=None):
     """Routes prompt refinement to the selected backend."""
     if not prompt.strip():
         return ""
@@ -168,13 +176,18 @@ def refine_master(prompt, backend, ollama_model, manual_token=None, character_na
     hf_token = manual_token.strip() if manual_token and manual_token.strip() else None
     
     if backend == "Ollama (Local)":
-        return refine_with_ollama(prompt, ollama_model, mode="refinement")
+        result = refine_with_ollama(prompt, ollama_model, mode="refinement")
     elif backend == "Hugging Face (Cloud)":
-        return refine_with_hf(prompt, hf_token, mode="refinement")
+        result = refine_with_hf(prompt, hf_text_model, hf_text_provider, hf_token, mode="refinement")
     else:
-        return refine_with_gemini(prompt, mode="refinement")
+        result = refine_with_gemini(prompt, mode="refinement")
+    
+    if result is None:
+        return gr.update(), f"⚠️ Refinement failed. Check console for details. Original prompt preserved."
+    
+    return result, ""
 
-def generate_name_master(prompt, backend, ollama_model, manual_token=None):
+def generate_name_master(prompt, backend, ollama_model, hf_text_model, hf_text_provider, manual_token=None):
     """Generates a thematic name based on the current prompt context."""
     if not prompt.strip():
         return "Unnamed Hero"
@@ -182,11 +195,13 @@ def generate_name_master(prompt, backend, ollama_model, manual_token=None):
     hf_token = manual_token.strip() if manual_token and manual_token.strip() else None
     
     if backend == "Ollama (Local)":
-        return refine_with_ollama(prompt, ollama_model, mode="naming")
+        result = refine_with_ollama(prompt, ollama_model, mode="naming")
     elif backend == "Hugging Face (Cloud)":
-        return refine_with_hf(prompt, hf_token, mode="naming")
+        result = refine_with_hf(prompt, hf_text_model, hf_text_provider, hf_token, mode="naming")
     else:
-        return refine_with_gemini(prompt, mode="naming")
+        result = refine_with_gemini(prompt, mode="naming")
+    
+    return result if result else "Unnamed Hero"
 
 def generate_image_with_gemini(refined_prompt, technical_prompt, aspect_ratio, character_name="Unnamed Hero"):
     if not gemini_active:
@@ -292,13 +307,14 @@ def generate_image_with_comfy(prompt, aspect_ratio, character_name="Unnamed Hero
         traceback.print_exc()
         return None, None, f"ComfyUI Error: {e}"
 
-def generate_image_with_hf(prompt, aspect_ratio, token=None, character_name="Unnamed Hero"):
+def generate_image_with_hf(prompt, aspect_ratio, model_id=None, provider=None, token=None, character_name="Unnamed Hero"):
     """Generates an image using Hugging Face Inference API."""
     active_token = token if token else HF_TOKEN
     if not active_token:
         return None, None, "Error: Hugging Face token not found. Please log in or provide a token."
     
-    model_id = HF_IMAGE_MODEL
+    active_model = model_id if model_id else HF_IMAGE_MODEL
+    active_provider = provider if provider and provider.strip() else "auto"
     
     # Resolution mapping
     res_map = {
@@ -311,8 +327,8 @@ def generate_image_with_hf(prompt, aspect_ratio, token=None, character_name="Unn
     width, height = res_map.get(aspect_ratio, (1024, 1024))
     
     try:
-        client = InferenceClient(api_key=active_token)
-        img = client.text_to_image(prompt, model=model_id, width=width, height=height)
+        client = InferenceClient(api_key=active_token, provider=active_provider)
+        img = client.text_to_image(prompt, model=active_model, width=width, height=height)
         
         # Embed metadata
         metadata = PngInfo()
@@ -325,12 +341,12 @@ def generate_image_with_hf(prompt, aspect_ratio, token=None, character_name="Unn
         temp_dir = tempfile.mkdtemp()
         img_path = os.path.join(temp_dir, filename)
         img.save(img_path, "PNG", pnginfo=metadata)
-        return img, img_path, f"Image generated via Hugging Face ({model_id})!"
+        return img, img_path, f"Image generated via Hugging Face ({active_model})!"
     except Exception as e:
         traceback.print_exc()
         return None, None, f"Hugging Face Image Error: {e}"
 
-def generate_image_master(refined_prompt, technical_prompt, aspect_ratio, backend, manual_token=None, character_name="Unnamed Hero"):
+def generate_image_master(refined_prompt, technical_prompt, aspect_ratio, backend, hf_image_model, hf_image_provider, manual_token=None, character_name="Unnamed Hero"):
     """Routes image generation to the selected backend."""
     final_prompt = refined_prompt.strip() if refined_prompt.strip() else technical_prompt
     
@@ -340,6 +356,6 @@ def generate_image_master(refined_prompt, technical_prompt, aspect_ratio, backen
     if backend == "ComfyUI (Local)":
         return generate_image_with_comfy(final_prompt, aspect_ratio, character_name)
     elif backend == "Hugging Face (Cloud)":
-        return generate_image_with_hf(final_prompt, aspect_ratio, hf_token, character_name)
+        return generate_image_with_hf(final_prompt, aspect_ratio, hf_image_model, hf_image_provider, hf_token, character_name)
     else:
         return generate_image_with_gemini(refined_prompt, technical_prompt, aspect_ratio, character_name)

modules/ui_layout.py

@@ -1,5 +1,5 @@
 import gradio as gr
-from .config import FEATURE_SEQUENCE, SECTIONS
+from .config import FEATURE_SEQUENCE, SECTIONS, HF_TEXT_MODELS, HF_IMAGE_MODELS, GEMINI_API_KEY
 from .core_logic import (
     features_data, generate_prompt, handle_regeneration, 
     save_character, load_character, get_example_list, load_example_character
@@ -137,38 +137,65 @@ def build_ui():
                         ollama_active = len(ollama_models) > 0
                         comfy_active = check_comfy_availability()
                         
-                        refinement_choices = ["Gemini (Cloud)", "Hugging Face (Cloud)"]
+                        refinement_choices = ["Hugging Face (Cloud)"]
+                        if GEMINI_API_KEY:
+                            refinement_choices.insert(0, "Gemini (Cloud)")
                         if ollama_active:
                             refinement_choices.append("Ollama (Local)")
                             
                         refinement_backend = gr.Radio(
                             choices=refinement_choices,
-                            value="Gemini (Cloud)",
+                            value=refinement_choices[0],
                             label="Prompt Refinement Backend",
                             scale=2
                         )
                         
-                        ollama_model_dropdown = gr.Dropdown(
-                            choices=ollama_models,
-                            value=ollama_models[0] if ollama_active else None,
-                            label="Ollama Model",
-                            visible=False,
-                            scale=1
-                        )
+                        with gr.Column(scale=1):
+                            ollama_model_dropdown = gr.Dropdown(
+                                choices=ollama_models,
+                                value=ollama_models[0] if ollama_active else None,
+                                label="Olama Model",
+                                visible=False
+                            )
+                            hf_text_model_dropdown = gr.Dropdown(
+                                choices=HF_TEXT_MODELS,
+                                value=HF_TEXT_MODELS[0],
+                                label="HF Text Model",
+                                visible=("Hugging Face (Cloud)" in refinement_choices and refinement_choices[0] == "Hugging Face (Cloud)")
+                            )
+                            hf_text_provider_input = gr.Textbox(
+                                value="auto",
+                                placeholder="Optional: e.g. fal-ai",
+                                label="HF Text Provider",
+                                visible=("Hugging Face (Cloud)" in refinement_choices and refinement_choices[0] == "Hugging Face (Cloud)")
+                            )
                     
                     with gr.Row():
-                        img_choices = ["Gemini (Cloud)", "Hugging Face (Cloud)"]
+                        img_choices = ["Hugging Face (Cloud)"]
+                        if GEMINI_API_KEY:
+                            img_choices.insert(0, "Gemini (Cloud)")
                         if comfy_active:
                             img_choices.append("ComfyUI (Local)")
                             
                         backend_selector = gr.Radio(
                             choices=img_choices, 
-                            value="Gemini (Cloud)", 
+                            value=img_choices[0], 
                             label="Image Generation Backend",
                             scale=2
                         )
                         with gr.Column(scale=1):
-                            gen_img_btn = gr.Button("🖼️ Generate Image", variant="primary")
+                            hf_image_model_dropdown = gr.Dropdown(
+                                choices=HF_IMAGE_MODELS,
+                                value=HF_IMAGE_MODELS[0],
+                                label="HF Image Model",
+                                visible=("Hugging Face (Cloud)" in img_choices and img_choices[0] == "Hugging Face (Cloud)")
+                            )
+                            hf_image_provider_input = gr.Textbox(
+                                value="auto",
+                                placeholder="Optional: e.g. fal-ai",
+                                label="HF Image Provider",
+                                visible=("Hugging Face (Cloud)" in img_choices and img_choices[0] == "Hugging Face (Cloud)")
+                            )
 
                     with gr.Row():
                         with gr.Column(scale=1):
@@ -190,6 +217,7 @@ def build_ui():
                 
                 gr.Markdown("---")
                 image_output = gr.Image(label="Portrait", show_label=False)
+                gen_img_btn = gr.Button("🖼️ Generate Image", variant="primary", scale=1)
                 download_img_btn = gr.DownloadButton("📥 Download Portrait (PNG)", variant="secondary", visible=False)
                 status_msg = gr.Markdown("")
                 download_file = gr.File(label="Saved Character JSON", visible=False)
@@ -220,13 +248,13 @@ def build_ui():
 
         refine_btn.click(
             fn=refine_master,
-            inputs=[prompt_output, refinement_backend, ollama_model_dropdown, hf_token_input, character_name],
-            outputs=refined_output
+            inputs=[prompt_output, refinement_backend, ollama_model_dropdown, hf_text_model_dropdown, hf_text_provider_input, hf_token_input, character_name],
+            outputs=[refined_output, status_msg]
         )
 
         gen_img_btn.click(
             fn=generate_image_master,
-            inputs=[refined_output, prompt_output, dropdowns[-1], backend_selector, hf_token_input, character_name],
+            inputs=[refined_output, prompt_output, dropdowns[-1], backend_selector, hf_image_model_dropdown, hf_image_provider_input, hf_token_input, character_name],
             outputs=[image_output, download_img_btn, status_msg]
         ).then(
             fn=lambda x: gr.update(value=x, visible=True) if x else gr.update(visible=False),
@@ -235,9 +263,22 @@ def build_ui():
         )
 
         refinement_backend.change(
-            fn=lambda b: gr.update(visible=(b == "Ollama (Local)")),
+            fn=lambda b: (
+                gr.update(visible=(b == "Ollama (Local)")), 
+                gr.update(visible=(b == "Hugging Face (Cloud)")),
+                gr.update(visible=(b == "Hugging Face (Cloud)"))
+            ),
             inputs=refinement_backend,
-            outputs=ollama_model_dropdown
+            outputs=[ollama_model_dropdown, hf_text_model_dropdown, hf_text_provider_input]
+        )
+
+        backend_selector.change(
+            fn=lambda b: (
+                gr.update(visible=(b == "Hugging Face (Cloud)")),
+                gr.update(visible=(b == "Hugging Face (Cloud)"))
+            ),
+            inputs=backend_selector,
+            outputs=[hf_image_model_dropdown, hf_image_provider_input]
         )
 
         save_btn.click(