LearnPrompt/humanize-ppt

Humanize PPT – AI‑driven “talk‑able” slide decks

What it is – Humanize PPT is a small Python‑based orchestration layer that turns raw material (Markdown, notes, data) into a presentation‑ready slide deck. It does not render the visual design itself; instead it decides how the story should flow (the “AST” – Audience‑State‑Transfer outline), which pages need images, SVG charts or short videos, and then hands off those decisions to downstream rendering skills (HTML‑slide generators, native PowerPoint exporters, Remotion video producers, etc.). After rendering it runs an automatic presentation‑check that flags pages that are “pretty but can’t be spoken” (e.g., text hidden by a badge, missing speaker notes) and produces fix‑prompts for the renderer.

---

Core ideas

Concept	What Humanize PPT does
AST outline	Parses the source material and produces a JSON plan (slide_plan.json) that records, for each slide, the audience’s starting state, the intended state after the slide, and the slide’s intent.
Visual enhancement	For each slide it decides whether an image, deterministic SVG chart, or a Remotion video is needed and writes the request (prompt hint + target path) into the plan. The actual assets are generated by plug‑in skills such as baoyu-image-gen (local Codex CLI) or remotion-video-production.
Style gallery	Before the outline is fixed it can ask a renderer to produce ≥ 4 cover‑page candidates, letting the user pick a visual style without committing to a full deck.
Presentation check‑up	After the downstream renderer finishes, Humanize PPT scans the output, compares it to the AST plan, and automatically reports “failed” slides (e.g., text overflow, badge covering text, missing speaker notes). It emits a fix_prompt.md that can be fed back to the renderer for a second pass (max 3 iterations).
Presentation mode	Generates a lightweight HTML presenter (presenter-shell.html) that shows the current slide, a timer, speaker notes, next‑slide preview and a slide‑map, so you can rehearse even before the final deck is rendered.

---

How it fits into an AI‑agent workflow

1. Install as a skill – Agents like Claude‑Code, Codex, or Hermes can add the skill with a single line (npx skills add LearnPrompt/humanize-ppt).
2. Prompt the agent – “Use Humanize PPT to turn this markdown into a Chinese PPT, then render with guizang-ppt-skill, add images with baoyu-image-gen, and make a video with Remotion.”
3. Humanize PPT runs – It creates the AST plan, writes a brief (guizang-production-prompt.md, ppt-master-production-prompt.md, …) and hands it to the chosen renderer.
4. Renderer produces the deck – HTML slide set, native .pptx, or a set of MP4 videos.
5. Automated QA – Humanize PPT reads the rendered files, runs its three‑round check‑up, and returns a concise report (qa_report.md) plus any fix prompts.
6. Iterate or present – Either feed the fix prompts back to the renderer or jump straight into the presenter shell to rehearse.

---

Main components (as described in the repo)

• scripts/humanize_ppt.py – CLI entry point. Accepts a source markdown, output folder, title, renderer choice, style flags, etc.
• slide_plan.json – Machine‑readable plan that lists every slide, its AST state, media slots, and any style choices.
• presenter-shell.html – Minimal HTML presenter that works with any rendered deck; shows slide, timer, speaker notes, and navigation.
• qa_report.md / fix_prompt.md – Human‑readable diagnostics and the exact prompts to ask the downstream renderer to fix a problem.

---

Ecosystem of downstream skills (the repo lists them as required for a full pipeline)

Skill	What it renders	Repo
guizang-ppt-skill	Chinese native PPT (magazine / Swiss style)	https://github.com/op7418/guizang-ppt-skill
frontend-slides	English HTML slide deck (viewport‑safe)	https://github.com/zarazhangrui/frontend-slides
beautiful-html-templates	English multi‑template HTML decks	https://github.com/zarazhangrui/beautiful-html-templates
ppt-master	Fully editable .pptx (DrawingML, notes, transitions)	https://github.com/hugohe3/ppt-master
remotion-video-production	Per‑slide explanatory MP4 videos	(Remotion ecosystem)
baoyu-image-gen	Local Codex‑CLI image generation (no API key)	https://github.com/JimLiu/baoyu-skills/tree/main/skills/baoyu-image-gen

---

Quick‑start example (from the README)

# Install the skill for an agent
npx skills add LearnPrompt/humanize-ppt -g

# Run the whole pipeline in one prompt to an agent
"用 humanize-ppt 把这份材料做成中文演讲 PPT：先出 AST 大纲和每页意图，
按大纲调 guizang-ppt-skill 原生渲染，配图用 baoyu-image-gen、视频用 remotion，
渲染完跑一遍演讲体检告诉我哪几页只能看不能讲，最后出演讲模式。"

The agent will:

1. Call humanize_ppt.py → produces guizang-production-prompt.md.
2. Invoke guizang-ppt-skill → gets a beautiful HTML/PPTX deck.
3. Run baoyu-image-gen & Remotion for media assets.
4. Run Humanize’s QA step → receives a list of problem slides.
5. Optionally re‑run the renderer with the generated fix prompt.
6. Open presenter-shell.html for rehearsal.

---

What you get

• AST‑driven slide plan (slide_plan.json).
• Renderer‑specific brief (*-production-prompt.md).
• Optional style‑gallery HTML for picking a cover style.
• Media assets (real images, SVG charts, MP4 videos) placed in the paths you specified.
• QA report (qa_report.md) that pinpoints “only‑look‑but‑can’t‑talk” slides.
• Editable native PPTX (when using ppt-master) or a ready‑to‑present HTML deck.
• Presenter shell for on‑the‑fly rehearsals.

---

License

MIT – free to use, modify, and integrate into other AI‑agent toolchains.

---

Bottom line

Humanize PPT is not a visual template library; it is the story‑orchestration layer that makes AI‑generated slide decks talkable. By separating content planning (AST) from visual rendering, and by providing an automated “presentation health check”, it lets LLM‑powered agents produce decks that are both attractive and ready for a live talk.