youtube-summarizer/backend/CLI_README.md

# YouTube Summarizer CLI Tool

A powerful command-line interface for managing YouTube video summaries with AI-powered generation, regeneration, and refinement capabilities.

## Features

- 🎥 **Video Summary Management**: Add, regenerate, and refine YouTube video summaries
- 🤖 **Multi-Model Support**: Use DeepSeek, Anthropic Claude, OpenAI GPT, or Google Gemini
- 📝 **Custom Prompts**: Full control over summarization with custom prompts
- 🔄 **Iterative Refinement**: Refine summaries until they meet your needs
- 📊 **Mermaid Diagrams**: Automatic generation and rendering of visual diagrams
- 📦 **Batch Processing**: Process multiple videos at once
- 🔍 **Comparison Tools**: Compare summaries generated with different models
- 💾 **Export Options**: Export summaries to JSON with full metadata

## Installation

```bash
# Navigate to the backend directory
cd apps/youtube-summarizer/backend

# Install required dependencies
pip install click rich sqlalchemy

# For Mermaid diagram rendering (optional)
npm install -g @mermaid-js/mermaid-cli
npm install -g mermaid-ascii  # For terminal ASCII diagrams
```

## Usage

### Basic Commands

```bash
# Set Python path (required)
export PYTHONPATH=/Users/enias/projects/my-ai-projects/apps/youtube-summarizer

# View help
python3 backend/cli.py --help

# Enable debug mode
python3 backend/cli.py --debug [command]
```

### List Summaries

```bash
# List recent summaries
python3 backend/cli.py list

# List with filters
python3 backend/cli.py list --limit 20
python3 backend/cli.py list --user-id USER_ID
python3 backend/cli.py list --video-id VIDEO_ID
```

### Show Summary Details

```bash
# Show summary details
python3 backend/cli.py show SUMMARY_ID

# Export to JSON
python3 backend/cli.py show SUMMARY_ID --export

# Render Mermaid diagrams if present
python3 backend/cli.py show SUMMARY_ID --render-diagrams

# Get diagram suggestions based on content
python3 backend/cli.py show SUMMARY_ID --suggest-diagrams
```

### Add New Summary

```bash
# Basic usage
python3 backend/cli.py add "https://youtube.com/watch?v=..."

# With options
python3 backend/cli.py add "https://youtube.com/watch?v=..." \
  --model anthropic \
  --length detailed \
  --diagrams

# With custom prompt
python3 backend/cli.py add "https://youtube.com/watch?v=..." \
  --prompt "Focus on technical details and provide code examples"

# With focus areas
python3 backend/cli.py add "https://youtube.com/watch?v=..." \
  --focus "architecture" \
  --focus "performance" \
  --focus "security"
```

### Regenerate Summary

```bash
# Regenerate with same model
python3 backend/cli.py regenerate SUMMARY_ID

# Switch to different model
python3 backend/cli.py regenerate SUMMARY_ID --model gemini

# With custom prompt
python3 backend/cli.py regenerate SUMMARY_ID \
  --prompt "Make it more concise and actionable"

# Change length and add diagrams
python3 backend/cli.py regenerate SUMMARY_ID \
  --length brief \
  --diagrams
```

### Refine Summary (Iterative Improvement)

```bash
# Interactive refinement mode
python3 backend/cli.py refine SUMMARY_ID --interactive

# In interactive mode:
# - Enter refinement instructions
# - Type 'done' when satisfied
# - Type 'undo' to revert last change

# Single refinement
python3 backend/cli.py refine SUMMARY_ID

# Refine with different model
python3 backend/cli.py refine SUMMARY_ID --model anthropic
```

### Batch Processing

```bash
# Process multiple videos from file
python3 backend/cli.py batch --input-file urls.txt

# Interactive batch mode (enter URLs manually)
python3 backend/cli.py batch

# Batch with options
python3 backend/cli.py batch \
  --input-file urls.txt \
  --model gemini \
  --length brief \
  --prompt "Focus on key takeaways"
```

### Compare Summaries

```bash
# Compare two summaries
python3 backend/cli.py compare SUMMARY_ID_1 SUMMARY_ID_2
```

### Manage Prompts

```bash
# Save a custom prompt template
python3 backend/cli.py save-prompt \
  --prompt "Summarize focusing on practical applications" \
  --name "practical" \
  --description "Focus on practical applications"

# List saved prompts
python3 backend/cli.py list-prompts
```

### Maintenance

```bash
# View statistics
python3 backend/cli.py stats

# Clean up old summaries
python3 backend/cli.py cleanup --days 30 --dry-run
python3 backend/cli.py cleanup --days 30  # Actually delete

# Delete specific summary
python3 backend/cli.py delete SUMMARY_ID
```

## Mermaid Diagram Support

The CLI can automatically generate and include Mermaid diagrams in summaries when the `--diagrams` flag is used. The AI will intelligently decide when diagrams would enhance understanding.

### Diagram Types

- **Flowcharts**: For processes and workflows
- **Sequence Diagrams**: For interactions and communications
- **Mind Maps**: For concept relationships
- **Timelines**: For chronological information
- **State Diagrams**: For system states
- **Entity Relationship**: For data structures
- **Pie Charts**: For statistical distributions

