Upload 11 files

Creating New Feature: Inpainting mode

app.py

@@ -1,4 +1,5 @@
 import sys
+import traceback
 import warnings
 warnings.filterwarnings("ignore")
 
@@ -26,13 +27,11 @@ def launch_final_blend_sceneweaver(share: bool = True, debug: bool = False):
             return interface
 
         except ImportError as import_error:
-            import traceback
             print(f"❌ Import failed: {import_error}")
             print(f"Traceback: {traceback.format_exc()}")
             raise
 
     except Exception as e:
-        import traceback
         print(f"❌ Failed to launch: {e}")
         print(f"Full traceback: {traceback.format_exc()}")
         raise

css_styles.py

@@ -512,6 +512,235 @@ class CSSStyles:
             font-size: 0.95rem !important;
         }
 
+        /* ===== INPAINTING UI STYLES ===== */
+        .inpainting-header {
+            text-align: center !important;
+            padding: 16px !important;
+            margin-bottom: 16px !important;
+            background: linear-gradient(135deg, var(--primary-light) 0%, var(--accent-light) 100%) !important;
+            border-radius: var(--radius-lg) !important;
+            border: 1px solid var(--border-color) !important;
+        }
+
+        .inpainting-header h3 {
+            font-size: 1.4rem !important;
+            font-weight: 600 !important;
+            color: var(--primary-color) !important;
+            margin: 0 0 8px 0 !important;
+        }
+
+        .inpainting-header p {
+            font-size: 0.95rem !important;
+            color: var(--text-secondary) !important;
+            margin: 0 !important;
+        }
+
+        /* Main mode tabs styling */
+        #main-mode-tabs {
+            margin-bottom: 16px !important;
+        }
+
+        #main-mode-tabs > .tab-nav {
+            background: var(--bg-secondary) !important;
+            border-radius: var(--radius-lg) !important;
+            padding: 6px !important;
+            gap: 6px !important;
+            border: 1px solid var(--border-color) !important;
+        }
+
+        #main-mode-tabs > .tab-nav > button {
+            border-radius: var(--radius-md) !important;
+            padding: 12px 24px !important;
+            font-weight: 600 !important;
+            font-size: 1rem !important;
+            transition: all var(--transition-normal) !important;
+            border: none !important;
+            background: transparent !important;
+            color: var(--text-secondary) !important;
+        }
+
+        #main-mode-tabs > .tab-nav > button.selected {
+            background: linear-gradient(135deg, var(--accent-color) 0%, var(--accent-hover) 100%) !important;
+            color: white !important;
+            box-shadow: var(--shadow-md) !important;
+        }
+
+        #main-mode-tabs > .tab-nav > button:hover:not(.selected) {
+            background: var(--bg-primary) !important;
+            color: var(--text-primary) !important;
+        }
+
+        /* Mask editor styling */
+        .mask-editor-container {
+            border: 2px dashed var(--border-color) !important;
+            border-radius: var(--radius-lg) !important;
+            padding: 8px !important;
+            background: var(--bg-secondary) !important;
+            transition: border-color var(--transition-fast) !important;
+        }
+
+        .mask-editor-container:hover {
+            border-color: var(--accent-color) !important;
+        }
+
+        /* Inpainting template cards */
+        .inpainting-gallery {
+            margin: 16px 0 !important;
+        }
+
+        .inpainting-category {
+            margin-bottom: 20px !important;
+        }
+
+        .inpainting-category-title {
+            font-size: 0.9rem !important;
+            font-weight: 600 !important;
+            color: var(--text-secondary) !important;
+            margin-bottom: 12px !important;
+            padding-bottom: 8px !important;
+            border-bottom: 1px solid var(--border-color) !important;
+        }
+
+        .inpainting-grid {
+            display: grid !important;
+            grid-template-columns: repeat(auto-fill, minmax(120px, 1fr)) !important;
+            gap: 10px !important;
+        }
+
+        .inpainting-card {
+            display: flex !important;
+            flex-direction: column !important;
+            align-items: center !important;
+            justify-content: center !important;
+            padding: 14px 10px !important;
+            background: var(--bg-primary) !important;
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-md) !important;
+            cursor: pointer !important;
+            transition: all var(--transition-normal) !important;
+            min-height: 80px !important;
+        }
+
+        .inpainting-card:hover {
+            background: var(--accent-light) !important;
+            border-color: var(--accent-color) !important;
+            transform: translateY(-2px) !important;
+            box-shadow: var(--shadow-md) !important;
+        }
+
+        .inpainting-card.selected {
+            background: var(--accent-light) !important;
+            border-color: var(--accent-color) !important;
+            box-shadow: 0 0 0 2px var(--accent-color) !important;
+        }
+
+        .inpainting-icon {
+            font-size: 1.6rem !important;
+            margin-bottom: 6px !important;
+        }
+
+        .inpainting-name {
+            font-size: 0.8rem !important;
+            font-weight: 500 !important;
+            color: var(--text-primary) !important;
+            text-align: center !important;
+            line-height: 1.2 !important;
+        }
+
+        .inpainting-desc {
+            font-size: 0.7rem !important;
+            color: var(--text-muted) !important;
+            text-align: center !important;
+            margin-top: 4px !important;
+        }
+
+        /* ControlNet mode toggle */
+        .controlnet-mode-toggle {
+            display: flex !important;
+            gap: 8px !important;
+            margin: 8px 0 !important;
+        }
+
+        .controlnet-mode-btn {
+            flex: 1 !important;
+            padding: 10px 16px !important;
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-md) !important;
+            background: var(--bg-primary) !important;
+            color: var(--text-secondary) !important;
+            font-weight: 500 !important;
+            cursor: pointer !important;
+            transition: all var(--transition-fast) !important;
+        }
+
+        .controlnet-mode-btn:hover {
+            border-color: var(--accent-color) !important;
+            color: var(--accent-color) !important;
+        }
+
+        .controlnet-mode-btn.active {
+            background: var(--accent-color) !important;
+            border-color: var(--accent-color) !important;
+            color: white !important;
+        }
+
+        /* Preview badge */
+        .preview-badge {
+            display: inline-flex !important;
+            align-items: center !important;
+            gap: 4px !important;
+            padding: 4px 10px !important;
+            background: var(--warning-color) !important;
+            color: white !important;
+            font-size: 0.75rem !important;
+            font-weight: 600 !important;
+            border-radius: var(--radius-sm) !important;
+            text-transform: uppercase !important;
+        }
+
+        /* Quality score display */
+        .quality-score {
+            display: inline-flex !important;
+            align-items: center !important;
+            gap: 6px !important;
+            padding: 6px 12px !important;
+            border-radius: var(--radius-md) !important;
+            font-weight: 500 !important;
+            font-size: 0.9rem !important;
+        }
+
+        .quality-score.excellent {
+            background: rgba(16, 185, 129, 0.1) !important;
+            color: var(--success-color) !important;
+        }
+
+        .quality-score.good {
+            background: rgba(59, 130, 246, 0.1) !important;
+            color: var(--accent-color) !important;
+        }
+
+        .quality-score.warning {
+            background: rgba(245, 158, 11, 0.1) !important;
+            color: var(--warning-color) !important;
+        }
+
+        .quality-score.poor {
+            background: rgba(239, 68, 68, 0.1) !important;
+            color: var(--error-color) !important;
+        }
+
+        /* Responsive adjustments for inpainting */
+        @media (max-width: 768px) {
+            .inpainting-grid {
+                grid-template-columns: repeat(2, 1fr) !important;
+            }
+
+            #main-mode-tabs > .tab-nav > button {
+                padding: 10px 16px !important;
+                font-size: 0.9rem !important;
+            }
+        }
+
         /* ===== DROPDOWN POSITIONING FIX FOR GRADIO 4.x/5.x ===== */
         /* Fix dropdown list positioning issue in left column */
         .feature-card {
@@ -542,4 +771,4 @@ class CSSStyles:
             box-shadow: var(--shadow-lg) !important;
             margin-top: 4px !important;
         }
-        """
+        """

image_blender.py

@@ -1,5 +1,6 @@
 import cv2
 import numpy as np
+import traceback
 from PIL import Image
 import logging
 from typing import Dict, Any, Optional, Tuple
@@ -7,24 +8,37 @@ from typing import Dict, Any, Optional, Tuple
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)
 
+
 class ImageBlender:
     """
-    Advanced image blending with aggressive spill suppression and color replacement
-    Completely eliminates yellow edge residue while maintaining sharp edges
+    Advanced image blending with aggressive spill suppression and color replacement.
+
+    Supports two primary modes:
+    - Background generation: Foreground preservation with edge refinement
+    - Inpainting: Seamless blending with adaptive color correction
+
+    Attributes:
+        enable_multi_scale: Whether multi-scale edge refinement is enabled
     """
 
-    EDGE_EROSION_PIXELS = 1          # Pixels to erode from mask edge (reduced to protect more foreground)
-    ALPHA_BINARIZE_THRESHOLD = 0.5   # Alpha threshold for binarization (increased to keep more foreground)
-    DARK_LUMINANCE_THRESHOLD = 60    # Luminance threshold for dark foreground detection
-    FOREGROUND_PROTECTION_THRESHOLD = 140  # Mask value above which pixels are strongly protected
-    BACKGROUND_COLOR_TOLERANCE = 30  # DeltaE tolerance for background color detection
+    EDGE_EROSION_PIXELS = 1          # Pixels to erode from mask edge
+    ALPHA_BINARIZE_THRESHOLD = 0.5   # Alpha threshold for binarization
+    DARK_LUMINANCE_THRESHOLD = 60    # Luminance threshold for dark foreground
+    FOREGROUND_PROTECTION_THRESHOLD = 140  # Mask value for strong protection
+    BACKGROUND_COLOR_TOLERANCE = 30  # DeltaE tolerance for background detection
+
+    # Inpainting-specific parameters
+    INPAINT_FEATHER_SCALE = 1.2      # Scale factor for inpainting feathering
+    INPAINT_COLOR_BLEND_RADIUS = 10  # Radius for color adaptation zone
 
     def __init__(self, enable_multi_scale: bool = True):
         """
         Initialize ImageBlender.
 
-        Args:
-            enable_multi_scale: Whether to enable multi-scale edge refinement (default True)
+        Parameters
+        ----------
+        enable_multi_scale : bool
+            Whether to enable multi-scale edge refinement (default True)
         """
         self.enable_multi_scale = enable_multi_scale
         self._debug_info = {}
@@ -499,7 +513,6 @@ class ImageBlender:
             logger.info(f"🔍 Trimap regions - FG_CORE: {fg_core.sum()}, RING: {ring_zone.sum()}, BG: {bg_zone.sum()}")
 
         except Exception as e:
-            import traceback
             logger.error(f"❌ Trimap definition failed: {e}")
             logger.error(f"📍 Traceback: {traceback.format_exc()}")
             print(f"❌ TRIMAP ERROR: {e}")
@@ -678,7 +691,7 @@ class ImageBlender:
         orig_linear = srgb_to_linear(orig_array)
         bg_linear = srgb_to_linear(bg_array)
 
-        # === Cartoon-optimized Alpha calculation ===
+        # Cartoon-optimized Alpha calculation 
         alpha = mask_array.astype(np.float32) / 255.0
 
         # Core foreground region - fully opaque
@@ -800,3 +813,293 @@ class ImageBlender:
             debug_images["adaptive_strength_heatmap"] = Image.fromarray(strength_heatmap_rgb)
 
         return debug_images
+
+    # INPAINTING-SPECIFIC BLENDING METHODS
+    def blend_inpainting(
+        self,
+        original: Image.Image,
+        generated: Image.Image,
+        mask: Image.Image,
+        feather_radius: int = 8,
+        apply_color_correction: bool = True
+    ) -> Image.Image:
+        """
+        Blend inpainted region with original image.
+
+        Specialized blending for inpainting that focuses on seamless integration
+        rather than foreground protection. Performs blending in linear color space
+        with optional adaptive color correction at boundaries.
+
+        Parameters
+        ----------
+        original : PIL.Image
+            Original image before inpainting
+        generated : PIL.Image
+            Generated/inpainted result from the model
+        mask : PIL.Image
+            Inpainting mask (white = inpainted area)
+        feather_radius : int
+            Feathering radius for smooth transitions
+        apply_color_correction : bool
+            Whether to apply adaptive color correction at boundaries
+
+        Returns
+        -------
+        PIL.Image
+            Blended result
+        """
+        logger.info(f"Inpainting blend: feather={feather_radius}, color_correction={apply_color_correction}")
+
+        # Ensure same size
+        if generated.size != original.size:
+            generated = generated.resize(original.size, Image.LANCZOS)
+        if mask.size != original.size:
+            mask = mask.resize(original.size, Image.LANCZOS)
+
+        # Convert to arrays
+        orig_array = np.array(original.convert('RGB')).astype(np.float32)
+        gen_array = np.array(generated.convert('RGB')).astype(np.float32)
+        mask_array = np.array(mask.convert('L')).astype(np.float32) / 255.0
+
+        # Apply feathering to mask
+        if feather_radius > 0:
+            scaled_radius = int(feather_radius * self.INPAINT_FEATHER_SCALE)
+            kernel_size = scaled_radius * 2 + 1
+            mask_array = cv2.GaussianBlur(
+                mask_array,
+                (kernel_size, kernel_size),
+                scaled_radius / 2
+            )
+
+        # Apply adaptive color correction if enabled
+        if apply_color_correction:
+            gen_array = self._apply_inpaint_color_correction(
+                orig_array, gen_array, mask_array
+            )
+
+        # sRGB to linear conversion for accurate blending
+        def srgb_to_linear(img):
+            img_norm = img / 255.0
+            return np.where(
+                img_norm <= 0.04045,
+                img_norm / 12.92,
+                np.power((img_norm + 0.055) / 1.055, 2.4)
+            )
+
+        def linear_to_srgb(img):
+            img_clipped = np.clip(img, 0, 1)
+            return np.where(
+                img_clipped <= 0.0031308,
+                12.92 * img_clipped,
+                1.055 * np.power(img_clipped, 1/2.4) - 0.055
+            )
+
+        # Convert to linear space
+        orig_linear = srgb_to_linear(orig_array)
+        gen_linear = srgb_to_linear(gen_array)
+
+        # Alpha blending in linear space
+        alpha = mask_array[:, :, np.newaxis]
+        result_linear = gen_linear * alpha + orig_linear * (1 - alpha)
+
+        # Convert back to sRGB
+        result_srgb = linear_to_srgb(result_linear)
+        result_array = (result_srgb * 255).astype(np.uint8)
+
+        logger.debug("Inpainting blend completed in linear color space")
+
+        return Image.fromarray(result_array)
+
+    def _apply_inpaint_color_correction(
+        self,
+        original: np.ndarray,
+        generated: np.ndarray,
+        mask: np.ndarray
+    ) -> np.ndarray:
+        """
+        Apply adaptive color correction to match generated region with surroundings.
+
+        Analyzes the boundary region and adjusts the generated content's
+        luminance and color to better match the original context.
+
+        Parameters
+        ----------
+        original : np.ndarray
+            Original image (float32, 0-255)
+        generated : np.ndarray
+            Generated image (float32, 0-255)
+        mask : np.ndarray
+            Blend mask (float32, 0-1)
+
+        Returns
+        -------
+        np.ndarray
+            Color-corrected generated image
+        """
+        # Find boundary region
+        mask_binary = (mask > 0.5).astype(np.uint8)
+        kernel = cv2.getStructuringElement(
+            cv2.MORPH_ELLIPSE,
+            (self.INPAINT_COLOR_BLEND_RADIUS * 2 + 1, self.INPAINT_COLOR_BLEND_RADIUS * 2 + 1)
+        )
+        dilated = cv2.dilate(mask_binary, kernel, iterations=1)
+        boundary_zone = (dilated > 0) & (mask < 0.3)
+
+        if not np.any(boundary_zone):
+            return generated
+
+        # Convert to Lab for perceptual color matching
+        orig_lab = cv2.cvtColor(
+            original.astype(np.uint8), cv2.COLOR_RGB2LAB
+        ).astype(np.float32)
+        gen_lab = cv2.cvtColor(
+            generated.astype(np.uint8), cv2.COLOR_RGB2LAB
+        ).astype(np.float32)
+
+        # Calculate statistics in boundary zone (original)
+        boundary_orig_l = orig_lab[boundary_zone, 0]
+        boundary_orig_a = orig_lab[boundary_zone, 1]
+        boundary_orig_b = orig_lab[boundary_zone, 2]
+
+        orig_mean_l = np.median(boundary_orig_l)
+        orig_mean_a = np.median(boundary_orig_a)
+        orig_mean_b = np.median(boundary_orig_b)
+
+        # Calculate statistics in generated inpaint region
+        inpaint_zone = mask > 0.5
+        if not np.any(inpaint_zone):
+            return generated
+
+        gen_inpaint_l = gen_lab[inpaint_zone, 0]
+        gen_inpaint_a = gen_lab[inpaint_zone, 1]
+        gen_inpaint_b = gen_lab[inpaint_zone, 2]
+
+        gen_mean_l = np.median(gen_inpaint_l)
+        gen_mean_a = np.median(gen_inpaint_a)
+        gen_mean_b = np.median(gen_inpaint_b)
+
+        # Calculate correction deltas
+        delta_l = orig_mean_l - gen_mean_l
+        delta_a = orig_mean_a - gen_mean_a
+        delta_b = orig_mean_b - gen_mean_b
+
+        # Limit correction to avoid over-adjustment
+        max_correction = 15
+        delta_l = np.clip(delta_l, -max_correction, max_correction)
+        delta_a = np.clip(delta_a, -max_correction * 0.5, max_correction * 0.5)
+        delta_b = np.clip(delta_b, -max_correction * 0.5, max_correction * 0.5)
+
+        logger.debug(f"Color correction deltas: L={delta_l:.1f}, a={delta_a:.1f}, b={delta_b:.1f}")
+
+        # Apply correction with spatial falloff from boundary
+        # Create distance map from boundary
+        distance = cv2.distanceTransform(
+            mask_binary, cv2.DIST_L2, 5
+        )
+        max_dist = np.max(distance)
+        if max_dist > 0:
+            # Correction strength falls off from boundary toward center
+            correction_strength = 1.0 - np.clip(distance / (max_dist * 0.5), 0, 1)
+        else:
+            correction_strength = np.ones_like(distance)
+
+        # Apply correction to Lab channels
+        corrected_lab = gen_lab.copy()
+        corrected_lab[:, :, 0] += delta_l * correction_strength * 0.7
+        corrected_lab[:, :, 1] += delta_a * correction_strength * 0.5
+        corrected_lab[:, :, 2] += delta_b * correction_strength * 0.5
+
+        # Clip to valid Lab ranges
+        corrected_lab[:, :, 0] = np.clip(corrected_lab[:, :, 0], 0, 255)
+        corrected_lab[:, :, 1] = np.clip(corrected_lab[:, :, 1], 0, 255)
+        corrected_lab[:, :, 2] = np.clip(corrected_lab[:, :, 2], 0, 255)
+
+        # Convert back to RGB
+        corrected_rgb = cv2.cvtColor(
+            corrected_lab.astype(np.uint8), cv2.COLOR_LAB2RGB
+        ).astype(np.float32)
+
+        return corrected_rgb
+
+    def blend_inpainting_with_guided_filter(
+        self,
+        original: Image.Image,
+        generated: Image.Image,
+        mask: Image.Image,
+        feather_radius: int = 8,
+        guide_radius: int = 8,
+        guide_eps: float = 0.01
+    ) -> Image.Image:
+        """
+        Blend inpainted region using guided filter for edge-aware transitions.
+
+        Combines standard alpha blending with guided filtering to preserve
+        edges in the original image while seamlessly integrating new content.
+
+        Parameters
+        ----------
+        original : PIL.Image
+            Original image
+        generated : PIL.Image
+            Generated/inpainted result
+        mask : PIL.Image
+            Inpainting mask
+        feather_radius : int
+            Base feathering radius
+        guide_radius : int
+            Guided filter radius
+        guide_eps : float
+            Guided filter regularization
+
+        Returns
+        -------
+        PIL.Image
+            Blended result with edge-aware transitions
+        """
+        logger.info("Applying guided filter inpainting blend")
+
+        # Ensure same size
+        if generated.size != original.size:
+            generated = generated.resize(original.size, Image.LANCZOS)
+        if mask.size != original.size:
+            mask = mask.resize(original.size, Image.LANCZOS)
+
+        # Convert to arrays
+        orig_array = np.array(original.convert('RGB')).astype(np.float32)
+        gen_array = np.array(generated.convert('RGB')).astype(np.float32)
+        mask_array = np.array(mask.convert('L')).astype(np.float32) / 255.0
+
+        # Apply base feathering
+        if feather_radius > 0:
+            kernel_size = feather_radius * 2 + 1
+            mask_feathered = cv2.GaussianBlur(
+                mask_array,
+                (kernel_size, kernel_size),
+                feather_radius / 2
+            )
+        else:
+            mask_feathered = mask_array
+
+        # Use original image as guide for the filter
+        guide = cv2.cvtColor(orig_array.astype(np.uint8), cv2.COLOR_RGB2GRAY)
+        guide = guide.astype(np.float32) / 255.0
+
+        # Apply guided filter to the mask
+        try:
+            mask_guided = cv2.ximgproc.guidedFilter(
+                guide=guide,
+                src=mask_feathered,
+                radius=guide_radius,
+                eps=guide_eps
+            )
+            logger.debug("Guided filter applied successfully")
+        except Exception as e:
+            logger.warning(f"Guided filter failed: {e}, using standard feathering")
+            mask_guided = mask_feathered
+
+        # Alpha blending
+        alpha = mask_guided[:, :, np.newaxis]
+        result = gen_array * alpha + orig_array * (1 - alpha)
+        result = np.clip(result, 0, 255).astype(np.uint8)
+
+        return Image.fromarray(result)

