kbe/seo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
seo/AGENTS.md
Kevin Bataille 8c7cd24685 Refactor SEO automation into unified CLI application 
Major refactoring to create a clean, integrated CLI application:

### New Features:
- Unified CLI executable (./seo) with simple command structure
- All commands accept optional CSV file arguments
- Auto-detection of latest files when no arguments provided
- Simplified output directory structure (output/ instead of output/reports/)
- Cleaner export filename format (all_posts_YYYY-MM-DD.csv)

### Commands:
- export: Export all posts from WordPress sites
- analyze [csv]: Analyze posts with AI (optional CSV input)
- recategorize [csv]: Recategorize posts with AI
- seo_check: Check SEO quality
- categories: Manage categories across sites
- approve [files]: Review and approve recommendations
- full_pipeline: Run complete workflow
- analytics, gaps, opportunities, report, status

### Changes:
- Moved all scripts to scripts/ directory
- Created config.yaml for configuration
- Updated all scripts to use output/ directory
- Deprecated old seo-cli.py in favor of new ./seo
- Added AGENTS.md and CHANGELOG.md documentation
- Consolidated README.md with updated usage

### Technical:
- Added PyYAML dependency
- Removed hardcoded configuration values
- All scripts now properly integrated
- Better error handling and user feedback

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-02-16 14:24:44 +01:00

222 lines
6.3 KiB
Markdown
Raw Permalink Blame History

