AI Story Board Generator Template

A comprehensive AI-powered storyboard generation system built with Mastra, featuring multiple specialized agents for creating, enhancing, and exporting storyboards with consistent character generation and advanced evaluation metrics. This template demonstrates advanced Mastra functionality including agent networks, automated workflows, memory management, and comprehensive evaluation systems.

🎯 Template Features

Core Mastra Functionality

  • Multi-Agent Architecture: 5 specialized agents working together
  • Agent Networks: Coordinated agent communication and task distribution
  • Automated Workflows: End-to-end storyboard generation pipelines
  • Memory Management: Persistent agent memory with LibSQL storage
  • MCP Integration: Model Context Protocol for external tool integration
  • Comprehensive Evaluation: 11 custom metrics implemented (5 storyboard + 5 script + 1 vision-based image consistency)

Advanced Integrations

  • Google Drive Upload: Direct file uploads via Zapier webhooks
  • AWS S3 Integration: Cloud storage for generated PDFs
  • Slack Notifications: Real-time status updates
  • Multiple AI Providers: OpenAI and Google Gemini support

🚀 Features

Core Functionality

  • AI-Powered Storyboard Creation: Generate complete storyboards from text descriptions
  • Multi-Agent Architecture: Specialized agents for different aspects of storyboard generation
  • Script Generation: Convert storyboards into detailed scripts with dialogue
  • Image Generation: Create visual prompts for storyboard scenes
  • Export Capabilities: PDF format
  • PDF Upload & Processing: Extract and process storyboard data from PDFs with Google Drive integration

Technical Features

  • TypeScript: Full type safety and modern development experience
  • Mastra Framework: Built on the powerful Mastra AI framework
  • AI SDK Integration: Support for multiple AI providers (OpenAI, Google Gemini)
  • Modular Architecture: Clean separation of concerns with dedicated modules
  • Comprehensive Evaluation System: Quality metrics for all agents
  • Google Drive Integration: Direct file uploads to Google Drive
  • Slack Notifications: Real-time notifications via Zapier webhooks

🤖 AI Agents

1. Storyboard Creator Agent

  • Purpose: Generates complete storyboards from story descriptions
  • Capabilities: Scene breakdown, visual descriptions, character development
  • Evaluation: Structure validation, visual prompt quality, content completeness

2. Script Generator Agent

  • Purpose: Converts storyboards into detailed scripts with dialogue
  • Capabilities: Dialogue generation, character voice, scene transitions
  • Evaluation: Script structure, dialogue quality, character development

3. Image Generator Agent

  • Purpose: Creates visual prompts and generates images for storyboard scenes
  • Capabilities: Scene visualization, style consistency, technical specifications, Google Imagen integration
  • Evaluation: Character and environment visual consistency analysis using GPT-4o-mini vision capabilities

4. Export Specialist Agent

  • Purpose: Handles export and data organization
  • Capabilities: PDF export, data formatting, file generation

5. PDF Upload Agent

  • Purpose: Processes and extracts data from uploaded PDFs with cloud integration
  • Capabilities: PDF parsing, content extraction, data conversion, Google Drive upload, Slack notifications
  • Integrations:
    • Google Drive: Direct file uploads to specified folders
    • Slack: Real-time notifications via Zapier webhook for upload status and processing results

📊 Evaluation System

The project includes a comprehensive evaluation system built on Mastra Evals to ensure high-quality outputs:

Evaluation Metrics

  • 11 Custom Metrics Implemented: Specialized evaluation criteria for storyboard, script, and image agents
  • Multi-Modal Evaluation: Vision-based analysis for image consistency using GPT-4o-mini
  • Heuristic + LLM-Based: Efficient rule-based evaluation plus advanced vision analysis
  • Detailed Logging: Comprehensive debugging and transparency
  • JSON Extraction: Handles markdown-wrapped JSON outputs automatically

Quality Assurance

  • Structure Validation: Ensures proper JSON format and required fields
  • Content Analysis: Evaluates quality, completeness, and consistency
  • Performance Tracking: Monitor agent performance over time

