📚 Storybook Generator

Create beautiful, illustrated storybooks about any topic using AI!

An intelligent multi-agent system that creates professional storybooks with custom illustrations. Perfect for parents, educators, and anyone who loves storytelling!

✨ Features

• 🤖 Multi-Agent AI System: 5 specialized AI agents working together
• 📖 Complete Storybooks: 5 chapters, ~100 words each, age-appropriate for 4-8 years
• 🎨 Custom Illustrations: AI-generated images using FLUX.1-dev model
• 📄 Professional Output: High-quality PDF and HTML formats
• 🎯 Any Topic: Create stories about anything your child loves
• 🔄 Smart Rate Limiting: Handles API quotas gracefully
• 📱 Mobile-Friendly: Responsive HTML output for all devices

🎬 Demo

$ python main.py

📚 What topic would you like your storybook to be about?

💡 Here are some popular topics for inspiration:
   • Animals (farm animals, jungle animals, pets)
   • Space and planets
   • Friendship and kindness
   [...]

✏️  Enter your story topic: magical forest animals

📖 You chose: 'magical forest animals'
Is this correct? (y/n): y

🎨 Creating a wonderful storybook about 'magical forest animals' for you!
⏳ This may take several minutes due to rate limiting...

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Google AI API key (for Gemini)
• Hugging Face API key (for FLUX.1-dev)

Installation

1. Clone the repository:

   git clone https://github.com/naakaarafr/Storybook-Generator.git
   cd Storybook-Generator
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up environment variables:

   # Create a .env file or export directly
   export GOOGLE_API_KEY="your_google_ai_api_key_here"
   export HUGGINGFACE_API_KEY="your_huggingface_api_key_here"
   

4. Install PDF tools (optional but recommended):

   # Option 1: WeasyPrint (recommended)
   pip install weasyprint
   
   # Option 2: mdpdf
   pip install mdpdf
   
   # Option 3: pdfkit + wkhtmltopdf
   pip install pdfkit
   # Then install wkhtmltopdf from https://wkhtmltopdf.org/downloads.html
   

5. Run the generator:

   python main.py
   

🔑 API Keys Setup

Google AI (Gemini) API Key

1. Visit Google AI Studio
2. Create a new project or select existing one
3. Generate an API key
4. Set the GOOGLE_API_KEY environment variable

Hugging Face API Key

1. Visit Hugging Face
2. Create a new token with "Read" permissions
3. Set the HUGGINGFACE_API_KEY environment variable

🛠️ How It Works

The system uses 5 specialized AI agents in a sequential workflow:

graph LR
    A[Story Outliner] --> B[Story Writer]
    B --> C[Image Generator]
    C --> D[Content Formatter]
    D --> E[PDF Converter]

🤖 The AI Agents

1. 📋 Story Outliner

   • Creates story structure and character profiles
   • Develops 5 chapter outlines
   • Ensures age-appropriate themes

2. ✍️ Story Writer

   • Writes complete story content
   • ~100 words per chapter
   • Maintains narrative consistency

3. 🎨 Image Generator

   • Creates custom illustrations using FLUX.1-dev
   • One image per chapter
   • Handles generation failures gracefully

4. 📝 Content Formatter

   • Formats content with professional styling
   • Creates publication-ready layouts
   • Handles images and placeholders

5. 📄 PDF Converter

   • Converts to high-quality PDF
   • Multiple conversion methods
   • Fallback to enhanced HTML

📁 Project Structure

storybook-generator/
├── agents.py              # AI agent definitions
├── config.py              # Configuration and rate limiting
├── crew.py                # CrewAI crew setup
├── main.py                # Main application entry point
├── tasks.py               # Task definitions for agents
├── tools.py               # Custom tools and utilities
├── template.md            # Story template (auto-generated)
├── requirements.txt       # Python dependencies
├── README.md              # This file
└── output/
    ├── story.md           # Generated markdown story
    ├── story.pdf          # Generated PDF (if conversion succeeds)
    ├── story.html         # Enhanced HTML version
    └── *.png              # Generated illustrations

