teknologika/Deckbuilder

[!IMPORTANT]
Deckbuilder is currently under active development and should NOT be considered production ready.

🎯 Deckbuilder

Create professional PowerPoint presentations from Markdown or JSON

Deckbuilder is a Python library, Command Line tool, and MCP server that generates PowerPoint presentations from structured content. Focus on your content - Deckbuilder handles the formatting and layout.

✨ 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***
• Language & Font updating: The ability to update the fonts and language of all slide objects using the command line tools using the CLI.
• Professional Tables: Custom styling with themes, colors, and precise dimension controls (column widths, row heights, table sizing).
• Supported Layouts: Progressive library of templates being added.

🧠 Smart Template System

• Intelligent Layout Selection: Automatic layout recommendations based on content type
• Pattern-Based Architecture: Customize any layout with your own templates
• Rich Content Support: Tables, images, multi-column layouts with professional styling

🖼️ Smart Image Processing

• Automatic Image Fallbacks: Missing images? Deckbuilder generates professional placeholders automatically
• Smart Cropping: Face detection and intelligent composition for perfect image sizing
• Professional Filters: Business-appropriate styling with grayscale and other effects

⚡ Enhanced CLI Experience

• Professional Hierarchical Interface: Clean command structure (deckbuilder <command> <subcommand>)
• One-Command Setup: deckbuilder init creates templates and configuration
• Context-Aware Paths: CLI args > env vars > current directory precedence
• Always Local Output: CLI outputs to current directory for predictable local development
• Global Arguments: -t/--template-folder, -l/--language, -f/--font for complete customisation
• Comprehensive Command Structure:
  • deckbuilder template → analyze, validate, document, enhance, list
  • deckbuilder config → show, languages, completion
  • deckbuilder image → generate, crop
  • deckbuilder remap → update existing PowerPoint files with language/font changes
• Template Management: Analyze, validate, and enhance PowerPoint templates with detailed validation

🚀 Quick Start

Installation

pip install deckbuilder

CLI Usage (Standalone)

# Initialize templates (one-time setup) This will create the default template and mapping JSON.
deckbuilder init

# Create presentation from markdown (outputs to current directory)
deckbuilder create presentation.md

# Use custom template folder (CLI arg overrides env vars)
deckbuilder --template-folder /custom/templates create presentation.md

# Create with custom language and font (supports both formats)
deckbuilder create presentation.md --language "es-ES" --font "Arial"
deckbuilder create presentation.md --language "Spanish (Spain)" --font "Times New Roman"

# View supported languages
deckbuilder config languages

# Template management & intelligence
deckbuilder template analyze default --verbose
deckbuilder template validate default
deckbuilder template list

# Smart template recommendations available through MCP tools

# Image generation with crop-first approach
deckbuilder image generate 800 600 --filter grayscale
deckbuilder image crop image.jpg 800 600

# Language and font remapping for existing PowerPoint files
deckbuilder remap existing.pptx --language en-US --font Arial

# View current configuration (shows path sources)
deckbuilder config show

# Get help
deckbuilder --help

MCP Server (Claude Desktop)

Add to your Claude Desktop configuration:

Option 1: Direct installation (recommended)

{
  "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",
        "DECK_PROOFING_LANGUAGE": "en-AU",
        "DECK_DEFAULT_FONT": "Calibri"
      }
    }
  }
}

New Environment Variables:

• DECK_PROOFING_LANGUAGE: Set proofing language for spell-check and grammar (accepts both "en-AU" and "English (Australia)" formats)
• DECK_DEFAULT_FONT: Set default font family for all presentations
• Default Language: Australian English (en-AU) if not specified

📝 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"
---

---
layout: Title and Content
title: "**Table Dimensions:** Custom Column Widths"
style: dark_blue_white_text
row_style: alternating_light_gray
border_style: thin_gray
column_widths: [8, 6, 4, 5]
row_height: 0.9
content: |
  Sales Performance Report with individual column width control:

  | **Product Category** | **Q1 Sales** | **Q2** | **Growth %** |
  | Enterprise Software | $125,000 | $142,000 | +13.6% |
  | SaaS Solutions | $89,500 | $98,200 | +9.7% |
  | Cloud Services | $156,000 | $178,000 | +14.1% |
  | Mobile Apps | $67,300 | $73,800 | +9.7% |