inpainting_module.py

@@ -0,0 +1,1311 @@
+import gc
+import logging
+import time
+import traceback
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+import cv2
+import numpy as np
+import torch
+from PIL import Image, ImageFilter
+
+from diffusers import ControlNetModel, DPMSolverMultistepScheduler
+from diffusers import StableDiffusionXLControlNetInpaintPipeline
+from diffusers import StableDiffusionXLInpaintPipeline
+from transformers import AutoImageProcessor, AutoModelForDepthEstimation
+from transformers import DPTImageProcessor, DPTForDepthEstimation
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+@dataclass
+class InpaintingConfig:
+    """Configuration for inpainting operations."""
+
+    # ControlNet settings
+    controlnet_conditioning_scale: float = 0.7
+    conditioning_type: str = "canny"  # "canny" or "depth"
+
+    # Canny edge detection parameters
+    canny_low_threshold: int = 100
+    canny_high_threshold: int = 200
+
+    # Mask settings
+    feather_radius: int = 8
+    min_mask_coverage: float = 0.01
+    max_mask_coverage: float = 0.95
+
+    # Generation settings
+    num_inference_steps: int = 25
+    guidance_scale: float = 7.5
+    preview_steps: int = 15
+    preview_guidance_scale: float = 8.0
+
+    # Quality settings
+    enable_auto_optimization: bool = True
+    max_optimization_retries: int = 3
+    min_quality_score: float = 70.0
+
+    # Memory settings
+    enable_vae_tiling: bool = True
+    enable_attention_slicing: bool = True
+    max_resolution: int = 1024
+
+
+@dataclass
+class InpaintingResult:
+    """Result container for inpainting operations."""
+
+    success: bool
+    result_image: Optional[Image.Image] = None
+    preview_image: Optional[Image.Image] = None
+    control_image: Optional[Image.Image] = None
+    blended_image: Optional[Image.Image] = None
+    quality_score: float = 0.0
+    quality_details: Dict[str, Any] = field(default_factory=dict)
+    generation_time: float = 0.0
+    retries: int = 0
+    error_message: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class InpaintingModule:
+    """
+    ControlNet-based Inpainting Module for SceneWeaver.
+
+    Implements StableDiffusionXLControlNetInpaintPipeline with support for
+    Canny edge and depth map conditioning. Features two-stage generation
+    (preview + full quality) and automatic quality optimization.
+
+    Attributes:
+        device: Computation device (cuda/mps/cpu)
+        config: InpaintingConfig instance
+        is_initialized: Whether pipeline is loaded
+
+    Example:
+        >>> module = InpaintingModule(device="cuda")
+        >>> module.load_inpainting_pipeline(progress_callback=my_callback)
+        >>> result = module.execute_inpainting(
+        ...     image=my_image,
+        ...     mask=my_mask,
+        ...     prompt="a beautiful garden"
+        ... )
+    """
+
+    # Model identifiers
+    CONTROLNET_CANNY_MODEL = "diffusers/controlnet-canny-sdxl-1.0"
+    CONTROLNET_DEPTH_MODEL = "diffusers/controlnet-depth-sdxl-1.0"
+    DEPTH_MODEL_PRIMARY = "LiheYoung/depth-anything-small-hf"
+    DEPTH_MODEL_FALLBACK = "Intel/dpt-hybrid-midas"
+    BASE_MODEL = "stabilityai/stable-diffusion-xl-base-1.0"
+
+    def __init__(
+        self,
+        device: str = "auto",
+        config: Optional[InpaintingConfig] = None
+    ):
+        """
+        Initialize the InpaintingModule.
+
+        Parameters
+        ----------
+        device : str, optional
+            Computation device. "auto" for automatic detection.
+        config : InpaintingConfig, optional
+            Configuration object. Uses defaults if not provided.
+        """
+        self.device = self._setup_device(device)
+        self.config = config or InpaintingConfig()
+
+        # Pipeline instances (lazy loaded)
+        self._inpaint_pipeline = None
+        self._controlnet_canny = None
+        self._controlnet_depth = None
+        self._depth_estimator = None
+        self._depth_processor = None
+
+        # State tracking
+        self.is_initialized = False
+        self._current_conditioning_type = None
+        self._last_seed = None
+        self._cached_latents = None
+        self._use_controlnet = True  # Track if ControlNet is available
+
+        # Reference to model manager (set by SceneWeaverCore)
+        self._model_manager = None
+
+        logger.info(f"InpaintingModule initialized on {self.device}")
+
+    def _setup_device(self, device: str) -> str:
+        """
+        Setup computation device.
+
+        Parameters
+        ----------
+        device : str
+            Device specification or "auto"
+
+        Returns
+        -------
+        str
+            Resolved device name
+        """
+        if device == "auto":
+            if torch.cuda.is_available():
+                return "cuda"
+            elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+                return "mps"
+            return "cpu"
+        return device
+
+    def set_model_manager(self, manager: Any) -> None:
+        """
+        Set reference to ModelManager for coordinated model lifecycle.
+
+        Parameters
+        ----------
+        manager : ModelManager
+            The global model manager instance
+        """
+        self._model_manager = manager
+        logger.info("ModelManager reference set for InpaintingModule")
+
+    def _memory_cleanup(self, aggressive: bool = False) -> None:
+        """
+        Perform memory cleanup.
+
+        Parameters
+        ----------
+        aggressive : bool
+            If True, perform multiple GC rounds and sync CUDA
+        """
+        rounds = 5 if aggressive else 2
+        for _ in range(rounds):
+            gc.collect()
+
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+            if aggressive:
+                torch.cuda.ipc_collect()
+                torch.cuda.synchronize()
+
+        logger.debug(f"Memory cleanup completed (aggressive={aggressive})")
+
+    def _check_memory_status(self) -> Dict[str, float]:
+        """
+        Check current GPU memory status.
+
+        Returns
+        -------
+        dict
+            Memory statistics including allocated, total, and usage ratio
+        """
+        if not torch.cuda.is_available():
+            return {"available": True, "usage_ratio": 0.0}
+
+        allocated = torch.cuda.memory_allocated() / 1024**3
+        total = torch.cuda.get_device_properties(0).total_memory / 1024**3
+        usage_ratio = allocated / total
+
+        return {
+            "allocated_gb": round(allocated, 2),
+            "total_gb": round(total, 2),
+            "free_gb": round(total - allocated, 2),
+            "usage_ratio": round(usage_ratio, 3),
+            "available": usage_ratio < 0.9
+        }
+
+    def load_inpainting_pipeline(
+        self,
+        conditioning_type: str = "canny",
+        progress_callback: Optional[Callable[[str, int], None]] = None
+    ) -> Tuple[bool, str]:
+        """
+        Load the ControlNet inpainting pipeline.
+
+        Implements mutual exclusion with background generation pipeline.
+        Only one pipeline can be loaded at a time.
+
+        Parameters
+        ----------
+        conditioning_type : str
+            Type of ControlNet conditioning: "canny" or "depth"
+        progress_callback : callable, optional
+            Function(message, percentage) for progress updates
+
+        Returns
+        -------
+        tuple
+            (success: bool, error_message: str)
+        """
+        if self.is_initialized and self._current_conditioning_type == conditioning_type:
+            logger.info(f"Inpainting pipeline already loaded with {conditioning_type}")
+            return True, ""
+
+        logger.info(f"Loading inpainting pipeline with {conditioning_type} conditioning...")
+
+        try:
+            self._memory_cleanup(aggressive=True)
+
+            if progress_callback:
+                progress_callback("Preparing to load inpainting models...", 5)
+
+            # Unload existing pipeline if different conditioning type
+            if self._inpaint_pipeline is not None:
+                self._unload_pipeline()
+
+            # Use ControlNet inpainting by default
+            use_controlnet_inpaint = True
+            logger.info("Using StableDiffusionXLControlNetInpaintPipeline")
+
+            if progress_callback:
+                progress_callback("Loading ControlNet model...", 20)
+
+            # Load appropriate ControlNet
+            dtype = torch.float16 if self.device == "cuda" else torch.float32
+            controlnet = None
+
+            if use_controlnet_inpaint:
+                if conditioning_type == "canny":
+                    controlnet = ControlNetModel.from_pretrained(
+                        self.CONTROLNET_CANNY_MODEL,
+                        torch_dtype=dtype,
+                        use_safetensors=True
+                    )
+                    self._controlnet_canny = controlnet
+                    logger.info("Loaded ControlNet Canny model")
+
+                elif conditioning_type == "depth":
+                    controlnet = ControlNetModel.from_pretrained(
+                        self.CONTROLNET_DEPTH_MODEL,
+                        torch_dtype=dtype,
+                        use_safetensors=True
+                    )
+                    self._controlnet_depth = controlnet
+
+                    # Load depth estimator
+                    if progress_callback:
+                        progress_callback("Loading depth estimation model...", 35)
+                    self._load_depth_estimator()
+                    logger.info("Loaded ControlNet Depth model")
+                else:
+                    raise ValueError(f"Unknown conditioning type: {conditioning_type}")
+            else:
+                # Skip ControlNet loading for fallback mode
+                logger.info(f"Skipping ControlNet loading (fallback mode)")
+
+            if progress_callback:
+                progress_callback("Loading SDXL Inpainting pipeline...", 50)
+
+            # Load the inpainting pipeline
+            if use_controlnet_inpaint and controlnet is not None:
+                self._inpaint_pipeline = StableDiffusionXLControlNetInpaintPipeline.from_pretrained(
+                    self.BASE_MODEL,
+                    controlnet=controlnet,
+                    torch_dtype=dtype,
+                    use_safetensors=True,
+                    variant="fp16" if dtype == torch.float16 else None
+                )
+            else:
+                # Fallback: Use dedicated inpainting model without ControlNet
+                self._inpaint_pipeline = StableDiffusionXLInpaintPipeline.from_pretrained(
+                    "diffusers/stable-diffusion-xl-1.0-inpainting-0.1",
+                    torch_dtype=dtype,
+                    use_safetensors=True,
+                    variant="fp16" if dtype == torch.float16 else None
+                )
+                self._use_controlnet = False
+
+            # Track ControlNet usage
+            self._use_controlnet = use_controlnet_inpaint and controlnet is not None
+
+            if progress_callback:
+                progress_callback("Configuring scheduler...", 70)
+
+            # Configure scheduler for faster generation
+            self._inpaint_pipeline.scheduler = DPMSolverMultistepScheduler.from_config(
+                self._inpaint_pipeline.scheduler.config
+            )
+
+            # Move to device
+            self._inpaint_pipeline = self._inpaint_pipeline.to(self.device)
+
+            if progress_callback:
+                progress_callback("Applying optimizations...", 85)
+
+            # Apply memory optimizations
+            self._apply_pipeline_optimizations()
+
+            # Set eval mode
+            self._inpaint_pipeline.unet.eval()
+            if hasattr(self._inpaint_pipeline, 'vae'):
+                self._inpaint_pipeline.vae.eval()
+
+            self.is_initialized = True
+            self._current_conditioning_type = conditioning_type if self._use_controlnet else "none"
+
+            if progress_callback:
+                progress_callback("Inpainting pipeline ready!", 100)
+
+            # Log memory status
+            mem_status = self._check_memory_status()
+            logger.info(f"Pipeline loaded. GPU memory: {mem_status.get('allocated_gb', 0):.1f}GB used")
+
+            return True, ""
+
+        except Exception as e:
+            error_msg = str(e)
+            logger.error(f"Failed to load inpainting pipeline: {error_msg}")
+            traceback.print_exc()
+            self._unload_pipeline()
+            return False, error_msg
+
+    def _load_depth_estimator(self) -> None:
+        """
+        Load depth estimation model with fallback strategy.
+
+        Tries Depth-Anything first, falls back to MiDaS if unavailable.
+        """
+        try:
+            logger.info(f"Attempting to load depth model: {self.DEPTH_MODEL_PRIMARY}")
+
+            self._depth_processor = AutoImageProcessor.from_pretrained(
+                self.DEPTH_MODEL_PRIMARY
+            )
+            self._depth_estimator = AutoModelForDepthEstimation.from_pretrained(
+                self.DEPTH_MODEL_PRIMARY,
+                torch_dtype=torch.float16 if self.device == "cuda" else torch.float32
+            )
+            self._depth_estimator.to(self.device)
+            self._depth_estimator.eval()
+
+            logger.info("Successfully loaded Depth-Anything model")
+
+        except Exception as e:
+            logger.warning(f"Primary depth model failed: {e}, trying fallback...")
+
+            try:
+                self._depth_processor = DPTImageProcessor.from_pretrained(
+                    self.DEPTH_MODEL_FALLBACK
+                )
+                self._depth_estimator = DPTForDepthEstimation.from_pretrained(
+                    self.DEPTH_MODEL_FALLBACK,
+                    torch_dtype=torch.float16 if self.device == "cuda" else torch.float32
+                )
+                self._depth_estimator.to(self.device)
+                self._depth_estimator.eval()
+
+                logger.info("Successfully loaded MiDaS fallback model")
+
+            except Exception as fallback_e:
+                logger.error(f"Fallback depth model also failed: {fallback_e}")
+                raise RuntimeError("Unable to load any depth estimation model")
+
+    def _apply_pipeline_optimizations(self) -> None:
+        """Apply memory and performance optimizations to the pipeline."""
+        if self._inpaint_pipeline is None:
+            return
+
+        # Try xformers first
+        try:
+            self._inpaint_pipeline.enable_xformers_memory_efficient_attention()
+            logger.info("Enabled xformers memory efficient attention")
+        except Exception:
+            try:
+                self._inpaint_pipeline.enable_attention_slicing()
+                logger.info("Enabled attention slicing")
+            except Exception:
+                logger.warning("No attention optimization available")
+
+        # VAE optimizations
+        if self.config.enable_vae_tiling:
+            if hasattr(self._inpaint_pipeline, 'enable_vae_tiling'):
+                self._inpaint_pipeline.enable_vae_tiling()
+                logger.debug("Enabled VAE tiling")
+
+        if hasattr(self._inpaint_pipeline, 'enable_vae_slicing'):
+            self._inpaint_pipeline.enable_vae_slicing()
+            logger.debug("Enabled VAE slicing")
+
+    def _unload_pipeline(self) -> None:
+        """Unload the inpainting pipeline and free memory."""
+        logger.info("Unloading inpainting pipeline...")
+
+        if self._inpaint_pipeline is not None:
+            del self._inpaint_pipeline
+            self._inpaint_pipeline = None
+
+        if self._controlnet_canny is not None:
+            del self._controlnet_canny
+            self._controlnet_canny = None
+
+        if self._controlnet_depth is not None:
+            del self._controlnet_depth
+            self._controlnet_depth = None
+
+        if self._depth_estimator is not None:
+            del self._depth_estimator
+            self._depth_estimator = None
+
+        if self._depth_processor is not None:
+            del self._depth_processor
+            self._depth_processor = None
+
+        self.is_initialized = False
+        self._current_conditioning_type = None
+        self._cached_latents = None
+
+        self._memory_cleanup(aggressive=True)
+        logger.info("Inpainting pipeline unloaded")
+
+    def prepare_control_image(
+        self,
+        image: Image.Image,
+        mode: str = "canny"
+    ) -> Image.Image:
+        """
+        Generate ControlNet conditioning image.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Input image
+        mode : str
+            Conditioning mode: "canny" or "depth"
+
+        Returns
+        -------
+        PIL.Image
+            Generated control image (edges or depth map)
+        """
+        logger.info(f"Preparing control image with mode: {mode}")
+
+        # Convert to RGB if needed
+        if image.mode != 'RGB':
+            image = image.convert('RGB')
+
+        img_array = np.array(image)
+
+        if mode == "canny":
+            return self._generate_canny_edges(img_array)
+        elif mode == "depth":
+            return self._generate_depth_map(image)
+        else:
+            raise ValueError(f"Unknown control mode: {mode}")
+
+    def _generate_canny_edges(self, img_array: np.ndarray) -> Image.Image:
+        """
+        Generate Canny edge detection image.
+
+        Parameters
+        ----------
+        img_array : np.ndarray
+            Input image as RGB numpy array
+
+        Returns
+        -------
+        PIL.Image
+            Edge detection result as grayscale image
+        """
+        # Convert to grayscale
+        gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+
+        # Apply Gaussian blur to reduce noise
+        blurred = cv2.GaussianBlur(gray, (5, 5), 1.4)
+
+        # Canny edge detection
+        edges = cv2.Canny(
+            blurred,
+            self.config.canny_low_threshold,
+            self.config.canny_high_threshold
+        )
+
+        # Convert to 3-channel for ControlNet
+        edges_3ch = cv2.cvtColor(edges, cv2.COLOR_GRAY2RGB)
+
+        logger.debug(f"Generated Canny edges with thresholds "
+                    f"{self.config.canny_low_threshold}/{self.config.canny_high_threshold}")
+
+        return Image.fromarray(edges_3ch)
+
+    def _generate_depth_map(self, image: Image.Image) -> Image.Image:
+        """
+        Generate depth map using depth estimation model.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Input RGB image
+
+        Returns
+        -------
+        PIL.Image
+            Depth map as grayscale image
+        """
+        if self._depth_estimator is None or self._depth_processor is None:
+            raise RuntimeError("Depth estimator not loaded")
+
+        # Preprocess
+        inputs = self._depth_processor(images=image, return_tensors="pt")
+        inputs = {k: v.to(self.device) for k, v in inputs.items()}
+
+        # Inference
+        with torch.no_grad():
+            outputs = self._depth_estimator(**inputs)
+            predicted_depth = outputs.predicted_depth
+
+        # Interpolate to original size
+        prediction = torch.nn.functional.interpolate(
+            predicted_depth.unsqueeze(1),
+            size=image.size[::-1],  # (H, W)
+            mode="bicubic",
+            align_corners=False
+        )
+
+        # Normalize to 0-255
+        depth_array = prediction.squeeze().cpu().numpy()
+        depth_min = depth_array.min()
+        depth_max = depth_array.max()
+
+        if depth_max - depth_min > 0:
+            depth_normalized = ((depth_array - depth_min) / (depth_max - depth_min) * 255)
+        else:
+            depth_normalized = np.zeros_like(depth_array)
+
+        depth_normalized = depth_normalized.astype(np.uint8)
+
+        # Convert to 3-channel for ControlNet
+        depth_3ch = cv2.cvtColor(depth_normalized, cv2.COLOR_GRAY2RGB)
+
+        logger.debug(f"Generated depth map, range: {depth_min:.2f} - {depth_max:.2f}")
+
+        return Image.fromarray(depth_3ch)
+
+    def prepare_mask(
+        self,
+        mask: Image.Image,
+        target_size: Tuple[int, int],
+        feather_radius: Optional[int] = None
+    ) -> Tuple[Image.Image, Dict[str, Any]]:
+        """
+        Prepare and validate mask for inpainting.
+
+        Parameters
+        ----------
+        mask : PIL.Image
+            Input mask (white = inpaint area)
+        target_size : tuple
+            Target (width, height) to match input image
+        feather_radius : int, optional
+            Feathering radius in pixels. Uses config default if None.
+
+        Returns
+        -------
+        tuple
+            (processed_mask, validation_info)
+
+        Raises
+        ------
+        ValueError
+            If mask coverage is outside acceptable range
+        """
+        feather = feather_radius if feather_radius is not None else self.config.feather_radius
+
+        # Convert to grayscale
+        if mask.mode != 'L':
+            mask = mask.convert('L')
+
+        # Resize to match target
+        if mask.size != target_size:
+            mask = mask.resize(target_size, Image.LANCZOS)
+
+        # Convert to array for processing
+        mask_array = np.array(mask)
+
+        # Calculate coverage
+        total_pixels = mask_array.size
+        white_pixels = np.count_nonzero(mask_array > 127)
+        coverage = white_pixels / total_pixels
+
+        validation_info = {
+            "coverage": coverage,
+            "white_pixels": white_pixels,
+            "total_pixels": total_pixels,
+            "feather_radius": feather,
+            "valid": True,
+            "warning": ""
+        }
+
+        # Validate coverage
+        if coverage < self.config.min_mask_coverage:
+            validation_info["valid"] = False
+            validation_info["warning"] = (
+                f"Mask coverage too low ({coverage:.1%}). "
+                f"Please select a larger area to inpaint."
+            )
+            logger.warning(f"Mask coverage {coverage:.1%} below minimum {self.config.min_mask_coverage:.1%}")
+
+        elif coverage > self.config.max_mask_coverage:
+            validation_info["valid"] = False
+            validation_info["warning"] = (
+                f"Mask coverage too high ({coverage:.1%}). "
+                f"Consider using background generation instead."
+            )
+            logger.warning(f"Mask coverage {coverage:.1%} above maximum {self.config.max_mask_coverage:.1%}")
+
+        # Apply feathering
+        if feather > 0:
+            mask_array = cv2.GaussianBlur(
+                mask_array,
+                (feather * 2 + 1, feather * 2 + 1),
+                feather / 2
+            )
+            logger.debug(f"Applied {feather}px feathering to mask")
+
+        processed_mask = Image.fromarray(mask_array, mode='L')
+
+        return processed_mask, validation_info
+
+    def enhance_prompt_for_inpainting(
+        self,
+        prompt: str,
+        image: Image.Image,
+        mask: Image.Image
+    ) -> Tuple[str, str]:
+        """
+        Enhance prompt based on non-masked region analysis.
+
+        Analyzes the surrounding context to generate appropriate
+        lighting and color descriptors.
+
+        Parameters
+        ----------
+        prompt : str
+            User-provided prompt
+        image : PIL.Image
+            Original image
+        mask : PIL.Image
+            Inpainting mask
+
+        Returns
+        -------
+        tuple
+            (enhanced_prompt, negative_prompt)
+        """
+        logger.info("Enhancing prompt for inpainting context...")
+
+        # Convert to arrays
+        img_array = np.array(image.convert('RGB'))
+        mask_array = np.array(mask.convert('L'))
+
+        # Analyze non-masked regions
+        non_masked = mask_array < 127
+
+        if not np.any(non_masked):
+            # No context available
+            enhanced_prompt = f"{prompt}, high quality, detailed, photorealistic"
+            negative_prompt = self._get_inpainting_negative_prompt()
+            return enhanced_prompt, negative_prompt
+
+        # Extract context pixels
+        context_pixels = img_array[non_masked]
+
+        # Convert to Lab for analysis
+        context_lab = cv2.cvtColor(
+            context_pixels.reshape(-1, 1, 3),
+            cv2.COLOR_RGB2LAB
+        ).reshape(-1, 3)
+
+        # Use robust statistics (median) to avoid outlier influence
+        median_l = np.median(context_lab[:, 0])
+        median_a = np.median(context_lab[:, 1])
+        median_b = np.median(context_lab[:, 2])
+
+        # Analyze lighting conditions
+        lighting_descriptors = []
+
+        if median_l > 170:
+            lighting_descriptors.append("bright")
+        elif median_l > 130:
+            lighting_descriptors.append("well-lit")
+        elif median_l > 80:
+            lighting_descriptors.append("moderate lighting")
+        else:
+            lighting_descriptors.append("dim lighting")
+
+        # Analyze color temperature (b channel: blue(-) to yellow(+))
+        if median_b > 140:
+            lighting_descriptors.append("warm golden tones")
+        elif median_b > 120:
+            lighting_descriptors.append("warm afternoon light")
+        elif median_b < 110:
+            lighting_descriptors.append("cool neutral tones")
+
+        # Calculate saturation from context
+        hsv = cv2.cvtColor(context_pixels.reshape(-1, 1, 3), cv2.COLOR_RGB2HSV)
+        median_saturation = np.median(hsv[:, :, 1])
+
+        if median_saturation > 150:
+            lighting_descriptors.append("vibrant colors")
+        elif median_saturation < 80:
+            lighting_descriptors.append("subtle muted colors")
+
+        # Build enhanced prompt
+        lighting_desc = ", ".join(lighting_descriptors) if lighting_descriptors else ""
+        quality_suffix = "high quality, detailed, photorealistic, seamless integration"
+
+        if lighting_desc:
+            enhanced_prompt = f"{prompt}, {lighting_desc}, {quality_suffix}"
+        else:
+            enhanced_prompt = f"{prompt}, {quality_suffix}"
+
+        negative_prompt = self._get_inpainting_negative_prompt()
+
+        logger.info(f"Enhanced prompt with context: {lighting_desc}")
+
+        return enhanced_prompt, negative_prompt
+
+    def _get_inpainting_negative_prompt(self) -> str:
+        """Get standard negative prompt for inpainting."""
+        return (
+            "inconsistent lighting, wrong perspective, mismatched colors, "
+            "visible seams, blending artifacts, color bleeding, "
+            "blurry, low quality, distorted, deformed, "
+            "harsh edges, unnatural transition"
+        )
+
+    def execute_inpainting(
+        self,
+        image: Image.Image,
+        mask: Image.Image,
+        prompt: str,
+        preview_only: bool = False,
+        seed: Optional[int] = None,
+        progress_callback: Optional[Callable[[str, int], None]] = None,
+        **kwargs
+    ) -> InpaintingResult:
+        """
+        Execute the inpainting operation.
+
+        Implements two-stage generation: fast preview followed by
+        full quality generation if requested.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Original image to inpaint
+        mask : PIL.Image
+            Inpainting mask (white = area to regenerate)
+        prompt : str
+            Text description of desired content
+        preview_only : bool
+            If True, only generate preview (faster)
+        seed : int, optional
+            Random seed for reproducibility
+        progress_callback : callable, optional
+            Progress update function(message, percentage)
+        **kwargs
+            Additional parameters:
+            - controlnet_conditioning_scale: float
+            - feather_radius: int
+            - num_inference_steps: int
+            - guidance_scale: float
+
+        Returns
+        -------
+        InpaintingResult
+            Result container with generated images and metadata
+        """
+        start_time = time.time()
+
+        if not self.is_initialized:
+            return InpaintingResult(
+                success=False,
+                error_message="Inpainting pipeline not initialized. Call load_inpainting_pipeline() first."
+            )
+
+        logger.info(f"Starting inpainting: prompt='{prompt[:50]}...', preview_only={preview_only}")
+
+        try:
+            # Update config with kwargs
+            conditioning_scale = kwargs.get(
+                'controlnet_conditioning_scale',
+                self.config.controlnet_conditioning_scale
+            )
+            feather_radius = kwargs.get('feather_radius', self.config.feather_radius)
+
+            if progress_callback:
+                progress_callback("Preparing images...", 5)
+
+            # Prepare image
+            if image.mode != 'RGB':
+                image = image.convert('RGB')
+
+            # Ensure dimensions are multiple of 8
+            width, height = image.size
+            new_width = (width // 8) * 8
+            new_height = (height // 8) * 8
+
+            if new_width != width or new_height != height:
+                image = image.resize((new_width, new_height), Image.LANCZOS)
+
+            # Check and potentially reduce resolution for memory
+            max_res = self.config.max_resolution
+            if max(new_width, new_height) > max_res:
+                scale = max_res / max(new_width, new_height)
+                new_width = int(new_width * scale) // 8 * 8
+                new_height = int(new_height * scale) // 8 * 8
+                image = image.resize((new_width, new_height), Image.LANCZOS)
+                logger.info(f"Reduced resolution to {new_width}x{new_height} for memory")
+
+            # Prepare mask
+            if progress_callback:
+                progress_callback("Processing mask...", 10)
+
+            processed_mask, mask_info = self.prepare_mask(
+                mask,
+                (new_width, new_height),
+                feather_radius
+            )
+
+            if not mask_info["valid"]:
+                return InpaintingResult(
+                    success=False,
+                    error_message=mask_info["warning"]
+                )
+
+            # Generate control image
+            if progress_callback:
+                progress_callback("Generating control image...", 20)
+
+            control_image = self.prepare_control_image(
+                image,
+                self._current_conditioning_type
+            )
+
+            # Enhance prompt
+            if progress_callback:
+                progress_callback("Enhancing prompt...", 25)
+
+            enhanced_prompt, negative_prompt = self.enhance_prompt_for_inpainting(
+                prompt, image, processed_mask
+            )
+
+            # Setup generator for reproducibility
+            if seed is None:
+                seed = int(time.time() * 1000) % (2**32)
+            self._last_seed = seed
+            generator = torch.Generator(device=self.device).manual_seed(seed)
+
+            # Stage 1: Preview generation
+            if progress_callback:
+                progress_callback("Generating preview...", 30)
+
+            preview_result = self._generate_inpaint(
+                image=image,
+                mask=processed_mask,
+                control_image=control_image,
+                prompt=enhanced_prompt,
+                negative_prompt=negative_prompt,
+                num_inference_steps=self.config.preview_steps,
+                guidance_scale=self.config.preview_guidance_scale,
+                controlnet_conditioning_scale=conditioning_scale,
+                generator=generator
+            )
+
+            if preview_only:
+                generation_time = time.time() - start_time
+
+                return InpaintingResult(
+                    success=True,
+                    preview_image=preview_result,
+                    control_image=control_image,
+                    generation_time=generation_time,
+                    metadata={
+                        "seed": seed,
+                        "prompt": enhanced_prompt,
+                        "conditioning_type": self._current_conditioning_type,
+                        "conditioning_scale": conditioning_scale,
+                        "preview_only": True
+                    }
+                )
+
+            # Stage 2: Full quality generation
+            if progress_callback:
+                progress_callback("Generating full quality...", 60)
+
+            # Use same seed for reproducibility
+            generator = torch.Generator(device=self.device).manual_seed(seed)
+
+            num_steps = kwargs.get('num_inference_steps', self.config.num_inference_steps)
+            guidance = kwargs.get('guidance_scale', self.config.guidance_scale)
+
+            full_result = self._generate_inpaint(
+                image=image,
+                mask=processed_mask,
+                control_image=control_image,
+                prompt=enhanced_prompt,
+                negative_prompt=negative_prompt,
+                num_inference_steps=num_steps,
+                guidance_scale=guidance,
+                controlnet_conditioning_scale=conditioning_scale,
+                generator=generator
+            )
+
+            if progress_callback:
+                progress_callback("Blending result...", 90)
+
+            # Blend result
+            blended = self.blend_result(image, full_result, processed_mask)
+
+            generation_time = time.time() - start_time
+
+            if progress_callback:
+                progress_callback("Complete!", 100)
+
+            return InpaintingResult(
+                success=True,
+                result_image=full_result,
+                preview_image=preview_result,
+                control_image=control_image,
+                blended_image=blended,
+                generation_time=generation_time,
+                metadata={
+                    "seed": seed,
+                    "prompt": enhanced_prompt,
+                    "negative_prompt": negative_prompt,
+                    "conditioning_type": self._current_conditioning_type,
+                    "conditioning_scale": conditioning_scale,
+                    "num_inference_steps": num_steps,
+                    "guidance_scale": guidance,
+                    "feather_radius": feather_radius,
+                    "mask_coverage": mask_info["coverage"],
+                    "preview_only": False
+                }
+            )
+
+        except torch.cuda.OutOfMemoryError:
+            logger.error("CUDA out of memory during inpainting")
+            self._memory_cleanup(aggressive=True)
+            return InpaintingResult(
+                success=False,
+                error_message="GPU memory exhausted. Try reducing image size or closing other applications."
+            )
+
+        except Exception as e:
+            logger.error(f"Inpainting failed: {e}")
+            logger.error(traceback.format_exc())
+            return InpaintingResult(
+                success=False,
+                error_message=f"Inpainting failed: {str(e)}"
+            )
+
+    def _generate_inpaint(
+        self,
+        image: Image.Image,
+        mask: Image.Image,
+        control_image: Image.Image,
+        prompt: str,
+        negative_prompt: str,
+        num_inference_steps: int,
+        guidance_scale: float,
+        controlnet_conditioning_scale: float,
+        generator: torch.Generator
+    ) -> Image.Image:
+        """
+        Internal method to run the inpainting pipeline.
+
+        Supports both ControlNet and non-ControlNet pipelines.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Original image
+        mask : PIL.Image
+            Processed mask
+        control_image : PIL.Image
+            ControlNet conditioning image (ignored if ControlNet not available)
+        prompt : str
+            Enhanced prompt
+        negative_prompt : str
+            Negative prompt
+        num_inference_steps : int
+            Number of denoising steps
+        guidance_scale : float
+            Classifier-free guidance scale
+        controlnet_conditioning_scale : float
+            ControlNet influence strength (ignored if ControlNet not available)
+        generator : torch.Generator
+            Random generator for reproducibility
+
+        Returns
+        -------
+        PIL.Image
+            Generated image
+        """
+        with torch.inference_mode():
+            if self._use_controlnet:
+                # Full ControlNet inpainting pipeline
+                result = self._inpaint_pipeline(
+                    prompt=prompt,
+                    negative_prompt=negative_prompt,
+                    image=image,
+                    mask_image=mask,
+                    control_image=control_image,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    controlnet_conditioning_scale=controlnet_conditioning_scale,
+                    generator=generator
+                )
+            else:
+                # Fallback: Standard SDXL inpainting without ControlNet
+                result = self._inpaint_pipeline(
+                    prompt=prompt,
+                    negative_prompt=negative_prompt,
+                    image=image,
+                    mask_image=mask,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    generator=generator
+                )
+
+        return result.images[0]
+
+    def blend_result(
+        self,
+        original: Image.Image,
+        generated: Image.Image,
+        mask: Image.Image
+    ) -> Image.Image:
+        """
+        Blend generated content with original image.
+
+        Uses linear color space blending for accurate results.
+
+        Parameters
+        ----------
+        original : PIL.Image
+            Original image
+        generated : PIL.Image
+            Generated inpainted image
+        mask : PIL.Image
+            Blending mask (white = use generated)
+
+        Returns
+        -------
+        PIL.Image
+            Blended result
+        """
+        logger.info("Blending inpainting result...")
+
+        # Ensure same size
+        if generated.size != original.size:
+            generated = generated.resize(original.size, Image.LANCZOS)
+        if mask.size != original.size:
+            mask = mask.resize(original.size, Image.LANCZOS)
+
+        # Convert to arrays
+        orig_array = np.array(original.convert('RGB')).astype(np.float32)
+        gen_array = np.array(generated.convert('RGB')).astype(np.float32)
+        mask_array = np.array(mask.convert('L')).astype(np.float32) / 255.0
+
+        # sRGB to linear conversion
+        def srgb_to_linear(img):
+            img_norm = img / 255.0
+            return np.where(
+                img_norm <= 0.04045,
+                img_norm / 12.92,
+                np.power((img_norm + 0.055) / 1.055, 2.4)
+            )
+
+        def linear_to_srgb(img):
+            img_clipped = np.clip(img, 0, 1)
+            return np.where(
+                img_clipped <= 0.0031308,
+                12.92 * img_clipped,
+                1.055 * np.power(img_clipped, 1/2.4) - 0.055
+            )
+
+        # Convert to linear space
+        orig_linear = srgb_to_linear(orig_array)
+        gen_linear = srgb_to_linear(gen_array)
+
+        # Alpha blending in linear space
+        alpha = mask_array[:, :, np.newaxis]
+        result_linear = gen_linear * alpha + orig_linear * (1 - alpha)
+
+        # Convert back to sRGB
+        result_srgb = linear_to_srgb(result_linear)
+        result_array = (result_srgb * 255).astype(np.uint8)
+
+        logger.debug("Blending completed in linear color space")
+
+        return Image.fromarray(result_array)
+
+    def execute_with_auto_optimization(
+        self,
+        image: Image.Image,
+        mask: Image.Image,
+        prompt: str,
+        quality_checker: Any,
+        progress_callback: Optional[Callable[[str, int], None]] = None,
+        **kwargs
+    ) -> InpaintingResult:
+        """
+        Execute inpainting with automatic quality-based optimization.
+
+        Retries with adjusted parameters if quality score is below threshold.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Original image
+        mask : PIL.Image
+            Inpainting mask
+        prompt : str
+            Text prompt
+        quality_checker : QualityChecker
+            Quality assessment instance
+        progress_callback : callable, optional
+            Progress update function
+        **kwargs
+            Additional inpainting parameters
+
+        Returns
+        -------
+        InpaintingResult
+            Best result achieved (may include retry information)
+        """
+        if not self.config.enable_auto_optimization:
+            return self.execute_inpainting(
+                image, mask, prompt,
+                progress_callback=progress_callback,
+                **kwargs
+            )
+
+        best_result = None
+        best_score = 0.0
+        retry_count = 0
+        prev_score = 0.0
+
+        # Mutable parameters for optimization
+        current_feather = kwargs.get('feather_radius', self.config.feather_radius)
+        current_scale = kwargs.get(
+            'controlnet_conditioning_scale',
+            self.config.controlnet_conditioning_scale
+        )
+        current_guidance = kwargs.get('guidance_scale', self.config.guidance_scale)
+        current_prompt = prompt
+
+        while retry_count <= self.config.max_optimization_retries:
+            if progress_callback and retry_count > 0:
+                progress_callback(f"Optimizing (attempt {retry_count + 1})...", 5)
+
+            # Execute inpainting
+            result = self.execute_inpainting(
+                image, mask, current_prompt,
+                preview_only=False,
+                feather_radius=current_feather,
+                controlnet_conditioning_scale=current_scale,
+                guidance_scale=current_guidance,
+                progress_callback=progress_callback if retry_count == 0 else None,
+                **{k: v for k, v in kwargs.items()
+                   if k not in ['feather_radius', 'controlnet_conditioning_scale',
+                               'guidance_scale']}
+            )
+
+            if not result.success:
+                return result
+
+            # Evaluate quality
+            if result.blended_image is not None:
+                quality_results = quality_checker.run_all_checks(
+                    foreground=image,
+                    background=result.result_image,
+                    mask=mask,
+                    combined=result.blended_image
+                )
+                quality_score = quality_results.get("overall_score", 0)
+            else:
+                quality_score = 50.0  # Default if no blended image
+
+            result.quality_score = quality_score
+            result.quality_details = quality_results if result.blended_image else {}
+            result.retries = retry_count
+
+            logger.info(f"Quality score: {quality_score:.1f} (attempt {retry_count + 1})")
+
+            # Track best result
+            if quality_score > best_score:
+                best_score = quality_score
+                best_result = result
+
+            # Check if quality is acceptable
+            if quality_score >= self.config.min_quality_score:
+                logger.info(f"Quality threshold met: {quality_score:.1f}")
+                return best_result
+
+            # Check for minimal improvement (early termination)
+            if retry_count > 0 and abs(quality_score - prev_score) < 5.0:
+                logger.info("Minimal improvement, stopping optimization")
+                return best_result
+
+            prev_score = quality_score
+            retry_count += 1
+
+            if retry_count > self.config.max_optimization_retries:
+                break
+
+            # Adjust parameters based on quality issues
+            checks = quality_results.get("checks", {})
+
+            edge_score = checks.get("edge_continuity", {}).get("score", 100)
+            harmony_score = checks.get("color_harmony", {}).get("score", 100)
+
+            if edge_score < 60:
+                # Edge issues: increase feathering, decrease control strength
+                current_feather = min(20, current_feather + 3)
+                current_scale = max(0.5, current_scale - 0.1)
+                logger.debug(f"Adjusting for edges: feather={current_feather}, scale={current_scale}")
+
+            if harmony_score < 60:
+                # Color harmony issues: emphasize consistency in prompt
+                if "color consistent" not in current_prompt.lower():
+                    current_prompt = f"{current_prompt}, color consistent with surroundings, matching lighting"
+                current_guidance = min(12.0, current_guidance + 1.0)
+                logger.debug(f"Adjusting for harmony: guidance={current_guidance}")
+
+            if edge_score < 60 and harmony_score < 60:
+                # Both issues: stronger guidance
+                current_guidance = min(12.0, current_guidance + 1.5)
+
+        logger.info(f"Optimization complete. Best score: {best_score:.1f}")
+        return best_result
+
+    def get_status(self) -> Dict[str, Any]:
+        """
+        Get current module status.
+
+        Returns
+        -------
+        dict
+            Status information including initialization state and memory usage
+        """
+        status = {
+            "initialized": self.is_initialized,
+            "device": self.device,
+            "conditioning_type": self._current_conditioning_type,
+            "last_seed": self._last_seed,
+            "config": {
+                "controlnet_conditioning_scale": self.config.controlnet_conditioning_scale,
+                "feather_radius": self.config.feather_radius,
+                "num_inference_steps": self.config.num_inference_steps,
+                "guidance_scale": self.config.guidance_scale
+            }
+        }
+
+        status["memory"] = self._check_memory_status()
+
+        return status

inpainting_templates.py

@@ -0,0 +1,707 @@
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class InpaintingTemplate:
+    """Data class representing an inpainting template."""
+
+    key: str
+    name: str
+    category: str
+    icon: str
+    description: str
+
+    # Prompt templates
+    prompt_template: str
+    negative_prompt: str
+
+    # Recommended parameters
+    controlnet_conditioning_scale: float = 0.7
+    feather_radius: int = 8
+    guidance_scale: float = 7.5
+    num_inference_steps: int = 25
+
+    # Conditioning type preference
+    preferred_conditioning: str = "canny"  # "canny" or "depth"
+
+    # Tips for users
+    usage_tips: List[str] = field(default_factory=list)
+
+
+class InpaintingTemplateManager:
+    """
+    Manages inpainting templates for various use cases.
+
+    Provides categorized presets optimized for different inpainting scenarios
+    including object replacement, removal, style transfer, and enhancement.
+
+    Attributes:
+        TEMPLATES: Dictionary of all available templates
+        CATEGORIES: List of category names in display order
+
+    Example:
+        >>> manager = InpaintingTemplateManager()
+        >>> template = manager.get_template("object_replacement")
+        >>> print(template.prompt_template)
+    """
+
+    TEMPLATES: Dict[str, InpaintingTemplate] = {
+        # Object Replacement Category 
+        "object_replacement": InpaintingTemplate(
+            key="object_replacement",
+            name="Object Replacement",
+            category="Replacement",
+            icon="🔄",
+            description="Replace selected objects with new content while preserving context",
+            prompt_template="{content}, seamlessly integrated into scene, matching lighting and perspective, realistic placement",
+            negative_prompt=(
+                "inconsistent lighting, wrong perspective, mismatched colors, "
+                "visible seams, floating objects, unrealistic placement, original object, "
+                "poorly integrated, disconnected from scene, keeping original"
+            ),
+            controlnet_conditioning_scale=0.48,
+            feather_radius=14,
+            guidance_scale=10.0,
+            num_inference_steps=38,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Draw mask PRECISELY around the object to replace (include small margin)",
+                "Be specific: Instead of 'plant', use 'large green potted fern with detailed leaves'",
+                "📝 Example prompts:",
+                "  • 'elegant white ceramic teacup with delicate gold rim and floral pattern'",
+                "  • 'modern silver laptop computer with sleek metallic finish'",
+                "  • 'vintage wooden desk lamp with warm brass details'"
+            ]
+        ),
+
+        "face_swap": InpaintingTemplate(
+            key="face_swap",
+            name="Face Enhancement",
+            category="Replacement",
+            icon="👤",
+            description="Enhance or modify facial features while maintaining identity cues",
+            prompt_template="{content}, natural skin texture, proper facial proportions, realistic lighting, detailed facial features",
+            negative_prompt=(
+                "deformed face, asymmetric features, unnatural skin, "
+                "plastic appearance, wrong eye direction, blurry features, "
+                "artificial smoothing, uncanny valley, distorted proportions"
+            ),
+            controlnet_conditioning_scale=0.88,
+            feather_radius=6,
+            guidance_scale=8.5,
+            num_inference_steps=35,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Draw mask CAREFULLY around face outline (avoid hair and neck)",
+                "High conditioning preserves facial structure - good for subtle enhancements",
+                "📝 Example prompts:",
+                "  • 'warm friendly smile with bright eyes and natural expression'",
+                "  • 'professional headshot with confident neutral expression'",
+                "  • 'gentle smile with soft natural lighting on face'"
+            ]
+        ),
+
+        "clothing_change": InpaintingTemplate(
+            key="clothing_change",
+            name="Clothing Change",
+            category="Replacement",
+            icon="👕",
+            description="Change clothing color, pattern, style, and material (moderate changes)",
+            prompt_template="transform to {content}, vivid fabric texture, natural folds and wrinkles, correct fit, proper color saturation",
+            negative_prompt=(
+                "wrong body proportions, floating fabric, unrealistic wrinkles, "
+                "mismatched lighting, visible edges, original clothing style, "
+                "keeping same color, faded colors, unchanged appearance, partial change"
+            ),
+            controlnet_conditioning_scale=0.42,
+            feather_radius=14,
+            guidance_scale=10.5,
+            num_inference_steps=38,
+            preferred_conditioning="depth",
+            usage_tips=[
+                "Best for: Similar color changes (black→navy, white→cream) and pattern changes",
+                "For extreme changes (black↔white), use 'Dramatic Color Change' template instead",
+                "📝 Example prompts:",
+                "  • 'deep navy blue formal blazer with fine texture and professional fit'",
+                "  • 'bright red polo shirt with clean collar and soft fabric'",
+                "  • 'charcoal gray sweater with ribbed knit texture'"
+            ]
+        ),
+
+        "dramatic_color_change": InpaintingTemplate(
+            key="dramatic_color_change",
+            name="Dramatic Color Change",
+            category="Replacement",
+            icon="🎨",
+            description="Extreme color transformations (dark↔light, black↔white)",
+            prompt_template="completely transform to {content}, vivid color saturation, high contrast, sharp color definition, clear distinct color",
+            negative_prompt=(
+                "original color, keeping same shade, partial change, color bleeding, "
+                "faded colors, mixed tones, subtle change, gradual transition, "
+                "original appearance, unchanged, dark remnants, light patches"
+            ),
+            controlnet_conditioning_scale=0.38,
+            feather_radius=16,
+            guidance_scale=12.0,
+            num_inference_steps=42,
+            preferred_conditioning="depth",
+            usage_tips=[
+                "Optimized for: black→white, white→black, dark→light extreme transformations",
+                "Use VERY vivid descriptors: 'PURE WHITE', 'JET BLACK', 'BRIGHT crimson red'",
+                "📝 Example prompts:",
+                "  • 'pure white dress shirt with crisp texture and sharp collar'",
+                "  • 'jet black leather jacket with smooth matte finish'",
+                "  • 'bright crimson red blazer with vivid saturated color'"
+            ]
+        ),
+
+        "clothing_addition": InpaintingTemplate(
+            key="clothing_addition",
+            name="Add Accessories",
+            category="Replacement",
+            icon="👔",
+            description="Add ties, pockets, buttons, or accessories to clothing (Advanced)",
+            prompt_template="{content}, clearly visible, highly detailed accessory, seamlessly integrated into clothing, proper placement and perspective",
+            negative_prompt=(
+                "missing details, incomplete, floating objects, disconnected, "
+                "unrealistic placement, wrong perspective, blurry, poorly integrated, "
+                "invisible, faint, unclear, hidden, absent, not visible"
+            ),
+            controlnet_conditioning_scale=0.25,
+            feather_radius=12,
+            guidance_scale=14.0,
+            num_inference_steps=50,
+            preferred_conditioning="depth",
+            usage_tips=[
+                "⚡ Advanced feature: For adding neckties, pocket squares, badges, or buttons",
+                "Draw mask from NECK to CHEST (vertical strip) for ties, not just collar area",
+                "📝 Example prompts:",
+                "  • 'burgundy silk necktie with diagonal stripes and Windsor knot, hanging down from collar to chest'",
+                "  • 'white pocket square with neat fold, visible in breast pocket'",
+                "  • 'silver lapel pin with detailed engraving on left collar'",
+                "⚠️ TIP: For ties, mask should cover the entire length where tie should appear"
+            ]
+        ),
+
+        # Object Removal Category 
+        "object_removal": InpaintingTemplate(
+            key="object_removal",
+            name="Object Removal",
+            category="Removal",
+            icon="🗑️",
+            description="Remove unwanted objects and fill with matching background",
+            prompt_template="clean background, seamless continuation, {content}",
+            negative_prompt=(
+                "visible patches, color mismatch, texture inconsistency, "
+                "ghost artifacts, blur spots, repeated patterns, visible seams"
+            ),
+            controlnet_conditioning_scale=0.48,
+            feather_radius=14,
+            guidance_scale=8.0,
+            num_inference_steps=30,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Draw mask slightly BEYOND object edges for better blending",
+                "Describe what background SHOULD look like (e.g., 'grass lawn', 'wooden floor')",
+                "📝 Example prompts:",
+                "  • 'clean grass lawn with natural green color'",
+                "  • 'smooth wooden floor with consistent grain pattern'",
+                "  • 'plain white wall with even texture'"
+            ]
+        ),
+
+        "watermark_removal": InpaintingTemplate(
+            key="watermark_removal",
+            name="Watermark Removal",
+            category="Removal",
+            icon="💧",
+            description="Remove watermarks and text overlays",
+            prompt_template="clean image, no text, seamless background, {content}",
+            negative_prompt=(
+                "text, watermark, logo, signature, letters, numbers, visible artifacts, "
+                "color inconsistency, blur, remnants, ghost text"
+            ),
+            controlnet_conditioning_scale=0.45,
+            feather_radius=12,
+            guidance_scale=8.5,
+            num_inference_steps=30,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Draw mask covering ALL watermark/text areas precisely",
+                "Describe what SHOULD be there instead (e.g., 'sky', 'fabric texture')",
+                "📝 Example prompts:",
+                "  • 'clean blue sky with smooth gradient'",
+                "  • 'natural skin texture without marks'",
+                "  • 'smooth fabric surface with consistent color'"
+            ]
+        ),
+
+        "blemish_removal": InpaintingTemplate(
+            key="blemish_removal",
+            name="Blemish Removal",
+            category="Removal",
+            icon="✨",
+            description="Remove skin blemishes, scratches, or small imperfections",
+            prompt_template="clean smooth surface, natural texture, {content}",
+            negative_prompt=(
+                "artificial smoothing, plastic texture, visible editing, "
+                "color patches, unnatural appearance, over-processed"
+            ),
+            controlnet_conditioning_scale=0.6,
+            feather_radius=6,
+            guidance_scale=6.5,
+            num_inference_steps=20,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Draw small precise masks for EACH blemish/imperfection",
+                "Lower guidance (6.5) preserves natural skin texture",
+                "📝 Example prompts:",
+                "  • 'natural clean skin with smooth texture'",
+                "  • 'smooth surface without scratches or marks'",
+                "  • 'clear skin with natural pores and texture'"
+            ]
+        ),
+
+        # Style Transfer Category 
+        "style_artistic": InpaintingTemplate(
+            key="style_artistic",
+            name="Artistic Style",
+            category="Style",
+            icon="🎨",
+            description="Apply artistic style to selected region",
+            prompt_template="{content}, distinctive artistic style, strong painterly effect, creative interpretation, visible brushstrokes",
+            negative_prompt=(
+                "photorealistic, plain, boring, low contrast, unchanged, "
+                "inconsistent style, harsh transitions, original appearance, realistic photo"
+            ),
+            controlnet_conditioning_scale=0.52,
+            feather_radius=12,
+            guidance_scale=11.5,
+            num_inference_steps=38,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Works best on larger areas (faces, clothing, backgrounds) for visible transformation",
+                "Be VERY specific about art style for best results",
+                "📝 Example prompts:",
+                "  • 'impressionist oil painting with visible thick brushstrokes and vibrant colors'",
+                "  • 'watercolor painting with soft edges and delicate color washes'",
+                "  • 'Van Gogh style with swirling brushstrokes and bold color contrasts'"
+            ]
+        ),
+
+        "style_vintage": InpaintingTemplate(
+            key="style_vintage",
+            name="Vintage Look",
+            category="Style",
+            icon="📻",
+            description="Apply vintage or retro aesthetic to selected area",
+            prompt_template="{content}, strong vintage aesthetic, warm sepia tones, film grain texture, nostalgic atmosphere",
+            negative_prompt=(
+                "modern, digital, cold colors, harsh contrast, "
+                "oversaturated, neon colors, contemporary look, clean digital, crisp"
+            ),
+            controlnet_conditioning_scale=0.55,
+            feather_radius=14,
+            guidance_scale=10.5,
+            num_inference_steps=35,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Works best on medium to large regions for visible aesthetic change",
+                "Specify era and style for best results",
+                "📝 Example prompts:",
+                "  • '1920s sepia photograph with faded brown tones and soft grain'",
+                "  • '1970s vintage photo with warm orange tones and slight film grain'",
+                "  • '1950s Kodachrome with saturated warm colors and nostalgic feel'"
+            ]
+        ),
+
+        "style_anime": InpaintingTemplate(
+            key="style_anime",
+            name="Anime Style",
+            category="Style",
+            icon="🎌",
+            description="Transform selected region to anime/illustration style",
+            prompt_template="{content}, anime illustration style, clean sharp lines, vibrant saturated colors, cel-shaded with flat colors",
+            negative_prompt=(
+                "photorealistic, blurry lines, muddy colors, realistic photo, "
+                "3D render, uncanny valley, western cartoon, gradient shading, photographic"
+            ),
+            controlnet_conditioning_scale=0.48,
+            feather_radius=10,
+            guidance_scale=12.5,
+            num_inference_steps=40,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "⚡ DRAMATIC transformation - best for portraits and characters",
+                "Expect significant stylistic changes from realistic to anime",
+                "📝 Example prompts:",
+                "  • 'modern anime style with large expressive eyes and vibrant colors'",
+                "  • 'Studio Ghibli style with soft features and warm color palette'",
+                "  • 'manga style with clean black lines and cel-shaded coloring'"
+            ]
+        ),
+
+        # Detail Enhancement Category 
+        "detail_enhance": InpaintingTemplate(
+            key="detail_enhance",
+            name="Detail Enhancement",
+            category="Enhancement",
+            icon="🔍",
+            description="Add fine details and textures to selected area",
+            prompt_template="{content}, highly detailed, intricate textures, fine details, sharp focus",
+            negative_prompt=(
+                "blurry, smooth, low detail, soft focus, "
+                "oversimplified, lacking texture"
+            ),
+            controlnet_conditioning_scale=0.85,
+            feather_radius=4,
+            guidance_scale=8.0,
+            num_inference_steps=30,
+            preferred_conditioning="depth",
+            usage_tips=[
+                "High conditioning (0.85) preserves overall structure while adding detail",
+                "Best for adding fine details to existing objects",
+                "📝 Example prompts:",
+                "  • 'highly detailed fabric with visible weave and fine threads'",
+                "  • 'intricate wood grain with natural knots and detailed texture'",
+                "  • 'sharp facial features with fine skin pores and detail'"
+            ]
+        ),
+
+        "texture_add": InpaintingTemplate(
+            key="texture_add",
+            name="Texture Addition",
+            category="Enhancement",
+            icon="🧱",
+            description="Add or enhance surface textures",
+            prompt_template="{content} texture, realistic surface detail, natural material appearance",
+            negative_prompt=(
+                "flat, smooth, unrealistic, plastic, "
+                "wrong material, inconsistent texture"
+            ),
+            controlnet_conditioning_scale=0.8,
+            feather_radius=5,
+            guidance_scale=7.5,
+            num_inference_steps=25,
+            preferred_conditioning="depth",
+            usage_tips=[
+                "Specify material type clearly for best results",
+                "Depth conditioning preserves 3D form while changing texture",
+                "📝 Example prompts:",
+                "  • 'rough wood texture with natural grain and knots'",
+                "  • 'soft cotton fabric with gentle weave pattern'",
+                "  • 'smooth marble surface with subtle veining'"
+            ]
+        ),
+
+        "lighting_fix": InpaintingTemplate(
+            key="lighting_fix",
+            name="Lighting Correction",
+            category="Enhancement",
+            icon="💡",
+            description="Correct or enhance lighting in selected area",
+            prompt_template="{content}, proper lighting, natural shadows, balanced exposure",
+            negative_prompt=(
+                "harsh shadows, overexposed, underexposed, "
+                "flat lighting, unnatural highlights"
+            ),
+            controlnet_conditioning_scale=0.65,
+            feather_radius=15,
+            guidance_scale=7.0,
+            num_inference_steps=25,
+            preferred_conditioning="depth",
+            usage_tips=[
+                "Use large feather (15px) for smooth lighting transitions",
+                "Best for fixing uneven lighting or adding natural light",
+                "📝 Example prompts:",
+                "  • 'soft natural lighting from window, gentle shadows'",
+                "  • 'balanced exposure with warm golden hour light'",
+                "  • 'even studio lighting with soft diffused shadows'"
+            ]
+        ),
+
+        # Background Category 
+        "background_extend": InpaintingTemplate(
+            key="background_extend",
+            name="Background Extension",
+            category="Background",
+            icon="📐",
+            description="Extend image background seamlessly",
+            prompt_template="seamless background extension, {content}, consistent style and lighting",
+            negative_prompt=(
+                "visible seams, style mismatch, lighting inconsistency, "
+                "repeated elements, unnatural continuation, abrupt changes"
+            ),
+            controlnet_conditioning_scale=0.55,
+            feather_radius=20,
+            guidance_scale=8.0,
+            num_inference_steps=32,
+            preferred_conditioning="canny",
+            usage_tips=[
+                "Draw mask on area to extend (edges of image)",
+                "Large feather (20px) ensures smooth blending with existing background",
+                "📝 Example prompts:",
+                "  • 'continue the wooden floor with same grain pattern'",
+                "  • 'extend blue sky with matching clouds and lighting'",
+                "  • 'seamless continuation of brick wall texture'"
+            ]
+        ),
+
+        "background_replace": InpaintingTemplate(
+            key="background_replace",
+            name="Background Replacement",
+            category="Background",
+            icon="🖼️",
+            description="Replace background while keeping subject intact",
+            prompt_template="{content}, professional background scene, seamless integration with subject, matching lighting and atmosphere",
+            negative_prompt=(
+                "floating subject, inconsistent lighting, disconnected, "
+                "wrong perspective, visible edges, color mismatch, original background, "
+                "poor integration, obvious composite"
+            ),
+            controlnet_conditioning_scale=0.60,
+            feather_radius=12,
+            guidance_scale=9.5,
+            num_inference_steps=35,
+            preferred_conditioning="depth",
+            usage_tips=[
+                "Draw mask around ENTIRE background (leave subject unmasked with small margin)",
+                "Include lighting description to match subject for natural results",
+                "📝 Example prompts:",
+                "  • 'professional photography studio with white backdrop and soft lighting'",
+                "  • 'modern minimalist office with white walls and bright natural lighting'",
+                "  • 'sunny beach with blue ocean and golden hour lighting'"
+            ]
+        ),
+    }
+
+    # Category display order
+    CATEGORIES = ["Replacement", "Removal", "Style", "Enhancement", "Background"]
+
+    def __init__(self):
+        """Initialize the InpaintingTemplateManager."""
+        logger.info(f"InpaintingTemplateManager initialized with {len(self.TEMPLATES)} templates")
+
+    def get_all_templates(self) -> Dict[str, InpaintingTemplate]:
+        """
+        Get all available templates.
+
+        Returns
+        -------
+        dict
+            Dictionary of all templates keyed by template key
+        """
+        return self.TEMPLATES
+
+    def get_template(self, key: str) -> Optional[InpaintingTemplate]:
+        """
+        Get a specific template by key.
+
+        Parameters
+        ----------
+        key : str
+            Template identifier
+
+        Returns
+        -------
+        InpaintingTemplate or None
+            Template if found, None otherwise
+        """
+        return self.TEMPLATES.get(key)
+
+    def get_templates_by_category(self, category: str) -> List[InpaintingTemplate]:
+        """
+        Get all templates in a specific category.
+
+        Parameters
+        ----------
+        category : str
+            Category name
+
+        Returns
+        -------
+        list
+            List of templates in the category
+        """
+        return [t for t in self.TEMPLATES.values() if t.category == category]
+
+    def get_categories(self) -> List[str]:
+        """
+        Get list of all categories in display order.
+
+        Returns
+        -------
+        list
+            Category names
+        """
+        return self.CATEGORIES
+
+    def get_template_choices_sorted(self) -> List[str]:
+        """
+        Get template choices formatted for Gradio dropdown.
+
+        Returns list of display strings sorted by category then A-Z.
+        Format: "icon Name"
+
+        Returns
+        -------
+        list
+            Formatted display strings for dropdown
+        """
+        display_list = []
+
+        for category in self.CATEGORIES:
+            templates = self.get_templates_by_category(category)
+            for template in sorted(templates, key=lambda t: t.name):
+                display_name = f"{template.icon} {template.name}"
+                display_list.append(display_name)
+
+        return display_list
+
+    def get_template_key_from_display(self, display_name: str) -> Optional[str]:
+        """
+        Get template key from display name.
+
+        Parameters
+        ----------
+        display_name : str
+            Display string like "🔄 Object Replacement"
+
+        Returns
+        -------
+        str or None
+            Template key if found
+        """
+        if not display_name:
+            return None
+
+        for key, template in self.TEMPLATES.items():
+            if f"{template.icon} {template.name}" == display_name:
+                return key
+        return None
+
+    def get_parameters_for_template(self, key: str) -> Dict[str, any]:
+        """
+        Get recommended parameters for a template.
+
+        Parameters
+        ----------
+        key : str
+            Template key
+
+        Returns
+        -------
+        dict
+            Dictionary of parameter names and values
+        """
+        template = self.get_template(key)
+        if not template:
+            return {}
+
+        return {
+            "controlnet_conditioning_scale": template.controlnet_conditioning_scale,
+            "feather_radius": template.feather_radius,
+            "guidance_scale": template.guidance_scale,
+            "num_inference_steps": template.num_inference_steps,
+            "preferred_conditioning": template.preferred_conditioning
+        }
+
+    def build_prompt(self, key: str, content: str) -> str:
+        """
+        Build complete prompt from template and user content.
+
+        Parameters
+        ----------
+        key : str
+            Template key
+        content : str
+            User-provided content description
+
+        Returns
+        -------
+        str
+            Formatted prompt with content inserted
+        """
+        template = self.get_template(key)
+        if not template:
+            return content
+
+        return template.prompt_template.format(content=content)
+
+    def get_negative_prompt(self, key: str) -> str:
+        """
+        Get negative prompt for a template.
+
+        Parameters
+        ----------
+        key : str
+            Template key
+
+        Returns
+        -------
+        str
+            Negative prompt string
+        """
+        template = self.get_template(key)
+        if not template:
+            return ""
+        return template.negative_prompt
+
+    def get_usage_tips(self, key: str) -> List[str]:
+        """
+        Get usage tips for a template.
+
+        Parameters
+        ----------
+        key : str
+            Template key
+
+        Returns
+        -------
+        list
+            List of tip strings
+        """
+        template = self.get_template(key)
+        if not template:
+            return []
+        return template.usage_tips
+
+    def build_gallery_html(self) -> str:
+        """
+        Build HTML for template gallery display.
+
+        Returns
+        -------
+        str
+            HTML string for Gradio display
+        """
+        html_parts = ['<div class="inpainting-gallery">']
+
+        for category in self.CATEGORIES:
+            templates = self.get_templates_by_category(category)
+            if not templates:
+                continue
+
+            html_parts.append(f'''
+            <div class="inpainting-category">
+                <h4 class="inpainting-category-title">{category}</h4>
+                <div class="inpainting-grid">
+            ''')
+
+            for template in sorted(templates, key=lambda t: t.name):
+                html_parts.append(f'''
+                <div class="inpainting-card" data-template="{template.key}">
+                    <span class="inpainting-icon">{template.icon}</span>
+                    <span class="inpainting-name">{template.name}</span>
+                    <span class="inpainting-desc">{template.description[:50]}...</span>
+                </div>
+                ''')
+
+            html_parts.append('</div></div>')
+
+        html_parts.append('</div>')
+        return ''.join(html_parts)