Available Metrics by Agent (Current)

  • Storyboard Agent: 5 metrics (structure, visual quality, content completeness, character consistency, narrative flow)
  • Script Agent: 5 metrics (structure, dialogue quality, character development, plot coherence, genre alignment)
  • Image Generator Agent: 1 vision-based metric (character and environment visual consistency with weighted scoring)

🛠️ Installation & Setup

Dependencies

  • @mastra/core: Core Mastra framework for AI agent development
  • @mastra/evals: Evaluation system for quality metrics
  • @mastra/libsql: LibSQL storage for agent memory
  • @mastra/loggers: Logging system for debugging and monitoring
  • @mastra/memory: Memory management for agent state
  • @ai-sdk/google: Google AI integration for Gemini models
  • @ai-sdk/openai: OpenAI integration for content analysis and generation
  • @aws-sdk/client-s3: AWS S3 cloud storage for PDF uploads
  • @aws-sdk/s3-request-presigner: S3 presigned URL generation
  • @google/genai: Google Generative AI for image generation
  • @google/generative-ai: Google AI SDK for advanced features
  • @modelcontextprotocol/server-filesystem: MCP filesystem server integration
  • canvas: Canvas API for image processing
  • jspdf: PDF generation library
  • pdfkit: PDF creation and manipulation
  • zod: Schema validation and type safety

Prerequisites

  • Node.js 18 or higher
  • npm or yarn package manager
  • API keys for OpenAI and Google Gemini

Quick Start

 1# Clone the repository
 2git clone <repository-url>
 3cd AI-Story-Board-Generator
 4
 5# Install dependencies
 6npm install
 7
 8# Set up environment variables
 9cp .env.example .env
10# Edit .env with your API keys
11
12# Start development server
13npm run dev

Template Structure

 1src/mastra/
 2├── agents/           # 5 specialized AI agents
 3├── tools/            # 6 custom tools for processing
 4├── workflows/        # 2 automated workflows
 5├── schemas/          # Zod schemas for type safety
 6├── evals/            # evaluation metrics (storyboard + script + image)
 7├── scorers/          # LLM-based visual consistency scorers
 8├── index.ts          # Main Mastra configuration
 9├── agent-network.ts  # Agent coordination system
10├── memory-config.ts  # Memory management setup
11└── mcp-config.ts     # MCP integration

⚙️ Configuration

Environment Variables

 1# Required API Keys
 2OPENAI_API_KEY=your_openai_key          # used for embeddings in memory
 3GOOGLE_API_KEY=your_google_key          # used by Google/Gemini models
 4
 5# PDF Upload (optional for examples/pdf-upload.ts)
 6AWS_ACCESS_KEY_ID=your_aws_access_key
 7AWS_SECRET_ACCESS_KEY=your_aws_secret_key
 8AWS_REGION=us-east-1
 9S3_BUCKET=your_s3_bucket_name
10
11# Zapier Webhook for Google Drive/Slack integrations (optional)
12ZAPIER_WEBHOOK_URL=your_zapier_webhook_url

🚀 Usage

Accessing Subagents in Playground

You can access various subagents in the playground and experiment with them individually:

  • Storyboard Agent: Creates visual storyboards from scripts
  • Script Generator Agent: Converts story ideas into detailed screenplays
  • Image Generator Agent: Generates images for storyboard scenes
  • Export Agent: Creates PDFs and other export formats
  • PDF Upload Agent: Handles cloud uploads to S3 and Google Drive

Agent Network Usage

V-Next Stream Agent Network

For coordinated multi-agent workflows, use the v-next stream agent network in the playground chat interface:

Prompt Structure:

create a storyboard for the story of "a curious boy who lives in a floating village of lanterns and sets out at dawn with his mechanical bird to find the lost light of the village" in steampunk style with warm sunrise tones, steampunk-inspired details, and emotional wonder. compile the final visuals into a PDF and upload it to my drive

The network will automatically:

  1. Generate a script from the story idea
  2. Convert script to storyboard with scenes
  3. Generate images for each scene
  4. Create PDF with embedded images
  5. Upload to S3 and Google Drive

Available Image Styles

