Otter PPT

AI-Powered PPT Generation Engine — Building Editable PowerPoint via Tool Calls

English | 中文

📖 Introduction

Otter PPT is a tool-call-based AI Agent PPT generation engine.

Unlike traditional "one-shot JSON generation" approaches, Otter PPT encapsulates every PowerPoint design operation into callable tools, allowing AI to build presentations step by step — just like a human designer:

User: "Create a PPT about AI"
  ↓
AI Agent (function calling loop)
  ├── set_theme(primary_color="#1A73E8", ...)
  ├── add_slide(layout="title")           → returns slide_id
  ├── add_title(slide_id, text="The Future of AI")
  ├── set_bg_gradient(slide_id, ...)
  ├── add_slide(layout="title_content")   → returns slide_id
  ├── add_bullet_list(slide_id, items=[...])
  ├── add_chart(slide_id, chart_type="bar", ...)
  ├── add_shape(slide_id, shape_type="rounded_rectangle", ...)
  ├── set_transition(slide_id, type="fade")
  ├── set_animation(slide_id, element_id, type="fly_in")
  └── done()
  ↓
Presentation Object → PPTX Builder → Editable .pptx File

✨ Key Features

Feature	Description
🔧 42 Design Tools	A comprehensive toolset covering all PPT capabilities
🎨 Themes & Styles	Color schemes, fonts, gradient backgrounds
📝 Text & Typography	Titles, body text, bullet lists, rich text
🖼️ Visual Elements	Images, shapes (14 types), tables, charts, connectors
✨ Animations & Transitions	Element animations with timeline control, slide transition effects
↩️ Undo / Redo	Full operation history (50 steps) for every mutating tool
🛡️ Quality Gates	Text overflow / bounds / tiny-text detection, cover hero gate, strict export mode
📥 PPTX Import	Reverse-parse existing .pptx files into editable sessions; template extraction
🖋️ SVG Import	Compile SVG drawings into native PPTX geometry (freeform custGeom)
📐 Precise Positioning	Percentage-based coordinate system, resolution-independent
🏗️ Native PPTX	Direct OOXML generation, fully editable
🔤 Font embedding	Curated Google Fonts + CJK system fonts, subset embedding into PPTX
🌐 HTTP API	Built-in Gin server with REST API support
🔌 Multi-Protocol Integration	MCP, STDIO JSON-RPC, OpenAPI — works with Claude Code, Cursor, Codex, and custom software
📦 Python SDK	Lightweight Python client for automation
🖥️ CLI Tool	One-command PPT generation from the terminal

🔌 Integrating with Claude Code, Cursor, Codex & Custom Software

Start the MCP stdio service after building:

./bin/otter-ppt mcp

Configure in any MCP-compatible client:

{
  "mcpServers": {
    "otter-ppt": {
      "command": "/absolute/path/to/otter-ppt",
      "args": ["mcp"]
    }
  }
}

AI invocation is not mandatory: you can configure text/image models for Otter PPT to orchestrate, or have external models generate Presentation JSON or tool calls, then hand them to Otter PPT via /api/v1/build or /api/v1/execute. Other programs can also use otter-ppt stdio (JSON-RPC 2.0), or auto-generate clients via openapi.yaml. The Python client is located at sdk/python. The service runs as a local Go binary.

Full configuration and protocol details: INTEGRATION.md.

📚 Platform Tutorials

Platform	Tutorial
CLI (gen / serve / mcp)	CLI Tutorial
Claude Code (MCP)	Claude Code Tutorial
Cursor (MCP)	Cursor Tutorial
Codex / STDIO JSON-RPC	Codex / STDIO Tutorial
Python SDK	Python SDK Tutorial
REST API (curl / OpenAPI)	REST API Tutorial
Docker Deployment	Docker Tutorial

🚀 Quick Start

Prerequisites

Go 1.22+
An OpenAI-compatible API key (supports OpenAI / DeepSeek / other compatible services)

Installation

git clone https://github.com/Spark-Relics/Otter-PPT.git
cd Otter-PPT/otter-ppt
make build

CLI Generation

# Set API Key
export TEXT_MODEL_API_KEY="sk-your-key-here"