### Example Prompts for Diagrams

```bash
# Request specific diagram types
python3 backend/cli.py add "URL" --prompt \
  "Include a flowchart for the main process and a timeline of events"

# Let AI decide on diagrams
python3 backend/cli.py add "URL" --diagrams

# Refine to add diagrams
python3 backend/cli.py refine SUMMARY_ID --interactive
# Then type: "Add a mind map showing the relationships between concepts"
```

### Rendering Diagrams

```bash
# Render diagrams from existing summary
python3 backend/cli.py show SUMMARY_ID --render-diagrams

# Diagrams are saved to: diagrams/SUMMARY_ID/
# Formats: .svg (vector), .png (image), .mmd (source code)
```

## Interactive Refinement Workflow

The refine command with `--interactive` flag provides a powerful iterative improvement workflow:

1. **View Current Summary**: Shows the existing summary
2. **Enter Instructions**: Provide specific refinement instructions
3. **Apply Changes**: AI regenerates based on your instructions
4. **Review Results**: See the updated summary
5. **Iterate or Complete**: Continue refining or save when satisfied

### Example Refinement Session

```bash
python3 backend/cli.py refine abc123 --interactive

# Terminal shows current summary...

Refinement instruction: Make it more concise, focus on actionable items
# AI refines...

Are you satisfied? [y/N]: n
Refinement instruction: Add a section on implementation steps
# AI refines...

Are you satisfied? [y/N]: n  
Refinement instruction: Include a flowchart for the process
# AI adds diagram...

Are you satisfied? [y/N]: y
✓ Great! Summary refined successfully!
```

## Model Selection Guide

### DeepSeek (default)
- **Best for**: Cost-effective summaries
- **Strengths**: Good balance of quality and speed
- **Use when**: Processing many videos or standard summaries

### Anthropic Claude
- **Best for**: High-quality, nuanced summaries
- **Strengths**: Excellent comprehension and writing
- **Use when**: Quality is paramount

### OpenAI GPT
- **Best for**: Creative and detailed summaries
- **Strengths**: Versatile and well-rounded
- **Use when**: Need specific GPT features

### Google Gemini
- **Best for**: Technical content
- **Strengths**: Strong on technical topics
- **Use when**: Summarizing technical videos

## Environment Variables

Set these in your `.env` file or export them:

```bash
# Required (at least one)
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...
export DEEPSEEK_API_KEY=sk-...

# Database
export DATABASE_URL=sqlite:///./data/youtube_summarizer.db

# Optional
export VIDEO_DOWNLOAD_STORAGE_PATH=./video_storage
export VIDEO_DOWNLOAD_KEEP_AUDIO_FILES=true
```

## Tips and Best Practices

1. **Start with Standard Length**: Use `--length standard` and refine if needed
2. **Use Focus Areas**: Specify 2-3 focus areas for targeted summaries
3. **Iterative Refinement**: Use the refine command to perfect summaries
4. **Model Comparison**: Generate with multiple models and compare
5. **Save Prompts**: Save successful prompts for reuse
6. **Batch Similar Videos**: Process related videos together with same settings
7. **Export Important Summaries**: Use `--export` to backup valuable summaries

## Troubleshooting

### API Key Issues
```bash
# Check environment variables
env | grep API_KEY

# Set API key for session
export ANTHROPIC_API_KEY=your_key_here
```

### Database Issues
```bash
# Check database path
ls -la data/youtube_summarizer.db

# Use different database
export DATABASE_URL=sqlite:///path/to/your/database.db
```

### Mermaid Rendering Issues
```bash
# Check if mmdc is installed
mmdc --version

# Install if missing
npm install -g @mermaid-js/mermaid-cli

# Use ASCII fallback if mmdc unavailable
npm install -g mermaid-ascii
```

## Examples

### Complete Workflow Example

```bash
# 1. Add a new summary with diagrams
python3 backend/cli.py add "https://youtube.com/watch?v=dQw4w9WgXcQ" \
  --model anthropic \
  --diagrams \
  --focus "key-concepts" \
  --focus "practical-applications"

# 2. Review the summary
python3 backend/cli.py show SUMMARY_ID --suggest-diagrams

# 3. Refine iteratively
python3 backend/cli.py refine SUMMARY_ID --interactive

# 4. Export final version
python3 backend/cli.py show SUMMARY_ID --export --render-diagrams

# 5. Compare with different model
python3 backend/cli.py regenerate SUMMARY_ID --model gemini
python3 backend/cli.py compare SUMMARY_ID OTHER_ID
```

### Custom Prompt Examples

```bash
# Technical summary
--prompt "Focus on technical implementation details, architecture decisions, and provide code examples where relevant"

# Business summary
--prompt "Emphasize business value, ROI, strategic implications, and actionable recommendations"

# Educational summary
--prompt "Create a study guide with learning objectives, key concepts, and practice questions"

# Creative summary
--prompt "Write an engaging narrative that tells the story of the video content"
```

## Support

For issues or questions, check the main YouTube Summarizer documentation or create an issue in the repository.