inventory

Imported skill inventory from anthropic

SKILL.md

GitHub

#!/usr/bin/env python3 """ Extract structured text content from PowerPoint presentations.

This module provides functionality to:

  • Extract all text content from PowerPoint shapes
  • Preserve paragraph formatting (alignment, bullets, fonts, spacing)
  • Handle nested GroupShapes recursively with correct absolute positions
  • Sort shapes by visual position on slides
  • Filter out slide numbers and non-content placeholders
  • Export to JSON with clean, structured data

Classes: ParagraphData: Represents a text paragraph with formatting ShapeData: Represents a shape with position and text content

Main Functions: extract_text_inventory: Extract all text from a presentation save_inventory: Save extracted data to JSON

Usage: python inventory.py input.pptx output.json """

import argparse import json import platform import sys from dataclasses import dataclass from pathlib import Path from typing import Any, Dict, List, Optional, Tuple, Union

from PIL import Image, ImageDraw, ImageFont from pptx import Presentation from pptx.enum.text import PP_ALIGN from pptx.shapes.base import BaseShape

Type aliases for cleaner signatures

JsonValue = Union[str, int, float, bool, None] ParagraphDict = Dict[str, JsonValue] ShapeDict = Dict[ str, Union[str, float, bool, List[ParagraphDict], List[str], Dict[str, Any], None] ] InventoryData = Dict[ str, Dict[str, "ShapeData"] ] # Dict of slide_id -> {shape_id -> ShapeData} InventoryDict = Dict[str, Dict[str, ShapeDict]] # JSON-serializable inventory

def main(): """Main entry point for command-line usage.""" parser = argparse.ArgumentParser( description="Extract text inventory from PowerPoint with proper GroupShape support.", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" Examples: python inventory.py presentation.pptx inventory.json Extracts text inventory with correct absolute positions for grouped shapes

python inventory.py presentation.pptx inventory.json --issues-only Extracts only text shapes that have overflow or overlap issues

The output JSON includes:

  • All text content organized by slide and shape

  • Correct absolute positions for shapes in groups

  • Visual position and size in inches

  • Paragraph properties and formatting

  • Issue detection: text overflow and shape overlaps """, )

    parser.add_argument("input", help="Input PowerPoint file (.pptx)") parser.add_argument("output", help="Output JSON file for inventory") parser.add_argument( "--issues-only", action="store_true", help="Include only text shapes that have overflow or overlap issues", )

    args = parser.parse_args()

    input_path = Path(args.input) if not input_path.exists(): print(f"Error: Input file not found: {args.input}") sys.exit(1) if not input_path.suffix.lower() == ".pptx": print("Error: Input must be a PowerPoint file (.pptx)") sys.exit(1) try: print(f"Extracting text inventory from: {args.input}") if args.issues_only: print( "Filtering to include only text shapes with issues (overflow/overlap)" ) inventory = extract_text_inventory(input_path, issues_only=args.issues_only) output_path = Path(args.output) output_path.parent.mkdir(parents=True, exist_ok=True) save_inventory(inventory, output_path) print(f"Output saved to: {args.output}") # Report statistics total_slides = len(inventory) total_shapes = sum(len(shapes) for shapes in inventory.values()) if args.issues_only: if total_shapes > 0: print( f"Found {total_shapes} text elements with issues in {total_slides} slides" ) else: print("No issues discovered") else: print( f"Found text in {total_slides} slides with {total_shapes} text elements" ) except Exception as e: print(f"Error processing presentation: {e}") import traceback traceback.print_exc() sys.exit(1)

@dataclass class ShapeWithPosition: """A shape with its absolute position on the slide."""

shape: BaseShape
absolute_left: int  # in EMUs
absolute_top: int  # in EMUs

class ParagraphData: """Data structure for paragraph properties extracted from a PowerPoint paragraph."""

