Add category management - Create and update WordPress categories from AI
New Features: - Create WordPress categories based on AI proposals - Bulk assign posts to categories - Confidence-based filtering (High/Medium/Low) - Manual category creation - Dry run mode for safe preview New Commands: - seo category_apply - Apply AI proposals to WordPress - seo category_create - Create new category manually New Modules: - src/seo/category_manager.py - WordPress category management - WordPressCategoryManager: Create/get categories - CategoryAssignmentProcessor: Process AI proposals Features: - Automatic category creation if doesn't exist - Bulk category assignment - Confidence threshold filtering - Append mode (doesn't replace existing categories) - Comprehensive error handling - Detailed statistics and logging Usage: ./seo category_propose # Get AI proposals ./seo category_apply -s mistergeek.net # Apply to site ./seo category_apply -s site -c High # High confidence only ./seo category_create -s site "New Cat" # Create category ./seo category_apply --dry-run # Preview changes Documentation: - CATEGORY_MANAGEMENT_GUIDE.md - Complete guide Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Kevin Bataille
258
CATEGORY_MANAGEMENT_GUIDE.md
Normal file
258
CATEGORY_MANAGEMENT_GUIDE.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Category Management Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The SEO automation tool can now **create and update WordPress categories** based on AI propositions. This includes:
|
||||
|
||||
1. **AI-powered category proposals** - Analyze posts and suggest optimal categories
|
||||
2. **Automatic category creation** - Create new categories in WordPress if they don't exist
|
||||
3. **Bulk category assignment** - Assign multiple posts to categories at once
|
||||
4. **Confidence-based filtering** - Only apply high-confidence recommendations
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
1. Export posts
|
||||
↓
|
||||
2. Get AI category proposals
|
||||
↓
|
||||
3. Review proposals (optional)
|
||||
↓
|
||||
4. Apply to WordPress (with confidence filter)
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### 1. Propose Categories (`seo category_propose`)
|
||||
|
||||
Analyze posts and generate category recommendations.
|
||||
|
||||
```bash
|
||||
# Propose categories for latest export
|
||||
./seo category_propose
|
||||
|
||||
# Propose for specific CSV
|
||||
./seo category_propose output/all_posts_2026-02-16.csv
|
||||
|
||||
# Save to custom file
|
||||
./seo category_propose -o output/my_proposals.csv
|
||||
```
|
||||
|
||||
**Output CSV columns:**
|
||||
- `post_id` - Post identifier
|
||||
- `title` - Post title
|
||||
- `current_categories` - Current categories
|
||||
- `proposed_category` - AI-suggested category
|
||||
- `alternative_categories` - Alternative suggestions
|
||||
- `category_reason` - Explanation
|
||||
- `category_confidence` - Confidence level (High/Medium/Low)
|
||||
|
||||
### 2. Apply Categories (`seo category_apply`)
|
||||
|
||||
Apply AI category proposals to WordPress.
|
||||
|
||||
```bash
|
||||
# Apply with default settings (Medium confidence)
|
||||
./seo category_apply -s mistergeek.net
|
||||
|
||||
# Apply only high-confidence recommendations
|
||||
./seo category_apply -s mistergeek.net -c High
|
||||
|
||||
# Apply specific proposals file
|
||||
./seo category_apply output/category_proposals_*.csv -s webscroll.fr
|
||||
|
||||
# Dry run (preview changes)
|
||||
./seo category_apply -s mistergeek.net --dry-run
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --site` - WordPress site (required): `mistergeek.net`, `webscroll.fr`, `hellogeek.net`
|
||||
- `-c, --confidence` - Minimum confidence: `High`, `Medium`, `Low` (default: Medium)
|
||||
- `--dry-run` - Preview changes without applying
|
||||
|
||||
### 3. Create Category (`seo category_create`)
|
||||
|
||||
Manually create a new category.
|
||||
|
||||
```bash
|
||||
# Create category
|
||||
./seo category_create -s mistergeek.net "VPN Reviews"
|
||||
|
||||
# Create with description
|
||||
./seo category_create -s webscroll.fr "Torrent Clients" -d "Guides about torrent clients"
|
||||
|
||||
# Dry run
|
||||
./seo category_create -s hellogeek.net "Test Category" --dry-run
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Complete Category Update Workflow
|
||||
|
||||
```bash
|
||||
# Step 1: Export posts
|
||||
./seo export
|
||||
|
||||
# Step 2: Get AI category proposals
|
||||
./seo category_propose
|
||||
|
||||
# Step 3: Review proposals (open CSV in spreadsheet)
|
||||
open output/category_proposals_*.csv
|
||||
|
||||
# Step 4: Apply high-confidence recommendations
|
||||
./seo category_apply -s mistergeek.net -c High
|
||||
|
||||
# Step 5: Apply remaining Medium confidence (optional)
|
||||
./seo category_apply -s mistergeek.net -c Medium
|
||||
```
|
||||
|
||||
### Example 2: Site-Specific Category Management
|
||||
|
||||
```bash
|
||||
# For mistergeek.net (tech content)
|
||||
./seo category_propose
|
||||
./seo category_apply -s mistergeek.net -c Medium
|
||||
|
||||
# For webscroll.fr (torrent content)
|
||||
./seo category_apply -s webscroll.fr -c Medium
|
||||
|
||||
# For hellogeek.net (misc content)
|
||||
./seo category_apply -s hellogeek.net -c Low
|
||||
```
|
||||
|
||||
### Example 3: Manual Category Creation
|
||||
|
||||
```bash
|
||||
# Create new categories before applying
|
||||
./seo category_create -s mistergeek.net "AI Tools"
|
||||
./seo category_create -s mistergeek.net "VPN Reviews"
|
||||
./seo category_create -s webscroll.fr "Seedbox Guides"
|
||||
|
||||
# Then apply AI proposals
|
||||
./seo category_apply -s mistergeek.net
|
||||
```
|
||||
|
||||
### Example 4: Safe Dry Run
|
||||
|
||||
```bash
|
||||
# Preview what would happen
|
||||
./seo category_propose
|
||||
./seo category_apply -s mistergeek.net --dry-run
|
||||
|
||||
# Output shows:
|
||||
# Would assign post 123 to "VPN"
|
||||
# Would assign post 456 to "Software"
|
||||
# etc.
|
||||
|
||||
# If satisfied, run without --dry-run
|
||||
./seo category_apply -s mistergeek.net
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Category Creation Logic
|
||||
|
||||
1. **Check if category exists** (by slug)
|
||||
2. **If exists**: Use existing category ID
|
||||
3. **If not**: Create new category with AI-suggested name
|
||||
4. **Assign post** to the category
|
||||
|
||||
### Confidence Filtering
|
||||
|
||||
- **High**: Only apply very confident recommendations (>90% accuracy)
|
||||
- **Medium**: Apply most recommendations (default, ~80% accuracy)
|
||||
- **Low**: Apply all recommendations including uncertain ones
|
||||
|
||||
### Safety Features
|
||||
|
||||
- **Dry run mode**: Preview changes before applying
|
||||
- **Confidence threshold**: Filter out low-confidence suggestions
|
||||
- **Append mode**: Adds to existing categories (doesn't replace)
|
||||
- **Error handling**: Continues on errors, reports statistics
|
||||
|
||||
## API Endpoints Used
|
||||
|
||||
The category manager uses WordPress REST API:
|
||||
|
||||
```
|
||||
GET /wp-json/wp/v2/categories - List categories
|
||||
POST /wp-json/wp/v2/categories - Create category
|
||||
GET /wp-json/wp/v2/posts/{id} - Get post details
|
||||
POST /wp-json/wp/v2/posts/{id} - Update post categories
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Site not found" error
|
||||
```bash
|
||||
# Use exact site name
|
||||
./seo category_apply -s mistergeek.net # ✓ Correct
|
||||
./seo category_apply -s mistergeek # ✗ Wrong
|
||||
```
|
||||
|
||||
### "No proposals found" error
|
||||
```bash
|
||||
# Run category_propose first
|
||||
./seo category_propose
|
||||
./seo category_apply -s mistergeek.net
|
||||
```
|
||||
|
||||
### Authentication errors
|
||||
```bash
|
||||
# Check .env file has correct credentials
|
||||
# WORDPRESS_MISTERGEEK_USERNAME=...
|
||||
# WORDPRESS_MISTERGEEK_PASSWORD=...
|
||||
```
|
||||
|
||||
### Categories not being created
|
||||
```bash
|
||||
# Check WordPress user has permission to create categories
|
||||
# Requires 'manage_categories' capability
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with High confidence**: Test with `-c High` first
|
||||
2. **Review proposals**: Open CSV and review before applying
|
||||
3. **Use dry run**: Always test with `--dry-run` first
|
||||
4. **Backup first**: Export posts before bulk changes
|
||||
5. **Monitor results**: Check WordPress admin after applying
|
||||
|
||||
## Programmatic Usage
|
||||
|
||||
```python
|
||||
from seo import SEOApp, CategoryAssignmentProcessor
|
||||
|
||||
app = SEOApp()
|
||||
|
||||
# Get proposals
|
||||
proposals_file = app.category_propose()
|
||||
|
||||
# Apply with high confidence
|
||||
stats = app.category_apply(
|
||||
proposals_csv=proposals_file,
|
||||
site_name='mistergeek.net',
|
||||
confidence='High',
|
||||
dry_run=False
|
||||
)
|
||||
|
||||
print(f"Updated {stats['posts_updated']} posts")
|
||||
```
|
||||
|
||||
## Output Statistics
|
||||
|
||||
After applying categories, you'll see:
|
||||
|
||||
```
|
||||
PROCESSING SUMMARY
|
||||
Total proposals processed: 150
|
||||
Categories created/found: 25
|
||||
Posts updated: 142
|
||||
Errors: 8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2026-02-16
|
||||
**Related**: See ENHANCED_ANALYSIS_GUIDE.md for AI analysis
|
||||
Reference in New Issue
Block a user