@cohortapp/agent-sdk 2.3.0

package/scripts/media-generation/README.md

@@ -0,0 +1,105 @@
+# Media Generation Pipeline
+
+> **Full setup guide**: See [docs/guides/media-generation-setup.md](../../docs/guides/media-generation-setup.md) for complete API setup, prompt spec authoring, brand alignment, testing, and troubleshooting.
+
+Generates branded illustrations, diagrams, and video assets using Google Gemini and Veo APIs.
+Ported from `~/company-web/app/scripts/media-generation/` and `~/innovation-lab/`.
+
+## Prerequisites
+
+```bash
+# Install dependencies
+cd ~/<agent-name> && npm install
+
+# Set API key in .env or config/environment.yaml
+echo "GEMINI_API_KEY=your-key-here" >> .env
+```
+
+Get a Gemini API key from: https://aistudio.google.com/apikey
+
+## Capabilities
+
+### Image Generation (Gemini)
+
+Generate illustrations and diagrams for board materials, presentations, and communications.
+
+```bash
+# Generate a single illustration from a prompt file
+node scripts/media-generation/generate-assets.mjs --illustration <slug>
+
+# Generate all missing illustrations
+node scripts/media-generation/generate-assets.mjs --all-missing
+```
+
+**Models supported:**
+
+- `gemini-3-pro-image-preview` (default) — best quality
+- `imagen-*` variants — Google Imagen models
+
+**Aspect ratios:** `1:1`, `3:4`, `4:3`, `9:16`, `16:9`
+
+### Video Generation (Veo 3.1)
+
+Generate branded video assets for presentations and social media.
+
+```bash
+# Generate a video from a prompt file
+node scripts/media-generation/generate-assets.mjs --video <slug>
+
+# Generate all missing videos
+node scripts/media-generation/generate-assets.mjs --all-missing-videos
+```
+
+**Model:** `veo-3.1-generate-preview`
+**Durations:** 4, 6, or 8 seconds
+**Resolutions:** 720p, 1080p, 4k
+**Modes:** text-to-video, image-to-video
+
+## Prompt Specifications
+
+Prompts live in `scripts/media-generation/prompts/` as TypeScript files:
+
+```
+prompts/
+  illustrations/     # Image generation prompts
+  diagrams/          # Diagram generation prompts
+  videos/            # Video generation prompts
+```
+
+Each prompt file exports a structured specification:
+
+```typescript
+export default {
+  id: "board-pack-cover-q2-2026",
+  slug: "board-pack-cover-q2-2026",
+  title: "Q2 2026 Board Pack Cover Illustration",
+  purpose: "Cover page visual for quarterly board materials",
+  imageCategory: "editorial-hand-drawn",
+  colorPalette: ["#1C1917", "#FAFAF9", "#78716C", "#D6D3D1"],
+  mood: ["institutional", "sophisticated", "premium"],
+  elements: [...],
+  style: "Monochromatic NYT-style hand-drawn editorial illustration...",
+  aspectRatio: "3:4",
+};
+```
+
+## Brand Alignment
+
+All generated assets follow `config/brand-assets.yaml`:
+
+- **Illustration style**: Monochromatic editorial hand-drawn (NYT-style)
+- **Colour palette**: `#1C1917`, `#FAFAF9`, `#78716C`, `#D6D3D1`, `#A8A29E`
+- **Mood**: Institutional, precise, premium, restrained
+- **Avoid**: Cartoon, isometric SaaS, stock photography aesthetics
+
+## Output
+
+- Images: `public/generated/illustrations/` and `public/generated/diagrams/`
+- Videos: `public/generated/videos/`
+- Generation log: `scripts/media-generation/generation-log.json`
+
+## Cross-Repo References
+
+- Source implementation: `~/company-web/app/scripts/media-generation/`
+- Visual prompt builder: `~/company-web/app/scripts/media-generation/visual-prompt-builder.ts`
+- Social image renderer: `~/innovation-lab/tools/social-image/`

package/scripts/media-generation/gemini-image-client.mjs