def __init__(self, paragraph: Any):
    """Initialize from a PowerPoint paragraph object.

    Args:
        paragraph: The PowerPoint paragraph object
    """
    self.text: str = paragraph.text.strip()
    self.bullet: bool = False
    self.level: Optional[int] = None
    self.alignment: Optional[str] = None
    self.space_before: Optional[float] = None
    self.space_after: Optional[float] = None
    self.font_name: Optional[str] = None
    self.font_size: Optional[float] = None
    self.bold: Optional[bool] = None
    self.italic: Optional[bool] = None
    self.underline: Optional[bool] = None
    self.color: Optional[str] = None
    self.theme_color: Optional[str] = None
    self.line_spacing: Optional[float] = None

    # Check for bullet formatting
    if (
        hasattr(paragraph, "_p")
        and paragraph._p is not None
        and paragraph._p.pPr is not None
    ):
        pPr = paragraph._p.pPr
        ns = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
        if (
            pPr.find(f"{ns}buChar") is not None
            or pPr.find(f"{ns}buAutoNum") is not None
        ):
            self.bullet = True
            if hasattr(paragraph, "level"):
                self.level = paragraph.level

    # Add alignment if not LEFT (default)
    if hasattr(paragraph, "alignment") and paragraph.alignment is not None:
        alignment_map = {
            PP_ALIGN.CENTER: "CENTER",
            PP_ALIGN.RIGHT: "RIGHT",
            PP_ALIGN.JUSTIFY: "JUSTIFY",
        }
        if paragraph.alignment in alignment_map:
            self.alignment = alignment_map[paragraph.alignment]

    # Add spacing properties if set
    if hasattr(paragraph, "space_before") and paragraph.space_before:
        self.space_before = paragraph.space_before.pt
    if hasattr(paragraph, "space_after") and paragraph.space_after:
        self.space_after = paragraph.space_after.pt

    # Extract font properties from first run
    if paragraph.runs:
        first_run = paragraph.runs[0]
        if hasattr(first_run, "font"):
            font = first_run.font
            if font.name:
                self.font_name = font.name
            if font.size:
                self.font_size = font.size.pt
            if font.bold is not None:
                self.bold = font.bold
            if font.italic is not None:
                self.italic = font.italic
            if font.underline is not None:
                self.underline = font.underline

            # Handle color - both RGB and theme colors
            try:
                # Try RGB color first
                if font.color.rgb:
                    self.color = str(font.color.rgb)
            except (AttributeError, TypeError):
                # Fall back to theme color
                try:
                    if font.color.theme_color:
                        self.theme_color = font.color.theme_color.name
                except (AttributeError, TypeError):
                    pass

    # Add line spacing if set
    if hasattr(paragraph, "line_spacing") and paragraph.line_spacing is not None:
        if hasattr(paragraph.line_spacing, "pt"):
            self.line_spacing = round(paragraph.line_spacing.pt, 2)
        else:
            # Multiplier - convert to points
            font_size = self.font_size if self.font_size else 12.0
            self.line_spacing = round(paragraph.line_spacing * font_size, 2)

def to_dict(self) -> ParagraphDict:
    """Convert to dictionary for JSON serialization, excluding None values."""
    result: ParagraphDict = {"text": self.text}

    # Add optional fields only if they have values
    if self.bullet:
        result["bullet"] = self.bullet
    if self.level is not None:
        result["level"] = self.level
    if self.alignment:
        result["alignment"] = self.alignment
    if self.space_before is not None:
        result["space_before"] = self.space_before
    if self.space_after is not None:
        result["space_after"] = self.space_after
    if self.font_name:
        result["font_name"] = self.font_name
    if self.font_size is not None:
        result["font_size"] = self.font_size
    if self.bold is not None:
        result["bold"] = self.bold
    if self.italic is not None:
        result["italic"] = self.italic
    if self.underline is not None:
        result["underline"] = self.underline
    if self.color:
        result["color"] = self.color
    if self.theme_color:
        result["theme_color"] = self.theme_color
    if self.line_spacing is not None:
        result["line_spacing"] = self.line_spacing

    return result

class ShapeData: """Data structure for shape properties extracted from a PowerPoint shape."""

@staticmethod
def emu_to_inches(emu: int) -> float:
    """Convert EMUs (English Metric Units) to inches."""
    return emu / 914400.0

