Predictor API client

This package provides a PyPi-installable lightweight client application for the Predictor API RESTFull server application. The package implements PredictorApiClient class enabling fast and easy method-based calls to all endpoints accessible on the API. To make working with the client a piece of cake, it provides full-documented example scripts for each of the supported endpoints. For more information about the Predictor API, please read the official readme and documentation.

The full programming sphinx-generated docs can be seen in the official documentation.

Endpoints: 1. predictor endpoints (/predict and /predict_proba) 1. /predict - calls .predict on the specified predictor. 2. /predict_proba - calls .predict_proba on the specified predictor. 2. security endpoints (/signup, /login, and /refresh) 1. /signup - signs-up a new user. 2. /login - logs-in an existing user (obtains access and refresh authorization tokens). 3. /refresh - refreshes an expired access token (obtains refreshed authorization access token).

Contents: 1. Installation 2. Configuration 3. Data 4. Examples 5. License 6. Contributors

---

Installation

pip install predictor-api-client

Configuration

The package provides the following configuration of the PredictorApiClient object during the instantiation: 1. API deployment specific configuration: it supports the configuration of the host (IP address), port (port number), and other settings related to the deployment and operation of the Predictor API (for more information, see the docs/). 2. API client specific configuration: it supports the configuration of the logging (logging_configuration). In this version, the package provides logging of the successful as well as unsuccessful /predict and /predict_proba endpoint calls (for more information, see the docs/).

Data

The full description of the requirements on input/output data (format, shape, etc.) can be found here.

Examples

In general, every time a client is used, the PredictorApiClient class must be instantiated. Next, all endpoint-specific data must be prepared. And finally, the endpoint-specific methods can be called. The full example scripts for each of the supported endpoints are placed at ./examples (simplified examples are shown bellow).

Client instantiation

```python from pprint import pprint from http import HTTPStatus from predictorapiclient.client import PredictorApiClient

Prepare the predictor API client settings

---------------------------------------------

Must be same as for the running Predictor API

---------------------------------------------

1. host (IP address)

2. port (port number)

3. request verification

4. request timeout in seconds

host = "http://127.0.0.1" port = 5000 verify = True timeout = 2

Instantiate the predictor API client

client = PredictorApiClient(host=host, port=port, verify=verify, timeout=timeout) ```

User sign-up

```python

This example assumes the presence of the client instantiation code

TODO: prepare data for a new user (see the API's requirements on the password)

1. username

2. password (e.g. can be generated with https://passwordsgenerator.net/)

username = "" password = ""

print("\n-- [01] example --") print(f"Signing-up a new user with username: {username} and password: {password}\n")

Sign-up a new user

response, statuscode = client.signup(username, password)

Check the output

if statuscode in (HTTPStatus.OK, HTTPStatus.CREATED): print("Successfully signed-up a new user") else: print(f"The request was unsuccessful ({statuscode}): {response}")

print("Response:") pprint(response) ```

User log-in

```python

This example assumes the presence of the client instantiation code

TODO: prepare data for an existing user (data from: user sign-up)

1. username

2. password

username = "" password = ""

print("\n-- [02] example --") print(f"Logging-in an existing user with username: {username} and password: {password}\n")

Log-in an existing user

response, statuscode = client.login(username, password)

Check the output

if statuscode == HTTPStatus.OK: print("Successfully logged-in an existing user") else: print(f"The request was unsuccessful ({statuscode}): {response}")

print("Response:") pprint(response) ```

Expired access token refresh

```python

This example assumes the presence of the client instantiation code

TODO: prepare data for request authorization (refresh token from: user log-in)

refresh_token = ""

print("\n-- [03] example --") print("Refreshing an expired access token\n")

Refresh an expired access token

response, statuscode = client.refreshaccesstoken(refreshtoken)

Check the output

if statuscode == HTTPStatus.OK: print("Successfully refreshed an expired access token") else: print(f"The request was unsuccessful ({statuscode}): {response}")

print("Response:") pprint(response) ```

Prediction

```python

This example assumes the presence of the client instantiation code

import numpy

TODO: prepare data for request authorization (access token and refresh token)

accesstoken = "" refreshtoken = ""

TODO: prepare model identifier

Example:

modelidentifier = "dummypredictor"

model_identifier = ""

TODO: prepare predictor data (feature values/labels)

----------------------------------------------------

Must meet the data requirements of the Predictor API

----------------------------------------------------

Example (10 subjects, each having 100 1-D features):

feature_values = numpy.random.rand(10, 1, 100)

feature_labels = None

featurevalues = "" featurelabels = None

print("\n-- [04] example --") print(f"Calling for prediction(s) on a predictor identified with: {model_identifier}\n")

Make the prediction(s)

Use one of the following:

1. client.predict(...)

2. client.predict_proba(...)

response, statuscode = client.predict( # or client.predictproba(...) accesstoken=accesstoken, refreshtoken=refreshtoken, modelidentifier=modelidentifier, featurevalues=featurevalues, featurelabels=featurelabels)

Check the output

if statuscode == HTTPStatus.OK: print("Successfully called .predict(...)/.predictproba(...)") else: print(f"The request was unsuccessful ({status_code}): {response}")

print("Response:") pprint(response) ```

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

This package is developed by the members of Brain Diseases Analysis Laboratory. For more information, please contact the head of the laboratory Jiri Mekyska mekyska@vut.cz or the main developer: Zoltan Galaz galaz@vut.cz.