KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

youtube-idea-agent

★ 4 Open GitHub ↗

An AI-powered YouTube content analysis and video idea generation platform with both API and web interfaces.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎥 YouTube AI Agent

An AI-powered YouTube content analysis and video idea generation platform with both API and web interfaces.

## 🌟 Features

- **🔍 YouTube Analysis**: Comprehensive analysis of YouTube topics with content insights
- **🧠 AI Video Idea Generation**: AI-powered video idea creation with criticism and refinement
- **🏆 Competition Analysis**: Market analysis and opportunity identification
- **🎯 Strategic Recommendations**: Data-driven content strategy advice
- **🌐 Multiple Interfaces**: Both REST API and beautiful web interface
- **📊 Structured Output**: All responses use validated Pydantic models

## 🏗️ Architecture

- **FastAPI Backend**: Modern Python REST API with automatic documentation
- **Streamlit Frontend**: Interactive web interface for easy access
- **Langgraph**: AI workflow orchestration for complex multi-step analysis
- **OpenAI GPT-4**: Powered insights and idea generation
- **YouTube Data API**: Real-time video and channel data
- **Pydantic**: Data validation and serialization

## 📦 Installation

1. **Clone the repository**:
   ```bash
   git clone git@github.com:adilmoujahid/youtube-idea-agent.git
   cd youtube-idea-agent
   ```

2. **Install dependencies**:
   ```bash
   uv sync
   ```

3. **Set up environment variables** in `.env`:
   ```env
   YOUTUBE_API_KEY=your_youtube_api_key_here
   OPENAI_API_KEY=your_openai_api_key_here
   ```

## 🚀 Quick Start

### **Option 1: Web Interface (Recommended)**
Start both the API backend and web frontend together:
```bash
uv run start_both.py
```

Then open your browser:
- **🌐 Streamlit Web App**: http://localhost:8501
- **📚 API Documentation**: http://localhost:8000/docs

### **Option 2: API Only**
Start just the FastAPI backend:
```bash
uv run start_api.py
```

### **Option 3: Step-by-Step**
```bash
# Terminal 1: Start API backend
uv run start_api.py

# Terminal 2: Start web frontend
uv run start_streamlit.py
```

## 🌐 Web Interface

The Streamlit frontend provides an intuitive web interface with:

### **📝 Configuration Panel**
- Topic input field
- Custom instructions for idea generation
- Dropdown for number of ideas (1-10)
- Two analysis modes: Analyze Only or Generate Ideas

### **📋 Results Display**
Organized in clear tabs:

1. **📊 YouTube Results**: Video metrics, query analysis, top performers
2. **💡 Insights**: Content strategy, competition analysis, recommendations
3. **🎬 Initial Ideas**: AI-generated video concepts *(Idea Generation Mode)*
4. **🔍 Criticism**: AI feedback and scores *(Idea Generation Mode)*
5. **✨ Final Ideas**: Refined ideas after criticism *(Idea Generation Mode)*

