Upload 10 files

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()