@staticmethod
def inches_to_pixels(inches: float, dpi: int = 96) -> int:
    """Convert inches to pixels at given DPI."""
    return int(inches * dpi)

@staticmethod
def get_font_path(font_name: str) -> Optional[str]:
    """Get the font file path for a given font name.

    Args:
        font_name: Name of the font (e.g., 'Arial', 'Calibri')

    Returns:
        Path to the font file, or None if not found
    """
    system = platform.system()

    # Common font file variations to try
    font_variations = [
        font_name,
        font_name.lower(),
        font_name.replace(" ", ""),
        font_name.replace(" ", "-"),
    ]

    # Define font directories and extensions by platform
    if system == "Darwin":  # macOS
        font_dirs = [
            "/System/Library/Fonts/",
            "/Library/Fonts/",
            "~/Library/Fonts/",
        ]
        extensions = [".ttf", ".otf", ".ttc", ".dfont"]
    else:  # Linux
        font_dirs = [
            "/usr/share/fonts/truetype/",
            "/usr/local/share/fonts/",
            "~/.fonts/",
        ]
        extensions = [".ttf", ".otf"]

    # Try to find the font file
    from pathlib import Path

    for font_dir in font_dirs:
        font_dir_path = Path(font_dir).expanduser()
        if not font_dir_path.exists():
            continue

        # First try exact matches
        for variant in font_variations:
            for ext in extensions:
                font_path = font_dir_path / f"{variant}{ext}"
                if font_path.exists():
                    return str(font_path)

        # Then try fuzzy matching - find files containing the font name
        try:
            for file_path in font_dir_path.iterdir():
                if file_path.is_file():
                    file_name_lower = file_path.name.lower()
                    font_name_lower = font_name.lower().replace(" ", "")
                    if font_name_lower in file_name_lower and any(
                        file_name_lower.endswith(ext) for ext in extensions
                    ):
                        return str(file_path)
        except (OSError, PermissionError):
            continue

    return None

@staticmethod
def get_slide_dimensions(slide: Any) -> tuple[Optional[int], Optional[int]]:
    """Get slide dimensions from slide object.

    Args:
        slide: Slide object

    Returns:
        Tuple of (width_emu, height_emu) or (None, None) if not found
    """
    try:
        prs = slide.part.package.presentation_part.presentation
        return prs.slide_width, prs.slide_height
    except (AttributeError, TypeError):
        return None, None

@staticmethod
def get_default_font_size(shape: BaseShape, slide_layout: Any) -> Optional[float]:
    """Extract default font size from slide layout for a placeholder shape.

    Args:
        shape: Placeholder shape
        slide_layout: Slide layout containing the placeholder definition

    Returns:
        Default font size in points, or None if not found
    """
    try:
        if not hasattr(shape, "placeholder_format"):
            return None

        shape_type = shape.placeholder_format.type  # type: ignore
        for layout_placeholder in slide_layout.placeholders:
            if layout_placeholder.placeholder_format.type == shape_type:
                # Find first defRPr element with sz (size) attribute
                for elem in layout_placeholder.element.iter():
                    if "defRPr" in elem.tag and (sz := elem.get("sz")):
                        return float(sz) / 100.0  # Convert EMUs to points
                break
    except Exception:
        pass
    return None

