Upload 17 files

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+backgrounds/beach.jpg filter=lfs diff=lfs merge=lfs -text
+backgrounds/cozy_home.jpg filter=lfs diff=lfs merge=lfs -text
+backgrounds/garden.jpg filter=lfs diff=lfs merge=lfs -text
+backgrounds/living_room.jpg filter=lfs diff=lfs merge=lfs -text
+backgrounds/park.jpg filter=lfs diff=lfs merge=lfs -text

app.py

@@ -0,0 +1,533 @@
+"""
+Shelter Flyer Generator - Main Application
+A Gradio-based web app for animal shelters to generate adoption flyers.
+
+Compatible with both local deployment and Hugging Face Spaces.
+"""
+
+import os
+import sys
+import gradio as gr
+from PIL import Image
+from pathlib import Path
+from datetime import datetime
+
+# Load environment variables (for local .env support)
+# Priority: Environment variables > .env file
+try:
+    from dotenv import load_dotenv
+    load_dotenv()  # This loads .env if present, but doesn't override existing env vars
+except ImportError:
+    print("[INFO] python-dotenv not installed. Using environment variables only.")
+
+# Import core modules
+try:
+    from core.background_removal import remove_background
+    from core.compositing import composite_animal_on_scene
+    from core.bio_generator import generate_bio
+    from core.flyer_builder import build_flyer
+    print("[OK] All core modules loaded successfully.")
+except ImportError as e:
+    print(f"[ERROR] Failed to import core modules: {e}")
+    print("Please ensure all core modules are present in the 'core/' directory.")
+    sys.exit(1)
+
+# ============================================================================
+# ROBUST TOKEN MANAGEMENT
+# ============================================================================
+def check_hf_token():
+    """
+    Check for HF_TOKEN with proper priority:
+    1. Environment variable (for HF Spaces)
+    2. .env file (for local development)
+    
+    Returns:
+        str or None: The token if found, None otherwise
+    """
+    token = os.getenv("HF_TOKEN")
+    
+    if token and token != "hf_xxxxxxxxxxxxxxxxxxxxx":
+        print("✅ Token detected")
+        return token
+    else:
+        print("❌ Token not found")
+        print("[WARN] Bio generation will use fallback template mode.")
+        print("[INFO] To use AI bio generation, set HF_TOKEN environment variable.")
+        print("[INFO] Get your token at: https://huggingface.co/settings/tokens")
+        return None
+
+# Check token at startup
+HF_TOKEN = check_hf_token()
+
+# ============================================================================
+# PATH CONSISTENCY (pathlib for cross-platform compatibility)
+# ============================================================================
+BASE_DIR = Path(__file__).parent.resolve()
+BACKGROUNDS_DIR = BASE_DIR / "backgrounds"
+OUTPUTS_DIR = BASE_DIR / "outputs"
+
+# Ensure outputs directory exists
+OUTPUTS_DIR.mkdir(parents=True, exist_ok=True)
+
+# Pre-defined personality traits
+PERSONALITY_TRAITS = [
+    "Good with kids",
+    "Good with other dogs",
+    "Good with cats",
+    "High energy",
+    "Calm / Relaxed",
+    "Playful",
+    "Loyal",
+    "Trained / Knows commands",
+    "Loves cuddles",
+    "Independent",
+    "Gentle",
+    "Protective",
+    "Loves walks",
+    "House-trained",
+    "Special needs"
+]
+
+# Available background scenes
+BACKGROUND_SCENES = {
+    "Living Room": "living_room.jpg",
+    "Cozy Home": "cozy_home.jpg",
+    "Garden/Yard": "garden.jpg",
+    "Forest Park": "park.jpg",
+    "Beach Sunset": "beach.jpg"
+}
+
+
+# ============================================================================
+# MAIN PIPELINE WITH FILE DOWNLOAD SUPPORT
+# ============================================================================
+def generate_flyer_pipeline(
+    animal_photo,
+    scene_choice,
+    custom_scene,
+    animal_name,
+    animal_type,
+    breed,
+    age,
+    traits,
+    additional_notes,
+    shelter_name,
+    shelter_contact
+):
+    """
+    Main pipeline that orchestrates the flyer generation process.
+    
+    Returns:
+        enhanced_photo: PIL.Image - The composited animal on scene
+        generated_bio: str - The AI-generated bio
+        flyer_file_path: str - Path to downloadable flyer file
+        status: str - Status message
+    """
+    
+    try:
+        # Validate inputs
+        if animal_photo is None:
+            return None, None, None, "❌ Please upload an animal photo."
+        
+        if not animal_name or not animal_type or not breed or not age:
+            return None, None, None, "❌ Please fill in all animal information fields."
+        
+        status_msg = "🚀 Starting flyer generation...\n\n"
+        
+        # Step 1: Select scene
+        if custom_scene is not None:
+            scene_image = custom_scene
+            status_msg += "✅ Using custom background scene\n"
+        elif scene_choice and scene_choice in BACKGROUND_SCENES:
+            scene_path = BACKGROUNDS_DIR / BACKGROUND_SCENES[scene_choice]
+            if not scene_path.exists():
+                return None, None, None, f"❌ Background file not found: {scene_path}"
+            scene_image = Image.open(scene_path)
+            status_msg += f"✅ Using {scene_choice} background\n"
+        else:
+            return None, None, None, "❌ Please select a background scene or upload a custom one."
+        
+        # Step 2: Remove background from animal photo
+        status_msg += "🔄 Removing background from animal photo...\n"
+        try:
+            animal_cutout = remove_background(animal_photo)
+            status_msg += "✅ Background removed successfully\n"
+        except Exception as e:
+            status_msg += f"❌ Background removal failed: {str(e)}\n"
+            return None, None, None, status_msg
+        
+        # Step 3: Composite animal onto scene
+        status_msg += "🔄 Compositing animal onto scene...\n"
+        try:
+            enhanced_photo = composite_animal_on_scene(
+                animal_rgba=animal_cutout,
+                scene=scene_image,
+                position="center",
+                scale_factor=0.6
+            )
+            status_msg += "✅ Enhanced photo created\n"
+        except Exception as e:
+            status_msg += f"❌ Compositing failed: {str(e)}\n"
+            return None, None, None, status_msg
+        
+        # Step 4: Generate bio with AI error handling & fallback
+        status_msg += "🔄 Generating bio...\n"
+        try:
+            bio_text = generate_bio(
+                name=animal_name,
+                animal_type=animal_type,
+                breed=breed,
+                age=age,
+                traits=traits if traits else [],
+                additional_notes=additional_notes
+            )
+            
+            # Check if fallback was used
+            if "Meet" in bio_text and "looking for a forever home" in bio_text:
+                status_msg += "✅ Bio generated (using template fallback)\n"
+            else:
+                status_msg += "✅ Bio generated with AI\n"
+                
+        except Exception as e:
+            status_msg += f"⚠️ Bio generation encountered an issue: {str(e)}\n"
+            status_msg += "📝 Using template-based bio as fallback...\n"
+            
+            # Manual fallback if bio_generator fails completely
+            bio_text = f"Meet {animal_name}! This {age} {breed} {animal_type.lower()} is looking for a forever home. "
+            if traits:
+                bio_text += f"{animal_name} is {', '.join(traits[:3]).lower()}. "
+            bio_text += f"Come meet {animal_name} at our shelter today!"
+            status_msg += "✅ Template bio created\n"
+        
+        # Step 5: Build final flyer
+        status_msg += "🔄 Building final flyer...\n"
+        try:
+            flyer_image = build_flyer(
+                photo=enhanced_photo,
+                name=animal_name,
+                animal_type=animal_type,
+                breed=breed,
+                age=age,
+                bio=bio_text,
+                shelter_name=shelter_name if shelter_name else "Your Local Animal Shelter",
+                shelter_contact=shelter_contact if shelter_contact else "",
+                template="template_1"
+            )
+            status_msg += "✅ Flyer created successfully\n"
+        except Exception as e:
+            status_msg += f"❌ Flyer building failed: {str(e)}\n"
+            return None, None, None, status_msg
+        
+        # Step 6: Save flyer to file for download
+        status_msg += "💾 Saving flyer...\n"
+        try:
+            # Create unique filename with timestamp
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            safe_name = "".join(c for c in animal_name if c.isalnum() or c in (' ', '-', '_'))
+            safe_name = safe_name.replace(' ', '_')
+            flyer_filename = f"flyer_{safe_name}_{timestamp}.jpg"
+            flyer_path = OUTPUTS_DIR / flyer_filename
+            
+            # Save with high quality
+            flyer_image.save(flyer_path, "JPEG", quality=95, optimize=True)
+            
+            status_msg += f"✅ Flyer saved: {flyer_filename}\n"
+            status_msg += "\n🎉 Generation complete! You can now download your flyer.\n"
+            
+            # Return the path as a string (Gradio will handle the file download)
+            return enhanced_photo, bio_text, str(flyer_path), status_msg
+            
+        except Exception as e:
+            status_msg += f"❌ Failed to save flyer: {str(e)}\n"
+            return enhanced_photo, bio_text, None, status_msg
+        
+    except Exception as e:
+        import traceback
+        error_msg = "❌ Unexpected error occurred:\n\n"
+        error_msg += f"Error: {str(e)}\n\n"
+        error_msg += "Stack trace:\n"
+        error_msg += traceback.format_exc()
+        return None, None, None, error_msg
+
+
+def regenerate_bio_only(
+    animal_name,
+    animal_type,
+    breed,
+    age,
+    traits,
+    additional_notes
+):
+    """
+    Regenerates just the bio without reprocessing images.
+    Includes proper error handling and fallback.
+    """
+    
+    try:
+        if not animal_name or not animal_type:
+            return "❌ Please provide at least name and animal type.", "Error"
+        
+        bio_text = generate_bio(
+            name=animal_name,
+            animal_type=animal_type,
+            breed=breed,
+            age=age,
+            traits=traits if traits else [],
+            additional_notes=additional_notes
+        )
+        
+        # Check if AI or fallback was used
+        if "Meet" in bio_text and "looking for a forever home" in bio_text:
+            status = "✅ Bio regenerated (template mode)"
+        else:
+            status = "✅ Bio regenerated with AI"
+        
+        return bio_text, status
+        
+    except Exception as e:
+        error_msg = f"❌ Error generating bio: {str(e)}\n"
+        error_msg += "Using fallback template..."
+        
+        # Fallback bio
+        bio_text = f"Meet {animal_name}! This {breed} {animal_type.lower()} is looking for a loving home. "
+        if traits:
+            bio_text += f"{animal_name} is {', '.join(traits[:2]).lower()}. "
+        bio_text += f"Visit our shelter to meet {animal_name}!"
+        
+        return bio_text, "⚠️ Used fallback template (API unavailable)"
+
+
+# ============================================================================
+# GRADIO 5.0+ COMPATIBLE UI
+# ============================================================================
+with gr.Blocks(
+    title="🐾 Shelter Flyer Generator",
+    theme=gr.themes.Soft()
+) as app:
+    
+    gr.Markdown("""
+    # 🐾 Shelter Flyer Generator
+    
+    Create beautiful adoption flyers for shelter animals with AI-enhanced photos and compelling bios.
+    
+    **How it works:**
+    1. Upload a photo of the animal
+    2. Choose a background scene
+    3. Fill in the animal's information
+    4. Generate a professional flyer!
+    """)
+    
+    with gr.Tabs():
+        # ====================================================================
+        # TAB 1: Upload & Describe
+        # ====================================================================
+        with gr.Tab("📸 Upload & Describe"):
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("### Animal Photo")
+                    animal_photo = gr.Image(
+                        type="pil",
+                        label="Upload Animal Photo",
+                        height=400
+                    )
+                    
+                    gr.Markdown("### Background Scene")
+                    scene_choice = gr.Radio(
+                        choices=list(BACKGROUND_SCENES.keys()),
+                        label="Choose a Background Scene",
+                        value="Living Room"
+                    )
+                    
+                    custom_scene = gr.Image(
+                        type="pil",
+                        label="Or Upload Your Own Scene (optional)",
+                        height=200
+                    )
+                
+                with gr.Column():
+                    gr.Markdown("### Animal Information")
+                    animal_name = gr.Textbox(
+                        label="Animal Name",
+                        placeholder="e.g., Bella"
+                    )
+                    
+                    animal_type = gr.Radio(
+                        choices=["Dog", "Cat", "Other"],
+                        label="Animal Type",
+                        value="Dog"
+                    )
+                    
+                    with gr.Row():
+                        breed = gr.Textbox(
+                            label="Breed",
+                            placeholder="e.g., Golden Retriever"
+                        )
+                        age = gr.Textbox(
+                            label="Age",
+                            placeholder="e.g., 2 years"
+                        )
+                    
+                    gr.Markdown("### Personality Traits")
+                    traits = gr.CheckboxGroup(
+                        choices=PERSONALITY_TRAITS,
+                        label="Select all that apply"
+                    )
+                    
+                    additional_notes = gr.Textbox(
+                        lines=3,
+                        label="Additional Notes",
+                        placeholder="Any special information about this animal..."
+                    )
+                    
+                    gr.Markdown("### Shelter Information")
+                    shelter_name = gr.Textbox(
+                        label="Shelter Name",
+                        placeholder="e.g., Happy Paws Animal Shelter",
+                        value="Your Local Animal Shelter"
+                    )
+                    
+                    shelter_contact = gr.Textbox(
+                        label="Contact Info",
+                        placeholder="e.g., (555) 123-4567 | www.shelter.org"
+                    )
+            
+            with gr.Row():
+                generate_btn = gr.Button(
+                    "🐾 Generate Flyer",
+                    variant="primary",
+                    size="lg"
+                )
+            
+            status_output = gr.Textbox(
+                label="Status",
+                lines=10,
+                interactive=False
+            )
+        
+        # ====================================================================
+        # TAB 2: Preview & Edit
+        # ====================================================================
+        with gr.Tab("👁️ Preview & Edit"):
+            gr.Markdown("### Enhanced Photo")
+            enhanced_photo_output = gr.Image(
+                label="Enhanced Photo Preview",
+                type="pil"
+            )
+            
+            gr.Markdown("### Generated Bio")
+            with gr.Row():
+                bio_output = gr.Textbox(
+                    lines=8,
+                    label="Generated Bio (Editable)",
+                    interactive=True
+                )
+            
+            with gr.Row():
+                regenerate_bio_btn = gr.Button("🔄 Regenerate Bio")
+                bio_status = gr.Textbox(
+                    label="Bio Status",
+                    lines=1,
+                    interactive=False
+                )
+        
+        # ====================================================================
+        # TAB 3: Download (UPDATED FOR FILE DOWNLOADS)
+        # ====================================================================
+        with gr.Tab("⬇️ Download"):
+            gr.Markdown("""
+            ### Download Your Flyer
+            
+            Once your flyer is generated, you can download it here.
+            """)
+            
+            # Main flyer download with file output
+            download_flyer = gr.File(
+                label="📥 Download Final Flyer (JPG)",
+                interactive=False
+            )
+            
+            gr.Markdown("""
+            ---
+            **Tip:** The downloaded JPG is high-quality and ready for:
+            - Social media posts
+            - Email campaigns  
+            - Printing on flyers
+            - Posting on your shelter website
+            """)
+    
+    # ========================================================================
+    # EVENT HANDLERS
+    # ========================================================================
+    generate_btn.click(
+        fn=generate_flyer_pipeline,
+        inputs=[
+            animal_photo,
+            scene_choice,
+            custom_scene,
+            animal_name,
+            animal_type,
+            breed,
+            age,
+            traits,
+            additional_notes,
+            shelter_name,
+            shelter_contact
+        ],
+        outputs=[
+            enhanced_photo_output,
+            bio_output,
+            download_flyer,  # Now outputs file path for download
+            status_output
+        ]
+    )
+    
+    regenerate_bio_btn.click(
+        fn=regenerate_bio_only,
+        inputs=[
+            animal_name,
+            animal_type,
+            breed,
+            age,
+            traits,
+            additional_notes
+        ],
+        outputs=[
+            bio_output,
+            bio_status
+        ]
+    )
+    
+    gr.Markdown("""
+    ---
+    ### About
+    
+    This app uses:
+    - **Background Removal**: RMBG-2.0 (Hugging Face)
+    - **Bio Generation**: Zephyr-7B (Hugging Face Inference API)
+    - **Image Processing**: Pillow
+    
+    Built for animal shelters to create compelling adoption flyers. 🐾
+    
+    **Note:** If HF_TOKEN is not configured, bio generation will use template mode.
+    """)
+
+
+# ============================================================================
+# LAUNCH CONFIGURATION
+# ============================================================================
+if __name__ == "__main__":
+    print("\n" + "="*60)
+    print("🐾 Shelter Flyer Generator")
+    print("="*60)
+    print(f"📁 Base directory: {BASE_DIR}")
+    print(f"📁 Backgrounds: {BACKGROUNDS_DIR}")
+    print(f"📁 Outputs: {OUTPUTS_DIR}")
+    print(f"🔑 HF Token: {'✅ Configured' if HF_TOKEN else '❌ Not found (using fallback mode)'}")
+    print("="*60 + "\n")
+    
+    # Launch with proper settings for both local and HF Spaces
+    app.launch(
+        server_name="0.0.0.0",  # Allows external access (needed for HF Spaces)
+        server_port=7860,        # Standard port
+        share=False              # Set to True for temporary public link
+    )

