Connecting the client to a platform

from averbis import Client
# Use existing API Token
client = Client('http://localhost:8400/health-discovery', api_token='YOUR_API_TOKEN')
# or generate new API Token based on your credentials (invalidates old API Token)
client = Client('http://localhost:8400/health-discovery', username = 'YOUR_USERNAME', password = 'YOUR_PASSWORD')

Connecting to a pipeline and assure that it is started

project = client.get_project('YOUR_PROJECT_NAME')
pipeline = project.get_pipeline('YOUR_PIPELINE_NAME')
pipeline.ensure_started()

Analysing a string

document = 'This is the string we want to analyse.'
annotations = pipeline.analyse_text(document, language='en')
for annotation in annotations:
    print(annotation)

Analysing a text file

with open('/path/to/text_file.txt', 'rb') as document:
    annotations = pipeline.analyse_text(document, language='en')
    for annotation in annotations:
        print(annotation)

Restricting returned annotation types

annotations = pipeline.analyse_text(document, language='en',
    annotation_types='*Diagnosis') # will return only annotations that end with 'Diagnosis'

Upload documents, process them using a pipeline, and export results

In contrast to the simple text analysis endpoint above, one can also upload the documents into the product and create an analysis process there using experimental endpoints (may change soon). This has some advantages, namely that the results can be inspected in our product using the AnnotationViewer, and that the same document collection could be re-processed several times.

document_collection = project.create_document_collection("COLLECTION_NAME")

file_path = "path/to/text/file.txt"
with open(file_path, "r", encoding="UTF-8") as input_io:
    document_collection.import_documents(input_io)
print(f"Number of documents: {document_collection.get_number_of_documents()}")

pipeline = project.get_pipeline("MY_PIPELINE_NAME")

# Using experimental endpoints to run the analysis and monitor the process state
process = document_collection.create_and_run_process(process_name="MY_PROCESS", pipeline=pipeline)
while process.get_process_state().state == "PROCESSING":
    time.sleep(1)

results = process.export_text_analysis()
print(results)

Pear Management

A PEAR (Processing Engine ARchive) file is the UIMA standard packaging format for UIMA components like analysis engines (annotators) or CAS consumers. We provdie some (experimental - may change soon) endpoints to upload, delete and list PEARs.

project.list_pears()
pear = project.install_pear("path/to/mypear.pear")
print(pear.get_default_configuration())
pear.delete()

Connection profiles

To avoid storing API keys in the Python scripts or constantly re-generating them, it is possible to store the keys for commonly used servers in a configuration file. This file must be called client-settings.json and it must be located either in the working directory of the script or in the user’s home folder in .averbis/client-settings.json.

Each profile has four settings:

• url: the base URL of the server application

• api-token: the API token

• verify-ssl: the path to a PEM file used to validate the server certificate if SSL is used

• timeout: An optional timeout parameter (in seconds)

Default settings which should be applied to all profiles can be stored in the special profile * (star).

{
  "profiles": {
    "*": {
      "verify-ssl": "caRoot.pem"
    },
    "localhost-hd": {
      "url": "https://localhost:8080/health-discovery",
      "api-token": "dummy-token"
    },
    "localhost-id": {
      "url": "https://localhost:8080/information-discovery",
      "api-token": "dummy-token",
      "verify-ssl": "id.pem"
    }
  }
}

An existing profile can then be loaded with

from averbis import Client
client = Client("localhost-id")