---

---
layout: Title and Content
title: "**Table Dimensions:** Equal Column Distribution"
style: light_blue_dark_text
row_style: alternating_light_gray
border_style: thin_gray
table_width: 22
row_height: 0.9
content: |
  Team Performance Dashboard with equal column distribution:

  | **Team Member** | **Projects** | **Completed** | **Success Rate** |
  | Alice Johnson | 25 | 24 | 96% |
  | Bob Smith | 18 | 17 | 94% |
  | Carol Davis | 32 | 31 | 97% |
  | David Wilson | 21 | 20 | 95% |

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"
        ]
      },
      {
        "type": "Title and Content",
        "title": "Team Performance Dashboard",
        "table": {
          "column_widths": [6, 4, 5, 3],
          "row_height": 1.8,
          "data": [
            ["**Team Member**", "**Projects**", "**Completed**", "**Rate**"],
            ["Alice Johnson", "25", "24", "96%"],
            ["Bob Smith", "18", "17", "94%"],
            ["Carol Davis", "32", "31", "97%"]
          ],
          "header_style": "dark_blue_white_text",
          "row_style": "alternating_light_gray",
          "border_style": "thin_gray"
        }
      }
    ]
  }
}

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}")

🌍 Language & Font Support

Supported Languages (20)

Deckbuilder supports 20 proofing languages for spell-check and grammar. You can use either locale codes (en-AU) or full names (English (Australia)):

# View all supported languages (shows both formats)
deckbuilder config languages

Available Languages:

• English (United States, United Kingdom, Canada, Australia)
• Spanish (Spain, Mexico, Latin America)
• French (France, Canada)
• German (Germany, Austria, Switzerland)
• Italian, Portuguese (Brazil, Portugal)
• Chinese (Simplified, Traditional), Japanese, Korean
• Dutch, Russian, Arabic

Font Customization

# Set language and font globally (supports both formats)
export DECK_PROOFING_LANGUAGE="en-AU"           # Locale code format
export DECK_PROOFING_LANGUAGE="English (Australia)"  # Full name format
export DECK_DEFAULT_FONT="Arial"

# Or use CLI arguments (both formats work)
deckbuilder create presentation.md --language "fr-CA" --font "Times New Roman"
deckbuilder create presentation.md --language "French (Canada)" --font "Arial"

# Check current settings (shows locale codes and descriptions)
deckbuilder config show

🖼️ 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

🚀 What's New in v1.2.0

Smart Template Recommendations

• Content Analysis: Automatically analyzes your content to suggest the best layouts
• MCP Integration: Available through Claude Desktop with intelligent recommendations

Enhanced Image Processing

• Better Image Sizing: Smart cropping ensures images fit perfectly without distortion
• Automatic Fallbacks: Professional placeholder images when your images are missing

Improved Pattern System

• User Customization: Create custom layout patterns in {template_folder}/patterns/
• Dynamic Loading: All layouts now use flexible pattern files instead of hard-coded templates

🏗️ Architecture

    Your Content (Markdown/JSON)
              ↓
    ┌─────────────────────┐
    │   Content Analysis  │  ← Analyzes your content type and audience
    └─────────┬───────────┘
              ↓
    ┌─────────────────────┐
    │ Template Selection  │  ← Recommends best layouts for your content
    └─────────┬───────────┘
              ↓
    ┌─────────────────────┐
    │  PowerPoint Engine  │  ← Generates professional presentations
    └─────────┬───────────┘
              ↓
    Your Professional Presentation

🎨 Supported Markdown 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 for detailed specifications.

🛠️ Development

Prerequisites

• Python 3.11+
• Virtual environments are 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

• - Full documentation index
• - Complete layout library (26+ patterns)
• - Python API reference and classes
• - CLI commands and usage examples
• - Smart template recommendations and MCP tools
• - Image processing with crop-first approach
• - Technical implementation details

🔧 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 for unit testing
• Anthropic Claude - for most of the development gruntwork :-)

📋 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 file for details.