mask_generator.py

@@ -1,5 +1,6 @@
 import cv2
 import numpy as np
+import traceback
 from PIL import Image, ImageFilter, ImageDraw
 import logging
 from typing import Optional, Tuple
@@ -222,7 +223,6 @@ class MaskGenerator:
 
         except Exception as e:
             logger.error(f"❌ BiRefNet mask generation failed: {e}")
-            import traceback
             logger.error(f"📍 Traceback: {traceback.format_exc()}")
             return None
 
@@ -380,7 +380,6 @@ class MaskGenerator:
             return is_cartoon
 
         except Exception as e:
-            import traceback
             logger.error(f"❌ Cartoon detection failed: {e}")
             logger.error(f"📍 Traceback: {traceback.format_exc()}")
             print(f"❌ CARTOON DETECTION ERROR: {e}")
@@ -437,7 +436,6 @@ class MaskGenerator:
             return enhanced_alpha
 
         except Exception as e:
-            import traceback
             logger.error(f"❌ Cartoon mask enhancement failed: {e}")
             logger.error(f"📍 Traceback: {traceback.format_exc()}")
             print(f"❌ CARTOON MASK ENHANCEMENT ERROR: {e}")

model_manager.py

@@ -1,7 +1,8 @@
 import logging
 import gc
 import time
