---
name: processing-pptx
description: Creates, reads, and modifies PowerPoint presentations (.pptx, .potx) with python-pptx — slides, layouts, text, tables, images, charts. Use when the user asks to create, build, read, edit, or fix a presentation, deck, or slides, or mentions .pptx/.potx files or PowerPoint. Do not use for Word documents, PDFs, or Google Slides.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Processing PPTX

## When to use / when NOT to use
- **Use for:** creating, reading, or modifying `.pptx` and `.potx` files — slides, text, tables, images, charts, speaker notes.
- **Do NOT use for:** Word documents, PDFs, or Google Slides (different API).

## Quick reference

Default library: **python-pptx**. Visual verification: **LibreOffice** render to PDF/images when layout correctness matters.

**Create:**
```python
from pptx import Presentation
from pptx.util import Inches, Pt

prs = Presentation()                      # 4:3 default; set 16:9 explicitly:
prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)

slide = prs.slides.add_slide(prs.slide_layouts[0])   # 0 = title slide
slide.shapes.title.text = "Q3 Results"
slide.placeholders[1].text = "Finance Team — 2026"
prs.save("deck.pptx")
```

**Read:**
```python
from pptx import Presentation
for i, slide in enumerate(Presentation("deck.pptx").slides, 1):
    for shape in slide.shapes:
        if shape.has_text_frame:
            print(i, shape.text_frame.text)
```

**Modify:**
```python
prs = Presentation("deck.pptx")
slide = prs.slides[1]
for shape in slide.shapes:
    if shape.has_text_frame and "draft" in shape.text_frame.text.lower():
        shape.text_frame.text = shape.text_frame.text.replace("Draft", "Final")
prs.save("deck.pptx")
```

**Visual check (when layout matters):**
```bash
soffice --headless --convert-to pdf deck.pptx   # then inspect pages for overflow/overlap
```

## Design rules
- Safe fonts only: Arial or Calibri.
- Keep ≥0.5" margins; body text ≥14pt, titles ≥28pt.
- No text-only slides in a finished deck — add an image, chart, or table per slide where content allows.
- Build a new deck from an existing template (`Presentation("template.potx")`) when the user has one; reuse its layouts instead of drawing boxes manually.

## Workflow
1. Classify the task: create / read / modify.
2. Creating: start from the user's template if provided, else default template with 16:9 size. Use slide layouts and placeholders, not free-floating text boxes, so themes apply.
3. Modifying: read all slides first; edit in place, preserving each shape's position and formatting.
4. Validate: re-open with `Presentation(path)` — if it raises, fix before delivering. Count slides and confirm expected titles.
5. If the deck is a final deliverable, render via `soffice --headless --convert-to pdf` and check for text overflow, overlap, and contrast.
6. Report the output path, slide count, and what changed.

## Edge cases & failure modes
- **python-pptx missing** → `pip install python-pptx`. **LibreOffice missing** → `brew install --cask libreoffice` (only needed for visual checks/conversion).
- **Corrupt / not a zip** → `Presentation()` raises `PackageNotFoundError`; report invalid pptx, stop.
- **Password-protected file** → python-pptx cannot decrypt; ask for an unprotected copy.
- **`.ppt` (legacy binary)** → unsupported; convert first: `soffice --headless --convert-to pptx file.ppt`.
- **Text overflowing its box** → python-pptx cannot measure rendered text; shorten text or reduce font size, then re-render to verify.

## References
Deeper recipes (bullets, tables, images, charts, speaker notes, template reuse, per-slide deletion, conversion, gotchas): see [references/recipes.md](references/recipes.md).