Update app.py

app.py

@@ -48,14 +48,18 @@ class JobStatus(str, Enum):
     COMPLETED = "completed"
     FAILED = "failed"
 
-# Story scene model
+# Enhanced Story scene model with character consistency
 class StoryScene(BaseModel):
     visual: str
     text: str
+    characters_present: List[str] = []  # Which characters are in this scene
+    scene_type: str = "general"  # "action", "dialogue", "establishing", etc.
 
 class CharacterDescription(BaseModel):
     name: str
     description: str
+    visual_prompt: str = ""  # Detailed visual description for AI
+    key_features: List[str] = []  # Critical features that must stay consistent
 
 class StorybookRequest(BaseModel):
     story_title: str
@@ -64,6 +68,7 @@ class StorybookRequest(BaseModel):
     model_choice: str = "dreamshaper-8"
     style: str = "childrens_book"
     callback_url: Optional[str] = None
+    consistency_seed: Optional[int] = None  # For consistent character generation
 
 class JobStatusResponse(BaseModel):
     job_id: str
@@ -83,6 +88,22 @@ MODEL_CHOICES = {
     "sd-2.1": "stabilityai/stable-diffusion-2-1",
 }
 
+# FALLBACK CHARACTER TEMPLATES (used only if n8n doesn't provide character details)
+FALLBACK_CHARACTER_TEMPLATES = {
+    "Sparkle the Star Cat": {
+        "visual_prompt": "small white kitten with distinctive silver star-shaped spots on fur, big golden eyes, shiny blue collar with star charm, playful expression",
+        "key_features": ["star-shaped spots", "blue collar", "golden eyes", "white fur"],
+    },
+    "Benny the Bunny": {
+        "visual_prompt": "fluffy brown rabbit with long ears, bright green eyes, red scarf around neck, cheerful expression",
+        "key_features": ["red scarf", "long ears", "green eyes", "brown fur"],
+    },
+    "Tilly the Turtle": {
+        "visual_prompt": "gentle green turtle with shiny turquoise shell decorated with swirl patterns, wise expression, slow-moving",
+        "key_features": ["turquoise shell", "swirl patterns", "green skin", "wise expression"],
+    }
+}
+
 # GLOBAL STORAGE
 job_storage = {}
 model_cache = {}
@@ -135,79 +156,259 @@ print("🚀 Initializing Storybook Generator API...")
 load_model("dreamshaper-8")
 print("✅ Model loaded and ready!")
 
-# PROFESSIONAL PROMPT ENGINEERING
-def enhance_prompt(prompt, style="childrens_book"):
-    """Transform basic prompts into professional-grade prompts"""
+# DYNAMIC CHARACTER PROCESSING FUNCTIONS
+def process_character_descriptions(characters_from_request):
+    """Process character descriptions from n8n and create consistency templates"""
+    character_templates = {}
+    
+    for character in characters_from_request:
+        char_name = character.name
+        
+        # Use provided visual_prompt or generate from description
+        if character.visual_prompt:
+            visual_prompt = character.visual_prompt
+        else:
+            # Generate visual prompt from description
+            visual_prompt = generate_visual_prompt_from_description(character.description, char_name)
+        
+        # Use provided key_features or extract from description
+        if character.key_features:
+            key_features = character.key_features
+        else:
+            key_features = extract_key_features_from_description(character.description)
+        
+        character_templates[char_name] = {
+            "visual_prompt": visual_prompt,
+            "key_features": key_features,
+            "consistency_keywords": f"consistent character, same {char_name.split()[-1].lower()}, maintaining appearance",
+            "source": "n8n_request"  # Track where this template came from
+        }
+    
+    print(f"✅ Processed {len(character_templates)} characters from n8n request")
+    return character_templates
+
+def generate_visual_prompt_from_description(description, character_name):
+    """Generate a visual prompt from character description"""
+    # Basic extraction of visual elements
+    description_lower = description.lower()
+    
+    # Extract species/type
+    species_keywords = ["kitten", "cat", "rabbit", "bunny", "turtle", "dog", "bird", "dragon", "bear", "fox"]
+    species = "character"
+    for keyword in species_keywords:
+        if keyword in description_lower:
+            species = keyword
+            break
+    
+    # Extract colors
+    color_keywords = ["white", "black", "brown", "red", "blue", "green", "yellow", "golden", "silver", "orange"]
+    colors = []
+    for color in color_keywords:
+        if color in description_lower:
+            colors.append(color)
+    
+    # Extract distinctive features
+    feature_keywords = ["spots", "stripes", "collar", "scarf", "shell", "wings", "horn", "tail", "ears", "eyes"]
+    features = []
+    for feature in feature_keywords:
+        if feature in description_lower:
+            features.append(feature)
+    
+    # Build visual prompt
+    visual_prompt_parts = []
+    if colors:
+        visual_prompt_parts.append(f"{' '.join(colors)} {species}")
+    else:
+        visual_prompt_parts.append(species)
+    
+    visual_prompt_parts.append(character_name)
     