-from typing import Dict, Any, Optional, Callable
+from enum import IntEnum
+from typing import Dict, Any, Optional, Callable, List
 from dataclasses import dataclass, field
 from threading import Lock
 import torch
@@ -10,13 +11,41 @@ logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)
 
 
+class ModelPriority(IntEnum):
+    """
+    Model priority levels for memory management.
+
+    Higher priority models are kept loaded longer under memory pressure.
+    """
+    CRITICAL = 100      # Never unload (e.g., OpenCLIP for analysis)
+    HIGH = 80           # Currently active pipeline
+    MEDIUM = 50         # Recently used models
+    LOW = 20            # Inactive pipelines, can be evicted
+    DISPOSABLE = 0      # Temporary models, evict first
+
+
 @dataclass
 class ModelInfo:
-    """Information about a registered model."""
+    """
+    Information about a registered model.
+
+    Attributes:
+        name: Unique model identifier
+        loader: Callable that returns the loaded model
+        is_critical: If True, model won't be unloaded under memory pressure
+        priority: ModelPriority level for eviction decisions
+        estimated_memory_gb: Estimated GPU memory usage
+        model_group: Group name for mutual exclusion (e.g., "pipeline")
+        is_loaded: Whether model is currently loaded
+        last_used: Timestamp of last use
+        model_instance: The actual model object
+    """
     name: str
     loader: Callable[[], Any]