Choose from these styles for your storyboards:

  • Cinematic: Professional film still with photorealistic quality
  • Photographic: High-quality photograph with natural lighting
  • Anime: Vibrant anime style with cel-shaded characters
  • Manga: Black and white manga panel with screentones
  • Ghibli-esque: Whimsical hand-drawn animation style
  • Disney-esque: Classic Disney animation with expressive characters
  • Comic Book: American comic book art with bold outlines
  • Graphic Novel: Mature graphic novel style with atmospheric lighting
  • Watercolor: Beautiful watercolor painting with soft edges
  • Low Poly: 3D low poly render with geometric shapes
  • Pixel Art: 16-bit pixel art with nostalgic retro aesthetic
  • Steampunk: Victorian steampunk style with brass details
  • Cyberpunk: Neon-drenched cyberpunk cityscape
  • Fantasy Art: Epic fantasy art with dramatic lighting
  • Film Noir: Black and white film noir with high contrast

Basic Storyboard Generation

 1import { mastra } from './src/mastra';
 2
 3// Generate a storyboard
 4const storyboardAgent = mastra.getAgent('storyboardAgent');
 5const response = await storyboardAgent.generate([
 6  {
 7    role: 'user',
 8    content: 'Create a storyboard for: A young woman discovers a magical book in an old library.'
 9  }
10]);
11
12console.log(response.text);

PDF Upload with Cloud Integration

 1import { generateAndUploadStoryboard } from './src/mastra';
 2
 3const result = await generateAndUploadStoryboard({
 4  storyIdea: 'A young woman discovers a magical book in an old library.',
 5  desiredFilename: 'storyboard.pdf',
 6  // optionally:
 7  // s3Bucket: 'your-bucket',
 8  // zapierWebhookUrl: process.env.ZAPIER_WEBHOOK_URL,
 9});
10
11console.log(result);

Running Evaluations

 1import { storyboardSpecificEvals } from './src/mastra/evals/storyboard-evals';
 2
 3// Evaluate storyboard quality
 4const result = await storyboardSpecificEvals.structure.measure(
 5  input,
 6  output
 7);
 8
 9console.log(`Structure Score: ${result.score}`);

Testing the Evaluation System

 1# Run the direct evals example
 2npx tsx examples/evals.ts

📁 Project Structure

 1src/
 2├── mastra/
 3│   ├── agents/           # AI agent implementations
 4│   │   ├── storyboard-agent.ts
 5│   │   ├── script-generator-agent.ts
 6│   │   ├── image-generator-agent.ts
 7│   │   ├── export-agent.ts
 8│   │   └── pdf-upload-agent.ts
 9│   ├── agentnetwork/     # Agent coordination system
10│   │   └── agent-network.ts
11│   ├── evals/           # Evaluation metrics
12│   │   ├── storyboard-evals.ts
13│   │   ├── script-evals.ts
14│   │   ├── image-evals.ts
15│   │   ├── character-consistency-eval.ts
16│   │   └── index.ts
17│   ├── scorers/         # LLM-based visual consistency scorers
18│   │   └── character-visual-consistency-scorer.ts
19│   ├── tools/           # Custom tools
20│   │   ├── character-consistency-tool.ts
21│   │   ├── image-generation-tool.ts
22│   │   ├── pdf-export-tool.ts
23│   │   ├── pdf-upload-tool.ts
24│   │   ├── script-analysis-tool.ts
25│   │   └── style-manager-tool.ts
26│   ├── workflows/       # Workflow definitions
27│   │   └── agent-network-automated-workflow.ts
28│   ├── schemas/         # Zod schemas for type safety
29│   │   ├── export-schema.ts
30│   │   ├── pdf-upload-schema.ts
31│   │   ├── script-schema.ts
32│   │   └── storyboard-schema.ts
33│   ├── index.ts         # Main exports
34│   ├── mcp-config.ts    # MCP integration
35│   └── memory-config.ts # Memory management setup
36└── examples/           # Usage examples
37    ├── basic-usage.ts
38    ├── evals.ts
39    ├── pdf-upload.ts
40    ├── streaming.ts
41    ├── workflow-automated.ts
42    ├── test-character-consistency.ts      # Vision-based character consistency test
43    └── test-direct-character-consistency.ts  # Direct AI SDK vision test

