Building Your Own Client

Ready to get started building your own client? This page gives a quick introduction to using the main Emtellipro interface for submitting documents for processing and retrieving the results.

First, ensure you’ve installed the package properly and have connectivity working: Installation

The next step is ensuring that your API keys are set up and working – to make sure you can use your API keys and can connect to the server, the quickest way is to use the provided example client to try and retrieve your user information (if you’ve already done this step in Basic Client then you can skip this step):

emtellipro-client \
    get-user \
    --access-key ACCESS_KEY \
    --secret-key SECRET_KEY \
    --server https://api.emtelligent.com:50001

If successful and your access is set up, this command will print out your username with a response like:

User with username: test_user

Retrieve your user info

As a first step in building our client, let’s replicate the client example above and try a code example where we connect to the API to test our access keys and retrieve our username. First, we’ll begin by importing the Emtellipro class and instantiating it with our access key and secret key.

>>> import emtellipro
>>> client = emtellipro.Emtellipro('ACCESS_KEY', 'SECRET_KEY')

Next we’ll retrieve the user info:

>>> user = client.user
>>> print(user)
User with username: [email protected]
>>> print(user.username)
[email protected]

Great - let’s go onto the next step where we’ll build a client for processing some medical text.

Submit a document for processing

Now that we’ve confirmed we can connect and authenticate against the emtelliPro API, let’s submit a simple document for processing. Note that although we’re submitting a single document the API handles a list of documents, so we’ll submit a list containing a single document.

>>> from emtellipro.data import InputDocument
>>> doc = InputDocument(
...         id_='12',
...         category='Radiology',
...         subcategory='CT',
...         text='The raw text of the document')
>>> result_futures = client.submit([doc])
>>> result_future = next(result_futures)

The ResultFuture instance returned by the client.submit call keeps track of the task ID returned by the API. It allows you to check on result of the processing using emtellipro.ResultFuture.done(). Note that an iterable of result futures is returned since the submitted documents are split into groups which fit into the maximum request size limit.

>>> bool(result_future.done())
True

Now that we know that processing of the submitted document is completed, we can retrieve the results. Calling result_future.result() returns a generator that parses the server’s response lazily. This method can be called multiple times to create new generators without extra API requests being sent.

>>> annotated_docs = list(result_future.result())
>>> annotated_docs[0].id
12

Each element in annotated_docs is an instance of AnnotatedDocument, which we can work with by reading its attributes, or if we’re simply looking to dump the raw results returned by the API, we can:

>>> raw_data = result_future.raw_result()
>>> with open('data.json', 'w') as f:
...     f.write(raw_data)

Submit many files for processing

In the case you have many files to submit, there is a convenience function provided for reading them and creating InputDocument instances.

>>> from glob import glob
>>> from emtellipro.utils import read_files
>>> input_docs, id_mapping = read_files(glob('./documents/*.txt'))
>>> client.submit(input_docs)

The read_files() function returns both the input documents as well as a mapping from each file path passed in and the associated document ID that was generated; this is useful for matching the returned results to the original files.

Next steps

This should be enough to get started with a simple client, but if you haven’t already read it, check out Database Client and the code in the examples directory for building a more complex client that can put results into a database for building apps based on the emtelliPro engine’s output.