Skip to main content
POST
/
enrichments
Python
import os
from isaacus import Isaacus

client = Isaacus(
    api_key=os.environ.get("ISAACUS_API_KEY"),  # This is the default and can be omitted
)
enrichment_response = client.enrichments.create(
    model="kanon-2-enricher",
    texts=["1.5 You (the \"User\") agree to be bound by these Terms."],
)
print(enrichment_response.results)
{
  "results": [
    {
      "index": 0,
      "document": {
        "version": "ilgs@1",
        "title": null,
        "subtitle": null,
        "type": "other",
        "jurisdiction": "US-FED",
        "segments": [
          {
            "id": "seg:0",
            "kind": "unit",
            "type": "paragraph",
            "category": "annotation",
            "type_name": null,
            "code": {
              "start": 0,
              "end": 4
            },
            "title": null,
            "parent": null,
            "span": {
              "start": 0,
              "end": 317
            }
          }
        ],
        "crossreferences": [],
        "locations": [
          {
            "id": "loc:0",
            "name": {
              "start": 308,
              "end": 315
            },
            "type": "country",
            "parent": null,
            "mentions": [
              {
                "start": 308,
                "end": 315
              }
            ]
          }
        ],
        "persons": [
          {
            "id": "per:0",
            "name": {
              "start": 32,
              "end": 42
            },
            "type": "natural",
            "role": "defense_counsel",
            "parent": null,
            "residence": null,
            "mentions": [
              {
                "start": 32,
                "end": 42
              }
            ]
          },
          {
            "id": "per:1",
            "name": {
              "start": 167,
              "end": 176
            },
            "type": "natural",
            "role": "plaintiff",
            "parent": null,
            "residence": "loc:0",
            "mentions": [
              {
                "start": 167,
                "end": 176
              }
            ]
          }
        ],
        "emails": [],
        "websites": [],
        "phone_numbers": [],
        "id_numbers": [],
        "terms": [
          {
            "id": "term:0",
            "name": {
              "start": 120,
              "end": 131
            },
            "meaning": {
              "start": 88,
              "end": 113
            },
            "mentions": [
              {
                "start": 237,
                "end": 248
              }
            ]
          }
        ],
        "external_documents": [
          {
            "id": "exd:0",
            "name": {
              "start": 66,
              "end": 72
            },
            "type": "other",
            "jurisdiction": "US-FED",
            "reception": "neutral",
            "mentions": [
              {
                "start": 66,
                "end": 72
              }
            ],
            "pinpoints": [
              {
                "start": 54,
                "end": 58
              }
            ]
          },
          {
            "id": "exd:1",
            "name": {
              "start": 80,
              "end": 113
            },
            "type": "statute",
            "jurisdiction": "US-FED",
            "reception": "neutral",
            "mentions": [
              {
                "start": 80,
                "end": 113
              }
            ],
            "pinpoints": [
              {
                "start": 79,
                "end": 84
              },
              {
                "start": 219,
                "end": 229
              }
            ]
          }
        ],
        "quotes": [
          {
            "source_segment": null,
            "source_document": "exd:0",
            "source_person": "per:0",
            "amending": false,
            "span": {
              "start": 79,
              "end": 317
            }
          }
        ],
        "dates": [],
        "headings": [],
        "junk": []
      }
    }
  ],
  "usage": {
    "input_tokens": 91
  }
}

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 enrich texts with an Isaacus enrichment model.

Note that this endpoint is currently in closed beta and is subject to change or be removed without notice until its official release. To get access, apply to the Isaacus Beta Program.

​
model
string
required

The ID of the model to use for enrichment.

Allowed value: "kanon-2-enricher"
Example:

"kanon-2-enricher"

​
texts
required

A text or array of texts to be enriched, each containing at least one non-whitespace character.

No more than 8 texts can be enriched in a single request.

Example:
[
  "1.5 You (the \"User\") agree to be bound by these Terms."
]
​
overflow_strategy
null | enum<string>

