Averbis-python-api

We are happy to release a new Python API version that provides parallelized support for the experimental `analyze_text_to_cas` endpoint.

What's Changed
* 87: Support parallel analyze_text_to_cas by reckart in https://github.com/averbis/averbis-python-api/pull/88
* 89: Upgrade to DKPro Cassis 0.6.0 by reckart in https://github.com/averbis/averbis-python-api/pull/90
* 91: Exporting type systems of text analysis results does not work by reckart in https://github.com/averbis/averbis-python-api/pull/92
* 89: Upgrade to DKPro Cassis 0.6.1 by reckart in https://github.com/averbis/averbis-python-api/pull/93


**Full Changelog**: https://github.com/averbis/averbis-python-api/compare/0.5.0...0.6.0

We are happy to release a new Python API version that provides support for some new experimental endpoints.

**52 Allow listing of pipelines**

python
from averbis import Client

client = Client("demo") uses client-settings.json profile
project = client.get_project("intern")
print(project.list_pipelines())

yields
`[Pipeline(name="discharge", project="intern"), Pipeline(name="deid", project="intern")]`

**85 Deleting project (proceed with great care!!)**

python
from averbis import Client

client = Client("demo") uses client-settings.json profile
project = client.get_project("dummy_project")
project.delete()


**80 : Exposing parameters for text analysis API**

We have now exposed the optional parameters `language`, `annotation_types` and `timeout` for the text analysis API endpoints. Description:
- _annotation_types_: Optional parameter indicating which types should be returned. Supports wildcard expressions, e.g. `de.averbis.types.*` returns all types with prefix "de.averbis.types". For the Health-Discovery only, passing **None** as argument will only returned the simplified types, while passing `"*"` as argument will return all annotations.
- _language_: Optional parameter setting the language of the document, e.g. "en" or "de".
- _timeout_: Optional timeout (in seconds) specifying how long the request is waiting for a server response.

**81 Resource downloads**

Allows downloading resources in the following way:

python
[pipeline/project/client].download_resources(target='/some/dir/resources.zip')
download a zip containing all resources

We are happy to release a new Python API versions that adds several new endpoints which have been released with the new major platform versions **6**.x.

**Process**
We introduce a new Process class with *experimental endpoints* to apply a pipeline to a collection of documents in the product.

python
client = Client("my_url")
project = client.get_project("my_project")
document_collection = project.get_document_collection("my_document_collection").
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()


If the pipeline or document collection has changed, the Process can also be re-applied using process.rerun()

**Pears**
We introduce some experimental endpoints to upload, delete and list [PEARs](https://uima.apache.org/doc-uima-pears.html). A PEAR (Processing Engine ARchive) file is the UIMA standard packaging format for UIMA components like analysis engines (annotators) or CAS consumers.

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


**Selected highlights**
- https://github.com/averbis/averbis-python-api/issues/62: Option to set a timeout on Client level using `Client("url", timeout=120)` or for some endpoints, e.g. `pipeline.analyse_text(text, timeout=120)`. If there is no response during the timeout (in seconds) then an error is raised.
- https://github.com/averbis/averbis-python-api/issues/60 Error messages are more informative now
- https://github.com/averbis/averbis-python-api/issues/49: Check if project exists `client.exists_project("project_name")`
- https://github.com/averbis/averbis-python-api/issues/55: New option to import pre-annotated documents (Cas files) into a document collection `document_collection.import_documents(cas)`
- https://github.com/averbis/averbis-python-api/issues/70: Options to upload/delete/list pipeline/project/client resources.
- https://github.com/averbis/averbis-python-api/issues/54: Refactor management of processes to document collection level

In this release `0.3.0`, we again extend our support to cover new API endpoints and increased the compatiblity to the new platform version 6.

**DocumentCollection**
A DocumentCollection can be used to import documents into our platform. The new API endpoints allow to list all document collections, create one, delete one, get the number of document in a collection and to insert documents (plain/text or solr/xml).
python
client = Client(url)
project = client.get_project("my_project")
collection = project.create_document_collection("my_collection")

file_path = "resources/texts/text1.txt"
with open(file_path, "r", encoding="UTF-8") as input_io:
collection.import_documents(input_io)
print(f"Number of documents: {collection.get_number_of_documents()}")
collection.delete()


**Deleting Pipeline**
We introduce a new *experimental* (may change soon) endpoint to delete an existing pipeline.
python
client = Client(url)
pipeline = client.get_project("my_project").get_pipeline("my_pipeline")
pipeline.delete()


**Exporting text analysis**
We introduce a new *experimental* (may change soon) endpoint to extract the result of a text analysis.
python
client = Client(url)
project = client.get_project("my_project")
export = project.export_text_analysis(
document_sources="my_document_sources", process="my_process", annotation_types="*"
)

The export (json) looks like this

{
"projectName": "my_project",
"documentSourceName": "my_document_sources",
"textAnalysisResultSetName": "my_process",
"pipelineName": "discharge",
"textAnalysisResultDtos": [
{
"documentName": "abcdef.txt",
"annotationDtos": [
{
"begin": 0,
"end": 12,
"type": "uima.tcas.DocumentAnnotation",
"coveredText": "Hello World",
"id": 66753,
}
]
truncated
}
truncated
],
}


**Others**
We now support the new schemaVersion 2.0 of the configuration json that are used in platform version 6.

We also provide a more convenient way to generate a new API Token directly in the Client constructor by calling:
python
client = Client('http://localhost:8400/health-discovery', username='YOUR_USERNAME', password='YOUR_PASSWORD')

Please note that this *invalidates* your old API Token!

Please do not hesitate to contact us if you have any questions regarding the new release.

In this release `0.2.0`, we extend our support to new experimental API endpoints. The new pipeline function `analyse_text_to_cas()` allows obtaining an UIMA Cas object as the result of sending a document to the textanalysis. There is also support for downloading the TypeSystem of a pipeline using the new experimental pipeline function `get_type_system()`.

Please note that the endpoints are strictly experimental, meaning that they may soon change or disappear. Calling these endpoints requires that the DKPro Cassis Python library has been installed.

We also removed the default value of the document language. If the language is not explicitly set, then we have a component that tries to automatically detect the language of the document. We advise to set the document language for very short documents (snippets) to avoid errors in the document language detection.

Please do not hesitate to contact us if you face any problems.

The Averbis Python API provides a Python library for accessing Averbis products via their REST API.

This is the first pre-release.

The library provides access to all functionalities exposed via the REST API of Averbis products at the time of its release. For most API calls, the results are provided simply as Python dictionaries. In future releases of this library, this may change and we may start wrapping the responses as more specific Python classes. Also, other aspects of the library may change on the way to a first stable version.

We are looking forward to your feedback!