carousel-generator-v2

What this skill does

# Carousel Generator v2

**World-class Instagram carousel generator** with AI content intelligence, multi-tool visual generation, and professional design systems.

---

## Quick Start

```bash
# Generate from topic
python -m scripts.carousel_generator "GLP-1 for weight loss" --template tips_5

# Generate from JSON structure
python -m scripts.carousel_generator input.json --output ./my-carousel/

# Generate from long-form content (backward mode)
python -m scripts.carousel_generator newsletter.txt

# Generate both 4:5 and 1:1 outputs
python -m scripts.carousel_generator "Statin myths" --template myth_busting --both-ratios
```

Or use in Claude Code:
```
"Create a carousel about statins myth-busting"
"Generate Instagram slides for GLP-1 benefits"
"Turn this newsletter into carousel slides: [paste content]"
```

---

## Architecture

```
INPUT LAYER
├── Topic only ("GLP-1 for weight loss")
├── Long-form content (newsletter, script, thread)
└── Structured JSON (slides already defined)
        ↓
CONTENT INTELLIGENCE (Claude/GPT-4o-mini)
├── Research via PubMed MCP + AstraDB RAG
├── Classify: 4A Framework (Actionable/Analytical/etc.)
├── Select template type (Tips/Stats/Story/Compare)
├── Structure into 8-10 slides with hook + CTA
└── Output: Structured JSON with slide specs
        ↓
VISUAL GENERATION (Multi-Tool Routing)
├── Standard slides → React + Puppeteer (default, high fidelity)
├── Pillow → Fallback renderer if Puppeteer unavailable
├── Infographics → Gemini API (medical accuracy)
├── Data slides → Plotly (charts, forest plots)
└── Icons → Health Icons (free, SVG, medical)
        ↓
QUALITY GATES
├── WCAG AA contrast check (4.5:1 ratio)
├── Text density check (≤15 words per slide)
├── Anti-AI voice verification
├── Brand consistency (design tokens)
└── Mobile preview generation
        ↓
OUTPUT
├── 8-10 PNG slides (1080×1350 or 1080×1080)
├── Dual ratio naming: slide_01_4x5.png, slide_01_1x1.png
├── Caption suggestions per slide
├── Alt text for accessibility
├── Hashtag recommendations
└── Quality report
```

---

## 10 Slide Types

| Type | Purpose | Best For |
|------|---------|----------|
| **HOOK** | Bold opening, curiosity gap | First slide, grab attention |
| **TIPS** | Numbered tips with icons | Actionable content, lists |
| **STATS** | Big number + context | Data-driven insights |
| **COMPARISON** | Before/after, vs layout | Contrasts, improvements |
| **STORY** | Patient narrative, quote | Human interest, case studies |
| **DATA** | Chart, graph, forest plot | Research results, evidence |
| **STEPS** | Process with numbered steps | How-to guides, procedures |
| **MYTH** | Crossed-out myth + truth | Myth-busting, corrections |
| **QUOTE** | Expert opinion | Authority, credibility |
| **CTA** | Call to action | Last slide, follow prompt |

---

## Template Presets

### tips_5 (Default)
```
HOOK → TIPS → TIPS → TIPS → TIPS → TIPS → STATS → CTA
```
Best for: Actionable advice, numbered lists, practical content

### myth_busting
```
HOOK → MYTH → MYTH → MYTH → STATS → CTA
```
Best for: Correcting misconceptions, debunking myths

### patient_story
```
HOOK → STORY → STORY → DATA → TIPS → QUOTE → CTA
```
Best for: Case studies, patient journeys, human interest

### data_driven
```
HOOK → STATS → DATA → COMPARISON → TIPS → CTA
```
Best for: Clinical trials, research findings, evidence-based content

### how_to
```
HOOK → STEPS → STEPS → STEPS → TIPS → CTA
```
Best for: Tutorials, procedures, step-by-step guides

---

## CLI Options

```bash
python -m scripts.carousel_generator INPUT [OPTIONS]

Arguments:
  INPUT                    Topic string, JSON file, or text file

Options:
  -t, --template TEXT      Template preset (tips_5, myth_busting, etc.)
  -a, --account INTEGER    Account: 1=@heartdocshailesh, [email protected]
  -r, --ratio TEXT         Aspect ratio: 4:5 (Instagram) or 1:1 (square)
  --both-ratios            Generate both 4:5 and 1:1 outputs
  -o, --output PATH        Output directory
  --no-ai                  Skip AI content structuring (uses curated database if available)
```