core/__init__.py

@@ -0,0 +1,15 @@
+"""
+Core modules for Shelter Flyer Generator
+"""
+
+from .background_removal import remove_background
+from .compositing import composite_animal_on_scene
+from .bio_generator import generate_bio
+from .flyer_builder import build_flyer
+
+__all__ = [
+    'remove_background',
+    'composite_animal_on_scene',
+    'generate_bio',
+    'build_flyer'
+]

core/background_removal.py

@@ -0,0 +1,232 @@
+"""
+Background Removal Module
+Uses briaai/RMBG-2.0 model from Hugging Face for high-quality background removal.
+Falls back to rembg if the primary model fails.
+"""
+
+from PIL import Image
+import numpy as np
+from typing import Optional
+import warnings
+
+# Module-level model cache
+_bg_removal_model = None
+_model_type = None
+
+
+def remove_background(image: Image.Image) -> Image.Image:
+    """
+    Takes an RGB image of an animal, returns an RGBA image
+    with the background removed (transparent).
+
+    Uses: briaai/RMBG-2.0 via transformers pipeline
+    Fallback: rembg library (U2-Net based)
+
+    Args:
+        image: PIL Image in RGB or RGBA format
+
+    Returns:
+        PIL Image in RGBA format with transparent background
+
+    Raises:
+        RuntimeError: If both methods fail
+    """
+    
+    # Convert to RGB if needed
+    if image.mode == 'RGBA':
+        # If already has alpha, just keep RGB channels
+        image = image.convert('RGB')
+    elif image.mode != 'RGB':
+        image = image.convert('RGB')
+    
+    # Try primary method: RMBG-2.0
+    try:
+        result = _remove_background_rmbg(image)
+        if result is not None:
+            return result
+    except Exception as e:
+        print(f"⚠️ RMBG-2.0 failed: {e}")
+        print("Falling back to rembg...")
+    
+    # Fallback: rembg
+    try:
+        result = _remove_background_rembg(image)
+        if result is not None:
+            return result
+    except Exception as e:
+        print(f"❌ rembg failed: {e}")
+        raise RuntimeError("Both background removal methods failed") from e
+    
+    raise RuntimeError("Background removal returned None")
+
+
+def _remove_background_rmbg(image: Image.Image) -> Optional[Image.Image]:
+    """
+    Remove background using briaai/RMBG-2.0 model.
+    
+    This is a state-of-the-art background removal model from Hugging Face.
+    The model is loaded once and cached for subsequent calls.
+    """
+    global _bg_removal_model, _model_type
+    
+    # Load model on first call
+    if _bg_removal_model is None or _model_type != 'rmbg':
+        print("Loading RMBG-2.0 model (first run may take a few minutes)...")
+        try:
+            from transformers import pipeline
+            import torch
+            
+            # Check if CUDA is available
+            device = 0 if torch.cuda.is_available() else -1
+            device_name = "GPU" if device == 0 else "CPU"
+            print(f"Using device: {device_name}")
+            
+            # Load the image segmentation pipeline
+            _bg_removal_model = pipeline(
+                "image-segmentation",
+                model="briaai/RMBG-2.0",
+                device=device,
+                trust_remote_code=True
+            )
+            _model_type = 'rmbg'
+            print("✅ RMBG-2.0 model loaded successfully.")
+            
+        except Exception as e:
+            print(f"Failed to load RMBG-2.0: {e}")
+            return None
+    
+    try:
+        # Run inference
+        # RMBG-2.0 returns a mask that we can use to create transparency
+        result = _bg_removal_model(image)
+        
+        # The result is a list of dicts with 'mask' and 'label'
+        # We want the mask for the main subject
+        if isinstance(result, list) and len(result) > 0:
+            mask = result[0]['mask']
+            
+            # Convert mask to numpy array
+            mask_array = np.array(mask)
+            
+            # Convert image to numpy array
+            image_array = np.array(image)
+            
+            # Create RGBA image
+            rgba_image = np.zeros((image_array.shape[0], image_array.shape[1], 4), dtype=np.uint8)
+            rgba_image[:, :, :3] = image_array
+            rgba_image[:, :, 3] = mask_array
+            
+            # Convert back to PIL
+            result_image = Image.fromarray(rgba_image, mode='RGBA')
+            
+            return result_image
+        else:
+            print("Unexpected result format from RMBG-2.0")
+            return None
+            
+    except Exception as e:
+        print(f"Error during RMBG-2.0 inference: {e}")
+        return None
+
+
+def _remove_background_rembg(image: Image.Image) -> Optional[Image.Image]:
+    """
+    Remove background using rembg library (U2-Net based).
+    This is a reliable fallback method.
+    """
+    global _bg_removal_model, _model_type
+    
+    # Load rembg on first call
+    if _bg_removal_model is None or _model_type != 'rembg':
+        print("Loading rembg (U2-Net) model...")
+        try:
+            from rembg import remove
+            _bg_removal_model = remove
+            _model_type = 'rembg'
+            print("✅ rembg model loaded successfully.")
+        except Exception as e:
+            print(f"Failed to load rembg: {e}")
+            return None
+    
+    try:
+        # rembg.remove returns a PIL Image with alpha channel
+        result_image = _bg_removal_model(image)
+        
+        # Ensure it's RGBA
+        if result_image.mode != 'RGBA':
+            result_image = result_image.convert('RGBA')
+        
+        return result_image
+        
+    except Exception as e:
+        print(f"Error during rembg inference: {e}")
+        return None
+
+
+def test_background_removal():
+    """Test function to verify background removal works."""
+    import os
+    from pathlib import Path
+    
+    # Try to load a test image
+    test_images = [
+        Path("cat.png"),
+        Path("turtle.png"),
+        Path("examples/cat.png"),
+        Path("examples/turtle.png")
+    ]
+    
+    test_image_path = None
+    for img_path in test_images:
+        if img_path.exists():
+            test_image_path = img_path
+            break
+    
+    if test_image_path is None:
+        print("No test images found. Please provide a test image.")
+        return False
+    
+    print(f"Testing background removal on: {test_image_path}")
+    
+    try:
+        # Load test image
+        test_image = Image.open(test_image_path)
+        print(f"Loaded image: {test_image.size}, mode: {test_image.mode}")
+        
+        # Remove background
+        result = remove_background(test_image)
+        print(f"Result: {result.size}, mode: {result.mode}")
+        
+        # Check that result has alpha channel
+        if result.mode != 'RGBA':
+            print("❌ Result is not RGBA!")
+            return False
+        
+        # Check that some pixels are transparent
+        alpha_channel = np.array(result)[:, :, 3]
+        min_alpha = alpha_channel.min()
+        max_alpha = alpha_channel.max()
+        
+        print(f"Alpha channel range: {min_alpha} to {max_alpha}")
+        
+        if min_alpha == 255 and max_alpha == 255:
+            print("⚠️ Warning: No transparency detected (all pixels opaque)")
+        
+        # Save result
+        output_path = Path("outputs") / f"test_bg_removed_{test_image_path.stem}.png"
+        output_path.parent.mkdir(exist_ok=True)
+        result.save(output_path)
+        print(f"✅ Test passed! Result saved to: {output_path}")
+        
+        return True
+        
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    print("Running background removal test...")
+    test_background_removal()

