🚀 Professional Book Series Generator

Transform ideas into publishable book series with AI-powered automation

Generate complete, professional book series from simple concepts using advanced AI agents, multi-provider LLM support, and automated publishing workflows.

---

⚡ Quick Start (5 minutes)

🚨 IMPORTANT: CLI Commands Must Be Run In Order!

The CLI uses a session-based workflow where each command saves data for the next:

generate-idea → generate-book → generate-pdf → generate-images
     ↓              ↓              ↓              ↓
  Series Idea   Book Plan     PDF Files      Images

Quick Example:

# 1. Setup
git clone <repository-url> && cd book-series-generator
poetry install && cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 2. Test setup
poetry run bsg init

# 3. Create series idea (REQUIRED FIRST!)
poetry run bsg generate-idea --concept "friendly dragons help children" --num-books 2

# 4. Plan first book (uses series from step 3)
poetry run bsg generate-book --book-number 1

# 5. Create PDF (uses book plan from step 4)
poetry run bsg generate-pdf --book-number 1

# 6. Check results
poetry run bsg status && ls output/

📖 Having Issues? Need More Detail?

👉 See CLI_QUICK_START.md for comprehensive instructions, troubleshooting, and examples.

Result: You now have a complete book ready for images and publishing! 🎉

---

🎯 Core Features

🤖 Multi-Provider LLM Support

• OpenAI (GPT-4, GPT-3.5-turbo)
• Anthropic (Claude-3 Opus, Sonnet, Haiku)
• Grok (via X.AI API)
• Ollama (Local models)
• Automatic fallbacks between providers

📝 Step-by-Step Generation

1. 💡 Generate Ideas - AI creates series concepts and outlines
2. 📖 Plan Books - Detailed chapter and scene planning
3. 📄 Create PDFs - Professional formatting without images
4. 🖼️ Add Images - Character-consistent illustrations (setup ready)
5. 🚀 Publish - Amazon KDP automation (coming soon)

🧪 Professional Testing

• Component testing for all system parts
• LLM provider validation and fallbacks
• PDF generation verification
• Interactive debugging tools

⚙️ Flexible Configuration

• Easy .env file setup for all API keys and settings
• Choose your preferred LLM provider
• Adjust generation parameters
• Comprehensive environment validation
• Session management with state persistence
• Rich console output with progress tracking

---

⚙️ Configuration

Environment Variables Setup

The system uses environment variables for API keys and configuration. The easiest way is to use a .env file:

# Copy the example file
cp .env.example .env

# Edit with your favorite editor
nano .env

Required Variables

• OPENAI_API_KEY - For GPT models and DALL-E image generation

Optional Variables

• ANTHROPIC_API_KEY - For Claude models (backup LLM)
• GROK_API_KEY - For X.AI Grok models (additional backup)
• AMAZON_EMAIL & AMAZON_PASSWORD - For KDP automation
• APIFY_API_KEY - For market research data

Automatic .env Setup

The bsg init command will help you set up your .env file:

poetry run bsg init
# Prompts to create .env from example
# Offers to open in your default editor
# Validates all configuration

---

📋 Step-by-Step Workflow

Phase 1: Initialize & Test

# Set up and validate system
poetry run bsg init

# Test individual components
poetry run bsg test-components

# Check configuration
poetry run bsg status

Phase 2: Generate Content

# Generate series idea
poetry run bsg generate-idea \
  --concept "underwater adventures teaching ocean science" \
  --audience "children 8-12" \
  --num-books 4

# Plan each book individually
poetry run bsg generate-book --book-number 1 --interactive
poetry run bsg generate-book --book-number 2 
poetry run bsg generate-book --book-number 3

# Generate PDFs (without images first)
poetry run bsg generate-pdf --book-number 1
poetry run bsg generate-pdf --book-number 2 --include-placeholders

Phase 3: Add Images & Publish

# Set up image generation (MCP integration)
poetry run bsg generate-images --series --type covers

# Validate everything
poetry run bsg validate

# Check final status
poetry run bsg status

---

🛠️ Available Commands

Command	Purpose	Example
init	Initialize and validate system	bsg init
generate-idea	Create series concept and outline	bsg generate-idea -c "space adventures"
generate-book	Plan specific book in detail	bsg generate-book -b 1 --interactive
generate-pdf	Create formatted PDF	bsg generate-pdf -b 1 -p
generate-images	Set up image generation	bsg generate-images --series
test-components	Test all system components	bsg test-components
validate	Validate current progress	bsg validate --step pdf
status	Show session progress	bsg status

