Model

For ease of use, the ELG internal API has been represented as a prebuilt python model using pydantic.
For technical documentation, see below.
For more information on the API itself, see:

https://european-language-grid.readthedocs.io/en/stable/all/A3_API/LTInternalAPI.html

Base messages

Request

class elg.model.base.Request.Request(*, type: str = None, params: dict = None)

Representation of a service invocation request. Intended to be abstract, subclasses should be initiated with their specific type

Subclasses

type: str

(required in subclass) the type of request

params: dict

(optional) vendor specific params, up to service implementor to decide how to interpret these

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

Response

class elg.model.base.ResponseObject.ResponseObject(*, type: str, warnings: List[StatusMessage] = None)

Representation of a successful completion response. Abstract, subclasses must instantiate this with their own type

Subclasses

type: str

(required in subclass) the type of response

warnings: List[StatusMessage]

(optional) messages describing any warnings on response

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

Annotation

class elg.model.base.Annotation.Annotation(*, start: Number, end: Number, sourceStart: Number = None, sourceEnd: Number = None, features: dict = None)

Representation of a single annotation with respect to either one or two streams of data.

start(Number, required)
Type

annotation start location (in response)

end(Number, required)
Type

annotation end location (in response)

source_start(Number, required in cases)
Type

annotation start location (in source)

source_end(Number, required in cases)
Type

annotation end location (in source)

features(dict, optional)
Type

arbitrary json metadata about content

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

Failure

class elg.model.base.Failure.Failure(*, errors: List[StatusMessage])

Details of a failed task

errors: List[StatusMessage]

(required) List of status messages describing the failure

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

Progress

class elg.model.base.Progress.Progress(*, percent: float, message: StatusMessage = None)

Details of an in progress task Some LT services can take a long time to process each request - likely useful to keep caller updated

percent: float

(required) completion percentage

message: StatusMessage

(optional) message describing progress report

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

StatusMessages

class elg.model.base.StatusMessage.StatusMessage(*, code: str, params: List[str], text: str, detail: Dict = None)

Represents a single status message, in a form amenable to internationalisation.

Each message contains a code, which can be looked up in a list to find the actual text in any of the available languages. The text can contain numbered placeholders of the form <code>{0}</code>, which are filled in with values specified in the “params” property. The “text” property provides a single fallback text to be used if the specified code cannot be found in the lookup table.

code: str

(required) status code to be found in lookup table

params: List[str]

(required) values to fill in message placeholder

text: str

(required) fallback text to be used if specified code cannot be found in lookup table

detail: Dict

(optional) arbitrary further details that don’t need translation (e.g. stacktrace)

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

StandardMessages

class elg.model.base.StandardMessages.StandardMessages

This class provides easy access to the standard set of ELG status messages that are provided by default by the platform and should be fully translated in the ELG user interface. If you use codes other than these standard ones in your services then you should also try to contribute translations of your messages into as many languages as possible for the benefit of other ELG users.

Implementation note: This class is auto-generated from elg-messages.properties - to add new message codes you should edit the property files, then run /utils/generate_standard_messages.py. Do not edit this class directly.

