demo
/
youtube-summarizer
1
0
Fork 0
Code Issues 8 Pull Requests 1 Packages Projects Releases Wiki Activity
youtube-summarizer/backend/CLI_README.md

9.8 KiB
Raw Blame History

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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

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

Manage Prompts

# 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

# 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

# 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

# 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

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:

# 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

# Check environment variables
env | grep API_KEY

# Set API key for session
export ANTHROPIC_API_KEY=your_key_here

Database Issues

# Check database path
ls -la data/youtube_summarizer.db

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

Mermaid Rendering Issues

# 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

# 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

# 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.