nano-banana-ppt

Category: Content & Multimedia | Uploader: JoeSangAI | Downloads: 0 | Version: v1.0（Latest）
Use when creating professional PowerPoint presentations, generating slides from content/topics, or visualizing concepts into a deck with Nano Banana 2. Supports Template Cloning and AI Minting modes.
Changelog: Source: GitHub https://github.com/JoeSangAI/nano-banana-ppt
Directory Structure

Current level: Root
📁 nano_banana_ppt/
- 📁 agents/
  - 📄 __init__.py 0 B
  - 📄 narrative.py 32.6 KB
  - 📄 style_library.py 9.3 KB
  - 📄 template.py 13.8 KB
  - 📄 visual.py 32.3 KB
- 📁 core/
  - 📄 __init__.py 0 B
  - 📄 data_visualizer.py 14.4 KB
  - 📄 executor.py 16.8 KB
  - 📄 generator.py 55.2 KB
  - 📄 image_selector.py 14.1 KB
- 📁 tests/
  - 📄 test_image_selector.py 916 B
  - 📄 test_image_selector_logic.py 851 B
  - 📄 test_llm_client.py 1.4 KB
  - 📄 test_mixed_layout_locking.py 2.1 KB
- 📁 utils/
  - 📄 __init__.py 0 B
  - 📄 analyzer.py 4.5 KB
  - 📄 image_utils.py 1.3 KB
  - 📄 llm_client.py 5.6 KB
  - 📄 regenerate.py 3.2 KB
  - 📄 review_plan.py 38.1 KB
  - 📄 review_plan.py.patch 949 B
- 📄 __init__.py 0 B
- 📄 main.py 36.0 KB
📄 .gitignore 248 B
📄 CHANGELOG.md 19.2 KB
📄 README.md 11.7 KB
📄 requirements.txt 87 B
📄 SKILL.md 13.4 KB
SKILL.md

---
name: nano-banana-ppt
description: Use when creating professional PowerPoint presentations, generating slides from content/topics, or visualizing concepts into a deck with Nano Banana 2. Supports Template Cloning and AI Minting modes.
---

# Nano Banana PPT Generator (Advanced)

