pptx

# pptx

Work with PowerPoint `.pptx` decks. The pptx file format is OOXML — a zip
container holding XML descriptions of slides, layouts, masters, and media.

## Delivery rule

First, use the available tool list for this session to choose the delivery path.

If `write_file`, `edit_file`, `apply_patch`, or `execute_code` is available:

- Build the `.pptx` in the active workspace using the paths below.
- Call `publish_artifact` for the final `.pptx` before your final reply when
  that tool is available.
- The code examples later in this document apply.

If only `create_pptx` is available:

- Use it only for a basic text-only deck from slide titles, body text, and
  bullets.
- Do not use it for illustrated, image-heavy, chart-heavy, template-based, or
  visually designed decks. It does not support images, icons, charts, custom
  layouts, or visual QA.
- If the user asked for those visual features, explain that full visual deck
  authoring is unavailable in this session instead of calling `create_pptx` as
  though it satisfies the request.

If none of those file-authoring tools are available:

- Do not attempt to generate, save, or modify the `.pptx`.
- Do not paste OOXML, Python, JavaScript, HTML, or other source as a substitute
  for sending the deck.
- Ignore the Path B, Path C, and Visual QA sections below; they do not apply
  when file authoring is unavailable.
- Reply plainly: explain that the current session cannot create files, and
  offer to publish an existing `.pptx` by path, describe the slide contents in
  text, or continue in a file-authoring surface such as the OpenSquilla Web UI.

In all cases, do not paste full file source as the deliverable. Source code is
appropriate only when the user explicitly asks for code.

## Decide the path first

Pick **one** of three paths up front; do not mix them. The right path depends
only on what is on disk before you start.

| You have | Goal | Path |
|---|---|---|
| Existing `.pptx` | Read text only | A. Read |
| Existing `.pptx` | Modify content while keeping the design | B. Edit-in-place |
| Nothing, or a brief | Build a new deck | C. Create from scratch |

If the user hands you a deck and asks for changes, default to path B and treat
the input deck as the visual style baseline. Only fall back to path C when the
user explicitly says "start fresh" or there is no input deck.

---

## Path A: Read text from a `.pptx`

Use the helper script. It walks slides via the python-pptx public API and
prints text grouped by slide. This is always available because python-pptx is
the only hard dependency.

```bash
python {baseDir}/scripts/extract_text.py /path/to/deck.pptx
python {baseDir}/scripts/extract_text.py /path/to/deck.pptx --json
```

For programmatic use, call python-pptx directly:

```python
from pptx import Presentation
prs = Presentation("deck.pptx")
for i, slide in enumerate(prs.slides, 1):
    for shape in slide.shapes:
        if shape.has_text_frame:
            for para in shape.text_frame.paragraphs:
                print(i, "".join(run.text for run in para.runs))
```

If `markitdown` is available, it gives a faster Markdown rendering:

```bash
python -m markitdown deck.pptx
```

---

## Path B: Edit an existing deck

Two sub-strategies; pick by how invasive the edit is.

### B1. Text-only edits (preferred)

When the change is "swap this string for that one" or "fill these placeholders":
use python-pptx to mutate runs in place. This preserves all theme/master/font
settings.

```python
from pptx import Presentation
prs = Presentation("input.pptx")
slide = prs.slides[0]
for shape in slide.shapes:
    if not shape.has_text_frame:
        continue
    for para in shape.text_frame.paragraphs:
        for run in para.runs:
            if run.text == "{{TITLE}}":
                run.text = "Q3 Review"
prs.save("output.pptx")
```

Edit at the `run` level, not the `paragraph` level — replacing whole paragraph
text drops formatting. If a placeholder spans multiple runs (often happens
when the original template had partial bold/italic), concatenate the runs into
the first run and clear the others.

### B2. Structural edits (add/remove/reorder slides, change layouts)

python-pptx's slide-level mutation is limited (no public reorder API). For
structural work, unzip the `.pptx`, patch `ppt/presentation.xml` and the
slide files, and repack:

```bash
mkdir _unpacked && (cd _unpacked && unzip -q ../input.pptx)
# edit _unpacked/ppt/presentation.xml (sldIdLst order)
# edit _unpacked/ppt/slides/slideN.xml content
(cd _unpacked && zip -q -r ../output.pptx . -x "*.DS_Store")
```

Rules when patching slide XML:

- Use `defusedxml.minidom` or `lxml`, not stdlib `xml.etree.ElementTree`. ET
  drops or rewrites namespace prefixes (`a:`, `p:`, `r:`) in ways PowerPoint
  refuses to load.
- After deleting slides, remove their `<p:sldId>` from
  `ppt/presentation.xml`'s `<p:sldIdLst>` AND remove the matching relationship
  in `ppt/_rels/presentation.xml.rels`. Skipping either yields a "repair"
  prompt in PowerPoint.
- Update `[Content_Types].xml` if you change the slide count.
- If the deck has speaker notes, each `slideN.xml` has a paired
  `notesSlideN.xml` referenced by `slideN.xml.rels`. Delete or move both
  together.

When done, validate by **opening the output in LibreOffice headless** (next
section) before declaring success. An invalid deck silently fails to render
in some places but loads fine in others.

---

## Path C: Create from scratch

Use **python-pptx** when the runtime is Python-first (more readable, simpler
deps). Use **PptxGenJS** when you need richer layout primitives (charts,
tables with merged cells, gradients) or are already in a Node toolchain.

### C1. python-pptx quick recipe

```python
from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.dml.color import RGBColor

prs = Presentation()
prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)  # 16:9 wide

title_layout = prs.slide_layouts[0]
slide = prs.slides.ad