deckbuilder 1.0.0b1

Intelligent PowerPoint presentation generation with content-first design philosophy, PlaceKitten image processing, and comprehensive CLI tools

🎯 Deckbuilder

Transform LLMs from layout pickers into presentation consultants

Deckbuilder is a powerful Python library and MCP (Model Context Protocol) server for intelligent PowerPoint presentation generation. Built with a content-first design philosophy, Deckbuilder transforms how AI creates presentations by focusing on what you want to communicate rather than just what layouts exist.

✨ Key Features

🚀 One-Shot Presentation Generation

Create complete PowerPoint presentations from JSON or Markdown with YAML frontmatter in a single command.

🎨 Rich Content Support

• Advanced Formatting: **bold**, *italic*, ___underline___, ***bold italic***
• Mixed Content: Seamlessly combine headings, paragraphs, and bullet points
• Professional Tables: Custom styling with themes and colors
• 50+ Business Layouts: Progressive library of professional presentation templates

🖼️ Smart Image Processing

• PlaceKitten Integration: Professional placeholder generation with computer vision
• Intelligent Fallbacks: Automatic handling of missing/invalid images
• Smart Cropping: Face detection and rule-of-thirds composition
• Professional Filters: 10+ effects optimized for business presentations
• Performance Optimized: <2s generation, intelligent caching

⚡ Enhanced CLI Experience

• One-Command Setup: deckbuilder init creates templates and configuration
• Smart Defaults: Intuitive file paths and environment resolution
• Tab Completion: Bash completion for commands, templates, and files
• Global Arguments: -t/--templates and -o/--output for custom paths
• Template Management: Analyze, validate, and enhance PowerPoint templates

🎯 Content-First Intelligence

Instead of asking "what layouts exist?", Deckbuilder asks "what do you want to communicate?" This transforms the system from a layout picker into an intelligent presentation consultant.

🚀 Quick Start

Installation

pip install deckbuilder

CLI Usage (Standalone)

# Initialize templates (one-time setup)
deckbuilder init

# Create presentation from markdown
deckbuilder create presentation.md

# Template management
deckbuilder analyze default --verbose
deckbuilder templates

# Image generation
deckbuilder image 800 600 --filter grayscale

# Get help
deckbuilder --help

MCP Server (Claude Desktop)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "deckbuilder": {
      "command": "deckbuilder-server",
      "env": {
        "DECK_TEMPLATE_FOLDER": "/Users/username/Documents/Deckbuilder/Templates",
        "DECK_TEMPLATE_NAME": "default",
        "DECK_OUTPUT_FOLDER": "/Users/username/Documents/Deckbuilder"
      }
    }
  }
}

📝 Usage Examples

Markdown with Frontmatter (Recommended)

---
layout: Title Slide
---
# **Deckbuilder** Presentation
## Creating presentations with *content-first* intelligence

---
layout: Four Columns
title: Feature Comparison
columns:
  - title: Performance
    content: "**Fast** processing with optimized algorithms"
  - title: Security
    content: "***Enterprise-grade*** encryption and compliance"
  - title: Usability
    content: "*Intuitive* interface with minimal learning curve"
  - title: Cost
    content: "___Transparent___ pricing with proven ROI"
---

---
layout: Picture with Caption
title: Market Analysis
media:
  image_path: "charts/revenue_growth.png"  # Auto-fallback to PlaceKitten if missing
  alt_text: "Revenue growth chart"
  caption: "**Q4 Revenue Growth** - 23% increase"
---

JSON Format (Programmatic)

{
  "presentation": {
    "slides": [
      {
        "type": "Title Slide",
        "title": "**Deckbuilder** Presentation",
        "subtitle": "Content-first presentation generation"
      },
      {
        "type": "Title and Content",
        "title": "Key Benefits",
        "content": [
          "**Intelligent** content analysis",
          "*Semantic* layout recommendations",
          "***Professional*** template system"
        ]
      }
    ]
  }
}

Python API

from deckbuilder import Deckbuilder

# Initialize engine
db = Deckbuilder()

# Create from markdown
result = db.create_presentation_from_markdown(
    markdown_content=open("presentation.md").read(),
    fileName="My_Presentation"
)