def __init__(
    self,
    shape: BaseShape,
    absolute_left: Optional[int] = None,
    absolute_top: Optional[int] = None,
    slide: Optional[Any] = None,
):
    """Initialize from a PowerPoint shape object.

    Args:
        shape: The PowerPoint shape object (should be pre-validated)
        absolute_left: Absolute left position in EMUs (for shapes in groups)
        absolute_top: Absolute top position in EMUs (for shapes in groups)
        slide: Optional slide object to get dimensions and layout information
    """
    self.shape = shape  # Store reference to original shape
    self.shape_id: str = ""  # Will be set after sorting

    # Get slide dimensions from slide object
    self.slide_width_emu, self.slide_height_emu = (
        self.get_slide_dimensions(slide) if slide else (None, None)
    )

    # Get placeholder type if applicable
    self.placeholder_type: Optional[str] = None
    self.default_font_size: Optional[float] = None
    if hasattr(shape, "is_placeholder") and shape.is_placeholder:  # type: ignore
        if shape.placeholder_format and shape.placeholder_format.type:  # type: ignore
            self.placeholder_type = (
                str(shape.placeholder_format.type).split(".")[-1].split(" ")[0]  # type: ignore
            )

            # Get default font size from layout
            if slide and hasattr(slide, "slide_layout"):
                self.default_font_size = self.get_default_font_size(
                    shape, slide.slide_layout
                )

    # Get position information
    # Use absolute positions if provided (for shapes in groups), otherwise use shape's position
    left_emu = (
        absolute_left
        if absolute_left is not None
        else (shape.left if hasattr(shape, "left") else 0)
    )
    top_emu = (
        absolute_top
        if absolute_top is not None
        else (shape.top if hasattr(shape, "top") else 0)
    )

    self.left: float = round(self.emu_to_inches(left_emu), 2)  # type: ignore
    self.top: float = round(self.emu_to_inches(top_emu), 2)  # type: ignore
    self.width: float = round(
        self.emu_to_inches(shape.width if hasattr(shape, "width") else 0),
        2,  # type: ignore
    )
    self.height: float = round(
        self.emu_to_inches(shape.height if hasattr(shape, "height") else 0),
        2,  # type: ignore
    )

    # Store EMU positions for overflow calculations
    self.left_emu = left_emu
    self.top_emu = top_emu
    self.width_emu = shape.width if hasattr(shape, "width") else 0
    self.height_emu = shape.height if hasattr(shape, "height") else 0

    # Calculate overflow status
    self.frame_overflow_bottom: Optional[float] = None
    self.slide_overflow_right: Optional[float] = None
    self.slide_overflow_bottom: Optional[float] = None
    self.overlapping_shapes: Dict[
        str, float
    ] = {}  # Dict of shape_id -> overlap area in sq inches
    self.warnings: List[str] = []
    self._estimate_frame_overflow()
    self._calculate_slide_overflow()
    self._detect_bullet_issues()

@property
def paragraphs(self) -> List[ParagraphData]:
    """Calculate paragraphs from the shape's text frame."""
    if not self.shape or not hasattr(self.shape, "text_frame"):
        return []

    paragraphs = []
    for paragraph in self.shape.text_frame.paragraphs:  # type: ignore
        if paragraph.text.strip():
            paragraphs.append(ParagraphData(paragraph))
    return paragraphs

def _get_default_font_size(self) -> int:
    """Get default font size from theme text styles or use conservative default."""
    try:
        if not (
            hasattr(self.shape, "part") and hasattr(self.shape.part, "slide_layout")
        ):
            return 14

        slide_master = self.shape.part.slide_layout.slide_master  # type: ignore
        if not hasattr(slide_master, "element"):
            return 14

        # Determine theme style based on placeholder type
        style_name = "bodyStyle"  # Default
        if self.placeholder_type and "TITLE" in self.placeholder_type:
            style_name = "titleStyle"

        # Find font size in theme styles
        for child in slide_master.element.iter():
            tag = child.tag.split("}")[-1] if "}" in child.tag else child.tag
            if tag == style_name:
                for elem in child.iter():
                    if "sz" in elem.attrib:
                        return int(elem.attrib["sz"]) // 100
    except Exception:
        pass

    return 14  # Conservative default for body text

def _get_usable_dimensions(self, text_frame) -> Tuple[int, int]:
    """Get usable width and height in pixels after accounting for margins."""
    # Default PowerPoint margins in inches
    margins = {"top": 0.05, "bottom": 0.05, "left": 0.1, "right": 0.1}

    # Override with actual margins if set
    if hasattr(text_frame, "margin_top") and text_frame.margin_top:
        margins["top"] = self.emu_to_inches(text_frame.margin_top)
    if hasattr(text_frame, "margin_bottom") and text_frame.margin_bottom:
        margins["bottom"] = self.emu_to_inches(text_frame.margin_bottom)
    if hasattr(text_frame, "margin_left") and text_frame.margin_left:
        margins["left"] = self.emu_to_inches(text_frame.margin_left)
    if hasattr(text_frame, "margin_right") and text_frame.margin_right:
        margins["right"] = self.emu_to_inches(text_frame.margin_right)

    # Calculate usable area
    usable_width = self.width - margins["left"] - margins["right"]
    usable_height = self.height - margins["top"] - margins["bottom"]

    # Convert to pixels
    return (
        self.inches_to_pixels(usable_width),
        self.inches_to_pixels(usable_height),
    )

