### Fetch Document Content (Python & JavaScript)

Source: https://docs.isaacus.com/quickstart

Fetches the content of a legal document from a given URL. This example uses the 'httpx' library in Python to get the text content of GitHub's terms of service. In JavaScript, the 'client.get' method is used to retrieve the content.

```python
import httpx

tos = httpx.get("https://examples.isaacus.com/github-tos.md").text
```

```javascript
const tos = await client.get("https://examples.isaacus.com/github-tos.md");
```

--------------------------------

### Install Isaacus API Client (Python & JavaScript)

Source: https://docs.isaacus.com/quickstart

Install the Isaacus API client for Python using pip, and for server-side JavaScript/TypeScript using npm. For AWS Marketplace customers using Python, the SageMaker integration should also be installed.

```bash
pip install isaacus

// If you're an AWS Marketplace customer, also install our SageMaker integration:
pip install isaacus-sagemaker
```

```bash
npm install isaacus
```

--------------------------------

### Initialize Isaacus API Client (Python & JavaScript)

Source: https://docs.isaacus.com/quickstart

Initializes the Isaacus API client using an API key. The client can be initialized by setting an environment variable or passing the key directly. Examples are provided for both Python and JavaScript, including notes on asynchronous usage and AWS Marketplace integration for Python.

```python
from isaacus import Isaacus

client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE")

# For async usage:
# from isaacus import AsyncIsaacus
# 
# aclient = AsyncIsaacus(api_key="...")

# For AWS Marketplace customers:
# from isaacus_sagemaker import IsaacusSageMakerRuntimeHTTPClient, \
#                                IsaacusSageMakerRuntimeEndpoint
# endpoints = [IsaacusSageMakerRuntimeEndpoint(name="your-endpoint-name")]
# http_client = IsaacusSageMakerRuntimeHTTPClient(endpoints=endpoints)
# client = Isaacus(http_client=http_client)
```

```javascript
import { Isaacus } from 'isaacus';

const client = new Isaacus({ apiKey: "PASTE_YOUR_API_KEY_HERE" });
```

--------------------------------

### IQL Operator Examples

Source: https://docs.isaacus.com/iql/specification

Demonstrates the usage of IQL operators like AND, OR, and NOT in query construction. These examples illustrate how to combine terms and apply logical operations.

```IQL
{confidentiality} AND {IS confidentiality clause}
```

```IQL
{ADR} OR {IS ADR clause} AND NOT {IS clause called "mediation"}
```

--------------------------------

### Initialize Client

Source: https://docs.isaacus.com/quickstart

Initialize the Isaacus API client with your API key. This can be done by setting the environment variable or passing it directly.

```APIDOC
## Initialize Client

### Description
Initialize the Isaacus API client with your API key. This can be done by setting the `ISAACUS_API_KEY` environment variable or by passing it directly during client instantiation.

### Method
Client Initialization

### Parameters
#### Request Body
- **api_key** (string) - Required - Your Isaacus API key.
- **http_client** (object) - Optional - An instance of `IsaacusSageMakerRuntimeHTTPClient` for AWS Marketplace customers.

### Request Example (Python)
```python
from isaacus import Isaacus

client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE")
```

### Request Example (JavaScript)
```javascript
import { Isaacus } from 'isaacus';

const client = new Isaacus({ apiKey: "PASTE_YOUR_API_KEY_HERE" });
```
```

--------------------------------

### Install Isaacus Python Package

Source: https://docs.isaacus.com/api-reference

Installs the Isaacus Python SDK using pip. This package simplifies interaction with the Isaacus API.

```bash
pip install isaacus

```

--------------------------------

### Install Isaacus SDKs

Source: https://docs.isaacus.com/api-reference/making-requests

Install the Isaacus Python and JavaScript/TypeScript SDKs using pip and npm respectively. These packages simplify interaction with the Isaacus API.

```bash
pip install isaacus
```

```bash
npm install isaacus
```

--------------------------------

### Error Handling Examples

Source: https://docs.isaacus.com/api-reference/classifications/universal-classification

This section provides examples of common error responses from the Isaacus API, including authentication errors, payment issues, access restrictions, and server errors.

