POST
/
rerankings
import os
from isaacus import Isaacus

client = Isaacus(
    api_key=os.environ.get("ISAACUS_API_KEY"),  # This is the default and can be omitted
)
reranking = client.rerankings.create(
    model="kanon-universal-classifier",
    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."],
)
print(reranking.results)
{
  "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
  }
}

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.

Body

application/json

A request to rerank legal documents by their relevance to a query with an Isaacus legal AI reranker.

​
model
enum<string>
required

The ID of the model to use for reranking.

Available options:
kanon-universal-classifier,
kanon-universal-classifier-mini
Example:

"kanon-universal-classifier"

​
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.

Required string length: 1 - 5000
Example:

"What are the essential elements required to establish a negligence claim?"

​
texts
string[]
required

The texts to rerank.

There must be at least one text.

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

Example:
[
  "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."
]
​
top_n
integer | null

The number of highest scoring results to return.

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

Required range: x >= 1
Example:

null

​
is_iql
boolean
default:false

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.

Example:

false

​
scoring_method
enum<string>
default:auto

The method to use for producing an overall relevance score for a text.

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.

Available options:
auto,
chunk_max,
chunk_avg,
chunk_min
Example:

"auto"

​
chunking_options
object | null

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.

Example:
{
  "size": null,
  "overlap_ratio": null,
  "overlap_tokens": null
}

Response

200
application/json
The documents have been successfully reranked.

The reranking of texts, by relevance to a query, out of an input array of texts.

​
results
object[]
required

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

Example:
[
  { "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
object
required

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

Example:
{ "input_tokens": 170 }