core/bio_generator.py

@@ -0,0 +1,280 @@
+"""
+Bio Generation Module
+Generates adoption bios using Hugging Face Inference API.
+"""
+
+import os
+from typing import List
+import time
+
+
+def generate_bio(
+    name: str,
+    animal_type: str,
+    breed: str,
+    age: str,
+    traits: List[str],
+    additional_notes: str = ""
+) -> str:
+    """
+    Generates a 1–2 paragraph adoption bio using a Hugging Face LLM.
+
+    Uses: HuggingFaceH4/zephyr-7b-beta via Inference API
+    Returns: A warm, engaging adoption bio string.
+    
+    Args:
+        name: Animal's name
+        animal_type: "Dog", "Cat", or "Other"
+        breed: Breed description
+        age: Age description
+        traits: List of personality traits
+        additional_notes: Any additional information
+    
+    Returns:
+        Generated bio text (1-2 paragraphs)
+    
+    Raises:
+        RuntimeError: If API call fails
+    """
+    
+    # Check for HF_TOKEN
+    hf_token = os.getenv("HF_TOKEN")
+    if not hf_token:
+        raise RuntimeError(
+            "HF_TOKEN environment variable not set. "
+            "Get your token at: https://huggingface.co/settings/tokens"
+        )
+    
+    # Build the prompt
+    prompt = _build_bio_prompt(name, animal_type, breed, age, traits, additional_notes)
+    
+    # Try Inference API
+    try:
+        return _generate_via_inference_api(prompt, hf_token)
+    except Exception as e:
+        print(f"⚠️ Inference API failed: {e}")
+        print("Trying fallback method...")
+        
+        # Fallback: Try a different model or use a template
+        return _generate_fallback_bio(name, animal_type, breed, age, traits, additional_notes)
+
+
+def _build_bio_prompt(
+    name: str,
+    animal_type: str,
+    breed: str,
+    age: str,
+    traits: List[str],
+    additional_notes: str
+) -> str:
+    """
+    Build the prompt for the LLM.
+    """
+    
+    traits_str = ", ".join(traits) if traits else "friendly"
+    
+    prompt = f"""You are a creative writer for an animal shelter. Write a warm, engaging adoption bio (1-2 paragraphs) for a pet based on the following details. The bio should make potential adopters fall in love with this animal.
+
+Name: {name}
+Type: {animal_type}
+Breed: {breed}
+Age: {age}
+Personality traits: {traits_str}
+Additional notes: {additional_notes if additional_notes else "None"}
+
+Write the bio in a friendly, heartfelt tone. Start with "Meet {name}!" and end with an encouraging call to action to visit the shelter. Do not use hashtags or emojis. Keep it under 150 words.
+
+Bio:"""
+    
+    return prompt
+
+
+def _generate_via_inference_api(prompt: str, hf_token: str, max_retries: int = 3) -> str:
+    """
+    Generate bio using Hugging Face Inference API.
+    """
+    
+    try:
+        from huggingface_hub import InferenceClient
+    except ImportError:
+        raise RuntimeError(
+            "huggingface_hub not installed. "
+            "Install it with: pip install huggingface-hub"
+        )
+    
+    # Initialize client
+    client = InferenceClient(token=hf_token)
+    
+    # Models to try (in order of preference)
+    models = [
+        "HuggingFaceH4/zephyr-7b-beta",
+        "mistralai/Mistral-7B-Instruct-v0.2",
+        "meta-llama/Llama-2-7b-chat-hf",
+        "google/flan-t5-xl"
+    ]
+    
+    last_error = None
+    
+    for model_name in models:
+        for attempt in range(max_retries):
+            try:
+                print(f"Attempting {model_name} (attempt {attempt + 1}/{max_retries})...")
+                
+                # Call the API
+                response = client.text_generation(
+                    prompt,
+                    model=model_name,
+                    max_new_tokens=250,
+                    temperature=0.7,
+                    top_p=0.9,
+                    repetition_penalty=1.1,
+                    do_sample=True
+                )
+                
+                # Extract the bio text
+                bio = _extract_bio_from_response(response)
+                
+                if bio and len(bio) > 20:
+                    print(f"✅ Bio generated successfully using {model_name}")
+                    return bio
+                else:
+                    print(f"⚠️ Generated bio too short, retrying...")
+                    
+            except Exception as e:
+                last_error = e
+                print(f"⚠️ Attempt failed: {e}")
+                
+                if attempt < max_retries - 1:
+                    wait_time = 2 ** attempt  # Exponential backoff
+                    print(f"Waiting {wait_time}s before retry...")
+                    time.sleep(wait_time)
+        
+        print(f"Model {model_name} failed after {max_retries} attempts, trying next model...")
+    
+    # If all models failed, raise the last error
+    raise RuntimeError(f"All models failed. Last error: {last_error}")
+
+
+def _extract_bio_from_response(response: str) -> str:
+    """
+    Extract the bio text from the model response.
+    """
+    
+    # The response might include the prompt + generated text
+    # Try to extract just the bio part
+    
+    # Look for "Bio:" and take everything after it
+    if "Bio:" in response:
+        bio = response.split("Bio:")[-1].strip()
+    else:
+        bio = response.strip()
+    
+    # Remove any trailing prompt artifacts
+    bio = bio.strip()
+    
+    # Remove any "---" or similar separators
+    if "---" in bio:
+        bio = bio.split("---")[0].strip()
+    
+    return bio
+
+
+def _generate_fallback_bio(
+    name: str,
+    animal_type: str,
+    breed: str,
+    age: str,
+    traits: List[str],
+    additional_notes: str
+) -> str:
+    """
+    Generate a bio using a template when API is unavailable.
+    """
+    
+    print("⚠️ Using fallback template-based bio generation")
+    
+    # Determine pronouns based on animal type
+    pronoun = "they" if animal_type == "Other" else "he/she"
+    possessive = "their" if animal_type == "Other" else "his/her"
+    
+    # Build traits description
+    if traits:
+        if len(traits) == 1:
+            traits_desc = traits[0].lower()
+        elif len(traits) == 2:
+            traits_desc = f"{traits[0].lower()} and {traits[1].lower()}"
+        else:
+            traits_desc = f"{', '.join(t.lower() for t in traits[:-1])}, and {traits[-1].lower()}"
+    else:
+        traits_desc = "friendly and loving"
+    
+    # Build the bio
+    animal_word = animal_type.lower() if animal_type != "Other" else "animal"
+    
+    intro = f"Meet {name}! This {age} {breed} {animal_word} is looking for a forever home."
+    
+    personality = f"{name} is {traits_desc}."
+    
+    if "good with kids" in [t.lower() for t in traits]:
+        personality += f" {name.split()[0]} would be perfect for a family with children."
+    elif "calm" in [t.lower() for t in traits] or "relaxed" in [t.lower() for t in traits]:
+        personality += f" {name.split()[0]} would thrive in a peaceful, quiet home."
+    elif "high energy" in [t.lower() for t in traits] or "playful" in [t.lower() for t in traits]:
+        personality += f" {name.split()[0]} would love an active family who enjoys outdoor adventures."
+    
+    if additional_notes:
+        personality += f" {additional_notes}"
+    
+    call_to_action = f"Come meet {name} at our shelter today and see if {pronoun}'s the perfect match for your family!"
+    
+    bio = f"{intro} {personality} {call_to_action}"
+    
+    return bio
+
+
+def test_bio_generation():
+    """Test function to verify bio generation works."""
+    
+    print("Testing bio generation...")
+    
+    test_cases = [
+        {
+            "name": "Bella",
+            "animal_type": "Dog",
+            "breed": "Golden Retriever",
+            "age": "2 years",
+            "traits": ["Good with kids", "Playful", "Loves cuddles", "House-trained"],
+            "additional_notes": "Bella knows basic commands and walks well on a leash."
+        },
+        {
+            "name": "Whiskers",
+            "animal_type": "Cat",
+            "breed": "Domestic Shorthair",
+            "age": "3 years",
+            "traits": ["Independent", "Calm / Relaxed", "Good with other cats"],
+            "additional_notes": "Whiskers enjoys sunny window spots and gentle petting."
+        }
+    ]
+    
+    for i, test_case in enumerate(test_cases, 1):
+        print(f"\n{'='*60}")
+        print(f"Test Case {i}: {test_case['name']}")
+        print(f"{'='*60}")
+        
+        try:
+            bio = generate_bio(**test_case)
+            print(f"\nGenerated Bio:")
+            print(f"{bio}")
+            print(f"\n✅ Test case {i} passed!")
+            
+        except Exception as e:
+            print(f"\n❌ Test case {i} failed: {e}")
+            import traceback
+            traceback.print_exc()
+    
+    print(f"\n{'='*60}")
+    print("Bio generation test complete!")
+
+
+if __name__ == "__main__":
+    test_bio_generation()

