Revolution Recommendation

A professional, content-based recommendation engine for WordPress built on AI embeddings.

Version 1 is designed for up to 5,000 source items per installation and runs entirely on a standard WordPress/MySQL environment — no external vector database required.

Features

• Content pipeline: extract → normalize → chunk → hash → embed → store
• Embedding providers: local deterministic provider (no API key) and OpenAI-compatible HTTP provider
• Chunking: configurable size/overlap with sentence/paragraph-aware splitting
• Content hashing: SHA-256 hashes skip re-embedding of unchanged content
• MySQL vector storage: JSON vectors in dedicated rr_* tables, batched in-PHP cosine similarity
• Recommendation engine: over-fetch candidates → filter → rank → top-N
• REST API: rr/v1 namespace for recommendations, events, indexing, and health
• Event tracking: impressions, clicks, views, likes, dismissals, add-to-cart, purchases
• Queue: Action Scheduler with WordPress cron fallback; idempotent, retryable jobs
• Caching: Redis-compatible abstraction with WordPress object cache fallback
• Admin dashboard: overview, content/index, provider settings, recommendation preview, analytics, queue, settings
• Security: capability checks, nonces, prepared SQL, rate limiting, AES-256-GCM encrypted API keys

Requirements

• PHP 8.2+
• WordPress 6.2+
• MySQL 8+ (or a compatible WordPress MySQL environment)
• Composer (for development; the plugin includes a PSR-4 fallback autoloader)

Installation

1. Copy the revolution-recommendation folder into wp-content/plugins/.
2. Activate the plugin. The rr_* tables are created automatically.
3. Visit Recommendation AI → AI Providers and choose an embedding provider:
   • Local — works immediately, no credentials required.
   • OpenAI-compatible — enter an API base URL, model, and API key.
4. Go to Recommendation AI → Content and trigger indexing.

REST API

Base namespace: /wp-json/rr/v1/

Example: recommendations

GET /wp-json/rr/v1/recommendations?item_id=123&limit=6

{
    "request_id": "rr_7f83a91c",
    "strategy": "content",
    "items": [
        { "id": 456, "score": 0.942, "_links": { "self": "https://example.com/?p=456" } }
    ]
}

Example: event

POST /wp-json/rr/v1/events
Content-Type: application/json

{
    "item_id": 456,
    "event_type": "click",
    "recommendation_id": "rr_7f83a91c",
    "position": 2
}

Development

composer install

# Quality gates
composer test      # PHPUnit (unit + integration smoke)
composer analyse   # PHPStan level 6
composer lint      # PHP_CodeSniffer (WordPress-Extra + relaxed WordPress-Docs)

The repository ships phpcs.xml.dist, phpstan.neon.dist, and phpunit.xml.dist. A docker-compose.yml is included for spinning up a WordPress + MySQL 8 test environment.

Architecture

Admin / REST API
        ↓
Application Services
        ↓
Domain / Recommendation Core
        ↓
Provider Interfaces
        ↓
Storage / WordPress Infrastructure

Core extension points (all interface-based, so later versions can swap storage or providers without touching the recommendation engine):

• Storage\Contracts\VectorStore
• AI\Contracts\EmbeddingProvider
• AI\Contracts\TranscriptionProvider
• Recommendation\Strategies\RecommendationStrategy
• Recommendation\Ranker
• Support\Contracts\Cache
• Queue\QueueManager

Database tables

Created on activation with the plugin database prefix (never hard-coded wp_):

License

GPL-2.0-or-later