Marketing Crew Wiki

# Marketing Crew Wiki

Welcome to the comprehensive wiki for the Marketing Crew project! This document serves as your complete guide to understanding, configuring, and extending the AI-powered marketing automation system.

## 📚 Table of Contents

1. [Getting Started](#getting-started)
2. [Architecture Deep Dive](#architecture-deep-dive)
3. [Agent System](#agent-system)
4. [Task Workflow](#task-workflow)
5. [Configuration Guide](#configuration-guide)
6. [API Reference](#api-reference)
7. [Troubleshooting](#troubleshooting)
8. [Advanced Usage](#advanced-usage)
9. [Examples & Templates](#examples--templates)
10. [FAQ](#faq)

## 🚀 Getting Started

### Prerequisites

Before you begin, ensure you have:

- **Python 3.12+**: The project requires Python 3.12 or higher
- **UV Package Manager**: Recommended for dependency management
- **Gemini API Key**: Required for Google AI integration
- **Git**: For version control

### Environment Setup

1. **Clone the Repository**
   ```bash
   git clone <repository-url>
   cd marketing
   ```

2. **Create Virtual Environment**
   ```bash
   # Using UV (recommended)
   uv venv
   uv sync
   
   # Or using standard Python
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   ```

3. **Configure Environment Variables**
   ```bash
   # Create .env file
   cp .env.example .env
   
   # Edit .env with your API keys
   GOOGLE_API_KEY=your_gemini_api_key_here
   SERPER_API_KEY=your_serper_api_key_here  # Optional
   ```

4. **Verify Installation**
   ```bash
   python -c "import crewai; print('CrewAI installed successfully!')"
   ```

## 🏗️ Architecture Deep Dive

### System Overview

The Marketing Crew follows a multi-agent architecture where specialized AI agents collaborate to complete marketing tasks:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Input Data   │───▶│  CrewAI Engine   │───▶│  Output Files   │
│                 │    │                  │    │                 │
│ - Product Info │    │ - Agent Manager  │    │ - Strategies    │
│ - Target       │    │ - Task Scheduler │    │ - Content       │
│ - Budget       │    │ - Process Flow   │    │ - Calendars     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   AI Agents      │
                    │                  │
                    │ • Head of Mkt    │
                    │ • Content Creator│
                    │ • Blog Writer    │
                    │ • SEO Specialist │
                    └──────────────────┘
```

### Core Components

#### 1. CrewAI Framework
- **Agent Management**: Handles agent lifecycle and communication
- **Task Orchestration**: Manages task execution and dependencies
- **Process Control**: Supports sequential and parallel execution modes

#### 2. LLM Integration
- **Model**: Gemini 2.0 Flash (configurable)
- **Temperature**: 0.7 (balanced creativity and consistency)
- **Rate Limiting**: 3 RPM to manage API costs

#### 3. Tool Integration
- **SerperDev**: Web search and research capabilities
- **Web Scraping**: Competitor and market data collection
- **File Operations**: Automated content storage and retrieval

## 🤖 Agent System

### Agent Types & Responsibilities

#### Head of Marketing
**Role**: Strategic leadership and market analysis
**Responsibilities**:
- Market research and trend analysis
- Competitor analysis and positioning
- Marketing strategy development
- Budget allocation and planning

**Tools**: Full access to all research and planning tools
**Output**: Strategic documents and market insights

#### Content Creator (Social Media)
**Role**: Social media content and video production
**Responsibilities**:
- Social media post creation
- Video script development
- Content calendar planning
- Platform-specific optimization

**Tools**: Content creation tools, research capabilities
**Output**: Post drafts, video scripts, content calendars

#### Content Writer (Blogs)
**Role**: Long-form content creation
**Responsibilities**:
- Blog post research and writing
- Content structure and flow
- Brand voice consistency
- Content optimization

**Tools**: Research tools, writing assistance
**Output**: Blog drafts, research reports

#### SEO Specialist
**Role**: Search engine optimization
**Responsibilities**:
- Keyword research and optimization
- Meta tag optimization
- Internal linking strategies
- Content performance analysis

**Tools**: SEO analysis tools, content optimization
**Output**: SEO-optimized content, performance reports

### Agent Configuration

Each agent is configured through YAML files in `config/agents.yaml`:

```yaml
agent_name:
  llm: gemini/gemini-2.0-flash
  role: "Agent's specific role"
  goal: "Primary objective"
  backstory: "Context and expertise level"
```

**Configuration Options**:
- `llm`: AI model specification
- `role`: Clear responsibility definition
- `goal`: Measurable objective
- `backstory`: Context for better decision-making

## 📋 Task Workflow

### Task Execution Flow

The Marketing Crew executes tasks in a sequential workflow:

```
1. Market Research
   ↓
2. Marketing Strategy
   ↓
3. Content Calendar
   ↓
4. Content Creation
   ↓
5. SEO Optimization
```

### Task Configuration

Tasks are defined in `config/tasks.yaml` with:

- **Description**: Detailed task requirements
- **Expected Output**: Deliverable specifications
- **Agent Assignment**: Responsible agent
- **Input Parameters**: Required data and context

### Task Types

#### Research Tasks
- **Market Research**: Industry analysis and insights
- **Content Research**: Topic research and keyword analysis
- **Competitor Analysis**: Market positioning and strategies

#### Planning Tasks
- **Strategy Development**: Comprehensive marketing plans
- **Content Calendar**: Weekly content scheduling
- **Budget Planning**: Resource allocation

#### Creation Tasks
- **Content Drafting**: Social media, blogs, videos
- **Script Writing**: Video and audio content
- **Copywriting**: Marketing copy and messaging

#### Optimization Tasks
- **SEO Optimization**: Search engine visibility
- **Content Refinement**: Quality improvement
- **Performance Analysis**: Metrics and insights

## ⚙️ Configuration Guide

### Environment Configuration

#### Required Variables
```bash
# .env file
GOOGLE_API_KEY=your_gemini_api_key_here
```

#### Optional Variables
```bash
SERPER_API_KEY=your_serper_api_key_here
LOG_LEVEL=INFO
MAX_RPM=3
```

### Agent Customization

#### Modifying Agent Behavior
1. Edit `config/agents.yaml`
2. Adjust role, goal, and backstory
3. Restart the application

#### Adding New Agents
1. Define agent in YAML config
2. Add agent method in `crew.py`
3. Assign tools and permissions
4. Integrate into task workflow

### Task Customization

#### Modifying Task Parameters
1. Edit `config/tasks.yaml`
2. Adjust description and expected output
3. Modify agent assignments
4. Update input parameters

#### Adding New Tasks
1. Define task in YAML config
2. Create task method in `crew.py`
3. Assign to appropriate agent
4. Integrate into workflow

### LLM Configuration

#### Model Selection
```python
llm = LLM(
    model="gemini/gemini-2.0-flash",  # Change model here
    temperature=0.7,                   # Adjust creativity (0.0-1.0)
)
```

#### Rate Limiting
```python
max_rpm=3  # Requests per minute
max_iter=30  # Maximum iterations per task
```

## 🔧 API Reference

### Core Classes

#### TheMarketingCrew
Main crew class that orchestrates all operations.

**Methods**:
- `head_of_marketing()`: Returns Head of Marketing agent
- `content_creator_social_media()`: Returns Content Creator agent
- `content_writer_blogs()`: Returns Blog Writer agent
- `seo_specialist()`: Returns SEO Specialist agent
- `marketingcrew()`: Returns configured crew instance

#### Agent
Individual AI agent with specific capabilities.

**Properties**:
- `config`: Agent configuration from YAML
- `tools`: Available tools and capabilities
- `llm`: Language model instance
- `max_rpm`: Rate limiting configuration

#### Task
Individual task definition and execution.

**Properties**:
- `config`: Task configuration from YAML
- `agent`: Assigned agent
- `output_json`: Expected output format

### Tool Integration

#### Available Tools
- **SerperDevTool**: Web search capabilities
- **ScrapeWebsiteTool**: Web scraping functionality
- **DirectoryReadTool**: File system access
- **FileWriterTool**: File creation and editing
- **FileReadTool**: File reading and parsing

#### Tool Configuration
```python
tools=[
    SerperDevTool(),
    ScrapeWebsiteTool(),
    DirectoryReadTool('resources/drafts'),
    FileWriterTool(),
    FileReadTool()
]
```

## 🚨 Troubleshooting

### Common Issues

#### 1. API Key Errors
**Problem**: "Invalid API key" or authentication errors
**Solution**:
- Verify API key in `.env` file
- Check key permissions and quotas
- Ensure proper environment variable loading

#### 2. Import Errors
**Problem**: Module not found errors
**Solution**:
- Verify Python version (3.12+)
- Install dependencies: `uv sync` or `pip install -r requirements.txt`
- Check virtual environment activation

#### 3. Rate Limiting
**Problem**: "Rate limit exceeded" errors
**Solution**:
- Reduce `max_rpm` in agent configuration
- Implement exponential backoff
- Check API provider limits

#### 4. File Permission Errors
**Problem**: Cannot write to output directories
**Solution**:
- Check directory permissions
- Ensure write access to `resources/drafts/`
- Verify file paths in configuration

### Debug Mode

Enable verbose logging:
```python
crew = Crew(
    agents=self.agents,
    tasks=self.tasks,
    process=Process.sequential,
    verbose=True,  # Enable debug output
    planning=True,
)
```

### Log Analysis

Check logs for:
- Agent communication patterns
- Task execution flow
- Error messages and stack traces
- Performance bottlenecks

## 🚀 Advanced Usage

### Custom Workflows

#### Parallel Execution
```python
crew = Crew(
    agents=self.agents,
    tasks=self.tasks,
    process=Process.parallel,  # Execute tasks in parallel
    verbose=True,
)
```

#### Conditional Task Execution
```python
@task
def conditional_task(self) -> Task:
    return Task(
        config=self.tasks_config['conditional_task'],
        agent=self.head_of_marketing(),
        context="Execute only if market research shows opportunity"
    )
```

### Integration Patterns

#### External API Integration
```python
from crewai_tools import BaseTool

class CustomAPITool(BaseTool):
    name: str = "Custom API Tool"
    description: str = "Integrates with external marketing APIs"
    
    def _run(self, query: str) -> str:
        # Implement API integration logic
        return "API response"
```

#### Database Integration
```python
class DatabaseTool(BaseTool):
    name: str = "Database Tool"
    description: str = "Stores and retrieves marketing data"
    
    def _run(self, operation: str, data: dict) -> str:
        # Implement database operations
        return "Database operation result"
```

### Performance Optimization

#### Caching Strategies
- Implement result caching for repeated queries
- Cache market research data
- Store agent responses for reuse

#### Batch Processing
- Group similar tasks for efficiency
- Process multiple content pieces simultaneously
- Optimize API calls and rate limiting

## 📝 Examples & Templates

### Input Templates

#### Product Launch
```python
inputs = {
    "product_name": "AI-Powered Analytics Platform",
    "target_audience": "Data Scientists, Business Analysts, Product Managers",
    "product_description": "Advanced analytics platform with AI-driven insights",
    "budget": "$100,000",
    "launch_date": "2024-03-15",
    "current_date": datetime.now().strftime("%Y-%m-%d"),
}
```

#### Content Campaign
```python
inputs = {
    "campaign_name": "Summer Product Launch",
    "target_audience": "Young professionals, 25-35",
    "campaign_goal": "Increase brand awareness by 40%",
    "budget": "$50,000",
    "duration": "3 months",
    "current_date": datetime.now().strftime("%Y-%m-%d"),
}
```

### Output Templates

#### Marketing Strategy
```markdown
# Marketing Strategy: [Product Name]

## Executive Summary
Brief overview of the strategy and objectives.

## Market Analysis
- Target audience segmentation
- Competitor analysis
- Market opportunities

## Strategy Components
- Positioning strategy
- Marketing channels
- Budget allocation
- Timeline and milestones

## Key Performance Indicators
- Success metrics
- Measurement methods
- Reporting schedule
```

#### Content Calendar
```markdown
# Content Calendar: [Week of Date]

## Monday
- **Blog Post**: [Topic] - [Author]
- **Social Media**: [Platform] - [Content Type]

## Tuesday
- **Video Content**: [Script Topic] - [Creator]
- **Email Campaign**: [Subject Line] - [Target Audience]

## Wednesday
- **Social Media**: [Platform] - [Content Type]
- **Blog Post**: [Topic] - [Author]
```

## ❓ FAQ

### General Questions

**Q: What makes Marketing Crew different from other marketing tools?**
A: Marketing Crew uses AI agents that work collaboratively, understanding context and creating cohesive strategies rather than isolated content pieces.

**Q: Can I use my own AI models?**
A: Yes, the system is designed to be model-agnostic. You can configure different LLM providers in the configuration.

**Q: How does the system handle different industries?**
A: The agents adapt to industry context through the input parameters and can be customized for specific verticals.

### Technical Questions

**Q: What's the maximum content length the system can generate?**
A: Content length is limited by the LLM's context window and can be configured through task parameters.

**Q: Can I integrate with my existing marketing tools?**
A: Yes, the system supports custom tool integration through the CrewAI tools framework.

**Q: How do I handle sensitive information?**
A: Sensitive data should be stored in environment variables and never committed to version control.

### Usage Questions

**Q: How often should I run the marketing crew?**
A: Frequency depends on your content needs. Weekly runs are recommended for most businesses.

**Q: Can I customize the output format?**
A: Yes, output formats are configurable through the task definitions and can include various file types.

**Q: What if I need to modify generated content?**
A: All generated content is stored as editable markdown files that can be reviewed and modified before publication.

---

## 📚 Additional Resources

- [CrewAI Documentation](https://docs.crewai.com/)
- [Google AI Gemini Documentation](https://ai.google.dev/docs)
- [Marketing Best Practices](https://marketingexamples.com/)
- [Content Strategy Guide](https://contentmarketinginstitute.com/)

---

**Need Help?** Create an issue in the repository or check the troubleshooting section above.