# Create from JSON
result = db.create_presentation(
    json_data={"presentation": {"slides": [...]}},
    fileName="JSON_Presentation"
)

print(f"✅ Created: {result}")

🖼️ PlaceKitten Image Processing

Smart Image Fallback System - When images are missing or invalid, PlaceKitten automatically generates professional placeholders:

from placekitten import PlaceKitten

pk = PlaceKitten()
placeholder = (pk.generate(1920, 1080, image_id=1)
                .smart_crop(1920, 1080)
                .apply_filter("grayscale")
                .save("professional_placeholder.jpg"))

Features:

• ✅ File Validation: Checks image existence, format, and accessibility
• ✅ Professional Styling: Automatic grayscale filtering for business context
• ✅ Smart Cropping: Computer vision-based cropping with face detection
• ✅ Performance Optimized: Intelligent caching prevents duplicate processing
• ✅ Seamless Integration: Zero user intervention required

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                    MCP Server Layer                 │
│  ┌─────────────────┐        ┌────────────────────┐  │
│  │   FastMCP       │        │   Content-First    │  │
│  │   Endpoints     │◄──────►│   MCP Tools        │  │
│  └────────┬────────┘        └────────────────────┘  │
│           │                                         │
├───────────┴─────────────────────────────────────────┤
│                 Presentation Engine                 │
│  ┌─────────────────┐        ┌────────────────────┐  │
│  │  PowerPoint     │        │   Template         │  │
│  │  Generation     │◄──────►│   Management       │  │
│  └────────┬────────┘        └────────────────────┘  │
│           │                                         │
├───────────┴─────────────────────────────────────────┤
│                Content Intelligence                 │
│  ┌─────────────────┐        �┌────────────────────┐  │
│  │  Layout         │        │   PlaceKitten      │  │
│  │  Intelligence   │◄──────►│   Processing       │  │
│  └─────────────────┘        └────────────────────┘  │
└─────────────────────────────────────────────────────┘

🎨 Supported Layouts

✅ Currently Implemented

• Title Slide - Opening slide with title and subtitle
• Title and Content - Rich text with headings, paragraphs, bullets
• Four Columns - Quad content areas with structured frontmatter
• Two Content - Side-by-side content areas
• Comparison - Left vs right comparison layout
• Table - Data tables with professional styling
• Section Header - Divider slides between topics
• Picture with Caption - Image-focused slides with smart fallbacks

🚧 Progressive Implementation (50+ Planned)

• Big Number displays, SWOT Analysis, Feature Matrix
• Timeline, Process Flow, Organizational Chart
• Dashboard, Metrics, Financial layouts
• And 40+ more business presentation layouts

See Supported Templates for complete roadmap.

🛠️ Development

Prerequisites

• Python 3.11+
• Virtual environment (recommended)

Development Install

git clone https://github.com/teknologika/deckbuilder.git
cd deckbuilder
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .[dev]

Code Quality Standards

# Format code (required before commits)
black --line-length 100 src/

# Check linting (required)
flake8 src/ tests/ --max-line-length=100 --ignore=E203,W503,E501

# Run tests (required)
pytest tests/

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Follow code quality standards
4. Add comprehensive tests
5. Submit pull request with clear description

📚 Documentation

• PLANNING.md - Project architecture and design principles
• API Documentation - Complete API reference
• Feature Specifications - Detailed feature documentation
• PlaceKitten Library - Image processing documentation

🔧 Technology Stack

• Python 3.11+ with modern type hints and comprehensive error handling
• FastMCP for Model Context Protocol server implementation
• python-pptx for PowerPoint generation and template manipulation
• PyYAML for structured frontmatter processing
• OpenCV + Pillow for computer vision and image processing
• pytest with 108 comprehensive tests including image integration

📋 Troubleshooting

Template not found:

# Create templates folder
deckbuilder init

# Check configuration
deckbuilder config

Permission denied when saving:

• Verify output folder has write permissions
• Ensure files aren't open in PowerPoint

MCP connection failures:

• Verify virtual environment is activated
• Check Python path in Claude Desktop config
• Ensure all dependencies are installed

📄 License

Apache License 2.0 - See LICENSE file for details.

---

Built with ❤️ for intelligent presentation generation

🚀 Get Started • 📖 Documentation • 🐛 Report Issues