Flash Cards from PDF Template

A simple Mastra template that generates educational flash cards from PDF documents. This template demonstrates how to extract content from PDFs, analyze it, and create question-answer pairs for studying.

Features

  • PDF Processing: Extract educational content from PDF documents (URL or file upload)
  • Flash Card Generation: Create simple question-answer pairs from the content
  • Optional Images: Generate educational images for visual learning (first 3 cards)
  • Simple Structure: Easy to understand and extend

Quick Start

  1. Install dependencies:

    pnpm install

  2. Set up environment variables: Create a .env file with:

     1OPENAI_API_KEY=your_openai_api_key
 2
 3# Optional - for image generation
 4AWS_REGION=us-east-1
 5AWS_ACCESS_KEY_ID=your_aws_access_key
 6AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
 7S3_BUCKET_NAME=your-bucket-name
 8S3_PUBLIC_URL_BASE=https://your-bucket.s3.amazonaws.com

  3. Run the application:

    pnpm dev

Usage

Basic Example

 1import { mastra } from './src/mastra';
 2
 3// Generate flash cards from a PDF URL
 4const result = await mastra.runWorkflow('flash-cards-generation-workflow', {
 5  pdfUrl: 'https://example.com/document.pdf',
 6  numberOfCards: 10,
 7  generateImages: false,
 8});
 9
10console.log(`Generated ${result.totalCards} flash cards`);
11result.flashCards.forEach(card => {
12  console.log(`Q: ${card.question}`);
13  console.log(`A: ${card.answer}`);
14  console.log(`Difficulty: ${card.difficulty}\n`);
15});

With File Upload

 1// Generate from uploaded PDF (base64 encoded)
 2const result = await mastra.runWorkflow('flash-cards-generation-workflow', {
 3  pdfData: 'data:application/pdf;base64,JVBERi0xLjQK...',
 4  filename: 'my-notes.pdf',
 5  numberOfCards: 15,
 6  generateImages: true, // Will generate images for first 3 cards
 7});

Components

Workflow

The main workflow (flash-cards-generation-workflow) has three steps:

  1. Extract PDF Content - Gets text from the PDF and identifies key concepts
  2. Generate Flash Cards - Creates question-answer pairs from the content
  3. Add Images (optional) - Generates educational images for visual learning

Tools

  • PDF Content Extractor - Extracts and analyzes PDF content
  • Flash Card Generator - Creates question-answer pairs
  • Educational Image Tool - Generates images using DALL-E

Agents

  • Flash Card Creator - Main agent for orchestrating the process
  • PDF Processor - Processes PDF content for educational use
  • Content Analyzer - Analyzes content for key learning points
  • Educational Image Creator - Creates visual learning aids

Input Parameters

 1{
 2  // PDF source (one required)
 3  pdfUrl?: string;        // URL to PDF file
 4  pdfData?: string;       // Base64 encoded PDF data
 5  filename?: string;      // Filename when using pdfData
 6
 7  // Options
 8  numberOfCards: number;  // 5-30 cards (default: 10)
 9  generateImages: boolean; // Generate images (default: false)
10}

Output Structure

 1{
 2  flashCards: [
 3    {
 4      question: string;     // The question
 5      answer: string;       // The answer
 6      category: string;     // Subject area
 7      difficulty: 'easy' | 'medium' | 'hard';
 8      imageUrl?: string;    // Optional image URL
 9    }
10  ],
11  totalCards: number;
12  subjectArea: string;
13  sourceInfo: {
14    pdfUrl?: string;
15    filename?: string;
16    pagesCount: number;
17  }
18}

Flash Card Types

The template generates three types of cards:

  1. Definition Cards - "What is X?" questions
  2. Concept Cards - "Explain Y" questions
  3. Fact Cards - Questions about specific facts

Cards are distributed across three difficulty levels:

  • Easy - Basic definitions and facts
  • Medium - Concept explanations
  • Hard - More complex concepts

Extending the Template

This template is designed to be simple and easy to modify:

Add More Question Types

Edit src/mastra/tools/flash-card-generator-tool.ts to add new question formats:

 1// Add a new question type
 2flashCards.push({
 3  question: `Why is ${concept.concept} important?`,
 4  answer: concept.explanation,
 5  category: subjectArea,
 6  difficulty: 'medium',
 7});

Customize Image Generation

Modify src/mastra/workflows/flash-cards-generation-workflow.ts to change which cards get images:

 1// Currently generates for first 3 cards
 2if (i < 3 && generateImages) {
 3  // Change to generate for all cards
 4  if (generateImages) {
 5    // Generate image...
 6  }
 7}

Add New Analysis

Extend the content analyzer in src/mastra/tools/content-analyzer-tool.ts to extract additional information from PDFs.

Environment Setup

Required

  • OPENAI_API_KEY - For AI content analysis and generation

Optional (for images)

  • AWS S3 credentials for storing generated images
  • Configure bucket for public read access

Development

 1# Install dependencies
 2pnpm install
 3
 4# Run development server
 5pnpm dev
 6
 7# Build for production
 8pnpm build
 9
10# Start production server
11pnpm start

Notes

  • The template processes PDFs by extracting text, so scanned image PDFs may not work well
  • Image generation is limited to 3 cards by default to manage costs
  • Flash cards are kept simple - just question, answer, and basic metadata
  • The template is designed as a learning example, not a production-ready product