@@ -0,0 +1,173 @@
+/**
+ * Gemini Image Generation Client for Northwind CEO Brain
+ *
+ * Generates branded illustrations, diagrams, and visual assets for
+ * board materials, investor presentations, and corporate communications.
+ *
+ * Ported from ~/company-web/app/scripts/media-generation/gemini-image-client.mjs
+ *
+ * Usage:
+ *   import { generateImageGemini } from './gemini-image-client.mjs';
+ *   const result = await generateImageGemini(prompt, { aspectRatio: '16:9' });
+ */
+
+import "dotenv/config";
+
+import { GoogleGenAI } from "@google/genai";
+
+/**
+ * Generate an image using Google AI (Gemini or Imagen)
+ *
+ * @param {string} prompt - The full generation prompt
+ * @param {object} options - Generation options
+ * @param {string} options.aspectRatio - Aspect ratio ('1:1', '3:4', '4:3', '9:16', '16:9')
+ * @param {string} options.model - Model name (default: gemini-3-pro-image-preview)
+ * @returns {Promise<{imageBase64: string, revisedPrompt: string, responseId: string}>}
+ */
+export async function generateImageGemini(prompt, options = {}) {
+  const apiKey = process.env.GEMINI_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "GEMINI_API_KEY environment variable not set.\n" +
+        "Add it to config/environment.yaml or .env file.\n" +
+        "Get a key from: https://aistudio.google.com/apikey",
+    );
+  }
+
+  const model =
+    options.model || process.env.GEMINI_MODEL || "gemini-3-pro-image-preview";
+  const aspectRatio = options.aspectRatio || "16:9";
+
+  console.log(`   [ImageGen] Model: ${model}`);
+  console.log(`   [ImageGen] Aspect Ratio: ${aspectRatio}`);
+  console.log(`   [ImageGen] Prompt length: ${prompt.length} characters`);
+
+  const ai = new GoogleGenAI({ apiKey });
+
+  if (model.startsWith("imagen-")) {
+    return generateViaImagen(ai, model, prompt, aspectRatio);
+  } else {
+    return generateViaGemini(ai, model, prompt, aspectRatio);
+  }
+}
+
+/**
+ * Generate via Gemini generateContent API (for gemini-* models)
+ */
+async function generateViaGemini(ai, model, prompt, aspectRatio) {
+  const response = await ai.models.generateContent({
+    model,
+    contents: prompt,
+    config: {
+      responseModalities: ["TEXT", "IMAGE"],
+    },
+  });
+
+  if (!response.candidates || response.candidates.length === 0) {
+    throw new Error("Gemini returned no candidates in response");
+  }
+
+  let imageBase64 = null;
+  let description = "";
+
+  for (const part of response.candidates[0].content.parts) {
+    if (part.text) {
+      description = part.text;
+      console.log(
+        `   [ImageGen] Description: ${description.substring(0, 120)}...`,
+      );
+    } else if (part.inlineData) {
+      imageBase64 = part.inlineData.data;
+      console.log(
+        `   [ImageGen] Image received (${Math.round(imageBase64.length / 1024)} KB base64)`,
+      );
+    }
+  }
+
+  if (!imageBase64) {
+    throw new Error(
+      "No image generated - Gemini returned text only.\n" +
+        (description
+          ? `Response text: ${description.substring(0, 300)}`
+          : "No text response either."),
+    );
+  }
+
+  return {
+    imageBase64,
+    revisedPrompt: description || prompt.substring(0, 500),
+    responseId: `gemini-${Date.now()}`,
+  };
+}
+
+/**
+ * Generate via Imagen generateImages API (for imagen-* models)
+ */
+async function generateViaImagen(ai, model, prompt, aspectRatio) {
+  const response = await ai.models.generateImages({
+    model,
+    prompt,
+    config: {
+      numberOfImages: 1,
+      aspectRatio,
+      includeRaiReason: true,
+    },
+  });
+
+  if (!response.generatedImages || response.generatedImages.length === 0) {
+    throw new Error(
+      "No images generated. The prompt may have been filtered by safety settings.",
+    );
+  }
+
+  const generated = response.generatedImages[0];
+
+  if (!generated.image || !generated.image.imageBytes) {
+    const reason = generated.raiFilteredReason || "unknown";
+    throw new Error(`Image was filtered by safety settings. Reason: ${reason}`);
+  }
+
+  const imageBase64 = generated.image.imageBytes;
+  console.log(
+    `   [ImageGen] Image received (${Math.round(imageBase64.length / 1024)} KB base64)`,
+  );
+
+  return {
+    imageBase64,
+    revisedPrompt: prompt.substring(0, 500),
+    responseId: `imagen-${Date.now()}`,
+  };
+}
+
+/**
+ * Generate a refined image by re-generating with enhanced prompt
+ */
+export async function generateImageGeminiWithRefinement(
+  originalPrompt,
+  refinementInstructions,
+  options = {},
+) {
+  const enhancedPrompt = `${originalPrompt}
+
+---
+
+REFINEMENT INSTRUCTIONS (CRITICAL - fix these issues from previous generation):
+
+${refinementInstructions}
+
+---
+
+Generate a corrected version addressing ALL refinement instructions above while maintaining
+the original composition, concept, and Northwind brand aesthetic requirements.`;
+
+  console.log(
+    `   [ImageGen] Regenerating with refinement instructions (${refinementInstructions.length} chars)`,
+  );
+
+  return generateImageGemini(enhancedPrompt, options);
+}
+
+export default {
+  generateImageGemini,
+  generateImageGeminiWithRefinement,
+};

