python-ppt-builder

name	python-ppt-builder
description	Create, render, and validate editable PowerPoint decks from one standalone Python builder using python-pptx, native Office Math, speaker notes, PDF/image assets, and PowerPoint-first visual QA. Use for general PPTX generation, reusable slide automation, Python-based presentation templates, or converting an existing slide design into a portable topic-specific builder without JSON specifications.

Standalone Python PPT Builder

Create each presentation from one topic-specific Python file. Keep theme, content, layout, assets, formulas, notes, rendering, and validation in code rather than JSON.

When this skill is explicitly invoked, use its Python builder workflow. Apply the visual-quality rules from a general presentation skill, but do not replace this skill's required python-pptx implementation with another presentation backend.

Deliverables

Produce:

• build_<topic>_ppt.py: complete and portable source of truth;
• <topic>.pptx: generated output;
• optional rendered_slides/slide-NN.png: visual-QA images.

Start from assets/build_ppt_template.py. Copy every required helper into the generated builder; do not import from this skill at runtime.

Run with uv:

uv run /absolute/path/build_<topic>_ppt.py \
  --output /absolute/path/<topic>.pptx \
  --work-dir /absolute/path/<topic>_ppt_work \
  --render-dir /absolute/path/rendered_slides \
  --render-backend powerpoint

Python environment

At the start of the task, treat the current working directory as the workspace root. Keep one reusable environment at <workspace-root>/.venv; the builder and output PPTX may be located elsewhere.

1. Record the workspace root before changing directories, for example PPT_WORKSPACE_ROOT="$PWD".
2. Reuse $PPT_WORKSPACE_ROOT/.venv when it exists and can import pptx.
3. If it does not exist, run uv venv "$PPT_WORKSPACE_ROOT/.venv".
4. Install with uv pip install --python "$PPT_WORKSPACE_ROOT/.venv/bin/python" "python-pptx>=1.0.2".
5. Run $PPT_WORKSPACE_ROOT/.venv/bin/python /absolute/path/build_<topic>_ppt.py ... by default; never install globally.
6. Retain PEP 723 metadata and use uv run /absolute/path/build_<topic>_ppt.py ... only as a portable fallback.

Workflow

1. Inspect the requested content, reference deck, output paths, and target speaking context.
2. Choose one coherent visual system: aspect ratio, typography, colors, spacing, header/footer, figure treatment, and density.
3. Write explicit numbered slide sections inside build_deck(); do not introduce a JSON slide schema.
4. Keep one main message per slide and express it in the slide title when appropriate.
5. Use native text, shapes, tables, charts, and Office Math wherever editability matters.
6. Add speaker notes when requested or when the deck is intended for presentation.
7. Generate the PPTX, run structural validation, render all slides with Microsoft PowerPoint, and visually inspect them.
8. Iterate until text wrapping, cropping, contrast, alignment, and slide-to-slide consistency are correct.

Formulas

• Use Pandoc only to convert LaTeX into editable Office Math/OMML.
• Use editable inline math for symbols inside prose and display math for standalone equations.
• Never use formula screenshots when native Office Math is possible.

Rendering and macOS permission

• Do not use Pandoc as a PPTX renderer.
• Final acceptance requires Microsoft PowerPoint native PDF export followed by Poppler pdftoppm.
• The builder must default to --render-backend powerpoint, print the selected backend, and reject a page-count mismatch between the PPTX, exported PDF, and PNG files.
• On first use, macOS may ask whether Codex or its terminal host can control Microsoft PowerPoint. Ask the user to allow it under System Settings > Privacy & Security > Automation. Do not modify system permissions automatically.
• LibreOffice is available only through explicit --render-backend libreoffice for diagnostics. Its output is never final-acceptance evidence and the builder must print final_eligible=false.
• Render into an empty directory to prevent stale slide images from passing QA.
• Identify the opened PowerPoint presentation by its absolute file path; never export whichever presentation happens to be active.
• Treat PowerPoint-native rendering as the final visual authority.

Validation

Check:

• slide count and intended ordering;
• one notes slide per slide when notes are required;
• intended <a14:m> Office Math elements exist;
• every external image resolves and remains sharp after rendering;
• no unintended overlap, overflow, clipping, or inconsistent margins;
• output images equal the PPTX slide count.

By default, refuse to overwrite an existing PPTX or non-empty render directory. Use --force only for the explicitly named output targets. Keep equation-conversion, PDF-export, rendering, and QA temporary files in --work-dir, which defaults next to the output PPTX as <output-stem>_ppt_work/. Do not use /tmp, /private/tmp, or another system temporary root.

Read references/builder-contract.md before final delivery.