legal-analytics-sdk v0.7.4

About the Project

The Legal Analytics API provides access to Legal Analytic’s Artificial Intelligence. It can be used to extract various contents from legal documents without worrying about deep learning natural language processing models.

Built with

Getting Started

To install the SDK add it to your project dependencies like this

NPM

npm install legal-analytics-sdk

YARN

yarn add legal-analytics-sdk

Basic Usage

To use the Legal-Analytics-Client you can access the instance with your custom API-Key. Furthermore you can define which ApiEndpoint you want to communicate with. The endpoints ApiEndpoint.STABLE for the productive environment and ApiEndpoint.NIGHLY for the latest yet unstable build are available.

import { getLegalAnalyticsClientInstance } from 'legal-analytics-sdk';
import { ApiEndpoint } from "legal-analytics-sdk/build/main/lib/models/ApiEndpoint";

const client = getLegalAnalyticsClientInstance("your-api-key", ApiEndpoint.STABLE);

Afterwards, you can connect to the API and you can start the analysis:

// file format to process
const fileFormat = DataFormat.PDF; // DOC, DOCX, HTML, PDF, RAW

const data = "encodedBase64String" // Blob or Buffer is also possible

// choose the legal properties to analyze
const criteriaList = [Criterion.DATA_DELETION_AND_RETURN];

// create builder
let builder = new Builder(data,fileFormat);

// configure builder
builder
.setCriteria(criteriaList)

// pass a request to the API
const response = await client.analyzeAsync(builder);

// get clauses for the Criterion
const clauses = result.getClauses(Criterion.DATA_DELETION_AND_RETURN);

// Iterate over all found text paragraphs (clauses)
clauses.forEach((clause: Clause) => {
  // Print the found paragraphs
  console.log(clause.clauseText);
})

To create the builder object, both data and the data format must be passed. Then the other optional parameters can be passed.

Instead of passing base64 encoded strings you can always pass a Buffer object as an alternative. When calling analyzeAsync a Promise object is returned containing the ApiResponse. You can access the text paragraphs our AI detected using the getClauses(Criterion) method:

Available Criteria

In the current version of the SDK, the following criteria are supported. To get the name of a Criteria you can use the getName() function.

Criterion.TERMS.getName(Language.english)

Available ApiOptions

Additionally, you can define ApiOptions in your analysis request which will change the returned results. For example, enabling the option ApiOption.IRRELEVANT_CLAUSES for a given Criterion will provide all irrelevant clauses associated with this criteria. You can enable ApiOptions as follows:

// create builder
let builder = new Builder(data,fileFormat);

let tasks = new Map();

