deckbuilder 1.0.0b1__py3-none-any.whl

deckbuilder/image_handler.py

@@ -0,0 +1,291 @@
+"""
+ImageHandler - Core image file validation, processing, and management.
+
+This module provides the ImageHandler class for validating image files,
+processing them for PowerPoint placeholders, and managing cached fallback images.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+from typing import Optional, Tuple
+
+from PIL import Image
+
+
+class ImageHandler:
+    """
+    Core image file validation, processing, and management.
+
+    Handles image file validation, format conversion, resizing,
+    and caching for optimal performance in presentation generation.
+    """
+
+    def __init__(self, cache_dir: str = "temp/image_cache"):
+        """
+        Initialize ImageHandler with cache directory.
+
+        Args:
+            cache_dir: Directory for caching processed images
+        """
+        self.cache_dir = Path(cache_dir)
+        try:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            # Fallback to a temporary directory if cache_dir is not writable
+            import tempfile
+
+            self.cache_dir = Path(tempfile.gettempdir()) / "deckbuilder_image_cache"
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+        # Supported image formats for PowerPoint
+        self.supported_formats = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".gif"}
+
+        # Quality settings for output
+        self.quality_settings = {"high": 95, "medium": 85, "low": 70}
+
+    def validate_image(self, image_path: str) -> bool:
+        """
+        Validate image file existence, format, and accessibility.
+
+        Args:
+            image_path: Path to image file to validate
+
+        Returns:
+            bool: True if image is valid and accessible, False otherwise
+        """
+        if not image_path:
+            return False
+
+        try:
+            path = Path(image_path)
+
+            # Check file existence
+            if not path.exists():
+                return False
+
+            # Check if it's a file (not directory)
+            if not path.is_file():
+                return False
+
+            # Check file extension
+            if path.suffix.lower() not in self.supported_formats:
+                return False
+
+            # Try to open and validate the image
+            with Image.open(path) as img:
+                # Verify image can be loaded and read
+                img.verify()
+
+            return True
+
+        except Exception:
+            # Any exception during validation means invalid image
+            return False
+
+    def get_image_dimensions(self, image_path: str) -> Optional[Tuple[int, int]]:
+        """
+        Get image dimensions without loading the full image.
+
+        Args:
+            image_path: Path to image file
+
+        Returns:
+            Tuple of (width, height) or None if image invalid
+        """
+        try:
+            with Image.open(image_path) as img:
+                return img.size
+        except Exception:
+            return None
+
+    def process_image(
+        self, image_path: str, target_dimensions: Tuple[int, int], quality: str = "high"
+    ) -> Optional[str]:
+        """
+        Process and resize image to target dimensions for PowerPoint placeholder.
+
+        Args:
+            image_path: Path to source image file
+            target_dimensions: Target (width, height) for placeholder
+            quality: Quality level ('high', 'medium', 'low')
+
+        Returns:
+            str: Path to processed image file, or None if processing failed
+        """
+        if not self.validate_image(image_path):
+            return None
+
+        try:
+            target_width, target_height = target_dimensions
+
+            # Generate cache key based on input and parameters
+            cache_key = self._generate_cache_key(image_path, target_dimensions, quality)
+            cached_path = self._get_cached_image(cache_key)
+
+            if cached_path:
+                return cached_path
+
+            # Process the image
+            with Image.open(image_path) as img:
+                # Convert to RGB if necessary (for JPEG output)
+                if img.mode != "RGB":
+                    img = img.convert("RGB")
+
+                # Calculate dimensions preserving aspect ratio
+                processed_img = self._resize_with_aspect_ratio(img, target_width, target_height)
+
+                # Save processed image
+                output_path = self._save_processed_image(processed_img, cache_key, quality)
+
+                return str(output_path)
+
+        except Exception as e:
+            print(f"Warning: Image processing failed for {image_path}: {e}")
+            return None
+
+    def _resize_with_aspect_ratio(
+        self, img: Image.Image, target_width: int, target_height: int
+    ) -> Image.Image:
+        """
+        Resize image to fit target dimensions while preserving aspect ratio.
+
+        Args:
+            img: PIL Image object
+            target_width: Target width
+            target_height: Target height
+
+        Returns:
+            PIL Image resized to fit within target dimensions
+        """
+        # Get original dimensions
+        orig_width, orig_height = img.size
+
+        # Calculate scaling ratios
+        width_ratio = target_width / orig_width
+        height_ratio = target_height / orig_height
+
+        # Use the smaller ratio to ensure image fits within bounds
+        scale_ratio = min(width_ratio, height_ratio)
+
+        # Calculate new dimensions
+        new_width = int(orig_width * scale_ratio)
+        new_height = int(orig_height * scale_ratio)
+
+        # Resize using high-quality resampling
+        return img.resize((new_width, new_height), Image.Resampling.LANCZOS)
+
+    def _generate_cache_key(
+        self, image_path: str, dimensions: Tuple[int, int], quality: str
+    ) -> str:
+        """
+        Generate unique cache key for processed image.
+
+        Args:
+            image_path: Source image path
+            dimensions: Target dimensions
+            quality: Quality setting
+
+        Returns:
+            str: Unique cache key
+        """
+        # Include file modification time to detect changes
+        try:
+            mtime = os.path.getmtime(image_path)
+        except OSError:
+            mtime = 0
+
+        # Create hash from path, dimensions, quality, and modification time
+        key_data = f"{image_path}_{dimensions[0]}x{dimensions[1]}_{quality}_{mtime}"
+        return hashlib.md5(key_data.encode(), usedforsecurity=False).hexdigest()  # nosec
+
+    def _get_cached_image(self, cache_key: str) -> Optional[str]:
+        """
+        Retrieve cached processed image if available.
+
+        Args:
+            cache_key: Cache key for the image
+
+        Returns:
+            str: Path to cached image, or None if not cached
+        """
+        cached_path = self.cache_dir / f"{cache_key}.jpg"
+
+        if cached_path.exists():
+            return str(cached_path)
+
+        return None
+
+    def _save_processed_image(self, img: Image.Image, cache_key: str, quality: str) -> Path:
+        """
+        Save processed image to cache with specified quality.
+
+        Args:
+            img: PIL Image to save
+            cache_key: Cache key for filename
+            quality: Quality level for JPEG compression
+
+        Returns:
+            Path: Path to saved image file
+        """
+        output_path = self.cache_dir / f"{cache_key}.jpg"
+
+        # Get quality setting
+        jpeg_quality = self.quality_settings.get(quality, 95)
+
+        # Save as JPEG with specified quality
+        img.save(output_path, "JPEG", quality=jpeg_quality, optimize=True)
+
+        return output_path
+
+    def cleanup_cache(self, max_size_mb: int = 100):
+        """
+        Clean up cache directory if it exceeds maximum size.
+
+        Args:
+            max_size_mb: Maximum cache size in megabytes
+        """
+        try:
+            # Calculate total cache size
+            total_size = sum(f.stat().st_size for f in self.cache_dir.glob("*.jpg") if f.is_file())
+
+            max_size_bytes = max_size_mb * 1024 * 1024
+
+            if total_size > max_size_bytes:
+                # Get files sorted by access time (LRU)
+                cache_files = [
+                    (f, f.stat().st_atime) for f in self.cache_dir.glob("*.jpg") if f.is_file()
+                ]
+                cache_files.sort(key=lambda x: x[1])  # Sort by access time
+
+                # Remove oldest files until under limit
+                current_size = total_size
+                for file_path, _ in cache_files:
+                    if current_size <= max_size_bytes:
+                        break
+
+                    file_size = file_path.stat().st_size
+                    file_path.unlink()
+                    current_size -= file_size
+
+        except Exception as e:
+            print(f"Warning: Cache cleanup failed: {e}")
+
+    def get_cache_stats(self) -> dict:
+        """
+        Get statistics about the image cache.
+
+        Returns:
+            dict: Cache statistics including file count and total size
+        """
+        try:
+            cache_files = list(self.cache_dir.glob("*.jpg"))
+            total_size = sum(f.stat().st_size for f in cache_files if f.is_file())
+
+            return {
+                "file_count": len(cache_files),
+                "total_size_mb": round(total_size / (1024 * 1024), 2),
+                "cache_dir": str(self.cache_dir),
+            }
+        except Exception:
+            return {"file_count": 0, "total_size_mb": 0.0, "cache_dir": str(self.cache_dir)}

deckbuilder/layout_intelligence.json

@@ -0,0 +1,288 @@
+{
+  "layout_intelligence": {
+    "version": "1.0",
+    "description": "Semantic metadata for content-first layout recommendations using convention-based placeholder names",
+    "last_updated": "2025-06-23"
+  },
+  "content_patterns": {
+    "intent_recognition": {
+      "comparison": {
+        "keywords": ["vs", "versus", "compare", "contrast", "option", "alternative", "pros", "cons"],
+        "structure": ["paired_content", "left_right", "side_by_side"],
+        "layouts": ["Comparison", "Two Content"],
+        "confidence": 0.9
+      },
+      "overview": {
+        "keywords": ["overview", "summary", "introduction", "agenda", "outline", "roadmap"],
+        "structure": ["list_items", "bullet_points", "numbered_items"],
+        "layouts": ["Title and Content", "Agenda, 6 Textboxes"],
+        "confidence": 0.8
+      },
+      "features": {
+        "keywords": ["feature", "benefit", "capability", "function", "advantage"],
+        "structure": ["multiple_columns", "categorized_content"],
+        "layouts": ["Four Columns With Titles", "Three Columns With Titles"],
+        "confidence": 0.85
+      },
+      "process": {
+        "keywords": ["step", "process", "workflow", "procedure", "method"],
+        "structure": ["sequential", "numbered", "timeline"],
+        "layouts": ["Agenda, 6 Textboxes", "Title and 6-item Lists"],
+        "confidence": 0.8
+      },
+      "statistics": {
+        "keywords": ["number", "percent", "metric", "data", "result", "performance"],
+        "structure": ["big_number", "key_metric", "single_focus"],
+        "layouts": ["Big Number", "Title and Content"],
+        "confidence": 0.9
+      },
+      "analysis": {
+        "keywords": ["swot", "analysis", "strength", "weakness", "opportunity", "threat"],
+        "structure": ["four_quadrant", "categorized_analysis"],
+        "layouts": ["SWOT Analysis", "Four Columns With Titles"],
+        "confidence": 0.95
+      }
+    },
+    "content_type_mapping": {
+      "title_content": {
+        "placeholders": ["title_top_1"],
+        "detection": ["single_heading", "main_title"],
+        "layouts": ["Title Slide", "Title Only"]
+      },
+      "subtitle_content": {
+        "placeholders": ["subtitle_1"],
+        "detection": ["secondary_heading", "tagline"],
+        "layouts": ["Title Slide"]
+      },
+      "body_content": {
+        "placeholders": ["content_1", "content_main_1"],
+        "detection": ["paragraph", "bullet_list", "description"],
+        "layouts": ["Title and Content", "Section Header"]
+      },
+      "column_content": {
+        "placeholders": ["content_col1_1", "content_col2_1", "content_col3_1", "content_col4_1"],
+        "detection": ["multiple_sections", "categorized_items", "parallel_content"],
+        "layouts": ["Four Columns With Titles", "Three Columns With Titles", "Four Columns", "Three Columns"]
+      },
+      "comparison_content": {
+        "placeholders": ["content_left_1", "content_right_1", "title_left_1", "title_right_1"],
+        "detection": ["paired_items", "versus_content", "side_by_side"],
+        "layouts": ["Comparison", "Two Content"]
+      },
+      "image_content": {
+        "placeholders": ["image_1", "image_main_1"],
+        "detection": ["image_reference", "media_placeholder", "visual_content"],
+        "layouts": ["Picture with Caption"]
+      },
+      "caption_content": {
+        "placeholders": ["text_caption_1"],
+        "detection": ["image_description", "caption_text"],
+        "layouts": ["Picture with Caption", "Content with Caption"]
+      },
+      "agenda_content": {
+        "placeholders": ["number_item1_1", "content_item1_1", "number_item2_1", "content_item2_1"],
+        "detection": ["numbered_list", "agenda_items", "sequential_content"],
+        "layouts": ["Agenda, 6 Textboxes", "Title and 6-item Lists"]
+      }
+    }
+  },
+  "layout_compatibility": {
+    "Title Slide": {
+      "optimal_for": ["presentation_intro", "section_divider", "title_only"],
+      "placeholders": {
+        "required": ["title_top_1"],
+        "optional": ["subtitle_1", "date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Main presentation title or section heading",
+        "subtitle_1": "Supporting tagline or description"
+      },
+      "confidence_factors": {
+        "single_heading": 0.9,
+        "short_title": 0.8,
+        "no_body_content": 0.85
+      }
+    },
+    "Title and Content": {
+      "optimal_for": ["general_content", "bullet_lists", "descriptions", "single_topic"],
+      "placeholders": {
+        "required": ["title_top_1", "content_1"],
+        "optional": ["date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Slide topic or main point",
+        "content_1": "Bullet points, paragraphs, or detailed content"
+      },
+      "confidence_factors": {
+        "single_content_block": 0.8,
+        "bullet_list": 0.85,
+        "paragraph_content": 0.7
+      }
+    },
+    "Comparison": {
+      "optimal_for": ["vs_content", "pros_cons", "before_after", "option_analysis"],
+      "placeholders": {
+        "required": ["title_top_1", "title_left_1", "content_left_1", "title_right_1", "content_right_1"],
+        "optional": ["date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Comparison topic",
+        "title_left_1": "Left option title",
+        "content_left_1": "Left option details",
+        "title_right_1": "Right option title",
+        "content_right_1": "Right option details"
+      },
+      "confidence_factors": {
+        "paired_content": 0.95,
+        "vs_keywords": 0.9,
+        "comparison_structure": 0.85
+      }
+    },
+    "Four Columns With Titles": {
+      "optimal_for": ["feature_grid", "benefit_overview", "four_categories", "quadrant_analysis"],
+      "placeholders": {
+        "required": ["title_top_1", "title_col1_1", "content_col1_1", "title_col2_1", "content_col2_1", "title_col3_1", "content_col3_1", "title_col4_1", "content_col4_1"],
+        "optional": ["date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Overall category or topic",
+        "title_col1_1": "First category title",
+        "content_col1_1": "First category details",
+        "title_col2_1": "Second category title",
+        "content_col2_1": "Second category details",
+        "title_col3_1": "Third category title",
+        "content_col3_1": "Third category details",
+        "title_col4_1": "Fourth category title",
+        "content_col4_1": "Fourth category details"
+      },
+      "confidence_factors": {
+        "four_items": 0.95,
+        "categorized_content": 0.9,
+        "parallel_structure": 0.85
+      }
+    },
+    "Three Columns With Titles": {
+      "optimal_for": ["three_categories", "feature_comparison", "process_steps"],
+      "placeholders": {
+        "required": ["title_top_1", "title_col1_1", "content_col1_1", "title_col2_1", "content_col2_1", "title_col3_1", "content_col3_1"],
+        "optional": ["date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Overall topic",
+        "title_col1_1": "First category",
+        "content_col1_1": "First details",
+        "title_col2_1": "Second category",
+        "content_col2_1": "Second details",
+        "title_col3_1": "Third category",
+        "content_col3_1": "Third details"
+      },
+      "confidence_factors": {
+        "three_items": 0.9,
+        "categorized_content": 0.85,
+        "balanced_content": 0.8
+      }
+    },
+    "Picture with Caption": {
+      "optimal_for": ["visual_content", "image_explanation", "diagram_description"],
+      "placeholders": {
+        "required": ["title_top_1", "image_1", "text_caption_1"],
+        "optional": ["date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Image or visual topic",
+        "image_1": "Main image or visual content",
+        "text_caption_1": "Image description or explanation"
+      },
+      "confidence_factors": {
+        "image_reference": 0.95,
+        "visual_content": 0.9,
+        "media_mention": 0.8
+      }
+    },
+    "Agenda, 6 Textboxes": {
+      "optimal_for": ["meeting_agenda", "process_steps", "numbered_items", "timeline"],
+      "placeholders": {
+        "required": ["title_top_1", "number_item1_1", "content_item1_1", "number_item2_1", "content_item2_1"],
+        "optional": ["number_item3_1", "content_item3_1", "number_item4_1", "content_item4_1", "number_item5_1", "content_item5_1", "number_item6_1", "content_item6_1", "date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Agenda or process title",
+        "number_item1_1": "Item number (01, 1, etc.)",
+        "content_item1_1": "Item description"
+      },
+      "confidence_factors": {
+        "numbered_list": 0.9,
+        "agenda_keywords": 0.85,
+        "sequential_content": 0.8
+      }
+    },
+    "Big Number": {
+      "optimal_for": ["key_metric", "important_statistic", "single_number_focus"],
+      "placeholders": {
+        "required": ["title_top_1", "content_1"],
+        "optional": ["date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "title_top_1": "Metric description",
+        "content_1": "Large number or percentage with context"
+      },
+      "confidence_factors": {
+        "percentage": 0.95,
+        "large_number": 0.9,
+        "metric_keywords": 0.85
+      }
+    },
+    "SWOT Analysis": {
+      "optimal_for": ["swot_analysis", "four_quadrant_analysis", "strategic_planning"],
+      "placeholders": {
+        "required": ["content_16", "content_17", "content_18", "content_19"],
+        "optional": ["date_footer_1", "footer_footer_1", "slide_number_footer_1"]
+      },
+      "content_hints": {
+        "content_16": "Strengths",
+        "content_17": "Weaknesses",
+        "content_18": "Opportunities",
+        "content_19": "Threats"
+      },
+      "confidence_factors": {
+        "swot_keywords": 0.98,
+        "four_categories": 0.9,
+        "analysis_structure": 0.85
+      }
+    }
+  },
+  "recommendation_engine": {
+    "scoring_weights": {
+      "content_structure": 0.4,
+      "keyword_matching": 0.3,
+      "intent_recognition": 0.2,
+      "layout_compatibility": 0.1
+    },
+    "minimum_confidence": 0.6,
+    "fallback_layouts": ["Title and Content", "Title Slide"],
+    "recommendation_rules": {
+      "multiple_recommendations": true,
+      "max_recommendations": 3,
+      "include_alternatives": true,
+      "explain_reasoning": true
+    }
+  },
+  "optimization_hints": {
+    "content_length": {
+      "title_top_1": "Keep under 60 characters for readability",
+      "subtitle_1": "Aim for 80-120 characters",
+      "content_areas": "Use bullet points for lists over 3 items",
+      "column_content": "Balance content length across columns"
+    },
+    "formatting_suggestions": {
+      "emphasis": "Use **bold** for key terms, *italic* for emphasis",
+      "structure": "Use consistent hierarchy with #, ##, ###",
+      "lists": "Use - for bullets, 1. for numbered items"
+    },
+    "layout_specific": {
+      "Comparison": "Keep left/right content balanced in length",
+      "Four Columns With Titles": "Aim for parallel structure across columns",
+      "Agenda, 6 Textboxes": "Use consistent numbering format (01, 02, etc.)"
+    }
+  }
+}