PishTop Content Suggestion with AI

PishTop Content Suggestion with AI is a next-generation related posts plugin that uses advanced semantic modeling. Rather than relying on simple keyword matching, it leverages local vector embeddings (generated via OpenRouter.ai) and cosine similarity in PHP to find contextually relevant recommendations.

To achieve maximum precision, the plugin performs local similarity pre-filtering and passes the top candidates to a selected OpenRouter Chat LLM (e.g., Gemini, GPT-4) for a final re-ranking step.

Key Features

• Embedding-Only Mode: Option to completely bypass the OpenRouter LLM re-ranking phase, using raw vector similarity to fetch recommendations locally, cutting API billing and optimizing site performance.
• Configurable Similarity Threshold: Enforce similarity score limits (0-100%) in the embedding-only phase to filter out low-relevance match candidates.
• Local Vector Storage: Custom database tables store text embedding vectors, preventing external API calls on every recommendation render.
• Embedding Model Versioning: Embeddings are versioned with the model ID. Stale embeddings (e.g., if you change models) are automatically filtered out.
• OpenRouter.ai Integration: Fetch high-quality text embeddings and perform LLM re-ranking using state-of-the-art models.
• Cost-Control Quotas: Separate daily limits block embedding and ranking operations once exceeded, automatically falling back to native category recommendations to prevent surprise API charges. Aligned with local WordPress timezone settings.
• Mutex Lock Stampede Protection: Restricts concurrent API calls during content updates, protecting your budgets under traffic surges.
• Display Layout Templates: Create custom wrapper and item markup right inside the settings dashboard. Include WooCommerce price and custom metadata variables instantly.
• Dynamic WooCommerce Contexts: Automatically overrides generic page titles on Cart, Checkout, and Thank You pages with active cart products and purchased items to yield relevant recommendations.
• WooCommerce Out-of-Stock Filter: Respects WooCommerce catalog visibility configurations, automatically hiding out-of-stock items from recommendations.
• User-Isolated Caching Keys: Cache transients on WooCommerce pages vary dynamically using secure cart item hashes and order IDs, preventing cross-user caching leakage.
• Developer Extensibility Filters: Hook into pishtop_ai_post_text to modify source text dynamically, and pishtop_ai_recommendations_transient_key to route custom transient cache partitions.
• Viewport Lazy Loading: Trigger frontend AJAX suggestion loading via Intersection Observer, saving bandwidth and reducing API costs by querying only when the recommendations block becomes visible.

External Services

This plugin relies on the third-party API service OpenRouter (openrouter.ai) to generate vector embeddings and perform LLM re-ranking of content suggestions.

Specifically, it makes remote requests to: * https://openrouter.ai/api/v1/embeddings (Sends post title, excerpt, content, taxonomies, and/or custom fields to generate numeric representation vectors of the content when a post is created/updated or during background indexing). * https://openrouter.ai/api/v1/chat/completions (Sends post text and lists of recommendation candidate metadata to rank recommendations dynamically upon content retrieval). * https://openrouter.ai/api/v1/models (Fetches list of available LLM and embedding models in the admin settings dashboard).

Use of these services is subject to the OpenRouter Terms of Service and Privacy Policy: * OpenRouter Terms of Service: https://openrouter.ai/terms * OpenRouter Privacy Policy: https://openrouter.ai/privacy

Settings Reference

General Settings

• OpenRouter API Key: Configures authorization to OpenRouter.
• Cache Expiry (TTL): Set time to cache recommendations (Hours/Days).
• Default Fallback: Native Category/Tag, Recent, or Hide.
• Cache Actions: Buttons to clear recommendation cache or clear all embeddings.

Matching Engine

• Enable LLM Re-ranking: Toggle switch to enable/disable the OpenRouter chat API reordering phase.
• Similarity Threshold (%): Minimum similarity score percent required for recommendations (available when LLM Re-ranking is disabled).
• Embedding Model: OpenRouter embedding vector model.
• Embedding Fields: Checkboxes to select which fields are concatenated for embeddings (Title, Excerpt, Content, Taxonomies, Custom Fields).
• Ranking Model: Chat model for LLM re-ranking.
• Similarity Candidate Count: Number of top similar vectors to query.
• Max Pre-filtered Candidates: Maximum candidates to select in SQL before similarity calculations.
• Max Recommendation Count: Default recommendation count.
• Payload Fields: Checkboxes for post attributes to include in the LLM ranking prompt (Title, Excerpt, Content).
• Prompt Editor: Customize system ranking prompt template with placeholder {{count}}. Features a default reset button.
• Final Output Sort: Sort results by Similarity, Random, Date Descending, Date Ascending, or Title Ascending.
• Thumbnail Size: Dropdown for custom thumbnail size query.
• Limit Candidates by Category: If checked, similarity search candidate queries are restricted strictly to the current post’s category.

API Quota & Security Settings

• Daily Embedding Quota: Max indexing requests per day.
• Daily Ranking Quota: Max retrieval requests per day.
• Stats Cards: Shows live counters for embedding and ranking usage today.

Display Templates

• Layout CSS Toggle: Toggle loading built-in styles.
• Repeater List: Create custom HTML repeater template rows with custom Wrapper HTML (using {{items}}), Item HTML (using placeholders {{title}}, {{permalink}}, {{image_url}}, {{excerpt}}, {{post_date}}, {{id}}, custom fields {{meta:key}}, WooCommerce prices {{price}} / {{price:key}}).

Logging & Diagnostics

• Enable Logging: Toggle logging console.
• Retention Period: Keep logs for X days.
• Max Log Rows: Logs table ceiling count (default 5000).
• Log Cleanup Threshold Ratio: Percentage threshold of max rows to prune logs to when full.
• Cron Indexing Settings: Customize cron embedding batch size, cron ranking batch size, cron worker interval, post save indexing delay, and active indexes safety queues.