> ## 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.

# Scenarios and Walkthroughs

> Step-by-step examples showing how to combine segments, rules, scheduling, pipelines, and A/B testing to achieve real business goals.

These walkthroughs show how the ranking platform features work together to solve real problems. Each scenario can be completed entirely within the console — no engineering support required.

***

## Scenario 1: newsroom weather emergency

**Goal:** Pin a closures guide to slot 2 on the homepage during a live weather event.

<Steps>
  <Step title="Create the rule">
    Open **Console > Rules Engine**, click **New Rule**, and create a `pin` rule named `Pin school closures guide to slot 2`.

    * Condition field: `entity_id`
    * Operator: `equals`
    * Value: `school-closures-live`
    * Action: pin the item to position `2`
    * Scope: homepage context
    * Status: active
  </Step>

  <Step title="Verify with Explainability">
    Open **Console > Explainability**, enter a reader ID and the item ID `school-closures-live`, then click **Explain**.

    **Pass condition:** Explainability shows the rule `Pin school closures guide to slot 2` matched the item.
  </Step>

  <Step title="Confirm the pipeline">
    Open **Console > Pipeline Config** and confirm the active pipeline for the homepage context has the **Rules** stage enabled. Also confirm no experiment is excluding the rule.
  </Step>
</Steps>

This scenario is a good operational test because only one valid result exists. If the item is not in slot `2`, the change failed.

***

## Scenario 2: Streaming platform series launch

**Goal:** Promote a new series for two weeks, targeting users who haven't watched it yet, while running an A/B test to measure the impact.

<Steps>
  <Step title="Define the audience">
    Create two segments in **Console > User Segments** to separate users who have and have not engaged with the series.

    **Segment: "Hasn't watched Series X"**

    * Type: `item_interaction`
    * Item ID: the series item ID, for example `series-x-ep1`
    * Operator: `interactions <`
    * Value: `1`
    * Name: "Hasn't watched Series X"

    **Segment: "Started but didn't finish Series X"**

    * Condition 1: Type `item_interaction`, Item ID `series_x_ep1`, Operator `interactions >`, Value `0`
    * Condition 2: Type `item_interaction`, Item ID `series_x_ep10`, Operator `interactions <`, Value `1`
    * Logic: AND
    * Name: "Started not finished Series X"
  </Step>

  <Step title="Create the rules">
    Create two scheduled rules in **Console > Rules Engine**.

    **Rule: "Pin Series X for new viewers"**

    * Type: `pin`
    * Priority: `80`
    * Condition: `segment_id` equals "Hasn't watched Series X"
    * Action: pin the series into the top 3 positions
    * Schedule: campaign launch through two weeks later

    **Rule: "Boost continuation for partial viewers"**

    * Type: `boost`
    * Priority: `70`
    * Condition: `segment_id` equals "Started not finished Series X"
    * Action: boost the series episodes with a high factor
    * Schedule: same campaign window
  </Step>

  <Step title="Run an A/B test">
    Go to **Console > A/B Testing**, click **New Experiment**, and create "Series X launch campaign".

    * Description: "Hypothesis: pinning Series X for non-viewers increases completion rate."
    * **Control** (50%): no config overrides; standard recommendations
    * **Treatment** (50%): config overrides with `include_rule_ids` set to the two rule IDs above
    * Status: **Running** on launch day
  </Step>

  <Step title="Measure results">
    During the campaign, open the experiment's **Results** tab and click **Refresh metrics** periodically. Compare CTR and conversion rate between Control and Treatment, then check lift percentage.

    After two weeks, set the experiment status to **Completed**. The rules auto-deactivate via their schedule.
  </Step>
</Steps>

***

## Scenario 3: E-commerce flash sale weekend

**Goal:** Boost sale items for a weekend, show premium items to high-value customers, suppress out-of-stock products, and test whether manual merchandising rules outperform pure ML.