```APIDOC
## Error Responses

### 401 Unauthorized

This error occurs when the provided API key is invalid, expired, or revoked.

**Detail**: The API key you provided does not exist or is expired or revoked.

### 402 Payment Required

This error indicates that your account is overdue and requires payment to continue using services.

**Detail**: Your account is overdue, please pay any outstanding invoices to continue using our services.

### 403 Forbidden

This error signifies that you are not allowed to access the requested resource. This can be due to lacking an active subscription.

**Detail**: You do not have an active subscription to our zero-flat fee, usage-based API plan.

### 413 Payload Too Large

This error is returned when the request payload exceeds the server's capacity.

**Detail**: The request is larger than the server is willing or able to process.

### 500 Internal Server Error

This error indicates an unexpected issue on the server side during request processing. It can also occur due to chunking timeouts with large texts or insufficient variation in whitespace.

**Detail**: An unexpected error occurred while processing the request.
**Detail**: Chunking timed out. Did you try to chunk a very large text with a very low chunk size or very little variation in levels of whitespace?

```

--------------------------------

### Enrichments API - Create

Source: https://docs.isaacus.com/api-reference/enrichments/enrichment

Example of creating an enrichment using the Isaacus client library.

```APIDOC
## POST /enrichments

### Description
This endpoint allows you to create enrichments for provided texts using a specified model.

### Method
POST

### Endpoint
/enrichments

### Parameters
#### Query Parameters
N/A

#### Request Body
- **model** (string) - Required - The name of the enrichment model to use.
- **texts** (array of strings) - Required - An array of texts to enrich.

### Request Example
```json
{
  "model": "kanon-2-enricher",
  "texts": ["1.5 You (the \"User\") agree to be bound by these Terms."]
}
```

### Response
#### Success Response (200)
- **results** (array) - An array containing the enrichment results for each input text.

#### Response Example
```json
{
  "results": [
    // ... enrichment results ...
  ]
}
```
```

--------------------------------

### Install Isaacus SDK and SageMaker Integration (Bash)

Source: https://docs.isaacus.com/integrations/amazon-sagemaker

Installs the Isaacus Python SDK and the Isaacus SageMaker Python integration package using pip. This is necessary to interact with Isaacus models deployed on Amazon SageMaker.

```bash
pip install isaacus isaacus-sagemaker
```

--------------------------------

### Authenticate Isaacus API Client (Python)

Source: https://docs.isaacus.com/api-reference

Demonstrates how to initialize the Isaacus Python client by providing an API key. The API key can be passed directly to the constructor or set as an environment variable.

```python
from isaacus import Isaacus

client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE")

```

--------------------------------

### Embed Document

Source: https://docs.isaacus.com/quickstart

Embed a legal document using the Kanon 2 Embedder. This process converts the document's text into a numerical representation (embedding) optimized for retrieval.