def _wrap_text_line(self, line: str, max_width_px: int, draw, font) -> List[str]:
    """Wrap a single line of text to fit within max_width_px."""
    if not line:
        return [""]

    # Use textlength for efficient width calculation
    if draw.textlength(line, font=font) <= max_width_px:
        return [line]

    # Need to wrap - split into words
    wrapped = []
    words = line.split(" ")
    current_line = ""

    for word in words:
        test_line = current_line + (" " if current_line else "") + word
        if draw.textlength(test_line, font=font) <= max_width_px:
            current_line = test_line
        else:
            if current_line:
                wrapped.append(current_line)
            current_line = word

    if current_line:
        wrapped.append(current_line)

    return wrapped

def _estimate_frame_overflow(self) -> None:
    """Estimate if text overflows the shape bounds using PIL text measurement."""
    if not self.shape or not hasattr(self.shape, "text_frame"):
        return

    text_frame = self.shape.text_frame  # type: ignore
    if not text_frame or not text_frame.paragraphs:
        return

    # Get usable dimensions after accounting for margins
    usable_width_px, usable_height_px = self._get_usable_dimensions(text_frame)
    if usable_width_px <= 0 or usable_height_px <= 0:
        return

    # Set up PIL for text measurement
    dummy_img = Image.new("RGB", (1, 1))
    draw = ImageDraw.Draw(dummy_img)

    # Get default font size from placeholder or use conservative estimate
    default_font_size = self._get_default_font_size()

    # Calculate total height of all paragraphs
    total_height_px = 0

    for para_idx, paragraph in enumerate(text_frame.paragraphs):
        if not paragraph.text.strip():
            continue

        para_data = ParagraphData(paragraph)

        # Load font for this paragraph
        font_name = para_data.font_name or "Arial"
        font_size = int(para_data.font_size or default_font_size)

        font = None
        font_path = self.get_font_path(font_name)
        if font_path:
            try:
                font = ImageFont.truetype(font_path, size=font_size)
            except Exception:
                font = ImageFont.load_default()
        else:
            font = ImageFont.load_default()

        # Wrap all lines in this paragraph
        all_wrapped_lines = []
        for line in paragraph.text.split("\n"):
            wrapped = self._wrap_text_line(line, usable_width_px, draw, font)
            all_wrapped_lines.extend(wrapped)

        if all_wrapped_lines:
            # Calculate line height
            if para_data.line_spacing:
                # Custom line spacing explicitly set
                line_height_px = para_data.line_spacing * 96 / 72
            else:
                # PowerPoint default single spacing (1.0x font size)
                line_height_px = font_size * 96 / 72

            # Add space_before (except first paragraph)
            if para_idx > 0 and para_data.space_before:
                total_height_px += para_data.space_before * 96 / 72

            # Add paragraph text height
            total_height_px += len(all_wrapped_lines) * line_height_px

            # Add space_after
            if para_data.space_after:
                total_height_px += para_data.space_after * 96 / 72

    # Check for overflow (ignore negligible overflows <= 0.05")
    if total_height_px > usable_height_px:
        overflow_px = total_height_px - usable_height_px
        overflow_inches = round(overflow_px / 96.0, 2)
        if overflow_inches > 0.05:  # Only report significant overflows
            self.frame_overflow_bottom = overflow_inches

