How to Control Recommendation Results with NeuronSearchLab Rules

Recommendation algorithms excel at finding patterns in user behavior, but they cannot understand business context, inventory constraints, or editorial priorities. This is where NeuronSearchLab's rules engine bridges the gap between machine learning outputs and operational requirements.

This guide walks you through implementing boost rules, pin rules, filter rules, and diversity controls to fine-tune your recommendation results without rebuilding your underlying models.

Prerequisites and Setup

Before configuring rules, you need:

1. A NeuronSearchLab account with admin console access
2. At least one context configured with catalog data
3. SDK credentials for your development environment
4. Basic familiarity with your catalog structure and business requirements

If you do not have credentials yet, sign up at console.neuronsearchlab.com/signup. Once registered, follow the getting started guide to set up your first context and connect your catalog.

For comprehensive setup instructions, see the catalog and events connection guide.

Understanding the NeuronSearchLab Rules Engine

Rules in NeuronSearchLab operate as a post-processing layer that modifies recommendation results after the initial ML-driven ranking. This approach preserves the benefits of collaborative filtering and learned embeddings while giving operators precise control over business logic.

The rules engine supports four primary operations:

• Boost rules increase the ranking score of items matching specific criteria
• Pin rules force specific items to appear at designated positions
• Filter rules remove items that should not appear in recommendations
• Diversity rules ensure variety across categorical dimensions

Rules are applied in a deterministic order during serving, allowing you to layer multiple business requirements without conflicts.

Configuring Boost Rules

Boost rules increase the relevance score of items matching your criteria, making them more likely to appear in top positions without guaranteeing specific placement.

Step 1: Navigate to Rules Configuration

1. Log into the NeuronSearchLab admin console
2. Select your target context from the contexts list
3. Click on "Rules" in the left navigation
4. Select "Create Rule" and choose "Boost Rule"

Step 2: Define Boost Criteria

Configure the conditions that trigger the boost:

// Example: Boost seasonal items during relevant periods
{
  "rule_type": "boost",
  "conditions": {
    "item_attributes": {
      "category": "seasonal",
      "season": "winter"
    },
    "time_range": {
      "start": "2026-12-01",
      "end": "2026-02-28"
    }
  },
  "boost_factor": 1.5,
  "name": "Winter Seasonal Boost"
}

The boost factor multiplies the original ranking score. Values greater than 1.0 increase ranking, while values between 0.0 and 1.0 decrease it.

Step 3: Set Boost Magnitude

Choose boost factors based on your business impact requirements:

• Light boost (1.1-1.3): Subtle preference adjustments
• Medium boost (1.3-2.0): Clear promotional priority
• Strong boost (2.0-5.0): Major campaign emphasis

Step 4: Test and Validate

After saving your boost rule, verify its impact using the recommendation testing interface in the console or by making test API calls with your SDK.

Implementing Pin Rules

Pin rules guarantee that specific items appear at exact positions in recommendation results, regardless of their algorithmic ranking.

Step 1: Create Pin Rule Configuration

Pin rules override algorithmic rankings completely for specified positions:

// Example: Pin featured products in top positions
{
  "rule_type": "pin",
  "conditions": {
    "context": "homepage_recommendations",
    "user_segments": ["premium_subscribers"]
  },
  "pinned_items": [
    {
      "item_id": "featured_product_123",
      "position": 1
    },
    {
      "item_id": "promotional_item_456",
      "position": 3
    }
  ],
  "name": "Premium User Featured Pins"
}

Step 2: Handle Position Conflicts

When multiple rules attempt to pin items to the same position, NeuronSearchLab applies rules in priority order. Set rule priorities in the console to resolve conflicts predictably.

Step 3: Monitor Pin Performance

Track click-through rates and conversion metrics for pinned positions to ensure editorial choices align with user preferences. High-performing pins can inform future algorithmic improvements.

Setting Up Filter Rules

Filter rules remove items from recommendation results based on business logic, inventory status, or content policies.

Step 1: Define Filter Conditions

Create filters that remove unwanted items before serving:

// Example: Filter out-of-stock items
{
  "rule_type": "filter",
  "conditions": {
    "item_attributes": {
      "inventory_status": "out_of_stock"
    }
  },
  "action": "exclude",
  "name": "Remove Out of Stock Items"
}

Step 2: Implement Conditional Filters

Apply filters based on user context or business requirements:

// Example: Age-appropriate content filtering
{
  "rule_type": "filter",
  "conditions": {
    "user_attributes": {
      "age_verified": false
    },
    "item_attributes": {
      "content_rating": ["mature", "adult"]
    }
  },
  "action": "exclude",
  "name": "Age Verification Filter"
}