The strategy for handling content exceeding the model's maximum input length.

auto currently behaves the same as drop_end, dropping excess tokens from the end of input. In the future, auto may implement more sophisticated strategies such as chunking and context-aware stitching.

drop_end drops tokens from the end of input exceeding the model's maximum input length.

null, which is the default setting, raises an error if the input exceeds the model's maximum input length.

Available options:
auto,
drop_end,
Example:

null

Response

The enriched documents alongside usage statistics.

​
results
Enrichment result · object[]
required

The input documents enriched into version 1.0.0 of the Isaacus Legal Graph Schema (IGLS).

All spans in an enriched document graph are indexed into the Unicode code point space of a source document. Access to source documents is thus required to resolve spans into text.

The start and end indices of spans are zero-based (i.e., the first Unicode code point in the document is at index 0) and half-open (i.e., the end index is exclusive).

All spans are globally laminar and well-nested similar to XML—it is impossible for any two spans to partially overlap; they can only be disjoint, adjacent, or wholly nested.

Spans of the exact same type (e.g., segments) will never be duplicated.

Spans cannot be empty and will never start or end at whitespace.

When using programming languages other than Python (which uses zero-based, half-open, Unicode code point-spaced string indexing), indices may need to be translated accordingly (for example, JavaScript slices into UTF-16 code units instead of Unicode code points).

Example:
{
  "version": "ilgs@1",
  "title": null,
  "subtitle": null,
  "type": "other",
  "jurisdiction": "US-FED",
  "segments": [
    {
      "id": "seg:0",
      "kind": "unit",
      "type": "paragraph",
      "category": "annotation",
      "type_name": null,
      "code": { "start": 0, "end": 4 },
      "title": null,
      "parent": null,
      "span": { "start": 0, "end": 317 }
    }
  ],
  "crossreferences": [],
  "locations": [
    {
      "id": "loc:0",
      "name": { "start": 308, "end": 315 },
      "type": "country",
      "parent": null,
      "mentions": [{ "start": 308, "end": 315 }]
    }
  ],
  "persons": [
    {
      "id": "per:0",
      "name": { "start": 32, "end": 42 },
      "type": "natural",
      "role": "defense_counsel",
      "parent": null,
      "residence": null,
      "mentions": [{ "start": 32, "end": 42 }]
    },
    {
      "id": "per:1",
      "name": { "start": 167, "end": 176 },
      "type": "natural",
      "role": "plaintiff",
      "parent": null,
      "residence": "loc:0",
      "mentions": [{ "start": 167, "end": 176 }]
    }
  ],
  "emails": [],
  "websites": [],
  "phone_numbers": [],
  "id_numbers": [],
  "terms": [
    {
      "id": "term:0",
      "name": { "start": 120, "end": 131 },
      "meaning": { "start": 88, "end": 113 },
      "mentions": [{ "start": 237, "end": 248 }]
    }
  ],
  "external_documents": [
    {
      "id": "exd:0",
      "name": { "start": 66, "end": 72 },
      "type": "other",
      "jurisdiction": "US-FED",
      "reception": "neutral",
      "mentions": [{ "start": 66, "end": 72 }],
      "pinpoints": [{ "start": 54, "end": 58 }]
    },
    {
      "id": "exd:1",
      "name": { "start": 80, "end": 113 },
      "type": "statute",
      "jurisdiction": "US-FED",
      "reception": "neutral",
      "mentions": [{ "start": 80, "end": 113 }],
      "pinpoints": [
        { "start": 79, "end": 84 },
        { "start": 219, "end": 229 }
      ]
    }
  ],
  "quotes": [
    {
      "source_segment": null,
      "source_document": "exd:0",
      "source_person": "per:0",
      "amending": false,
      "span": { "start": 79, "end": 317 }
    }
  ],
  "dates": [],
  "headings": [],
  "junk": []
}
​
usage
Enrichment usage · object
required

Statistics about the usage of resources in the process of enriching the input.

Example:
{ "input_tokens": 91 }