core/compositing.py

@@ -0,0 +1,293 @@
+"""
+Image Compositing Module
+Composites the animal cutout onto a background scene with smart scaling and positioning.
+"""
+
+from PIL import Image, ImageFilter, ImageEnhance
+import numpy as np
+from typing import Literal, Tuple
+
+
+def composite_animal_on_scene(
+    animal_rgba: Image.Image,
+    scene: Image.Image,
+    position: Literal["center", "left", "right"] = "center",
+    scale_factor: float = 0.6
+) -> Image.Image:
+    """
+    Places the transparent-background animal onto the scene image.
+    Returns the final composited RGB image.
+    
+    Args:
+        animal_rgba: PIL Image in RGBA format (animal with transparent background)
+        scene: PIL Image (background scene)
+        position: Where to place the animal ("center", "left", "right")
+        scale_factor: Animal size relative to scene height (0.0 to 1.0)
+    
+    Returns:
+        PIL Image in RGB format with animal composited on scene
+    """
+    
+    # Ensure scene is RGB
+    if scene.mode == 'RGBA':
+        scene = scene.convert('RGB')
+    elif scene.mode != 'RGB':
+        scene = scene.convert('RGB')
+    
+    # Ensure animal is RGBA
+    if animal_rgba.mode != 'RGBA':
+        animal_rgba = animal_rgba.convert('RGBA')
+    
+    # Make a copy of the scene to avoid modifying the original
+    composite = scene.copy()
+    
+    # Resize animal to fit the scene
+    animal_resized = _resize_animal_to_scene(animal_rgba, scene, scale_factor)
+    
+    # Smooth the edges of the alpha mask
+    animal_smooth = _smooth_alpha_edges(animal_resized)
+    
+    # Calculate position
+    x_pos, y_pos = _calculate_position(
+        animal_size=animal_smooth.size,
+        scene_size=composite.size,
+        position=position
+    )
+    
+    # Composite the animal onto the scene
+    # PIL's paste with mask uses the alpha channel for transparency
+    composite.paste(animal_smooth, (x_pos, y_pos), animal_smooth)
+    
+    return composite
+
+
+def _resize_animal_to_scene(
+    animal: Image.Image,
+    scene: Image.Image,
+    scale_factor: float
+) -> Image.Image:
+    """
+    Resize animal proportionally to fill scale_factor of scene height.
+    
+    Args:
+        animal: RGBA image of animal
+        scene: Background scene image
+        scale_factor: Target height as fraction of scene height
+    
+    Returns:
+        Resized animal image
+    """
+    
+    # Target height is scale_factor * scene height
+    target_height = int(scene.size[1] * scale_factor)
+    
+    # Calculate new width maintaining aspect ratio
+    aspect_ratio = animal.size[0] / animal.size[1]
+    target_width = int(target_height * aspect_ratio)
+    
+    # Ensure animal doesn't exceed scene width
+    max_width = int(scene.size[0] * 0.9)  # Leave 10% margin
+    if target_width > max_width:
+        target_width = max_width
+        target_height = int(target_width / aspect_ratio)
+    
+    # Resize with high-quality resampling
+    animal_resized = animal.resize(
+        (target_width, target_height),
+        Image.Resampling.LANCZOS
+    )
+    
+    return animal_resized
+
+
+def _smooth_alpha_edges(animal_rgba: Image.Image, blur_radius: int = 2) -> Image.Image:
+    """
+    Apply slight Gaussian blur to edges of the alpha mask for smoother blending.
+    
+    Args:
+        animal_rgba: RGBA image
+        blur_radius: Radius of Gaussian blur (pixels)
+    
+    Returns:
+        RGBA image with smoothed alpha channel
+    """
+    
+    # Split into RGB and alpha
+    rgb = animal_rgba.convert('RGB')
+    alpha = animal_rgba.split()[3]  # Get alpha channel
+    
+    # Apply slight blur to alpha channel
+    alpha_blurred = alpha.filter(ImageFilter.GaussianBlur(radius=blur_radius))
+    
+    # Merge back
+    result = rgb.copy()
+    result.putalpha(alpha_blurred)
+    
+    return result
+
+
+def _calculate_position(
+    animal_size: Tuple[int, int],
+    scene_size: Tuple[int, int],
+    position: str
+) -> Tuple[int, int]:
+    """
+    Calculate x, y position for animal placement.
+    
+    Args:
+        animal_size: (width, height) of animal
+        scene_size: (width, height) of scene
+        position: "center", "left", or "right"
+    
+    Returns:
+        (x, y) position for top-left corner of animal
+    """
+    
+    animal_width, animal_height = animal_size
+    scene_width, scene_height = scene_size
+    
+    # Vertical position: bottom-aligned with slight offset
+    # This makes the animal look like it's "standing" on the scene
+    y_offset = int(scene_height * 0.15)  # 15% from bottom
+    y_pos = scene_height - animal_height - y_offset
+    
+    # Ensure animal doesn't go above the scene
+    y_pos = max(y_pos, 0)
+    
+    # Horizontal position
+    if position == "center":
+        x_pos = (scene_width - animal_width) // 2
+    elif position == "left":
+        x_offset = int(scene_width * 0.1)  # 10% from left
+        x_pos = x_offset
+    elif position == "right":
+        x_offset = int(scene_width * 0.1)  # 10% from right
+        x_pos = scene_width - animal_width - x_offset
+    else:
+        # Default to center
+        x_pos = (scene_width - animal_width) // 2
+    
+    # Ensure animal stays within scene bounds
+    x_pos = max(0, min(x_pos, scene_width - animal_width))
+    
+    return x_pos, y_pos
+
+
+def auto_adjust_brightness(
+    animal_rgba: Image.Image,
+    scene: Image.Image,
+    strength: float = 0.5
+) -> Image.Image:
+    """
+    Optional: Adjust animal brightness to match scene lighting.
+    
+    Args:
+        animal_rgba: RGBA image of animal
+        scene: Background scene image
+        strength: How much to adjust (0.0 = no adjustment, 1.0 = full adjustment)
+    
+    Returns:
+        RGBA image with adjusted brightness
+    """
+    
+    # Calculate average brightness of scene
+    scene_gray = scene.convert('L')
+    scene_array = np.array(scene_gray)
+    scene_brightness = scene_array.mean() / 255.0
+    
+    # Calculate average brightness of animal (excluding transparent pixels)
+    animal_array = np.array(animal_rgba)
+    rgb = animal_array[:, :, :3]
+    alpha = animal_array[:, :, 3]
+    
+    # Only consider non-transparent pixels
+    mask = alpha > 0
+    if mask.sum() == 0:
+        return animal_rgba  # No visible pixels
+    
+    animal_brightness = rgb[mask].mean() / 255.0
+    
+    # Calculate brightness adjustment factor
+    brightness_diff = scene_brightness - animal_brightness
+    adjustment = 1.0 + (brightness_diff * strength)
+    adjustment = max(0.5, min(adjustment, 1.5))  # Clamp to reasonable range
+    
+    # Apply brightness adjustment
+    rgb_image = animal_rgba.convert('RGB')
+    enhancer = ImageEnhance.Brightness(rgb_image)
+    adjusted_rgb = enhancer.enhance(adjustment)
+    
+    # Merge back with alpha
+    result = adjusted_rgb.copy()
+    result.putalpha(animal_rgba.split()[3])
+    
+    return result
+
+
+def test_compositing():
+    """Test function to verify compositing works."""
+    from pathlib import Path
+    import sys
+    
+    # Try to import background removal to get a cutout
+    try:
+        from .background_removal import remove_background
+    except ImportError:
+        sys.path.insert(0, str(Path(__file__).parent.parent))
+        from core.background_removal import remove_background
+    
+    # Find test images
+    test_animal = None
+    for path in [Path("cat.png"), Path("examples/cat.png")]:
+        if path.exists():
+            test_animal = path
+            break
+    
+    test_scene = None
+    for path in [Path("backgrounds/living_room.jpg"), Path("backgrounds/park.jpg")]:
+        if path.exists():
+            test_scene = path
+            break
+    
+    if test_animal is None or test_scene is None:
+        print("❌ Test images not found")
+        return False
+    
+    print(f"Testing compositing with animal: {test_animal}, scene: {test_scene}")
+    
+    try:
+        # Load images
+        animal_img = Image.open(test_animal)
+        scene_img = Image.open(test_scene)
+        
+        # Remove background
+        print("Removing background...")
+        animal_cutout = remove_background(animal_img)
+        
+        # Composite
+        print("Compositing...")
+        result = composite_animal_on_scene(
+            animal_rgba=animal_cutout,
+            scene=scene_img,
+            position="center",
+            scale_factor=0.6
+        )
+        
+        # Save result
+        output_path = Path("outputs") / f"test_composite_{test_animal.stem}_on_{test_scene.stem}.jpg"
+        output_path.parent.mkdir(exist_ok=True)
+        result.save(output_path, quality=95)
+        print(f"✅ Test passed! Result saved to: {output_path}")
+        
+        return True
+        
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    print("Running compositing test...")
+    test_compositing()