tasks.set(Criterion.TERMS, new ApiOptions([ApiOption.IRRELEVANT_CLAUSES])

builder.setTasks(tasks)

// pass a request to the API
const response = client.analyzeAsync(builder);

//get clauses for the Criterion
const clauses = result.getClauses(Criterion.TERMS);

// Iterate over all found clauses and print them together with the confidence value
clauses.forEach((clause: Clause) => {
  console.log(`Confidence :  ${clause.confidence} `);
  console.log(`Clause Text:  ${clause.clauseText} `);
})

Available CriterionFilters

If you want to filter the Criterion you can use the CriterionFilter class.

Example

Lets say you want to only get Terms which are longer then 6 Month. And you also want to know if DELIVERY_TERMS with the IncoTerm CFR are written down in the Contract.

let incotermArray = [InCoTerm.CFR];

let tasks = new Map();

tasks.set(Criterion.TERMS, new ApiOptions([],[new CriterionFilter(CriterionFilterType.DATES, CriterionFilterOperator.LT, new SparseDate(20, 6, 2021))], new CriterionWithOptions(Criterion.PERIOD_OF_NOTICE, [ApiOption.METADATA]))

tasks.set(Criterion.DELIVERY_TERMS, new ApiOptions([],[new CriterionFilter(CriterionFilterType.INCOTERMS, CriterionFilterOperator.EQ, new InCoTerms(incotermArray))]))

let builder = new Builder(data,fileFormat);

// configure builder
builder
.setTasks(tasks)
.setOcrMode(OcrMode.FORCED)

// pass a request to the API
const response = await client.analyzeAsync(builder);

//get clauses for the Criterion
const termClauses = result.getClauses(Criterion.TERMS);

// Iterate over all found clauses and print them together with the confidence value
termClauses.forEach((clause: Clause) => {
  console.log(`Confidence :  ${clause.confidence} `);
  console.log(`Clause Text:  ${clause.clauseText} `);
})

const deliveryClauses = result.getClauses(Criterion.DELIVERY_TERMS);

deliveryClauses.forEach((clause: Clause) => {
  console.log(`Confidence :  ${clause.confidence} `);
  console.log(`Clause Text:  ${clause.clauseText} `);
})

In this case only clauses with a Term longer than 6(Six) months, and Delivery Clauses with the InCoTerm CFR will be returned.

Multi-Language Support

With version 0.2.3 we introduce multi-language support. This means we are extending the analysis functionality to support legal documents in English and German. You can add the language of the analyzed file to the Builder methods by adding the Language enum as an optional Parameter

 builder.setLanguage(Language.english).

Currently all criteria are available in English. This feature is considered work in progress.

Metadata

Besides finding relevant text passages for various criteria, we offer the extraction of criteria metadata. These data can be connected to the whole document (e.g. all phone numbers or e-mail addresses) or to certain criteria (e.g. the maximum amount for contractual penalties/fines). Both the Document and Criteria Metadata are always enabled by default.

The following functions of the ApiResponse are available to read the document and criteria Metadata:

getDocumentMetadata(key: ApiDocumentMetadataKey,(optional) asMetadataEntity: boolean)

This function will return an Array of Metadata associated with the document and given ApiDocumentMetadataKey. In addition, it is possible to specify the parameter asMetadataEntity, which causes all metadata types to be returned as MetaDataEntity. There you can read at which exact text position the metadata was found. If you want to get the corresponding result class-types to the ApiDocumentMetadataKey directly, you dont need to specify the asMetadataEntity parameter.

getCriterionMetadata(criterion: Criterion,key: ApiCriterionMetadataKey,(optional) asMetadataEntity)

This function will return an Array of Metadata associated with the given Criteria and ApiDocumentMetadataKey. As with getDocumentMetadata, it is also possible to return the result directly as a result class-type or as MetaDataEntity.

The different DocumentMetdatakeys / CriterionMetadatakeys and their result classes are described in detail below.

Now you can start the analysis. The ApiResponse will contain the document metadata and metadata for each analyzed criterion which can be accessed using the following method on the received response:

import { ApiResponse } from './ApiResponse';

// pass a request to the API

let builder = new Builder(data,fileFormat);

builder
.setCriteria(criteriaList)
.setTasks(tasks)

const response = await client.analyzeAsync(builder);

let documentEntities = getDocumentMetadata(ApiDocumentMetadataKey.NAMED_ENTITIES);

let termDates = getCriterionMetadata(Criterion.TERMS,ApiCriterionMetadataKey.DATES);

SmartSearch

With version 0.3.0 we introduced a new functionality, which can be used to define your own criteria without having to deal with large amounts of data or complex machine learning models. We offer the following three ways to find text passages which are most relevant to your requirements

You can create multiple SmartSearchTasks and add them to the analyze call as an optional Parameter.

let taskSimilarity = new SmartSearchTask("sst-similar",SmartSearchType.SIMILARITY,"Sentence here",0.8);

let taskEquality = new SmartSearchTask("sst-equality",SmartSearchType.EQUALITY,"Word or Sentence here");

let taskRegex = new SmartSearchTask("sst-regex",SmartSearchType.REGULAR_EXPRESSION,"Regex here");

let smartSearchTasks:SmartSearchTask[] = [];

smartSearchTasks.push(taskSimilarity, taskEquality, taskRegex);

let builder = new Builder(data,fileFormat);

builder
.setSmartSearchTasks(smartSearchTasks)


const response = await client.analyzeAsync(builder);

After the query has been answered, the results of the SmartSearchTasks can be accessed as follows.

response.getSmartSearchResult(ssTaskEquality.id);
response.getSmartSearchResult(ssTaskEquality.id)
response.getSmartSearchResult(ssTaskRegex.id);

PDF Report

You can generate a PDF report that contains the results of the analysis. The report contains a paragraph for each Criterion that was used in the analysis. If the AI found results for a Criterion the corresponding text passages will occur in the report. If any SmartSearchTasks were specified, the corresponding SmartSearchResults will occur at the bottom of the report.

You can specify a result format and further options to customize the result pdf file.

ApiResponse.getAnalysisPdf(apiResponse:ApiResponse, PdfGeneratorResultType.FILE_OPEN, language:Language, pdfOptions?:PdfGeneratorOptions);

ResultType

The resultType parameter allows you to specify, in which format the generated pdf file should be returned. The following result types are currently available:

Further Configuration

Additionally you can supply further customization parameters with the pdfOptions parameter. A PdfGeneratorOptions object looks as follows

export type PdfGeneratorOptions = {
  language?: Language;
  pdfTitle?: string;
  originalFilename?: string;
  analysisResultGroups?: AnalysisResultGroup[];
  pdfDownloadFilename?: string;
};

AnalysisResultGroups

An AnalysisResultGroup can be used to group the analysis results of multiple criteria into one paragraph in the pdf report. The following example shows how an AnalysisResultGroup is created.

const analysisResultGroup: AnalysisResultGroup = new AnalysisResultGroup(
  apiResponse: ApiResponse,
  criteria: Criterion[],
  aliasNaming: String
);

You can specify which of the results for which criteria should be grouped together. The aliasNaming property allows you to specify the common name of this group. The results will appear under a paragraph with this name in the pdf report.

If you use AnalysisResultGroups for your pdf report, keep in mind that only results for criteria will be included that are part of the array of AnalysisResultGroups. For each result that should not be grouped, you must still create an AnalysisResultGroup that only contains this Criterion for its results to appear in the pdf report.

Troubleshooting

As the API and SDK are currently in development, there is always the chance that something goes wrong. Therefore, each ApiResponse contains a List of ApiError objects. You can access all errors using the errors property on your ApiResponse:

// did any errors occur?
if(response.hasErrors()) {
  // print all errors
  response.errors.forEach((error: ApiError) => {
    console.log(error.description)
  })
}

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Having trouble or suggestions?