def _calculate_slide_overflow(self) -> None:
    """Calculate if shape overflows the slide boundaries."""
    if self.slide_width_emu is None or self.slide_height_emu is None:
        return

    # Check right overflow (ignore negligible overflows <= 0.01")
    right_edge_emu = self.left_emu + self.width_emu
    if right_edge_emu > self.slide_width_emu:
        overflow_emu = right_edge_emu - self.slide_width_emu
        overflow_inches = round(self.emu_to_inches(overflow_emu), 2)
        if overflow_inches > 0.01:  # Only report significant overflows
            self.slide_overflow_right = overflow_inches

    # Check bottom overflow (ignore negligible overflows <= 0.01")
    bottom_edge_emu = self.top_emu + self.height_emu
    if bottom_edge_emu > self.slide_height_emu:
        overflow_emu = bottom_edge_emu - self.slide_height_emu
        overflow_inches = round(self.emu_to_inches(overflow_emu), 2)
        if overflow_inches > 0.01:  # Only report significant overflows
            self.slide_overflow_bottom = overflow_inches

def _detect_bullet_issues(self) -> None:
    """Detect bullet point formatting issues in paragraphs."""
    if not self.shape or not hasattr(self.shape, "text_frame"):
        return

    text_frame = self.shape.text_frame  # type: ignore
    if not text_frame or not text_frame.paragraphs:
        return

    # Common bullet symbols that indicate manual bullets
    bullet_symbols = ["•", "●", "○"]

    for paragraph in text_frame.paragraphs:
        text = paragraph.text.strip()
        # Check for manual bullet symbols
        if text and any(text.startswith(symbol + " ") for symbol in bullet_symbols):
            self.warnings.append(
                "manual_bullet_symbol: use proper bullet formatting"
            )
            break

@property
def has_any_issues(self) -> bool:
    """Check if shape has any issues (overflow, overlap, or warnings)."""
    return (
        self.frame_overflow_bottom is not None
        or self.slide_overflow_right is not None
        or self.slide_overflow_bottom is not None
        or len(self.overlapping_shapes) > 0
        or len(self.warnings) > 0
    )

def to_dict(self) -> ShapeDict:
    """Convert to dictionary for JSON serialization."""
    result: ShapeDict = {
        "left": self.left,
        "top": self.top,
        "width": self.width,
        "height": self.height,
    }

    # Add optional fields if present
    if self.placeholder_type:
        result["placeholder_type"] = self.placeholder_type

    if self.default_font_size:
        result["default_font_size"] = self.default_font_size

    # Add overflow information only if there is overflow
    overflow_data = {}

    # Add frame overflow if present
    if self.frame_overflow_bottom is not None:
        overflow_data["frame"] = {"overflow_bottom": self.frame_overflow_bottom}

    # Add slide overflow if present
    slide_overflow = {}
    if self.slide_overflow_right is not None:
        slide_overflow["overflow_right"] = self.slide_overflow_right
    if self.slide_overflow_bottom is not None:
        slide_overflow["overflow_bottom"] = self.slide_overflow_bottom
    if slide_overflow:
        overflow_data["slide"] = slide_overflow

    # Only add overflow field if there is overflow
    if overflow_data:
        result["overflow"] = overflow_data

    # Add overlap field if there are overlapping shapes
    if self.overlapping_shapes:
        result["overlap"] = {"overlapping_shapes": self.overlapping_shapes}

    # Add warnings field if there are warnings
    if self.warnings:
        result["warnings"] = self.warnings

    # Add paragraphs after placeholder_type
    result["paragraphs"] = [para.to_dict() for para in self.paragraphs]

    return result

def is_valid_shape(shape: BaseShape) -> bool: """Check if a shape contains meaningful text content.""" # Must have a text frame with content if not hasattr(shape, "text_frame") or not shape.text_frame: # type: ignore return False

text = shape.text_frame.text.strip()  # type: ignore
if not text:
    return False

# Skip slide numbers and numeric footers
if hasattr(shape, "is_placeholder") and shape.is_placeholder:  # type: ignore
    if shape.placeholder_format and shape.placeholder_format.type:  # type: ignore
        placeholder_type = (
            str(shape.placeholder_format.type).split(".")[-1].split(" ")[0]  # type: ignore
        )
        if placeholder_type == "SLIDE_NUMBER":
            return False
        if placeholder_type == "FOOTER" and text.isdigit():
            return False

return True

