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

| Library | License(s) | |---------|-----| | WS | MIT License | | Axios | MIT License | | Typescript-Starter | MIT License |

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.

| Parameter | Description | | --------------------- | -------------------------------------------------------- | | fileFormat | Format of the file to analyze. The following file formats are currently available: PDF, DOCX, DOC, HTML, PDF, RAW. | | data | Contains the data of the file to analyze, in this case Base64 encoded | | criteriaList (optional) | Collection of legal properties (criteria) to find with default ApiOptions.| | tasks (optional) | Collection of legal properties to find with specific ApiOptions | ocrMode (optional) | Decides which OCR Mode (Enum) will be used NEVER, FORCED, or AUTOMATIC | | nerMode(optional) | Defines with which Method the Entity Recognition should be performed PERFORMANCE, QUALITY, or BOTH | | criteriaWithOptions(optional) | Collection of legal properties (criteria) to find with additional options.| | language (optional) | Language of the document to be analyzed. If nothing is given it defaults to German. | | smartSearchTasks(optional) | Collection of SmartSearchTasks to find in the document. |

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)

| Criteria | Description | Languages | | --------------------- |---------------------- |---------------- | | DATA_DELETION_AND_RETURN | Criterion summarizing all clauses regarding deletion and return of private/personal or classified/sensitive data. | German / English | | DATA_TRANSFER_TO_THIRD_PARTIES |Criterion summarizing all clauses containing regulations regarding data forwarding to third parties. | German / English| | DATA_TRANSFER_TO_OTHERWISE_AUTHORIZED_THIRD_PARTIES |Criterion summarizing all clauses containing regulations regarding data forwarding to partner companies. | German / English| | DATA_TRANSFER_TO_PARTNER_COMPANY | Criterion summarizing all clauses containing regulations regarding data forwarding to partner companies. | German / English |
| DATA_TRANSFER_FOR_AGGREED_PURPOSE |Criterion summarizing all clauses that require forwarded data to serve a mutually aggreed purpose. | German / English | | DEADLINES | Criterion summarizing all clauses containing deadlines of all kinds. | German / English | FINES | Criterion summarizing clauses containing fines.| German / English | FORCE_MAJEURE | Criterion summarizing clauses which apply in the case of influences which cannot be controlled. | German / English | DEFINITION_OF_INFORMATION | Criterion summarizing clauses which define which data and information is considered confidential and which is not. | German / English | CHANGE_OF_CONTROL| Criterion summarizing clauses in case the management changes, the contracting party is bought by a third party, etc. | German / English | TERMS | Criterion summarizing clauses containing terms of all kinds | German / English | LOOPHOLES | Criterion summarizing all clauses containing regulations which apply in case of a found loophole or if the legal document becomes partially invalid. | German / English | ORDINARIY_JURISDICTION | Criterion summarizing clauses which allow or restrict the jurisdiction to ordinary (non-arbitration) courts. | German / English | PREAMBLE | Criterion summarizing clauses containing the objective of the legal document. | German / English | ARBITRATION | Criterion summarizing clauses which allow or restrict litigations to be carried out in arbitration courts. | German/ English | WRITTEN_FORM_REQUIREMENTS | Criterion summarizing clauses which require changes of the legal document to be noted and approved in written form. | German / English | CONTRACT_CANCELLATION | Criterion summarizing clauses which regulate the document's cancellation. | German / English | CONTRACTUAL_CLAIMS_BREACH_OF_CONTRACT | Criterion summarizing clauses which define how a breach of contract can be punished besides statutory penalties. | German / English | PERIOD_OF_NOTICE | Criterion summarizing all deadlines regarding contract termination/cancellation. | German / English | REVOCATION_INFORMATION | Clauses regarding the revocation of the legal document. | German / English | DELIVERY_TERMS | Clauses regarding the terms and conditions of a delivery. | German / English | EXCLUSION_OF_IPR_AND_UN_SALES_LAW | Clauses regarding the exclusion of IPR and UN sales law. | German / English | RENTAL_COLLATERAL | Clauses regarding Rental Collateral in any form. | German / English | EXTENSION_OPTION | Clauses regarding Extension Options. | German / 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} `);
})

| Option | Description | Enabled by default | | --------------------- |-----------------| -------------| | RELEVANT_CLAUSES| If enabled this option requests the AI to include clauses which are classified as relevant by the Juracus AI.| true | | IRRELEVANT_CLAUSES |If enabled this option requests the AI to include clauses which are classified as irrelevant by the Juracus AI. | false |
| METADATA | If enabled this option requests the AI to include additional meta information of the given Criteria in the response. | true

Available CriterionFilters

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

