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
- HTTP
POST /v1/reranking-policies, GET /v1/reranking-policies, GET .../{name}, GET .../{name}/versions, POST /v1/reranking-policies/rerank
Example
{
"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.