Skip to main content

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 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:
1

Store controls on the context

Rerank controls are stored on the context record under json_data.rerank_controls.
2

Read and save through Platform API routes

The console reads and saves them through GET /api/rerank-controls and PUT /api/rerank-controls.
3

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

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.

​
Configure in the console

1

Open Rerank Controls

Navigate to Console > Rerank Controls.
2

Open a context

Click a context row to open the editor.
3

Set the global default

Set the Global Default, the baseline mode and depth applied when no surface-specific preset matches.
4

Configure surface presets

Optionally configure Surface Presets to override behaviour for search, results, or recommendations surfaces independently.
5

Save changes

Save your changes.

​
Global defaults

FieldDescription
Default SurfaceThe surface assumed when the caller does not specify one.
Rerank Modeoff (no reranking), balanced (moderate), or aggressive (strong personalisation, higher latency).
Rerank DepthNumber 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: 
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:
VariableDescription
RERANK_CONTROLS_STAGEoff, internal, canary, or general. Controls who receives reranking.
RERANK_KILL_SWITCHSet to true to immediately disable all reranking.
RERANK_MAX_DEPTHHard ceiling for rerank depth across all contexts.
RERANK_INTERNAL_TEAM_IDSComma-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: 
{
  "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
  }
}