Rerank

The POST /v2/rerank endpoint is a Cohere-compatible reranking mock. Register fixture patterns on the LLMock instance and the request query is matched against them — first match wins, no match returns empty results.

Endpoint

How It Works

• The query field is matched against registered patterns — string patterns are case-insensitive substring matches, RegExp patterns are tested as-is
• First matching fixture wins, so register specific patterns before catch-alls
• Unmatched queries return an empty results array
• Under strict mode (--strict, or X-AIMock-Strict: true on the request), an unmatched query returns 503 no_fixture_match instead of an empty array
• An array query is joined with spaces for matching

Unit Test: Rerank Fixture

const mock = new LLMock();
mock.onRerank("machine learning", [
  { index: 0, relevance_score: 0.99 },
  { index: 2, relevance_score: 0.85 },
]);
await mock.start();

const res = await fetch(`${mock.url}/v2/rerank`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "machine learning basics" }),
});

const body = await res.json();
expect(body.results).toHaveLength(2);
expect(body.results[0].relevance_score).toBe(0.99);

Response Format

The response follows the Cohere rerank v2 shape — each result carries only index and relevance_score:

{
  "id": "rerank-...",
  "results": [
    { "index": 0, "relevance_score": 0.99 },
    { "index": 2, "relevance_score": 0.85 }
  ],
  "meta": { "billed_units": { "search_units": 0 } }
}

Validation

• Malformed JSON bodies are rejected with 400
• A query that is neither a string nor an array is rejected with 400
• A missing query matches against the empty string (usually a miss)

Journal Integration

Rerank requests are recorded in the LLMock journal with service: "rerank":

const entries = mock.getRequests();
const rerankRequests = entries.filter((e) => e.service === "rerank");