+    if features:
+        visual_prompt_parts.append(f"with {', '.join(features)}")
+    
+    # Add emotional/character traits
+    trait_keywords = ["playful", "brave", "curious", "kind", "cheerful", "wise", "calm", "friendly"]
+    traits = [trait for trait in trait_keywords if trait in description_lower]
+    if traits:
+        visual_prompt_parts.append(f"{', '.join(traits)} expression")
+    
+    visual_prompt = " ".join(visual_prompt_parts)
+    print(f"🔧 Generated visual prompt for {character_name}: {visual_prompt}")
+    
+    return visual_prompt
+
+def extract_key_features_from_description(description):
+    """Extract key features from character description"""
+    description_lower = description.lower()
+    key_features = []
+    
+    # Look for distinctive physical features
+    feature_patterns = [
+        r"(\w+)\s+(?:spots|stripes|marks)",
+        r"(\w+)\s+(?:collar|scarf|ribbon)",
+        r"(\w+)\s+(?:eyes|fur|skin|shell)",
+        r"(\w+)\s+(?:ears|tail|wings|horn)"
+    ]
+    
+    for pattern in feature_patterns:
+        matches = re.findall(pattern, description_lower)
+        key_features.extend(matches)
+    
+    # Remove duplicates and limit to 3 most important features
+    key_features = list(set(key_features))[:3]
+    
+    # If no features found, use some defaults based on character type
+    if not key_features:
+        if any(word in description_lower for word in ["kitten", "cat"]):
+            key_features = ["whiskers", "tail", "paws"]
+        elif any(word in description_lower for word in ["rabbit", "bunny"]):
+            key_features = ["long ears", "fluffy tail", "paws"]
+        elif any(word in description_lower for word in ["turtle"]):
+            key_features = ["shell", "slow moving", "wise eyes"]
+        else:
+            key_features = ["distinctive appearance", "consistent features"]
+    
+    print(f"🔧 Extracted key features: {key_features}")
+    return key_features
+
+# ENHANCED PROMPT ENGINEERING WITH DYNAMIC CHARACTER CONSISTENCY
+def enhance_prompt_with_characters(scene_visual, characters_present, character_templates, style="childrens_book", scene_number=1):
+    """Create prompts that maintain character consistency using dynamic templates"""
+    
+    # Get character descriptions for this scene
+    character_descriptions = []
+    consistency_keywords = []
+    
+    for char_name in characters_present:
+        if char_name in character_templates:
+            char_data = character_templates[char_name]
+            character_descriptions.append(f"{char_name}: {char_data['visual_prompt']}")
+            consistency_keywords.append(char_data['consistency_keywords'])
+        else:
+            # Fallback if character not in templates
+            character_descriptions.append(f"{char_name}: distinctive character")
+            consistency_keywords.append(f"consistent {char_name}")
+    
+    # Style templates
     style_templates = {
-        "childrens_book": [
-            "masterpiece, best quality, 4K, ultra detailed, children's book illustration",
-            "watercolor painting, whimsical, cute, charming, storybook style",
-            "vibrant colors, soft lighting, magical, enchanting, dreamlike",
-            "Pixar style, Disney animation, high detail, professional artwork"
-        ],
-        "realistic": [
-            "photorealistic, 8K, ultra detailed, professional photography",
-            "sharp focus, studio lighting, high resolution, intricate details",
-            "realistic textures, natural lighting, cinematic quality"
-        ],
-        "fantasy": [
-            "epic fantasy art, digital painting, concept art, trending on artstation",
-            "magical, mystical, ethereal, otherworldly, fantasy illustration",
-            "dynamic composition, dramatic lighting, highly detailed"
-        ],
-        "anime": [
-            "anime style, Japanese animation, high quality, detailed artwork",
-            "beautiful anime illustration, vibrant colors, clean lines",
-            "studio ghibli style, makoto shinkai, professional anime art"
-        ]
+        "childrens_book": "children's book illustration, watercolor style, soft colors, whimsical, magical, storybook art, professional illustration",
+        "realistic": "photorealistic, detailed, natural lighting, professional photography",
+        "fantasy": "fantasy art, magical, ethereal, digital painting, concept art",
+        "anime": "anime style, Japanese animation, vibrant colors, detailed artwork"
     }
     
-    templates = style_templates.get(style, style_templates["childrens_book"])
-    style_prompt = templates[0]
+    style_prompt = style_templates.get(style, style_templates["childrens_book"])
+    
+    # Build the enhanced prompt
+    character_context = ". ".join(character_descriptions)
+    consistency_context = ", ".join(consistency_keywords)
     
-    enhanced = f"{style_prompt}, {prompt}"
+    enhanced_prompt = (
+        f"{style_prompt}, {scene_visual}. "
+        f"Featuring: {character_context}. "
+        f"Maintain character consistency: {consistency_context}. "
+        f"Scene {scene_number} of storybook series. "
+    )
     
+    # Quality boosters for consistency
     quality_boosters = [
-        "intricate details", "beautiful composition", "perfect lighting",
-        "professional artwork", "award winning", "trending on artstation"
+        "consistent character design", "maintain identical features", 
+        "same characters throughout", "continuous visual narrative",
+        "professional storybook illustration", "cohesive art style",
+        "character continuity", "consistent proportions"
     ]
     
-    boosters = random.sample(quality_boosters, 2)
-    enhanced += ", " + ", ".join(boosters)
+    enhanced_prompt += ", ".join(quality_boosters)
     
+    # Enhanced negative prompt to avoid inconsistencies
     negative_prompt = (
-        "blurry, low quality, low resolution, ugly, deformed, poorly drawn, "
-        "bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, "
-        "disconnected limbs, mutation, mutated, ugly, disgusting, bad art, "
-        "beginner, amateur, distorted, watermark, signature, text, username"
+        "inconsistent characters, different appearances, changing features, "
+        "multiple versions of same character, inconsistent art style, "
+        "blurry, low quality, bad anatomy, deformed characters, "
+        "wrong proportions, mismatched features, different art style"
     )
     
-    return enhanced, negative_prompt
+    return enhanced_prompt, negative_prompt
 
