382 lines
9.8 KiB
Markdown
382 lines
9.8 KiB
Markdown
# 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. |