Metadata-Version: 2.4
Name: illuma-presentx
Version: 0.1.0
Summary: PPTX generation, QA verification, and template editing toolkit
Author: Illuma AI
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: lxml>=4.9.0
Requires-Dist: pillow>=9.0.0
Provides-Extra: text
Requires-Dist: markitdown[pptx]>=0.1.0; extra == "text"
Provides-Extra: layout
Requires-Dist: python-pptx>=1.0.0; extra == "layout"
Provides-Extra: all
Requires-Dist: markitdown[pptx]>=0.1.0; extra == "all"
Requires-Dist: python-pptx>=1.0.0; extra == "all"

# illuma-presentx

PPTX generation, QA verification, and template editing toolkit for LLM-powered presentation workflows.

## Installation

```bash
# Core (XML tools, thumbnail generation)
pip install git+https://github.com/illuma-ai/illuma-presentx.git

# With text extraction support
pip install "illuma-presentx[text] @ git+https://github.com/illuma-ai/illuma-presentx.git"

# With layout analysis support
pip install "illuma-presentx[layout] @ git+https://github.com/illuma-ai/illuma-presentx.git"

# All optional dependencies
pip install "illuma-presentx[all] @ git+https://github.com/illuma-ai/illuma-presentx.git"
```

## Quick Start

### CLI Usage

```bash
# Run the PPTX workflow runner
presentx --help

# Generate thumbnails from a presentation
python -m presentx.thumbnail input.pptx

# Unpack a PPTX for editing
python -m presentx.office.unpack input.pptx unpacked/

# Repack after editing
python -m presentx.office.pack unpacked/ output.pptx --original input.pptx
```

### PPTXWorkflow Usage

```python
from presentx import PPTXWorkflow

workflow = PPTXWorkflow(work_dir="/mnt/data")

# Unpack a template
workflow.unpack("template.pptx", "unpacked/")

# Generate thumbnails for analysis
workflow.thumbnail("template.pptx")

# Clean orphaned files after editing
workflow.clean("unpacked/")

# Repack into final output
workflow.pack("unpacked/", "output.pptx", original="template.pptx")
```

## Architecture

```
src/presentx/
  __init__.py          # PPTXWorkflow, public API
  pptx_runner.py       # CLI entry point
  thumbnail.py         # Slide thumbnail grid generation
  add_slide.py         # Duplicate/create slides from layouts
  clean.py             # Remove orphaned slides, media, rels
  office/
    unpack.py          # Extract and pretty-print PPTX XML
    pack.py            # Validate, repair, and repack PPTX
    soffice.py         # LibreOffice wrapper for PDF conversion
    schemas/           # OOXML XSD schemas for validation
  js/
    merge_decks.cjs    # Multi-part deck merger (Node.js)
  docs/
    SKILL.md           # Main skill guide (creation, QA, design)
    pptxgenjs.md       # PptxGenJS API reference and patterns
    editing.md         # Template editing workflow
```

## Available Tools

| Tool | Purpose |
|------|---------|
| `thumbnail.py` | Generate visual grid of slide thumbnails |
| `unpack.py` | Extract PPTX to directory with pretty-printed XML |
| `pack.py` | Repack directory into validated PPTX |
| `add_slide.py` | Duplicate a slide or create from a layout |
| `clean.py` | Remove orphaned slides, media, and relationships |
| `soffice.py` | Convert PPTX to PDF via LibreOffice |
| `merge_decks.cjs` | Merge multi-part PPTX files (Node.js) |

## Workflows

### Create from Scratch (PptxGenJS)

Use when no template is available. See `docs/pptxgenjs.md` for the full PptxGenJS API reference including shapes, charts, icons, and common pitfalls.

### Edit from Template

Use when modifying an existing presentation. See `docs/editing.md` for the unpack/edit/pack workflow, XML editing patterns, and formatting rules.

### QA Verification

Every generated presentation should go through content QA (markitdown text check) and visual QA (slide-to-image conversion + inspection). See `docs/SKILL.md` for the full QA protocol.

## Dependencies

**Core:** defusedxml, lxml, Pillow

**Optional:**
- `markitdown[pptx]` -- text extraction from PPTX files
- `python-pptx` -- layout analysis and programmatic slide manipulation

**External (not pip-managed):**
- Node.js + `pptxgenjs` -- creating presentations from scratch
- LibreOffice (`soffice`) -- PDF conversion for visual QA
- Poppler (`pdftoppm`) -- PDF to image conversion

## License

MIT