-def generate_high_quality_image(prompt, model_choice="dreamshaper-8", style="childrens_book", negative_prompt=""):
-    """Generate HIGH-QUALITY image with professional settings"""
+def extract_characters_from_visual(visual_description, available_characters):
+    """Extract character names from visual description using available characters"""
+    characters = []
+    visual_lower = visual_description.lower()
+    
+    # Check for each available character name in the visual description
+    for char_name in available_characters:
+        # Use the first word or main identifier from character name
+        char_identifier = char_name.split()[0].lower()
+        if char_identifier in visual_lower or char_name.lower() in visual_lower:
+            characters.append(char_name)
+    
+    return characters
+
+def generate_character_reference_sheet(characters):
+    """Generate reference descriptions for consistent character generation"""
+    reference_sheet = {}
+    
+    for character in characters:
+        char_name = character.name
+        reference_sheet[char_name] = {
+            "name": char_name,
+            "base_prompt": character.visual_prompt if character.visual_prompt else generate_visual_prompt_from_description(character.description, char_name),
+            "key_features": character.key_features if character.key_features else extract_key_features_from_description(character.description),
+            "must_include": character.key_features[:2] if character.key_features else []
+        }
+    
+    return reference_sheet
+
+def generate_consistent_image(prompt, model_choice, style, characters_present, character_templates, scene_number, consistency_seed=None):
+    """Generate image with character consistency measures using dynamic templates"""
+    
+    # Enhance prompt with character consistency
+    enhanced_prompt, negative_prompt = enhance_prompt_with_characters(
+        prompt, characters_present, character_templates, style, scene_number
+    )
+    
+    # Use a consistent seed for character generation
+    if consistency_seed:
+        base_seed = consistency_seed
+    else:
+        base_seed = hash("".join(characters_present)) % 1000000 if characters_present else random.randint(1000, 9999)
+    
+    # Adjust seed slightly per scene but maintain character consistency
+    scene_seed = base_seed + scene_number
+    
     try:
         pipe = load_model(model_choice)
         
         image = pipe(
-            prompt=prompt,
+            prompt=enhanced_prompt,
             negative_prompt=negative_prompt,
-            num_inference_steps=30,
-            guidance_scale=8.5,
+            num_inference_steps=35,  # Increased for better quality
+            guidance_scale=7.5,      # Slightly lower for more consistency
             width=768,
             height=768,
-            generator=torch.Generator(device="cpu").manual_seed(int(time.time()))
+            generator=torch.Generator(device="cpu").manual_seed(scene_seed)
         ).images[0]
         
-        print("✅ HIGH-QUALITY Image generated successfully!")
+        print(f"✅ Generated consistent image for scene {scene_number}")
+        print(f"👥 Characters: {characters_present}")
+        print(f"🌱 Seed used: {scene_seed}")
+        
         return image
         
     except Exception as e:
-        print(f"❌ HQ Generation failed: {str(e)}")
+        print(f"❌ Consistent generation failed: {str(e)}")
         raise
 
-# LOCAL FILE MANAGEMENT FUNCTIONS
+# Backward compatibility functions
+def enhance_prompt(prompt, style="childrens_book"):
+    """Legacy function for backward compatibility"""
+    return enhance_prompt_with_characters(prompt, [], {}, style, 1)
+
+def generate_high_quality_image(prompt, model_choice="dreamshaper-8", style="childrens_book", negative_prompt=""):
+    """Legacy function for backward compatibility"""
+    return generate_consistent_image(prompt, model_choice, style, [], {}, 1)
+
+# LOCAL FILE MANAGEMENT FUNCTIONS (unchanged)
 def save_image_to_local(image, prompt, style="test"):
     """Save image to local persistent storage"""
     try:
@@ -287,7 +488,7 @@ def refresh_local_images():
         print(f"Error refreshing local images: {e}")
         return []
 
-# OCI BUCKET FUNCTIONS (for n8n API)
+# OCI BUCKET FUNCTIONS (unchanged)
 def save_to_oci_bucket(image, text_content, story_title, page_number, file_type="image"):
     """Save both images and text to OCI bucket via your OCI API"""
     try:
