<p align="center">
<h1 align="center">DeckForge</h1>
<p align="center"><strong>API-first presentation generation for humans and AI agents</strong></p>
</p>

<p align="center">
<a href="https://github.com/Whatsonyourmind/deckforge/actions/workflows/ci.yml"></a>

<a href="https://github.com/Whatsonyourmind/deckforge/blob/master/LICENSE"></a>
<a href="https://www.npmjs.com/package/@lukastan/deckforge"></a>
<a href="https://deckforge-api.onrender.com/v1/health"></a>




</p>

---

Executive-ready slides, one API call away. Send a JSON intermediate representation (IR) or a natural-language prompt and get back a .pptx file or Google Slides deck -- with professional layout, consistent branding, and verified quality.

---

> 🚀 Using DeckForge in production — or want higher limits, priority support, or a specific slide/chart capability?
> Tell me about your use case → — I read every one.

---

What this solves

- Your agent needs to turn a structured slide spec into a real PowerPoint — without a headless Office install or hand-written python-pptx code. Send a Presentation IR (slides, elements, theme) to render and get a themed .pptx (or Google Slides) deck plus a quality score and a count of layout/QA issues.
- Your agent needs a deck from a one-line prompt — without designing the narrative itself. generate runs a 4-stage content pipeline (intent → outline → expand → refine) that picks slide types and writes content, returning a structured IR you can then render.
- You need finance-flavored slides — without rebuilding DCF, comp-table, waterfall, or returns layouts every time. 9 finance slide types and finance-oriented chart types (waterfall, tornado, football field, sensitivity table) are first-class IR, so a model output of numbers becomes an auditable, themed slide.
- Your agent must choose valid slide_type, theme, and chart values at runtime — without guessing. themes (15) and slide_types (32: 23 universal + 9 finance, with required/optional elements) are discovery tools that return the exact identifiers and element requirements to build correct IR.
- You need a deterministic cost before spending on a render — without trial calls. cost_estimate computes credits from ceil(slides/10) plus per-finance-slide and per-chart surcharges, returning a breakdown and USD equivalent so an autonomous agent can budget before it acts.
- You want decks to be consistent and machine-checked — without a human design pass. Every render runs a QA pipeline with auto-fix for contrast, overflow, and alignment, and reports a quality_score and qa_issues count back to the caller.

---

Features

- 32 slide types -- title, agenda, bullet points, comparison, timeline, process flow, org chart, stats callout, table, chart, matrix, funnel, map, and more
- 9 finance-specific slides -- DCF summary, comp table, waterfall chart, deal overview, returns analysis, capital structure, market landscape, risk matrix, investment thesis
- 24 chart types -- bar, line, area, pie, donut, scatter, bubble, combo, waterfall, funnel, treemap, radar, tornado, football field, sensitivity table, heatmap, sankey, gantt, sunburst, and more
- 15 built-in themes -- corporate-blue, executive-dark, finance-pro, modern-gradient, minimal-light, tech-neon, and 9 others (plus custom brand kits)
- Native PPTX output -- python-pptx rendering with element-level control, transitions, and chart embedding
- Google Slides output -- direct export via Google Slides API (OAuth flow included)
- AI content generation -- natural-language to slides via Claude, OpenAI, Gemini, or Ollama (4-stage pipeline: intent, outline, expand, refine)
- 5-pass QA pipeline -- automated quality checks with auto-fix engine for contrast, overflow, alignment, and more
- Constraint-based layout -- kiwisolver constraint solver, 12-column grid, adaptive overflow (font reduce, reflow, split)
- MCP server -- 6 tools for AI agent integration (render, generate, themes, slide_types, cost_estimate, pricing)
- x402 payment middleware -- optional per-call USDC support (Base L2) for self-hosted deployments; disabled by default
- Billing infrastructure -- Stripe subscription + credit-system support for self-hosted deployments (no hosted paid plans are offered yet)
- TypeScript SDK -- @lukastan/deckforge with fluent builder pattern, full type safety, SSE streaming

Quick Start

Get from zero to your first rendered deck in under 5 minutes.

Prerequisites

- Docker and Docker Compose
- Git

Steps

# 1. Clone the repo
git clone https://github.com/Whatsonyourmind/deckforge && cd deckforge
2. Copy environment config (works out of the box for local dev)
cp .env.example .env
3. Start all services (API, workers, PostgreSQL, Redis, MinIO)
docker compose up -d
4. Initialize the database (runs migrations, seeds test user + API key)
bash scripts/bootstrap-db.sh
5. Verify the API is running
curl http://localhost:8000/v1/health
=> {"status":"healthy"}

The bootstrap script outputs a test API key (dk_test_...). Save it for the examples below.

API Examples

Render a deck from IR

curl -X POST http://localhost:8000/v1/render \
  -H "Authorization: Bearer dk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q4 Board Update",
    "theme": "corporate-blue",
    "slides": [
      {
        "slide_type": "title_slide",
        "elements": [
          {"type": "title", "content": "Q4 2026 Board Update"},
          {"type": "subtitle", "content": "Acme Corp -- Confidential"}
        ]
      },
      {
        "slide_type": "stats_callout",
        "elements": [
          {"type": "title", "content": "Key Metrics"},
          {"type": "metric", "content": "$4.2M", "label": "ARR"},
          {"type": "metric", "content": "142%", "label": "YoY Growth"},
          {"type": "metric", "content": "94%", "label": "Retention"}
        ]
      }
    ]
  }' \
  --output board-update.pptx

Generate a deck from natural language

curl -X POST http://localhost:8000/v1/generate \
  -H "Authorization: Bearer dk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 10-slide pitch deck for a B2B SaaS startup in the cybersecurity space, Series A, $2M ARR",
    "theme": "executive-dark",
    "output_format": "pptx"
  }' \
  --output pitch-deck.pptx

> Note: The /v1/generate endpoint requires at least one LLM API key configured in .env (Anthropic, OpenAI, Gemini, or Ollama).

…