🔧 Development

📈 Quality Metrics

All evaluation metrics return scores between 0.0 and 1.0:

  • 0.9-1.0: Excellent quality, exceeds expectations
  • 0.7-0.8: Good quality, meets most requirements
  • 0.4-0.6: Acceptable quality, minor improvements needed
  • 0.0-0.3: Poor quality, needs significant improvement

🔧 Development & Testing

Available Scripts

 1npm run dev      # Start development server
 2npm run build    # Build the project

Performance Optimization

  • Memory Management: Uses LibSQL for persistent agent memory
  • Agent Networks: Efficient task distribution across agents
  • Streaming: Real-time output streaming for better UX
  • Caching: Intelligent caching of generated content

Security Best Practices

  • API Key Management: Secure environment variable handling
  • Input Validation: Comprehensive Zod schema validation
  • Error Handling: Graceful error handling and logging
  • Access Control: Proper authentication for external services

🚨 Troubleshooting

Common Issues

1. API Key Errors

 1# Check environment variables
 2echo $OPENAI_API_KEY
 3echo $GOOGLE_API_KEY
 4
 5# Verify .env file exists
 6ls -la .env

2. Memory Database Issues

 1# Reset memory database
 2rm mastra-memory.db
 3npm run dev

3. Evaluation Failures

 1# Debug specific metric
 2npx tsx examples/evals.ts

4. PDF Upload Issues

 1# Verify AWS credentials
 2aws sts get-caller-identity
 3
 4# Check Zapier webhook
 5curl -X POST $ZAPIER_WEBHOOK_URL

Performance Tips

  • Use streaming functions for real-time feedback
  • Enable memory for consistent character development
  • Use agent networks for complex multi-step processes
  • Monitor evaluation scores for quality improvement

📚 API Reference

Core Functions

Storyboard Generation

 1// Generate complete storyboard from story idea
 2const result = await generateCompleteStoryboard(
 3  "A young detective solves a mystery in a small town",
 4  { style: "Cinematic" }
 5);
 6
 7// Generate storyboard with streaming
 8const stream = await streamStoryboardCreation(
 9  "A sci-fi adventure in space",
10  { style: "Sci-Fi" }
11);

Script Generation

 1// Generate script from story idea
 2const script = await generateScript(
 3  "A romantic comedy about two chefs",
 4  { genre: "romance", tone: "lighthearted" }
 5);
 6
 7// Stream script generation
 8const stream = await streamScriptGeneration(
 9  "A thriller about a hacker",
10  { genre: "thriller", tone: "dark" }
11);

Image Generation

 1// Generate images for storyboard
 2const images = await generateStoryboardImages(
 3  storyboardData,
 4  { style: "Anime", quality: "high" }
 5);
 6
 7// Stream image generation
 8const stream = await streamImageGeneration(
 9  storyboardData,
10  { style: "Photorealistic" }
11);

Export Functions

 1// Export to PDF
 2const pdf = await exportStoryboard(
 3  storyboardData,
 4  { format: "pdf", layout: "cinematic" }
 5);
 6
 7// Export with streaming
 8const stream = await streamPDFExport(
 9  storyboardData,
10  { format: "pdf", includeMetadata: true }
11);

PDF Upload & Processing

 1// Upload and process PDF
 2const result = await generateAndUploadStoryboard(
 3  storyboardData,
 4  {
 5    desiredFilename: "my-storyboard.pdf",
 6    s3Bucket: "my-bucket",
 7    zapierWebhookUrl: "https://hooks.zapier.com/..."
 8  }
 9);
10
11// Automated workflow
12const result = await runAutomatedAgentNetwork(
13  "A fantasy adventure story",
14  {
15    style: "Fantasy",
16    title: "The Dragon's Quest",
17    genre: "fantasy",
18    tone: "epic"
19  }
20);

Agent Configuration

Each agent can be configured with custom settings:

 1import { storyboardAgent } from './src/mastra/agents/storyboard-agent';
 2
 3// Custom agent configuration
 4const customAgent = new Agent({
 5  name: 'custom-storyboard',
 6  model: google('gemini-2.0-flash'),
 7  memory: createAgentMemory(),
 8  tools: { customTool },
 9  evals: { customEval }
10});