package/scripts/media-generation/generate-assets.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+/**
+ * Visual Asset Generator for Northwind CEO Brain
+ *
+ * Generates branded illustrations, diagrams, and videos for
+ * board materials, investor presentations, and corporate communications.
+ *
+ * Ported from ~/company-web/app/scripts/media-generation/generate-visual-assets.mjs
+ *
+ * Usage:
+ *   node scripts/media-generation/generate-assets.mjs --illustration <slug>
+ *   node scripts/media-generation/generate-assets.mjs --video <slug>
+ *   node scripts/media-generation/generate-assets.mjs --all-missing
+ *   node scripts/media-generation/generate-assets.mjs --all-missing-videos
+ */
+
+import "dotenv/config";
+
+import fs from "fs/promises";
+import path from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+
+import { generateImageGemini } from "./gemini-image-client.mjs";
+import { createText2Video, downloadVideo } from "./veo-video-client.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, "../..");
+
+const PROMPTS_DIR = path.join(__dirname, "prompts");
+const ILLUSTRATION_OUTPUT = path.join(ROOT, "public/generated/illustrations");
+const DIAGRAM_OUTPUT = path.join(ROOT, "public/generated/diagrams");
+const VIDEO_OUTPUT = path.join(ROOT, "public/generated/videos");
+const LOG_FILE = path.join(__dirname, "generation-log.json");
+
+const RATE_LIMIT_DELAY = 15000; // 15s between requests
+
+// ─── Helpers ───
+
+async function loadPromptSpec(type, slug) {
+  const specPath = path.join(PROMPTS_DIR, type, `${slug}.ts`);
+  if (!existsSync(specPath)) {
+    // Try .mjs extension
+    const mjsPath = path.join(PROMPTS_DIR, type, `${slug}.mjs`);
+    if (!existsSync(mjsPath)) {
+      throw new Error(`Prompt spec not found: ${specPath} or ${mjsPath}`);
+    }
+    return (await import(mjsPath)).default;
+  }
+  // Use tsx to import TypeScript
+  const { execaCommand } = await import("execa");
+  const result = await execaCommand(
+    `npx tsx -e "import spec from '${specPath}'; console.log(JSON.stringify(spec))"`,
+    { cwd: ROOT },
+  );
+  return JSON.parse(result.stdout);
+}
+
+async function listPromptSlugs(type) {
+  const dir = path.join(PROMPTS_DIR, type);
+  if (!existsSync(dir)) return [];
+  const files = await fs.readdir(dir);
+  return files
+    .filter((f) => f.endsWith(".ts") || f.endsWith(".mjs"))
+    .map((f) => f.replace(/\.(ts|mjs)$/, ""));
+}
+
+async function readLog() {
+  if (!existsSync(LOG_FILE)) return [];
+  const content = await fs.readFile(LOG_FILE, "utf-8");
+  return JSON.parse(content);
+}
+
+async function appendLog(entry) {
+  const log = await readLog();
+  log.push({ ...entry, generatedAt: new Date().toISOString() });
+  await fs.writeFile(LOG_FILE, JSON.stringify(log, null, 2));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Illustration Generation ───
+
+async function generateIllustration(slug) {
+  console.log(`\n  Generating illustration: ${slug}`);
+
+  const spec = await loadPromptSpec("illustrations", slug);
+  const outputDir =
+    spec.imageCategory === "diagram" ? DIAGRAM_OUTPUT : ILLUSTRATION_OUTPUT;
+  const outputPath = path.join(outputDir, `${slug}.png`);
+
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const prompt = spec.prompt || buildDefaultPrompt(spec);
+  const aspectRatio = spec.aspectRatio || "16:9";
+
+  const result = await generateImageGemini(prompt, { aspectRatio });
+
+  const buffer = Buffer.from(result.imageBase64, "base64");
+  await fs.writeFile(outputPath, buffer);
+
+  console.log(
+    `  Saved: ${outputPath} (${Math.round(buffer.length / 1024)} KB)`,
+  );
+
+  await appendLog({
+    slug,
+    title: spec.title,
+    type: "illustration",
+    outputPath: path.relative(ROOT, outputPath),
+    aspectRatio,
+    responseId: result.responseId,
+    promptLength: prompt.length,
+    fileSizeKB: Math.round(buffer.length / 1024),
+  });
+
+  return outputPath;
+}
+
+function buildDefaultPrompt(spec) {
+  const parts = [
+    `Create an illustration for: ${spec.title}`,
+    `Purpose: ${spec.purpose}`,
+    `Style: ${spec.style || "Monochromatic NYT-style hand-drawn editorial illustration. Pen-and-ink with cross-hatching and stippling."}`,
+    `Mood: ${(spec.mood || ["institutional", "sophisticated"]).join(", ")}`,
+    `Color palette: ${(spec.colorPalette || ["#1C1917", "#FAFAF9", "#78716C", "#D6D3D1"]).join(", ")}`,
+  ];
+
+  if (spec.elements) {
+    parts.push(
+      `Key elements:\n${spec.elements.map((e) => `- ${e}`).join("\n")}`,
+    );
+  }
+
+  parts.push(
+    "IMPORTANT: This is for Northwind, an institutional-grade AI asset management platform. The illustration must feel premium, restrained, and sophisticated. Avoid cartoon, isometric, or generic SaaS illustration styles.",
+  );
+
+  return parts.join("\n\n");
+}
+
+// ─── Video Generation ───
+
+async function generateVideo(slug) {
+  console.log(`\n  Generating video: ${slug}`);
+
+  const spec = await loadPromptSpec("videos", slug);
+  const outputPath = path.join(VIDEO_OUTPUT, `${slug}.mp4`);
+
+  await fs.mkdir(VIDEO_OUTPUT, { recursive: true });
+
+  const prompt = spec.prompt || `${spec.title}. ${spec.purpose}`;
+  const options = {
+    duration: spec.duration || "8",
+    aspectRatio: spec.aspectRatio || "16:9",
+    resolution: spec.resolution || "720p",
+  };
+
+  if (spec.negativePrompt) {
+    options.negativePrompt = spec.negativePrompt;
+  }
+
+  let operation;
+  if (spec.sourceImage) {
+    const { createImage2Video } = await import("./veo-video-client.mjs");
+    operation = await createImage2Video(spec.sourceImage, prompt, options);
+  } else {
+    operation = await createText2Video(prompt, options);
+  }
+
+  await downloadVideo(operation, outputPath);
+
+  await appendLog({
+    slug,
+    title: spec.title,
+    type: "video",
+    outputPath: path.relative(ROOT, outputPath),
+    duration: options.duration,
+    aspectRatio: options.aspectRatio,
+    resolution: options.resolution,
+  });
+
+  return outputPath;
+}
+
+// ─── Batch Operations ───
+
+async function generateAllMissing(type) {
+  const slugs = await listPromptSlugs(type);
+  const outputDir =
+    type === "videos"
+      ? VIDEO_OUTPUT
+      : type === "diagrams"
+        ? DIAGRAM_OUTPUT
+        : ILLUSTRATION_OUTPUT;
+  const ext = type === "videos" ? ".mp4" : ".png";
+
+  const missing = slugs.filter(
+    (slug) => !existsSync(path.join(outputDir, `${slug}${ext}`)),
+  );
+
+  console.log(
+    `\n  Found ${missing.length} missing ${type} (of ${slugs.length} total)`,
+  );
+
+  for (const slug of missing) {
+    try {
+      if (type === "videos") {
+        await generateVideo(slug);
+      } else {
+        await generateIllustration(slug);
+      }
+      await sleep(RATE_LIMIT_DELAY);
+    } catch (error) {
+      console.error(`  Error generating ${slug}: ${error.message}`);
+    }
+  }
+}
+
+// ─── CLI ───
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes("--help")) {
+    console.log(`
+  Northwind Visual Asset Generator
+
+  Usage:
+    --illustration <slug>    Generate a single illustration
+    --video <slug>           Generate a single video
+    --all-missing            Generate all missing illustrations
+    --all-missing-videos     Generate all missing videos
+    --list                   List available prompt slugs
+    --help                   Show this help
+    `);
+    return;
+  }
+
+  if (args.includes("--list")) {
+    const illustrations = await listPromptSlugs("illustrations");
+    const diagrams = await listPromptSlugs("diagrams");
+    const videos = await listPromptSlugs("videos");
+    console.log(
+      `\n  Illustrations (${illustrations.length}):`,
+      illustrations.join(", ") || "none",
+    );
+    console.log(
+      `  Diagrams (${diagrams.length}):`,
+      diagrams.join(", ") || "none",
+    );
+    console.log(`  Videos (${videos.length}):`, videos.join(", ") || "none");
+    return;
+  }
+
+  const illustrationIdx = args.indexOf("--illustration");
+  if (illustrationIdx !== -1) {
+    await generateIllustration(args[illustrationIdx + 1]);
+    return;
+  }
+
+  const videoIdx = args.indexOf("--video");
+  if (videoIdx !== -1) {
+    await generateVideo(args[videoIdx + 1]);
+    return;
+  }
+
+  if (args.includes("--all-missing")) {
+    await generateAllMissing("illustrations");
+    await generateAllMissing("diagrams");
+    return;
+  }
+
+  if (args.includes("--all-missing-videos")) {
+    await generateAllMissing("videos");
+    return;
+  }
+
+  console.error("Unknown arguments. Use --help for usage.");
+}
+
+main().catch((err) => {
+  console.error(`\n  Fatal error: ${err.message}`);
+  process.exit(1);
+});