clams.app package

Core package providing classes for representing CLAMS apps.

class clams.app.ClamsApp

Bases: ABC

An abstract class to define API’s for ClamsApps. A CLAMS app should inherit this class and then can be used with classes in restify to work as web applications.

_RAW_PARAMS_KEY = '#RAW#'

_abc_impl = <_abc_data object>

abstract _annotate(mmif: Mmif, _raw_parameters=None, **refined_parameters) → Mmif

An abstract method to generate (or load if stored elsewhere) the app metadata at runtime. All CLAMS app must implement this.

This is where the bulk of your logic will go. A typical implementation of this method would be

1. Create a new view (or views) by calling new_view() on the input mmif object.

2. Call sign_view() with the input runtime parameters for the record.

3. Call new_contain() on the new view object with any annotation properties specified by the configuration.

4. Process the data and create Annotation objects and add them to the new view.

5. While doing so, get help from DocumentTypes, AnnotationTypes classes to generate @type strings.

6. Return the mmif object

Parameters:

• mmif – An input MMIF object to annotate

• runtime_params – An arbitrary set of k-v pairs to configure the app at runtime

Returns:

A Mmif object of the annotated output, ready for serialization

abstract _appmetadata() → AppMetadata

An abstract method to generate the app metadata.

Returns:

A Python object of the metadata, must be JSON-serializable

static _check_mmif_compatibility(target_specver, input_specver)

_load_appmetadata() → AppMetadata

A private method to load the app metadata. This is called in __init__, (only once) and it uses three sources to load the metadata (in the order of priority):

1. using a metadata.py file (recommended)

2. using self._appmetadata() method (legacy, no longer recommended)

In any case, AppMetadata class must be useful.

For metadata specification, see https://sdk.clams.ai/appmetadata.jsonschema.

_refine_params(**runtime_params: List[str])

Method to “fill” the parameter dictionary with default values, when a key-value is not specified in the input. The input map is not really “filled” as a copy of it is returned with addition of default values. :param runtime_params: key-value pairs of runtime parameters :return: a copy of parameter map, with default values added :raises ValueError: when a value for a required parameter is not found in the input

annotate(mmif: str | dict | Mmif, **runtime_params: List[str]) → str

A public method to invoke the primary app function. It’s essentially a wrapper around _annotate() method where some common operations (that are invoked by keyword arguments) are implemented.

Parameters:

• mmif – An input MMIF object to annotate

• runtime_params – An arbitrary set of k-v pairs to configure the app at runtime

Returns:

Serialized JSON string of the output of the app

appmetadata(**kwargs: List[str]) → str

A public method to get metadata for this app as a string.

Returns:

Serialized JSON string of the metadata

get_configuration(**runtime_params)

static open_document_location(document: str | ~mmif.serialize.annotation.Document, opener: ~typing.Any = <built-in function open>, **openerargs)

A context-providing file opener. A user can provide their own opener class/method and parameters. By default, with will use python built-in open to open the location of the document.

Parameters:

• document – A Document object that has location

• opener – A Python class or method that can be used to open a file (e.g. PIL.Image for an image file)

• openerargs – Parameters that are passed to the opener

Returns:

record_error(mmif: str | dict | Mmif, **runtime_conf: List[str]) → Mmif

A method to record an error instead of annotation results in the view this app generated. For logging purpose, the runtime parameters used when the error occurred must be passed as well.

Parameters:

• mmif – input MMIF object

• runtime_conf – parameters passed to annotate when the app encountered the error

Returns:

An output MMIF with a new view with the error encoded in the view metadata

set_error_view(mmif: str | dict | Mmif, **runtime_conf: List[str]) → Mmif

A method to record an error instead of annotation results in the view this app generated. For logging purpose, the runtime parameters used when the error occurred must be passed as well.

Parameters:

• mmif – input MMIF object

• runtime_conf – parameters passed to annotate when the app encountered the error

Returns:

An output MMIF with a new view with the error encoded in the view metadata

sign_view(view: View, runtime_conf: dict) → None

A method to “sign” a new view that this app creates at the beginning of annotation. Signing will populate the view metadata with information and configuration of this app. The parameters passed to the _annotate() must be passed to this method. This means all parameters for “common” configuration that are consumed in annotate() should not be recorded in the view metadata. :param view: a view to sign :param runtime_conf: runtime configuration of the app as k-v pairs

universal_parameters = [{'name': 'pretty', 'type': 'boolean', 'choices': None, 'default': False, 'multivalued': False, 'description': 'The JSON body of the HTTP response will be re-formatted with 2-space indentation'}, {'name': 'runningTime', 'type': 'boolean', 'choices': None, 'default': False, 'multivalued': False, 'description': 'The running time of the app will be recorded in the view metadata'}, {'name': 'hwFetch', 'type': 'boolean', 'choices': None, 'default': False, 'multivalued': False, 'description': 'The hardware information (architecture, GPU and vRAM) will be recorded in the view metadata'}]

static validate_document_locations(mmif: str | Mmif) → None

Validate files encoded in the input MMIF.

Parameters:

mmif – An input MMIF with zero or more Document

Raises:

FileNotFoundError – When any of files is not found at its location