-    is_critical: bool = False  # Critical models are not unloaded under memory pressure
+    is_critical: bool = False
+    priority: int = ModelPriority.MEDIUM
     estimated_memory_gb: float = 0.0
+    model_group: str = ""  # For mutual exclusion (e.g., "pipeline")
     is_loaded: bool = False
     last_used: float = 0.0
     model_instance: Any = None
@@ -25,12 +54,34 @@ class ModelInfo:
 class ModelManager:
     """
     Singleton model manager for unified model lifecycle management.
-    Handles lazy loading, caching, and intelligent memory management.
+
+    Handles lazy loading, caching, priority-based eviction, and mutual
+    exclusion for pipeline models. Designed for memory-constrained
+    environments like Google Colab and HuggingFace Spaces.
+
+    Features:
+        - Priority-based model eviction under memory pressure
+        - Mutual exclusion for pipeline models (only one active at a time)
+        - Automatic memory monitoring and cleanup
+        - Support for model groups and dependencies
+
+    Example:
+        >>> manager = get_model_manager()
+        >>> manager.register_model(
+        ...     name="sdxl_pipeline",
+        ...     loader=load_sdxl,
+        ...     priority=ModelPriority.HIGH,
+        ...     model_group="pipeline"
+        ... )
+        >>> pipeline = manager.load_model("sdxl_pipeline")
     """
 
     _instance = None
     _lock = Lock()
 
+    # Known model groups for mutual exclusion
+    PIPELINE_GROUP = "pipeline"  # Only one pipeline can be loaded at a time
+
     def __new__(cls):
         if cls._instance is None:
             with cls._lock:
@@ -45,9 +96,11 @@ class ModelManager:
 
         self._models: Dict[str, ModelInfo] = {}
         self._memory_threshold = 0.80  # Trigger cleanup at 80% GPU memory usage
+        self._high_memory_threshold = 0.90  # Critical threshold for aggressive cleanup
         self._device = self._detect_device()
+        self._active_pipeline: Optional[str] = None  # Track currently active pipeline
 
-        logger.info(f"🔧 ModelManager initialized on {self._device}")
+        logger.info(f"ModelManager initialized on {self._device}")
         self._initialized = True
 
     def _detect_device(self) -> str:
@@ -63,44 +116,73 @@ class ModelManager:
         name: str,
         loader: Callable[[], Any],
         is_critical: bool = False,
-        estimated_memory_gb: float = 0.0
+        priority: int = ModelPriority.MEDIUM,
+        estimated_memory_gb: float = 0.0,
+        model_group: str = ""
     ):
         """
         Register a model for managed loading.
 
-        Args:
-            name: Unique model identifier
-            loader: Callable that returns the loaded model
-            is_critical: If True, model won't be unloaded under memory pressure
-            estimated_memory_gb: Estimated GPU memory usage in GB
+        Parameters
+        ----------
+        name : str
+            Unique model identifier
+        loader : callable
+            Function that returns the loaded model
+        is_critical : bool
+            If True, model won't be unloaded under memory pressure
+        priority : int
+            ModelPriority level for eviction decisions
+        estimated_memory_gb : float
+            Estimated GPU memory usage in GB
+        model_group : str
+            Group name for mutual exclusion (e.g., "pipeline")
         """
         if name in self._models:
-            logger.warning(f"⚠️ Model '{name}' already registered, updating")
+            logger.warning(f"Model '{name}' already registered, updating")
+
+        # Critical models always have highest priority
+        if is_critical:
+            priority = ModelPriority.CRITICAL
 
         self._models[name] = ModelInfo(
             name=name,
             loader=loader,
             is_critical=is_critical,
+            priority=priority,
             estimated_memory_gb=estimated_memory_gb,
+            model_group=model_group,
             is_loaded=False,
             last_used=0.0,
             model_instance=None
         )
-        logger.info(f"📝 Registered model: {name} (critical={is_critical}, ~{estimated_memory_gb:.1f}GB)")
+        logger.info(f"Registered model: {name} (priority={priority}, group={model_group}, ~{estimated_memory_gb:.1f}GB)")
 
-    def load_model(self, name: str) -> Any:
+    def load_model(self, name: str, update_priority: Optional[int] = None) -> Any:
         """
         Load a model by name. Returns cached instance if already loaded.
 
-        Args:
-            name: Model identifier
+        Implements mutual exclusion for pipeline models - loading a new
+        pipeline will unload any existing pipeline first.
 
-        Returns:
+        Parameters
+        ----------
+        name : str
+            Model identifier
+        update_priority : int, optional
+            If provided, update the model's priority after loading
+
+        Returns
+        -------
+        Any
             Loaded model instance
 
-        Raises:
-            KeyError: If model not registered
-            RuntimeError: If loading fails
+        Raises
+        ------
+        KeyError
+            If model not registered
+        RuntimeError
+            If loading fails
         """
         if name not in self._models:
             raise KeyError(f"Model '{name}' not registered")
@@ -110,15 +192,21 @@ class ModelManager:
         # Return cached instance
         if model_info.is_loaded and model_info.model_instance is not None:
             model_info.last_used = time.time()
-            logger.debug(f"📦 Using cached model: {name}")
+            if update_priority is not None:
+                model_info.priority = update_priority
+            logger.debug(f"Using cached model: {name}")
             return model_info.model_instance
 
+        # Handle mutual exclusion for pipeline group
+        if model_info.model_group == self.PIPELINE_GROUP:
+            self._ensure_pipeline_exclusion(name)
+
         # Check memory pressure before loading
         self.check_memory_pressure()
 
         # Load the model
         try:
-            logger.info(f"📥 Loading model: {name}")
+            logger.info(f"Loading model: {name}")
             start_time = time.time()
 
             model_instance = model_info.loader()
@@ -127,32 +215,64 @@ class ModelManager:
             model_info.is_loaded = True
             model_info.last_used = time.time()
 
+            if update_priority is not None:
+                model_info.priority = update_priority
+
+            # Track active pipeline
+            if model_info.model_group == self.PIPELINE_GROUP:
+                self._active_pipeline = name
+
             load_time = time.time() - start_time
-            logger.info(f"✅ Model '{name}' loaded in {load_time:.1f}s")
+            logger.info(f"Model '{name}' loaded in {load_time:.1f}s")
 
             return model_instance
 
         except Exception as e:
-            logger.error(f"❌ Failed to load model '{name}': {e}")
+            logger.error(f"Failed to load model '{name}': {e}")
             raise RuntimeError(f"Model loading failed: {e}")
 
-    def unload_model(self, name: str):
+    def _ensure_pipeline_exclusion(self, new_pipeline: str) -> None:
+        """
+        Ensure only one pipeline is loaded at a time.
+
+        Unloads any existing pipeline before loading a new one.
+
+        Parameters
+        ----------
+        new_pipeline : str
+            Name of the pipeline about to be loaded
+        """
+        for name, info in self._models.items():
+            if (info.model_group == self.PIPELINE_GROUP and
+                info.is_loaded and
+                name != new_pipeline):
+                logger.info(f"Unloading {name} to make room for {new_pipeline}")
+                self.unload_model(name)
+
+    def unload_model(self, name: str) -> bool:
         """
         Unload a specific model to free memory.
 
-        Args:
-            name: Model identifier
+        Parameters
+        ----------
+        name : str
+            Model identifier
+
+        Returns
+        -------
+        bool
+            True if model was unloaded successfully
         """
         if name not in self._models:
-            return
+            return False
 
         model_info = self._models[name]
 
         if not model_info.is_loaded:
-            return
+            return True
 
         try:
-            logger.info(f"🗑️ Unloading model: {name}")
+            logger.info(f"Unloading model: {name}")
 
             # Delete model instance
             if model_info.model_instance is not None:
@@ -161,21 +281,33 @@ class ModelManager:
             model_info.model_instance = None
             model_info.is_loaded = False
 
+            # Update active pipeline tracking
+            if self._active_pipeline == name:
+                self._active_pipeline = None
+
             # Cleanup
             gc.collect()
             if torch.cuda.is_available():
                 torch.cuda.empty_cache()
+                torch.cuda.ipc_collect()
 
-            logger.info(f"✅ Model '{name}' unloaded")
+            logger.info(f"Model '{name}' unloaded")
+            return True
 
         except Exception as e:
-            logger.error(f"❌ Error unloading model '{name}': {e}")
+            logger.error(f"Error unloading model '{name}': {e}")
+            return False
 
     def check_memory_pressure(self) -> bool:
         """
-        Check GPU memory usage and unload least-used non-critical models if needed.
+        Check GPU memory usage and unload low-priority models if needed.
 
-        Returns:
+        Uses priority-based eviction: lower priority models are unloaded first,
+        then falls back to least-recently-used within same priority tier.
+
+        Returns
+        -------
+        bool
             True if cleanup was performed
         """
         if not torch.cuda.is_available():
@@ -188,18 +320,19 @@ class ModelManager:
         if usage_ratio < self._memory_threshold:
             return False
 
-        logger.warning(f"⚠️ Memory pressure detected: {usage_ratio:.1%} used")
+        logger.warning(f"Memory pressure detected: {usage_ratio:.1%} used")
 
