ppt-master 0.1.0__py3-none-any.whl

cli.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""ppt-master CLI — unified entry point for all scripts.
+
+Usage:
+    ppt-master <command> [args...]
+    ppt-master --help
+
+Examples:
+    ppt-master project init my-project --format ppt169
+    ppt-master pdf-to-md report.pdf
+    ppt-master svg-to-pptx projects/my-project
+"""
+
+import os
+import subprocess
+import sys
+
+SCRIPTS_DIR = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)),
+    "skills", "ppt-master", "scripts"
+)
+
+COMMANDS = {
+    "project":                "project_manager.py",
+    "pdf-to-md":              "source_to_md/pdf_to_md.py",
+    "doc-to-md":              "source_to_md/doc_to_md.py",
+    "excel-to-md":            "source_to_md/excel_to_md.py",
+    "ppt-to-md":              "source_to_md/ppt_to_md.py",
+    "web-to-md":              "source_to_md/web_to_md.py",
+    "analyze-images":         "analyze_images.py",
+    "image-gen":              "image_gen.py",
+    "image-search":           "image_search.py",
+    "latex-render":           "latex_render.py",
+    "svg-quality-check":      "svg_quality_checker.py",
+    "total-md-split":         "total_md_split.py",
+    "finalize-svg":           "finalize_svg.py",
+    "svg-to-pptx":            "svg_to_pptx.py",
+    "check-annotations":      "check_annotations.py",
+    "animation-config":       "animation_config.py",
+    "notes-to-audio":         "notes_to_audio.py",
+    "pptx-template-import":   "pptx_template_import.py",
+    "template-fill-pptx":     "template_fill_pptx.py",
+    "svg-editor":             "svg_editor/server.py",
+    "update-spec":            "update_spec.py",
+    "visual-review":          "visual_review.py",
+    "svg-position-calc":      "svg_position_calculator.py",
+    "rotate-images":          "rotate_images.py",
+    "update-repo":            "update_repo.py",
+    "generate-examples-index": "generate_examples_index.py",
+    "batch-validate":         "batch_validate.py",
+    "gemini-watermark-remove": "gemini_watermark_remover.py",
+    "pptx-animations":        "pptx_animations.py",
+    "check-deps-sync":        "check_deps_sync.py",
+    "pptx-to-svg":            "pptx_to_svg.py",
+    "error-helper":           "error_helper.py",
+    "project-utils":          "project_utils.py",
+    "config":                 "config.py",
+    "register-template":      "register_template.py",
+}
+
+COMMAND_DESCRIPTIONS = {
+    "project":                "Create/validate/manage PPT projects",
+    "pdf-to-md":              "Convert PDF to Markdown",
+    "doc-to-md":              "Convert DOCX/HTML/EPUB to Markdown",
+    "excel-to-md":            "Convert Excel to Markdown",
+    "ppt-to-md":              "Convert PPTX to Markdown",
+    "web-to-md":              "Convert URL/webpage to Markdown",
+    "analyze-images":         "Analyze images and compute layout sizes",
+    "image-gen":              "AI image generation (multi-backend)",
+    "image-search":           "Search and download web images",
+    "latex-render":           "Render LaTeX formulas to PNG",
+    "svg-quality-check":      "Validate SVG against PPT constraints",
+    "total-md-split":         "Split total.md into per-page files",
+    "finalize-svg":           "Post-process SVGs (icons, images, text)",
+    "svg-to-pptx":            "Export SVGs to PPTX",
+    "check-annotations":      "Scan SVGs for edit annotations",
+    "animation-config":       "Create/validate animation configuration",
+    "notes-to-audio":         "Generate per-slide narration audio (TTS)",
+    "pptx-template-import":   "Extract SVG references from PPTX template",
+    "template-fill-pptx":     "Fill content into PPTX template",
+    "svg-editor":             "Launch web-based SVG editor (live preview)",
+    "update-spec":            "Propagate color/font changes to all SVGs",
+    "visual-review":          "Visual review via Playwright (PNG renderer)",
+    "svg-position-calc":      "Chart coordinate calculator",
+    "rotate-images":          "Rotate images (EXIF + manual)",
+    "update-repo":            "Git pull + uv sync repository updater",
+    "generate-examples-index": "Generate examples README index",
+    "batch-validate":         "Batch project validator",
+    "gemini-watermark-remove": "Remove watermarks from Gemini images",
+    "pptx-animations":        "Animation demo and list utilities",
+    "check-deps-sync":        "Verify dependency manifest sync",
+    "pptx-to-svg":            "Convert PPTX to SVG",
+    "error-helper":           "Error explanation lookup",
+    "project-utils":          "Project utility helpers",
+    "config":                 "List canvas formats and color presets",
+    "register-template":      "Register layout template",
+}
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv
+
+    if len(argv) < 2 or any(a in ("-h", "--help") for a in argv[1:]):
+        print("Usage: ppt-master <command> [args...]")
+        print("\nCommands:")
+        width = max(len(k) for k in COMMANDS) + 2
+        for name in sorted(COMMANDS):
+            desc = COMMAND_DESCRIPTIONS.get(name, "")
+            print(f"  {name:<{width}}{desc}")
+        return 0
+
+    cmd = argv[1]
+    args = argv[2:]
+
+    script_rel = COMMANDS.get(cmd)
+    if script_rel is None:
+        print(f"Unknown command: {cmd}", file=sys.stderr)
+        print("Run 'ppt-master' without arguments to list commands.", file=sys.stderr)
+        return 1
+
+    script_path = os.path.join(SCRIPTS_DIR, script_rel)
+    if not os.path.isfile(script_path):
+        print(f"Script not found: {script_path}", file=sys.stderr)
+        return 1
+
+    try:
+        result = subprocess.run([sys.executable, script_path, *args])
+    except KeyboardInterrupt:
+        return 130
+    return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ppt_master-0.1.0.dist-info/METADATA

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: ppt-master
+Version: 0.1.0
+Summary: AI-driven multi-format SVG content generation system
+Author: elvisw
+License: MIT
+Project-URL: Repository, https://github.com/elvisw/ppt-master
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-pptx>=0.6.21
+Requires-Dist: edge-tts>=7.2.8
+Requires-Dist: svglib>=1.5.0
+Requires-Dist: reportlab>=4.0.0
+Requires-Dist: PyMuPDF>=1.23.0
+Requires-Dist: mammoth>=1.6.0
+Requires-Dist: markdownify>=0.11.6
+Requires-Dist: ebooklib>=0.18
+Requires-Dist: nbconvert>=7.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: curl_cffi>=0.7.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: flask>=3.0.0
+Dynamic: license-file
+
+# PPT Master — AI generates natively editable PPTX from any document
+
+[![Version](https://img.shields.io/badge/version-v2.9.0-blue.svg)](https://github.com/hugohe3/ppt-master/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/hugohe3/ppt-master.svg)](https://github.com/hugohe3/ppt-master/stargazers)
+[![AtomGit stars](https://atomgit.com/hugohe3/ppt-master/star/badge.svg)](https://atomgit.com/hugohe3/ppt-master)
+
+English | [中文](./README_CN.md)
+
+<p align="center">
+  <sub>This project is kept free and open source with the support of <a href="https://www.packyapi.com/register?aff=ppt-master">PackyCode</a>, <a href="https://apikey.fun/register?aff=PPT-MASTER">APIKEY.FUN</a> and other sponsors.</sub>
+</p>
+
+<table>
+  <tr>
+    <td width="180"><a href="https://www.packyapi.com/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" width="150"></a></td>
+    <td>Thanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more. PackyCode provides special discounts for our project users: register using <a href="https://www.packyapi.com/register?aff=ppt-master">this link</a> and enter the promo code <strong>ppt-master</strong> during recharge to get 10% off.</td>
+  </tr>
+  <tr>
+    <td width="180"><a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" width="150"></a></td>
+    <td>Thanks to APIKEY.FUN for sponsoring this project! APIKEY.FUN is a professional enterprise-grade AI relay service committed to stable, efficient, and low-cost AI access for businesses and developers. The platform supports mainstream models including Claude, OpenAI, and Gemini, with prices as low as <strong>7% of official rates</strong>. Register through <a href="https://apikey.fun/register?aff=PPT-MASTER">our dedicated link</a> for an exclusive perk: <strong>up to 5% off on top-ups, permanently</strong>.</td>
+  </tr>
+</table>
+
+> [!IMPORTANT]
+> ### This is a tool, not a wishing well
+> Don't expect it to hand you a finished, perfect deck in one shot. Its real value is taking most of the tedious work off your plate; the polishing that's left is yours — a natively editable deck exists precisely so you can keep working on it, not a flat image you can't touch. The cheaper the model, the more there is to do. How good the result turns out comes down to your skill with this project and with PowerPoint.
+
+<p align="center">
+  <a href="https://hugohe3.github.io/ppt-master/"><strong>Live Demo</strong></a> ·
+  <a href="https://www.hehugo.com/"><strong>About Hugo He</strong></a> ·
+  <a href="./examples/"><strong>Examples</strong></a> ·
+  <a href="./docs/faq.md"><strong>FAQ</strong></a> ·
+  <a href="./docs/roadmap.md"><strong>Roadmap</strong></a> ·
+  <a href="mailto:heyug3@gmail.com"><strong>Contact</strong></a>
+</p>
+
+<h3 align="center">Download the new <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_attention_is_all_you_need/exports/attention_is_all_you_need_narrated.pptx">narrated <em>Attention Is All You Need</em> deck</a> — play it in PowerPoint and every slide reads itself out loud. That's just the tip of what PPT Master can do.</h3>
+<h3 align="center">Of course, you can also download any of the six example decks below — opening the raw .pptx in PowerPoint is the fastest way to see this project's real capability ceiling.</h3>
+
+<table>
+  <tr>
+    <td align="center" width="33%">
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026"><img src="docs/assets/screenshots/preview_pritzker_2026.png" alt="Editorial magazine — Pritzker 2026 architecture review" /></a><br/>
+      <sub><b>Editorial Magazine</b> — architecture photography, calm typographic grid<br/>
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_pritzker_2026/exports/pritzker_2026.pptx">Download .pptx</a></sub>
+    </td>
+    <td align="center" width="33%">
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026"><img src="docs/assets/screenshots/preview_global_ai_capital.png" alt="Data journalism — Global AI Capital 2026" /></a><br/>
+      <sub><b>Data Journalism</b> — Bloomberg-style dark dashboard, chart-driven<br/>
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_global_ai_capital_2026/exports/global_ai_capital_2026.pptx">Download .pptx</a></sub>
+    </td>
+    <td align="center" width="33%">
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems"><img src="docs/assets/screenshots/preview_swiss_grid.png" alt="Swiss typographic grid — Grid Systems primer" /></a><br/>
+      <sub><b>Swiss Grid</b> — strict modular grid, restrained type, red-accent<br/>
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_swiss_grid_systems/exports/swiss_grid_systems.pptx">Download .pptx</a></sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="33%">
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo"><img src="docs/assets/screenshots/preview_glassmorphism_demo.png" alt="Glassmorphism SaaS — AI Agent engineering demo" /></a><br/>
+      <sub><b>Glassmorphism SaaS</b> — translucent layers, gradient depth, product UI<br/>
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_glassmorphism_demo/exports/glassmorphism_demo.pptx">Download .pptx</a></sub>
+    </td>
+    <td align="center" width="33%">
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis"><img src="docs/assets/screenshots/preview_sugar_rush_memphis.png" alt="Memphis pop — Sugar Rush festival" /></a><br/>
+      <sub><b>Memphis Pop</b> — bold primaries, geometric patterns, playful energy<br/>
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_sugar_rush_memphis/exports/sugar_rush_memphis.pptx">Download .pptx</a></sub>
+    </td>
+    <td align="center" width="33%">
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide"><img src="docs/assets/screenshots/preview_indie_bookstore_zine.png" alt="Risograph zine — Indie bookstore guide" /></a><br/>
+      <sub><b>Risograph Zine</b> — duotone print, hand-made bookstore-culture feel<br/>
+      <a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_indie_bookstore_zine_guide/exports/indie_bookstore_zine_guide.pptx">Download .pptx</a></sub>
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <sub>Generated with Claude Opus 4.7 + <code>gpt-image-2</code>. <a href="https://hugohe3.github.io/ppt-master/">Flip through all examples online →</a> · <a href="./examples/"><code>examples/</code> directory</a> · <a href="./docs/why-ppt-master.md">Why PPT Master?</a></sub>
+</p>
+
+---
+
+Drop in your source material and get back a **real PowerPoint**: directly editable, with native slide transitions and entrance animations, speaker notes you can turn into audio narration, and the option to follow your own PPT template — a complete deck you can present as-is and keep editing. How to use each capability → [Getting Started](./docs/getting-started.md).
+
+> **⚠️ PPT Master is a harness, not a complete agent.** `harness + model = agent` — the tool owns the workflow; the model sets the ceiling. To form a genuinely high-quality agent, use **Claude with a large context window (~1M tokens) + AI image generation (`gpt-image-2`)**. Other models can run the pipeline but cannot reach the same quality ceiling. If results disappoint, upgrade the model — don't blame the harness.
+
+> **How it works** — PPT Master is a workflow (a "skill") that works inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy. You chat with the AI — "make a deck from this PDF" — and it follows the workflow to produce a real editable `.pptx` on your computer. No coding on your side; the IDE is just where the conversation happens.
+>
+> **What you'll do**: install Python, install an AI IDE, drop in your material.
+
+> **Why it's shaped this way** — knowing how to use Python and AI agents will matter more and more. This project is meant to show how far you can go with just those two things. There's a learning curve if you're starting cold, but it's the curve worth climbing. Making a deck is just the excuse — what I'm really pushing is Python and agents.
+
+PPT Master is different:
+
+- **Real PowerPoint** — if a file can't be opened and edited in PowerPoint, it shouldn't be called a PPT. Every element PPT Master outputs is directly clickable and editable
+- **Transparent, predictable cost** — the tool is free and open source; the only cost is your AI model usage. As AI tools move to usage-based billing, you pay exactly what you consume — no separate PPT subscription added on top
+- **Data stays local** — your files shouldn't have to be uploaded to someone else's server just to make a presentation. Apart from AI model communication, the entire pipeline runs on your machine
+- **No platform lock-in** — your workflow shouldn't be held hostage by any single company. Works with Claude Code, Cursor, VS Code Copilot, and more; supports Claude, GPT, Gemini, Kimi, and other models
+
+AI presentation tools roughly fall into four categories. PPT Master only does the last one:
+
+| Category | Output | Editable element-by-element in PowerPoint? |
+|---|---|:---:|
+| Template fill-in | PPTX built from a fixed template | Partially — limited by the template |
+| Image-based | One large image per slide, packed into PPTX | ❌ each slide is a picture |
+| HTML presentation | Web-based deck | ❌ not a PPTX |
+| **Native editable (PPT Master)** | **Real DrawingML shapes, text boxes, charts** | ✅ click any element to edit |
+
+---
+
+## The person using it matters more
+
+The examples above were all made in a single pass — I didn't even refine them; spend some time polishing and it's a different story entirely. With the same PowerPoint, a designer can produce something stunning while most people only ever touch a few basic features — the difference isn't the tool, it's the person using it. If you can't get there yet, it's most likely that you haven't learned the workflow — start with [Getting Started](./docs/getting-started.md) and the example projects.
+
+The best results do need Claude. Before you call it expensive, think about what it would cost to hire someone to produce a deck at the same level. The project also supports GPT, Gemini, Kimi, and other models — the results simply differ. Expecting top-tier output while paying the lowest possible cost was never reasonable to begin with.
+
+---
+
+## Built by Hugo He
+
+I'm a finance professional (CPA · CPV · Consulting Engineer (Investment)) who regularly reviews and edits presentation decks. I wanted AI-generated slides to remain editable in PowerPoint, not flattened into images — so I built this.
+
+🌐 [Personal website](https://www.hehugo.com/) · 📧 [heyug3@gmail.com](mailto:heyug3@gmail.com) · 🐙 [@hugohe3](https://github.com/hugohe3)
+
+---
+
+## Quick Start
+
+### 1. Prerequisites
+
+**You only need Python and uv.** uv is a Python package manager. `uv sync` installs all dependencies into an isolated virtual environment — no global pollution.
+
+| Dependency | Required? | What it does |
+|------------|:---------:|--------------|
+| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **Yes** | Core runtime |
+| [uv](https://docs.astral.sh/uv/getting-started/installation/) | ✅ **Yes** | Python package manager — isolated environments, no global pollution |
+
+> **TL;DR** — Install Python and uv, run `uv sync`, and you're ready to generate presentations.
+
+<details open>
+<summary><strong>Windows</strong> — see the dedicated step-by-step guide ⚠️</summary>
+
+Windows requires a few extra steps (PATH setup, execution policy, etc.). We wrote a **step-by-step guide** specifically for Windows users:
+
+**📖 [Windows Installation Guide](./docs/windows-installation.md)** — from zero to a working presentation in 10 minutes.
+
+Quick version: download Python from [python.org](https://www.python.org/downloads/) → **check "Add to PATH"** during install → install [uv](https://docs.astral.sh/uv/getting-started/installation/) → `uv sync` → done.
+</details>
+
+<details>
+<summary><strong>macOS / Linux</strong> — install and go</summary>
+
+```bash
+# macOS
+brew install python uv
+uv sync
+
+# Ubuntu / Debian
+sudo apt install python3
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync
+```
+</details>
+
+<details>
+<summary><strong>Edge-case fallback</strong> — 99% of users don't need this</summary>
+
+**Pandoc** — only needed for legacy document formats: `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`, `.html`, `.epub`, `.ipynb` are handled natively by Python — no pandoc required.
+
+```bash
+# macOS
+brew install pandoc
+
+# Ubuntu / Debian
+sudo apt install pandoc
+```
+</details>
+
+### 2. Pick an Agent
+
+PPT Master runs in **any tool with agent capability** — read/write files, execute commands, and sustain multi-turn conversation.
+
+| Type | Examples | Notes |
+|---|---|---|
+| **IDE-native agent** | • VS Code architecture ([VS Code](https://code.visualstudio.com/) itself, plus forks & derivatives): [Cursor](https://cursor.sh/), Trae, Codebuddy IDE, [Windsurf](https://codeium.com/windsurf), Void, etc.<br>• Other architectures: [Zed](https://zed.dev/), etc. | Editor with a built-in agent |
+| **IDE plugin / extension** | [GitHub Copilot](https://github.com/features/copilot), [Claude Code](https://claude.ai/code) (VS Code / JetBrains extension), [Cline](https://cline.bot/), [Continue](https://continue.dev/), Roo Code, etc. | Installed inside hosts like VS Code or JetBrains |
+| **CLI agent** | [Claude Code](https://claude.ai/code) CLI, [Codex CLI](https://github.com/openai/codex), [Aider](https://aider.chat/), Gemini CLI, etc. | Runs in the terminal; suits scripting, remote, or server use |
+
+> **Model recommendation**: for the best results, use **Claude Opus** with `gpt-image-2`; **Gemini 3.5 Flash** currently offers great overall value for money — notably fast and well worth a try.
+
+**🔑 Want to use Claude / GPT / Gemini but don't have access yet?** Project sponsors **[PackyCode](https://www.packyapi.com/register?aff=ppt-master)** and **[APIKEY.FUN](https://apikey.fun/register?aff=PPT-MASTER)** can help — both offer pay-as-you-go access to Claude, GPT, Gemini and more, no subscription required. **PackyCode**: 10% off with promo code **`ppt-master`** at top-up. **APIKEY.FUN**: prices as low as **7% of official rates**; register via our link for an exclusive permanent discount of up to 5% on top-ups.
+
+### 3. Set Up
+
+**Option A — Download ZIP** (no Git required): click **Code → Download ZIP** on the [GitHub page](https://github.com/hugohe3/ppt-master), then unzip.
+
+**Option B — Git clone** (requires [Git](https://git-scm.com/downloads) installed):
+
+```bash
+git clone https://github.com/hugohe3/ppt-master.git
+cd ppt-master
+```
+
+Then install dependencies:
+
+```bash
+uv sync
+```
+
+> ⚠️ **Two install options**:
+>
+> **Local build** (from repo root):
+> ```bash
+> uv build --wheel                                    # Pre-build (~4min, one-time)
+> mv dist/ppt_master-*.whl dist/ppt-master-latest-py3-none-any.whl
+> uv tool install ppt-master-latest-py3-none-any.whl  # Installs instantly
+> ```
+>
+> **Direct download** (no repo needed):
+> ```bash
+> curl -LO https://github.com/elvisw/ppt-master/releases/latest/download/ppt-master-latest-py3-none-any.whl
+> uv tool install ppt-master-latest-py3-none-any.whl
+> ```
+
+To update later (Option A / B): `uvx ppt-master update-repo`
+
+> **Option C — Skill marketplace**: the repo ships `.claude-plugin/marketplace.json`, so it can be installed through the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem:
+>
+> ```bash
+> # Cross-agent CLI (Claude Code, Cursor, Codex, etc.)
+> npx skills add hugohe3/ppt-master
+>
+> # Or inside Claude Code
+> /plugin marketplace add hugohe3/ppt-master
+> /plugin install ppt-master@ppt-master
+> ```
+>
+> Both install paths above only fetch the skill files (not the full repo); you still need to `uv sync` from the installed location for the post-processing scripts to run.
+
+### 4. Create
+
+**Provide source materials (recommended):** Place your PDF, DOCX, images, or other files in the `projects/` directory, then tell the AI chat panel which files to use. The quickest way to get the path: right-click the file in your file manager or IDE sidebar → **Copy Path** (or **Copy Relative Path**) and paste it directly into the chat.
+
+```
+You: Please create a PPT from projects/q3-report/sources/report.pdf
+```
+
+**Paste content directly:** You can also paste text content straight into the chat window and the AI will generate a PPT from it.
+
+```
+You: Please turn the following into a PPT: [paste your content here...]
+```
+
+Either way, the AI will first confirm the design spec:
+
+```
+AI:  Sure. Let's confirm the design spec:
+     [Template] B) Free design
+     [Format]   PPT 16:9
+     [Pages]    8-10 pages
+     ...
+```
+
+The AI handles everything — content analysis, visual design, SVG generation, and PPTX export.
+
+> **Output:** Native-shapes `.pptx` (directly editable) saved to `exports/<name>_<timestamp>.pptx`. A copy of `svg_output/` is always snapshotted to `backup/<timestamp>/svg_output/` for re-export / archival. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` (see [FAQ](./docs/faq.md)). Requires Office 2016+.
+
+> **Already have a `.pptx` you want to reuse?** Hand the AI that deck plus your material and ask it to "fill this deck with the new content" — it fills text, table, and chart data into your existing design and exports only the pages you pick, staying natively editable. See the [FAQ](./docs/faq.md) and [template-fill workflow](./skills/ppt-master/workflows/template-fill-pptx.md).
+
+> **AI lost context?** Ask it to read `skills/ppt-master/SKILL.md`.
+
+> **Something went wrong?** Check the **[FAQ](./docs/faq.md)** — it covers model selection, layout issues, export problems, and more. Continuously updated from real user reports.
+
+### 5. Image Acquisition (Optional)
+
+Two paths for non-user images, mixable per row in the same deck:
+
+For API-backed features, put credentials in `.env`. Clone installs can use `cp .env.example .env`; skill marketplace installs should use a persistent user config:
+
+```bash
+mkdir -p ~/.ppt-master
+cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env
+```
+
+PPT Master reads the current process environment first, then the first `.env` found in this order: current working directory, skill directory (e.g. `~/.agents/skills/ppt-master/.env`), clone repo root, `~/.ppt-master/.env`.
+
+**A) AI generation** — `image_gen.py`. Set `IMAGE_BACKEND` plus the provider's `*_API_KEY` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.), and the pipeline calls it automatically. Run `uvx ppt-master image-gen --list-backends` for the full backend list. `gpt-image-2` is currently the best default.
+
+**B) Web image search** — `image_search.py`. **Zero-config works**, but configure `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) for higher-quality results. Without keys, search uses Openverse / Wikimedia Commons only; this is useful as a fallback, but image quality can be uneven because many results are ordinary user uploads. With keys, the default provider chain also appends Pexels / Pixabay, which materially improves modern stock photography, people, workplace, lifestyle, and illustration coverage. The default is quality-first: CC0, Public Domain, Pexels / Pixabay no-attribution licenses, CC BY, and CC BY-SA are considered together, and Executor adds a small inline credit whenever the selected image requires attribution. Use `--strict-no-attribution` only when a slide cannot tolerate any credit line. For high-impact covers, product shots, portraits, and branded scenes, prefer this order: user-provided high-resolution assets / AI generation > web search with Pexels / Pixabay keys > zero-config web search.
+
+> Full reference: [`image-generator.md`](./skills/ppt-master/references/image-generator.md) (AI) · [`image-searcher.md`](./skills/ppt-master/references/image-searcher.md) (web).
+
+---
+
+## Documentation
+
+| | Document | Description |
+|---|----------|-------------|
+| 📘 | [Getting Started](./docs/getting-started.md) | First deck in 3 steps, plus how to use templates, live preview, animations, narration, voice cloning (**new users start here**) |
+| 🆚 | [Why PPT Master](./docs/why-ppt-master.md) | How it compares to Gamma, Copilot, and other AI tools |
+| 🪟 | [Windows Installation](./docs/windows-installation.md) | Step-by-step setup guide for Windows users |
+| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules |
+| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |
+| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands |
+| 💼 | [Examples](./examples/README.md) | All example projects |
+| 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |
+| ❓ | [FAQ](./docs/faq.md) | Model selection, cost, layout troubleshooting, custom templates |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
+
+## License
+
+[MIT](LICENSE)
+
+## Acknowledgments
+
+[SVG Repo](https://www.svgrepo.com/) · [Tabler Icons](https://github.com/tabler/tabler-icons) · [Simple Icons](https://github.com/simple-icons/simple-icons) · [Phosphor Icons](https://github.com/phosphor-icons/core) · [Robin Williams](https://en.wikipedia.org/wiki/Robin_Williams_(author)) (CRAP principles)
+
+## Contact & Collaboration
+
+Looking to collaborate, integrate PPT Master into your workflow, or just have questions?
+
+- 💬 **Questions & sharing** — [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)
+- 🐛 **Bug reports & feature requests** — [GitHub Issues](https://github.com/hugohe3/ppt-master/issues)
+- 🌐 **Learn more about the author** — [www.hehugo.com](https://www.hehugo.com/)
+
+---
+
+## Star History
+
+<a href="https://star-history.com/#hugohe3/ppt-master&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date" />
+ </picture>
+</a>
+
+---
+
+## Sponsors & Support
+
+PPT Master is currently built and maintained primarily by me. Every new template, bug fix, and documentation update takes ongoing resources — currently shared by the sponsors and individual supporters below.
+
+**Corporate sponsors**
+
+<a href="https://www.packyapi.com/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" height="40" /></a>
+&nbsp;
+<a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" height="40" /></a>
+&nbsp;
+<a href="https://m.do.co/c/547f129aabe1"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_blue.svg" alt="Powered by DigitalOcean" height="40" /></a>
+
+**Individual support**
+
+If PPT Master has been helpful to you, individual support of any amount helps keep the project moving and free.
+
+<a href="https://paypal.me/hugohe3"><img src="https://img.shields.io/badge/PayPal-Sponsor-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="Sponsor via PayPal" /></a>
+
+<img src="docs/assets/alipay-qr.jpg" alt="Alipay QR Code" width="220" />
+
+---
+
+Made with ❤️ by [Hugo He](https://www.hehugo.com/) — if this project helps you, please give it a ⭐ and consider [sponsoring](#sponsors--support).
+
+<sub>Official distribution: <a href="https://github.com/hugohe3/ppt-master">GitHub</a> (primary) · <a href="https://atomgit.com/hugohe3/ppt-master">AtomGit</a> (mirror). Redistributions on other platforms are unofficial. MIT licensed — attribution required.</sub>
+
+[⬆ Back to Top](#ppt-master--ai-generates-natively-editable-pptx-from-any-document)