@@ -328,10 +529,14 @@ def save_to_oci_bucket(image, text_content, story_title, page_number, file_type=
     except Exception as e:
         raise Exception(f"OCI upload failed: {str(e)}")
 
-# JOB MANAGEMENT FUNCTIONS (for n8n API)
+# JOB MANAGEMENT FUNCTIONS
 def create_job(story_request: StorybookRequest) -> str:
     job_id = str(uuid.uuid4())
     
+    # Process character descriptions from n8n
+    character_templates = process_character_descriptions(story_request.characters)
+    character_references = generate_character_reference_sheet(story_request.characters)
+    
     job_storage[job_id] = {
         "status": JobStatus.PENDING,
         "progress": 0,
@@ -340,10 +545,14 @@ def create_job(story_request: StorybookRequest) -> str:
         "result": None,
         "created_at": time.time(),
         "updated_at": time.time(),
-        "pages": []
+        "pages": [],
+        "character_templates": character_templates,
+        "character_references": character_references
     }
     
     print(f"📝 Created job {job_id} for story: {story_request.story_title}")
+    print(f"👥 Processed {len(character_templates)} characters from n8n request")
+    
     return job_id
 
 def update_job_status(job_id: str, status: JobStatus, progress: int, message: str, result=None):
@@ -368,7 +577,7 @@ def update_job_status(job_id: str, status: JobStatus, progress: int, message: st
         try:
             callback_url = request_data["callback_url"]
             
-            # Enhanced callback data for better Telegram notifications
+            # Enhanced callback data
             callback_data = {
                 "job_id": job_id,
                 "status": status.value,
@@ -376,6 +585,7 @@ def update_job_status(job_id: str, status: JobStatus, progress: int, message: st
                 "message": message,
                 "story_title": request_data["story_title"],
                 "total_scenes": len(request_data["scenes"]),
+                "total_characters": len(request_data["characters"]),
                 "timestamp": time.time(),
                 "source": "huggingface-storybook-generator",
                 "estimated_time_remaining": calculate_remaining_time(job_id, progress)
@@ -387,7 +597,8 @@ def update_job_status(job_id: str, status: JobStatus, progress: int, message: st
                     "total_pages": result.get("total_pages", 0),
                     "generation_time": result.get("generation_time", 0),
                     "oci_bucket_url": result.get("oci_bucket_url", ""),
-                    "pages_generated": result.get("generated_pages", 0)
+                    "pages_generated": result.get("generated_pages", 0),
+                    "characters_used": result.get("characters_used", 0)
                 }
             
             # Add current scene info for processing jobs
@@ -395,7 +606,13 @@ def update_job_status(job_id: str, status: JobStatus, progress: int, message: st
                 current_scene = progress // (100 // len(request_data["scenes"])) + 1
                 callback_data["current_scene"] = current_scene
                 callback_data["total_scenes"] = len(request_data["scenes"])
-                callback_data["scene_description"] = request_data["scenes"][current_scene-1]["visual"][:100] + "..."
+                if current_scene <= len(request_data["scenes"]):
+                    scene_visual = request_data["scenes"][current_scene-1]["visual"]
+                    callback_data["scene_description"] = scene_visual[:100] + "..."
+                    
+                    # Add characters in current scene
+                    if "characters_present" in request_data["scenes"][current_scene-1]:
+                        callback_data["characters_in_scene"] = request_data["scenes"][current_scene-1]["characters_present"]
             
             headers = {
                 'Content-Type': 'application/json',
@@ -433,19 +650,26 @@ def calculate_remaining_time(job_id, progress):
     
     return "Unknown"
 
-# BACKGROUND TASK FOR COMPLETE STORYBOOK GENERATION (n8n API)
+# ENHANCED BACKGROUND TASK WITH DYNAMIC CHARACTER CONSISTENCY
 def generate_storybook_background(job_id: str):
-    """Background task to generate complete storybook with images and text"""
+    """Background task to generate complete storybook with dynamic character consistency"""
     try:
         job_data = job_storage[job_id]
         story_request_data = job_data["request"]
         story_request = StorybookRequest(**story_request_data)
+        character_templates = job_data["character_templates"]
         
-        print(f"🎬 Starting COMPLETE storybook generation for job {job_id}")
+        print(f"🎬 Starting DYNAMIC storybook generation for job {job_id}")
         print(f"📖 Story: {story_request.story_title}")
-        print(f"📄 Pages: {len(story_request.scenes)} scenes")
+        print(f"👥 Characters: {len(story_request.characters)} (from n8n)")
+        print(f"📄 Scenes: {len(story_request.scenes)}")
+        print(f"🌱 Consistency seed: {story_request.consistency_seed}")
+        
+        # Log character details
+        for char in story_request.characters:
+            print(f"   - {char.name}: {char.description[:50]}...")
         
-        update_job_status(job_id, JobStatus.PROCESSING, 5, "Starting storybook generation...")
+        update_job_status(job_id, JobStatus.PROCESSING, 5, "Starting storybook generation with dynamic character consistency...")
         
         total_scenes = len(story_request.scenes)
         generated_pages = []
@@ -453,25 +677,35 @@ def generate_storybook_background(job_id: str):
         
         for i, scene in enumerate(story_request.scenes):
             progress = 5 + int((i / total_scenes) * 90)
+            
+            # Extract characters for this scene
+            characters_present = []
+            if hasattr(scene, 'characters_present') and scene.characters_present:
+                characters_present = scene.characters_present
+            else:
+                # Fallback: extract from visual description using available characters
+                available_chars = [char.name for char in story_request.characters]
+                characters_present = extract_characters_from_visual(scene.visual, available_chars)
+            
             update_job_status(
                 job_id, 
                 JobStatus.PROCESSING, 
                 progress, 
-                f"Generating page {i+1}/{total_scenes}: {scene.visual[:50]}..."
+                f"Generating page {i+1}/{total_scenes} with {len(characters_present)} characters: {scene.visual[:50]}..."
             )
             
             try:
-                print(f"🖼️ Generating page {i+1}: {scene.visual}")
+                print(f"🖼️ Generating page {i+1} with characters: {characters_present}")
                 
-                # Create enhanced prompt for high-quality image
-                enhanced_prompt, negative_prompt = enhance_prompt(scene.visual, story_request.style)
-                
-                # Generate high-quality image
-                image = generate_high_quality_image(
-                    enhanced_prompt, 
+                # Generate consistent image using dynamic character templates
+                image = generate_consistent_image(
+                    scene.visual, 
                     story_request.model_choice, 
                     story_request.style,
-                    negative_prompt
+                    characters_present,
+                    character_templates,
+                    i + 1,
+                    story_request.consistency_seed
                 )
                 
                 # Save IMAGE to OCI bucket
@@ -498,12 +732,13 @@ def generate_storybook_background(job_id: str):
                     "image_url": image_url,
                     "text_url": text_url,
                     "text_content": scene.text,
-                    "prompt_used": enhanced_prompt,
-                    "visual_description": scene.visual
+                    "visual_description": scene.visual,
+                    "characters_present": characters_present,
+                    "prompt_used": f"Dynamic consistent generation with {len(characters_present)} characters"
                 }
                 generated_pages.append(page_data)
                 
-                print(f"✅ Page {i+1} completed - Image: {image_url}, Text: {text_url}")
+                print(f"✅ Page {i+1} completed - Characters: {characters_present}")
                 
             except Exception as e:
                 error_msg = f"Failed to generate page {i+1}: {str(e)}"
@@ -522,6 +757,8 @@ def generate_storybook_background(job_id: str):
             "generation_time": round(generation_time, 2),
             "folder_path": f"stories/{story_request.story_title}",
             "oci_bucket_url": f"https://oci.com/stories/{story_request.story_title}",
+            "consistency_seed": story_request.consistency_seed,
+            "character_names": [char.name for char in story_request.characters],
             "pages": generated_pages,
             "file_structure": {
                 "images": [f"page_{i+1:03d}.png" for i in range(total_scenes)],
@@ -533,25 +770,40 @@ def generate_storybook_background(job_id: str):
             job_id, 
             JobStatus.COMPLETED, 
             100, 
-            f"🎉 Storybook completed! {len(generated_pages)} pages created in {generation_time:.2f}s. Saved to OCI bucket.",
+            f"🎉 Storybook completed! {len(generated_pages)} pages with {len(story_request.characters)} dynamic characters created in {generation_time:.2f}s.",
             result
         )
         
-        print(f"🎉 COMPLETE Storybook generation finished for job {job_id}")
+        print(f"🎉 DYNAMIC Storybook generation finished for job {job_id}")
         print(f"📁 Saved to: stories/{story_request.story_title} in OCI bucket")
+        print(f"👥 Dynamic character consistency maintained for {len(story_request.characters)} characters across {total_scenes} scenes")
         
     except Exception as e:
-        error_msg = f"Story generation failed: {str(e)}"
+        error_msg = f"Dynamic story generation failed: {str(e)}"
         print(f"❌ {error_msg}")
         update_job_status(job_id, JobStatus.FAILED, 0, error_msg)
 
 # FASTAPI ENDPOINTS (for n8n)
 @app.post("/api/generate-storybook")
 async def generate_storybook(request: dict, background_tasks: BackgroundTasks):
-    """Main endpoint for n8n integration - generates complete storybook"""
+    """Main endpoint for n8n integration - generates complete storybook with dynamic character consistency"""
     try:
         print(f"📥 Received n8n request for story: {request.get('story_title', 'Unknown')}")
         
+        # Add consistency seed if not provided
+        if 'consistency_seed' not in request or not request['consistency_seed']:
+            request['consistency_seed'] = random.randint(1000, 9999)
+            print(f"🌱 Generated consistency seed: {request['consistency_seed']}")
+        
+        # Ensure characters have required fields
+        if 'characters' in request:
+            for char in request['characters']:
+                if 'visual_prompt' not in char or not char['visual_prompt']:
+                    # Generate visual prompt from description if not provided
+                    char['visual_prompt'] = ""
+                if 'key_features' not in char:
+                    char['key_features'] = []
+        
         # Convert to Pydantic model
         story_request = StorybookRequest(**request)
         
@@ -568,16 +820,19 @@ async def generate_storybook(request: dict, background_tasks: BackgroundTasks):
         # Immediate response for n8n
         response_data = {
             "status": "success",
-            "message": "Storybook generation started successfully",
+            "message": "Storybook generation with dynamic character consistency started successfully",
             "job_id": job_id,
             "story_title": story_request.story_title,
             "total_scenes": len(story_request.scenes),
+            "total_characters": len(story_request.characters),
+            "character_names": [char.name for char in story_request.characters],
+            "consistency_seed": story_request.consistency_seed,
             "callback_url": story_request.callback_url,
-            "estimated_time_seconds": len(story_request.scenes) * 30,
+            "estimated_time_seconds": len(story_request.scenes) * 35,
             "timestamp": datetime.now().isoformat()
         }
         
-        print(f"✅ Job {job_id} started for: {story_request.story_title}")
+        print(f"✅ Job {job_id} started with dynamic character consistency for: {story_request.story_title}")
         
         return response_data
         
@@ -612,6 +867,7 @@ async def api_health():
         "timestamp": datetime.now().isoformat(),
         "active_jobs": len(job_storage),
         "models_loaded": list(model_cache.keys()),
+        "fallback_templates": list(FALLBACK_CHARACTER_TEMPLATES.keys()),
         "oci_api_connected": OCI_API_BASE_URL
     }
 
@@ -631,145 +887,56 @@ async def delete_local_image_api(filename: str):
     except Exception as e:
         return {"status": "error", "message": str(e)}
 
-# Create the Gradio interface with QUALITY OPTIONS and LOCAL FILE MANAGEMENT
-with gr.Blocks(title="Premium Children's Book Illustrator", theme="soft") as demo:
-    gr.Markdown("# 🎨 Premium Children's Book Illustrator")
-    gr.Markdown("Generate **studio-quality** storybook images with professional results")
-    
-    # Storage info display
-    storage_info = gr.Textbox(
-        label="📊 Local Storage Information",
-        interactive=False,
-        lines=2
-    )
-    
-    def update_storage_info():
-        info = get_local_storage_info()
-        if "error" not in info:
-            return f"📁 Local Storage: {info['total_files']} images, {info['total_size_mb']} MB used"
-        return "📁 Local Storage: Unable to calculate"
-    
-    with gr.Row():
-        with gr.Column(scale=1):
-            gr.Markdown("### 🎯 Quality Settings")
-            
-            model_choice = gr.Dropdown(
-                label="AI Model",
-                choices=list(MODEL_CHOICES.keys()),
-                value="dreamshaper-8",
-                info="Choose the best model for your style"
-            )
-            
-            style_choice = gr.Dropdown(
-                label="Art Style",
-                choices=["childrens_book", "realistic", "fantasy", "anime"],
-                value="childrens_book",
-                info="Select the artistic style"
-            )
-            
-            prompt_input = gr.Textbox(
-                label="Scene Description",
-                placeholder="Describe your scene in detail...\nExample: A friendly dragon reading a giant book under a magical tree with glowing fairies",
-                lines=3
-            )
-            
-            generate_btn = gr.Button("✨ Generate Premium Image", variant="primary")
-            
-            # Current image management
-            current_file_path = gr.State()
-            delete_btn = gr.Button("🗑️ Delete This Image", variant="stop")
-            delete_status = gr.Textbox(label="Delete Status", interactive=False, lines=2)
-            
-            gr.Markdown("### 📚 API Usage for n8n")
-            gr.Markdown("""
-            **For complete storybooks (OCI bucket):**
-            - Endpoint: `POST /api/generate-storybook`
-            - Input: `story_title`, `scenes[]`, `characters[]`
-            - Output: Saves to OCI bucket automatically
-            """)
-        
-        with gr.Column(scale=2):
-            image_output = gr.Image(label="Generated Image", height=500, show_download_button=True)
-            status_output = gr.Textbox(label="Status", interactive=False, lines=4)
-    
-    # Examples section
-    with gr.Accordion("💡 Prompt Examples & Tips", open=False):
-        gr.Markdown("""
-        ## 🎨 Professional Prompt Examples:
-        
-        **Best Results:**
-        - "A cute baby dragon learning to read with an old wise turtle in a magical forest"
-        - "Group of animal friends having a picnic under a giant glowing mushroom"
-        - "Little girl exploring a castle made of candy with talking animals"
-        - "Space adventure with friendly robots and colorful aliens"
-        
-        ## 🚫 Avoid:
-        - "dragon" → **"friendly cartoon dragon reading book"**
-        - "cat" → **"cute kitten playing with yarn ball"**
-        - "tree" → **"magical tree with glowing fairies"**
-        
-        ## ⚡ Pro Tips:
-        1. **Be descriptive** - Add colors, emotions, settings
-        2. **Specify style** - "watercolor", "cartoon", "realistic"
-        3. **Add details** - "with glowing effects", "in a magical forest"
-        4. **Use positive language** - "happy", "friendly", "colorful"
-        """)
-    
-    # Local file management section
-    with gr.Accordion("📁 Manage Local Test Images", open=True):
-        gr.Markdown("### Locally Saved Images")
-        
-        with gr.Row():
-            refresh_btn = gr.Button("🔄 Refresh List")
-            clear_all_btn = gr.Button("🗑️ Clear All Images", variant="stop")
-        
-        file_gallery = gr.Gallery(
-            label="Local Images",
-            show_label=True,
-            elem_id="gallery",
-            columns=4,
-            height="auto"
-        )
-        
-        clear_status = gr.Textbox(label="Clear Status", interactive=False)
+# Enhanced Gradio interface with dynamic character testing
+def create_gradio_interface():
+    """Create Gradio interface with dynamic character consistency features"""
     
-    # Debug section
-    with gr.Accordion("🔧 Advanced Settings", open=False):
-        debug_btn = gr.Button("🔄 Check System Status", variant="secondary")
-        debug_output = gr.Textbox(label="System Info", interactive=False, lines=4)
-    
-    def generate_test_image(prompt, model_choice, style_choice):
-        """Generate a single image for testing and save locally"""
+    def generate_test_image_with_characters(prompt, model_choice, style_choice, character_names_text):
+        """Generate a single image for testing character consistency"""
         try:
             if not prompt.strip():
                 return None, "❌ Please enter a prompt", None
             
+            # Parse character names from text input
+            character_names = [name.strip() for name in character_names_text.split(",") if name.strip()]
+            
             print(f"🎨 Generating test image with prompt: {prompt}")
+            print(f"👥 Character names: {character_names}")
             
-            # Enhance the prompt
-            enhanced_prompt, negative_prompt = enhance_prompt(prompt, style_choice)
+            # Create dynamic character templates for testing
+            character_templates = {}
+            for char_name in character_names:
+                character_templates[char_name] = {
+                    "visual_prompt": f"{char_name}, distinctive appearance, consistent features",
+                    "key_features": ["consistent appearance", "maintain features"],
+                    "consistency_keywords": f"consistent {char_name}"
+                }
+            
+            # Enhance the prompt with character consistency
+            enhanced_prompt, negative_prompt = enhance_prompt_with_characters(
+                prompt, character_names, character_templates, style_choice, 1
+            )
             
             # Generate the image
-            image = generate_high_quality_image(
-                enhanced_prompt, 
+            image = generate_consistent_image(
+                prompt, 
                 model_choice, 
                 style_choice,
-                negative_prompt
+                character_names,
+                character_templates,
+                1
             )
             
             # Save to local storage
             filepath, filename = save_image_to_local(image, prompt, style_choice)
             
-            if filepath:
-                save_info = f"💾 **Saved locally:** `{filepath}`"
-            else:
-                save_info = "⚠️ Could not save to local storage"
+            character_info = f"👥 Characters: {', '.join(character_names)}" if character_names else "👥 No specific characters"
             
             status_msg = f"""✅ Success! Generated: {prompt}
 
-{save_info}
+{character_info}
 
-🎨 Enhanced prompt: {enhanced_prompt}
+🎨 Enhanced prompt: {enhanced_prompt[:200]}...
 
 📁 **Local file:** {filename if filename else 'Not saved'}"""
             
@@ -780,107 +947,231 @@ with gr.Blocks(title="Premium Children's Book Illustrator", theme="soft") as dem
             print(error_msg)
             return None, error_msg, None
     
-    def delete_current_image(filepath):
-        """Delete the currently displayed image"""
-        if not filepath:
-            return "❌ No image to delete", None, None, refresh_local_images()
+    with gr.Blocks(title="Premium Children's Book Illustrator with Dynamic Character Consistency", theme="soft") as demo:
+        gr.Markdown("# 🎨 Premium Children's Book Illustrator")
+        gr.Markdown("Generate **studio-quality** storybook images with **dynamic character consistency**")
         
-        success, message = delete_local_image(filepath)
-        updated_files = refresh_local_images()
+        # Storage info display
+        storage_info = gr.Textbox(
+            label="📊 Local Storage Information",
+            interactive=False,
+            lines=2
+        )
         
-        if success:
-            status_msg = f"✅ {message}"
-            return status_msg, None, "Image deleted successfully!", updated_files
-        else:
-            return f"❌ {message}", None, "Delete failed", updated_files
-    
-    def clear_all_images():
-        """Delete all local images"""
-        try:
-            storage_info = get_local_storage_info()
-            deleted_count = 0
+        def update_storage_info():
+            info = get_local_storage_info()
+            if "error" not in info:
+                return f"📁 Local Storage: {info['total_files']} images, {info['total_size_mb']} MB used"
+            return "📁 Local Storage: Unable to calculate"
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("### 🎯 Quality Settings")
+                
+                model_dropdown = gr.Dropdown(
+                    label="AI Model",
+                    choices=list(MODEL_CHOICES.keys()),
+                    value="dreamshaper-8"
+                )
+                
+                style_dropdown = gr.Dropdown(
+                    label="Art Style",
+                    choices=["childrens_book", "realistic", "fantasy", "anime"],
+                    value="childrens_book"
+                )
+                
+                # Dynamic character input for testing
+                character_names_input = gr.Textbox(
+                    label="Character Names (comma-separated)",
+                    placeholder="Enter character names: Sparkle the Star Cat, Benny the Bunny, Tilly the Turtle",
+                    info="Enter character names to test consistency features",
+                    lines=2
+                )
+                
+                prompt_input = gr.Textbox(
+                    label="Scene Description",
+                    placeholder="Describe your scene with character interactions...\nExample: Sparkle the Star Cat chasing butterflies while Benny the Bunny watches",
+                    lines=3
+                )
+                
+                generate_btn = gr.Button("✨ Generate Premium Image", variant="primary")
+                
+                # Current image management
+                current_file_path = gr.State()
+                delete_btn = gr.Button("🗑️ Delete This Image", variant="stop")
+                delete_status = gr.Textbox(label="Delete Status", interactive=False, lines=2)
+                
+                gr.Markdown("### 📚 API Usage for n8n")
+                gr.Markdown("""
+                **For complete storybooks (OCI bucket):**
+                - Endpoint: `POST /api/generate-storybook`
+                - Input: `story_title`, `scenes[]`, `characters[]`
+                - Output: Saves to OCI bucket with dynamic character consistency
+                """)
             
-            if "images" in storage_info:
-                for image_info in storage_info["images"]:
-                    success, _ = delete_local_image(image_info["path"])
-                    if success:
-                        deleted_count += 1
+            with gr.Column(scale=2):
+                image_output = gr.Image(label="Generated Image", height=500, show_download_button=True)
+                status_output = gr.Textbox(label="Status", interactive=False, lines=4)
+        
+        # Dynamic character guidance section
+        with gr.Accordion("👥 Dynamic Character Guidance", open=False):
+            gr.Markdown("""
+            ### How to Use Dynamic Characters from n8n:
             
-            updated_files = refresh_local_images()
-            return f"✅ Deleted {deleted_count} images", updated_files
-        except Exception as e:
-            return f"❌ Error: {str(e)}", refresh_local_images()
-    
-    def check_system_status():
-        """Check system status"""
-        return f"""**System Status:**
+            **n8n Payload Structure:**
+            ```json
+            {
+              "story_title": "Your Story Title",
+              "characters": [
+                {
+                  "name": "Character Name",
+                  "description": "Character description...",
+                  "visual_prompt": "Detailed visual description",  // Optional
+                  "key_features": ["feature1", "feature2"]         // Optional
+                }
+              ],
+              "scenes": [
+                {
+                  "visual": "Scene description with characters...",
+                  "text": "Scene text...",
+                  "characters_present": ["Character Name"]         // Optional
+                }
+              ]
+            }
+            ```
+            
+            **Features:**
+            - ✅ Dynamic character processing from n8n
+            - ✅ Automatic visual prompt generation
+            - ✅ Key feature extraction
+            - ✅ Cross-scene consistency
+            - ✅ Flexible character numbers and types
+            """)
+        
+        # Examples section
+        with gr.Accordion("💡 Prompt Examples & Tips", open=False):
+            gr.Markdown("""
+            ## 🎨 Professional Prompt Examples with Dynamic Characters:
+            
+            **Best Results with Dynamic Characters:**
+            - "Sparkle the Star Cat chasing butterflies in a sunny meadow"
+            - "Benny the Bunny and Tilly the Turtle having a picnic"
+            - "Multiple characters discovering a magical portal together"
+            
+            ## ⚡ Dynamic Character Consistency Tips:
+            1. **Always mention character names** in your prompts
+            2. **n8n will send character details** automatically
+            3. **The system processes any number** of characters dynamically
+            4. **Consistency is maintained** across all scenes automatically
+            """)
+        
+        # Local file management section
+        with gr.Accordion("📁 Manage Local Test Images", open=True):
+            gr.Markdown("### Locally Saved Images")
+            
+            with gr.Row():
+                refresh_btn = gr.Button("🔄 Refresh List")
+                clear_all_btn = gr.Button("🗑️ Clear All Images", variant="stop")
+            
+            file_gallery = gr.Gallery(
+                label="Local Images",
+                show_label=True,
+                elem_id="gallery",
+                columns=4,
+                height="auto"
+            )
+            
+            clear_status = gr.Textbox(label="Clear Status", interactive=False)
+        
+        # Debug section
+        with gr.Accordion("🔧 Advanced Settings", open=False):
+            debug_btn = gr.Button("🔄 Check System Status", variant="secondary")
+            debug_output = gr.Textbox(label="System Info", interactive=False, lines=4)
+        
+        def check_system_status():
+            """Check system status"""
+            active_jobs = len(job_storage)
+            return f"""**System Status:**
 - Model: {current_model_name}
+- Dynamic Character Processing: ✅ Enabled
+- Fallback Templates: {len(FALLBACK_CHARACTER_TEMPLATES)} available
 - OCI API: {OCI_API_BASE_URL}
 - Local Storage: {get_local_storage_info().get('total_files', 0)} images
-- Active Jobs: {len(job_storage)}
-- Ready for premium image generation!"""
-
-    # Connect buttons to functions
-    generate_btn.click(
-        fn=generate_test_image,
-        inputs=[prompt_input, model_choice, style_choice],
-        outputs=[image_output, status_output, current_file_path]
-    ).then(
-        fn=refresh_local_images,
-        outputs=file_gallery
-    ).then(
-        fn=update_storage_info,
-        outputs=storage_info
-    )
-    
-    delete_btn.click(
-        fn=delete_current_image,
-        inputs=current_file_path,
-        outputs=[delete_status, image_output, status_output, file_gallery]
-    ).then(
-        fn=update_storage_info,
-        outputs=storage_info
-    )
-    
-    refresh_btn.click(
-        fn=refresh_local_images,
-        outputs=file_gallery
-    ).then(
-        fn=update_storage_info,
-        outputs=storage_info
-    )
-    
-    clear_all_btn.click(
-        fn=clear_all_images,
-        outputs=[clear_status, file_gallery]
-    ).then(
-        fn=update_storage_info,
-        outputs=storage_info
-    )
-    
-    debug_btn.click(
-        fn=check_system_status,
-        inputs=None,
-        outputs=debug_output
-    )
+- Active Jobs: {active_jobs}
+- Ready for dynamic character consistency generation!"""
+
+        # Connect buttons to functions
+        generate_btn.click(
+            fn=generate_test_image_with_characters,
+            inputs=[prompt_input, model_dropdown, style_dropdown, character_names_input],
+            outputs=[image_output, status_output, current_file_path]
+        ).then(
+            fn=refresh_local_images,
+            outputs=file_gallery
+        ).then(
+            fn=update_storage_info,
+            outputs=storage_info
+        )
+        
+        delete_btn.click(
+            fn=delete_current_image,
+            inputs=current_file_path,
+            outputs=[delete_status, image_output, status_output, file_gallery]
+        ).then(
+            fn=update_storage_info,
+            outputs=storage_info
+        )
+        
+        refresh_btn.click(
+            fn=refresh_local_images,
+            outputs=file_gallery
+        ).then(
+            fn=update_storage_info,
+            outputs=storage_info
+        )
+        
+        clear_all_btn.click(
+            fn=clear_all_images,
+            outputs=[clear_status, file_gallery]
+        ).then(
+            fn=update_storage_info,
+            outputs=storage_info
+        )
+        
+        debug_btn.click(
+            fn=check_system_status,
+            inputs=None,
+            outputs=debug_output
+        )
+        
+        # Initialize on load
+        demo.load(fn=refresh_local_images, outputs=file_gallery)
+        demo.load(fn=update_storage_info, outputs=storage_info)
     
-    # Initialize on load
-    demo.load(fn=refresh_local_images, outputs=file_gallery)
-    demo.load(fn=update_storage_info, outputs=storage_info)
+    return demo
+
+# Create enhanced Gradio app
+demo = create_gradio_interface()
 
 # Enhanced root endpoint that explains the API structure
 @app.get("/")
 async def root():
     return {
-        "message": "Storybook Generator API is running!",
+        "message": "Storybook Generator API with Dynamic Character Consistency is running!",
         "api_endpoints": {
             "health_check": "GET /api/health",
             "generate_storybook": "POST /api/generate-storybook",
             "check_job_status": "GET /api/job-status/{job_id}",
             "local_images": "GET /api/local-images"
         },
+        "features": {
+            "dynamic_characters": "✅ Enabled",
+            "character_consistency": "✅ Enabled", 
+            "flexible_storytelling": "✅ Enabled",
+            "n8n_integration": "✅ Enabled"
+        },
         "web_interface": "GET /ui",
-        "note": "Use API endpoints for programmatic access, /ui for testing interface"
+        "note": "Use API endpoints for programmatic access with dynamic characters from n8n"
     }
 
 # Add a simple test endpoint
@@ -888,11 +1179,13 @@ async def root():
 async def test_endpoint():
     return {
         "status": "success", 
-        "message": "API is working correctly",
+        "message": "API with dynamic character consistency is working correctly",
+        "dynamic_processing": "✅ Enabled",
+        "fallback_templates": len(FALLBACK_CHARACTER_TEMPLATES),
         "timestamp": datetime.now().isoformat()
     }
 
-# For Hugging Face Spaces deployment - FIXED APPROACH
+# For Hugging Face Spaces deployment
 def get_app():
     return app
 
@@ -907,9 +1200,10 @@ if __name__ == "__main__":
         print("🚀 Running on Hugging Face Spaces - Integrated Mode")
         print("📚 API endpoints available at: /api/*")
         print("🎨 Web interface available at: /ui")
+        print("👥 Dynamic character consistency features enabled")
         print("🔌 Both API and UI running on same port")
         
-        # FIX: Properly mount Gradio without reassigning app
+        # Mount Gradio without reassigning app
         gr.mount_gradio_app(app, demo, path="/ui")
         
         # Run the combined app
@@ -924,6 +1218,7 @@ if __name__ == "__main__":
         print("🚀 Running locally - Separate API and UI servers")
         print("📚 API endpoints: http://localhost:8000/api/*")
         print("🎨 Web interface: http://localhost:7860/ui")
+        print("👥 Dynamic character consistency features enabled")
         
         def run_fastapi():
             """Run FastAPI on port 8000 for API calls"""
@@ -960,5 +1255,4 @@ if __name__ == "__main__":
             while True:
                 time.sleep(1)
         except KeyboardInterrupt:
-            print("🛑 Shutting down servers...")
-            
+            print("🛑 Shutting down servers...")