| CriterionFilter | Description | CriterionFilterOperator | Value Class | | --------------------- |--------|---------| -------------| | DATES| Filters based on a given SparseDate for example 01.01.2021.| LT,LEQ,EQ,GEQ,GT| SparseDate (day,month,year) | | AMOUNTS_OF_MONEY | Filters based on a given amount / price. | LT,LEQ,EQ,GEQ,GT| AmountOfMoney(amount,currency) | | PERIODS_OF_TIME | Filters based on a given Period of Time.| LT,LEQ,EQ,GEQ,GT| PeriodOfTime(period,unit) | INCOTERMS | Filters based on a given InCoTerms.|EQ,NEQ| InCoTerms(Array of InCoterm)

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.

| DocumentMetdatakey | Result Class | asMetadataEntity | | --------------------- | -------------------------------------------------------- | ----------------| |PHONE_NUMBERS | PhoneNumber| MetaDataEntity | |EMAILS | Email| MetaDataEntity | |CONTRACT_TYPE | Enum (ContractType)| MetaDataEntity | |DATES | SparseDate| MetaDataEntity | |AMOUNTS_OF_MONEY | AmountOfMoney| MetaDataEntity | |NAMED_ENTITIES | NamedEntity| MetaDataEntity | |WEB_LINKS | Weblink| MetaDataEntity | |INCOTERMS | IncoTerms | MetaDataEntity |

| CriterionMetadatakey | Result Class | asMetadataEntity | | --------------------- | -------------------------------------------------------- | ----------------| |DATES | SparseDate| MetaDataEntity | |AMOUNTS_OF_MONEY | AmountOfMoney| MetaDataEntity | |LEGAL_REFERENCES | LegalReference| MetaDataEntity | |PERIODS_OF_TIME | PeriodOfTime| MetaDataEntity | |NAMED_ENTITIES | NamedEntity| MetaDataEntity | |INCOTERMS | IncoTerms | MetaDataEntity |

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

| Parameter | Description | | --------------------- | -------------------------------------------------------- | |SmartSearchType.EQUALITY | Can be used to find text passages which are equal to a provided text. You will not have to worry about words that are broken over multiple lines, like “... bro-\n ken ...” as linebreaks \n preceded by -, will be accepted as well, even if you did not specify them in your search task. | |SmartSearchType.REGULAR_EXPRESSION | Can be used to define a regular expression which will return all text passages which match the expression. Again you will not have to worry about line breaks and words broken over multiple lines.| |SmartSearchType.SIMILARITY| Searches for text passages based on their string similarity to the underlying value. | |SmartSearchType.SEMANTIC_SIMILARITY| Searches for text passages based on their semantic similarity to the underlying value. |

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:

|Parameter|Description| |---|---| |PdfGeneratorResultType.BASE64|Will create the pdf file and return it as a base64 encoded String.| |PdfGeneratorResultType.BLOB|Creates the pdf file and returns it as a Blob.| |PdfGeneratorResultType.BUFFER|Creates the pdf file and returns it as a Buffer.| |PdfGeneratorResultType.PDFKIT_DOCUMENT|Creates the pdf file and returns it as a PdfKit.Document that allows for processing of the file with the PDFKit node package. | |PdfGeneratorResultType.DOWNLOAD|Works only in the browser. Will create the pdf file and download it. You can use the pdfDownloadFilename attribute of the pdfOptions to specify the name of the file that will be downloaded. | |PdfGeneratorResultType.DATA_URL|Works only in the browser. Returns a Promise that eventually resolves to the file URL once the creation of pdf is finished.| |PdfGeneratorResultType.FILE_OPEN|Works only in the browser. Will create the pdf file and open it in a new Tab.| |PdfGeneratorResultType.PRINT|Works only in the browser. Will create the pdf file and open it in a new Tab in print preview mode.|

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;
};

|Property|Description| |---|---| |PdfGenerator.language| Optional. Changes the language of the report. Currently, German and English reports are available. The default value is Language.german.| |PdfGeneratorOptions.pdfTitle|Optional. Changes the header of the report to the specified value. | |PdfGeneratorOptions.originalFilename|Optional. Can be used to add a custom subheader, e.g. to include the name of the analysed file in the report. | |PdfGeneratorOptions.analysisResultGroups|Optional. Allows to group the results of multiple criteria together into common paragraphs. For further information about the usage, see the section 'AnalysisResultGroups' below.| |PdfGeneratorOptions.pdfDownloadFilename|Optional. Can be used to customize name of the downloaded pdf file, if the resultType is set to DOWNLOAD. |

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)
  })
}

| Name | Type | Description | |------|------| -------------| | ID | string | Unique identifier for the error | | Name | string | Short name or description | | Description | string | Detailed description | | Error Code | int | Code for this type of error | | Source | ApiStage | Where the error occurred |

License

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

Contact

Having trouble or suggestions?

| Name | LinkedIn | E-Mail | Field | |------|----------|--------|----------| | Sven Wensing | https://www.linkedin.com/in/sven-wensing-523596176/ | [email protected] | Backend | | Till Werner | https://www.linkedin.com/in/till-w-0a0a24200/ | [email protected] | Artificial Intelligence | | David Schonebeck | https://www.linkedin.com/in/david-schonebeck/ | [email protected] | Sales & Pricing |