> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.emtelligent.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server. # engine This module contains the `Emtellipro` class and related classes for interacting with the engine. ## Module Contents ### Classes | Name | Description | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`ResultFutureStatus`](#emtelliproengineresultfuturestatus) | This class is returned by ResultFuture.done, and contains information about the processing status of the job. | | [`Result`](#emtelliproengineresult) | This is the result from the engine containing parsed annotated docs, and other information about this processing run. | | [`ResultFuture`](#emtelliproengineresultfuture) | This class mimics asyncio.Future and concurrent.futures.Future in terms of some of the available methods and semantics, but you cannot await or yield from any of its methods. | | [`Emtellipro`](#emtelliproengineemtellipro) | This is the main way of interacting with the API. It handles all the necessary details for submitting documents for processing and retrieving results. | ### Functions | Name | Description | | ---- | ----------- | ### Data `FEATURES` `CATEGORIES` ### API #### `emtellipro.engine.FEATURES` ```python emtellipro.engine.FEATURES ``` These are the complete list of available features. #### `emtellipro.engine.CATEGORIES` ```python emtellipro.engine.CATEGORIES ``` This is a mapping from category names to subcategories that are supported by this version of the emtelliPro SDK. #### `emtellipro.engine.ResultFutureStatus` ```python class emtellipro.engine.ResultFutureStatus(status, prev_progress) ``` **Bases:** object This class is returned by ResultFuture.done, and contains information about the processing status of the job. Note: this class implements `__bool__` with the same semantics as `.done` **Attributes:** * `done`: whether the job has completed processing (can either be a successful, failed, or cancelled job; both are considered "done") * `success`: whether the job has completed successfully; note if the job is not done, this will be false * `progress`: a number in \[0, 1] representing the percentage of completed documents * `state`: The value of the "state" field in the status returned by emtelliPro. ##### `ResultFutureStatus.__bool__` ```python __bool__() ``` #### `emtellipro.engine.Result` ```python class emtellipro.engine.Result ``` **Bases:** object This is the result from the engine containing parsed annotated docs, and other information about this processing run. It is possible to iterate over this object, which will have the effect of iterating over the annotated docs. **Attributes:** * `task_id`: The task ID for the task that produced this result. * `engine_version`: The engine version returned by the engine. * `annotated_docs`: A list of `AnnotatedDocument` instances. * `raw`: The unparsed original text that was returned by the engine. * `json`: The parsed JSON for the result class. ##### Initialization ```python __init__(task_id, engine_version, raw, annotated_docs) ``` ##### `Result.task_id` ```python task_id: str ``` ##### `Result.engine_version` ```python engine_version: str ``` ##### `Result.raw` ```python raw: str ``` ##### `Result.annotated_docs` ```python annotated_docs: typing.List[emtellipro.data.AnnotatedDocument] ``` **Type:** typing.List\[[`AnnotatedDocument`](/nlp/python/reference/data#emtelliprodataannotateddocument)] ##### `Result.json` ```python property json: dict ``` **Return type:** `dict` ##### `Result.fail` ```python fail( task_id: str, engine_version: str, input_docs: collections.abc.Iterable[emtellipro.data.InputDocument], raw: typing.Optional[str] = None ) ``` Create a Result instance where all the annotated documents are failed. **Parameters:** **`task_id`** `str` The task ID to insert into the fake result. --- **`engine_version`** `str` The engine version to insert in to the fake result. --- **`input_docs`** `collections.abc.Iterable[emtellipro.data.InputDocument]` The input docs that were submitted for this result. Only the ID and category/subcategory attributes are used to generate fake annotated document objects. --- **`raw`** `typing.Optional[str]` The JSON string to set at the 'raw' attribute. --- ##### `Result.__iter__` ```python __iter__() ``` #### `emtellipro.engine.ResultFuture` ```python class emtellipro.engine.ResultFuture(task_id, api, num_docs=None) ``` **Bases:** object This class mimics asyncio.Future and concurrent.futures.Future in terms of some of the available methods and semantics, but you cannot await or yield from any of its methods. ResultFuture instances will be created by the Emtellipro and should not be created directly. Note: ResultFuture objects are pickle-able. **Attributes:** * `task_id`: The task ID as returned by the emtelliPro API. This can be stored and then used with `Emtellipro.check_task()` to recreate a ResultFuture instance. ##### Initialization **Parameters:** * **task_id**: a string representing the ID of the task submitted to the server. * **api**: instance of \_api.Api used for retrieving results and checking status. * **num_docs**: the number of documents this result future is handling, if known. ##### `ResultFuture.num_docs` ```python property num_docs ``` The total number of documents submitted for processing. ##### `ResultFuture.cancel` ```python cancel() ``` Cancel the task being represented by this ResultFuture. ##### `ResultFuture.cancelled` ```python cancelled() ``` Check if the task is cancelled. **Returns:** The cancellation status of the task (a boolean). ##### `ResultFuture.done` ```python done(timeout=None) -> emtellipro.engine.ResultFutureStatus ``` Check if task is done (i.e. cancelled, successful, failed). **Parameters:** **Returns:** The processing status, which can be used in an `if` statement since it will evaluate to True if the task is done. **Return type:** [`ResultFutureStatus`](/nlp/python/reference/engine#emtelliproengineresultfuturestatus) **`timeout`** when checking the status of the job, the server may keep the connection open up to this amount of time or until the job is completed, whichever is quicker. --- ##### `ResultFuture.result` ```python result() -> emtellipro.engine.Result ``` Retrieve the results of the task. The response from emtelliPro is cached, so calling this multiple times will not lead to multiple calls to emtelliPro. If you'd like the unparsed raw API response, use `.raw_result()` instead. **Returns:** The result of processing the task. **Raises:** [`exc.TaskFailedError`](/nlp/python/reference/exc#emtelliproexctaskfailederror): The task has a status of 'failure'. [`exc.TaskNotFoundError`](/nlp/python/reference/exc#emtelliproexctasknotfounderror): The task is not found on the server. **Return type:** [`Result`](/nlp/python/reference/engine#emtelliproengineresult) ##### `ResultFuture.engine_version` ```python property engine_version ``` The engine version as returned in the result. This can only be accessed after calling `.result()`; accessing this attribute before will result in an AttributeError. ##### `ResultFuture.raw_result` ```python raw_result(result_format=data.AnnotatedDocument.supported_result_format) ``` Return the raw text result from the API, unparsed. The text is cached, so multiple calls to this method will not result in multiple API calls. If you'd like the parsed result, use `.result()` instead. **Raises:** [`exc.TaskFailedError`](/nlp/python/reference/exc#emtelliproexctaskfailederror): The task has a status of 'failure'. [`exc.TaskNotFoundError`](/nlp/python/reference/exc#emtelliproexctasknotfounderror): The task is not found on the server. #### `emtellipro.engine.Emtellipro` ```python class emtellipro.engine.Emtellipro(server, auth: typing.Union[tuple[str, str], str], *, max_retries=DEFAULT_MAX_RETRIES, extra_headers: typing.Optional[collections.abc.Mapping] = None) ``` **Bases:** object This is the main way of interacting with the API. It handles all the necessary details for submitting documents for processing and retrieving results. **Example:** ```python input_docs = ... client = Emtellipro(...) for batch in emtellipro.utils.batch_documents(input_docs): result_future = client.submit(batch) while not result_future.done(): pass print(result_future.result) ``` **Attributes:** * `server`: The emtelliPro server URL. ##### Initialization **Parameters:** * **server**: The URL of the server to connect to. If you wish to use the default global server, you should pass `Emtellipro.DEFAULT_SERVER` here. * **auth**: The authentication keys; this must be a tuple of (access key, shared secret) for HMAC based authentication, or a single string for API-key based authentication. *New in version 6.10.* Support for API key authentication. * **max_retries (optional)**: the number of times to retry failed API requests; there may be failures due to network issues, so this should be a positive integer. * **extra_headers**: Any extra headers to include in all requests. ##### `Emtellipro.DEFAULT_MAX_RETRIES` ```python DEFAULT_MAX_RETRIES ``` **Value**: `5` ##### `Emtellipro.DEFAULT_SERVER` ```python DEFAULT_SERVER ``` The default global server that can be passed as the argument to `server`. **Value**: `https://nlp.emtelligent.com` ##### `Emtellipro.submit` ```python submit( documents: typing.Iterable[emtellipro.data.InputDocument], features: typing.Optional[typing.Iterable[str]] = None, document_type: str = 'plain' ) -> emtellipro.engine.ResultFuture ``` Submit documents for annotating. **Parameters:** **`documents`** `typing.Iterable[emtellipro.data.InputDocument]` An iterable of Document objects to be annotated. The `category` and `subcategory` attributes of each document will be validated against [`CATEGORIES`](/nlp/python/reference/engine#emtelliproenginecategories). --- **`features`** `typing.Optional[typing.Iterable[str]]` A list of features to enable in the processing of the documents. Default of None means "enable all". See [`FEATURES`](/nlp/python/reference/engine#emtelliproenginefeatures) for complete list of options. --- **`document_type`** `str` — default: 'plain' String containing the document type to be used for all documents which don't specify their own type. Default is `'plain'` --- **Returns:** A ResultFuture object representing the current status of the annotation process. > **Warning** This will not check that the submitted batch of documents is too big. You should use [`batch_documents`](/nlp/python/reference/utils#emtelliproutilsbatch_documents) to split up a large number of documents into smaller batches that do not go over the maximum submission limit. **Return type:** [`ResultFuture`](/nlp/python/reference/engine#emtelliproengineresultfuture) ##### `Emtellipro.check_task` ```python check_task(task_id) -> emtellipro.engine.ResultFuture ``` Create a ResultFuture instance from a `task_id`. **Parameters:** **Returns:** A new future object that can be used to monitor processing status and retrieve results. **Raises:** [`exc.TaskNotFoundError`](/nlp/python/reference/exc#emtelliproexctasknotfounderror): Raised if the task ID wasn't found on the server. **Return type:** [`ResultFuture`](/nlp/python/reference/engine#emtelliproengineresultfuture) **`task_id`** the task ID. This is available on `ResultFuture` instances as the `.task_id` attribute, however it is simply the task ID as returned by the emtelliPro API's `/submit` call, so that can be provided regardless of how it was obtained (e.g. if you obtained it from our Java SDK, that will work, too). --- ##### `Emtellipro.user` ```python property user: emtellipro.data.User ``` The user information as known by the Emtellipro server. **Return type:** [`User`](/nlp/python/reference/data#emtelliprodatauser)