clams.app package

Core package providing classes for representing CLAMS apps.

class clams.app.ClamsApp[source]

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._abc_data object>
abstract _annotate(mmif: Mmif, _raw_parameters=None, **refined_parameters) → Mmif[source]

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[source]

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)[source]
static _cuda_device_name_concat(name, mem)[source]
static _cuda_memory_to_str(mem) → str[source]
static _get_available_vram() → int[source]

Get currently available VRAM in bytes (GPU-wide, across all processes).

Uses nvidia-smi to get actual available memory, not just current process.

Returns:

Available VRAM in bytes, or 0 if unavailable

_get_profile_path(param_hash: str) → Path[source]

Get filesystem path for memory profile file.

Profile files are stored in a per-app directory under user’s cache.

Parameters:

param_hash – Hash of parameters from mmif.utils.cli.describe.generate_param_hash()

Returns:

Path to the profile file

_load_appmetadata() → AppMetadata[source]

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.

static _profile_cuda_memory(func)[source]

Decorator for profiling CUDA memory usage and managing VRAM availability.

This decorator: 1. Checks VRAM requirements before execution (if conditions met) 2. Rejects requests if insufficient VRAM 3. Records peak memory usage after execution 4. Calls empty_cache() for cleanup

Parameters:

func – The function to wrap (typically _annotate)

Returns:

Decorated function that returns (result, cuda_profiler) where cuda_profiler is dict with “<GPU_NAME>, <GPU_TOTAL_MEMORY>” keys and dict values containing ‘available_before’ and ‘peak’ memory in bytes

_record_vram_usage(parameters: dict, peak_bytes: int) → None[source]

Record peak memory usage to profile file.

Uses atomic write (temp + rename) to avoid corruption from concurrent writes. Only updates if new value is higher.

Profile files are JSON containing: - peak_bytes: Peak VRAM usage by the torch process - parameters: Original parameters for human readability

Parameters:

  • parameters – Request parameters (for hash and recording)

  • peak_bytes – Measured peak VRAM usage

_refine_params(**runtime_params: List[str])[source]

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[source]

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[source]

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

Returns:

Serialized JSON string of the metadata

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

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[source]

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[source]

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[source]

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 = [{'choices': None, 'default': False, 'description': 'The JSON body of the HTTP response will be re-formatted with 2-space indentation', 'multivalued': False, 'name': 'pretty', 'type': 'boolean'}, {'choices': None, 'default': True, 'description': 'The running time of the app will be recorded in the view metadata', 'multivalued': False, 'name': 'runningTime', 'type': 'boolean'}, {'choices': None, 'default': False, 'description': 'The hardware information (architecture, GPU and vRAM) will be recorded in the view metadata', 'multivalued': False, 'name': 'hwFetch', 'type': 'boolean'}]
static validate_document_locations(mmif: str | Mmif) → None[source]

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