Memory Management

 1import { createAgentMemory } from './src/mastra/memory-config';
 2
 3// Create memory instance
 4const memory = createAgentMemory();
 5
 6// Use with agent
 7const agent = new Agent({
 8  memory,
 9  // ... other config
10});

Evaluation System

 1import { storyboardSpecificEvals } from './src/mastra/evals/storyboard-evals';
 2
 3// Run evaluation
 4const result = await storyboardSpecificEvals.structure.measure(
 5  input,
 6  output
 7);
 8
 9// Get detailed metrics
10console.log('Score:', result.score);
11console.log('Details:', result.info);

🤝 Contributing

This template follows Mastra's official template guidelines:

  • Project Structure: All Mastra code in src/mastra/
  • TypeScript: Strict typing with Zod schemas
  • ES Modules: Modern JavaScript with "type": "module"
  • Node.js 18+: Latest LTS support
  • Framework-free: Pure Mastra functionality

Template Compliance

  • ✅ Project Structure: Proper organization in src/mastra/
  • ✅ TypeScript Config: ES2022, strict mode, bundler resolution
  • ✅ Package.json: Template naming, ES modules, Node.js 18+
  • ✅ Environment Config: Comprehensive .env.example
  • ✅ Agent Development: AI SDK integration, memory management
  • ✅ Tool Development: Zod validation, error handling
  • ✅ Workflow Development: createStep/createWorkflow usage
  • ✅ Schema Safety: Comprehensive Zod schemas with TypeScript exports

📄 License

MIT License - see LICENSE file for details.

▶️ Running the Examples

This template ships with runnable example scripts under examples/ that demonstrate non‑streaming, streaming, automated workflow, direct eval usage, and PDF upload.

Prerequisites (all examples)

  • Node.js 18+
  • Install deps: npm install
  • Required env for core features:
    • OPENAI_API_KEY (used for embeddings in memory)
    • GOOGLE_API_KEY (used by Google/Gemini models)

Set them temporarily per shell:

 1export OPENAI_API_KEY="your_openai_key"
 2export GOOGLE_API_KEY="your_google_key"

Or inline for a single run:

OPENAI_API_KEY="..." GOOGLE_API_KEY="..." npx tsx examples/basic-usage.ts

1) Non‑Streaming End‑to‑End: examples/basic-usage.ts

Runs three non‑streaming helpers:

  • generateCompleteStoryboardSync (idea → script → storyboard → export)
  • storyIdeaToPDFSync (idea → PDF storyboard)
  • scriptToPDFSync (script → PDF storyboard)

Run:

npx tsx examples/basic-usage.ts

Expect truncated JSON previews printed to stdout.

2) Streaming Pipelines: examples/streaming.ts

Demonstrates streaming for each step with progress logs:

  • generateScript
  • createStoryboard
  • generateStoryboardImages
  • exportStoryboard

Run:

npx tsx examples/streaming.ts

Each stage prints chunk previews to the console.

3) Automated Workflow: examples/workflow-automated.ts

Runs automatedStoryIdeaToPDF to execute the full pipeline automatically.

Run:

npx tsx examples/workflow-automated.ts

Prints the resulting object (truncated) including summary and PDF path when available.

4) Direct Evals Usage: examples/evals.ts

Shows how to call implemented metrics directly:

  • Storyboard: structure, visualPromptQuality
  • Script: structure, genreAlignment

Run:

npx tsx examples/evals.ts

Outputs metric scores (0.0–1.0) to stdout.

6) Character Consistency Testing: examples/test-character-consistency.ts

Tests the vision-based character and environment consistency evaluation system using actual generated images from the generated-images/ folder:

npx tsx examples/test-character-consistency.ts

This example demonstrates:

  • Multi-modal evaluation using GPT-4o-mini vision capabilities
  • Character consistency analysis across 5 forest scene images
  • Environment consistency scoring with detailed breakdown
  • Weighted scoring system (60% characters, 40% environment)
  • Comprehensive reporting with per-character and per-image analysis