-        # Find non-critical models sorted by last used time
-        unloadable = [
+        # Find evictable models (not critical, loaded)
+        # Sort by priority (ascending) then by last_used (ascending)
+        evictable = [
             (name, info) for name, info in self._models.items()
-            if info.is_loaded and not info.is_critical
+            if info.is_loaded and info.priority < ModelPriority.CRITICAL
         ]
-        unloadable.sort(key=lambda x: x[1].last_used)
+        evictable.sort(key=lambda x: (x[1].priority, x[1].last_used))
 
-        # Unload oldest non-critical models
+        # Unload models starting from lowest priority
         cleaned = False
-        for name, info in unloadable:
+        for name, info in evictable:
             self.unload_model(name)
             cleaned = True
 
@@ -210,13 +343,21 @@ class ModelManager:
 
         return cleaned
 
-    def force_cleanup(self):
-        """Force cleanup all non-critical models and clear caches."""
-        logger.info("🧹 Force cleanup initiated")
+    def force_cleanup(self, keep_critical_only: bool = True):
+        """
+        Force cleanup models and clear caches.
+
+        Parameters
+        ----------
+        keep_critical_only : bool
+            If True, only keep CRITICAL priority models loaded
+        """
+        logger.info("Force cleanup initiated")
 
-        # Unload all non-critical models
-        for name, info in self._models.items():
-            if info.is_loaded and not info.is_critical:
+        # Unload models based on priority
+        threshold = ModelPriority.CRITICAL if keep_critical_only else ModelPriority.HIGH
+        for name, info in list(self._models.items()):
+            if info.is_loaded and info.priority < threshold:
                 self.unload_model(name)
 
         # Aggressive garbage collection
@@ -228,7 +369,81 @@ class ModelManager:
             torch.cuda.ipc_collect()
             torch.cuda.synchronize()
 
-        logger.info("✅ Force cleanup completed")
+        logger.info("Force cleanup completed")
+
+    def update_priority(self, name: str, priority: int) -> bool:
+        """
+        Update a model's priority level.
+
+        Parameters
+        ----------
+        name : str
+            Model identifier
+        priority : int
+            New priority level
+
+        Returns
+        -------
+        bool
+            True if priority was updated
+        """
+        if name not in self._models:
+            return False
+
+        self._models[name].priority = priority
+        logger.debug(f"Updated priority for {name} to {priority}")
+        return True
+
+    def get_active_pipeline(self) -> Optional[str]:
+        """
+        Get the name of currently active pipeline.
+
+        Returns
+        -------
+        str or None
+            Name of active pipeline, or None if no pipeline is loaded
+        """
+        return self._active_pipeline
+
+    def switch_to_pipeline(
+        self,
+        name: str,
+        loader: Optional[Callable[[], Any]] = None
+    ) -> Any:
+        """
+        Switch to a different pipeline, unloading current one.
+
+        This is a convenience method for pipeline switching that handles
+        mutual exclusion automatically.
+
+        Parameters
+        ----------
+        name : str
+            Pipeline name to switch to
+        loader : callable, optional
+            Loader function if pipeline not already registered
+
+        Returns
+        -------
+        Any
+            The loaded pipeline instance
+
+        Raises
+        ------
+        KeyError
+            If pipeline not registered and no loader provided
+        """
+        # Register if needed
+        if name not in self._models and loader is not None:
+            self.register_model(
+                name=name,
+                loader=loader,
+                priority=ModelPriority.HIGH,
+                model_group=self.PIPELINE_GROUP
+            )
+
+        # Load will handle unloading of current pipeline
+        return self.load_model(name, update_priority=ModelPriority.HIGH)
 
     def get_memory_status(self) -> Dict[str, Any]:
         """

quality_checker.py

@@ -2,7 +2,7 @@ import logging
 import numpy as np
 import cv2
 from PIL import Image
-from typing import Dict, Any, Tuple, Optional
+from typing import Dict, Any, Tuple, Optional, List
 from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
@@ -407,3 +407,452 @@ class QualityChecker:
             summary += f"\nNotes: {'; '.join(results['warnings'])}"
 
         return summary
+
+    # =========================================================================
+    # INPAINTING-SPECIFIC QUALITY CHECKS
+    # =========================================================================
+
+    def check_inpainting_edge_continuity(
+        self,
+        original: Image.Image,
+        inpainted: Image.Image,
+        mask: Image.Image,
+        ring_width: int = 5
+    ) -> QualityResult:
+        """
+        Check edge continuity at inpainting boundary.
+
+        Calculates color distribution similarity between the ring zones
+        on each side of the mask boundary in Lab color space.
+
+        Parameters
+        ----------
+        original : PIL.Image
+            Original image before inpainting
+        inpainted : PIL.Image
+            Result after inpainting
+        mask : PIL.Image
+            Inpainting mask (white = inpainted area)
+        ring_width : int
+            Width in pixels for the ring zones on each side
+
+        Returns
+        -------
+        QualityResult
+            Edge continuity assessment
+        """
+        try:
+            # Convert to arrays
+            orig_array = np.array(original.convert('RGB'))
+            inpaint_array = np.array(inpainted.convert('RGB'))
+            mask_array = np.array(mask.convert('L'))
+
+            # Find boundary using morphological gradient
+            kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+            dilated = cv2.dilate(mask_array, kernel, iterations=ring_width)
+            eroded = cv2.erode(mask_array, kernel, iterations=ring_width)
+
+            # Inner ring (inside inpainted region, near boundary)
+            inner_ring = (mask_array > 127) & (eroded <= 127)
+
+            # Outer ring (outside inpainted region, near boundary)
+            outer_ring = (mask_array <= 127) & (dilated > 127)
+
+            if not np.any(inner_ring) or not np.any(outer_ring):
+                return QualityResult(
+                    score=50,
+                    passed=True,
+                    issue="Unable to detect boundary rings",
+                    details={"ring_width": ring_width}
+                )
+
+            # Convert to Lab for perceptual comparison
+            inpaint_lab = cv2.cvtColor(inpaint_array, cv2.COLOR_RGB2LAB).astype(np.float32)
+
+            # Get Lab values for each ring from the inpainted image
+            inner_lab = inpaint_lab[inner_ring]
+            outer_lab = inpaint_lab[outer_ring]
+
+            # Calculate statistics for each channel
+            inner_mean = np.mean(inner_lab, axis=0)
+            outer_mean = np.mean(outer_lab, axis=0)
+            inner_std = np.std(inner_lab, axis=0)
+            outer_std = np.std(outer_lab, axis=0)
+
+            # Calculate differences
+            mean_diff = np.abs(inner_mean - outer_mean)
+            std_diff = np.abs(inner_std - outer_std)
+
+            # Calculate Delta E (simplified)
+            delta_e = np.sqrt(np.sum(mean_diff ** 2))
+
+            # Score calculation
+            # Low Delta E = good continuity
+            # Target: Delta E < 10 is excellent, < 20 is good
+            if delta_e < 5:
+                continuity_score = 100
+            elif delta_e < 10:
+                continuity_score = 90
+            elif delta_e < 20:
+                continuity_score = 75
+            elif delta_e < 30:
+                continuity_score = 60
+            elif delta_e < 50:
+                continuity_score = 40
+            else:
+                continuity_score = max(20, 100 - delta_e)
+
+            # Penalize for large std differences (inconsistent textures)
+            std_penalty = min(20, np.mean(std_diff) * 0.5)
+            final_score = max(0, continuity_score - std_penalty)
+
+            passed = final_score >= 60
+            issue = ""
+
+            if final_score < 60:
+                if delta_e > 30:
+                    issue = f"Visible color discontinuity at boundary (Delta E: {delta_e:.1f})"
+                elif np.mean(std_diff) > 20:
+                    issue = "Texture mismatch at boundary"
+                else:
+                    issue = "Poor edge blending"
+
+            return QualityResult(
+                score=final_score,
+                passed=passed,
+                issue=issue,
+                details={
+                    "delta_e": delta_e,
+                    "mean_diff_l": mean_diff[0],
+                    "mean_diff_a": mean_diff[1],
+                    "mean_diff_b": mean_diff[2],
+                    "std_diff_avg": np.mean(std_diff),
+                    "inner_pixels": np.count_nonzero(inner_ring),
+                    "outer_pixels": np.count_nonzero(outer_ring)
+                }
+            )
+
+        except Exception as e:
+            logger.error(f"Inpainting edge continuity check failed: {e}")
+            return QualityResult(score=0, passed=False, issue=str(e), details={})
+
+    def check_inpainting_color_harmony(
+        self,
+        original: Image.Image,
+        inpainted: Image.Image,
+        mask: Image.Image
+    ) -> QualityResult:
+        """
+        Check color harmony between inpainted region and surrounding area.
+
+        Compares color statistics of the inpainted region with adjacent
+        non-inpainted regions to assess visual coherence.
+
+        Parameters
+        ----------
+        original : PIL.Image
+            Original image
+        inpainted : PIL.Image
+            Inpainted result
+        mask : PIL.Image
+            Inpainting mask
+
+        Returns
+        -------
+        QualityResult
+            Color harmony assessment
+        """
+        try:
+            inpaint_array = np.array(inpainted.convert('RGB'))
+            mask_array = np.array(mask.convert('L'))
+
+            # Define regions
+            inpaint_region = mask_array > 127
+
+            # Get adjacent region (dilated mask minus original mask)
+            kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (15, 15))
+            dilated = cv2.dilate(mask_array, kernel, iterations=2)
+            adjacent_region = (dilated > 127) & (mask_array <= 127)
+
+            if not np.any(inpaint_region) or not np.any(adjacent_region):
+                return QualityResult(
+                    score=50,
+                    passed=True,
+                    issue="Insufficient regions for comparison",
+                    details={}
+                )
+
+            # Convert to Lab
+            inpaint_lab = cv2.cvtColor(inpaint_array, cv2.COLOR_RGB2LAB).astype(np.float32)
+
+            # Extract region colors
+            inpaint_colors = inpaint_lab[inpaint_region]
+            adjacent_colors = inpaint_lab[adjacent_region]
+
+            # Calculate color statistics
+            inpaint_mean = np.mean(inpaint_colors, axis=0)
+            adjacent_mean = np.mean(adjacent_colors, axis=0)
+
+            inpaint_std = np.std(inpaint_colors, axis=0)
+            adjacent_std = np.std(adjacent_colors, axis=0)
+
+            # Color histogram comparison
+            hist_scores = []
+            for i in range(3):  # L, a, b channels
+                hist_inpaint, _ = np.histogram(
+                    inpaint_colors[:, i], bins=32, range=(0, 255)
+                )
+                hist_adjacent, _ = np.histogram(
+                    adjacent_colors[:, i], bins=32, range=(0, 255)
+                )
+
+                # Normalize
+                hist_inpaint = hist_inpaint.astype(np.float32) / (np.sum(hist_inpaint) + 1e-6)
+                hist_adjacent = hist_adjacent.astype(np.float32) / (np.sum(hist_adjacent) + 1e-6)
+
+                # Bhattacharyya coefficient (1 = identical, 0 = completely different)
+                bc = np.sum(np.sqrt(hist_inpaint * hist_adjacent))
+                hist_scores.append(bc)
+
+            avg_hist_score = np.mean(hist_scores)
+
+            # Calculate harmony score
+            mean_diff = np.linalg.norm(inpaint_mean - adjacent_mean)
+
+            if mean_diff < 10 and avg_hist_score > 0.8:
+                harmony_score = 100
+            elif mean_diff < 20 and avg_hist_score > 0.7:
+                harmony_score = 85
+            elif mean_diff < 30 and avg_hist_score > 0.6:
+                harmony_score = 70
+            elif mean_diff < 50:
+                harmony_score = 55
+            else:
+                harmony_score = max(30, 100 - mean_diff)
+
+            # Boost score if histogram similarity is high
+            histogram_bonus = (avg_hist_score - 0.5) * 20  # -10 to +10
+            final_score = max(0, min(100, harmony_score + histogram_bonus))
+
+            passed = final_score >= 60
+            issue = ""
+
+            if final_score < 60:
+                if mean_diff > 40:
+                    issue = "Significant color mismatch with surrounding area"
+                elif avg_hist_score < 0.5:
+                    issue = "Color distribution differs from context"
+                else:
+                    issue = "Poor color integration"
+
+            return QualityResult(
+                score=final_score,
+                passed=passed,
+                issue=issue,
+                details={
+                    "mean_color_diff": mean_diff,
+                    "histogram_similarity": avg_hist_score,
+                    "inpaint_luminance": inpaint_mean[0],
+                    "adjacent_luminance": adjacent_mean[0]
+                }
+            )
+
+        except Exception as e:
+            logger.error(f"Inpainting color harmony check failed: {e}")
+            return QualityResult(score=0, passed=False, issue=str(e), details={})
+
+    def check_inpainting_artifact_detection(
+        self,
+        inpainted: Image.Image,
+        mask: Image.Image
+    ) -> QualityResult:
+        """
+        Detect common inpainting artifacts like blurriness or color bleeding.
+
+        Parameters
+        ----------
+        inpainted : PIL.Image
+            Inpainted result
+        mask : PIL.Image
+            Inpainting mask
+
+        Returns
+        -------
+        QualityResult
+            Artifact detection results
+        """
+        try:
+            inpaint_array = np.array(inpainted.convert('RGB'))
+            mask_array = np.array(mask.convert('L'))
+
+            inpaint_region = mask_array > 127
+
+            if not np.any(inpaint_region):
+                return QualityResult(
+                    score=50,
+                    passed=True,
+                    issue="No inpainted region detected",
+                    details={}
+                )
+
+            # Extract inpainted region pixels
+            gray = cv2.cvtColor(inpaint_array, cv2.COLOR_RGB2GRAY)
+
+            # Calculate sharpness (Laplacian variance)
+            laplacian = cv2.Laplacian(gray, cv2.CV_64F)
+            inpaint_laplacian = laplacian[inpaint_region]
+            sharpness = np.var(inpaint_laplacian)
+
+            # Get surrounding region for comparison
+            kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (10, 10))
+            dilated = cv2.dilate(mask_array, kernel, iterations=1)
+            surrounding = (dilated > 127) & (mask_array <= 127)
+
+            if np.any(surrounding):
+                surrounding_laplacian = laplacian[surrounding]
+                surrounding_sharpness = np.var(surrounding_laplacian)
+                sharpness_ratio = sharpness / (surrounding_sharpness + 1e-6)
+            else:
+                sharpness_ratio = 1.0
+
+            # Check for color bleeding (abnormal saturation at edges)
+            hsv = cv2.cvtColor(inpaint_array, cv2.COLOR_RGB2HSV)
+            saturation = hsv[:, :, 1]
+
+            # Find boundary pixels
+            boundary_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+            boundary = cv2.morphologyEx(mask_array, cv2.MORPH_GRADIENT, boundary_kernel) > 0
+
+            if np.any(boundary):
+                boundary_saturation = saturation[boundary]
+                saturation_std = np.std(boundary_saturation)
+            else:
+                saturation_std = 0
+
+            # Calculate score
+            sharpness_score = 100
+            if sharpness_ratio < 0.3:
+                sharpness_score = 40  # Much blurrier than surroundings
+            elif sharpness_ratio < 0.6:
+                sharpness_score = 60
+            elif sharpness_ratio < 0.8:
+                sharpness_score = 80
+
+            bleeding_penalty = min(20, saturation_std * 0.5)
+
+            final_score = max(0, sharpness_score - bleeding_penalty)
+            passed = final_score >= 60
+
+            issue = ""
+            if sharpness_ratio < 0.5:
+                issue = "Inpainted region appears blurry"
+            elif saturation_std > 40:
+                issue = "Possible color bleeding at edges"
+            elif final_score < 60:
+                issue = "Detected visual artifacts"
+
+            return QualityResult(
+                score=final_score,
+                passed=passed,
+                issue=issue,
+                details={
+                    "sharpness": sharpness,
+                    "sharpness_ratio": sharpness_ratio,
+                    "boundary_saturation_std": saturation_std
+                }
+            )
+
+        except Exception as e:
+            logger.error(f"Inpainting artifact detection failed: {e}")
+            return QualityResult(score=0, passed=False, issue=str(e), details={})
+
+    def run_inpainting_checks(
+        self,
+        original: Image.Image,
+        inpainted: Image.Image,
+        mask: Image.Image
+    ) -> Dict[str, Any]:
+        """
+        Run all inpainting-specific quality checks.
+
+        Parameters
+        ----------
+        original : PIL.Image
+            Original image before inpainting
+        inpainted : PIL.Image
+            Result after inpainting
+        mask : PIL.Image
+            Inpainting mask
+
+        Returns
+        -------
+        dict
+            Comprehensive quality assessment for inpainting
+        """
+        logger.info("Running inpainting quality checks...")
+
+        results = {
+            "checks": {},
+            "overall_score": 0,
+            "passed": True,
+            "warnings": [],
+            "errors": []
+        }
+
+        # Run inpainting-specific checks
+        edge_result = self.check_inpainting_edge_continuity(original, inpainted, mask)
+        results["checks"]["edge_continuity"] = {
+            "score": edge_result.score,
+            "passed": edge_result.passed,
+            "issue": edge_result.issue,
+            "details": edge_result.details
+        }
+
+        harmony_result = self.check_inpainting_color_harmony(original, inpainted, mask)
+        results["checks"]["color_harmony"] = {
+            "score": harmony_result.score,
+            "passed": harmony_result.passed,
+            "issue": harmony_result.issue,
+            "details": harmony_result.details
+        }
+
+        artifact_result = self.check_inpainting_artifact_detection(inpainted, mask)
+        results["checks"]["artifact_detection"] = {
+            "score": artifact_result.score,
+            "passed": artifact_result.passed,
+            "issue": artifact_result.issue,
+            "details": artifact_result.details
+        }
+
+        # Calculate overall score (weighted)
+        weights = {
+            "edge_continuity": 0.4,
+            "color_harmony": 0.35,
+            "artifact_detection": 0.25
+        }
+
+        total_score = (
+            edge_result.score * weights["edge_continuity"] +
+            harmony_result.score * weights["color_harmony"] +
+            artifact_result.score * weights["artifact_detection"]
+        )
+        results["overall_score"] = round(total_score, 1)
+
+        # Determine overall pass/fail
+        results["passed"] = all([
+            edge_result.passed,
+            harmony_result.passed,
+            artifact_result.passed
+        ])
+
+        # Collect issues
+        for check_name, check_data in results["checks"].items():
+            if check_data["issue"]:
+                if check_data["passed"]:
+                    results["warnings"].append(f"{check_name}: {check_data['issue']}")
+                else:
+                    results["errors"].append(f"{check_name}: {check_data['issue']}")
+
+        logger.info(f"Inpainting quality: {results['overall_score']:.1f}, Passed: {results['passed']}")
+
+        return results

scene_templates.py

@@ -4,7 +4,6 @@ from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
 
-
 @dataclass
 class SceneTemplate:
     """Data class representing a scene template"""
@@ -25,7 +24,7 @@ class SceneTemplateManager:
 
     # Scene template definitions
     TEMPLATES: Dict[str, SceneTemplate] = {
-        # === Professional Category ===
+        # Professional Category 
         "office_modern": SceneTemplate(
             key="office_modern",
             name="Modern Office",
@@ -72,7 +71,7 @@ class SceneTemplateManager:
             guidance_scale=7.5
         ),
 
-        # === Nature Category ===
+        # Nature Category 
         "beach_sunset": SceneTemplate(
             key="beach_sunset",
             name="Sunset Beach",
@@ -128,7 +127,7 @@ class SceneTemplateManager:
             guidance_scale=7.0
         ),
 
-        # === Urban Category ===
+        # Urban Category 
         "city_skyline": SceneTemplate(
             key="city_skyline",
             name="City Skyline",
@@ -175,7 +174,7 @@ class SceneTemplateManager:
             guidance_scale=7.5
         ),
 
-        # === Artistic Category ===
+        # Artistic Category 
         "gradient_soft": SceneTemplate(
             key="gradient_soft",
             name="Soft Gradient",
@@ -213,7 +212,7 @@ class SceneTemplateManager:
             guidance_scale=6.5
         ),
 
-        # === Seasonal Category ===
+        # Seasonal Category 
         "autumn_foliage": SceneTemplate(
             key="autumn_foliage",
             name="Autumn Foliage",

scene_weaver_core.py

@@ -5,25 +5,47 @@ from PIL import Image
 import logging
 import gc
 import time
-from typing import Optional, Dict, Any, Tuple, List
+from typing import Optional, Dict, Any, Tuple, List, Callable
 from pathlib import Path
 import warnings
 warnings.filterwarnings("ignore")
 
 from diffusers import StableDiffusionXLPipeline, DPMSolverMultistepScheduler
 import open_clip
+import traceback
 from mask_generator import MaskGenerator
 from image_blender import ImageBlender
 from quality_checker import QualityChecker
+from model_manager import get_model_manager, ModelPriority
+from inpainting_module import InpaintingModule
+from inpainting_templates import InpaintingTemplateManager
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)
 
 class SceneWeaverCore:
     """
-    SceneWeaver with perfect background generation + fixed blending + memory optimization
+    SceneWeaver Core Engine - Facade for all AI generation subsystems.
+
+    Integrates SDXL pipeline, OpenCLIP analysis, mask generation, image blending,
+    and inpainting functionality into a unified interface.
+
+    Attributes:
+        device: Computation device (cuda/mps/cpu)
+        is_initialized: Whether models are loaded
+        inpainting_module: Optional InpaintingModule instance
+
+    Example:
+        >>> core = SceneWeaverCore()
+        >>> core.load_models()
+        >>> result = core.generate_and_combine(image, prompt="sunset beach")
     """
 
+    # Model registry names
+    MODEL_SDXL_PIPELINE = "sdxl_background_pipeline"
+    MODEL_OPENCLIP = "openclip_analyzer"
+    MODEL_INPAINTING_PIPELINE = "inpainting_pipeline"
+
     # Style presets for diversity generation mode
     STYLE_PRESETS = {
         "professional": {
@@ -82,7 +104,17 @@ class SceneWeaverCore:
         self.image_blender = ImageBlender()
         self.quality_checker = QualityChecker()
 
-        logger.info(f"OptimizedSceneWeaver initialized on {self.device}")
+        # Model manager reference
+        self._model_manager = get_model_manager()
+
+        # Inpainting module (lazy loaded)
+        self._inpainting_module = None
+        self._inpainting_initialized = False
+
+        # Current mode tracking
+        self._current_mode = "background"  # "background" or "inpainting"
+
+        logger.info(f"SceneWeaverCore initialized on {self.device}")
 
     def _setup_device(self, device: str) -> str:
         """Setup computation device"""
@@ -277,7 +309,7 @@ class SceneWeaverCore:
             # Analyze image characteristics
             img_array = np.array(foreground_image.convert('RGB'))
 
-            # === Analyze color temperature ===
+            # Analyze color temperature 
             # Convert to LAB to analyze color temperature
             lab = cv2.cvtColor(img_array, cv2.COLOR_RGB2LAB)
             avg_a = np.mean(lab[:, :, 1])  # a channel: green(-) to red(+)
@@ -286,12 +318,12 @@ class SceneWeaverCore:
             # Determine warm/cool tone
             is_warm = avg_b > 128  # b > 128 means more yellow/warm
 
-            # === Analyze brightness ===
+            # Analyze brightness 
             gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
             avg_brightness = np.mean(gray)
             is_bright = avg_brightness > 127
 
-            # === Get subject type from CLIP ===
+            # Get subject type from CLIP 
             clip_analysis = self.analyze_image_with_clip(foreground_image)
             subject_type = "unknown"
 
@@ -306,7 +338,7 @@ class SceneWeaverCore:
             elif "nature" in clip_analysis.lower() or "landscape" in clip_analysis.lower():
                 subject_type = "nature"
 
-            # === Build prompt fragments library ===
+            # Build prompt fragments library
             lighting_options = {
                 "warm_bright": "warm golden hour lighting, soft natural light",
                 "warm_dark": "warm ambient lighting, cozy atmosphere",
@@ -325,7 +357,7 @@ class SceneWeaverCore:
 
             quality_modifiers = "high quality, detailed, sharp focus, photorealistic"
 
-            # === Select appropriate fragments ===
+            # Select appropriate fragments 
             # Lighting based on color temperature and brightness
             if is_warm and is_bright:
                 lighting = lighting_options["warm_bright"]
@@ -339,7 +371,7 @@ class SceneWeaverCore:
             # Atmosphere based on subject type
             atmosphere = atmosphere_options.get(subject_type, atmosphere_options["unknown"])
 
-            # === Check for conflicts in user prompt ===
+            # Check for conflicts in user prompt 
             user_prompt_lower = user_prompt.lower()
 
             # Avoid adding conflicting descriptions
@@ -348,7 +380,7 @@ class SceneWeaverCore:
             if "dark" in user_prompt_lower or "night" in user_prompt_lower:
                 lighting = lighting.replace("bright", "").replace("daylight", "")
 
-            # === Combine enhanced prompt ===
+            # Combine enhanced prompt 
             fragments = [user_prompt]
 
             if lighting:
@@ -592,7 +624,6 @@ class SceneWeaverCore:
             }
 
         except Exception as e:
-            import traceback
             error_traceback = traceback.format_exc()
             logger.error(f"❌ Generation and combination failed: {str(e)}")
             logger.error(f"📍 Full traceback:\n{error_traceback}")
@@ -806,3 +837,341 @@ class SceneWeaverCore:
             })
 
         return status
+
+    # INPAINTING FACADE METHODS
+    def get_inpainting_module(self):
+        """
+        Get or create the InpaintingModule instance.
+
+        Implements lazy loading - module is only created when first accessed.
+
+        Returns
+        -------
+        InpaintingModule
+            The inpainting module instance
+        """
+        if self._inpainting_module is None:
+            self._inpainting_module = InpaintingModule(device=self.device)
+            self._inpainting_module.set_model_manager(self._model_manager)
+            logger.info("InpaintingModule created (lazy load)")
+
+        return self._inpainting_module
+
+    def switch_to_inpainting_mode(
+        self,
+        conditioning_type: str = "canny",
+        progress_callback: Optional[Callable[[str, int], None]] = None
+    ) -> bool:
+        """
+        Switch to inpainting mode, unloading background pipeline.
+
+        Implements mutual exclusion between pipelines to conserve memory.
+
+        Parameters
+        ----------
+        conditioning_type : str
+            ControlNet conditioning type: "canny" or "depth"
+        progress_callback : callable, optional
+            Progress update function(message, percentage)
+
+        Returns
+        -------
+        bool
+            True if switch was successful
+        """
+        logger.info(f"Switching to inpainting mode (conditioning: {conditioning_type})")
+
+        try:
+            # Unload background pipeline first
+            if self.pipeline is not None:
+                if progress_callback:
+                    progress_callback("Unloading background pipeline...", 10)
+
+                del self.pipeline
+                self.pipeline = None
+                self._ultra_memory_cleanup()
+                logger.info("Background pipeline unloaded")
+
+            # Load inpainting pipeline
+            if progress_callback:
+                progress_callback("Loading inpainting pipeline...", 20)
+
+            inpaint_module = self.get_inpainting_module()
+
+            def inpaint_progress(msg, pct):
+                if progress_callback:
+                    # Map inpainting progress (0-100) to (20-90)
+                    mapped_pct = 20 + int(pct * 0.7)
+                    progress_callback(msg, mapped_pct)
+
+            success, error_msg = inpaint_module.load_inpainting_pipeline(
+                conditioning_type=conditioning_type,
+                progress_callback=inpaint_progress
+            )
+
+            if success:
+                self._current_mode = "inpainting"
+                self._inpainting_initialized = True
+
+                if progress_callback:
+                    progress_callback("Inpainting mode ready!", 100)
+
+                logger.info("Successfully switched to inpainting mode")
+            else:
+                self._last_inpainting_error = error_msg
+                logger.error(f"Failed to load inpainting pipeline: {error_msg}")
+
+            return success
+
+        except Exception as e:
+            traceback.print_exc()
+            self._last_inpainting_error = str(e)
+            logger.error(f"Failed to switch to inpainting mode: {e}")
+            if progress_callback:
+                progress_callback(f"Error: {str(e)}", 0)
+            return False
+
+    def switch_to_background_mode(
+        self,
+        progress_callback: Optional[Callable[[str, int], None]] = None
+    ) -> bool:
+        """
+        Switch back to background generation mode.
+
+        Parameters
+        ----------
+        progress_callback : callable, optional
+            Progress update function
+
+        Returns
+        -------
+        bool
+            True if switch was successful
+        """
+        logger.info("Switching to background generation mode")
+
+        try:
+            # Unload inpainting pipeline
+            if self._inpainting_module is not None and self._inpainting_module.is_initialized:
+                if progress_callback:
+                    progress_callback("Unloading inpainting pipeline...", 10)
+
+                self._inpainting_module._unload_pipeline()
+                self._ultra_memory_cleanup()
+
+            # Reload background pipeline
+            if progress_callback:
+                progress_callback("Loading background pipeline...", 30)
+
+            # Reset initialization flag to force reload
+            self.is_initialized = False
+            self.load_models(progress_callback=progress_callback)
+
+            self._current_mode = "background"
+
+            if progress_callback:
+                progress_callback("Background mode ready!", 100)
+
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to switch to background mode: {e}")
+            return False
+
+    def execute_inpainting(
+        self,
+        image: Image.Image,
+        mask: Image.Image,
+        prompt: str,
+        preview_only: bool = False,
+        template_key: Optional[str] = None,
+        progress_callback: Optional[Callable[[str, int], None]] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Execute inpainting operation through the Facade.
+
+        This is the main entry point for inpainting functionality.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Original image to inpaint
+        mask : PIL.Image
+            Inpainting mask (white = area to regenerate)
+        prompt : str
+            Text description of desired content
+        preview_only : bool
+            If True, generate quick preview only
+        template_key : str, optional
+            Inpainting template key to use
+        progress_callback : callable, optional
+            Progress update function
+        **kwargs
+            Additional inpainting parameters
+
+        Returns
+        -------
+        dict
+            Result dictionary with images and metadata
+        """
+        # Ensure inpainting mode is active
+        if self._current_mode != "inpainting" or not self._inpainting_initialized:
+            conditioning = kwargs.get('conditioning_type', 'canny')
+            if not self.switch_to_inpainting_mode(conditioning, progress_callback):
+                error_detail = getattr(self, '_last_inpainting_error', 'Unknown error')
+                return {
+                    "success": False,
+                    "error": f"Failed to initialize inpainting mode: {error_detail}"
+                }
+
+        inpaint_module = self.get_inpainting_module()
+
+        # Apply template if specified
+        if template_key:
+            template_mgr = InpaintingTemplateManager()
+            template = template_mgr.get_template(template_key)
+
+            if template:
+                # Build prompt from template
+                prompt = template_mgr.build_prompt(template_key, prompt)
+                # Apply template parameters as defaults
+                params = template_mgr.get_parameters_for_template(template_key)
+                for key, value in params.items():
+                    if key not in kwargs:
+                        kwargs[key] = value
+
+        # Execute inpainting
+        result = inpaint_module.execute_inpainting(
+            image=image,
+            mask=mask,
+            prompt=prompt,
+            preview_only=preview_only,
+            progress_callback=progress_callback,
+            **kwargs
+        )
+
+        # Convert InpaintingResult to dictionary format
+        return {
+            "success": result.success,
+            "combined_image": result.blended_image or result.result_image,
+            "generated_image": result.result_image,
+            "preview_image": result.preview_image,
+            "control_image": result.control_image,
+            "original_image": image,
+            "mask": mask,
+            "quality_score": result.quality_score,
+            "generation_time": result.generation_time,
+            "metadata": result.metadata,
+            "error": result.error_message if not result.success else None
+        }
+
+    def execute_inpainting_with_optimization(
+        self,
+        image: Image.Image,
+        mask: Image.Image,
+        prompt: str,
+        progress_callback: Optional[Callable[[str, int], None]] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Execute inpainting with automatic quality optimization.
+
+        Retries with adjusted parameters if quality is below threshold.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Original image
+        mask : PIL.Image
+            Inpainting mask
+        prompt : str
+            Text prompt
+        progress_callback : callable, optional
+            Progress callback
+        **kwargs
+            Additional parameters
+
+        Returns
+        -------
+        dict
+            Optimized result dictionary
+        """
+        # Ensure inpainting mode
+        if self._current_mode != "inpainting" or not self._inpainting_initialized:
+            conditioning = kwargs.get('conditioning_type', 'canny')
+            if not self.switch_to_inpainting_mode(conditioning, progress_callback):
+                error_detail = getattr(self, '_last_inpainting_error', 'Unknown error')
+                return {
+                    "success": False,
+                    "error": f"Failed to initialize inpainting mode: {error_detail}"
+                }
+
+        inpaint_module = self.get_inpainting_module()
+
+        result = inpaint_module.execute_with_auto_optimization(
+            image=image,
+            mask=mask,
+            prompt=prompt,
+            quality_checker=self.quality_checker,
+            progress_callback=progress_callback,
+            **kwargs
+        )
+
+        return {
+            "success": result.success,
+            "combined_image": result.blended_image or result.result_image,
+            "generated_image": result.result_image,
+            "preview_image": result.preview_image,
+            "control_image": result.control_image,
+            "quality_score": result.quality_score,
+            "quality_details": result.quality_details,
+            "retries": result.retries,
+            "generation_time": result.generation_time,
+            "metadata": result.metadata,
+            "error": result.error_message if not result.success else None
+        }
+
+    def get_current_mode(self) -> str:
+        """
+        Get current operation mode.
+
+        Returns
+        -------
+        str
+            "background" or "inpainting"
+        """
+        return self._current_mode
+
+    def is_inpainting_ready(self) -> bool:
+        """
+        Check if inpainting is ready to use.
+
+        Returns
+        -------
+        bool
+            True if inpainting module is loaded and ready
+        """
+        return (
+            self._inpainting_module is not None and
+            self._inpainting_module.is_initialized
+        )
+
+    def get_inpainting_status(self) -> Dict[str, Any]:
+        """
+        Get inpainting module status.
+
+        Returns
+        -------
+        dict
+            Status information
+        """
+        if self._inpainting_module is None:
+            return {
+                "initialized": False,
+                "mode": self._current_mode
+            }
+
+        status = self._inpainting_module.get_status()
+        status["mode"] = self._current_mode
+        return status

ui_manager.py

@@ -1,7 +1,8 @@
 import logging
 import time
+import traceback
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Dict, Any, List
 from PIL import Image
 import numpy as np
 import cv2
@@ -11,6 +12,7 @@ import spaces
 from scene_weaver_core import SceneWeaverCore
 from css_styles import CSSStyles
 from scene_templates import SceneTemplateManager
+from inpainting_templates import InpaintingTemplateManager
 
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)
@@ -23,13 +25,26 @@ logging.basicConfig(
 
 
 class UIManager:
-    """Gradio UI with enhanced memory management and professional design"""
+    """
+    Gradio UI Manager with support for background generation and inpainting.
+
+    Provides a professional interface with mode switching, template selection,
+    and advanced parameter controls.
+
+    Attributes:
+        sceneweaver: SceneWeaverCore instance
+        template_manager: Scene template manager
+        inpainting_template_manager: Inpainting template manager
+    """
 
     def __init__(self):
         self.sceneweaver = SceneWeaverCore()
         self.template_manager = SceneTemplateManager()
+        self.inpainting_template_manager = InpaintingTemplateManager()
         self.generation_history = []
+        self.inpainting_history = []
         self._preview_sensitivity = 0.5
+        self._current_mode = "background"  # "background" or "inpainting"
 
     def apply_template(self, display_name: str, current_negative: str) -> Tuple[str, str, float]:
         """
@@ -234,7 +249,6 @@ class UIManager:
                 return None, None, None, f"Error: {error_msg}", gr.update(visible=False)
 
         except Exception as e:
-            import traceback
             error_traceback = traceback.format_exc()
             logger.error(f"Generation handler error: {str(e)}")
             logger.error(f"Traceback:\n{error_traceback}")
@@ -249,18 +263,12 @@ class UIManager:
         self._gradio_version = gr.__version__
         self._gradio_major = int(self._gradio_version.split('.')[0])
 
-        # Gradio 5.x: css/theme moved to launch(), Blocks() has minimal params
-        # Gradio 4.x: css/theme are in Blocks() constructor
-        if self._gradio_major >= 5:
-            blocks_kwargs = {
-                "title": "SceneWeaver - AI Background Generator"
-            }
-        else:
-            blocks_kwargs = {
-                "css": self._css,
-                "title": "SceneWeaver - AI Background Generator",
-                "theme": gr.themes.Soft()
-            }
+        # Both Gradio 4.x and 5.x use css/theme in Blocks() constructor
+        blocks_kwargs = {
+            "css": self._css,
+            "title": "SceneWeaver - AI Background Generator",
+            "theme": gr.themes.Soft()
+        }
 
         with gr.Blocks(**blocks_kwargs) as interface:
 
@@ -271,177 +279,232 @@ class UIManager:
                     <span class="title-emoji">🎨</span>
                     SceneWeaver
                 </h1>
-                <p class="main-subtitle">AI-powered background generation with professional edge processing</p>
+                <p class="main-subtitle">AI-powered background generation and inpainting with professional edge processing</p>
             </div>
             """)
 
-            with gr.Row():
-                # Left Column - Input controls
-                with gr.Column(scale=1, min_width=350, elem_classes=["feature-card"]):
-                    gr.HTML("""
-                    <div class="card-content">
-                        <h3 class="card-title">
-                            <span class="section-emoji">📸</span>
-                            Upload & Generate
-                        </h3>
-                    </div>
-                    """)
+            # Main Tabs for Mode Selection
+            with gr.Tabs(elem_id="main-mode-tabs") as main_tabs:
 
-                    uploaded_image = gr.Image(
-                        label="Upload Your Image",
-                        type="pil",
-                        height=280,
-                        elem_classes=["input-field"]
-                    )
+                # Background Generation Tab
+                with gr.Tab("Background Generation", elem_id="bg-gen-tab"):
 
-                    # Scene Template Selector (without Accordion to fix dropdown positioning in Gradio 5.x)
-                    template_dropdown = gr.Dropdown(
-                        label="Scene Templates",
-                        choices=[""] + self.template_manager.get_template_choices_sorted(),
-                        value="",
-                        info="24 curated scenes sorted A-Z (optional)",
-                        elem_classes=["template-dropdown"]
-                    )
+                    with gr.Row():
+                        # Left Column - Input controls
+                        with gr.Column(scale=1, min_width=350, elem_classes=["feature-card"]):
+                            gr.HTML("""
+                            <div class="card-content">
+                                <h3 class="card-title">
+                                    <span class="section-emoji">📸</span>
+                                    Upload & Generate
+                                </h3>
+                            </div>
+                            """)
+
+                            uploaded_image = gr.Image(
+                                label="Upload Your Image",
+                                type="pil",
+                                height=280,
+                                elem_classes=["input-field"]
+                            )
 
-                    prompt_input = gr.Textbox(
-                        label="Background Scene Description",
-                        placeholder="Select a template above or describe your own scene...",
-                        lines=3,
-                        elem_classes=["input-field"]
-                    )
+                            # Scene Template Selector (without Accordion to fix dropdown positioning in Gradio 5.x)
+                            template_dropdown = gr.Dropdown(
+                                label="Scene Templates",
+                                choices=[""] + self.template_manager.get_template_choices_sorted(),
+                                value="",
+                                info="24 curated scenes sorted A-Z (optional)",
+                                elem_classes=["template-dropdown"]
+                            )
 
-                    combination_mode = gr.Dropdown(
-                        label="Composition Mode",
-                        choices=["center", "left_half", "right_half", "full"],
-                        value="center",
-                        info="center=Smart Center | left_half=Left Half | right_half=Right Half | full=Full Image",
-                        elem_classes=["input-field"]
-                    )
+                            prompt_input = gr.Textbox(
+                                label="Background Scene Description",
+                                placeholder="Select a template above or describe your own scene...",
+                                lines=3,
+                                elem_classes=["input-field"]
+                            )
 
-                    focus_mode = gr.Dropdown(
-                        label="Focus Mode",
-                        choices=["person", "scene"],
-                        value="person",
-                        info="person=Tight Crop | scene=Include Surrounding Objects",
-                        elem_classes=["input-field"]
-                    )
+                            combination_mode = gr.Dropdown(
+                                label="Composition Mode",
+                                choices=["center", "left_half", "right_half", "full"],
+                                value="center",
+                                info="center=Smart Center | left_half=Left Half | right_half=Right Half | full=Full Image",
+                                elem_classes=["input-field"]
+                            )
 
-                    with gr.Accordion("Advanced Options", open=False):
-                        negative_prompt = gr.Textbox(
-                            label="Negative Prompt",
-                            value="blurry, low quality, distorted, people, characters",
-                            lines=2,
-                            elem_classes=["input-field"]
-                        )
+                            focus_mode = gr.Dropdown(
+                                label="Focus Mode",
+                                choices=["person", "scene"],
+                                value="person",
+                                info="person=Tight Crop | scene=Include Surrounding Objects",
+                                elem_classes=["input-field"]
+                            )
 
-                        steps_slider = gr.Slider(
-                            label="Quality Steps",
-                            minimum=15,
-                            maximum=50,
-                            value=25,
-                            step=5,
-                            elem_classes=["input-field"]
-                        )
+                            with gr.Accordion("Advanced Options", open=False):
+                                negative_prompt = gr.Textbox(
+                                    label="Negative Prompt",
+                                    value="blurry, low quality, distorted, people, characters",
+                                    lines=2,
+                                    elem_classes=["input-field"]
+                                )
+
+                                steps_slider = gr.Slider(
+                                    label="Quality Steps",
+                                    minimum=15,
+                                    maximum=50,
+                                    value=25,
+                                    step=5,
+                                    elem_classes=["input-field"]
+                                )
+
+                                guidance_slider = gr.Slider(
+                                    label="Guidance Scale",
+                                    minimum=5.0,
+                                    maximum=15.0,
+                                    value=7.5,
+                                    step=0.5,
+                                    elem_classes=["input-field"]
+                                )
+
+                            generate_btn = gr.Button(
+                                "Generate Background",
+                                variant="primary",
+                                size="lg",
+                                elem_classes=["primary-button"]
+                            )
 
-                        guidance_slider = gr.Slider(
-                            label="Guidance Scale",
-                            minimum=5.0,
-                            maximum=15.0,
-                            value=7.5,
-                            step=0.5,
-                            elem_classes=["input-field"]
-                        )
+                        # Right Column - Results display
+                        with gr.Column(scale=2, elem_classes=["feature-card"], elem_id="results-gallery-centered"):
+                            gr.HTML("""
+                            <div class="card-content">
+                                <h3 class="card-title">
+                                    <span class="section-emoji">🎭</span>
+                                    Results Gallery
+                                </h3>
+                            </div>
+                            """)
+
+                            # Loading notice
+                            gr.HTML("""
+                            <div class="loading-notice">
+                                <span class="loading-notice-icon">⏱️</span>
+                                <span class="loading-notice-text">
+                                    <strong>First-time users:</strong> Initial model loading takes 1-2 minutes.
+                                    Subsequent generations are much faster (~30s).
+                                </span>
+                            </div>
+                            """)
+
+                            # Quick start guide
+                            gr.HTML("""
+                            <details class="user-guidance-panel">
+                                <summary class="guidance-summary">
+                                    <span class="emoji-enhanced">💡</span>
+                                    Quick Start Guide
+                                </summary>
+                                <div class="guidance-content">
+                                    <p><strong>Step 1:</strong> Upload any image with a clear subject</p>
+                                    <p><strong>Step 2:</strong> Describe or Choose your desired background scene</p>
+                                    <p><strong>Step 3:</strong> Choose composition mode (center works best)</p>
+                                    <p><strong>Step 4:</strong> Click Generate and wait for the magic!</p>
+                                    <p><strong>Tip:</strong> For dark clothing, ensure good lighting in original photo.</p>
+                                </div>
+                            </details>
+                            """)
+
+                            with gr.Tabs():
+                                with gr.TabItem("Final Result"):
+                                    combined_output = gr.Image(
+                                        label="Your Generated Image",
+                                        elem_classes=["result-gallery"],
+                                        show_label=False
+                                    )
+                                with gr.TabItem("Background"):
+                                    generated_output = gr.Image(
+                                        label="Generated Background",
+                                        elem_classes=["result-gallery"],
+                                        show_label=False
+                                    )
+                                with gr.TabItem("Original"):
+                                    original_output = gr.Image(
+                                        label="Processed Original",
+                                        elem_classes=["result-gallery"],
+                                        show_label=False
+                                    )
+
+                            status_output = gr.Textbox(
+                                label="Status",
+                                value="Ready to create! Upload an image and describe your vision.",
+                                interactive=False,
+                                elem_classes=["status-panel", "status-ready"]
+                            )
 
-                    generate_btn = gr.Button(
-                        "Generate Background",
-                        variant="primary",
-                        size="lg",
-                        elem_classes=["primary-button"]
+                            with gr.Row():
+                                download_btn = gr.DownloadButton(
+                                    "Download Result",
+                                    value=None,
+                                    visible=False,
+                                    elem_classes=["secondary-button"]
+                                )
+                                clear_btn = gr.Button(
+                                    "Clear All",
+                                    elem_classes=["secondary-button"]
+                                )
+                                memory_btn = gr.Button(
+                                    "Clean Memory",
+                                    elem_classes=["secondary-button"]
+                                )
+
+                    # Event handlers for Background Generation Tab
+                    # Template selection handler
+                    template_dropdown.change(
+                        fn=self.apply_template,
+                        inputs=[template_dropdown, negative_prompt],
+                        outputs=[prompt_input, negative_prompt, guidance_slider]
                     )
 
-                # Right Column - Results display
-                with gr.Column(scale=2, elem_classes=["feature-card"], elem_id="results-gallery-centered"):
-                    gr.HTML("""
-                    <div class="card-content">
-                        <h3 class="card-title">
-                            <span class="section-emoji">🎭</span>
-                            Results Gallery
-                        </h3>
-                    </div>
-                    """)
-
-                    # Loading notice
-                    gr.HTML("""
-                    <div class="loading-notice">
-                        <span class="loading-notice-icon">⏱️</span>
-                        <span class="loading-notice-text">
-                            <strong>First-time users:</strong> Initial model loading takes 1-2 minutes.
-                            Subsequent generations are much faster (~30s).
-                        </span>
-                    </div>
-                    """)
-
-                    # Quick start guide
-                    gr.HTML("""
-                    <details class="user-guidance-panel">
-                        <summary class="guidance-summary">
-                            <span class="emoji-enhanced">💡</span>
-                            Quick Start Guide
-                        </summary>
-                        <div class="guidance-content">
-                            <p><strong>Step 1:</strong> Upload any image with a clear subject</p>
-                            <p><strong>Step 2:</strong> Describe or Choose your desired background scene</p>
-                            <p><strong>Step 3:</strong> Choose composition mode (center works best)</p>
-                            <p><strong>Step 4:</strong> Click Generate and wait for the magic!</p>
-                            <p><strong>Tip:</strong> For dark clothing, ensure good lighting in original photo.</p>
-                        </div>
-                    </details>
-                    """)
+                    generate_btn.click(
+                        fn=self.generate_handler,
+                        inputs=[
+                            uploaded_image,
+                            prompt_input,
+                            combination_mode,
+                            focus_mode,
+                            negative_prompt,
+                            steps_slider,
+                            guidance_slider
+                        ],
+                        outputs=[
+                            combined_output,
+                            generated_output,
+                            original_output,
+                            status_output,
+                            download_btn
+                        ]
+                    )
 
-                    with gr.Tabs():
-                        with gr.TabItem("Final Result"):
-                            combined_output = gr.Image(
-                                label="Your Generated Image",
-                                elem_classes=["result-gallery"],
-                                show_label=False
-                            )
-                        with gr.TabItem("Background"):
-                            generated_output = gr.Image(
-                                label="Generated Background",
-                                elem_classes=["result-gallery"],
-                                show_label=False
-                            )
-                        with gr.TabItem("Original"):
-                            original_output = gr.Image(
-                                label="Processed Original",
-                                elem_classes=["result-gallery"],
-                                show_label=False
-                            )
+                    clear_btn.click(
+                        fn=lambda: (None, None, None, "Ready to create!", gr.update(visible=False)),
+                        outputs=[combined_output, generated_output, original_output, status_output, download_btn]
+                    )
 
-                    status_output = gr.Textbox(
-                        label="Status",
-                        value="Ready to create! Upload an image and describe your vision.",
-                        interactive=False,
-                        elem_classes=["status-panel", "status-ready"]
+                    memory_btn.click(
+                        fn=lambda: self.sceneweaver._ultra_memory_cleanup() or "Memory cleaned!",
+                        outputs=[status_output]
                     )
 
-                    with gr.Row():
-                        download_btn = gr.DownloadButton(
-                            "Download Result",
-                            value=None,
-                            visible=False,
-                            elem_classes=["secondary-button"]
-                        )
-                        clear_btn = gr.Button(
-                            "Clear All",
-                            elem_classes=["secondary-button"]
-                        )
-                        memory_btn = gr.Button(
-                            "Clean Memory",
-                            elem_classes=["secondary-button"]
-                        )
+                    combined_output.change(
+                        fn=lambda img: gr.update(value="outputs/latest_combined.png", visible=True) if (img is not None) else gr.update(visible=False),
+                        inputs=[combined_output],
+                        outputs=[download_btn]
+                    )
+
+                # End of Background Generation Tab
+
+                # Inpainting Tab
+                self.create_inpainting_tab()
 
-            # Footer with tech credits
+            # Footer with tech credits (outside tabs)
             gr.HTML("""
             <div class="app-footer">
                 <div class="footer-powered">
@@ -464,57 +527,13 @@ class UIManager:
             </div>
             """)
 
-            # Event handlers
-            # Template selection handler
-            template_dropdown.change(
-                fn=self.apply_template,
-                inputs=[template_dropdown, negative_prompt],
-                outputs=[prompt_input, negative_prompt, guidance_slider]
-            )
-
-            generate_btn.click(
-                fn=self.generate_handler,
-                inputs=[
-                    uploaded_image,
-                    prompt_input,
-                    combination_mode,
-                    focus_mode,
-                    negative_prompt,
-                    steps_slider,
-                    guidance_slider
-                ],
-                outputs=[
-                    combined_output,
-                    generated_output,
-                    original_output,
-                    status_output,
-                    download_btn
-                ]
-            )
-
-            clear_btn.click(
-                fn=lambda: (None, None, None, "Ready to create!", gr.update(visible=False)),
-                outputs=[combined_output, generated_output, original_output, status_output, download_btn]
-            )
-
-            memory_btn.click(
-                fn=lambda: self.sceneweaver._ultra_memory_cleanup() or "Memory cleaned!",
-                outputs=[status_output]
-            )
-
-            combined_output.change(
-                fn=lambda img: gr.update(value="outputs/latest_combined.png", visible=True) if (img is not None) else gr.update(visible=False),
-                inputs=[combined_output],
-                outputs=[download_btn]
-            )
-
         return interface
 
     def launch(self, share: bool = True, debug: bool = False):
         """Launch the UI interface"""
         interface = self.create_interface()
 
-        # Build launch kwargs based on Gradio version
+        # Launch kwargs compatible with both Gradio 4.x and 5.x
         launch_kwargs = {
             "share": share,
             "debug": debug,
@@ -522,10 +541,450 @@ class UIManager:
             "quiet": False
         }
 
-        # Gradio 5.x: css/theme are passed to launch()
-        # Gradio 4.x: these were already set in Blocks()
-        if self._gradio_major >= 5:
-            launch_kwargs["css"] = self._css
-            launch_kwargs["theme"] = gr.themes.Soft()
+        return interface.launch(**launch_kwargs)
+
+    # INPAINTING UI METHODS
+    def apply_inpainting_template(
+        self,
+        display_name: str,
+        current_prompt: str
+    ) -> Tuple[str, float, int, str]:
+        """
+        Apply an inpainting template to the UI fields.
+
+        Parameters
+        ----------
+        display_name : str
+            Template display name from dropdown
+        current_prompt : str
+            Current prompt content
+
+        Returns
+        -------
+        tuple
+            (prompt, conditioning_scale, feather_radius, conditioning_type)
+        """
+        if not display_name:
+            return current_prompt, 0.7, 8, "canny"
+
+        template_key = self.inpainting_template_manager.get_template_key_from_display(display_name)
+        if not template_key:
+            return current_prompt, 0.7, 8, "canny"
+
+        template = self.inpainting_template_manager.get_template(template_key)
+        if template:
+            params = self.inpainting_template_manager.get_parameters_for_template(template_key)
+            return (
+                current_prompt,
+                params.get('controlnet_conditioning_scale', 0.7),
+                params.get('feather_radius', 8),
+                params.get('preferred_conditioning', 'canny')
+            )
+
+        return current_prompt, 0.7, 8, "canny"
+
+    def extract_mask_from_editor(self, editor_output: Dict[str, Any]) -> Optional[Image.Image]:
+        """
+        Extract mask from Gradio ImageEditor output.
+
+        Handles different Gradio versions' output formats.
+
+        Parameters
+        ----------
+        editor_output : dict
+            Output from gr.ImageEditor component
+
+        Returns
+        -------
+        PIL.Image or None
+            Extracted mask as grayscale image
+        """
+        if editor_output is None:
+            return None
+
+        try:
+            # Gradio 5.x format
+            if isinstance(editor_output, dict):
+                # Check for 'layers' key (Gradio 5.x ImageEditor)
+                if 'layers' in editor_output and editor_output['layers']:
+                    # Get the first layer as mask
+                    layer = editor_output['layers'][0]
+                    if isinstance(layer, np.ndarray):
+                        mask_array = layer
+                    elif isinstance(layer, Image.Image):
+                        mask_array = np.array(layer)
+                    else:
+                        return None
+
+                # Check for 'composite' key
+                elif 'composite' in editor_output:
+                    composite = editor_output['composite']
+                    if isinstance(composite, np.ndarray):
+                        mask_array = composite
+                    elif isinstance(composite, Image.Image):
+                        mask_array = np.array(composite)
+                    else:
+                        return None
+                else:
+                    return None
+
+            elif isinstance(editor_output, np.ndarray):
+                mask_array = editor_output
+            elif isinstance(editor_output, Image.Image):
+                mask_array = np.array(editor_output)
+            else:
+                logger.warning(f"Unexpected editor output type: {type(editor_output)}")
+                return None
+
+            # Convert to grayscale if needed
+            if len(mask_array.shape) == 3:
+                if mask_array.shape[2] == 4:
+                    # RGBA - use alpha channel
+                    mask_gray = mask_array[:, :, 3]
+                else:
+                    # RGB - convert to grayscale
+                    mask_gray = cv2.cvtColor(mask_array, cv2.COLOR_RGB2GRAY)
+            else:
+                mask_gray = mask_array
+
+            return Image.fromarray(mask_gray.astype(np.uint8), mode='L')
+
+        except Exception as e:
+            logger.error(f"Failed to extract mask from editor: {e}")
+            return None
+
+    def inpainting_handler(
+        self,
+        image: Optional[Image.Image],
+        mask_editor: Dict[str, Any],
+        prompt: str,
+        template_dropdown: str,
+        conditioning_type: str,
+        conditioning_scale: float,
+        feather_radius: int,
+        guidance_scale: float,
+        num_steps: int,
+        progress: gr.Progress = gr.Progress()
+    ) -> Tuple[Optional[Image.Image], Optional[Image.Image], Optional[Image.Image], str]:
+        """
+        Handle inpainting generation request.
+
+        Parameters
+        ----------
+        image : PIL.Image
+            Original image to inpaint
+        mask_editor : dict
+            Mask editor output
+        prompt : str
+            Text description of desired content
+        template_dropdown : str
+            Selected template (optional)
+        conditioning_type : str
+            ControlNet conditioning type
+        conditioning_scale : float
+            ControlNet influence strength
+        feather_radius : int
+            Mask feathering radius
+        guidance_scale : float
+            Guidance scale for generation
+        num_steps : int
+            Number of inference steps
+        progress : gr.Progress
+            Progress callback
+
+        Returns
+        -------
+        tuple
+            (result_image, preview_image, control_image, status_message)
+        """
+        if image is None:
+            return None, None, None, "Please upload an image first"
+
+        # Extract mask
+        mask = self.extract_mask_from_editor(mask_editor)
+        if mask is None:
+            return None, None, None, "Please draw a mask on the image"
+
+        # Validate mask
+        mask_array = np.array(mask)
+        coverage = np.count_nonzero(mask_array > 127) / mask_array.size
+        if coverage < 0.01:
+            return None, None, None, "Mask too small - please select a larger area"
+        if coverage > 0.95:
+            return None, None, None, "Mask too large - consider using background generation instead"
+
+        def progress_callback(msg: str, pct: int):
+            progress(pct / 100, desc=msg)
+
+        try:
+            start_time = time.time()
+
+            # Get template key if selected
+            template_key = None
+            if template_dropdown:
+                template_key = self.inpainting_template_manager.get_template_key_from_display(
+                    template_dropdown
+                )
+
+            # Execute inpainting through SceneWeaverCore facade
+            result = self.sceneweaver.execute_inpainting(
+                image=image,
+                mask=mask,
+                prompt=prompt,
+                preview_only=False,
+                template_key=template_key,
+                conditioning_type=conditioning_type,
+                controlnet_conditioning_scale=conditioning_scale,
+                feather_radius=feather_radius,
+                guidance_scale=guidance_scale,
+                num_inference_steps=num_steps,
+                progress_callback=progress_callback
+            )
+
+            elapsed = time.time() - start_time
+
+            if result.get('success'):
+                # Store in history
+                self.inpainting_history.append({
+                    'result': result.get('combined_image'),
+                    'prompt': prompt,
+                    'time': elapsed
+                })
+                if len(self.inpainting_history) > 3:
+                    self.inpainting_history.pop(0)
+
+                quality_score = result.get('quality_score', 0)
+                status = f"Inpainting complete in {elapsed:.1f}s"
+                if quality_score > 0:
+                    status += f" | Quality: {quality_score:.0f}/100"
+
+                return (
+                    result.get('combined_image'),
+                    result.get('preview_image'),
+                    result.get('control_image'),
+                    status
+                )
+            else:
+                error_msg = result.get('error', 'Unknown error')
+                return None, None, None, f"Inpainting failed: {error_msg}"
+
+        except Exception as e:
+            logger.error(f"Inpainting handler error: {e}")
+            logger.error(traceback.format_exc())
+            return None, None, None, f"Error: {str(e)}"
+
+    def create_inpainting_tab(self) -> gr.Tab:
+        """
+        Create the inpainting tab UI.
+
+        Returns
+        -------
+        gr.Tab
+            Configured inpainting tab component
+        """
+        with gr.Tab("Inpainting", elem_id="inpainting-tab") as tab:
+            gr.HTML("""
+            <div class="inpainting-header">
+                <h3 style="display: flex; align-items: center; gap: 10px; margin-bottom: 8px;">
+                    ControlNet Inpainting
+                    <span style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                                 color: white;
+                                 padding: 3px 10px;
+                                 border-radius: 12px;
+                                 font-size: 0.65em;
+                                 font-weight: 700;
+                                 letter-spacing: 0.5px;
+                                 box-shadow: 0 2px 4px rgba(102, 126, 234, 0.3);">
+                        BETA
+                    </span>
+                </h3>
+                <p style="color: #666; margin-bottom: 12px;">Draw a mask to select the area you want to regenerate</p>
+                <div style="background: linear-gradient(to right, #FFF4E6, #FFE8CC);
+                            border-left: 4px solid #FF9500;
+                            padding: 12px 15px;
+                            border-radius: 6px;
+                            margin-top: 10px;
+                            box-shadow: 0 2px 4px rgba(255, 149, 0, 0.1);">
+                    <p style="color: #8B4513; font-size: 0.9em; margin: 0; line-height: 1.5;">
+                        <strong>⚠️ Beta Feature - Continuously Optimizing</strong><br>
+                        Results may vary depending on complexity. Use templates and detailed prompts for best results.
+                        Advanced features (like Add Accessories) may require multiple attempts.
+                    </p>
+                </div>
+            </div>
+            """)
+
+            with gr.Row():
+                # Left column - Input
+                with gr.Column(scale=1):
+                    # Image upload
+                    inpaint_image = gr.Image(
+                        label="Upload Image",
+                        type="pil",
+                        height=300
+                    )
+
+                    # Mask editor
+                    mask_editor = gr.ImageEditor(
+                        label="Draw Mask (white = area to inpaint)",
+                        type="pil",
+                        height=300,
+                        brush=gr.Brush(colors=["#FFFFFF"], default_size=20),
+                        eraser=gr.Eraser(default_size=20),
+                        layers=False
+                    )
+
+                    # Template selection
+                    with gr.Accordion("Inpainting Templates", open=False):
+                        inpaint_template = gr.Dropdown(
+                            choices=[""] + self.inpainting_template_manager.get_template_choices_sorted(),
+                            value="",
+                            label="Select Template",
+                            elem_classes=["template-dropdown"]
+                        )
+                        template_tips = gr.Markdown("")
+
+                    # Prompt
+                    inpaint_prompt = gr.Textbox(
+                        label="Prompt",
+                        placeholder="Describe what you want to generate in the masked area...",
+                        lines=2
+                    )
+
+                # Right column - Settings and Output
+                with gr.Column(scale=1):
+                    # Settings
+                    with gr.Accordion("Generation Settings", open=True):
+                        conditioning_type = gr.Radio(
+                            choices=["canny", "depth"],
+                            value="canny",
+                            label="ControlNet Mode"
+                        )
+
+                        conditioning_scale = gr.Slider(
+                            minimum=0.5,
+                            maximum=1.0,
+                            value=0.7,
+                            step=0.05,
+                            label="ControlNet Strength"
+                        )
+
+                        feather_radius = gr.Slider(
+                            minimum=0,
+                            maximum=20,
+                            value=8,
+                            step=1,
+                            label="Feather Radius (px)"
+                        )
+
+                    with gr.Accordion("Advanced Settings", open=False):
+                        inpaint_guidance = gr.Slider(
+                            minimum=5.0,
+                            maximum=15.0,
+                            value=7.5,
+                            step=0.5,
+                            label="Guidance Scale"
+                        )
+
+                        inpaint_steps = gr.Slider(
+                            minimum=15,
+                            maximum=50,
+                            value=25,
+                            step=5,
+                            label="Inference Steps"
+                        )
+
+                    # Generate button
+                    inpaint_btn = gr.Button(
+                        "Generate Inpainting",
+                        variant="primary",
+                        elem_classes=["primary-button"]
+                    )
+
+                    # Status
+                    inpaint_status = gr.Textbox(
+                        label="Status",
+                        value="Ready for inpainting",
+                        interactive=False
+                    )
+
+            # Output row
+            with gr.Row():
+                with gr.Column(scale=1):
+                    inpaint_result = gr.Image(
+                        label="Result",
+                        type="pil",
+                        height=400
+                    )
+
+                with gr.Column(scale=1):
+                    with gr.Tabs():
+                        with gr.Tab("Preview"):
+                            inpaint_preview = gr.Image(
+                                label="Preview",
+                                type="pil",
+                                height=350
+                            )
+                        with gr.Tab("Control Image"):
+                            inpaint_control = gr.Image(
+                                label="Control Image",
+                                type="pil",
+                                height=350
+                            )
+
+            # Event handlers
+            inpaint_template.change(
+                fn=self.apply_inpainting_template,
+                inputs=[inpaint_template, inpaint_prompt],
+                outputs=[inpaint_prompt, conditioning_scale, feather_radius, conditioning_type]
+            )
+
+            inpaint_template.change(
+                fn=lambda x: self._get_template_tips(x),
+                inputs=[inpaint_template],
+                outputs=[template_tips]
+            )
+
+            # Copy uploaded image to mask editor
+            inpaint_image.change(
+                fn=lambda x: x,
+                inputs=[inpaint_image],
+                outputs=[mask_editor]
+            )
+
+            inpaint_btn.click(
+                fn=self.inpainting_handler,
+                inputs=[
+                    inpaint_image,
+                    mask_editor,
+                    inpaint_prompt,
+                    inpaint_template,
+                    conditioning_type,
+                    conditioning_scale,
+                    feather_radius,
+                    inpaint_guidance,
+                    inpaint_steps
+                ],
+                outputs=[
+                    inpaint_result,
+                    inpaint_preview,
+                    inpaint_control,
+                    inpaint_status
+                ]
+            )
+
+        return tab
+
+    def _get_template_tips(self, display_name: str) -> str:
+        """Get usage tips for selected template."""
+        if not display_name:
+            return ""
+
+        template_key = self.inpainting_template_manager.get_template_key_from_display(display_name)
+        if not template_key:
+            return ""
 
-        return interface.launch(**launch_kwargs)
+        tips = self.inpainting_template_manager.get_usage_tips(template_key)
+        if tips:
+            return "**Tips:**\n" + "\n".join(f"- {tip}" for tip in tips)
+        return ""