deckbuilder 1.0.0b1__py3-none-any.whl

mcp_server/layout_recommendations.py

@@ -0,0 +1,595 @@
+"""
+Layout Recommendation Engine for Content-First Presentation Intelligence
+
+This module implements Tool #2: recommend_slide_approach() which analyzes specific
+content pieces and recommends optimal PowerPoint layouts based on communication intent.
+
+Design Philosophy: Match content structure and message intent to most effective layout,
+not just "what layouts exist?"
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class LayoutRecommendation:
+    """Single layout recommendation with confidence scoring"""
+
+    layout: str
+    confidence: float
+    reason: str
+    best_for: str
+
+
+class LayoutRecommendationEngine:
+    """
+    Analyzes content pieces and recommends optimal slide layouts.
+
+    Focuses on content structure, message intent, and communication effectiveness
+    rather than just available template options.
+    """
+
+    def __init__(self):
+        """Initialize with layout intelligence mapping"""
+        self.layout_intelligence = self._build_layout_intelligence()
+        self.available_layouts = self._get_available_layouts()
+
+    def recommend_slide_approach(
+        self, content_piece: str, message_intent: str, presentation_context: Optional[Dict] = None
+    ) -> Dict[str, Any]:
+        """
+        Analyze content and recommend optimal slide layouts.
+
+        Args:
+            content_piece: Specific content to present
+            message_intent: What they want this content to communicate
+            presentation_context: Optional context from analyze_presentation_needs()
+
+        Returns:
+            Dictionary with layout recommendations, content analysis, and suggestions
+        """
+        # Analyze the content structure and type
+        content_analysis = self._analyze_content_structure(content_piece)
+
+        # Determine communication intent
+        intent_analysis = self._analyze_message_intent(message_intent, content_piece)
+
+        # Generate layout recommendations with confidence scoring
+        layout_recommendations = self._generate_layout_recommendations(
+            content_analysis, intent_analysis, presentation_context
+        )
+
+        # Provide content structuring suggestions
+        content_suggestions = self._generate_content_suggestions(
+            content_analysis, intent_analysis, layout_recommendations
+        )
+
+        # Generate structured frontmatter preview
+        structured_frontmatter = self._generate_structured_frontmatter_preview(
+            layout_recommendations, content_piece, message_intent
+        )
+
+        return {
+            "recommended_layouts": [
+                {
+                    "layout": rec.layout,
+                    "confidence": rec.confidence,
+                    "reason": rec.reason,
+                    "best_for": rec.best_for,
+                }
+                for rec in layout_recommendations
+            ],
+            "content_analysis": content_analysis,
+            "content_suggestions": content_suggestions,
+            "structured_frontmatter": structured_frontmatter,
+        }
+
+    def _analyze_content_structure(self, content_piece: str) -> Dict[str, Any]:
+        """Analyze the structure and characteristics of the content."""
+        content_lower = content_piece.lower()
+
+        # Count various content elements
+        numbers_count = len(re.findall(r"\d+%|\$[\d,]+|\d+", content_piece))
+        bullet_indicators = len(re.findall(r"[-*•]|\d+\.|\w\)", content_piece))
+
+        # Detect content patterns
+        has_comparison = any(
+            word in content_lower for word in ["vs", "versus", "compared to", "versus", "against"]
+        )
+        has_list_structure = (
+            bullet_indicators > 2
+            or content_piece.count("\n") > 2
+            or content_piece.count(",") >= 3
+            or content_piece.count(":") >= 2
+        )
+        has_metrics = numbers_count >= 2
+        has_process = any(
+            word in content_lower for word in ["first", "then", "next", "finally", "step"]
+        )
+
+        # Determine content type
+        if has_comparison:
+            content_type = "comparison"
+        elif has_metrics:
+            content_type = "metrics_data"
+        elif has_process:
+            content_type = "process_timeline"
+        elif has_list_structure:
+            content_type = "structured_list"
+        else:
+            content_type = "narrative_text"
+
+        # Count distinct elements for layout sizing
+        distinct_elements = self._count_distinct_elements(content_piece)
+
+        return {
+            "content_type": content_type,
+            "data_elements": numbers_count,
+            "distinct_elements": distinct_elements,
+            "has_comparison": has_comparison,
+            "has_metrics": has_metrics,
+            "has_list_structure": has_list_structure,
+            "has_process": has_process,
+            "structure_pattern": self._determine_structure_pattern(content_piece),
+            "visual_emphasis": self._determine_visual_emphasis(content_piece, content_type),
+        }
+
+    def _analyze_message_intent(self, message_intent: str, content_piece: str) -> Dict[str, Any]:
+        """Analyze what the user wants to communicate with this content."""
+        intent_lower = message_intent.lower()
+
+        # Categorize communication intent
+        if any(word in intent_lower for word in ["compare", "contrast", "versus", "vs"]):
+            intent_category = "comparison"
+        elif any(
+            word in intent_lower for word in ["highlight", "emphasize", "showcase", "feature"]
+        ):
+            intent_category = "emphasis"
+        elif any(
+            word in intent_lower
+            for word in ["explain", "show process", "demonstrate", "walk through"]
+        ):
+            intent_category = "explanation"
+        elif any(word in intent_lower for word in ["data", "metrics", "numbers", "performance"]):
+            intent_category = "data_presentation"
+        elif any(word in intent_lower for word in ["overview", "summary", "introduction"]):
+            intent_category = "overview"
+        else:
+            intent_category = "general_information"
+
+        return {
+            "intent_category": intent_category,
+            "emphasis_level": self._determine_emphasis_level(message_intent),
+            "audience_focus": self._determine_audience_focus(message_intent),
+            "communication_goal": self._determine_communication_goal(message_intent),
+        }
+
+    def _generate_layout_recommendations(
+        self,
+        content_analysis: Dict[str, Any],
+        intent_analysis: Dict[str, Any],
+        presentation_context: Optional[Dict] = None,
+    ) -> List[LayoutRecommendation]:
+        """Generate ranked layout recommendations based on content and intent analysis."""
+        recommendations = []
+
+        content_type = content_analysis["content_type"]
+        intent_category = intent_analysis["intent_category"]
+        distinct_elements = content_analysis["distinct_elements"]
+
+        # Apply layout intelligence rules
+        if content_type == "comparison" or intent_category == "comparison":
+            if distinct_elements == 2:
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Comparison",
+                        0.95,
+                        "Two distinct elements perfect for side-by-side comparison",
+                        "head-to-head comparisons and before/after scenarios",
+                    )
+                )
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Two Content",
+                        0.80,
+                        "Alternative two-column layout for comparison content",
+                        "detailed side-by-side content with more text",
+                    )
+                )
+            elif 3 <= distinct_elements <= 4:
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Four Columns",
+                        0.90,
+                        f"{distinct_elements} elements ideal for structured comparison grid",
+                        "feature matrices and multi-factor comparisons",
+                    )
+                )
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Comparison",
+                        0.70,
+                        "Simplified two-way comparison focusing on main contrasts",
+                        "high-level comparison without detailed breakdown",
+                    )
+                )
+
+        elif content_type == "metrics_data" or intent_category == "data_presentation":
+            if content_analysis["data_elements"] >= 3:
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Four Columns",
+                        0.85,
+                        "Multiple metrics benefit from structured grid presentation",
+                        "KPI dashboards and performance metrics",
+                    )
+                )
+            recommendations.append(
+                LayoutRecommendation(
+                    "Title and Content",
+                    0.75,
+                    "Traditional layout works well for data with explanatory text",
+                    "metrics with context and analysis",
+                )
+            )
+
+        elif content_type == "structured_list":
+            if 3 <= distinct_elements <= 4:
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Four Columns",
+                        0.88,
+                        "List structure maps well to column-based presentation",
+                        "feature lists and categorized information",
+                    )
+                )
+            recommendations.append(
+                LayoutRecommendation(
+                    "Title and Content",
+                    0.85,
+                    "Classic bulleted list presentation",
+                    "traditional content delivery with clear hierarchy",
+                )
+            )
+            if distinct_elements == 2:
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Two Content",
+                        0.80,
+                        "Two main topics work well in side-by-side layout",
+                        "dual-topic presentations",
+                    )
+                )
+
+        elif content_type == "process_timeline":
+            recommendations.append(
+                LayoutRecommendation(
+                    "Four Columns",
+                    0.80,
+                    "Process steps map well to sequential columns",
+                    "step-by-step processes and timelines",
+                )
+            )
+            recommendations.append(
+                LayoutRecommendation(
+                    "Title and Content",
+                    0.75,
+                    "Sequential list format for process explanation",
+                    "detailed process documentation",
+                )
+            )
+
+        else:  # narrative_text or general
+            recommendations.append(
+                LayoutRecommendation(
+                    "Title and Content",
+                    0.85,
+                    "Standard layout ideal for narrative and explanatory content",
+                    "general information and detailed explanations",
+                )
+            )
+            if intent_category == "overview":
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Section Header",
+                        0.70,
+                        "High-level overview content works as section divider",
+                        "topic introductions and agenda items",
+                    )
+                )
+
+        # Add fallback recommendations if none were generated
+        if not recommendations:
+            recommendations.append(
+                LayoutRecommendation(
+                    "Title and Content",
+                    0.70,
+                    "Default layout suitable for most content types",
+                    "general content presentation and information delivery",
+                )
+            )
+            if content_analysis["has_comparison"]:
+                recommendations.append(
+                    LayoutRecommendation(
+                        "Comparison",
+                        0.65,
+                        "Content contains comparison elements",
+                        "side-by-side comparisons and contrasts",
+                    )
+                )
+
+        # Sort by confidence score
+        recommendations.sort(key=lambda x: x.confidence, reverse=True)
+
+        # Return top 3 recommendations
+        return recommendations[:3]
+
+    def _generate_content_suggestions(
+        self,
+        content_analysis: Dict[str, Any],
+        intent_analysis: Dict[str, Any],
+        layout_recommendations: List[LayoutRecommendation],
+    ) -> Dict[str, Any]:
+        """Generate content structuring and presentation suggestions."""
+        primary_layout = layout_recommendations[0] if layout_recommendations else None
+
+        if not primary_layout:
+            return {}
+
+        # Generate suggestions based on recommended layout
+        if primary_layout.layout == "Four Columns":
+            return {
+                "primary_message": "Structured comparison or categorized information",
+                "supporting_details": [
+                    "distinct categories",
+                    "balanced content distribution",
+                    "clear labels",
+                ],
+                "recommended_structure": "title + categorized columns with headers",
+                "visual_approach": "balanced grid with consistent formatting",
+            }
+        elif primary_layout.layout == "Comparison":
+            return {
+                "primary_message": "Side-by-side comparison highlighting key differences",
+                "supporting_details": [
+                    "contrasting elements",
+                    "clear distinctions",
+                    "decision factors",
+                ],
+                "recommended_structure": "title + left vs right comparison",
+                "visual_approach": "clear visual separation with balanced content",
+            }
+        elif primary_layout.layout == "Two Content":
+            return {
+                "primary_message": "Dual-topic presentation with equal emphasis",
+                "supporting_details": [
+                    "complementary topics",
+                    "balanced detail level",
+                    "related themes",
+                ],
+                "recommended_structure": "title + two main content areas",
+                "visual_approach": "side-by-side layout with clear separation",
+            }
+        else:  # Title and Content or others
+            return {
+                "primary_message": "Structured information with clear hierarchy",
+                "supporting_details": ["main points", "supporting details", "logical flow"],
+                "recommended_structure": "title + bulleted or paragraph content",
+                "visual_approach": "traditional layout with clear visual hierarchy",
+            }
+
+    def _generate_structured_frontmatter_preview(
+        self,
+        layout_recommendations: List[LayoutRecommendation],
+        content_piece: str,
+        message_intent: str,
+    ) -> Dict[str, Any]:
+        """Generate structured frontmatter preview for the recommended layout."""
+        if not layout_recommendations:
+            return {}
+
+        primary_layout = layout_recommendations[0].layout
+
+        # Generate title from content or intent
+        title = self._extract_title_from_content(content_piece, message_intent)
+
+        if primary_layout == "Four Columns":
+            return {
+                "preferred_format": "Four Columns",
+                "yaml_preview": f"""layout: Four Columns
+title: {title}
+columns:
+  - title: Category 1
+    content: "Key information for first category"
+  - title: Category 2
+    content: "Key information for second category"
+  - title: Category 3
+    content: "Key information for third category"
+  - title: Category 4
+    content: "Key information for fourth category" """,
+                "placeholder_mapping": {
+                    "Title 1": title,
+                    "Col 1 Title": "Category 1",
+                    "Col 2 Title": "Category 2",
+                    "Col 3 Title": "Category 3",
+                    "Col 4 Title": "Category 4",
+                },
+            }
+        elif primary_layout == "Comparison":
+            return {
+                "preferred_format": "Comparison",
+                "yaml_preview": f"""layout: Comparison
+title: {title}
+comparison:
+  left:
+    title: Option A
+    content: "Benefits and characteristics of first option"
+  right:
+    title: Option B
+    content: "Benefits and characteristics of second option" """,
+                "placeholder_mapping": {
+                    "Title 1": title,
+                    "Text Placeholder 2": "Option A",
+                    "Text Placeholder 4": "Option B",
+                },
+            }
+        else:
+            return {
+                "preferred_format": primary_layout,
+                "yaml_preview": f"""layout: {primary_layout}
+title: {title}
+content: |
+  - Key point from your content
+  - Supporting information
+  - Additional details""",
+                "placeholder_mapping": {
+                    "Title 1": title,
+                    "Content Placeholder 2": "Your content here",
+                },
+            }
+
+    def _count_distinct_elements(self, content: str) -> int:
+        """Count distinct content elements that could map to separate layout areas."""
+        # Look for bullet points, numbered lists, or natural separators
+        bullet_count = len(re.findall(r"[-*•]\s+", content))
+        number_list_count = len(re.findall(r"\d+\.\s+", content))
+        paragraph_count = len([p for p in content.split("\n\n") if p.strip()])
+
+        # Special handling for comparison content
+        if any(word in content.lower() for word in ["vs", "versus", "compared to", "against"]):
+            # For comparisons, assume at least 2 elements being compared
+            return max(2, bullet_count, number_list_count, min(paragraph_count, 4))
+
+        # For lists, count actual items
+        if bullet_count > 0:
+            return bullet_count
+        elif number_list_count > 0:
+            return number_list_count
+
+        # Check for comma-separated lists (like "feature1, feature2, feature3, and feature4")
+        comma_separated = [item.strip() for item in content.split(",") if item.strip()]
+        if len(comma_separated) >= 3:
+            return min(len(comma_separated), 4)
+
+        # Check for colon-separated lists (like "feature1: description, feature2: description")
+        colon_separated = len(re.findall(r"[^:]+:", content))
+        if colon_separated >= 2:
+            return min(colon_separated, 4)
+
+        # For paragraph content, minimum of 1, maximum of 4
+        return max(1, min(paragraph_count, 4))
+
+    def _determine_structure_pattern(self, content: str) -> str:
+        """Determine the structural pattern of the content."""
+        if re.search(r"[-*•]\s+.*[-*•]\s+", content):
+            return "bulleted_list"
+        elif re.search(r"\d+\.\s+.*\d+\.\s+", content):
+            return "numbered_list"
+        elif content.count("\n\n") >= 2:
+            return "paragraph_blocks"
+        else:
+            return "continuous_text"
+
+    def _determine_visual_emphasis(self, content: str, content_type: str) -> str:
+        """Determine what visual emphasis would work best."""
+        if content_type == "comparison":
+            return "balanced_comparison"
+        elif content_type == "metrics_data":
+            return "data_focused"
+        elif content_type == "process_timeline":
+            return "sequential_flow"
+        else:
+            return "content_hierarchy"
+
+    def _determine_emphasis_level(self, message_intent: str) -> str:
+        """Determine how much visual emphasis is needed."""
+        intent_lower = message_intent.lower()
+        if any(word in intent_lower for word in ["critical", "important", "key", "highlight"]):
+            return "high"
+        elif any(word in intent_lower for word in ["show", "present", "explain"]):
+            return "medium"
+        else:
+            return "standard"
+
+    def _determine_audience_focus(self, message_intent: str) -> str:
+        """Determine audience consideration from intent."""
+        intent_lower = message_intent.lower()
+        if any(word in intent_lower for word in ["executive", "board", "leadership"]):
+            return "executive"
+        elif any(word in intent_lower for word in ["technical", "detail", "implementation"]):
+            return "technical"
+        else:
+            return "general"
+
+    def _determine_communication_goal(self, message_intent: str) -> str:
+        """Determine the primary communication goal."""
+        intent_lower = message_intent.lower()
+        if any(word in intent_lower for word in ["decide", "choose", "recommend"]):
+            return "decision_support"
+        elif any(word in intent_lower for word in ["understand", "explain", "clarify"]):
+            return "comprehension"
+        elif any(word in intent_lower for word in ["convince", "persuade", "sell"]):
+            return "persuasion"
+        else:
+            return "information_sharing"
+
+    def _extract_title_from_content(self, content_piece: str, message_intent: str) -> str:
+        """Extract or generate an appropriate title from content and intent."""
+        # Try to extract from first line if it looks like a title
+        first_line = content_piece.split("\n")[0].strip()
+        if len(first_line) < 60 and not first_line.endswith("."):
+            return first_line
+
+        # Generate from message intent
+        intent_words = message_intent.split()[:3]
+        if intent_words:
+            return " ".join(word.capitalize() for word in intent_words)
+
+        # Fallback
+        return "Content Overview"
+
+    def _build_layout_intelligence(self) -> Dict[str, Any]:
+        """Build the layout intelligence mapping for content-to-layout recommendations."""
+        return {
+            "comparison_layouts": ["Comparison", "Two Content", "Four Columns"],
+            "data_layouts": ["Four Columns", "Title and Content"],
+            "list_layouts": ["Title and Content", "Four Columns", "Two Content"],
+            "process_layouts": ["Four Columns", "Title and Content", "Two Content"],
+            "narrative_layouts": ["Title and Content", "Section Header"],
+        }
+
+    def _get_available_layouts(self) -> List[str]:
+        """Get list of currently available PowerPoint layouts."""
+        return [
+            "Title Slide",
+            "Title and Content",
+            "Section Header",
+            "Two Content",
+            "Comparison",
+            "Title Only",
+            "Blank",
+            "Content with Caption",
+            "Picture with Caption",
+            "Four Columns",
+        ]
+
+
+# Helper function for easy import
+def recommend_slide_approach(
+    content_piece: str, message_intent: str, presentation_context: Optional[Dict] = None
+) -> Dict[str, Any]:
+    """
+    Convenience function for getting slide layout recommendations.
+
+    Args:
+        content_piece: Specific content to present
+        message_intent: What they want this content to communicate
+        presentation_context: Optional context from analyze_presentation_needs()
+
+    Returns:
+        Dictionary with layout recommendations and content suggestions
+    """
+    engine = LayoutRecommendationEngine()
+    return engine.recommend_slide_approach(content_piece, message_intent, presentation_context)