Isaacus API

Endpoints

Reranking

POST /rerankings

Score and rank documents by their relevance to queries with an Isaacus reranker.

Example

import Isaacus from 'isaacus';

const client = new Isaacus({
  apiKey: process.env['ISAACUS_API_KEY'],
});

const rerankingResponse = await client.rerankings.create({
  model: 'kanon-2-reranker',
  query: 'What are the essential elements required to establish a negligence claim?',
  texts: [
    'To form a contract, there must be an offer, acceptance, consideration, and mutual intent to be bound.',
    'Criminal cases involve a completely different standard, requiring proof beyond a reasonable doubt.',
    'In a negligence claim, the plaintiff must prove duty, breach, causation, and damages.',
    'Negligence in tort law requires establishing a duty of care that the defendant owed to the plaintiff.',
    'The concept of negligence is central to tort law, with courts assessing whether a breach of duty caused harm.',
  ],
});

console.log(rerankingResponse.results);

Authorizations

Authorization
string header required

An Isaacus-issued API key passed as a bearer token via the Authorization header in the format Authorization: Bearer YOUR_API_KEY.

Request body

query
string required

The query to evaluate the relevance of the texts to.

The query must contain at least one non-whitespace character.

Unlike the texts being reranked, the query cannot be so long that it exceeds the maximum input length of the reranker.

texts
string[] required

The texts to rerank.

There must be at least one text.

Each text must contain at least one non-whitespace character.

top_n

The number of highest scoring results to return.

If null, which is the default, all results will be returned.

is_iql
boolean

Whether the query should be interpreted as an Isaacus Query Language (IQL) query, which is not the case by default.

If you allow untrusted users to construct their own queries, think carefully before enabling IQL since queries can be crafted to consume an excessively large amount of tokens.

scoring_method
enum

The method to use for producing an overall relevance score for a text that exceeds the model's local context window and has, therefore, been split into multiple chunks.

auto is the default scoring method and is recommended for most use cases. Currently, it is equivalent to chunk_max. In the future, it will automatically select the best method based on the model and inputs.

chunk_max uses the highest relevance score of all of a text's chunks.

chunk_avg averages the relevance scores of all of a text's chunks.

chunk_min uses the lowest relevance score of all of a text's chunks.

chunking_options

Settings for how texts should be chunked into smaller segments by semchunk before reranking.

If null, the texts will not be chunked and will instead be truncated to the maximum input length of the reranker less overhead if found to exceed that limit.

Chunking is enabled by default.

size

The maximum number of tokens allowed in a chunk.

If null, the maximum input length of the model will be used less overhead.

overlap_ratio

The proportion of the chunk size by which chunks should overlap.

The ratio must be less than 1.

If null, no overlapping will occur unless overlap_tokens is set.

overlap_ratio and overlap_tokens cannot both be set.

overlap_tokens

The number of tokens by which chunks should overlap.

If null, no overlapping will occur unless overlap_ratio is set.

overlap_tokens and overlap_ratio cannot both be set.

Response

Reranking response

200 
{
  "results": [
    {
      "index": 2,
      "score": 0.7727372261985272
    },
    {
      "index": 3,
      "score": 0.7332913519466231
    },
    {
      "index": 4,
      "score": 0.32399687407609323
    },
    {
      "index": 1,
      "score": 0.09480246485705024
    },
    {
      "index": 0,
      "score": 0.06929198572432578
    }
  ],
  "usage": {
    "input_tokens": 170
  }
}
results
object[] required

The texts reranked by relevance to the query, in order from highest to lowest relevance score.

index
integer required

The index of the text in the input array of texts, starting from 0 (and, therefore, ending at the number of texts minus 1).

score
number required

A score between 0 and 1, inclusive, representing the relevance of the text to the query.

usage
object required

Statistics about the usage of resources in the process of reranking the texts.

input_tokens
integer required

The number of tokens inputted to the model.

See making requests for authentication, SDK usage, and errors.