Follow this short guide to get up and running with the Isaacus API by classifying your first legal document with the Kanon Universal Classifier, our flagship universal classification model.

If you’re looking to perform tasks other than universal classification with the Isaacus API (e.g., reranking), follow the first two steps of this guide to set up your account and API client, and then check out the capabilities section of our documentation for information on how to use the API for those tasks.

​
1. Set up your account

Head to the Isaacus Platform to create a new account.

Once signed up, add a payment method to claim your free credits.

After adding a payment method, create a new API key.

Make sure to keep your API key safe. You won’t be able to see it again after you create it. But don’t worry, you can always generate a new one.

​
2. Install the Isaacus API client

Now that your account is set up, install our Python or server-side JavaScript/TypeScript API client (or check out our API reference if you’re not using either of those languages).

pip install isaacus

​
3. Classify a document

With our API client installed, let’s classify our first legal document.

To start, you need to initialize the client with your API key. You can do this by setting the ISAACUS_API_KEY environment variable or by passing it directly, which is what we’re doing in this example.

from isaacus import Isaacus

client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE")

Next, let’s grab a legal document to classify. For this example, we’ll use Github’s terms of service.

tos = client.get(path="https://examples.isaacus.com/github-tos.md", cast_to=str)

We’re going to classify the terms of service using the Kanon Universal Classifier, the world’s most accurate universal legal AI classifier.

What is a universal classifier? A universal classifier (also known as a zero-shot classifier) is a system that classifies whether a statement expressed about a document (e.g., “This is a confidentiality clause.”) is supported by that document. Unlike traditional classifiers, universal classifiers don’t require training data to classify a document.

Universal classifiers can be used for a broad range of information retrieval and extraction tasks, from pulling out particular types of clauses from contracts all the way to scoring the relevance of legal documents to search queries.

Right now, we’re interested in identifying confidentiality clauses in the terms of service.

To do that, we’ll use the query This is a confidentiality clause..

response = client.classifications.universal.create(
    model="kanon-universal-classifier",
    query="This is a confidentiality clause.",
    texts=[tos],
)

Since we only passed the classifer a single document, let’s unpack the first classification result, accessible at response.classifications[0], in addition to our usage statistics.

classification = response.classifications[0]
chunks = classification.chunks
score = classification.score

usage = response.usage

Because legal documents can often be quite long, the classifier will automatically break them up into chunks for you (though you can disable this by setting the chunking_options parameter to null). Typically, these chunks will correspond to individual clauses in the document.

Chunks are stored in the classification.chunks attribute and come with their own text, score, start, and end attributes, with start and end representing the start and end character indices of the chunk in the original text.

classification.score contains the overall classification score of the document. This score is currently set to the largest score of any chunk.

Scores range from 0.00.0 to 1.01.0, with a score over 0.50.5 indicating a positive classification. You can think of the scores as the classifier’s estimation of the likelihood that the query is supported by the document.

response.usage contains statistics about the usage of resources in the process of classifying the document. response.usage.input_tokens will give you the number of tokens inputted into the classifier, which you can cross-reference with our pricing to estimate the cost of classifying the document (excluding applicable taxes).

When passing multiple documents to the classifier, you can access each document’s classification via the response.classifications array, which is sorted from highest to lowest classification score. You can use the classification.index attribute to recover the index of documents in the original input array.

Now, let’s print out the results.

from isaacus.types.classifications.universal_classification import Classification

def print_classification(classification: Classification) -> None:
    chunks = classification.chunks
    score = classification.score
    
    # Print the overall classification score.
    print(
        f'Overall classification score: {score * 100:.2f}%',
        end='\n\n',
    )

    # Filter out chunks with a score below 50%.
    chunks = filter(lambda c: c.score > 0.5, chunks)

    # Print the chunks.
    if chunks:
        print('#' * 18, 'Snippets with a positive classification', '#' * 18, end='\n')
    
    for chunk in chunks:
        chunk_text = chunk.text
        chunk_score = chunk.score
        start, end = chunk.start, chunk.end

        # Print the chunk in the format:
        # ---------- start char = {start} | end char = {end} | score = {chunk_score * 100}% ----------
        # {chunk_text}

        print(
            '-' * 10,
            f'start char = {start:,} | end char = {end:,} | score = {chunk_score:.2%}',
            '-' * 10,
            '\n',
            chunk_text,
            end='\n\n',
        )

print_classification(classification)

The output should look something like this:

Likelihood of there being a confidentiality clause: 98.28%

---------- start char = 19,966 | end char = 22,311 | score = 98.28% ---------- 
 ### 2. Confidentiality of Private Repositories

GitHub considers the contents of private repositories to be confidential to...

And that’s it! You’ve just classified a legal document using the Kanon Universal Classifier.