core/flyer_builder.py

@@ -0,0 +1,485 @@
+"""
+Flyer Builder Module
+Assembles the final adoption flyer with photo, bio, and shelter information.
+"""
+
+from PIL import Image, ImageDraw, ImageFont
+from pathlib import Path
+from typing import Optional, Tuple
+import textwrap
+
+
+def build_flyer(
+    photo: Image.Image,
+    name: str,
+    animal_type: str,
+    breed: str,
+    age: str,
+    bio: str,
+    shelter_name: str = "Your Local Animal Shelter",
+    shelter_contact: str = "",
+    template: str = "template_1"
+) -> Image.Image:
+    """
+    Assembles a print-ready flyer image (PNG).
+    Returns a PIL Image of the final flyer.
+    
+    Args:
+        photo: Enhanced animal photo (composited on scene)
+        name: Animal's name
+        animal_type: "Dog", "Cat", or "Other"
+        breed: Breed description
+        age: Age description
+        bio: Generated bio text
+        shelter_name: Name of the shelter
+        shelter_contact: Contact information
+        template: Template style to use
+    
+    Returns:
+        PIL Image of the final flyer (1080 x 1920 px, portrait)
+    """
+    
+    # Canvas size (portrait, social-media friendly)
+    canvas_width = 1080
+    canvas_height = 1920
+    
+    # Color scheme (warm, inviting colors)
+    colors = {
+        'background': (255, 250, 245),      # Warm white
+        'header_bg': (255, 140, 105),       # Coral
+        'text_dark': (51, 51, 51),          # Dark gray
+        'text_light': (255, 255, 255),      # White
+        'accent': (100, 180, 220),          # Soft blue
+        'info_bg': (245, 245, 245)          # Light gray
+    }
+    
+    # Create canvas
+    flyer = Image.new('RGB', (canvas_width, canvas_height), colors['background'])
+    draw = ImageDraw.Draw(flyer)
+    
+    # Load fonts
+    fonts = _load_fonts()
+    
+    # Layout positions
+    margin = 40
+    current_y = margin
+    
+    # 1. Header: "ADOPT ME!" banner
+    current_y = _draw_header(draw, canvas_width, current_y, colors, fonts)
+    
+    # 2. Animal photo (centered, with rounded corners)
+    current_y = _draw_photo(flyer, photo, canvas_width, current_y, margin)
+    
+    # 3. Info bar: Name, breed, age, type
+    current_y = _draw_info_bar(
+        draw, name, breed, age, animal_type,
+        canvas_width, current_y, margin, colors, fonts
+    )
+    
+    # 4. Bio section
+    current_y = _draw_bio(
+        draw, bio, canvas_width, current_y, margin, colors, fonts
+    )
+    
+    # 5. Footer: Shelter info
+    _draw_footer(
+        draw, shelter_name, shelter_contact,
+        canvas_width, canvas_height, margin, colors, fonts
+    )
+    
+    return flyer
+
+
+def _load_fonts() -> dict:
+    """
+    Load fonts with fallback to default if custom fonts not available.
+    """
+    
+    fonts = {}
+    
+    # Try to load custom fonts
+    font_paths = {
+        'bold': [
+            Path("templates/fonts/Poppins-Bold.ttf"),
+            Path("fonts/Poppins-Bold.ttf"),
+        ],
+        'regular': [
+            Path("templates/fonts/Poppins-Regular.ttf"),
+            Path("fonts/Poppins-Regular.ttf"),
+        ]
+    }
+    
+    # Try loading custom fonts
+    for font_type, paths in font_paths.items():
+        loaded = False
+        for path in paths:
+            if path.exists():
+                try:
+                    fonts[f'{font_type}_large'] = ImageFont.truetype(str(path), 72)
+                    fonts[f'{font_type}_title'] = ImageFont.truetype(str(path), 48)
+                    fonts[f'{font_type}_heading'] = ImageFont.truetype(str(path), 36)
+                    fonts[f'{font_type}_body'] = ImageFont.truetype(str(path), 28)
+                    fonts[f'{font_type}_small'] = ImageFont.truetype(str(path), 24)
+                    loaded = True
+                    break
+                except Exception as e:
+                    print(f"⚠️ Failed to load font {path}: {e}")
+        
+        if not loaded:
+            print(f"⚠️ Using default font for {font_type}")
+    
+    # Fallback to default font if needed
+    if not fonts:
+        try:
+            fonts['bold_large'] = ImageFont.truetype("arial.ttf", 72)
+            fonts['bold_title'] = ImageFont.truetype("arial.ttf", 48)
+            fonts['bold_heading'] = ImageFont.truetype("arial.ttf", 36)
+            fonts['regular_body'] = ImageFont.truetype("arial.ttf", 28)
+            fonts['regular_small'] = ImageFont.truetype("arial.ttf", 24)
+        except:
+            # Ultimate fallback
+            fonts['bold_large'] = ImageFont.load_default()
+            fonts['bold_title'] = ImageFont.load_default()
+            fonts['bold_heading'] = ImageFont.load_default()
+            fonts['regular_body'] = ImageFont.load_default()
+            fonts['regular_small'] = ImageFont.load_default()
+    
+    return fonts
+
+
+def _draw_header(
+    draw: ImageDraw.ImageDraw,
+    canvas_width: int,
+    y_pos: int,
+    colors: dict,
+    fonts: dict
+) -> int:
+    """
+    Draw the "ADOPT ME!" header banner.
+    Returns the new y position.
+    """
+    
+    header_height = 150
+    
+    # Draw header background
+    draw.rectangle(
+        [(0, y_pos), (canvas_width, y_pos + header_height)],
+        fill=colors['header_bg']
+    )
+    
+    # Draw header text
+    header_text = "🐾 ADOPT ME! 🐾"
+    font = fonts.get('bold_large', fonts.get('bold_title', ImageFont.load_default()))
+    
+    # Get text bbox for centering
+    bbox = draw.textbbox((0, 0), header_text, font=font)
+    text_width = bbox[2] - bbox[0]
+    text_height = bbox[3] - bbox[1]
+    
+    text_x = (canvas_width - text_width) // 2
+    text_y = y_pos + (header_height - text_height) // 2
+    
+    draw.text(
+        (text_x, text_y),
+        header_text,
+        fill=colors['text_light'],
+        font=font
+    )
+    
+    return y_pos + header_height + 40
+
+
+def _draw_photo(
+    flyer: Image.Image,
+    photo: Image.Image,
+    canvas_width: int,
+    y_pos: int,
+    margin: int
+) -> int:
+    """
+    Draw the animal photo with rounded corners.
+    Returns the new y position.
+    """
+    
+    # Photo dimensions
+    photo_width = canvas_width - (2 * margin)
+    photo_height = int(photo_width * 0.75)  # 4:3 aspect ratio
+    
+    # Resize photo to fit
+    photo_resized = photo.copy()
+    photo_resized.thumbnail((photo_width, photo_height), Image.Resampling.LANCZOS)
+    
+    # Center the resized photo
+    photo_x = margin + (photo_width - photo_resized.width) // 2
+    photo_y = y_pos
+    
+    # Create rounded corners mask
+    mask = _create_rounded_rectangle_mask(
+        photo_resized.size,
+        radius=30
+    )
+    
+    # Apply mask to photo
+    photo_rounded = photo_resized.copy()
+    photo_rounded.putalpha(mask)
+    
+    # Paste onto flyer
+    flyer.paste(photo_rounded, (photo_x, photo_y), photo_rounded)
+    
+    return photo_y + photo_resized.height + 40
+
+
+def _create_rounded_rectangle_mask(size: Tuple[int, int], radius: int) -> Image.Image:
+    """
+    Create a mask for rounded corners.
+    """
+    
+    mask = Image.new('L', size, 0)
+    draw = ImageDraw.Draw(mask)
+    
+    # Draw rounded rectangle
+    draw.rounded_rectangle(
+        [(0, 0), size],
+        radius=radius,
+        fill=255
+    )
+    
+    return mask
+
+
+def _draw_info_bar(
+    draw: ImageDraw.ImageDraw,
+    name: str,
+    breed: str,
+    age: str,
+    animal_type: str,
+    canvas_width: int,
+    y_pos: int,
+    margin: int,
+    colors: dict,
+    fonts: dict
+) -> int:
+    """
+    Draw the info bar with name, breed, age, type.
+    Returns the new y position.
+    """
+    
+    bar_height = 180
+    bar_y = y_pos
+    
+    # Draw background
+    draw.rectangle(
+        [(margin, bar_y), (canvas_width - margin, bar_y + bar_height)],
+        fill=colors['info_bg'],
+        outline=colors['accent'],
+        width=3
+    )
+    
+    # Draw animal name (large, centered at top)
+    name_font = fonts.get('bold_title', ImageFont.load_default())
+    bbox = draw.textbbox((0, 0), name, font=name_font)
+    name_width = bbox[2] - bbox[0]
+    name_x = (canvas_width - name_width) // 2
+    name_y = bar_y + 20
+    
+    draw.text(
+        (name_x, name_y),
+        name,
+        fill=colors['text_dark'],
+        font=name_font
+    )
+    
+    # Draw breed, age, type (smaller, below name)
+    info_font = fonts.get('regular_body', ImageFont.load_default())
+    
+    info_text = f"{breed} • {age} • {animal_type}"
+    bbox = draw.textbbox((0, 0), info_text, font=info_font)
+    info_width = bbox[2] - bbox[0]
+    info_x = (canvas_width - info_width) // 2
+    info_y = name_y + 65
+    
+    draw.text(
+        (info_x, info_y),
+        info_text,
+        fill=colors['text_dark'],
+        font=info_font
+    )
+    
+    return bar_y + bar_height + 40
+
+
+def _draw_bio(
+    draw: ImageDraw.ImageDraw,
+    bio: str,
+    canvas_width: int,
+    y_pos: int,
+    margin: int,
+    colors: dict,
+    fonts: dict
+) -> int:
+    """
+    Draw the bio text with word wrapping.
+    Returns the new y position.
+    """
+    
+    bio_font = fonts.get('regular_body', ImageFont.load_default())
+    
+    # Word wrap the bio
+    max_width = canvas_width - (2 * margin) - 40
+    
+    # Estimate characters per line
+    # Use a sample to estimate average char width
+    sample = "A" * 50
+    bbox = draw.textbbox((0, 0), sample, font=bio_font)
+    avg_char_width = (bbox[2] - bbox[0]) / 50
+    chars_per_line = int(max_width / avg_char_width)
+    
+    wrapped_lines = textwrap.wrap(bio, width=chars_per_line)
+    
+    # Draw each line
+    line_spacing = 15
+    current_y = y_pos
+    
+    for line in wrapped_lines:
+        draw.text(
+            (margin + 20, current_y),
+            line,
+            fill=colors['text_dark'],
+            font=bio_font
+        )
+        
+        bbox = draw.textbbox((0, 0), line, font=bio_font)
+        line_height = bbox[3] - bbox[1]
+        current_y += line_height + line_spacing
+    
+    return current_y + 40
+
+
+def _draw_footer(
+    draw: ImageDraw.ImageDraw,
+    shelter_name: str,
+    shelter_contact: str,
+    canvas_width: int,
+    canvas_height: int,
+    margin: int,
+    colors: dict,
+    fonts: dict
+):
+    """
+    Draw the footer with shelter information.
+    """
+    
+    footer_height = 150
+    footer_y = canvas_height - footer_height
+    
+    # Draw footer background
+    draw.rectangle(
+        [(0, footer_y), (canvas_width, canvas_height)],
+        fill=colors['accent']
+    )
+    
+    # Draw shelter name
+    name_font = fonts.get('bold_heading', ImageFont.load_default())
+    bbox = draw.textbbox((0, 0), shelter_name, font=name_font)
+    name_width = bbox[2] - bbox[0]
+    name_x = (canvas_width - name_width) // 2
+    name_y = footer_y + 30
+    
+    draw.text(
+        (name_x, name_y),
+        shelter_name,
+        fill=colors['text_light'],
+        font=name_font
+    )
+    
+    # Draw contact info if provided
+    if shelter_contact:
+        contact_font = fonts.get('regular_small', ImageFont.load_default())
+        bbox = draw.textbbox((0, 0), shelter_contact, font=contact_font)
+        contact_width = bbox[2] - bbox[0]
+        contact_x = (canvas_width - contact_width) // 2
+        contact_y = name_y + 55
+        
+        draw.text(
+            (contact_x, contact_y),
+            shelter_contact,
+            fill=colors['text_light'],
+            font=contact_font
+        )
+
+
+def build_flyer_pdf(
+    photo: Image.Image,
+    name: str,
+    animal_type: str,
+    breed: str,
+    age: str,
+    bio: str,
+    shelter_name: str = "Your Local Animal Shelter",
+    shelter_contact: str = "",
+    template: str = "template_1"
+) -> bytes:
+    """
+    Same as build_flyer but returns PDF bytes.
+    Coming soon - for now returns None.
+    """
+    
+    # TODO: Implement PDF generation using fpdf2
+    print("⚠️ PDF generation not yet implemented")
+    return None
+
+
+def test_flyer_builder():
+    """Test function to verify flyer building works."""
+    from pathlib import Path
+    
+    # Try to find a composited image or create a simple test
+    test_composite = None
+    for path in Path("outputs").glob("test_composite_*.jpg"):
+        test_composite = path
+        break
+    
+    if test_composite is None:
+        print("⚠️ No composite test image found. Creating a simple test...")
+        # Create a simple test image
+        test_img = Image.new('RGB', (800, 600), (100, 150, 200))
+        test_composite = test_img
+    else:
+        test_composite = Image.open(test_composite)
+    
+    print(f"Testing flyer builder with image: {test_composite}")
+    
+    # Test data
+    test_data = {
+        "photo": test_composite,
+        "name": "Bella",
+        "animal_type": "Dog",
+        "breed": "Golden Retriever",
+        "age": "2 years",
+        "bio": "Meet Bella! This sweet golden girl is the perfect family companion. She's great with kids, loves to play fetch, and will greet you every day with a wagging tail. Bella is house-trained and knows basic commands. Come meet Bella at our shelter today and see if she's the perfect match for your family!",
+        "shelter_name": "Happy Paws Animal Shelter",
+        "shelter_contact": "(555) 123-4567 | www.happypaws.org"
+    }
+    
+    try:
+        print("Building flyer...")
+        flyer = build_flyer(**test_data)
+        
+        # Save result
+        output_path = Path("outputs") / "test_flyer.png"
+        output_path.parent.mkdir(exist_ok=True)
+        flyer.save(output_path, quality=95)
+        print(f"✅ Test passed! Flyer saved to: {output_path}")
+        
+        return True
+        
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    print("Running flyer builder test...")
+    test_flyer_builder()

requirements.txt

@@ -0,0 +1,9 @@
+gradio>=4.0
+Pillow>=10.0
+transformers>=4.35
+torch>=2.0
+huggingface-hub>=0.20
+python-dotenv>=1.0
+fpdf2>=2.7
+rembg>=2.0
+numpy>=1.24