ShipShap Puck AI

Multi-provider AI plugin for the Puck visual editor. Supports DeepSeek (text-only) and Moonshot AI/Kimi (text + vision) via Vercel AI SDK.

Table of Contents

• Installation
• Environment Variables
• Model Pricing
  • DeepSeek
  • Moonshot (Kimi)
• Client Usage
  • Plugin Options
• Server Usage
  • Handler Options
• Providers & Models
• Image Attachments
• How It Works
• License

Installation

pnpm add @shipshapjs/plugin-ai @puckeditor/core
# or
npm install @shipshapjs/plugin-ai @puckeditor/core

Environment Variables

Set these based on your provider choice:

# Required: choose provider
AI_PROVIDER=deepseek      # or moonshotai

# Required: model for the active provider
DEEPSEEK_MODEL=deepseek-v4-flash   # deepseek-v4-flash | deepseek-v4-pro
MOONSHOT_MODEL=kimi-k2.6           # kimi-k2.6 | kimi-k2.7-code

# Provider-specific API keys
DEEPSEEK_API_KEY=sk-...
MOONSHOT_API_KEY=sk-...

When AI_PROVIDER=deepseek, DEEPSEEK_MODEL must be set to a valid DeepSeek model. When AI_PROVIDER=moonshotai, MOONSHOT_MODEL must be set to a valid Moonshot model. Invalid values throw on startup.

Model Pricing

Prices are per 1M tokens (USD). Input is split into cache-hit and cache-miss rates where providers support context caching.

💡 Price multiples vs deepseek-v4-flash (per 1M tokens). claude-sonnet-5 is not supported — listed for comparison only.*

Cache miss

• kimi-k2.6: ~7× input · ~14× output
• claude-sonnet-5: ~14× input · ~36× output

Cache hit

• kimi-k2.6: ~57× input · ~14× output
• claude-sonnet-5: ~71× input · ~36× output

* Claude Sonnet 5 introductory pricing through August 31, 2026. Source: Anthropic Pricing.

DeepSeek

Source: DeepSeek Models & Pricing

| Model | Input (cache hit) | Input (cache miss) | Output | Context | Images | | ------------------- | ----------------- | ------------------ | ------ | ------- | ------ | | deepseek-v4-flash | $0.0028 | $0.14 | $0.28 | 1M | | | deepseek-v4-pro | $0.003625 | $0.435 | $0.87 | 1M | |

Moonshot (Kimi)

Source: Kimi API Pricing

| Model | Input (cache hit) | Input (cache miss) | Output | Context | Images | | ---------------- | ----------------- | ------------------ | ------ | ------- | ------ | | kimi-k2.6 | $0.16 | $0.95 | $4.00 | 262K | ✅ | | kimi-k2.7-code | $0.19 | $0.95 | $4.00 | 262K | ✅ |

Client Usage

Import the plugin and add it to your Puck editor's plugin list:

import { createAiPlugin } from "@shipshapjs/plugin-ai";
import "@shipshapjs/plugin-ai/styles.css";

// Pass provider + model so the UI enables image attachments for vision models
const aiPlugin = createAiPlugin({ provider: "moonshotai", model: "kimi-k2.6" });

<Puck
  plugins={[aiPlugin]}
  config={config}
  data={data}
  onPublish={async (data) => {
    // Save data
  }}
/>

Plugin Options

| Option | Type | Default | Description | | ---------- | ---------------------------- | ---------------- | ---------------------------------------------- | | model | See model enums below | undefined | Active model; gates image attachments by model | | provider | "deepseek" \| "moonshotai" | undefined | Fallback for image gating when model omitted | | endpoint | string | "/api/puck/ai" | API endpoint for AI requests | | label | string | "AI" | Plugin rail label |

Server Usage

Create an API route that proxies to the AI handler:

// app/api/puck/ai/route.ts (Next.js)
// or app/routes/api.puck.ts (React Router 7)

import { createAiHandler, parseProviderFromEnv } from "@shipshapjs/plugin-ai/server";

export async function action({ request }) {
  return createAiHandler(request, {
    provider: parseProviderFromEnv(process.env.AI_PROVIDER),
    context: "We are Acme Corp. Create landing pages for our products.",
  });
}

Handler Options

| Option | Type | Required | Description | | ---------- | ---------------------------- | -------- | -------------------------------------------- | | provider | "deepseek" \| "moonshotai" | Yes | AI provider to use | | model | See model enums below | No | Override DEEPSEEK_MODEL / MOONSHOT_MODEL | | apiKey | string | No | Override env var API key | | context | string | No | Business context for system prompt | | baseURL | string | No | Override provider base URL |

Providers & Models

| Provider | Model options | Images | Use Case | | ------------ | -------------------------------------- | ------ | ------------------------------- | | deepseek | deepseek-v4-flash, deepseek-v4-pro | | Text-only page generation | | moonshotai | kimi-k2.6, kimi-k2.7-code | ✅ | Text + image-to-page generation |

Image Attachments

Image upload is enabled when the configured model supports vision (kimi-k2.6, kimi-k2.7-code). Pass model to createAiPlugin so the UI matches your server-side MOONSHOT_MODEL / DEEPSEEK_MODEL setting.

• DeepSeek models: Image button disabled; server returns 422 if images are sent.
• Moonshot vision models: Full image support — attach images to generate pages from visuals.

How It Works

The plugin uses AI SDK tool calling:

1. User sends a prompt (optionally with images for Moonshot)
2. AI generates a structured update_page tool call with JSON
3. Plugin applies the generated data to the Puck editor via dispatch({ type: "setData" })
4. Page renders with undo/redo history preserved

License

MIT