```APIDOC
## Embed Document

### Description
Embed a legal document using the Kanon 2 Embedder. This process converts the document's text into a numerical representation (embedding) optimized for retrieval. The `task` parameter should be set to `"retrieval/document"` for document embeddings.

### Method
POST

### Endpoint
`/embeddings/create`

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for embedding. Use `"kanon-2-embedder"`.
- **texts** (string or array of strings) - Required - The text content of the document(s) to embed.
- **task** (string) - Required - The task for the embedder. Set to `"retrieval/document"` for embedding documents.
- **dimensions** (integer) - Optional - The desired dimensionality of the embedding. Defaults to 1792.

### Request Example (Python)
```python
document_response = client.embeddings.create(
    model="kanon-2-embedder",
    texts=tos, # You can pass a single text or a list of texts here.
    task="retrieval/document",
)
```

### Request Example (JavaScript)
```javascript
const document_response = await client.embeddings.create({
    model: "kanon-2-embedder",
    texts: tos, // You can pass a single text or an array of texts here.
    task: "retrieval/document",
});
```

### Response
#### Success Response (200)
- **embeddings** (array of objects) - A list of embedding objects, each containing:
  - **embedding** (array of floats) - The numerical embedding vector.
  - **index** (integer) - The index of the text in the input list.
- **usage** (object) - Usage statistics for the request.

#### Response Example
```json
{
  "embeddings": [
    {
      "embedding": [0.123, -0.456, ...],
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "total_tokens": 100
  }
}
```
```

--------------------------------

### Classify Confidentiality Clauses using IQL Template

Source: https://docs.isaacus.com/capabilities/universal-classification

This example demonstrates how to use the pre-optimized '{IS confidentiality clause}' template in IQL to classify confidentiality clauses within a given text.

```APIDOC
## POST /classifications/universal/create

### Description
Classifies texts using a specified model and an Isaacus Query Language (IQL) query.

### Method
POST

### Endpoint
/classifications/universal/create

### Parameters
#### Request Body
- **model** (string) - Required - The name of the model to use for classification.
- **query** (string) - Required - The IQL query to use for classification. Can be a custom query or a template like '{IS confidentiality clause}'.
- **texts** (array of strings) - Required - A list of texts to classify.

### Request Example
```json
{
  "model": "kanon-universal-classifier",
  "query": "{IS confidentiality clause}",
  "texts": ["...your legal text here..."]
}
```

### Response
#### Success Response (200)
- **classifications** (array) - A list of classification results, one for each input text.
  - **score** (number) - The confidence score of the classification.
  - **start** (integer) - The starting character index of the classified text segment.
  - **end** (integer) - The ending character index of the classified text segment.

#### Response Example
```json
{
  "classifications": [
    {
      "score": 79.47,
      "start": 25715,
      "end": 27954
    }
  ]
}
```
```

--------------------------------

### Obtaining Access

Source: https://docs.isaacus.com/api-reference

To access the Isaacus API, you need an active account, an API plan subscription, no overdue invoices, and an active API key.

```APIDOC
## Obtaining Access

To access the Isaacus API, you must:
  1. have an **active, email-verified account** on the Isaacus Platform, which you can create [here](link_to_account_creation);
  2. be **subscribed** to our usage-based (no-flat-fee) API plan, which you can do [here](link_to_api_plan_subscription) (if you’ve unsubscribed from that plan, you can use that same link to resubscribe);
  3. not have any **overdue invoices** , which you can pay [here](link_to_invoice_payment);
  4. have an **active API key** , which you can generate [here](link_to_api_key_generation).

You can use your usage dashboard to monitor your API usage.
```

--------------------------------

### IQL Template with Argument

Source: https://docs.isaacus.com/iql/introduction

Shows how to use an IQL template that accepts a custom argument. This allows for more specific queries by providing a descriptive string.

```iql
{IS clause that "imposes a duty of confidence"}
```

--------------------------------

### Display Similarity Score (JavaScript)

Source: https://docs.isaacus.com/quickstart

This snippet shows how to log the similarity score of an irrelevant query to a document in JavaScript. It formats the score as a percentage with two decimal places. This is useful for visualizing the output of similarity calculations.

```javascript
console.log(`Similarity of irrelevant query to the document: ${(irrelevant_similarity * 100).toFixed(2)}`);
```

--------------------------------

### Locations Extraction

Source: https://docs.isaacus.com/api-reference/enrichments/enrichment

Extracts an array of locations identified in the document. Each location has an ID, name with start and end positions, type, parent, children, and a list of mentions with start and end positions.

```yaml
locations:
  items:
    $ref: '#/components/schemas/ILGSv1 Location'
  type: array
  description: An array of locations identified in the document.
  examples:
    - - id: loc:6
        name:
          start: 6523
          end: 6582
        type: address
        parent: loc:1
        children:
          - loc:3
          - loc:4
        mentions:
          - start: 5074
            end: 5133
          - start: 6523
            end: 6582
          - start: 8094
            end: 8153
```

--------------------------------

### Cross-references Extraction

Source: https://docs.isaacus.com/api-reference/enrichments/enrichment

Extracts an array of cross-references within a document. Each cross-reference points to a single segment or a span of segments, defined by start and end segment IDs and a span with start and end positions.

```yaml
crossreferences:
  items:
    $ref: '#/components/schemas/ILGSv1 Crossreference'
  type: array
  description: >-
    An array of cross-references within the document pointing to a
    single segment or a span of segments.
  examples:
    - - start: seg:49
        end: seg:51
        span:
          start: 2213
          end: 2229
```

--------------------------------

### Invoking an IQL Template

Source: https://docs.isaacus.com/iql/introduction

Demonstrates how to invoke a pre-defined IQL template for a common legal classification task. Templates simplify queries by abstracting complex logic.

```iql
{IS confidentiality clause}
```

--------------------------------

### ILGSv1 Crossreference Schema Definition

Source: https://docs.isaacus.com/api-reference/enrichments/enrichment

Defines the structure for a cross-reference within a document, including start and end segment identifiers and the span of segments. It ensures that start and end are required and follow specific patterns.

```yaml
ILGSv1 Crossreference:
  type: object
  required:
    - start
    - end
    - span
  title: ILGSv1 Crossreference
  description: A cross-reference within the document pointing to one or more segments.
  properties:
    start:
      type: string
      minLength: 5
      pattern: '^seg:.+'
      description: >-
        The unique identifier of the earliest segment in the span of
        segments being cross-referenced with ties broken in favor of the
        least-nested (i.e., largest) segment. If the cross-reference points
        to a single segment, `start` and `end` will be identical.
      examples:
        - seg:49
    end:
      type: string
      minLength: 5
      pattern: '^seg:.+'
      description: >-
        The unique identifier of the latest segment in the span of segments
        being cross-referenced with ties broken in favor of the least-nested
        (i.e., largest) segment. If the cross-reference points to a single
        segment, `start` and `end` will be identical.
      examples:
        - seg:51
    span:
      $ref: '#/components/schemas/ILGSv1 Span'
```

--------------------------------

### Initialize Isaacus Client and Download Document (Python)

Source: https://docs.isaacus.com/capabilities/enrichment

This snippet demonstrates how to initialize the Isaacus API client using an API key and then download a sample document from a URL. It's the first step in preparing data for the enrichment process.

```python
from isaacus import Isaacus

# Create an Isaacus API client.
client = Isaacus(
    api_key="PASTE_YOUR_API_KEY_HERE" # See https://docs.isaacus.com/quickstart
)

# Download Apple's terms of service as an example document to enrich.
doc_text = client.get("https://examples.isaacus.com/apple-tos.txt", cast_to=str)

```

--------------------------------

### Create Universal Classifier Query (Python & JavaScript)

Source: https://docs.isaacus.com/capabilities/universal-classification

This snippet demonstrates how to create a universal classifier using IQL queries in both Python and JavaScript. It shows how to specify a model, construct a query string combining multiple conditions, and process the response to extract classification details. This is useful for identifying specific types of clauses within a given text.

```python
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)
```

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

printClassification(classification);
```

--------------------------------

### Persons Extraction

Source: https://docs.isaacus.com/api-reference/enrichments/enrichment

Extracts an array of legal persons identified in the document. Each person has an ID, name with start and end positions, type, role, parent, children, residence, and mentions with start and end positions.

```yaml
persons:
  items:
    $ref: '#/components/schemas/ILGSv1 Person'
  type: array
  description: An array of legal persons identified in the document.
  examples:
    - - id: per:8
        name:
          start: 6943
          end: 6968
        type: natural
        role: defense_counsel
        parent: per:1
        children:
          - per:9
          - per:10
        residence: loc:5
        mentions:
          - start: 6943
            end: 6968
```

--------------------------------

### Generate Embeddings for Retrieval Queries (Python & JavaScript)

Source: https://docs.isaacus.com/quickstart

Generates embeddings for input texts, specifically tailored for retrieval tasks by setting the 'task' parameter to 'retrieval/query'. This allows for comparing the semantic similarity of queries to documents. Requires the 'client' object to be initialized with the appropriate model.

```python
query_responses = client.embeddings.create(
    model="kanon-2-embedder",
    texts=[
        "What are GitHub's billing policies?", # This is a relevant query.
        "What are Microsoft's billing policies?", # This is an irrelevant query.
    ],
    task="retrieval/query",
)

query_embeddings = query_responses.embeddings
relevant_query_embedding = query_embeddings[0].embedding
irrelevant_query_embedding = query_embeddings[1].embedding
```

```javascript
const query_responses = await client.embeddings.create({
    model: "kanon-2-embedder",
    texts: [
        "What are GitHub's billing policies?", // This is a relevant query.
        "What are Microsoft's billing policies?", // This is an irrelevant query.
    ],
    task: "retrieval/query",
});

const query_embeddings = query_responses.embeddings;
const relevant_query_embedding = query_embeddings[0].embedding;
const irrelevant_query_embedding = query_embeddings[1].embedding;
```

--------------------------------

### Calculate Cosine Similarity with NumPy (Python)

Source: https://docs.isaacus.com/integrations/amazon-sagemaker

This Python code calculates the cosine similarity between query embeddings and a document embedding using NumPy's dot function. It assumes embeddings are L2-normalized. Ensure NumPy is installed (`pip install numpy`).

```python
import numpy as np # NOTE You may need to run `pip install numpy`.

relevant_similarity = np.dot(relevant_query_embedding, document_embedding)
irrelevant_similarity = np.dot(irrelevant_query_embedding, document_embedding)

print(f"Similarity of relevant query to the document: {relevant_similarity * 100:.2f}")
print(f"Similarity of irrelevant query to the document: {irrelevant_similarity * 100:.2f}")
```

--------------------------------

### JavaScript Example: Creating an Enrichment

Source: https://docs.isaacus.com/api-reference/enrichments/enrichment

This JavaScript code snippet demonstrates how to use the Isaacus client library to create an enrichment. It shows the initialization of the client with an API key and the process of sending text data for enrichment, including handling the response.

```JavaScript
import Isaacus from 'isaacus';

const client = new Isaacus({
  apiKey: process.env['ISAACUS_API_KEY'], // This is the default and can be omitted
});

const enrichmentResponse = await client.enrichments.create({
  model: 'kanon-2-enricher',
  texts: ['1.5 You (the "User") agree to be bound by these Terms.'],
});

console.log(enrichmentResponse.results);
```

--------------------------------

### Create Document Embeddings (Python & JavaScript)

Source: https://docs.isaacus.com/quickstart

Creates embeddings for a given document text using the 'kanon-2-embedder' model. The 'task' parameter is set to 'retrieval/document' to optimize the embedding for retrieval. The optional 'dimensions' parameter can be used to control embedding dimensionality.

```python
document_response = client.embeddings.create(
    model="kanon-2-embedder",
    texts=tos, # You can pass a single text or a list of texts here.
    task="retrieval/document",
)
```

```javascript
const document_response = await client.embeddings.create({
    model: "kanon-2-embedder",
    texts: tos, // You can pass a single text or an array of texts here.
    task: "retrieval/document",
});
```

--------------------------------

### Authenticate Isaacus API Client (JavaScript)

Source: https://docs.isaacus.com/api-reference

Illustrates initializing the Isaacus JavaScript client with an API key. The API key can be provided directly to the client constructor or configured via environment variables.

```javascript
import { Isaacus } from "isaacus";

const client = new Isaacus({
  apiKey: "PASTE_YOUR_API_KEY_HERE",
});

```

--------------------------------

### Accessing the API

Source: https://docs.isaacus.com/api-reference

The Isaacus API is a RESTful API accessible via HTTP requests. SDKs are available for Python and JavaScript/TypeScript for easier integration.

```APIDOC
## Accessing the API

The Isaacus API is a RESTful API that can be accessed using any tool or programming language that supports HTTP requests. To make interfacing with the Isaacus API easier than using raw HTTP requests, we also offer and recommend using our Python and server-side JavaScript/TypeScript packages.

**Base URL:** `https://api.isaacus.com/v1`

**Python SDK Installation:**
```
pip install isaacus
```

**JavaScript/TypeScript SDK Installation:**
```
npm install isaacus
```
```

--------------------------------

### Using Parentheses for Grouping in IQL

Source: https://docs.isaacus.com/iql/introduction

Illustrates the use of parentheses in IQL to group statements and control the order of operations in complex queries. This ensures precise evaluation of logical expressions.

```iql
({IS clause A}) AND ({IS clause B} OR {IS clause C})
```

--------------------------------

### Extracting Headings as Spans (Schema)

Source: https://docs.isaacus.com/api-reference/enrichments/enrichment

This schema defines an array of spans within the document's text that constitute headings. Each heading is represented by its start and end indices.

```json
{
  "type": "array",
  "description": "An array of spans within the document's text constituting headings.",
  "items": {
    "$ref": "#/components/schemas/ILGSv1 Span"
  },
  "examples": [
    {
      "-": [
        {
          "start": 0,
          "end": 30
        },
        {
          "start": 116,
          "end": 133
        }
      ]
    }
  ]
}
```

--------------------------------

### Handle Access Forbidden Error (403)

Source: https://docs.isaacus.com/api-reference/rerankings/reranking

This snippet shows how to handle a 403 Access Forbidden error, which can occur due to insufficient permissions or lack of an active subscription. It includes examples for both scenarios.

```json
{
  "type": "https://docs.isaacus.com/api-reference/errors#403-access-forbidden",
  "title": "Access forbidden error",
  "status": 403,
  "detail": "You are not allowed to access this resource.",
  "instance": null
}
{
  "type": "https://docs.isaacus.com/api-reference/errors#403-access-forbidden",
  "title": "No subscription error",
  "status": 403,
  "detail": "You do not have an active subscription to our zero-flat fee, usage-based API plan.",
  "instance": null
}
```

--------------------------------

### Initialize Isaacus Client (JavaScript)

Source: https://docs.isaacus.com/api-reference/classifications/universal-classification

This snippet demonstrates how to initialize the Isaacus client using an API key. Ensure your API key is securely stored and accessed, for example, via environment variables. This client is used for interacting with the Isaacus API.

```javascript
import Isaacus from 'isaacus';


const client = new Isaacus({
  apiKey: process.env['ISAACUS_API_KEY'], // This is the default and can be omitted
});

```