pptx-designer 1.0.0b4__tar.gz

pptx_designer-1.0.0b4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chaokun Sun
+
+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.

pptx_designer-1.0.0b4/PKG-INFO

@@ -0,0 +1,504 @@
+Metadata-Version: 2.4
+Name: pptx-designer
+Version: 1.0.0b4
+Summary: Python library for LLMs to generate pixel-perfect PowerPoint presentations with 40,000+ style combinations
+Author-email: Chaokun Sun <sunchaokun@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sunchaokun/pptx-designer
+Project-URL: Documentation, https://pptx-designer.readthedocs.io
+Project-URL: Repository, https://github.com/sunchaokun/pptx-designer
+Project-URL: Changelog, https://github.com/sunchaokun/pptx-designer/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/sunchaokun/pptx-designer/issues
+Keywords: pptx,powerpoint,presentation,llm,ai,build-mode,svg,charts,diagrams,python-pptx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: lxml>=4.9.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: shapely>=2.0
+Provides-Extra: images
+Requires-Dist: httpx>=0.24.0; extra == "images"
+Provides-Extra: ai-images
+Requires-Dist: openai>=1.0.0; extra == "ai-images"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# pptx-designer
+
+**A code-first Python library for editable PowerPoint generation in LLM coding workflows**
+
+[![PyPI version](https://img.shields.io/pypi/v/pptx-designer.svg)](https://pypi.org/project/pptx-designer/)
+[![Python](https://img.shields.io/pypi/pyversions/pptx-designer.svg)](https://pypi.org/project/pptx-designer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Turn reviewed Python code into editable `.pptx` files with composable presentation primitives, design data, and native PowerPoint objects.
+
+[Installation](#installation) · [Quick Start](#quick-start) · [Build Mode](#build-mode) · [LLM Authoring Guide](docs/llm-authoring-guide.md) · [Documentation](docs/README.md)
+
+</div>
+
+---
+
+## Why pptx-designer?
+
+More software is now written with an LLM in the loop. That makes the generated **code**—rather than an opaque prompt result—the useful unit of review, versioning, testing, and iteration. `pptx-designer` is a standard Python package built for that workflow: an assistant can compose explicit function calls, and a developer can inspect, modify, test, and rerun the same file.
+
+It is deliberately not a presentation SaaS or a prompt-to-image black box. The output is a `.pptx` built from PowerPoint-native objects whenever the chosen component can express them.
+
+| Design choice | What it means in practice |
+|---|---|
+| **Code is the source of truth** | Layout, wording, colours, and data live in Python and can be reviewed in Git. |
+| **LLM-friendly public APIs** | Small, named, composable helpers reduce ambiguity when code is generated or edited by an assistant. |
+| **Deterministic build path** | The same inputs, package version, fonts, and runtime produce a repeatable build target. |
+| **Editable by default** | Shapes, text, diagrams, and supported SVG elements are emitted as native PPT objects where possible. |
+| **Progressive control** | Start with `generate_ppt()`; move to Build mode when a slide needs exact composition. |
+| **Optional AI services** | Core layout and drawing do not require an API key; image generation/search is opt-in. |
+
+### Scope and honest boundaries
+
+`pptx-designer` adds a higher-level, presentation-oriented layer on top of `python-pptx`; it does not replace PowerPoint's rendering engine or implement every presentation/SVG feature. Native editability and visual fidelity depend on the component and target Office environment. The SVG compiler intentionally supports an editable subset, not browser-complete SVG. Treat generated PPTX files as build artifacts: open them in the target application and review important slides before delivery.
+
+---
+
+## Installation
+
+```bash
+pip install pptx-designer
+```
+
+Optional extras:
+
+```bash
+pip install pptx-designer[images]      # Stock photo search (Unsplash/Pexels)
+pip install pptx-designer[ai-images]   # AI image generation (OpenAI, etc.)
+```
+
+**Requirements**: Python 3.10+
+
+---
+
+## Quick Start
+
+### A code-first slide
+
+When an AI coding assistant generates PPT code, it produces:
+
+```python
+from pptx_designer.tools.shapes import rect
+from pptx_designer.tools.text import text, multiline
+from pptx_designer.tools.cards import kpi_card
+from pptx_designer.tools.layout import page_header
+from pptx_designer.tools.images import cover_image
+from pptx_designer.core.pipeline import Presentation
+
+C = {
+    "primary": "#1D78FA",
+    "accent": "#FF6B35",
+    "text_dark": "#1A1A1A",
+    "text_body": "#4A4A4A",
+    "background": "#FFFFFF",
+}
+
+prs = Presentation()
+slide = prs.slides.add_slide(prs.slide_layouts[6])
+
+page_header(slide, "Q4 Revenue Report", "Financial Summary", C=C)
+kpi_card(slide, 1.0, 2.0, 3.5, 1.5, "$12.8M", "Revenue", "+23%", C=C)
+kpi_card(slide, 5.0, 2.0, 3.5, 1.5, "89%", "Retention", "+5pp", C=C)
+rect(slide, 0.5, 6.8, 12.3, 0.08, fill=C["primary"])
+
+prs.save("output/q4_report.pptx")
+```
+
+### A generated deck from structured content
+
+```python
+from pptx_designer import generate_ppt
+
+# Structured content makes the generated deck predictable and reviewable.
+result = generate_ppt(
+    content={
+        "title": "Q4 Revenue Report",
+        "pages": [
+            {"goal": "hook", "title": "Q4 2026", "subtitle": "Record Quarter"},
+            {"goal": "content", "title": "Key Metrics", "bullets": ["Revenue: $12.8M", "Growth: +23%"]},
+        ]
+    },
+    style="professional",
+    output="output/report.pptx",
+)
+
+# A simple query uses the package's built-in planner; no LLM provider is required.
+result = generate_ppt("AI startup pitch deck", style="dark cyberpunk")
+```
+
+---
+
+## Build Mode
+
+All presentations are built using **composable atoms** — simple, predictable functions that create shapes, text, images, and charts.
+
+### Shapes
+
+```python
+from pptx_designer.tools.shapes import rect, rrect, oval, hexagon, diamond, star5
+
+rect(slide, left=1, top=1, width=4, height=2, fill="#3B82F6")
+rrect(slide, left=1, top=3.3, width=4, height=2, fill="#2563EB")
+oval(slide, left=6, top=1, width=2, height=2, fill="#10B981")
+hexagon(slide, cx=9, cy=2, size=1.5, fill="#F59E0B")
+```
+
+### Text
+
+```python
+from pptx_designer.tools.text import text, multiline, gradient_text, dramatic_text
+
+text(slide, left=1, top=1, width=8, height=1, txt="Hello World", font_size=32, bold=True)
+multiline(slide, left=1, top=2, width=8, height=3, lines=["Line 1", "Line 2", "Line 3"], font_size=14)
+gradient_text(slide, left=1, top=1, width=8, height=1, txt="Gradient", preset="gold-shine", font_size=48)
+```
+
+### Charts
+
+```python
+from pptx_designer.tools.charts import bar_chart
+
+bar_chart(slide, left=2, top=2, data=[("Q1", 0.85, "85%"), ("Q2", 0.92, "92%")])
+```
+
+### Diagrams
+
+```python
+from pptx_designer.diagrams import DiagramStyle, FlowchartDiagram, Region, TimelineDiagram
+
+region = Region(left=1, top=2, width=10, height=5)
+style = DiagramStyle()
+
+FlowchartDiagram(
+    data={"nodes": [{"label": "Discover"}, {"label": "Build"}, {"label": "Review"}]},
+    style=style,
+    region=Region(left=1, top=2, width=10, height=2),
+).render(slide)
+
+TimelineDiagram(
+    data={"events": [{"year": "2024", "title": "Launch"}, {"year": "2025", "title": "Scale"}]},
+    style=style,
+    region=Region(left=1, top=4.5, width=10, height=2),
+).render(slide)
+```
+
+### SVG → PPTX
+
+```python
+from pptx_designer.tools.svg import svg_chart
+
+svg = """<svg viewBox="0 0 400 200" xmlns="http://www.w3.org/2000/svg">
+  <rect x="20" y="20" width="360" height="160" rx="16" fill="#2563EB"/>
+  <text x="200" y="112" text-anchor="middle" font-size="28"
+        font-weight="bold" fill="#FFFFFF">Editable SVG</text>
+</svg>"""
+
+result = svg_chart(slide, svg, x=1, y=1, w=8, h=4)
+print(result.shape_count, result.warnings)
+```
+
+The compiler creates native PowerPoint shapes and text for its supported SVG subset. It supports common geometry, paths, text/tspan, transforms, gradients, `defs`/`use`, and a constrained clipping path workflow. Filters, masks, patterns, animations, external resources, and some SVG paint semantics are not full-fidelity features. Always inspect `result.warnings` for a production SVG. See the [SVG guide](docs/svg-guide.md) for supported input, error handling, and limits.
+
+### Effects
+
+```python
+from pptx_designer.effects import text_fx, shape_fx
+
+text_fx.apply_shadow(shape, blur=8, distance=3, color="#000000")
+shape_fx.apply_3d(shape, depth=10, material="powder")
+shape_fx.apply_pattern(shape, "cross", fg="#000000", bg="#FFFFFF")
+```
+
+---
+
+## LLM coding workflow
+
+The library is designed for an assistant to write ordinary Python—not to hide layout decisions behind a remote generation service. A reliable workflow is:
+
+1. Define slide content, data, and design constraints in code.
+2. Ask the LLM to compose public `pptx_designer` APIs.
+3. Review the generated Python as normal application code.
+4. Run it, inspect the `.pptx`, and keep the code and tests in version control.
+
+This creates a practical feedback loop: a user can edit a title or value in PowerPoint for a one-off change, or edit the keyed Python call and rebuild when the change should be reproducible.
+
+### 1. Explicit function signatures
+
+```python
+def rect(slide, left, top, width, height, fill, line=None, C=None) -> Shape
+def text(slide, left, top, width, height, txt, font_size=12, color="text_body", bold=False, ...) -> Shape
+def kpi_card(slide, left, top, width, height, number, label, trend="", trend_up=True, C=None, ...) -> list[Shape]
+```
+
+Named arguments and focused helpers give an LLM a constrained target and give reviewers readable code.
+
+### 2. Composable presentation primitives
+
+Each helper has a narrow responsibility. An LLM can combine them like building blocks, while a developer retains control over every call:
+
+```python
+# LLM generates this code
+page_header(slide, "Title", "Subtitle", C=C)
+kpi_card(slide, 1, 2, 3, 1.5, "$12M", "Revenue", "+20%", C=C)
+kpi_card(slide, 5, 2, 3, 1.5, "89%", "Retention", "+5pp", C=C)
+rect(slide, 0.5, 6.8, 12.3, 0.08, fill=C["primary"])
+```
+
+### 3. Theme data and explicit overrides
+
+The built-in palette, typography, and style data help an assistant begin from coherent defaults. For production work, pin explicit choices when visual consistency matters:
+
+```python
+from pptx_designer.renderer.theme import ThemeComposer
+
+theme = ThemeComposer().compose(style="dark cyberpunk")
+# Returns: colors, typography, decoration, layout_variant
+```
+
+### 4. No API keys for core drawing features
+
+All shape/text/chart/diagram/effect functions work offline. AI image generation is optional.
+
+### Prompting an LLM safely
+
+When using pptx-designer with AI coding assistants, use this system prompt:
+
+```
+You are a PPT generation expert using pptx-designer.
+
+Rules:
+1. Use only documented public `pptx_designer` imports; do not invent helpers or private modules.
+2. Create a `Presentation()`, add a blank slide, and save the result with `prs.save(path)`.
+3. Use named arguments for positions and dimensions. Coordinates are inches.
+4. Keep colours in a `C` dictionary or select an explicit theme.
+5. Prefer native shapes, text, charts, and diagrams. Check `SVGResult.warnings` after compiling SVG.
+6. Generate a runnable Python file and do not claim the PPT is correct until it has been opened or rendered for review.
+
+Available modules:
+- pptx_designer.tools.shapes: rect, rrect, oval, hexagon, diamond, star5, triangle, arrow
+- pptx_designer.tools.text: text, multiline, gradient_text, dramatic_text, vertical_text
+- pptx_designer.tools.charts: bar_chart, comparison_bars
+- pptx_designer.tools.cards: kpi_card, highlight_cards, code_block, section_divider, hero_slide
+- pptx_designer.tools.layout: page_header, top_bar, page_number
+- pptx_designer.data: PALETTES (192 colors), TYPOGRAPHY (74 fonts), STYLES (84 presets)
+```
+
+---
+
+## Style system
+
+The library ships palette, typography, and style-preset data. Natural-language style selection is a convenience for exploration; explicit values are more appropriate for a reproducible build:
+
+```python
+from pptx_designer.renderer.theme import ThemeComposer
+
+# Natural language
+theme = ThemeComposer().compose(style="warm fintech")
+
+# Exact control
+theme = ThemeComposer().compose(
+    palette="cyber-neon",
+    fonts="tech-mono",
+    decoration="neon-glow",
+    layout="sidebar-left",
+)
+```
+
+### Built-in design data
+
+| Database | Count | Access |
+|----------|------:|--------|
+| Color palettes | 192 | `from pptx_designer.data import PALETTES` |
+| Font pairs | 74 | `from pptx_designer.data import TYPOGRAPHY` |
+| Style presets | 84 | `from pptx_designer.data import STYLES` |
+
+Built-in theme atoms (for ThemeComposer):
+
+| Atom | Count | Examples |
+|------|------:|---------|
+| Hardcoded palettes | 30 | ocean-blue, cyber-neon, golden-luxury |
+| Hardcoded fonts | 15 | modern-sans, tech-mono, elegant-serif |
+| Decorations | 10 | accent-bar, neon-glow, brush-stroke |
+| Layouts | 12 | standard, sidebar-left, grid-2x2 |
+
+---
+
+## Template and enterprise utilities
+
+The package also includes project-scanning and proposal utilities for template- and brand-led workflows. These APIs are optional: the code-first Build mode remains the common foundation.
+
+```python
+from pptx_designer.enterprise import ProjectScanner, ProposalGenerator
+
+# Scan project for assets
+scanner = ProjectScanner()
+assets = scanner.scan("./my-project")
+
+# Generate style proposals
+proposals = ProposalGenerator().generate(
+    query="Q4 business review",
+    template=assets.template_path,
+)
+
+# Generate with confirmed style
+from pptx_designer import generate_ppt
+result = generate_ppt(
+    content=assets.content_raw,
+    template=assets.template_path,
+    confirmed_proposal="A",
+)
+```
+
+---
+
+## Configuration
+
+### Image generation and `.env`
+
+Put a `.env` beside your own `build.py` / project files (or in one of its
+parent directories), then keep it out of Git. Do **not** put credentials in
+the installed `pptx_designer` package directory: upgrades and virtual
+environments will replace it.
+
+[`.env.example`](.env.example) is the checked-in reference file. Copy it to
+your own project root, then replace only the provider you plan to use:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+```bash
+cp .env.example .env
+```
+
+The package reads the nearest `.env` from the working directory upward.
+Process environment variables take precedence over values in `.env`.
+
+```dotenv
+# .env in your presentation project
+PPT_IMAGE_LLM_PROVIDER=gpt-image
+OPENAI_API_KEY=your-api-key
+# OPENAI_IMAGE_MODEL=gpt-image-1
+```
+
+Test the configuration without writing image-request code yourself:
+
+```powershell
+pptx-designer image "editorial fragrance bottle on black stone" --image-mode auto -v
+```
+
+`auto` resolves sources in this order:
+
+1. A `host_image_generator` supplied by an Agent host.
+2. Explicit Python arguments or CLI options.
+3. Project `.env` and process environment variables.
+4. An Agent provider configuration that explicitly references an environment key.
+5. Stock-image search, then no image / the calling layout's placeholder.
+
+When `PPT_IMAGE_LLM_PROVIDER` is omitted, `auto` selects a provider from one
+configured provider key (`OPENAI_API_KEY`, `ARK_API_KEY`, `GEMINI_API_KEY`,
+`DASHSCOPE_API_KEY`, or `MOONSHOT_API_KEY`).
+
+```python
+from pptx_designer import fetch_image
+
+asset = fetch_image(
+    "editorial fragrance bottle on black stone",
+    mode="auto",
+    goal="hook",
+)
+print(asset["path"])  # local file path, or None when every source declines
+```
+
+Agent hosts can also inject a `host_image_generator` callback. This is the
+safe bridge for a host-owned image tool (such as an Agent image-generation
+capability) when no image API is configured: the callback must return a local
+image file path, which `pptx-designer` then places in the slide. The library
+does not attempt to invoke Agent tools or login credentials by itself. This
+hook is for Agent/Skill implementers, not ordinary `build.py` users:
+
+```python
+from pptx_designer import fetch_image
+
+def generate_with_host_tool(*, keywords, emotion, goal, width, height):
+    # The Agent host calls its own image tool and returns the saved local path.
+    return "C:/project/assets/generated/hero.png"
+
+asset = fetch_image(
+    "quiet modern architecture at dawn",
+    mode="auto",
+    host_image_generator=generate_with_host_tool,
+)
+```
+
+A Codex provider entry is considered only when it references an environment
+key. Login/session tokens are never treated as image API keys, and the
+provider's ordinary text model is never treated as an image model. Set an
+explicit `image_model` in the Agent configuration when a non-default image
+model is required.
+
+| Variable | Provider | Description |
+|----------|----------|-------------|
+| `ARK_API_KEY` | Seedream (ByteDance) | Image generation |
+| `OPENAI_API_KEY` | OpenAI | GPT Image / DALL-E |
+| `GEMINI_API_KEY` | Google | Gemini images |
+| `DASHSCOPE_API_KEY` | Alibaba | Wanx images |
+| `UNSPLASH_ACCESS_KEY` | Unsplash | Stock photos |
+| `PEXELS_API_KEY` | Pexels | Stock photos |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/sunchaokun/pptx-designer.git
+cd pptx-designer
+pip install -e ".[dev]"
+
+python -m pytest tests/ -q
+python -m ruff check src/pptx_designer/compiler tests/test_compiler tests/test_svg_tools.py tests/test_svg_compiler_integration.py
+```
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [API reference](docs/api-reference.md)
+- [LLM authoring guide](docs/llm-authoring-guide.md)
+- [SVG compiler guide](docs/svg-guide.md)
+- [Changelog](CHANGELOG.md)
+
+## Advanced examples
+
+Explore complete four-page, editable decks in [examples/](examples/README.md): a luxury fragrance lookbook, a couture editorial deck, and an architecture vision book. Every example includes the build script, original image assets, and its generated `.pptx` output.
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.