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

# Rerank Controls

> Configure reranking behaviour per context to tune relevance and personalisation.

Rerank controls store per-context settings for the learned reranking layer. Configure them in the console when you need operators to manage the intended rerank mode, depth, and surface presets for a context.

## How it works

The current product surface works like this:

<Steps>
  <Step title="Store controls on the context">
    Rerank controls are stored on the context record under `json_data.rerank_controls`.
  </Step>

  <Step title="Read and save through Platform API routes">
    The console reads and saves them through `GET /api/rerank-controls` and `PUT /api/rerank-controls`.
  </Step>

  <Step title="Gate rollout with feature flags">
    Feature flags such as `RERANK_CONTROLS_STAGE`, `RERANK_KILL_SWITCH`, and `RERANK_MAX_DEPTH` control rollout state in the console and resolver helper.
  </Step>

  <Step title="Serve through the Core API">
    Recommendation serving still goes through the Core API recommendation endpoint. There is no documented `GET /api/recommendations` Platform API route.
  </Step>
</Steps>

## Configure in the console

<Steps>
  <Step title="Open Rerank Controls">
    Navigate to **Console > Rerank Controls**.
  </Step>

  <Step title="Open a context">
    Click a context row to open the editor.
  </Step>

  <Step title="Set the global default">
    Set the **Global Default**, the baseline mode and depth applied when no surface-specific preset matches.
  </Step>

  <Step title="Configure surface presets">
    Optionally configure **Surface Presets** to override behaviour for `search`, `results`, or `recommendations` surfaces independently.
  </Step>

  <Step title="Save changes">
    Save your changes.
  </Step>
</Steps>

## Global defaults

| Field               | Description                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| **Default Surface** | The surface assumed when the caller does not specify one.                                              |
| **Rerank Mode**     | `off` (no reranking), `balanced` (moderate), or `aggressive` (strong personalisation, higher latency). |
| **Rerank Depth**    | Number of candidates to rerank. Higher values improve quality at the cost of latency.                  |

## Surface presets

Each surface (`search`, `results`, `recommendations`) can override the global mode and depth. Surfaces that match the global default show as "inheriting" in the UI.

## API access

Use a Platform API key with the `admin` scope to inspect or update saved controls:

```bash theme={null}
curl "https://console.neuronsearchlab.com/api/rerank-controls?contextId=101" \
  -H "Authorization: Bearer nsl_..."
```

## Feature flags and kill switch

Rerank controls support staged rollouts via environment variables:

| Variable                   | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `RERANK_CONTROLS_STAGE`    | `off`, `internal`, `canary`, or `general`. Controls who receives reranking. |
| `RERANK_KILL_SWITCH`       | Set to `true` to immediately disable all reranking.                         |
| `RERANK_MAX_DEPTH`         | Hard ceiling for rerank depth across all contexts.                          |
| `RERANK_INTERNAL_TEAM_IDS` | Comma-separated team IDs allowed during the `internal` stage.               |

When the kill switch is active or the stage is `off`, the resolver helper treats reranking as disabled and resolves `rerank_mode: off` with `rerank_depth: 0`.

## Response shape

The Platform API returns context controls plus the current feature flags:

```json theme={null}
{
  "context": {
    "contextId": 101,
    "contextName": "Homepage Feed",
    "config": {
      "global_default": {
        "surface": "recommendations",
        "rerank_mode": "balanced",
        "rerank_depth": 80
      },
      "surface_presets": {
        "search": { "rerank_mode": "aggressive", "rerank_depth": 120 },
        "results": { "rerank_mode": "balanced", "rerank_depth": 80 },
        "recommendations": { "rerank_mode": "balanced", "rerank_depth": 80 }
      }
    }
  },
  "featureFlags": {
    "rerank_controls_stage": "general",
    "rerank_kill_switch": false,
    "rerank_max_depth": 200
  }
}
```