def collect_shapes_with_absolute_positions( shape: BaseShape, parent_left: int = 0, parent_top: int = 0 ) -> List[ShapeWithPosition]: """Recursively collect all shapes with valid text, calculating absolute positions.

For shapes within groups, their positions are relative to the group.
This function calculates the absolute position on the slide by accumulating
parent group offsets.

Args:
    shape: The shape to process
    parent_left: Accumulated left offset from parent groups (in EMUs)
    parent_top: Accumulated top offset from parent groups (in EMUs)

Returns:
    List of ShapeWithPosition objects with absolute positions
"""
if hasattr(shape, "shapes"):  # GroupShape
    result = []
    # Get this group's position
    group_left = shape.left if hasattr(shape, "left") else 0
    group_top = shape.top if hasattr(shape, "top") else 0

    # Calculate absolute position for this group
    abs_group_left = parent_left + group_left
    abs_group_top = parent_top + group_top

    # Process children with accumulated offsets
    for child in shape.shapes:  # type: ignore
        result.extend(
            collect_shapes_with_absolute_positions(
                child, abs_group_left, abs_group_top
            )
        )
    return result

# Regular shape - check if it has valid text
if is_valid_shape(shape):
    # Calculate absolute position
    shape_left = shape.left if hasattr(shape, "left") else 0
    shape_top = shape.top if hasattr(shape, "top") else 0

    return [
        ShapeWithPosition(
            shape=shape,
            absolute_left=parent_left + shape_left,
            absolute_top=parent_top + shape_top,
        )
    ]

return []

def sort_shapes_by_position(shapes: List[ShapeData]) -> List[ShapeData]: """Sort shapes by visual position (top-to-bottom, left-to-right).

Shapes within 0.5 inches vertically are considered on the same row.
"""
if not shapes:
    return shapes

# Sort by top position first
shapes = sorted(shapes, key=lambda s: (s.top, s.left))

# Group shapes by row (within 0.5 inches vertically)
result = []
row = [shapes[0]]
row_top = shapes[0].top

for shape in shapes[1:]:
    if abs(shape.top - row_top) <= 0.5:
        row.append(shape)
    else:
        # Sort current row by left position and add to result
        result.extend(sorted(row, key=lambda s: s.left))
        row = [shape]
        row_top = shape.top

# Don't forget the last row
result.extend(sorted(row, key=lambda s: s.left))
return result

def calculate_overlap( rect1: Tuple[float, float, float, float], rect2: Tuple[float, float, float, float], tolerance: float = 0.05, ) -> Tuple[bool, float]: """Calculate if and how much two rectangles overlap.

Args:
    rect1: (left, top, width, height) of first rectangle in inches
    rect2: (left, top, width, height) of second rectangle in inches
    tolerance: Minimum overlap in inches to consider as overlapping (default: 0.05")

Returns:
    Tuple of (overlaps, overlap_area) where:
    - overlaps: True if rectangles overlap by more than tolerance
    - overlap_area: Area of overlap in square inches
"""
left1, top1, w1, h1 = rect1
left2, top2, w2, h2 = rect2

# Calculate overlap dimensions
overlap_width = min(left1 + w1, left2 + w2) - max(left1, left2)
overlap_height = min(top1 + h1, top2 + h2) - max(top1, top2)

# Check if there's meaningful overlap (more than tolerance)
if overlap_width > tolerance and overlap_height > tolerance:
    # Calculate overlap area in square inches
    overlap_area = overlap_width * overlap_height
    return True, round(overlap_area, 2)

return False, 0

def detect_overlaps(shapes: List[ShapeData]) -> None: """Detect overlapping shapes and update their overlapping_shapes dictionaries.

This function requires each ShapeData to have its shape_id already set.
It modifies the shapes in-place, adding shape IDs with overlap areas in square inches.

Args:
    shapes: List of ShapeData objects with shape_id attributes set
"""
n = len(shapes)