classmethod generate_elg_request_invalid(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.invalid

classmethod generate_elg_request_missing(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.missing

classmethod generate_elg_request_type_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.type.unsupported

classmethod generate_elg_request_property_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.property.unsupported

classmethod generate_elg_request_too_large(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.too.large

classmethod generate_elg_request_parameter_missing(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.parameter.missing

classmethod generate_elg_request_parameter_invalid(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.parameter.invalid

classmethod generate_elg_request_text_mimetype_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.text.mimeType.unsupported

classmethod generate_elg_request_audio_format_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.audio.format.unsupported

classmethod generate_elg_request_audio_samplerate_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.audio.sampleRate.unsupported

classmethod generate_elg_request_image_format_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.image.format.unsupported

classmethod generate_elg_request_structuredtext_property_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.request.structuredText.property.unsupported

classmethod generate_elg_response_invalid(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.response.invalid

classmethod generate_elg_response_type_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.response.type.unsupported

classmethod generate_elg_response_property_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.response.property.unsupported

classmethod generate_elg_response_texts_property_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.response.texts.property.unsupported

classmethod generate_elg_response_classification_property_unsupported(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.response.classification.property.unsupported

classmethod generate_elg_service_not_found(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.service.not.found

classmethod generate_elg_async_call_not_found(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.async.call.not.found

classmethod generate_elg_permissions_quotaexceeded(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.permissions.quotaExceeded

classmethod generate_elg_permissions_accessdenied(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.permissions.accessDenied

classmethod generate_elg_permissions_accessmanagererror(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.permissions.accessManagerError

classmethod generate_elg_file_not_found(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.file.not.found

classmethod generate_elg_file_expired(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.file.expired

classmethod generate_elg_upload_too_large(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.upload.too.large

classmethod generate_elg_service_internalerror(params=[], detail={}, **kwargs)

Generate StatusMessage for code: elg.service.internalError


Request messages

TextRequest

class elg.model.request.TextRequest.TextRequest(*, type: str = 'text', params: dict = None, content: str, mimeType: str = 'text/plain', features: Dict = None, annotations: Dict[str, List[Annotation]] = None)

Request representing a single piece of text, optionally with associated markup Subclass of elg.model.base.Request.Request

For example a list of paragraphs or sentences, or a corpus of documents, each divided into sentences. While this could be represented as standoff annotations in a plain “text” request, the structured format is more suitable for certain types of tools.

type: str

(required) the type of request must be “text”

content: str

(optional) text content

mimeType: str

(optional) mime type of request, default “text/plain”

features: Dict

(optional) arbitrary json metadata about content

annotations: Dict[str, List[Annotation]]

(optional) optional annotations on request

Structured Text Request

class elg.model.request.StructuredTextRequest.Text(*, content: str = None, mimeType: str = 'text/plain', features: dict = None, annotations: Dict[str, List[Annotation]] = None, texts: List[Text] = None)

A single node in a structured text request.

Each text can have an associated score (for example a confidence value for multiple alternative translations or transcriptions) and optional annotations, which can be linked to both the result text in this object and to the original source material from the corresponding request.

content: str

(optional) text content

mime_type: str

(optional) mime type of request, default “text/plain”

features: dict

(optional) arbitrary json metadata about content

annotations: Dict[str, List[Annotation]]

(optional) optional annotations on request

texts: List[Text]

(optional) recursive, same structure

classmethod either_content_or_text(values)

ensures only either the “content” or the “text” fields are present

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

class elg.model.request.StructuredTextRequest.StructuredTextRequest(*, type: str = 'structuredText', params: dict = None, texts: List[Text])

Request representing text with some structure. Subclass of elg.model.base.Request.Request

For example a list of paragraphs or sentences, or a corpus of documents, each divided into sentences. Whilst this could be represented as standoff annotations in a plain “text” request, the structured format is more suitable for certain types of tools.

type: str

(required) the type of request must be “structuredText”

texts: List[Text]

(required) the actual text object with the text content

Audio Request

class elg.model.request.AudioRequest.AudioRequest(*, type: str = 'audio', params: dict = None, content: bytes = None, generator: Any = None, format: str = 'LINEAR16', sampleRate: int = None, features: Dict = None, annotations: Dict[str, List[Annotation]] = None)

Request representing a piece of audio - the actual audio data will be sent as a separate request. Subclass of elg.model.base.Request.Request

type: str

(required) the type of request must be “audio”

content: bytes

(optional) audio itself, if not being sent as separate stream

generator: Any

(optional) generator that provide the audio itself

format: str

(required) format of audio request. must be either “LINEAR16” (default) or “MP3”

sample_rate: int

(optional) sample rate of audio

features: Dict

(optional) arbitrary json metadata about content

annotations: Dict[str, List[Annotation]]

(optional) optional annotations on request

classmethod format_must_be_specific(v)

(validator) ensures the format of the audio request is either “LINEAR16” or “MP3”

classmethod generator_must_be_iterable(v)

(validator) ensures the iterator field of the audio request is either None or an Iterable

classmethod from_file(filename, format: Optional[str] = None, sample_rate: Optional[int] = None, features: Optional[Dict] = None, annotations: Optional[Dict[str, List[Annotation]]] = None, params: Optional[dict] = None, streaming: bool = False, blocksize: int = 1024)

allows you to generate audio request from file

Image Request

class elg.model.request.ImageRequest.ImageRequest(*, type: str = 'image', params: dict = None, content: bytes = None, generator: Any = None, format: str = 'png', features: Dict = None)

Request representing a piece of an image - the actual image data may be sent as a separate request. Subclass of elg.model.base.Request.Request

type: str

(required) the type of request must be “image”

content: bytes

(optional) image itself, if not being sent as separate stream

generator: Any

(optional) generator that provide the audio itself

format: str

(required) format of image, e.g BMP, PNG, JPG. Default is “png”

features: Dict

(optional) arbitrary json metadata about content

classmethod format_must_be_valid(format_value)

(validator) ensures the format field of the image request is either None or one of the currently accepted 5

classmethod generator_must_be_iterable(v)

(validator) ensures the iterator field of the image request is either None or an Iterable

classmethod from_file(filename, format: Optional[str] = None, features: Optional[Dict] = None, params: Optional[dict] = None, streaming: bool = False, blocksize: int = 1024)

allows you to generate image request from file


Response messages

AnnotationsResponse

class elg.model.response.AnnotationsResponse.AnnotationsResponse(*, type: str = 'annotations', warnings: List[StatusMessage] = None, features: dict = None, annotations: Dict[str, List[Annotation]] = None)

Response representing standoff annotations over a single stream of data (e.g. information extraction results). Subclass of elg.model.base.ResponseObject.ResponseObject

type: str

(required) the type of response must be “annotations”

features: dict

(optional) arbitrary json metadata about content

annotations: Dict[str, List[Annotation]]

(optional) optional annotations on request

classmethod either_features_or_annotations(values)

(validator) ensures either the “features” or “annotations” fields are present

AudioResponse

class elg.model.response.AudioResponse.AudioResponse(*, type: str = 'audio', warnings: List[StatusMessage] = None, content: str, format: str, features: dict = None, annotations: Dict[str, List[Annotation]] = None)

Response representing audio data with optional standoff annotations (e.g. text-to-speech results) Subclass of elg.model.base.ResponseObject.ResponseObject

type: str

(required) type of response

content: str

(required) base64 encoded audio for short audio snippets

format: str

either “LINEAR16” or “MP3”

Type

(required) specifies audio format used

features: dict

(required) arbitrary json metadata about content

annotations: Dict[str, List[Annotation]]

(required) optional annotations on response

classmethod format_must_be_specific(v)

(validator) ensures the format of the audio response is either “LINEAR16” or “MP3”

to_file(filename)

(validator) writes audio response to file

Classification Response

class elg.model.response.ClassificationResponse.ClassesResponse(*, score: float = None, **extra_data: Any)

Classification object: classification and score (optional likelihood of classification) Subclass of elg.model.base.ResponseObject.ResponseObject

class_field: str

(required) labelled class

score: float

(optional) confidence score in class

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

class elg.model.response.ClassificationResponse.ClassificationResponse(*, type: str = 'classification', warnings: List[StatusMessage] = None, classes: List[ClassesResponse] = None)

Response encapsulating one or more classifications of the whole input message, optionally with confidence scores attached.

type: str

(required) type of response

classes: List[ClassesResponse]

(optional) list of classifications, zero or more allowed

TextsResponse

class elg.model.response.TextsResponse.TextsResponseObject(*, role: str = None, content: str = None, texts: List[TextsResponseObject] = None, score: Number = None, features: dict = None, annotations: Dict[str, List[Annotation]] = None)

Object representing a structured piece of text. Recursive.

role: str

(optional) the role of this node in the response

content: str

(optional) string of translated/transcribed text

texts: List[TextsResponseObject]

(optional) list of same structures, recursive

score: Number

(optional) confidence of response

features: dict

(optional) arbitrary JSON metadata about content

annotations: Dict[str, List[Annotation]]

(optional) optional annotations on request

classmethod either_content_or_text(values)

(validator) ensures either the “content” or “text” fields are present

json(**kwargs: Any) → str

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

class elg.model.response.TextsResponse.TextsResponse(*, type: str = 'texts', warnings: List[StatusMessage] = None, texts: List[TextsResponseObject])

Response consisting of a set of one or more new texts, each with optional annotations attached to it. Subclass of elg.model.base.ResponseObject.ResponseObject

For example a set of possible translations produced by a translation tool or possible transcriptions produced by a speech-to-text recogniser.

type: str

(optional) type of response, must be “texts”

texts: List[TextsResponseObject]

(optional) list of objects representing a structured text response