Rules Engine

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

---

​

Where rules fit

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

---

​

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:

​

Segment conditions

Target a rule to users in a specific segment: 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.

​

Setting a schedule

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 for details.