# Compare each pair of shapes
for i in range(n):
    for j in range(i + 1, n):
        shape1 = shapes[i]
        shape2 = shapes[j]

        # Ensure shape IDs are set
        assert shape1.shape_id, f"Shape at index {i} has no shape_id"
        assert shape2.shape_id, f"Shape at index {j} has no shape_id"

        rect1 = (shape1.left, shape1.top, shape1.width, shape1.height)
        rect2 = (shape2.left, shape2.top, shape2.width, shape2.height)

        overlaps, overlap_area = calculate_overlap(rect1, rect2)

        if overlaps:
            # Add shape IDs with overlap area in square inches
            shape1.overlapping_shapes[shape2.shape_id] = overlap_area
            shape2.overlapping_shapes[shape1.shape_id] = overlap_area

def extract_text_inventory( pptx_path: Path, prs: Optional[Any] = None, issues_only: bool = False ) -> InventoryData: """Extract text content from all slides in a PowerPoint presentation.

Args:
    pptx_path: Path to the PowerPoint file
    prs: Optional Presentation object to use. If not provided, will load from pptx_path.
    issues_only: If True, only include shapes that have overflow or overlap issues

Returns a nested dictionary: {slide-N: {shape-N: ShapeData}}
Shapes are sorted by visual position (top-to-bottom, left-to-right).
The ShapeData objects contain the full shape information and can be
converted to dictionaries for JSON serialization using to_dict().
"""
if prs is None:
    prs = Presentation(str(pptx_path))
inventory: InventoryData = {}

for slide_idx, slide in enumerate(prs.slides):
    # Collect all valid shapes from this slide with absolute positions
    shapes_with_positions = []
    for shape in slide.shapes:  # type: ignore
        shapes_with_positions.extend(collect_shapes_with_absolute_positions(shape))

    if not shapes_with_positions:
        continue

    # Convert to ShapeData with absolute positions and slide reference
    shape_data_list = [
        ShapeData(
            swp.shape,
            swp.absolute_left,
            swp.absolute_top,
            slide,
        )
        for swp in shapes_with_positions
    ]

    # Sort by visual position and assign stable IDs in one step
    sorted_shapes = sort_shapes_by_position(shape_data_list)
    for idx, shape_data in enumerate(sorted_shapes):
        shape_data.shape_id = f"shape-{idx}"

    # Detect overlaps using the stable shape IDs
    if len(sorted_shapes) > 1:
        detect_overlaps(sorted_shapes)

    # Filter for issues only if requested (after overlap detection)
    if issues_only:
        sorted_shapes = [sd for sd in sorted_shapes if sd.has_any_issues]

    if not sorted_shapes:
        continue

    # Create slide inventory using the stable shape IDs
    inventory[f"slide-{slide_idx}"] = {
        shape_data.shape_id: shape_data for shape_data in sorted_shapes
    }

return inventory

def get_inventory_as_dict(pptx_path: Path, issues_only: bool = False) -> InventoryDict: """Extract text inventory and return as JSON-serializable dictionaries.

This is a convenience wrapper around extract_text_inventory that returns
dictionaries instead of ShapeData objects, useful for testing and direct
JSON serialization.

Args:
    pptx_path: Path to the PowerPoint file
    issues_only: If True, only include shapes that have overflow or overlap issues

Returns:
    Nested dictionary with all data serialized for JSON
"""
inventory = extract_text_inventory(pptx_path, issues_only=issues_only)

# Convert ShapeData objects to dictionaries
dict_inventory: InventoryDict = {}
for slide_key, shapes in inventory.items():
    dict_inventory[slide_key] = {
        shape_key: shape_data.to_dict() for shape_key, shape_data in shapes.items()
    }

return dict_inventory

def save_inventory(inventory: InventoryData, output_path: Path) -> None: """Save inventory to JSON file with proper formatting.

Converts ShapeData objects to dictionaries for JSON serialization.
"""
# Convert ShapeData objects to dictionaries
json_inventory: InventoryDict = {}
for slide_key, shapes in inventory.items():
    json_inventory[slide_key] = {
        shape_key: shape_data.to_dict() for shape_key, shape_data in shapes.items()
    }

with open(output_path, "w", encoding="utf-8") as f:
    json.dump(json_inventory, f, indent=2, ensure_ascii=False)

if name == "main": main()