Step 3: Balance Filter Strictness

Overly aggressive filtering can reduce recommendation coverage. Monitor the percentage of requests that return fewer results due to filtering, and adjust criteria if coverage drops below acceptable thresholds.

Implementing Diversity Rules

Diversity rules ensure variety across categorical dimensions, preventing recommendations from becoming too narrow or repetitive.

Step 1: Configure Category Diversity

Set maximum limits for items from specific categories:

// Example: Limit items per category in results
{
  "rule_type": "diversity",
  "conditions": {
    "context": "user_homepage"
  },
  "diversity_constraints": {
    "category": {
      "max_items_per_value": 2,
      "minimum_categories": 3
    },
    "brand": {
      "max_items_per_value": 1
    }
  },
  "name": "Homepage Category Diversity"
}

Step 2: Implement Temporal Diversity

Prevent recent recommendations from dominating future results:

// Example: Reduce recently recommended items
{
  "rule_type": "diversity",
  "conditions": {
    "time_window": "24h"
  },
  "diversity_constraints": {
    "recently_recommended": {
      "max_repeat_ratio": 0.2
    }
  },
  "name": "24 Hour Recency Diversity"
}

Step 3: Balance Relevance and Diversity

Diversity rules can reduce short-term engagement if applied too aggressively. Start with moderate constraints and adjust based on user feedback and engagement metrics.

Verifying Rule Performance

Testing Individual Rules

Use the console's recommendation preview to test rules before deployment:

1. Navigate to your context's recommendation testing interface
2. Input sample user attributes and request parameters
3. Preview results with and without your new rule
4. Verify the rule triggers correctly for your test cases

Monitoring Production Impact

Track rule effectiveness using NeuronSearchLab's analytics dashboard:

• Coverage metrics: Percentage of requests where rules trigger
• Position impact: How rules change average item positions
• Engagement changes: Click-through and conversion rate differences
• Diversity scores: Categorical distribution in served results

A/B Testing Rule Changes

Before applying rules to all users, validate their impact using experiments:

1. Create an experiment in the NeuronSearchLab console
2. Assign rules to the treatment group while maintaining control
3. Monitor performance differences over a statistically significant period
4. Apply successful rules broadly based on experiment results

For detailed experiment setup, see the experimentation documentation.

Troubleshooting Common Issues

Rules Not Triggering

Problem: Rules appear configured correctly but do not affect recommendation results.

Solutions:

• Verify rule conditions match your actual catalog data structure
• Check that the target context has sufficient catalog data
• Ensure rule priority settings do not conflict with higher-priority rules
• Confirm the rule status is set to "active" in the console

Over-Filtering Results

Problem: Filter rules remove too many items, reducing recommendation coverage.

Solutions:

• Review filter conditions for overly restrictive criteria
• Implement fallback logic for cases with insufficient qualifying items
• Monitor coverage metrics and set alerts for drops below target thresholds
• Consider using boost rules instead of hard filters for marginal cases

Diversity Rules Reducing Relevance

Problem: Diversity constraints significantly impact engagement metrics.

Solutions:

• Reduce diversity constraint strictness gradually
• Apply diversity rules only to specific positions (e.g., positions 5-10)
• Use diversity as a secondary optimization after relevance thresholds
• Test different diversity approaches using A/B experiments

Pin Rules Creating Poor User Experience

Problem: Pinned items have low engagement or feel forced to users.

Solutions:

• Limit pins to top-performing inventory based on historical data
• Use pins sparingly and only for high-confidence promotional content
• Implement pins conditionally based on user segments or contexts
• Monitor pinned item performance and rotate underperforming content

FAQ

Q: How many rules can I apply to a single context? A: NeuronSearchLab supports multiple rules per context. However, complex rule combinations can increase serving latency. Monitor performance and optimize rule logic for production workloads.

Q: Can rules access real-time data like current inventory levels? A: Rules evaluate against catalog data that syncs with your inventory systems. For real-time filtering, update catalog attributes frequently or use the API to mark items as unavailable.

Q: How do rules interact with machine learning model updates? A: Rules apply after ML ranking, so model improvements preserve rule behavior. When retraining models, verify that rule effectiveness remains consistent with new algorithmic outputs.

Q: Can I apply different rules based on user location or device type? A: Yes, rules support conditional logic based on user attributes, request context, and session metadata. Configure conditions to match your targeting requirements.

Q: How do I roll back rules if they negatively impact performance? A: Rules can be deactivated immediately in the console. For gradual rollbacks, reduce rule scope or adjust parameters before full deactivation.

For additional implementation guidance, see the complete documentation or contact support through the admin console.