⚙️ Configuration

Rate Limiting

The system includes intelligent rate limiting for API calls:

• Gemini API: 15 requests per minute (configurable)
• Automatic retries with exponential backoff
• Smart waiting between failed requests
• Usage tracking and warnings

Customization

You can customize the system by modifying:

• config.py: API settings and rate limits
• agents.py: Agent behaviors and goals
• tasks.py: Task descriptions and requirements
• tools.py: Image generation and PDF conversion

📊 Output Files

After successful generation, you'll find:

• 📖 story.md: Markdown version of your storybook
• 📄 story.pdf: Professional PDF (if conversion succeeds)
• 🌐 story.html: Enhanced HTML with print functionality
• *🖼️ .png: Generated illustrations (or placeholder descriptions)

🎨 Sample Topics

Try these engaging topics:

Animals & Nature:

• Magical forest animals
• Ocean adventure with dolphins
• Farm animals' friendship
• Jungle safari expedition

Space & Science:

• Journey to the moon
• Robot friends from space
• Solar system exploration
• Time machine adventures

Fantasy & Magic:

• Princess and the dragon
• Wizard's apprentice
• Fairy garden secrets
• Enchanted castle mystery

Everyday Adventures:

• First day at school
• Family camping trip
• Cooking with grandma
• Neighborhood helpers

🔧 Troubleshooting

Common Issues

❌ "No PDF conversion tools found"

# Install one of these:
pip install weasyprint       # Recommended
pip install mdpdf           # Alternative
pip install pdfkit          # Requires wkhtmltopdf

❌ "Rate limit exceeded"

• The system handles this automatically
• Wait for the specified time
• Check your API quotas

❌ "Image generation failed"

• Images will be replaced with detailed descriptions
• Check your Hugging Face API key
• Verify API quota availability

❌ "Font errors with WeasyPrint"

• Usually safe to ignore
• PDF is often created successfully
• Try using mdpdf as alternative

Environment Variables

Create a .env file in the project root:

GOOGLE_API_KEY=your_google_ai_api_key_here
HUGGINGFACE_API_KEY=your_huggingface_api_key_here

📋 Requirements

Python Packages

crewai>=0.28.0
langchain-google-genai>=1.0.0
pillow>=9.0.0
requests>=2.28.0
markdown>=3.4.0

# PDF conversion (choose one or more)
weasyprint>=60.0  # Recommended
mdpdf>=1.0.0      # Alternative
pdfkit>=1.0.0     # Requires wkhtmltopdf

System Requirements

• Python 3.8+
• Internet connection for API calls
• 500MB+ free disk space
• Optional: wkhtmltopdf for pdfkit

🤝 Contributing

Contributions are welcome! Here are some ways you can help:

1. 🐛 Bug Reports: Open an issue with details
2. 💡 Feature Requests: Suggest new capabilities
3. 🔧 Code Improvements: Submit pull requests
4. 📚 Documentation: Help improve docs
5. 🎨 Templates: Create new story templates

Development Setup

# Clone and setup
git clone https://github.com/naakaarafr/storybook-generator.git
cd storybook-generator

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .
pip install -r requirements-dev.txt  # If it exists

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• CrewAI: Multi-agent orchestration framework
• Google Gemini: Advanced language model
• FLUX.1-dev: State-of-the-art image generation
• Hugging Face: AI model hosting and inference

📞 Support

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Check this README and code comments

🎯 Roadmap

Future enhancements planned:

• Multiple Languages: Support for non-English stories
• Custom Characters: Upload and use custom character descriptions
• Interactive Mode: Real-time story editing and preview
• Audio Narration: Text-to-speech integration
• Batch Generation: Create multiple stories at once
• Template Library: Pre-made story templates
• Character Consistency: Maintain character appearance across images
• Story Variations: Generate alternative versions of the same story

---