seo/README.md

# SEO Automation Tool

A comprehensive WordPress SEO automation suite that leverages AI to analyze, categorize, and optimize content across multiple sites.

## 🚀 Overview

This tool helps you manage SEO for multiple WordPress sites by:
- Exporting all posts with complete metadata
- Using AI to analyze content and provide actionable recommendations
- Suggesting optimal site placement and categorization
- Providing SEO quality analysis for titles and meta descriptions
- Supporting manual approval of all recommendations

## 📋 Features

- **Multi-site support**: Works with multiple WordPress installations
- **AI-powered analysis**: Uses Claude AI for content recommendations
- **Category management**: Suggests optimal categories and site placement
- **SEO quality checks**: Analyzes title and meta description quality
- **Manual approval**: All recommendations require human approval
- **Configurable**: Uses both .env and YAML configuration files
- **Modular design**: Each workflow is independent and chainable

## 🛠️ Prerequisites

1. **Python 3.8+**
2. **WordPress sites** with REST API access
3. **App passwords** for WordPress authentication
4. **OpenRouter API key** for AI analysis

## 📦 Installation

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd seo
   ```

2. Create a virtual environment:
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

4. Configure your environment:
   ```bash
   cp .env.example .env
   # Edit .env with your credentials
   ```

5. Update the configuration in `config.yaml` if needed

## 🚀 Quick Start

### Option 1: Full Pipeline (Recommended)
```bash
./seo full_pipeline
```

### Option 2: Step-by-Step
```bash
# Export all posts
./seo export

# Analyze with AI
./seo analyze

# Check SEO quality
./seo seo_check
```

### Option 3: Chain Commands
```bash
./seo export && \
./seo analyze && \
./seo seo_check
```

## 📁 Workflows

### 1. Export Posts
```bash
./seo export
```
Exports all posts from configured WordPress sites with complete metadata.
- **Output**: `output/all_posts_YYYY-MM-DD.csv`

### 2. AI Analysis
```bash
./seo analyze [csv_file]
```
Uses AI to analyze posts and provide recommendations for site placement, categorization, and content consolidation.
- **Input**: CSV file (optional, uses latest export if not provided)
- **Output**: `output/posts_with_ai_recommendations_*.csv`

### 3. SEO Quality Check
```bash
./seo seo_check
```
Analyzes title and meta description quality with SEO scoring.
- **Output**: `output/seo_analysis_*.csv` and `output/seo_analysis_*.html`

### 4. Category Management
```bash
./seo categories
```
Manages categories across all sites with AI-powered recommendations.
- **Output**: `output/category_assignments_*.csv`, `output/proposed_categories_*.csv`

### 5. Approve Recommendations
```bash
./seo approve [file1.csv] [file2.csv] ...
```
Interactive approval system for all recommendations.
- **Input**: CSV files with recommendations (optional, auto-detects if not provided)
- **Output**: `output/approved_recommendations_*.csv`, `output/rejected_recommendations_*.csv`

### 6. Recategorize Posts
```bash
./seo recategorize [csv_file]
```
Recategorize posts with AI suggestions.
- **Input**: CSV file (optional, uses latest export if not provided)
- **Output**: `output/posts_with_recategorization_*.csv`

### 7. Full Pipeline
```bash
./seo full_pipeline
```
Runs the complete workflow: export → analyze → seo_check

### 8. Analytics Import
```bash
./seo analytics ga4_export.csv gsc_export.csv
```
Imports Google Analytics and Search Console data.
- **Input**: GA4 and GSC CSV exports
- **Output**: `output/posts_with_analytics.csv`

### 9. Content Gaps
```bash
./seo gaps
```
Analyzes content gaps and suggests new content opportunities.
- **Output**: `output/content_gaps.csv`

### 10. Keyword Opportunities
```bash
./seo opportunities
```
Analyzes keyword opportunities for SEO optimization.
- **Output**: `output/keyword_opportunities.csv`

### 11. Report Generation
```bash
./seo report
```
Generates comprehensive SEO optimization reports.
- **Output**: `output/seo_optimization_report.md`

### 12. Status Check
```bash
./seo status
```
Shows status of output files.

## 🖥️ CLI Usage

The SEO automation tool provides a simple, intuitive CLI inspired by Ruby on Rails:

```bash
./seo help                    # Show available commands
./seo export                  # Export all posts from WordPress sites
./seo analyze                 # Analyze posts with AI for recommendations
./seo recategorize            # Recategorize posts with AI
./seo seo_check               # Check SEO quality of titles/descriptions
./seo categories              # Manage categories across sites
./seo approve                 # Review and approve recommendations
./seo full_pipeline           # Run complete workflow: export → analyze → seo_check
./seo analytics ga4.csv gsc.csv  # Import analytics data
./seo gaps                    # Analyze content gaps
./seo opportunities           # Analyze keyword opportunities
./seo report                  # Generate SEO optimization report
./seo status                  # Show output files status
```

## 🏗️ Project Structure

```
seo/
├── seo                          # Main CLI executable
├── src/seo/                     # Integrated application package
│   ├── __init__.py              # Package initialization
│   ├── cli.py                   # Command-line interface
│   ├── app.py                   # Main application class
│   ├── config.py                # Configuration management
│   ├── exporter.py              # Post export functionality
│   ├── analyzer.py              # AI analysis functionality
│   ├── recategorizer.py         # Recategorization functionality
│   ├── seo_checker.py           # SEO quality checking
│   ├── categories.py            # Category management
│   └── approval.py              # User approval system
├── scripts/                     # Legacy scripts (deprecated)
├── config.yaml                  # YAML configuration
├── .env                         # Environment variables
├── .env.example                 # Template
├── requirements.txt             # Dependencies
├── output/                      # Generated files
└── README.md
```

## 📦 Installation

For development/installation:

```bash
# Install in development mode
pip install -e .

# Or just use the executable directly
./seo help
```

## 🎯 Typical Workflow

1. **Export posts** from all sites:
   ```bash
   python scripts/seo-cli.py export
   ```

2. **Review exported data** in `output/reports/`

3. **Analyze with AI**:
   ```bash
   python scripts/seo-cli.py analyze
   ```

4. **Manage categories**:
   ```bash
   python scripts/seo-cli.py categories
   ```

5. **Approve recommendations**:
   ```bash
   python scripts/seo-cli.py approve output/reports/*.csv
   ```

6. **Execute approved changes** manually in WordPress

## 📊 Output Files

All results are saved in `output/reports/`:
- `all_posts_for_ai_decision_*.csv` - All exported posts
- `posts_with_ai_recommendations_*.csv` - AI analysis results
- `category_assignments_*.csv` - Category recommendations
- `approved_recommendations_*.csv` - Approved changes
- `rejected_recommendations_*.csv` - Rejected changes

## 🔒 Security

- Credentials stored in `.env` file (not committed)
- All API calls use secure authentication
- Read-only operations by default
- Manual approval required for all changes

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

## 🆘 Support

For support, please open an issue in the repository or contact the maintainers.

---

**Made with ❤️ for better SEO automation**