![Streamlit Interface](https://via.placeholder.com/800x400/2E3440/81A1C1?text=Streamlit+Interface+Screenshot)

## 🔧 API Endpoints

### **Basic YouTube Analysis**
```bash
POST /analyze
```
Analyze a YouTube topic and get comprehensive insights.

### **Video Idea Generation**
```bash
POST /generate-ideas
```
Generate AI-powered video ideas with criticism and refinement.

### **Quick Analysis**
```bash
GET /topics/{topic}/quick-analysis
```
Get simplified analysis results for faster responses.

See [API_README.md](API_README.md) for complete API documentation.

## 📊 Example Use Cases

### **Content Creators**
- Research competitor performance and trending topics
- Generate fresh video ideas with AI assistance
- Optimize video lengths based on data
- Identify content gaps in your niche

### **Marketing Teams**
- Analyze YouTube landscape for clients
- Generate content strategies for campaigns
- Research influencer opportunities
- Identify market positioning

### **Educational Channels**
- Find popular learning topics and formats
- Optimize tutorial lengths for engagement
- Identify knowledge gaps to address
- Improve overall content strategy

## 🎯 Sample Analysis Results

### **YouTube Metrics**
- Total videos analyzed: 125
- Average views: 245,000
- Optimal duration: 12-18 minutes
- Top performing video: 2.1M views

### **AI-Generated Ideas** *(Example)*
```json
{
  "title": "Build Your First AI Agent: Step-by-Step Guide for Beginners",
  "description": "Complete tutorial showing how to create a functional AI agent...",
  "recommended_length_minutes": 15,
  "target_audience": "Marketing professionals and tech beginners",
  "content_type": "tutorial"
}
```

### **Strategic Recommendations**
1. Create 15-minute tutorial videos with practical examples
2. Focus on beginner-friendly content with clear explanations
3. Include hands-on coding demonstrations
4. Target the "AI for business" opportunity gap

## 🧪 Testing

### **Test the API**
```bash
python test_api.py
```

### **Manual Testing**
```bash
# Basic analysis
curl -X POST "http://localhost:8000/analyze" \
     -H "Content-Type: application/json" \
     -d '{"topic": "machine learning"}'

# Generate ideas
curl -X POST "http://localhost:8000/generate-ideas" \
     -H "Content-Type: application/json" \
     -d '{
       "topic": "AI Agents",
       "number_of_ideas": 3,
       "instructions": "hands-on tutorials"
     }'
```

## 📁 Project Structure

```
youtube-idea-agent/
├── app/                          # FastAPI backend
│   ├── main.py                  # API endpoints
│   ├── agent.py                 # Langgraph AI workflows
│   ├── models.py                # Pydantic data models
│   ├── youtube_client.py        # YouTube API client
│   └── config.py                # Configuration settings
├── streamlit_app.py             # Streamlit web frontend
├── notebooks/                   # Original Jupyter notebooks
│   └── youtube_ai_agent.ipynb   # Development notebook
├── start_api.py                 # FastAPI startup script
├── start_streamlit.py           # Streamlit startup script
├── start_both.py                # Combined startup script
├── test_api.py                  # API testing suite
├── API_README.md                # API documentation
├── STREAMLIT_README.md          # Frontend documentation
└── .env                         # Environment variables
```

## ⚡ Performance

- **Basic Analysis**: 30-60 seconds
- **Video Idea Generation**: 2-3 minutes
- **Concurrent Users**: Supports multiple simultaneous requests
- **Rate Limits**: Respects YouTube API and OpenAI quotas

## 🔐 Security & Configuration

### **Environment Variables**
```env
# Required
YOUTUBE_API_KEY=your_youtube_api_key
OPENAI_API_KEY=your_openai_api_key

# Optional (with defaults)
LLM_MODEL=gpt-4o-mini
LLM_TEMPERATURE=0.7
DEFAULT_MAX_RESULTS=25
```

### **API Security**
- Input validation with Pydantic
- Rate limiting and timeout protection
- CORS middleware for web frontend
- Comprehensive error handling

## 🚨 Troubleshooting

### **Common Issues**
- **"Cannot connect to backend"**: Ensure `python start_api.py` is running
- **API key errors**: Check `.env` file configuration
- **Timeout errors**: YouTube analysis can take 1-3 minutes
- **Empty results**: Try broader topics or check API quotas

### **Support Resources**
- **API Issues**: Check logs at http://localhost:8000/docs
- **Frontend Issues**: Review browser console
- **Performance**: Monitor API quotas and connection

## 📈 Monitoring & Logging

- Comprehensive request/response logging
- Error tracking with stack traces
- Performance monitoring
- API usage metrics

## 🚀 Deployment

### **Development**
```bash
python start_both.py
```

### **Production API**
```bash
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### **Production Web App**
```bash
streamlit run streamlit_app.py --server.port 8501 --server.address 0.0.0.0
```

## 🔄 Development Workflow

1. **Backend Development**: Modify files in `app/` directory
2. **Frontend Development**: Edit `streamlit_app.py`
3. **Testing**: Run `python test_api.py` for API tests
4. **Documentation**: Update README files for changes

## 📚 Documentation

- **[API Documentation](API_README.md)**: Complete FastAPI reference
- **[Frontend Guide](STREAMLIT_README.md)**: Streamlit interface documentation
- **Interactive Docs**: http://localhost:8000/docs (when running)
- **Development Notebook**: `notebooks/youtube_ai_agent.ipynb`

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes and test thoroughly
4. Update documentation as needed
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License.

## 🏆 Acknowledgments

- **FastAPI**: Modern, fast web framework for building APIs
- **Streamlit**: Beautiful web apps for machine learning
- **Langgraph**: AI workflow orchestration
- **OpenAI**: GPT-4 language model
- **YouTube Data API**: Video and channel data

---

**🎥 Ready to revolutionize your YouTube content strategy? Get started in minutes!**

```bash
# One command to start everything
uv run start_both.py
```

Open http://localhost:8501 and start analyzing! 🚀

youtube-idea-agent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README