claude-presentation-builder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Byrne Reese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# claude-presentation-builder
+
+An agentic Node.js module that generates branded PowerPoint presentations using Claude. You provide a prompt describing what you want and a skill file defining your brand rules — Claude runs a full agentic loop to generate gradient assets, write a `pptxgenjs` build script, execute it, and deliver a finished `.pptx` file.
+
+---
+
+## How it works
+
+The module drives a multi-turn conversation with the Claude API. In each turn Claude can call three tools — `bash`, `write_file`, and `read_file` — to do real work: install packages, generate background images, write and run a Node.js build script. Your app handles none of that; it just waits for the `.pptx` to land at `outputPath`.
+
+```
+Your app                        Claude
+   │                               │
+   │── generatePresentation() ────>│
+   │                               │── write_file: gen_gradients.py
+   │<── tool execution ────────────│
+   │── result ────────────────────>│
+   │                               │── bash: python gen_gradients.py
+   │<── tool execution ────────────│
+   │── result ────────────────────>│
+   │                               │── write_file: build.js
+   │                               │── bash: node build.js
+   │<── tool execution ────────────│
+   │── result ────────────────────>│
+   │                               │── end_turn
+   │<── { outputPath, summary } ───│
+```
+
+---
+
+## Installation
+
+```bash
+npm install claude-presentation-builder
+```
+
+Requires Node.js 18 or later.
+
+---
+
+## Quick start
+
+```js
+import { generatePresentation } from "claude-presentation-builder";
+import { readFileSync } from "fs";
+
+const skillContent = readFileSync("./my-brand.skill.md", "utf8");
+
+const { outputPath } = await generatePresentation({
+  apiKey:       process.env.ANTHROPIC_API_KEY,
+  prompt:       "Create a 5-slide executive summary for our Q3 roadmap",
+  skillContent,
+  outputPath:   "./decks/q3-roadmap.pptx",
+});
+
+console.log("Saved to:", outputPath);
+```
+
+---
+
+## API Reference
+
+### `generatePresentation(options)`
+
+Returns `Promise<{ outputPath: string, summary: string }>`.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | ✅ | Your Anthropic API key. Use `process.env.ANTHROPIC_API_KEY` — never hardcode. |
+| `prompt` | `string` | ✅ | Natural language description of the presentation to build. Be as specific as you like — number of slides, audience, key messages, data to include. |
+| `skillContent` | `string` | ✅ | The full text of your brand/template skill file. This tells Claude exactly how to style the presentation. See [Writing a skill file](#writing-a-skill-file). |
+| `outputPath` | `string` | — | Where to write the finished `.pptx`. Accepts absolute or relative paths. Defaults to `./presentation-<timestamp>.pptx` in the current working directory. |
+| `workDir` | `string` | — | Directory Claude uses for intermediate files (gradient PNGs, build scripts, etc.). Defaults to a unique folder inside `os.tmpdir()`. Useful to set explicitly if you want to inspect intermediate outputs or cache gradient assets between runs. |
+| `model` | `string` | — | Claude model to use. Defaults to `"claude-opus-4-6"`. |
+| `maxTokens` | `number` | — | `max_tokens` per API call. Defaults to `8096`. Increase if Claude is truncating long build scripts. |
+| `onProgress` | `function` | — | Progress callback invoked throughout the build. Receives a single [event object](#progress-events). Useful for logging, UI progress bars, or debugging. |
+
+#### Return value
+
+```ts
+{
+  outputPath: string,  // Absolute path to the written .pptx file
+  summary:    string,  // Claude's final text response — a short description of what was built
+}
+```
+
+#### Errors
+
+| Condition | Error message |
+|---|---|
+| `apiKey` not provided | `claude-presentation-builder: apiKey is required` |
+| `prompt` not provided | `claude-presentation-builder: prompt is required` |
+| `skillContent` not provided | `claude-presentation-builder: skillContent is required. Pass the text of your brand/template skill file.` |
+| Claude completes without producing a file | `claude-presentation-builder: Claude did not produce output.pptx in <workDir>. Check onProgress logs for build errors.` |
+
+---
+
+### Progress events
+
+The `onProgress` callback receives one of these event shapes on each update:
+
+```ts
+// An API call is being made
+{ type: "api_call", round: number }
+
+// Claude returned a stop reason
+{ type: "stop_reason", value: "tool_use" | "end_turn", round: number }
+
+// Claude is invoking a tool
+{ type: "tool_call", tool: "bash" | "write_file" | "read_file", input: object }
+
+// A tool has returned its result
+{ type: "tool_result", tool: "bash" | "write_file" | "read_file", output: string }
+
+// Claude finished — build is complete
+{ type: "complete", text: string }
+
+// Internal log line from the tool executor
+{ type: "log", message: string }
+```
+
+**Example — simple console logger:**
+
+```js
+const { outputPath } = await generatePresentation({
+  apiKey, prompt, skillContent,
+  onProgress: (e) => {
+    if (e.type === "tool_call")   console.log(`⚙  ${e.tool}:`, JSON.stringify(e.input).slice(0, 80));
+    if (e.type === "tool_result") console.log(`   → ${String(e.output).slice(0, 100)}`);
+    if (e.type === "complete")    console.log("✅ Done");
+  },
+});
+```
+
+**Example — structured logging:**
+
+```js
+import pino from "pino";
+const log = pino();
+
+onProgress: (e) => log.info(e, "presentation-builder")
+```
+
+---
+
+## Writing a skill file
+
+A skill file is a plain Markdown (`.md`) text file that tells Claude how to build your presentation. You load it yourself and pass its content as the `skillContent` parameter. There is no required format — Claude reads it as instructions.
+
+```js
+import { readFileSync } from "fs";
+
+const skillContent = readFileSync("./acme-brand.skill.md", "utf8");
+```
+
+A well-written skill file typically covers:
+
+- **Background/theme** — how to generate or load slide backgrounds (colors, gradients, images)
+- **Typography** — font names, sizes, weights, and colors for each text role
+- **Layout library** — named slide layouts with exact positioning and dimensions
+- **Brand assets** — where logo and icon files live and how to use them
+- **Build workflow** — the step-by-step process Claude must follow (e.g. generate PNGs first, then write the pptxgenjs script, then run it)
+- **Critical rules** — hard constraints that must never be violated
+
+**Minimal example skill file:**
+
+```markdown
+# Acme Corp Presentation Template
+
+Build presentations using pptxgenjs (npm install pptxgenjs).
+
+## Background
+All slides use a solid #1A1A2E background.
+
+## Typography
+- Titles: 32pt, bold, white (#FFFFFF), font "Helvetica Neue"
+- Body:   14pt, normal, light gray (#CCCCCC), font "Helvetica Neue"
+
+## Footer
+Every slide: company name bottom-right, slide number bottom-left. 9pt, #888888.
+
+## Build steps
+1. Write build.js using pptxgenjs.
+2. Run: npm install pptxgenjs && node build.js
+3. Output must be written to output.pptx.
+```
+
+> **Tip:** The more precise your skill file, the more consistent the output. Define exact hex codes, font sizes in points, and element positions in inches (pptxgenjs uses inches for all coordinates on a 10" × 5.625" canvas).
+
+---
+
+## Advanced usage
+
+### Inspect intermediate build files
+
+Set `workDir` to a stable path to keep Claude's working files after the build completes — useful for debugging or caching gradient assets.
+
+```js
+const { outputPath } = await generatePresentation({
+  apiKey, prompt, skillContent,
+  outputPath: "./output.pptx",
+  workDir:    "./build-cache",
+});
+// ./build-cache/ will contain gen_gradients.py, bg_warm.png, build.js, output.pptx, etc.
+```
+
+### Use a different Claude model
+
+```js
+const { outputPath } = await generatePresentation({
+  apiKey, prompt, skillContent,
+  model: "claude-sonnet-4-6",  // faster and cheaper; may need a more explicit skill file
+});
+```
+
+### Load skill content from multiple files
+
+Compose your skill from reusable parts:
+
+```js
+import { readFileSync } from "fs";
+
+const skillContent = [
+  readFileSync("./skills/brand-colors.md", "utf8"),
+  readFileSync("./skills/slide-layouts.md", "utf8"),
+  readFileSync("./skills/build-workflow.md", "utf8"),
+].join("\n\n---\n\n");
+
+const { outputPath } = await generatePresentation({
+  apiKey, prompt, skillContent,
+});
+```
+
+### Batch generation
+
+```js
+import { generatePresentation } from "claude-presentation-builder";
+import { readFileSync } from "fs";
+
+const skillContent = readFileSync("./my-brand.skill.md", "utf8");
+
+const decks = [
+  { prompt: "Q1 business review — 8 slides", output: "./q1-review.pptx" },
+  { prompt: "Product roadmap overview — 6 slides", output: "./roadmap.pptx" },
+  { prompt: "New hire onboarding deck — 10 slides", output: "./onboarding.pptx" },
+];
+
+for (const deck of decks) {
+  const { outputPath } = await generatePresentation({
+    apiKey: process.env.ANTHROPIC_API_KEY,
+    prompt: deck.prompt,
+    skillContent,
+    outputPath: deck.output,
+  });
+  console.log("Built:", outputPath);
+}
+```
+
+---
+
+## Requirements
+
+- Node.js 18+
+- An [Anthropic API key](https://console.anthropic.com/)
+- Python 3 with `Pillow` and `numpy` available on `PATH` (required if your skill generates gradient backgrounds — install with `pip install Pillow numpy`)
+
+---
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,152 @@
+/**
+ * claude-presentation-builder
+ *
+ * Agentic AI-powered presentation builder. Pass a prompt describing what
+ * you want and a skill file defining your brand/template rules — Claude
+ * drives a full agentic loop to generate, build, and write a .pptx file.
+ *
+ * Usage:
+ *
+ *   import { generatePresentation } from "claude-presentation-builder";
+ *   import { readFileSync } from "fs";
+ *
+ *   const skillContent = readFileSync("./my-brand.skill.md", "utf8");
+ *
+ *   const { outputPath } = await generatePresentation({
+ *     apiKey:       process.env.ANTHROPIC_API_KEY,
+ *     prompt:       "Create a 5-slide deck about our Q3 roadmap",
+ *     skillContent,
+ *     outputPath:   "./decks/q3-roadmap.pptx",
+ *   });
+ *
+ *   console.log("Saved to:", outputPath);
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { TOOL_DEFINITIONS, createToolExecutor } from "./src/tools.js";
+import { runAgenticLoop } from "./src/loop.js";
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a branded PowerPoint presentation using an agentic Claude loop.
+ *
+ * @param {object}   options
+ * @param {string}   options.apiKey        Anthropic API key (required)
+ * @param {string}   options.prompt        What the presentation should be about (required)
+ * @param {string}   options.skillContent  Brand/template instructions for Claude (required).
+ *                                         Typically the text content of a Markdown skill file.
+ * @param {string}   [options.outputPath]  Where to save the finished .pptx file.
+ *                                         Defaults to ./presentation-<timestamp>.pptx
+ * @param {string}   [options.workDir]     Directory for intermediate build files (gradients,
+ *                                         scripts, etc.). Defaults to a temp folder under
+ *                                         os.tmpdir() that is unique per call.
+ * @param {string}   [options.model]       Claude model to use.
+ *                                         Defaults to "claude-opus-4-6".
+ * @param {number}   [options.maxTokens]   max_tokens per API call. Defaults to 8096.
+ * @param {Function} [options.onProgress]  Progress callback invoked throughout the build.
+ *                                         Receives a single event object — see Event Types.
+ *
+ * @returns {Promise<{ outputPath: string, summary: string }>}
+ *   outputPath — absolute path to the written .pptx file
+ *   summary    — Claude's final text response (a short description of what was built)
+ *
+ * @throws {Error} if apiKey, prompt, or skillContent are missing
+ * @throws {Error} if Claude completes without writing output.pptx to workDir
+ */
+export async function generatePresentation({
+  apiKey,
+  prompt,
+  skillContent,
+  outputPath,
+  workDir,
+  model = "claude-opus-4-6",
+  maxTokens = 8096,
+  onProgress = () => {},
+}) {
+  // ── Validate ──────────────────────────────────────────────────────────────
+  if (!apiKey)
+    throw new Error("claude-presentation-builder: apiKey is required");
+  if (!prompt)
+    throw new Error("claude-presentation-builder: prompt is required");
+  if (!skillContent)
+    throw new Error(
+      "claude-presentation-builder: skillContent is required. " +
+        "Pass the text of your brand/template skill file. " +
+        "Example: readFileSync('./my-brand.skill.md', 'utf8')"
+    );
+
+  // ── Resolve paths ─────────────────────────────────────────────────────────
+  const resolvedWorkDir =
+    workDir ?? path.join(os.tmpdir(), `cpb-${Date.now()}`);
+
+  const resolvedOutputPath =
+    outputPath ?? path.resolve(`presentation-${Date.now()}.pptx`);
+
+  const absoluteOutputPath = path.isAbsolute(resolvedOutputPath)
+    ? resolvedOutputPath
+    : path.resolve(resolvedOutputPath);
+
+  fs.mkdirSync(resolvedWorkDir, { recursive: true });
+  fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
+
+  // ── Wire up tools ─────────────────────────────────────────────────────────
+  const executeTools = createToolExecutor(resolvedWorkDir, (msg) =>
+    onProgress({ type: "log", message: msg })
+  );
+
+  // ── Run the agentic loop ──────────────────────────────────────────────────
+  const client = new Anthropic({ apiKey });
+
+  const summary = await runAgenticLoop({
+    client,
+    model,
+    maxTokens,
+    systemPrompt: buildSystemPrompt(skillContent, resolvedWorkDir),
+    userMessage: prompt,
+    tools: TOOL_DEFINITIONS,
+    executeTools,
+    onProgress,
+  });
+
+  // ── Copy output to the requested destination ──────────────────────────────
+  const builtFile = path.join(resolvedWorkDir, "output.pptx");
+
+  if (!fs.existsSync(builtFile)) {
+    throw new Error(
+      `claude-presentation-builder: Claude did not produce output.pptx in ${resolvedWorkDir}.\n` +
+        `Check onProgress logs for build errors.`
+    );
+  }
+
+  fs.copyFileSync(builtFile, absoluteOutputPath);
+
+  return { outputPath: absoluteOutputPath, summary };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function buildSystemPrompt(skillContent, workDir) {
+  return `\
+You are a presentation builder. Build a PowerPoint presentation by following
+the brand and template instructions below exactly.
+
+You have three tools:
+- bash       → run shell commands (Python, Node.js, npm install, etc.)
+- write_file → write a file to disk
+- read_file  → read a file from disk
+
+Working directory: ${workDir}
+The finished presentation MUST be written to: ${workDir}/output.pptx
+
+IMPORTANT: Do NOT narrate steps or output tool-call syntax as text.
+Actually USE the tools to execute every step.
+
+---
+
+${skillContent}
+`;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "claude-presentation-builder",
+  "version": "1.0.0",
+  "description": "Agentic AI-powered presentation builder — bring your own brand skill, get back a .pptx",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0"
+  },
+  "keywords": [
+    "presentation",
+    "pptx",
+    "powerpoint",
+    "claude",
+    "anthropic",
+    "ai",
+    "agent"
+  ],
+  "license": "MIT"
+}

package/src/loop.js

@@ -0,0 +1,92 @@
+/**
+ * runAgenticLoop
+ *
+ * Drives a multi-turn Claude conversation that can call tools. Keeps running
+ * until Claude returns stop_reason === "end_turn" (no more tool calls).
+ *
+ * @param {object}   opts
+ * @param {object}   opts.client         Anthropic SDK client instance
+ * @param {string}   opts.model          Model string, e.g. "claude-opus-4-6"
+ * @param {number}   opts.maxTokens      max_tokens for each API call
+ * @param {string}   opts.systemPrompt   System prompt passed to every call
+ * @param {string}   opts.userMessage    The initial user message
+ * @param {Array}    opts.tools          Tool definition array (TOOL_DEFINITIONS)
+ * @param {Function} opts.executeTools   (toolName, toolInput) => string
+ * @param {Function} [opts.onProgress]   Optional (event) => void progress callback
+ *                                       event: { type, tool?, input?, output?, text? }
+ *
+ * @returns {Promise<string>}  The final text response from Claude
+ */
+export async function runAgenticLoop({
+  client,
+  model,
+  maxTokens,
+  systemPrompt,
+  userMessage,
+  tools,
+  executeTools,
+  onProgress = () => {},
+}) {
+  const messages = [{ role: "user", content: userMessage }];
+  let round = 0;
+
+  while (true) {
+    round++;
+    onProgress({ type: "api_call", round });
+
+    const response = await client.messages.create({
+      model,
+      max_tokens: maxTokens,
+      system: systemPrompt,
+      tools,
+      messages,
+    });
+
+    onProgress({ type: "stop_reason", value: response.stop_reason, round });
+
+    // Append Claude's reply to history
+    messages.push({ role: "assistant", content: response.content });
+
+    // ── Done ──────────────────────────────────────────────────────────────
+    if (response.stop_reason === "end_turn") {
+      const finalText = response.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("\n")
+        .trim();
+
+      onProgress({ type: "complete", text: finalText });
+      return finalText;
+    }
+
+    // ── Tool calls ────────────────────────────────────────────────────────
+    if (response.stop_reason === "tool_use") {
+      const toolResults = [];
+
+      for (const block of response.content) {
+        if (block.type !== "tool_use") continue;
+
+        onProgress({ type: "tool_call", tool: block.name, input: block.input });
+
+        const output = executeTools(block.name, block.input);
+
+        onProgress({ type: "tool_result", tool: block.name, output });
+
+        toolResults.push({
+          type: "tool_result",
+          tool_use_id: block.id,
+          content: String(output),
+        });
+      }
+
+      // Send results back and loop
+      messages.push({ role: "user", content: toolResults });
+      continue;
+    }
+
+    // ── Unexpected ────────────────────────────────────────────────────────
+    throw new Error(
+      `Unexpected stop_reason "${response.stop_reason}" in round ${round}`
+    );
+  }
+}

package/src/tools.js

@@ -0,0 +1,123 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+// ── Tool definitions sent to the Claude API ───────────────────────────────────
+
+export const TOOL_DEFINITIONS = [
+  {
+    name: "bash",
+    description:
+      "Execute a bash command in the working directory. Use this to: run Python scripts " +
+      "(e.g. generate gradient PNGs), install npm packages, run Node.js scripts to build " +
+      "the .pptx file, and inspect the filesystem. Always prefer writing scripts to disk " +
+      "first via write_file, then executing them with bash.",
+    input_schema: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description: "The bash command to execute.",
+        },
+      },
+      required: ["command"],
+    },
+  },
+  {
+    name: "write_file",
+    description:
+      "Write text content to a file. Use this to create Python scripts, Node.js scripts, " +
+      "and any other files needed during the build. Paths are relative to the working directory " +
+      "unless absolute.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "File path (relative to working directory, or absolute).",
+        },
+        content: {
+          type: "string",
+          description: "Full text content to write.",
+        },
+      },
+      required: ["path", "content"],
+    },
+  },
+  {
+    name: "read_file",
+    description:
+      "Read the contents of a file. Use this to inspect generated files, check for errors, " +
+      "or verify output.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "File path (relative to working directory, or absolute).",
+        },
+      },
+      required: ["path"],
+    },
+  },
+];
+
+// ── Tool executor factory ─────────────────────────────────────────────────────
+
+/**
+ * Returns an executeTools(name, input) function bound to a specific workDir.
+ * Any error is caught and returned as a string so Claude can self-correct.
+ *
+ * @param {string} workDir  Absolute path to the working directory
+ * @param {Function} [log]  Optional log(message) callback for progress output
+ */
+export function createToolExecutor(workDir, log = () => {}) {
+  fs.mkdirSync(workDir, { recursive: true });
+
+  return function executeTools(toolName, toolInput) {
+    log(`[tool:${toolName}] ${JSON.stringify(toolInput).slice(0, 120)}`);
+
+    try {
+      // ── bash ──────────────────────────────────────────────────────────────
+      if (toolName === "bash") {
+        const output = execSync(toolInput.command, {
+          cwd: workDir,
+          timeout: 120_000, // 2 min per command
+          encoding: "utf8",
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        const trimmed = (output || "(no output)").slice(0, 4000);
+        log(`[output] ${trimmed.slice(0, 200)}`);
+        return trimmed;
+      }
+
+      // ── write_file ────────────────────────────────────────────────────────
+      if (toolName === "write_file") {
+        const filePath = path.isAbsolute(toolInput.path)
+          ? toolInput.path
+          : path.join(workDir, toolInput.path);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, toolInput.content, "utf8");
+        log(`[written] ${filePath}`);
+        return `File written: ${filePath}`;
+      }
+
+      // ── read_file ─────────────────────────────────────────────────────────
+      if (toolName === "read_file") {
+        const filePath = path.isAbsolute(toolInput.path)
+          ? toolInput.path
+          : path.join(workDir, toolInput.path);
+        const content = fs.readFileSync(filePath, "utf8");
+        log(`[read] ${filePath} (${content.length} chars)`);
+        return content.slice(0, 8000); // cap to avoid blowing context
+      }
+
+      return `Unknown tool: ${toolName}`;
+    } catch (err) {
+      // Return error text — lets Claude read it and self-correct
+      const msg = `ERROR: ${err.message}\n${err.stderr ?? ""}`.trim();
+      log(`[error] ${msg.slice(0, 300)}`);
+      return msg;
+    }
+  };
+}