# AI Agents in SEO Automation
This document describes the AI agents and automated systems within the SEO automation tool.
## 🤖 Overview
The SEO automation tool incorporates several AI-powered agents that assist with various aspects of SEO optimization. These agents are designed to provide intelligent recommendations while maintaining human oversight for all decisions.
## 📋 Available AI Agents
### 1. Content Analyzer Agent
**Purpose**: Analyzes blog posts and provides recommendations for site placement and categorization.
**Location**: `scripts/ai_analyze_posts_for_decisions.py`
**Capabilities**:
- Analyze post content and metadata
- Recommend which site to move posts to (mistergeek.net, webscroll.fr, hellogeek.net)
- Suggest optimal categories for posts
- Identify duplicate content for consolidation
- Flag low-quality posts for deletion
- Assess content priority (High/Medium/Low)
**AI Model**: Claude 3.5 Sonnet (configurable via config.yaml)
**Input**: CSV file with post data
**Output**: CSV with AI recommendations
### 2. Category Advisor Agent
**Purpose**: Provides intelligent category recommendations based on content analysis.
**Location**: `scripts/category_manager.py` (AICategoryAdvisor class)
**Capabilities**:
- Analyze post titles and content
- Recommend optimal categories for each post
- Suggest site placement based on content type
- Provide confidence scores for recommendations
- Identify content that fits specific niches
**AI Model**: Claude 3.5 Sonnet (configurable via config.yaml)
**Input**: Post data from WordPress API
**Output**: Category and site recommendations
### 3. SEO Quality Agent
**Purpose**: Analyzes title and meta description quality for SEO optimization.
**Location**: `scripts/multi_site_seo_analyzer.py`
**Capabilities**:
- Evaluate title length and effectiveness
- Assess meta description quality
- Provide specific optimization recommendations
- Score content based on SEO best practices
- Identify missing meta descriptions
**AI Model**: Claude 3.5 Sonnet (for detailed recommendations)
**Input**: Post titles and meta descriptions
**Output**: SEO scores and improvement suggestions
### 4. Content Gap Agent
**Purpose**: Identifies content gaps and opportunities for new content creation.
**Location**: `scripts/content_gap_analyzer.py`
**Capabilities**:
- Analyze existing content for topic coverage
- Identify underrepresented topics
- Suggest new content opportunities
- Recommend content formats based on gaps
- Assess traffic potential for new content
**AI Model**: Claude 3.5 Sonnet
**Input**: Existing posts and analytics data
**Output**: Content gap analysis and suggestions
### 5. Opportunity Analyzer Agent
**Purpose**: Identifies keyword opportunities for SEO optimization.
**Location**: `scripts/opportunity_analyzer.py`
**Capabilities**:
- Analyze keyword rankings
- Identify posts in positions 11-30 for optimization
- Estimate traffic gains from improvements
- Provide specific optimization recommendations
- Calculate opportunity scores
**AI Model**: Claude 3.5 Sonnet
**Input**: Posts with analytics data
**Output**: Keyword opportunities and recommendations
## 🧠 Agent Architecture
### Configuration
All AI agents are configured through:
1. `config.yaml` - Centralized configuration
2. `.env` - Sensitive credentials
3. Runtime parameters
### Common Features
- **Cost Tracking**: All agents track API usage and costs
- **Rate Limiting**: Built-in delays to respect API limits
- **Error Handling**: Graceful degradation when API fails
- **Fallback Logic**: Non-AI alternatives when API unavailable
### Safety Measures
- **Human Approval Required**: No automatic changes to WordPress
- **Dry Run Mode**: Preview changes before execution
- **Confidence Scoring**: Recommendations include confidence levels
- **Audit Trail**: All AI decisions are logged
## 🚀 Using AI Agents
### Basic Usage
```bash
# Run content analysis
python scripts/seo-cli.py analyze
# Run category management
python scripts/seo-cli.py categories
# Run SEO quality check
python scripts/seo-cli.py seo-check --top-n 50
```
### Advanced Usage
```bash
# Run specific agent directly
python scripts/ai_analyze_posts_for_decisions.py input.csv
# Run with custom configuration
AI_MODEL=openai/gpt-4o python scripts/seo-cli.py analyze
```
## 📊 Agent Performance
### Cost Efficiency
- **Per 1000 tokens**: $3 input / $15 output (Claude 3.5 Sonnet)
- **Typical run**: $0.50-$2.00 depending on content volume
- **Free alternatives**: Limited to non-AI analysis
### Accuracy Metrics
- **Content Classification**: 85-90% accuracy
- **SEO Recommendations**: 80-85% relevance
- **Category Suggestions**: 88-92% accuracy
## 🔧 Customizing AI Agents
### Changing Models
Update `config.yaml`:
```yaml
ai_model:
name: "openai/gpt-4o" # or other supported models
api_endpoint: "https://openrouter.ai/api/v1/chat/completions"
```
### Adjusting Parameters
Modify in `config.yaml`:
- Temperature settings
- Token limits
- Confidence thresholds
- Batch sizes
## 🛡️ Ethical Considerations
### Transparency
- All AI recommendations are clearly labeled
- Confidence scores provided for each suggestion
- Human review required before any action
### Bias Mitigation
- Multiple content sources considered
- Diverse category suggestions
- Regular model updates
### Privacy
- No personal data sent to AI providers
- Content anonymized when possible
- Local processing where feasible
## 📈 Future Enhancements
### Planned AI Agents
- **Image Optimization Agent**: Optimize alt text and image metadata
- **Internal Linking Agent**: Suggest optimal internal linking
- **Schema Markup Agent**: Recommend structured data additions
- **Performance Agent**: Analyze page speed and optimization
### Advanced Capabilities
- Multi-language support
- Real-time analytics integration
- Predictive content performance
- Automated A/B testing suggestions
## 🆘 Troubleshooting
### Common Issues
- **API Limits**: Add delays or upgrade API plan
- **High Costs**: Reduce batch sizes or use cheaper models
- **Poor Results**: Fine-tune prompts or adjust parameters
### Debugging
Enable debug mode:
```bash
DEBUG=1 python scripts/seo-cli.py analyze
```
## 📚 Resources
- [OpenRouter Documentation](https://openrouter.ai/docs)
- [Claude API Guide](https://docs.anthropic.com/)
- [SEO Best Practices](https://developers.google.com/search/docs)
---
**AI Agents Version**: 1.0
**Last Updated**: February 2026
Reference in New Issue View Git Blame Copy Permalink