### Examples

```bash
# Basic usage
python -m scripts.carousel_generator "5 signs of heart attack"

# Myth-busting format
python -m scripts.carousel_generator "Statin myths" --template myth_busting

# Use secondary account
python -m scripts.carousel_generator "CAC scoring" --account 2

# Square format for multi-platform
python -m scripts.carousel_generator "BP monitoring" --ratio 1:1

# Dual ratio output
python -m scripts.carousel_generator "Hypertension myths" --both-ratios

# Custom output directory
python -m scripts.carousel_generator "GLP-1" -o ./client-carousel/
```

---

## Python API

```python
from scripts.carousel_generator import CarouselGenerator
from scripts.models import CarouselConfig, AspectRatio

# Configure
config = CarouselConfig(
    account=1,
    aspect_ratio=AspectRatio.INSTAGRAM_4X5,
    max_slides=10,
    check_contrast=True,
    check_anti_ai=True
)

# Initialize generator
generator = CarouselGenerator(config)

# Generate from topic
result = generator.generate_from_topic(
    "GLP-1 for weight loss",
    template="tips_5",
    use_ai=True
)

print(f"Generated {len(result.slides)} slides to {result.output_directory}")
```

### Generate from JSON Structure

```python
# Create structured input
carousel_json = {
    "topic": "Heart Health Tips",
    "slides": [
        {
            "type": "hook",
            "title": "5 Things Your Cardiologist Wishes You Knew",
            "subtitle": "Evidence-based insights"
        },
        {
            "type": "tips",
            "title": "Tip #1",
            "bullet_points": [
                "LDL target matters more than total cholesterol",
                "Below 100 mg/dL for most, below 70 for high risk"
            ]
        },
        {
            "type": "cta",
            "cta_text": "Follow for more",
            "cta_handle": "@heartdocshailesh"
        }
    ]
}

import json
with open("input.json", "w") as f:
    json.dump(carousel_json, f)

result = generator.generate_from_json(Path("input.json"))
```

### Generate from Long-form Content (Backward Mode)

```python
newsletter_content = """
# The Truth About Statins

Recent meta-analyses have conclusively shown that statins reduce
cardiovascular events by 25-30%. The most common side effect,
muscle pain, occurs in only 5-10% of patients...
"""

result = generator.generate_from_longform(
    newsletter_content,
    content_type="newsletter"
)
```

---

## Quality Checker

The generator automatically runs quality checks:

```python
from scripts.quality_checker import QualityChecker
from scripts.models import Carousel

checker = QualityChecker()

# Run all checks
results = checker.run_all_checks(carousel)

# Generate report
report = checker.generate_report(results)
print(report)
```

### Quality Checks Performed

| Check | Threshold | Description |
|-------|-----------|-------------|
| **text_density** | ≤15 words/slide | Ensures scannability |
| **contrast_ratio** | ≥4.5:1 | WCAG AA compliance |
| **anti_ai** | No AI patterns | Detects AI-generated phrases |
| **slide_count** | 8-10 slides | Optimal engagement |
| **hook_quality** | Question or number | Engaging first slide |
| **cta_presence** | Last slide is CTA | Clear call to action |

### Anti-AI Detection

The checker flags these patterns:
- "It's important to note"
- "In conclusion"
- "Stands as a testament"
- "Groundbreaking" / "Game-changing"
- "Vibrant tapestry"
- Em dash overuse (more than 1 per paragraph)

---

## Brand Tokens

Design tokens are stored in `tokens/brand-tokens.json`:

### Colors
| Token | Value | Use |
|-------|-------|-----|
| primary | #207178 | Titles, CTAs, primary brand |
| secondary | #E4F1EF | Backgrounds, soft elements |
| accent | #F28C81 | Icons, highlights, bullets |
| neutralLight | #F8F9FA | Alternative backgrounds |
| neutralDark | #333333 | Body text |
| alert | #E63946 | Emphasis, danger, alerts |

### Typography
| Element | Font | Size