> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules Engine

> Create post-scoring ranking rules that boost, bury, pin, filter, cap, dedupe, reorder, group, and otherwise reshape recommendation results.

The Rules Engine lets you override ML-generated rankings with deliberate post-scoring logic. Contexts decide how candidates are retrieved and pre-filtered. Rules decide what happens to those scored candidates before the final response is returned.

Use rules when you need to:

* promote or demote matching items
* suppress repeats or cap over-represented content
* pin items to exact positions
* override sort order or inject controlled randomness
* return grouped results instead of a flat list
* weight results using user topic affinity

***

## Creating a rule

<Steps>
  <Step title="Open Rules Engine">
    Navigate to **Console > Rules Engine**.
  </Step>

  <Step title="Start a new rule">
    Click **New Rule**.
  </Step>

  <Step title="Fill in the required fields">
    Fill in the required fields:

    * **Name** - a descriptive label such as "Boost new arrivals" or "Cap sponsored items".
    * **Type** - the action the rule performs.
    * **Priority** - higher numbers execute first.
    * **Active** - toggle on to make the rule live.
  </Step>

  <Step title="Add conditions">
    Add one or more conditions to control when the rule applies.
  </Step>

  <Step title="Configure the action">
    Configure the action parameters for the selected rule type.
  </Step>

  <Step title="Set an optional schedule">
    Optionally set a schedule with start and end dates.
  </Step>

  <Step title="Create the rule">
    Click **Create Rule**.
  </Step>
</Steps>

***

## Where rules fit

| Configure in     | Use it for                                                                                                |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| **Contexts**     | Model selection, recommendation type, and pre-query filters that narrow the candidate pool before scoring |
| **Rules Engine** | Post-scoring ranking, suppression, ordering, grouping, and business logic applied after scoring           |

If you need to change what gets scored in the first place, use a **Context**. If you need to change how scored candidates are promoted, suppressed, ordered, or reshaped, use the **Rules Engine**.

***

## Rule type reference

| Type             | What it does                                                                                         | Main action settings               | Example configuration                                                 |
| ---------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------- |
| `boost`          | Multiplies matching item scores upward so they rise in the ranked list.                              | `weight`                           | Conditions: `is_new_arrival = true` • Action: `weight = 1.8`          |
| `bury`           | Multiplies matching item scores downward so they fall relative to stronger candidates.               | `weight`                           | Conditions: `quality_band = low` • Action: `weight = 0.4`             |
| `filter`         | Removes matching items from the result set entirely.                                                 | None                               | Conditions: `availability = out_of_stock`                             |
| `pin`            | Moves the first matching item to a fixed 1-based position after ranking.                             | `pin_position`                     | Conditions: `item_id = launch-hero-2026` • Action: `pin_position = 1` |
| `cap`            | Limits how much of the final list matching items may occupy.                                         | `cap_fraction`                     | Conditions: `content_type = sponsored` • Action: `cap_fraction = 0.2` |
| `diversity`      | Limits repetition across a metadata field so the result set stays varied.                            | `diversity_field`, `diversity_max` | Action: `diversity_field = brand`, `diversity_max = 2`                |
| `dedupe`         | Prevents the same item or entity from reappearing within a sliding result window.                    | `dedupe_window`                    | Action: `dedupe_window = 24`                                          |
| `randomize`      | Shuffles result order to introduce variety on low-stakes or discovery-oriented surfaces.             | None                               | Conditions: `surface = explore`                                       |
| `reorder`        | Overrides the default relevance sort with a metadata field sort.                                     | `order_field`, `order_direction`   | Action: `order_field = published_at`, `order_direction = desc`        |
| `ensure_top`     | Preserves a minimum number of high-relevance items in the top band even when other rules are active. | `top_count`                        | Action: `top_count = 5`                                               |
| `group_by`       | Returns grouped results based on one or more metadata fields instead of a flat ranked list.          | `group_by_fields`                  | Action: `group_by_fields = ["category", "brand"]`                     |
| `weighted_topic` | Reweights results using a topic or category field derived from user behaviour.                       | `topic_field`                      | Action: `topic_field = category`                                      |

***

## Choosing the right rule

Think about rules in four buckets:

* **Score modifiers**: `boost`, `bury`, `weighted_topic`
* **Hard constraints**: `filter`, `cap`, `diversity`, `dedupe`
* **Ordering controls**: `pin`, `randomize`, `reorder`, `ensure_top`
* **Response shaping**: `group_by`

This makes rule design simpler:

* Use **boost** or **bury** when you want relevance to matter, but not be absolute.
* Use **filter** when an item must never appear.
* Use **cap** or **diversity** when too much of one class of content is crowding the list.
* Use **pin** when a specific item must occupy a specific slot.
* Use **reorder** when relevance should be secondary to a known business sort such as recency.
* Use **group\_by** when the consuming surface is meant to show grouped entities rather than a flat list.

