Rerank evidence

Select candidate passages by relevance to a query.

You have retrieved passages and want the most relevant evidence for a question.

Explore this recipe interactively · Source and implementation guide

Use rerank in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { rerank } from 'jev-recipes/rerank';

const result = await rerank({
  "query": "How do I reset my password?",
  "items": [
    {
      "id": "billing",
      "text": "Invoices are available on the Billing page."
    },
    {
      "id": "reset",
      "text": "Select Forgot password on the sign-in page. We will email you a reset link."
    },
    {
      "id": "security",
      "text": "Choose a strong password and enable two-factor authentication."
    }
  ],
  "topK": 2,
  "minRelevance": 0.5
});
console.log(result);

Input contract

Field	Type	Needed
query	string	Required
items	array	Required
topK	integer	Optional
minRelevance	number	Optional

Full input and result schemas

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      },
      "items": {
        "minItems": 1,
        "maxItems": 100,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "text": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "text"
          ]
        }
      },
      "topK": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      },
      "minRelevance": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "query",
      "items"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "text": {
              "type": "string"
            },
            "relevance": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "required": [
            "id",
            "text",
            "relevance"
          ],
          "additionalProperties": false
        }
      },
      "evaluated": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "items",
      "evaluated"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo rerank.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "items": [
    {
      "id": "reset",
      "text": "Select Forgot password on the sign-in page. We will email you a reset link.",
      "relevance": 0.97
    }
  ],
  "evaluated": 3
}

Evaluation evidence

Unknown response origin

No verified live accuracy measurement is available. Evaluate representative cases before using this decision in your workflow.

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

Does not retrieve documents or establish source truth.
Provide 1 to 100 items with unique IDs.

Related recipes

answerability: Use answerability to check whether the selected evidence is enough to answer.