## Overview
Automates professional PowerPoint creation using Google's Nano Banana 2 (Gemini 3). This advanced version features a modular "Auto Pipeline" that supports:
1.  **Narrative Architecture**: Deep analysis of content to build logical story flows (using `NarrativeAgent`). Supports multiple narrative frameworks (SCQA, Golden Circle, Hero's Journey, etc.) and **speaker notes** (演讲备注) for detailed presenter guidance—screen text stays concise while rich context lives in notes.
2.  **Visual Prompt Engineering**: Sophisticated image generation prompts with style injection (using `VisualAgent`).
3.  **Template Cloning**: Extract style, logo, and layout from existing PDF/PPTX templates (using `TemplateAgent`).
4.  **AI Minting**: Automatically define and generate a cohesive visual style if no template is provided.
5.  **Charts, Infographics, and Editable Finishers**: Numeric data uses rendered charts (`bar` / `line` / `pie`), high-density structure can use `infographic`, and the final deck appends one pure-background helper slide plus two blank editable template slides for manual finishing when needed.

## 叙事与版面设计原则 (Narrative & Layout)

- **副标题按需**：金句页、封面可省略副标题；仅当能补充关键信息或承上启下时使用。
- **正文形态多样化**：`paragraph`（成段）、`bullets`（要点）、`data`（数据块）、`quote`（引用）、`mixed`（混合）。避免所有页面僵化为 bullet 列表。
- **呼吸页 (breathing)**：适当穿插轻页面——一个问句、一个数字或半屏留白+过渡语，给听众 3–5 秒消化时间。
- **密度交替**：信息页 ↔ 金句页 ↔ 数据页 ↔ 图/流程页，形成节奏。结合演讲内容自然交替，不为了节奏而节奏。
- **抬机率设计**：穿插可拍照页（金句、翔实数据、框架图、公式、行动指引）。结尾优先放一句可拍照金句。
- **数据表达策略**：趋势/比例优先用图表；高密度结构优先用 `infographic`；如果必须保留原始表格，建议最终贴入系统附赠的空白模板页中手工整理。

## Data, Infographics, and Manual Tables

| 类型 | 实现方式 | 特点 |
|------|----------|------|
| **图表** (visualization: bar/line/pie) | 图片渲染 | 由 Matplotlib 生成柱状/折线/饼图，风格与 style_config 一致 |
| **信息图** (`infographic`) | AI 结构化排版 | 适合高密度信息、全景图、模块化框架 |
| **原始表格保留** | 使用末尾两张空白模板页手工贴入 | 避免自动生成丑陋原生表格，同时保留编辑自由度 |

**不要承诺原生表格自动生成。** 当前推荐路径是：把数据重构为图表或 infographic；如果用户明确要保留表格原貌，则在最终 PPT 里使用空白模板页手工补齐。

## 原生图片排版 (Native Images Semantic Layout)

通过 `visual_plan.md` 中的 `- **📥 原生图片**：` 配置，支持在 AI 生成的背景上精准贴合原图。

**排版机制：**
1. **自动提取与智能选择**：`NarrativeAgent` 会自动提取源文档中的本地或网络图片（并下载），根据上下文严格判断相关性。只有强相关（如数据图表、新闻截图）才会保留。
2. **强制背景留白**：在生成背景的 Prompt 中，注入严厉的禁令（`CRITICAL VISUAL CONSTRAINT...`），强迫 AI 在指定区域（如左侧、右侧）留出不含任何文字和复杂图形的纯色安全区。
3. **视觉智能对齐 (VLM Layout)**：在背景生成后，调用 `Gemini 1.5 Pro`（视觉能力）去“看”一眼这页 PPT，根据背景上的留白和文字走势，计算出一个**完美的、带有安全边距的绝对居中坐标**，彻底避免图片压字或紧贴边缘的尴尬，实现真正的人类设计师级排版。
4. **完美比例缩放**：最后在插入 PPTX 时，严格保持原生图片的长宽比（Aspect Ratio），在 VLM 给定的安全框内等比缩放并绝对居中。

## When to Use
- User asks for "PPT", "slides", "deck", or "presentation".
- Converting existing documents/notes into slide format with high visual fidelity.
- **Cloning a style**: "Make it look like this PDF" or "Use this template".
- **Visualizing abstract concepts**: "Create a futuristic pitch deck".

## Workflow (Dual-Director Pipeline)

The pipeline is split into phases to allow human review before image generation (the expensive step).

### Pre-defined Style Library (内置风格库)
You can directly use these high-quality curated styles by passing their names to the `--style` argument or `style_preference` input:
- **`claude_minimalist`**: Warm, intellectual, approachable. Off-white/cream backgrounds, elegant typography mixing serif and sans-serif.
- **`neo_brutalism`** (新粗野主义): Raw, bold, unapologetic. High contrast, stark backgrounds, bright accents, thick black borders, hard offset shadows.
- **`japanese_aesthetic`** (日式美学): Zen, quiet, balanced. Muted earth tones, extreme negative space, asymmetrical balance.
- **`apple_keynote`**: Premium, cinematic. Deep black backgrounds, massive white typography, glowing gradients.
- **`liquid_glass`**: Premium glassmorphism with Bento Grid layouts and frosted translucent panels.
- **`magazine_editorial`**: Fashion/editorial layout with dramatic whitespace and serif-led typography.
- **`soft_3d_clay`**: Friendly inflated 3D clay aesthetic with soft pastel colors.
- **`dark_luxury`**: Premium dark background with metallic gold accents.
- **`traditional_chinese`**: Neo-Chinese aesthetic with ink wash, vermilion and jade accents.
- **`holographic_chrome`**: Y2K holographic chrome and iridescent gradients.
- **`cyberpunk`**: Dark, dystopian, high-tech. Deep navy/black with neon cyan, magenta, electric yellow.
- **`academic_paper`**: Clean, authoritative. White background, classic serif typography, formal grid structure.

### Phase 1.1: Content Plan (Copywriter Director)

```bash
python3 -m nano_banana_ppt.main plan-content <content_file> [template_file] [logo_file] [output_name] [--pages N] [--briefing "..."]
```
- **Copywriter Director** analyzes content, parses template, and generates narrative outline.
- Saves **content_plan.md** (人类可读的大纲草案，含各页标题/正文/演讲备注/配图建议).
- Stores all project assets under `output/ppt/<date>_<project_name>/`.
- Does NOT touch visual style at this stage.
- **Agent MUST present the content_plan.md outline to the user for confirmation before proceeding to Phase 1.5.**

### Phase 1.5: Visual Plan (Art Director)

```bash
python3 -m nano_banana_ppt.main plan-visual <project_dir> [--style "风格名称或描述"]
```
- **Art Director** reads confirmed content plan, generates a Design System Manifesto (defining shape, composition, color, and explicitly banning cliché AI elements).
- Saves **visual_plan.md** (完整的视觉计划 Markdown: 包含 Art Director 的 Manifesto、配色色板、以及各页的完整信息).
- NarrativeAgent 会：精细拆解章节、将详实论述放入演讲备注、用 hero 页突出金句。支持多种正文形态（paragraph/bullets/data/quote/mixed）、呼吸页、副标题按需、抬机率设计。
- Does NOT generate plan.json or visual prompts at this stage.
- **Agent MUST present the visual_plan.md outline and manifesto to the user for confirmation before proceeding to execute.**

### Phase 1.5: Prototype (Optional but Recommended)

```bash
python3 -m nano_banana_ppt.main prototype <project_dir_or_plan_md> [output_name] [--slides 1 2]
```
- Rapidly generates 1-2 slides to confirm the visual style and template integration before generating the entire deck.
- Helps validate that the Art Director's Cliche Avoidance and Theme rules are working effectively.

### Phase 2: Execute (Derives technical plan, generates images + assembles PPTX)

```bash
python3 -m nano_banana_ppt.main execute <project_dir_or_plan_md> [output_name] [--resolution 1K|2K|4K] [--slides 3 5 7]
```
- Accepts: project directory (e.g. `output/设定集`), `visual_plan.md`, or `plan.json`.
- If given visual_plan.md: parses MD → derives plan.json (LLM generates visual_prompts using the Design System Manifesto) → saves plan.json → generates images.
- Generates images via Gemini, assembles `.pptx`.

### Agent Workflow (CRITICAL — follow this exact sequence):
1. **Style Consultation (Interactive):** Before running any commands, ask the user if they have a preferred visual style. **Proactively list 3-4 relevant options** from the *Curated Style Library* (e.g., "Would you like a 'Claude Minimalist', 'Apple Keynote', or 'Liquid Glass' style?").
2. Run `plan-content` with user's content file.
3. **STOP. Present content_plan.md to the user and wait for confirmation.** (Read the file or summarize the terminal output.)
4. *(Optional) The Co-pilot Question (NotebookLM Integration):*
   - After generating `content_plan.md`, you MAY proactively ask the user: *"您现在生成了一版是我们这个 Skill 为您提供的叙事，那么您要不要同时也看一看 NotebookLM 原生的叙事会帮您怎么做？"*
   - If user agrees: Use the `notebooklm-automation` skill to generate an outline. Save it as `notebooklm_outline.md` in the project directory. Have the user fuse/modify, then write final result back into `content_plan.md`.
   - If user declines: Proceed to next step.
5. **Only after the user confirms content_plan.md**, run `plan-visual` with the project directory AND the selected `--style` (if any).
6. **⛔ HARD STOP. Present visual_plan.md to the user and WAIT.** Read the file and show the user: (a) the Art Director's Manifesto / 视觉主张, (b) the Color Palette with roles, (c) the Cliche Avoidance bans. Remind them they can edit `visual_plan.md` directly. **This stop applies even when the user selected a curated built-in style** (e.g. `apple_keynote`, `neo_brutalism`), because the Manifesto is content-specific and must be reviewed.
7. **Style Confirmation & Prototype Offer:** Ask the user if they want to prototype 1-2 slides (`prototype` command) to confirm the visual style before executing the full deck.
8. **⛔ HARD STOP. Wait for user confirmation.** Do NOT run `execute` or `prototype` in the same response/turn as `plan-visual`. You MUST end your turn after presenting visual_plan.md and wait for the user's next message.
9. **If the user wants to prototype**, run the `prototype` command and **STOP again**. Wait for the user to review the generated slides.
10. **Only after the user explicitly approves the prototype or plan (e.g., "确认" / "可以" / "开始生成" / "run execute")**, run `execute`.

**⛔ FORBIDDEN:** Running `plan-content` and `plan-visual` back-to-back without user confirmation of content_plan.md.
**⛔ FORBIDDEN:** Running `plan-visual` and `execute` back-to-back without user confirmation of visual_plan.md. This includes curated/built-in styles — the Manifesto is always content-specific and requires review.
**⛔ FORBIDDEN:** Running `plan-content → plan-visual → execute` in one go. Each phase MUST pause for human review.
**⛔ FORBIDDEN:** Using NotebookLM's native `generate slide-deck` to skip the `execute` phase. The final presentation MUST be generated using the native `nano_banana_ppt` `execute` command for high-quality visuals.

### Legacy: One-shot auto mode (interactive terminal only)
```bash
python3 -m nano_banana_ppt.main auto <content_file> [template_file] [logo_file] [output_name]
```

## Dependencies
- `openai` (used for Gemini compatibility)
- `pymupdf` (fitz, for template parsing)
- `python-pptx`
- `Pillow`
- `python-dotenv`
- `requests`

## Configuration
- `GOOGLE_API_KEY`: Recommended public configuration.
- `OPENAI_API_KEY` / `OPENAI_API_BASE`: Optional compatibility path for advanced users, but do not present it as the default public setup.

## Common Mistakes & Red Flags

| Mistake | Consequence | Fix |
|---------|-------------|-----|
| **Skipping Phase 1 review** | User gets unwanted content | ALWAYS show visual_plan.md outline to user and wait for confirmation before execute |
| **Chaining plan→execute without confirmation** | User cannot review/edit plan before costly image generation | NEVER run execute in the same turn as plan. STOP after plan, present outline, wait for "确认" |
| **Using .pptx as template** | May need LibreOffice for conversion | Prefer PDF templates, or ensure `soffice` is installed |
| **Missing API Key** | Script failure | Ensure `GOOGLE_API_KEY` is set |
| **Promising native editable tables** | User expects a feature the current pipeline no longer provides | Offer charts, infographic pages, or the final blank template slides for manual table insertion |
| **Manual XML editing** | Corrupt files | Always use the script |
| **Not providing Logo source** | No logo in output | Pass logo file alongside template |
| **Running `execute` without `plan`** | Missing plan file | Always run `plan` first; execute needs visual_plan.md or plan.json |
| **Ignoring gray slides** | API failures resulted in placeholder | Rerun with `--slides N` for failed pages (check terminal output for errors) |

## Stability Notes
- Default max_retries increased to 5 with exponential backoff (up to 48s wait).
- Max concurrent workers set to 2 to prevent API rate limiting.
- If specific slides fail (render as gray placeholders), use `execute ... --slides X Y` to regenerate only those slides.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
nano-banana-ppt

Directory Structure

SKILL.md

Report

Notice