***

## Conditions

Conditions determine which items or users a rule applies to. A rule with no conditions applies to everything in scope.

### Item metadata conditions

Match against fields in the item's metadata:

| Field          | Operator       | Value          | Meaning                 |
| -------------- | -------------- | -------------- | ----------------------- |
| `genre`        | `equals`       | `action`       | Item genre is action    |
| `price`        | `greater_than` | `50`           | Item costs more than 50 |
| `stock_status` | `equals`       | `out_of_stock` | Item is unavailable     |

### Segment conditions

Target a rule to users in a specific segment:

<Steps>
  <Step title="Add a segment condition">
    Add a condition and set the field to `segment_id`.
  </Step>

  <Step title="Choose from the dropdown">
    A dropdown appears listing all available segments.
  </Step>

  <Step title="Select the segment">
    Select the segment. The rule now only applies to users who belong to that segment.
  </Step>
</Steps>

This is how you build targeted campaigns, such as boosting a new series only for users who have not yet watched it.

***

## Notes for each rule type

### `boost`

Use `boost` when you want a soft promotion rather than a hard override. Higher weights push matching items upward while still allowing genuinely stronger results to compete.

### `bury`

Use `bury` for items that should remain eligible but less prominent, such as low-margin products, stale inventory, or low-quality content.

### `filter`

Use `filter` for non-negotiable constraints such as compliance, availability, or market restrictions. Once filtered out, an item is gone for that request.

### `pin`

Use `pin` when a specific item must land in a precise slot. Pinning happens after ranking, so it is best for high-confidence placements like launch heroes or mandated disclosures.

### `cap`

Use `cap` when matching items are allowed, but only up to a share of the list. This is especially useful for sponsored, house-brand, or single-vendor content.

### `diversity`

Use `diversity` when a single attribute dominates the list. Common fields are `brand`, `category`, `series_id`, or `author`.

### `dedupe`

Use `dedupe` when repeated entities hurt trust or usefulness. Typical examples are not showing the same SKU twice in a carousel or the same article again in the next few positions.

### `randomize`

Use `randomize` on exploratory or serendipity-focused surfaces where exact ranking is less important than freshness and variety.

### `reorder`

Use `reorder` when business logic should temporarily outweigh relevance, such as sorting by `published_at desc` for a latest-news rail or by `price asc` for a clearance shelf.

### `ensure_top`

Use `ensure_top` to protect the top band from becoming entirely campaign-driven. It works well alongside boosts and pins when you still want the first few results to remain relevance-led.

### `group_by`

Use `group_by` when the consuming UI is designed around grouped entities, such as categories, brands, or collections instead of single items.

### `weighted_topic`

Use `weighted_topic` when users consistently engage with recognizable content topics. A field such as `category`, `topic`, or `tag_family` is a good fit.

***

## Scheduling

Rules support time-based activation via start and end dates.

| Configuration    | Behaviour                                               |
| ---------------- | ------------------------------------------------------- |
| Both dates set   | Rule is active only within the window                   |
| Start date only  | Rule activates at that time, with no automatic end      |
| End date only    | Rule is active now but deactivates after the deadline   |
| Neither date set | Rule is always active, subject to the **Active** toggle |

### Setting a schedule

<Steps>
  <Step title="Choose dates">
    In the rule editor, use the **Start date** and **End date** datetime pickers.
  </Step>

  <Step title="Check the scheduled badge">
    Rules with a schedule show a **scheduled** badge in the table view.
  </Step>

  <Step title="Clear dates when needed">
    Click **Clear schedule** to remove dates and make the rule always active.
  </Step>
</Steps>

Scheduling is enforced at the database level, so time-zone handling stays consistent regardless of where the request originates.

***

## Priority and execution order

Rules execute in **descending priority order** (highest first). When multiple rules affect the same item:

* A `pin` at priority 100 can still place an item ahead of a `boost` at priority 50.
* A `filter` removes the item entirely, so later rules never see it.
* A `cap` or `diversity` rule can trim over-represented content even after score adjustments.

Use priority deliberately:

* **100+** for hard business constraints and compliance-sensitive rules
* **50-99** for campaigns, featured placements, and seasonal pushes
* **1-49** for softer merchandising preferences

***

## How rules interact with experiments

When an A/B experiment is running, each variant can include `config_overrides` that specify:

* `include_rule_ids` — only these rules apply for users in this variant
* `exclude_rule_ids` — these rules are skipped for users in this variant

This lets you test the impact of specific rule sets against a control group. See [A/B Testing](/guides/ab-testing) for details.