Search & retrieval

Reranking policies

Lets an operator author, version and apply an explicit ranking policy over retrieval candidates instead of baking ranking rules into application code.

Available in previewEngine edition 5f8ea3af

What it does

A reranking policy is versioned data: weights over lexical, vector, recency and authority signals, boost and bury rules, a per-group diversity cap, hard exclude or require constraints and a feature-cost budget. POST /v1/reranking-policies/rerank applies a stored or inline policy to candidates the caller supplies and returns the final order with a report of which signals were used or skipped and why. The search routes do not apply policies automatically.

How it works

Each candidate carries an id, an optional kind, a lexical (BM25) score, a vector (cosine) score, a recency value (larger means newer), an authority weight, a group key, a flagged marker and free attributes. A policy sets non-negative weights for lexical, vector, recency and authority (lexical and vector default to 1, the others to 0), a list of business rules that add to or subtract from a matching candidate score, an optional diversity cap on how many candidates of one group may sit at the head of the ranking, hard constraints that exclude or require candidates, and a top_k. Rules and constraints match on kind, the flagged marker or an exact attribute value. Constrained-out candidates are removed before scoring and cannot appear in the result; diversity overflow is demoted below the head, not dropped.

Scoring is deterministic. Signals are min-max normalised within the candidate set so weights compare across scales, and ties break by candidate id ascending, so the output never depends on input order. A signal missing from every candidate is dropped and recorded; a signal missing from some candidates counts as a neutral zero for those.

Every signal has a fixed cost, and the reranker admits signals in a fixed priority order while the running cost stays inside the policy feature budget (a total cost that defaults to 100). A signal that would exceed the budget is skipped and reported. If the budget cannot afford any scoring signal, the result falls back to reciprocal-rank fusion of the two first-stage scores. The response lists the signals used, the signals skipped with the reason, whether it fell back and the estimated cost.

Policies are immutable, numbered versions with a content hash. Publishing appends the next version with a compare-and-swap; a second administrator racing for the same version gets a retryable 409 and re-reads. Publishing needs an admin or service credential. The rerank call is open to any authenticated caller, reads policies of that project alone, and accepts either policy_name (latest stored version) or an inline policy that is validated first, which makes a dry run possible without publishing.

Where you reach it

  • HTTPPOST /v1/reranking-policies, GET /v1/reranking-policies, GET .../{name}, GET .../{name}/versions, POST /v1/reranking-policies/rerank

Example

POST /v1/reranking-policies/rerank with an inline policy (dry run)json
{
  "policy": {
    "name": "fresh-and-diverse",
    "weights": { "lexical": 1.0, "vector": 1.0, "recency": 0.5, "authority": 0.0 },
    "rules": [
      { "name": "bury-flagged", "match": "flagged", "action": { "action": "bury", "amount": 0.5 } }
    ],
    "diversity": { "max_per_group": 2 },
    "top_k": 10
  },
  "candidates": [
    { "id": "a", "lexical_score": 7.2, "vector_score": 0.81, "recency": 1760000000, "group": "acme" },
    { "id": "b", "lexical_score": 6.9, "vector_score": 0.88, "recency": 1750000000, "group": "acme" },
    { "id": "c", "lexical_score": 3.1, "vector_score": 0.92, "recency": 1770000000, "group": "zen", "flagged": true }
  ]
}

Limits

  • The route reranks candidates supplied in the request. The search, vector and hybrid routes do not call it, so applying a policy is a second request from your application.
  • Recency, authority, group and flagged values come from the caller; the platform does not derive them.
  • Quality evidence is a fixture-based comparison in the engine repository (a policy improves nDCG over base fusion on a constructed case), not a measurement on production data.
  • Rules adjust the normalised score by a fixed amount you choose; there is no learned weighting.

Evidence

  • On this siteHTTP API reference
  • Tests23 policy tests and 2 route tests cover the signals, normalisation, tie-break, budget, fallback and constraints; one evaluation-harness test compares nDCG against base fusion on a fixture

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to try this against your own workload.