---

🔧 Configuration

Environment Variables

# Required (choose at least one)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key  
GROK_API_KEY=your_grok_key

# Optional for full automation
AMAZON_EMAIL=your_amazon_email
AMAZON_PASSWORD=your_amazon_password
APIFY_API_KEY=your_apify_key

LLM Provider Selection

# Use specific provider and model
bsg --provider openai --model gpt-4 generate-idea -c "adventure story"
bsg --provider anthropic --model claude-3-opus generate-book -b 1
bsg --provider grok --model grok-beta generate-pdf -b 1

Generation Parameters

# Via config or CLI options
target_audience = "children 6-10"  # Age range
number_of_books = 3               # Series length  
target_book_length = 5000         # Words per book
reading_level = "grade 3"         # Complexity
include_educational_elements = True

---

📁 Project Structure

book-series-generator/
├── 📄 pyproject.toml          # Poetry configuration
├── 📖 README.md               # This file
├── 📁 src/book_series_generator/
│   ├── 🧠 models/             # Pydantic data models
│   ├── 🤖 agents/             # AI agents for generation
│   ├── 🔧 services/           # Core services (LLM, generation)
│   ├── 📄 pdf/                # PDF generation
│   ├── 🖼️ image_generation/   # Image generation (MCP)
│   ├── 🚀 automation/         # Publishing automation
│   └── 🖥️ cli.py              # Command-line interface
├── 📁 tests/                  # Comprehensive test suite
├── 📁 docs/                   # Detailed documentation
└── 📁 output/                 # Generated content

---

🧪 Testing & Validation

System Testing

# Test all components
poetry run bsg test-components

# Test specific parts
poetry run pytest tests/unit/test_llm_service.py
poetry run pytest tests/integration/ -v

Validation Workflow

# Validate each step
poetry run bsg validate --step idea    # Check series concept
poetry run bsg validate --step book    # Check book plans
poetry run bsg validate --step pdf     # Check PDF generation
poetry run bsg validate               # Validate everything

Quality Checks

# Code quality
poetry run black src/ tests/
poetry run isort src/ tests/  
poetry run flake8 src/
poetry run mypy src/

# Test coverage
poetry run pytest --cov=book_series_generator --cov-report=html

---

🔄 Development Workflow

Adding New LLM Providers

1. Add provider config in src/book_series_generator/models/llm_config.py
2. Implement provider class in src/book_series_generator/services/llm_service.py
3. Test with poetry run bsg test-components

Extending Generation Steps

1. Add new commands in src/book_series_generator/cli.py
2. Implement validation in CLI validation functions
3. Add tests in tests/unit/test_cli.py

Custom Book Templates

1. Modify src/book_series_generator/pdf/templates.py
2. Test with poetry run bsg generate-pdf --include-placeholders
3. Validate with poetry run bsg validate --step pdf

---

🚨 Troubleshooting

Common Issues

❌ "No LLM providers available"

# Check API keys
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

# Test providers
poetry run bsg test-components

❌ "PDF generation failed"

# Check dependencies
poetry install

# Test PDF generation
poetry run bsg test-components

❌ "Session state lost"

# Check session directory
poetry run bsg status

# Start new session
poetry run bsg init

Debug Mode

# Verbose output
poetry run bsg --verbose test-components

# Check logs in session directory
ls output/session_*/

---

🎯 Next Steps

Immediate Goals

1. ✅ Multi-provider LLM support
2. ✅ Step-by-step CLI workflow
3. ✅ Professional PDF generation
4. 🚧 Image generation (MCP setup ready)
5. ⏳ Amazon KDP automation

Future Enhancements

• Audiobook generation with text-to-speech
• Multi-language content generation
• Advanced analytics and market research
• Social media integration
• Enterprise API endpoints

---

🤝 Contributing

This is a private, proprietary system. Contributing guidelines:

1. Code Quality: All code must pass tests and type checking
2. Documentation: Update docs for any new features
3. Testing: Add tests for new functionality
4. CLI Integration: New features should integrate with CLI workflow

# Development setup
poetry install --with dev,docs
poetry run pre-commit install

# Before committing
poetry run pytest
poetry run black src/ tests/
poetry run mypy src/

---

📞 Support

System Status: Production ready for content generation Testing: Comprehensive test suite with 80%+ coverage Documentation: Complete CLI reference and step-by-step guides

For issues:

1. Run poetry run bsg test-components
2. Check poetry run bsg status
3. Review session logs in output/session_*/

---

Ready to generate your first book series? Start with poetry run bsg init! 🚀