<Steps>
  <Step title="Create the high-value customer segment">
    Go to **Console > User Segments**, click **New Segment**, and create "High-value customers".

    * Type: `computed`
    * Field: `total_events`
    * Operator: `greater_than`
    * Value: `100`
  </Step>

  <Step title="Create the sale rules">
    Create the merchandising rules in **Console > Rules Engine**.

    **Rule: "Flash sale boost"**

    * Type: `boost`
    * Priority: `60`
    * Condition: `category` equals `sale`
    * Action: boost with a high factor
    * Schedule: Friday 18:00 to Sunday 23:59

    **Rule: "VIP exclusive items"**

    * Type: `boost`
    * Priority: `80`
    * Conditions: `segment_id` equals "High-value customers" and `tier` equals `premium`
    * Action: boost premium items strongly
    * Schedule: same weekend window

    **Rule: "Suppress out-of-stock"**

    * Type: `filter`
    * Priority: `100`
    * Condition: `stock_status` equals `out_of_stock`
    * Action: exclude matching items
    * Schedule: none; always active
  </Step>

  <Step title="Set up the pure ML experiment">
    Go to **Console > Pipeline Config**, create or note your default pipeline, and consider creating a second pipeline with the **rules stage disabled** for pure ML ranking.

    Then create an experiment in **Console > A/B Testing**:

    * **Control** (50%): default pipeline
    * **Treatment** (50%): pipeline with rules stage disabled
    * Status: **Running** on Friday
  </Step>

  <Step title="Monitor the sale">
    Open **Console > Analytics** and watch served volume. Filter by user ID to spot-check that VIP users see premium items, and refresh experiment metrics throughout the weekend.

    After the sale, complete the experiment and compare conversion rates. The sale rules auto-deactivate after Sunday, so no cleanup is needed.
  </Step>
</Steps>

***

## Scenario 4: Content freshness and diversity

**Goal:** Ensure recommendations always include recent content and don't over-represent a single category.

<Steps>
  <Step title="Create freshness and diversity rules">
    Create both rules in **Console > Rules Engine**.

    **Rule: "Boost new content"**

    * Type: `boost`
    * Priority: `50`
    * Condition: `published_days_ago` is less than `7`
    * Action: boost by a moderate factor
    * Schedule: none; always active

    **Rule: "Diversify by category"**

    * Type: `diversify`
    * Priority: `40`
    * Conditions: none; applies to all results
    * Action: limit to maximum 3 items per `category` value
    * Schedule: none; always active
  </Step>

  <Step title="Verify with Explainability">
    Go to **Console > Explainability**, enter a test user ID and an item ID for a recently published item, and confirm the "Boost new content" rule shows **matched**.

    Try an older item and confirm it shows **no match**.
  </Step>
</Steps>

***

## Scenario 5: Gradual feature rollout

**Goal:** Roll out a new set of ranking rules to 10% of users first, then expand.

<Steps>
  <Step title="Deploy rules as inactive">
    Create your new rules but leave them **inactive** with the toggle off. Note their rule IDs.
  </Step>

  <Step title="Create a staged experiment">
    Go to **Console > A/B Testing** and create an experiment:

    * **Control** (90%): no config overrides
    * **Treatment** (10%): config overrides with `include_rule_ids` set to the new rule IDs
    * Status: **Running**
  </Step>

  <Step title="Monitor and expand">
    Check experiment metrics after a few days. If metrics look good, edit the experiment and adjust traffic to Control 50% and Treatment 50%.

    Continue monitoring. When confident, set the experiment to **Completed**, activate the rules for everyone, and delete the experiment.
  </Step>
</Steps>

***

## Combining features

These scenarios demonstrate a pattern: **segments define who, rules define what, scheduling defines when, pipelines define how, and experiments measure whether it works.**

| Feature         | Role                                  |
| --------------- | ------------------------------------- |
| User Segments   | Target specific user cohorts          |
| Rules Engine    | Override rankings with business logic |
| Rule scheduling | Time-bound campaigns                  |
| Pipeline Config | Control which processing stages run   |
| A/B Testing     | Measure impact with traffic splits    |
| Explainability  | Debug and verify before launch        |
| Analytics       | Monitor outcomes in production        |