# Simple mode: fast, direct agent loop (no vision review)
./bin/otter-ppt gen \
  --topic "Future Trends of Artificial Intelligence" \
  --slides 10 \
  --style "tech, dark theme" \
  --language en \
  --mode simple \
  --output my_presentation.pptx

# Workflow mode: plan → build → AI visual review → refine (default)
./bin/otter-ppt gen \
  --topic "Future Trends of Artificial Intelligence" \
  --slides 10 \
  --mode workflow \
  --output my_presentation.pptx

Mode	Speed	Quality	How It Works
`simple`	⚡ Fast (~1 min/slide)	Good	Prompt → Agent tools → Auto-fix → PPTX
`workflow`	🐢 Slower (~3 min/slide)	Best	Plan → Build → Render → AI Vision Review → Refine → PPTX


### Start HTTP Server

```bash
export TEXT_MODEL_API_KEY="sk-your-key-here"   # only needed for /generate
./bin/otter-ppt serve --port 8080

Agent-native note: MCP (otter-ppt mcp) and STDIO (otter-ppt stdio) modes need no API key — your agent (Claude Code, Cursor, Codex…) brings its own LLM. The HTTP server is for web services and SDK integrations.

API usage examples:

# Generate PPT (requires API key)
curl -X POST http://localhost:8080/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"topic":"Artificial Intelligence","slides":8,"language":"en","style":"tech"}'

# Build PPTX from JSON (no API key needed)
curl -X POST http://localhost:8080/api/v1/build \
  -H "Content-Type: application/json" \
  -d @presentation.json \
  -o output.pptx

# Stateful editing session: create → execute → undo, no state round-trips
SESSION=$(curl -s -X POST http://localhost:8080/api/v1/session | jq -r .session_id)
curl -X POST http://localhost:8080/api/v1/session/$SESSION/execute \
  -H "Content-Type: application/json" \
  -d '{"calls":[{"name":"add_slide","arguments":{"layout":"blank"}}]}'
curl -X POST http://localhost:8080/api/v1/session/$SESSION/build -o output.pptx

# List available tools
curl http://localhost:8080/api/v1/tools

See INTEGRATION.md for the full session workflow (undo/redo, render, self-healing 400 errors) and openapi.yaml for the machine-readable contract.

Environment Check

./bin/otter-ppt doctor   # render backends, fonts, LLM config at a glance

🔧 Tool Reference

All tools available to the AI Agent:

Presentation Level

Tool	Description
`set_title`	Set presentation title
`set_theme`	Set global color scheme and fonts
`set_slide_size`	Set slide dimensions (16:9 / 4:3)

Slide Operations

Tool	Description
`add_slide`	Add a new slide
`delete_slide`	Delete a slide
`duplicate_slide`	Duplicate a slide
`move_slide`	Reorder slides
`set_notes`	Set speaker notes

Background

Tool	Description
`set_bg_color`	Set solid color background
`set_bg_gradient`	Set gradient background
`set_bg_image`	Set image background

Text

Tool	Description
`add_title`	Add a title
`add_text`	Add a text box
`add_bullet_list`	Add a bullet list

Visual Elements

Tool	Description
`add_image`	Add an image
`add_shape`	Add a shape (rectangle / oval / arrow / star, etc. — 14 types)
`add_table`	Add a table
`add_chart`	Add a native editable DrawingML chart (bar / line / pie / area / doughnut)
`add_connector`	Add a connector / arrow

Element Operations

Tool	Description
`update_text`	Update text content
`update_style`	Update font style
`update_position`	Update position and size
`delete_element`	Delete an element
`bring_to_front`	Bring to front
`send_to_back`	Send to back
`set_rotation`	Set rotation angle
`set_opacity`	Set opacity

Animation & Transitions

Tool	Description
`set_transition`	Set slide transition effect
`set_animation`	Set element animation

State & Export

Tool	Description
`get_state`	Get current state
`done`	Finish and export

📐 Coordinate System

All positions use percentage coordinates (0–100), relative to slide dimensions:

┌─────────────────────────────────┐
│ 0,0                        100,0│
│                                 │
│   ┌─── x,y ───┐                │
│   │            │                │
│   │   W × H    │                │
│   │            │                │
│   └────────────┘                │
│                                 │
│ 0,100                     100,100│
└─────────────────────────────────┘

x, y: Top-left corner coordinates
w, h: Width and height
Recommended content range: x+w ≤ 95, y+h ≤ 92

🏗️ Project Structure

otter-ppt/
├── cmd/
│   ├── otter-ppt/
│   │   └── main.go           # CLI entry point (serve / gen)
│   └── fontdl/
│       └── main.go           # Font download tool (Google Fonts + sysfonts)
├── internal/
│   ├── model/                # Data models
│   │   ├── presentation.go   # Presentation, Slide, Element
│   │   ├── slide.go          # ElementType, ShapeType, ChartType enums
│   │   ├── background.go     # Background, Gradient, Transition, Animation
│   │   ├── shape.go          # ShapeData, ChartData, ConnectorData
│   │   └── layout.go         # SlideLayout
│   ├── pptoolkit/            # ★ Core: PPT toolset
│   │   ├── session.go        # Session (thread-safe canvas)
│   │   ├── tools.go          # OpenAI tool definitions (42)
│   │   ├── handlers.go       # Tool dispatch and execution
│   │   └── schema.go         # JSON Schema build helpers
│   ├── agent/                # AI Agent + Workflow pipeline
│   │   ├── agent.go          # LLM ↔ tool call orchestration
│   │   ├── workflow.go       # Multi-phase: plan → build → review → refine
│   │   ├── planner.go        # Phase 1: LLM design planning
│   │   └── vision.go         # Phase 4: Multimodal visual evaluation
│   ├── builder/              # PPTX builder
│   │   ├── builder.go        # Main entry + helper functions
│   │   ├── content_types.go  # [Content_Types].xml
│   │   ├── presentation.go   # presentation.xml
│   │   ├── font_embed.go     # Font embedding (fntdata parts)
│   │   ├── theme_master.go   # theme + slideMaster + slideLayout
│   │   ├── slide.go          # Slide XML generation
│   │   └── elements.go       # Element XML (text/shape/table/chart/connector)
│   ├── fonts/                # ★ Font management
│   │   ├── registry.go       # Font discovery, metadata, catalog
│   │   ├── ttf.go            # TTF/OTF name table parser
│   │   └── builtin.go        # Built-in font recommendations
│   ├── server/               # HTTP API server
│   │   └── server.go         # Gin routes (incl. font endpoints)
│   ├── ai/                   # Legacy one-shot generation mode
│   │   └── generator.go
│   ├── imageutil/            # Image utilities
│   │   └── image.go
│   ├── renderer/             # Slide rendering for visual review
│   │   └── renderer.go       # LibreOffice → PDF → PNG (3-tier fallback)
├── go.mod
├── Makefile
└── README.md

🔑 Environment Variables

Variable	Description	Default
`TEXT_MODEL_API_KEY`	LLM API key (required)	Falls back to `OPENAI_API_KEY`
`TEXT_MODEL_BASE_URL`	LLM API endpoint	Falls back to `OPENAI_BASE_URL`
`TEXT_MODEL_NAME`	Text model name	Falls back to `OPENAI_MODEL`, then `gpt-4o`
`IMAGE_MODEL_API_KEY`	Image generation API key (optional)	-
`IMAGE_MODEL_BASE_URL`	Image generation endpoint	-
`IMAGE_MODEL_NAME`	Image model name	-

Compatible LLM Services

Set OPENAI_BASE_URL to use other compatible services:

# DeepSeek
export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export OPENAI_MODEL="deepseek-chat"

# Other compatible services
export OPENAI_BASE_URL="https://your-api.com/v1"

🔤 Font System

Otter PPT includes a built-in font management system that discovers, catalogues, and embeds fonts into PPTX output.

Features

Font Registry: Automatically scans assets/fonts/ for .ttf, .otf, and .ttc files
Metadata Parsing: Extracts font family name, PostScript name, weight, and subfamily from font files
PPTX Embedding: Fonts used in the presentation are embedded into the PPTX for cross-platform consistency
CJK Support: Detects and tags CJK fonts (Microsoft YaHei, SimSun, SimHei, KaiTi)
Built-in Catalog: 35+ recommended fonts (system, Google Fonts, open-source) as a reference
Custom Installation: Upload your own fonts via API or manually drop files in assets/fonts/

Downloading Curated Fonts

The cmd/fontdl tool downloads open-source fonts from Google Fonts and copies select Windows system CJK fonts:

# Download Google Fonts (20 Latin fonts) + Windows system CJK fonts
go run ./cmd/fontdl -dir assets/fonts -sysfonts

# Only Google Fonts
go run ./cmd/fontdl -dir assets/fonts

# Only system fonts (CJK)
go run ./cmd/fontdl -dir assets/fonts -no-gstatic -sysfonts

Downloaded Google Fonts: Inter, Montserrat, Roboto, Open Sans, Lato, Poppins, Raleway, Playfair Display, Merriweather, Lora, JetBrains Mono, Source Code Pro, Bebas Neue, Oswald, Dancing Script, Caveat

Copied System Fonts (Windows only): Microsoft YaHei, SimHei (黑体), SimSun (宋体), KaiTi (楷体)

Font API Endpoints

Endpoint	Method	Description
`/api/v1/fonts`	GET	List all installed fonts + built-in catalog
`/api/v1/fonts/scan`	POST	Re-scan fonts directory
`/api/v1/fonts/install`	POST	Upload and install a font file (`.ttf`, `.otf`, `.ttc`)

Install a Custom Font

curl -X POST http://localhost:8080/api/v1/fonts/install \
  -F "font=@MyCustomFont.ttf"

List Available Fonts

curl http://localhost:8080/api/v1/fonts

Adding Fonts Manually

Simply drop .ttf, .otf, or .ttc files into the assets/fonts/ directory and re-scan:

# Copy your font file
cp MyFont.ttf assets/fonts/

# Trigger a re-scan via API
curl -X POST http://localhost:8080/api/v1/fonts/scan

Font Categories

Category	Examples	Use Case
Sans-serif	Inter, Montserrat, Roboto, Open Sans	Modern UI, tech presentations
Serif	Playfair Display, Lora, Merriweather	Elegant, editorial, formal
Display	Bebas Neue, Oswald	Headlines, posters
Script	Dancing Script, Caveat	Decorative, creative
Mono	JetBrains Mono, Source Code Pro	Code snippets, technical
CJK	Microsoft YaHei, SimSun, SimHei, KaiTi	Chinese, Japanese, Korean

🔬 Visual Review Architecture

Otter PPT supports a multi-phase workflow (--mode workflow) that adds AI visual evaluation after the initial build:

Phase 1: PLAN     → LLM creates slide outline + design strategy
Phase 2: GATHER   → Pre-generate images in parallel (optional)
Phase 3: BUILD    → Agent tool-calling loop (same as simple mode)
Phase 4: REVIEW   → Render slides → send to vision AI → get design feedback
Phase 5: REFINE   → Agent fixes issues based on AI feedback
Phase 6: POLISH   → Final auto-fix + layout validation

Rendering Backends (3-tier fallback)

The renderer converts PPTX slides into images for the vision model to evaluate. It automatically selects the best available backend:

Tier	Backend	Output Quality	Dependencies	When to Use
1	LibreOffice headless	⭐⭐⭐ Perfect (true PPTX render)	`soffice` + `pdftoppm` in PATH	Server/Desktop with LibreOffice
2	HTML + system headless browser screenshot	⭐⭐ Good (full CSS rendering)	Chrome/Edge/Chromium/Firefox on system	Any desktop environment, zero download
3	Structural text description	⭐ Functional (JSON-like element dump)	None	Fallback when image API unsupported

Auto-detection: The renderer probes for soffice/libreoffice and pdftoppm at startup. If found, Tier 1 is used. If not, it falls back to Tier 2 (self-contained HTML rendering via the system's headless browser — Chrome/Edge on Windows, Chromium on Linux). If the vision model rejects images, Tier 3 sends structured text.

Installing LibreOffice (optional, for best quality)

Windows

Download from https://www.libreoffice.org/download/ and install. The soffice.exe will be auto-detected at:

C:\Program Files\LibreOffice\program\soffice.exe
C:\Program Files (x86)\LibreOffice\program\soffice.exe

For pdftoppm, install Poppler for Windows and add to PATH.

Linux / Docker

# Debian/Ubuntu
apt-get install -y libreoffice poppler-utils

# Alpine
apk add libreoffice poppler-utils

# Docker (add to Dockerfile)
RUN apt-get update && apt-get install -y libreoffice poppler-utils && rm -rf /var/lib/apt/lists/*

macOS

brew install --cask libreoffice
brew install poppler

Vision Evaluation Flow

PPTX → Best available renderer → Slide images (PNG, base64)
                                        ↓
                              Vision LLM (multimodal)
                                        ↓
                         { design_score, content_score,
                           issues[], suggestions[] }
                                        ↓
                    Agent.Refine() → update_position, update_style, etc.

If the vision model's overall score ≥ threshold (default 75), the presentation is accepted. Otherwise, feedback is fed back to the agent for up to MaxRefineRounds (default 2) iterations.

🗺️ Development Roadmap

📄 License

MIT License

📋 Changelog

v0.6.0

Atomic batch execution: session /execute now runs calls transactionally; any failure rolls back the entire batch, while a successful batch becomes one undo step.
Reliable idempotent retries: idempotency_key caches and replays both successful and rolled-back 422 responses, retaining 64 keys per session with FIFO eviction.
Concurrent duplicate suppression: concurrent requests using the same idempotency key execute only once; followers wait and replay the completed result.
Agent-friendly HTTP behavior: error responses include repairable examples and explicit rollback/retry guidance.
Tests and docs: added atomicity, failure-cache, and FIFO eviction coverage; synchronized OpenAPI and integration documentation.

v0.5.1

HTTP stateful sessions: POST /api/v1/session + /execute|render|build|undo|redo — server-side state with 30-min TTL; undo/redo now works over HTTP and iterative agents stop re-shipping full presentation JSON (see INTEGRATION.md)
Self-healing API errors: /execute 400s now include a valid example payload + session-mode hint; agents can self-correct from the error alone
Instant text overflow warnings: add_text / add_title / add_bullet_list return data.warnings (quality gate moved from export time to add time)
Style-aware add_card corner radius: cards follow the active style preset (swiss_minimal → sharp 0, soft_rounded → 0.15), no more design-lock conflicts
otter-ppt doctor: environment capability check (render backends, fonts, LLM config)
serve startup capability summary: render backend degradation is surfaced up front
Fixed otter-ppt --help / -h (previously "Unknown command")
OpenAPI: session endpoints + /api/v1/render documented

v0.5.0

Undo/redo operation history: every mutating tool call is snapshotted (50-deep stack); undo / redo available via MCP, STDIO, REST, and agent tool calls
Quality gates: text overflow / out-of-bounds / tiny-text detection with cover hero gate; export_pptx strict mode rejects decks with errors
PPTX import: import_pptx reverse-parses existing .pptx files (all element types, theme, notes, charts) into editable sessions
SVG import: import_svg compiles SVG drawings into native PPTX freeform geometry
Template extraction: load_template pulls palette/fonts/slide size/layout list from existing .pptx
Two-level design system: 7 style × 8 palette presets with design lock (typography role anchors, page rhythm discipline)
AI image rendering presets: 8 deck-wide rendering styles with prose prompt engineering (vector, watercolor, 3D isometric, etc.)
add_card tool, theme-aware shape text styling, chart ink adaptation for dark themes
Golden snapshot regression tests: 31 OOXML part baselines protect the builder against rendering regressions
Group transforms, animation timeline (duration/delay/order), font subsetting on PPTX embed
Visual style gallery: specimen decks per design style
Fixed PowerPoint "needs repair" errors caused by missing notesMaster part

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
cmd		cmd
docs		docs
examples		examples
internal		internal
scripts		scripts
sdk/python		sdk/python
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
INTEGRATION.md		INTEGRATION.md
Makefile		Makefile
README.md		README.md
README_CN.md		README_CN.md
go.mod		go.mod
go.sum		go.sum
icon.png		icon.png
openapi.yaml		openapi.yaml

Latest commit

History

Folders and files

Repository files navigation