The test uses real storyboard images located in generated-images/scene_1_A_lush__ancient_fore_*.png to validate the visual consistency evaluation system.

5) PDF Upload Workflow: examples/pdf-upload.ts

Generates a storyboard then uploads the PDF via the provided workflow helper.

Additional env required:

 1export AWS_ACCESS_KEY_ID="..."
 2export AWS_SECRET_ACCESS_KEY="..."
 3export AWS_REGION="us-east-1"         # or your region
 4export S3_BUCKET="your-bucket-name"   # your S3 bucket name
 5# Optional (Zapier webhook → Google Drive, Slack, etc.)
 6export ZAPIER_WEBHOOK_URL="https://hooks.zapier.com/..."

Run:

npx tsx examples/pdf-upload.ts

The script prints the upload result (S3 URL and/or downstream integration status).

Run All Examples Sequentially

 1for f in basic-usage streaming workflow-automated evals test-character-consistency pdf-upload; do \
 2  npx tsx examples/$f.ts; \
 3done

🖼️ Generated Images & Test Data

The generated-images/ folder contains sample storyboard images used for testing the visual consistency evaluation system:

  • scene_1_A_lush__ancient_fore_*.png: 5 forest scene images featuring a young explorer and crow companion
  • Used by: Character consistency evaluation tests and examples
  • Purpose: Demonstrates multi-modal evaluation capabilities using real generated content
  • Format: PNG images generated by Google Imagen through the Image Generator Agent
  • Evaluation: These images achieve ~85-90% consistency scores in character and environment analysis

🔗 Integrations

Google Drive Integration

  • Direct Upload: PDF files are automatically uploaded to specified Google Drive folders
  • Folder Organization: Files are organized by date and project
  • Access Control: Secure authentication using OAuth 2.0
  • File Management: Automatic file naming and metadata tagging

Slack Notifications via Zapier

  • Real-time Updates: Instant notifications for upload status and processing results
  • Rich Notifications: Include file links, processing status, and error details
  • Customizable: Configure notification channels and message formats
  • Error Handling: Notifications for failed uploads or processing errors

Zapier Automation Flow: Upload PDF from S3 to Google Drive + Slack Notification

This Zap handles the following automation:

  • Accepts a PDF file URL (typically from S3) via webhook.
  • Uploads that file to Google Drive.
  • Sends a Slack DM with the Google Drive link.

🔗 Zap Structure (3-Step Flow)

✅ Step 1: Webhooks by Zapier — Catch Hook

  • Trigger: Catch Hook
  • Use Case: Receive incoming POST request from your Mastra Agent or S3 MCP server.
  • Expected Payload:
 1{
 2  "fileUrl": "https://your-s3-bucket.amazonaws.com/storybook.pdf",
 3  "filename": "storybook.pdf"
 4}

✅ Step 2: Google Drive — Upload File

  • Action: Upload File
  • Drive: Your connected Google Drive account
  • Folder: Destination folder of your choice
  • File: Use the fileUrl from Step 1
  • File Name: Use filename from Step 1
  • Convert to Google Docs: No (keep original PDF format)

Note: This step returns a file ID (e.g., 1ABC123xyz456) which you will use to build a public link.

✅ Step 3: Slack — Send Direct Message

  • Action: Send Direct Message
  • To: Your Slack user ID or another teammate
  • Message Body:
 1🚀 PDF uploaded successfully!
 2📄 File: *{{filename}}*
 3🔗 <https://drive.google.com/file/d/{{id}}/view?usp=sharing|Click here to check it out>

Replace {{filename}} and {{id}} with the dynamic fields from Step 1 and Step 2.

✅ Result:

Your app or agent can now generate PDFs → upload via S3 URL → send to Zapier webhook → Zap uploads to Google Drive → Slack DM sent with public PDF link.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run the evaluation suite
  6. Submit a pull request

📄 License

This template is part of the Mastra framework and follows the same licensing terms.

🆘 Support

  • Issues: Report bugs and feature requests via GitHub Issues
  • Discussions: Join community discussions on GitHub Discussions
  • Documentation: Check the EVALS.md file for evaluation system details