pptx-cli 1.0.0__py3-none-any.whl

pptx_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,505 @@
+Metadata-Version: 2.4
+Name: pptx-cli
+Version: 1.0.0
+Summary: Template-bound PowerPoint generation for enterprise decks
+Author: Thomas Rohde
+License: MIT License
+        
+        Copyright (c) 2026 Thomas Rohde
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,enterprise,openxml,powerpoint,pptx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: lxml>=5.3.1
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.4
+Requires-Dist: typer>=0.15.1
+Description-Content-Type: text/markdown
+
+# pptx
+
+[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/pptx-cli/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Template-bound PowerPoint generation for enterprise decks.
+
+`pptx` turns a real `.pptx` template into a machine-readable manifest, then generates slides and decks **inside the original corporate design contract** instead of trying to approximate it from prompts.
+
+If your organization cares about slide masters, locked branding, placeholder rules, layout fidelity, and CI validation, this is the tool.
+
+The package is published to PyPI as [`pptx-cli`](https://pypi.org/project/pptx-cli/) and installs the `pptx` command.
+
+## Why `pptx` exists
+
+Most AI slide generators fail where enterprise users care most:
+
+- layouts drift from the official template
+- placeholders get used inconsistently
+- static branding moves or disappears
+- theme styling gets recreated approximately instead of preserved exactly
+- decks look plausible but are structurally wrong
+
+`pptx` takes a different approach:
+
+1. **Initialize from a real template**
+2. **Extract a manifest of layouts, placeholders, assets, and rules**
+3. **Generate only within those approved boundaries**
+4. **Validate output before it reaches humans, CI, or customers**
+
+The result is a CLI that behaves more like a compiler toolchain than a drawing tool.
+
+## Features
+
+- Initialize a manifest package from a real enterprise `.pptx`
+- Inspect layouts, placeholders, themes, assets, and compatibility warnings
+- Build slides from approved layouts only
+- Build full decks from JSON/YAML specs
+- Preserve template-bound masters, themes, geometry, and protected elements
+- Validate generated decks against manifest rules and template fingerprints
+- Diff template versions to detect breaking changes
+- Generate template-specific wrapper CLIs
+- Expose an agent-first machine contract with:
+  - stable JSON response envelopes
+  - structured error codes
+  - documented exit codes
+  - a built-in `guide` command
+  - `--dry-run` support for mutating commands
+
+## Installation
+
+### With `uv` (recommended)
+
+```bash
+uv tool install pptx-cli
+```
+
+### From the repository
+
+```bash
+uv tool install git+https://github.com/ThomasRohde/pptx-cli.git
+```
+
+### From PyPI with pip
+
+```bash
+pip install pptx-cli
+```
+
+### Verify installation
+
+```bash
+pptx --version
+pptx guide --format json
+```
+
+## Quick start
+
+The repository includes a real sample template at `Template.pptx`. The examples below use that file and the layout IDs currently extracted from it.
+
+Initialize a template package from an existing PowerPoint file:
+
+```bash
+pptx init ./Template.pptx --out ./corp-template
+```
+
+Inspect the extracted layouts:
+
+```bash
+pptx layouts list --manifest ./corp-template
+pptx layouts show title-only --manifest ./corp-template
+pptx placeholders list 1-title-and-content --manifest ./corp-template
+```
+
+Create a single slide:
+
+```bash
+pptx slide create \
+  --manifest ./corp-template \
+  --layout title-only \
+  --set title="Enterprise AI Operating Model" \
+  --set subtitle="March 2026" \
+  --out ./out/operating-model-slide.pptx
+```
+
+Build a full deck from a spec:
+
+```bash
+pptx deck build \
+  --manifest ./corp-template \
+  --spec ./deck.yaml \
+  --out ./out/operating-model.pptx
+```
+
+Validate the result:
+
+```bash
+pptx validate \
+  --manifest ./corp-template \
+  --deck ./out/operating-model.pptx \
+  --strict
+```
+
+Preview the write before touching the filesystem:
+
+```bash
+pptx deck build \
+  --manifest ./corp-template \
+  --spec ./deck.yaml \
+  --out ./out/operating-model.pptx \
+  --dry-run
+```
+
+## Example deck spec
+
+```yaml
+manifest: ./corp-template
+metadata:
+  title: Enterprise AI Operating Model
+  author: Thomas Rohde
+  template_version: 1.2.0
+slides:
+  - layout: title-only
+    content:
+      title: Enterprise AI Operating Model
+      subtitle: March 2026
+  - layout: 1-breaker-with-pattern
+    content:
+      title: Why this change
+      subtitle: Preserve, don’t imitate
+  - layout: 1-title-and-content
+    content:
+      title: Core idea
+      content_1: |
+        Preserve the template.
+        Generate inside its rules.
+      subtitle: Layouts and placeholders become machine-readable contracts.
+```
+
+## Core commands
+
+```text
+pptx guide
+pptx init
+pptx doctor
+pptx layouts list
+pptx layouts show
+pptx placeholders list
+pptx theme show
+pptx assets list
+pptx slide create
+pptx deck build
+pptx validate
+pptx manifest diff
+pptx manifest schema
+pptx completions generate
+pptx wrapper generate
+```
+
+## Manifest package layout
+
+A template initialization produces a package like this:
+
+```text
+corp-template/
+  manifest.yaml
+  manifest.schema.json
+  annotations.yaml
+  assets/
+    images/
+    media/
+    embedded/
+  previews/
+    layouts/
+  fingerprints/
+    parts.json
+  reports/
+    init-report.json
+```
+
+### Key files
+
+- `manifest.yaml` — extracted source-of-truth contract
+- `manifest.schema.json` — schema for validation and tooling
+- `annotations.yaml` — human-authored semantic annotations layered over extracted facts
+- `reports/init-report.json` — warnings, unsupported features, and compatibility findings
+- `fingerprints/parts.json` — structural fingerprints used for validation and diffing
+
+## Supported v1 content types
+
+`pptx` supports these placeholder content types in v1:
+
+- text
+- image
+- table
+- chart
+- markdown-to-text
+
+### Fidelity model
+
+Guaranteed in scope:
+
+- slide size and orientation
+- master/layout relationships
+- approved placeholder geometry
+- protected static elements
+- preserved theme references where supported
+- deterministic content mapping into approved placeholders
+
+Best-effort in v1:
+
+- advanced chart workbook behavior
+- highly custom chart or table styling internals
+- content-sensitive text reflow edge cases
+- animations and transitions
+
+## Agent-first CLI contract
+
+`pptx` is designed to be scriptable by both humans and coding agents.
+
+### Structured response envelope
+
+In machine-readable mode, commands return a single JSON envelope on stdout:
+
+```json
+{
+  "schema_version": "1.0",
+  "request_id": "req_20260307_120000_abcd",
+  "ok": true,
+  "command": "layouts.list",
+  "result": {},
+  "warnings": [],
+  "errors": [],
+  "metrics": {
+    "duration_ms": 42
+  }
+}
+```
+
+### Output rules
+
+- stdout is reserved for structured machine output
+- stderr is used for progress and diagnostics
+- `LLM=true` enables minimal non-decorative output behavior
+- `--dry-run` previews mutating commands without writing files
+
+### Discoverability
+
+Use `guide` to retrieve the CLI contract in one call:
+
+```bash
+pptx guide --format json
+```
+
+That output includes:
+
+- commands and subcommands
+- input/output schema references
+- examples
+- error-code taxonomy
+- exit-code mapping
+- identifier conventions
+
+## Exit codes
+
+`pptx` uses stable exit-code categories for automation:
+
+| Exit code | Meaning |
+|---|---|
+| `0` | Success |
+| `10` | Validation or schema error |
+| `20` | Permission or policy failure |
+| `40` | Conflict or stale-state failure |
+| `50` | I/O or package read/write failure |
+| `90` | Internal error |
+
+## Safety model
+
+Mutating commands support preview-first workflows and safe writes:
+
+- `--dry-run` for non-destructive previews
+- structured change summaries for write operations
+- explicit override flags for dangerous operations
+- temporary-file staging and atomic replacement where possible
+
+Because PowerPoint files are ZIP-based packages wearing office clothes, half the job is content generation and the other half is not breaking them.
+
+## Wrapper CLIs
+
+You can generate a template-specific wrapper CLI for teams that want a narrower interface:
+
+```bash
+pptx wrapper generate \
+  --manifest ./corp-template \
+  --out ./wrappers/acme-pptx
+```
+
+In v1, wrapper generation emits a thin Python package scaffold that delegates to the shared `pptx` engine.
+
+## Validation and governance
+
+`pptx validate` checks both structure and fidelity constraints, including:
+
+- master/layout usage
+- placeholder mapping correctness
+- required placeholder presence
+- schema compliance of deck specs
+- missing assets or broken relationships
+- fingerprint mismatches for protected components
+- geometry drift for locked objects and placeholders
+
+This makes `pptx` suitable for:
+
+- local authoring workflows
+- CI pipelines
+- agent-driven deck generation
+- enterprise template governance
+
+## Versioning and diffing
+
+When templates change, `pptx` can compare manifest packages:
+
+```bash
+pptx manifest diff ./corp-template-v1 ./corp-template-v2
+```
+
+Diffs highlight:
+
+- added or removed layouts
+- placeholder contract changes
+- alias changes
+- geometry changes
+- theme/font changes
+- asset changes
+- additive vs. breaking changes
+
+## Platform support
+
+- Windows
+- macOS
+- Linux
+
+Microsoft PowerPoint is **not required** to run the CLI.
+
+## Use cases
+
+- enterprise strategy decks
+- consulting deliverables
+- board and steering-committee presentations
+- corporate communications templates
+- internal automation pipelines generating `.pptx` output from structured data
+- AI-assisted deck generation with strict branding control
+
+## Development
+
+### Sample template for local testing
+
+The repository root includes `Template.pptx`, which is currently used for:
+
+- CLI integration tests
+- README quick-start examples
+- local manual smoke tests while the fixture catalog grows
+
+If additional sanitized templates are introduced later, they should live under `tests/fixtures/templates/` with a short note describing their scenario coverage.
+
+Clone the repository and sync the development environment:
+
+```bash
+git clone https://github.com/ThomasRohde/pptx-cli.git
+cd pptx-cli
+uv sync --group dev
+```
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Run linting and type checks:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+```
+
+## Versioning
+
+The project uses semantic versioning with a **single source of truth** in `src/pptx_cli/__init__.py`.
+
+Use the helper script to bump versions safely:
+
+```bash
+uv run python scripts/bump_version.py patch
+uv run python scripts/bump_version.py minor
+uv run python scripts/bump_version.py major
+```
+
+This commits the version change, creates an annotated `v*` tag, and pushes — which triggers the publish workflow automatically. Use `--no-push` to tag locally without pushing.
+
+This updates the package version used for builds and PyPI publishing without needing to edit multiple files manually.
+
+## Documentation
+
+- `PRD.md` — product definition and scope
+- `CLI-MANIFEST.md` — agent-first CLI design principles adopted by this project
+- `SCAFFOLD.md` — project scaffolding instructions
+
+## Roadmap highlights
+
+- richer preview generation
+- deeper table/chart plugins
+- broader enterprise policy packs
+- multi-template registries
+- post-v1 MCP integration
+
+## Contributing
+
+Contributions are welcome.
+
+Please open an issue or discussion for:
+
+- new placeholder/content type support
+- template edge cases
+- manifest schema changes
+- CLI contract changes
+- validation or fidelity bugs
+
+For larger changes, include:
+
+- the motivating template behavior
+- expected vs. actual output
+- sample manifest or sanitized `.pptx` structure where possible
+
+## License
+
+MIT

pptx_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+pptx_cli/__init__.py,sha256=zHV2M6IAifaZLSjMwl38Lnsdp1e9BLkmZU8cXrLdnXM,74
+pptx_cli/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+pptx_cli/cli.py,sha256=VBDuTGyhn_EvLwsCB5Fb2XO0pRPkfks6GhImisjvnbo,11663
+pptx_cli/commands/__init__.py,sha256=gQ6tnU0Rvm0-ESWFUBU-KDl5dpNOpUTG509hXOQQjwY,27
+pptx_cli/commands/compose.py,sha256=M40r1KAgN5m7lifgjZAZuhJBwhHpE-PmWjRYIXHa-n8,1996
+pptx_cli/commands/guide.py,sha256=lNLcKvPLHKFLzKExqwZsgxhybu4sWUDLbVAYnw_dNRk,6666
+pptx_cli/commands/init.py,sha256=iWWhzvKRdHrqa7ZPGSbx8OPsiOX0RPor57OrbhJIPgg,1501
+pptx_cli/commands/inspect.py,sha256=44QPISE8bJORX_SfxejglQdaXpChWEpblTG26ywVK98,2752
+pptx_cli/commands/manifest_ops.py,sha256=h8IFJkWt70-U-tWyEdxhJ3pLorTSDAakO_umoZJOPzI,643
+pptx_cli/commands/validate.py,sha256=tvbtXbEWc90HkaNT3lels5xVawd2QWX4YyqUglv3Dc8,449
+pptx_cli/commands/wrapper.py,sha256=MFrEijPhWcjees6QZ0yRvV_TorDG89F-F_fnDarhz78,7548
+pptx_cli/core/__init__.py,sha256=ehOnz_7yfZMv4k5gNtY2IxJt3C-MXmgIIQxtIwCXpXU,28
+pptx_cli/core/composition.py,sha256=xEEPy94Gr1jA8sqaLJOzeOZMxxu8XuQ7Xn9xuubXWEE,10266
+pptx_cli/core/ids.py,sha256=FlLiP3TDXL2iH-P2sHkM8bObluG_EnuBFnOWfdgcFAw,547
+pptx_cli/core/io.py,sha256=3QrTqdJQH0RnWTyGLPXmB_iHijqLc-RpjlAyNtA9ewk,1670
+pptx_cli/core/manifest_store.py,sha256=f0VjSlSLAfYYSiSEYopX7MxQ4RQV47h0OsMdjxAafRA,2011
+pptx_cli/core/runtime.py,sha256=EXEyC3efWNMasEuDllsFcmzIMVcPyjkY1YVP9ctr9aU,644
+pptx_cli/core/template.py,sha256=ha4dQJqDrt0UOSHaiLagCm51vjNoco0mctfUTFgsIFo,22102
+pptx_cli/core/validation.py,sha256=nrXB9pyBe4QDc24cODaTIyI2qoKrom52oU4KnlSNNcU,8293
+pptx_cli/core/versioning.py,sha256=R4Wk4m4K0gPfQIa-OOSM6EHVqkAXLKasQ92hrv-CRFU,1565
+pptx_cli/models/__init__.py,sha256=w3uwhzxinzrafGS8x0OhfWDCBerckShkGhuFl-_wEzI,38
+pptx_cli/models/envelope.py,sha256=fgNiINoOd_Jjt7qbzB9pNrwN5HCgSTr-e6zTk_ZVfXg,1399
+pptx_cli/models/manifest.py,sha256=rqylSMPgW0q_ESM_audoBnU2wb3pl7OyohmGnesdxG4,4902
+pptx_cli-1.0.0.dist-info/METADATA,sha256=mT31KwMQfNd6F-ojuVXZvzMB5itLuhXdySemEwYNP1A,13403
+pptx_cli-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pptx_cli-1.0.0.dist-info/entry_points.txt,sha256=KCwbqLMg3lFy-ixO3MYv0Xv4buWwPAc7W3cFusk6jXs,43
+pptx_cli-1.0.0.dist-info/licenses/LICENSE,sha256=XeaSn5y2iyNPWLW7TlPEWT8OkLhuZw-koqZ5bhUw5tg,1069
+pptx_cli-1.0.0.dist-info/RECORD,,

pptx_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pptx_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pptx = pptx_cli.cli:main

pptx_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Rohde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.