​
4. Advanced: write your own queries

In the previous example, we used a simple, plain English query to classify confidentiality clauses.

That worked fine for our purposes, but what if you needed to absolutely maximize the accuracy of your classifications?

One way is to construct a test dataset and then repeatedly evaluate differently worded queries on that dataset until you find the best one. This is a time-consuming process, but it can yield excellent results.

The good news is that, for a whole bunch of legal classification problems, we’ve already done that work for you.

Each of our models comes with a set of pre-optimized queries that you can use to classify legal documents with high accuracy and minimal effort.

These queries can be accessed using the Isaacus Query Language or IQL.

IQL is the world’s first legal AI query language — that is, a query language designed specifically for analyzing legal documents with AI systems.

Any statement you can think of, including the one we used earlier, qualifies as an IQL statement. You just need to wrap them in curly brackets like so: {This is a confidentiality clause.}.

To invoke a pre-optimized query template, we can express our query in the format {IS <template name>}. You can find a list of available templates here.

For example, we could’ve invoked the {IS confidentiality clause} template to classify confidentiality clauses in the Github terms of service instead of trying to write our own query from scratch. Let’s do that now.

response = client.classifications.universal.create(
    model="kanon-universal-classifier",
    query="{IS confidentiality clause}",
    texts=[tos],
)
classification = response.classifications[0]

print_classification(classification)

This time, our most “confidentiality clause”-like chunks have shuffled around a bit, with the top chunk now being:

---------- start char = 25,715 | end char = 27,954 | score = 79.47% ---------- 
... **Confidentiality Obligations.** You agree that any non-public Beta Preview
information we give you, such as information about a private Beta Preview, will
be considered GitHub’s confidential information (collectively, “Confidential
Information”), ...

That certainly sounds like a confidentiality clause.

Our templates cover more than just confidentiality clauses, however. We’ve got templates for pulling out indemnities, force majeure clauses, termination clauses — even unilateral clauses, clauses that benefit or obligate only a single party, often a key indicator of a contract’s one-sidedness and potential for unfairness.

There are also templates that allow you to plug in your own descriptions of what you’re looking for via the format {IS <template name> "<template argument>"}.

For example, if you wanted to identify clauses that specifically obligate the party referred to as “you” in the document, you could use the {IS clause obligation "<party name>"} template like so: {IS clause obligating "You"}.

response = client.classifications.universal.create(
    model="kanon-universal-classifier",
    query='{IS clause obligating "You"}',
    texts=[tos],
)
classification = response.classifications[0]

print_classification(classification)

Now, our top chunk is:

---------- start char = 13,300 | end char = 15,403 | score = 78.25% ---------- 
Your use of the Website and Service must not violate any applicable laws,
including copyright or trademark laws, export control or sanctions laws, or
other laws in your jurisdiction. You are responsible for making sure that your
use of the Service is in compliance with laws and any applicable regulations.

If there isn’t a template available for what you’re looking for, you can always try one of our more general templates like {IS clause called "<clause name>"} (e.g., {IS clause called "confidentiality"}) or {IS clause that "<clause description>"} (e.g., {IS clause that "imposes a duty of confidentiality"}). We don’t yet have very many templates for non-contractual classifications, however, our models have been trained on an equal mix of contracts, cases and legislation, so you can always write your own queries for anything not covered by an existing template.

In addition to allowing you to invoke query templates, IQL also enables you to string statements together using logical operators like AND, OR, and NOT, as well as the > and < comparison operators and the + operator for averaging.

For example, if we wanted to identify confidentiality clauses that apply to you and you alone, we could use this query: {IS confidentiality clause} AND {IS clause obligating "You"} AND {IS unilateral clause}.

response = client.classifications.universal.create(
    model="kanon-universal-classifier",
    query='{IS confidentiality clause} AND {IS clause obligating "You"} AND {IS unilateral clause}',
    texts=[tos],
)
classification = response.classifications[0]

print_classification(classification)

That query pulls up the top chunk from before, which is indeed a unilateral confidentiality clause.

Congratulations on becoming an IQL pro!

​
5. Next steps

Beyond the examples we’ve shared here, there’s a lot more that you can do with the Isaacus API.

To learn how to take full advantage of the API, you can check out our:

  1. Capabilities section, which covers the full range of tasks the Isaacus API supports, including universal classification and reranking.
  2. API reference, which documents how to interface with our API and the endpoints and parameters that are available.
  3. IQL documentation, which explains how IQL works and how you can use it to improve the accuracy of your classifications.
  4. Pricing section, which shows just how affordable our API is.

If you’re ever unsure about how to use the Isaacus API or if you have any other questions, we also encourage you to reach out to us. We’re always happy to help.