Connect Python applications with COMPREDICT AI Core.
Project description
COMPREDICT's AI CORE API Client
Python client for connecting to the COMPREDICT V1 REST API.
To find out more, please visit COMPREDICT website.
Requirements
To connect to the API with basic auth you need the following:
- Token generated with your AI Core username and password
- (Optional) Callback url to send the results
- (Optional) Private key for decrypting the messages.
Installation
You can use pip
or easy-install
to install the package:
$ pip install COMPREDICT-AI-SDK
or
$ easy-install COMPREDICT-AI-SDK
Configuration
Basic Authentication
AI Core requires from the user, to authenticate with token, generated with user's AI CORE username and password.
There are two ways in which user can generate needed token:
- Generate token directly with utility function (this approach requires user to pass url to AICore as well):
from compredict.utils.authentications import generate_token
# user_username and user_password in this example, are of course credentials personal to each user
response = generate_token(url="https://core.compredict.ai/api/v2", username=user_username,
password=user_password)
response_json = response.json()
# access tokens or errors encountered
if response.status_code == 200:
token = response_json['access']
refresh_token = response_json['refresh']
print(token)
print(refresh_token)
elif response.status_code == 400:
print(response_json['errors'])
else:
print(response_json['error'])
Now, you can instantiate Client with freshly generated token.
import compredict
compredict_client = compredict.client.api.get_instance(token=your_new_generated_token_here)
- Instantiate Client with your AICore username and password. In this case, token, as well as refresh_token, will be generated and assigned automatically to the Client. After this operation, you don't need to reinstantiate Client with generated token. You should be able to directly call all Client methods as you like.
import compredict
compredict_client = compredict.client.api.get_instance(username=username, password=password, callback_url=None,
ppk=None, passphrase="")
Accessing new access token with token refresh
Refresh token is used for generating new access token (mainly in case if previous access token is expired).
New access token can be generated with refresh token in two ways:
1. By calling utility function:
from compredict.utils.authentications import generate_token_from_refresh_token
response = generate_token_from_refresh_token(url="https://core.compredict.ai/api/v2", token=refresh_token)
response_json = response.json()
# access token or errors encountered
if response.status_code == 200:
token = response_json['access']
print(token)
elif response.status_code == 400:
print(response_json['errors'])
else:
print(response_json['error'])
Then, you can instantiate Client with new access token.
2. By calling Client method:
If you generated token with passing to the Client your username and password, you don't need to pass your refresh_token to generate_token_from_refresh_token() Client method, since your refresh_token is already stored inside the Client.
# look above for the explanation in which cases token_to_refresh is not required
token = compredict_client.generate_token_from_refresh_token(refresh_token)
Check token validity
If user would like for Client to automatically check token validity while instantiating Client, validate needs to enabled.
import compredict
compredict_client = compredict.client.api.get_instance(token=your_new_generated_token_here, validate=True)
User can manually verify token validity in two ways:
1. By calling utility function:
from compredict.utils.authentications import verify_token
response = verify_token(url="https://core.compredict.ai/api/v2", token=token_to_verify)
# check validity
if response.status_code == 200:
print(True)
else:
print(False)
2. By calling Client method:
If you generated token with passing to the Client your username and password, you don't need to pass your token to verify_token() Client method, since your token is already stored inside the Client.
# look above for the explanation in which cases token_to_verify is not required
validity = compredict_client.verify_token(token_to_verify)
print(validity)
In case of valid token, response will be empty with status_code 200.
We highly advice that the SDK information are stored as environment variables.
Accessing Algorithms (GET)
To list all the algorithms in a collection:
algorithms = compredict_client.get_algorithms()
for algorithm in algorithms:
print(algorithm.name)
print(algorithm.version)
To access a single algorithm:
algorithm = compredict_client.get_algorithm('ecolife')
print(algorithm.name)
print(algorithm.description)
Algorithm RUN (POST)
Any algorithm a user has access to is different, it has different:
- Input data and structure.
- Output data.
- Evaluation set.
- Result instance.
- Monitoring Tools.
- Accepted file format.
The run
function has the following signature:
Task|Result = algorithm.run(data, evaluate=True, encrypt=False, callback_url=None,
callback_param=None, file_content_type=None, monitor=True)
data
: data to be processed by the algorithm, it can be:dict
: forces the file's content type to beapplication/json
str
: path to the file to be sent, set thefile_content_type
to the mime type or empty forapplication/json
pandas
: DataFrame containing the data, set thefile_content_type
to convert the content to appropriate file.
evaluate
: to evaluate the result of the algorithm. Checkalgorithm.evaluations
, more in depth later.encrypt
: to encrypt the data using RSA AES, more in depth later.callback_url
: If the result isTask
, then AI core will send back the results to the provided URL once processed. It can be multiple callbackscallback_param
: additional parameters to pass when results are sent to callback url. In case of multiple callbacks, it can be a single callback params for all, or multiple callback params for each callback url.file_content_type
: The type of data to be sent. Based onalgorithm.accepted_file_format
. it could be:application/json
: for dict data.text/csv
: when passing pandas DataFrame.application/parquet
: when passing pandas's DataFrame.
monitor
: boolean indicating if the output results of the model should be monitored or not. By default it is set to True.
Depending on the algorithm's computation requirement algorithm.result
, the result can be:
- compredict.resources.Task: holds a job id of the task that the user can query later to get the results.
- compredict.resources.Result: contains the result of the algorithm + evaluation + monitors
Create list of urls for callbacks
callback_url = ["https://me.myportal.cloudapp.azure.com", "http://me.mydata.s3.amazonaws.com/my_bucket",
"http://my_website/my_data.com"]
After creating a list, use it when running algorithm:
results = algorithm.run(data, callback_url=callback_url, evaluate=False, encrypt=True)
Example of sending data as application/json
:
X_test = dict(
feature_1=[1, 2, 3, 4],
feature_2=[2, 3, 4, 5]
)
algorithm = compredict_client.get_algorithm('algorithm_id')
result = algorithm.run(X_test)
You can identify when the algorithm dispatches the processing of task to queue or sends the results instantly by checking:
>>> print(algorithm.results)
"The request will be sent to queue for processing"
or dynamically:
results = algorithm.run(X_test, evaluate=True)
if isinstance(results, compredict.resources.Task):
print(results.job_id)
while results.status != results.STATUS_FINISHED:
print("task is not done yet.. waiting...")
sleep(15)
results.update()
if results.success is True:
print(results.predictions)
else:
print(results.error)
else: # not a Task, it is a Result Instance
print(results.predictions)
Example of sending data as application/parquet
:
import pandas as pd
X_test = pd.DataFrame(dict(
feature_1=[1, 2, 3, 4],
feature_2=[2, 3, 4, 5]
))
algorithm = compredict_client.get_algorithm('algorithm_id')
result = algorithm.run(X_test, file_content_type="application/parquet")
Example of sending data from parquet file:
algorithm = compredict_client.get_algorithm('algorithm_id')
result = algorithm.run("/path/to/file.parquet", file_content_type="application/parquet")
If you set up callback_url
then the results will be POSTed automatically to you once the
calculation is finished.
Each algorithm has its own evaluation methods that are used to evaluate the performance of the algorithm given the data. You can identify the evaluation metric by calling:
algorithm.evaluations # associative array.
When running the algorithm, with evaluate = True
, then the algorithm will be evaluated by the default parameters. In order to tweek these parameters, you have to specify an associative array with the modified parameters. For example:
evaluate = {"rainflow-counting": {"hysteresis": 0.2, "N":100000}} # evaluate name and its params
result = algorithm.run(X_test, evaluate=evaluate)
Data Privacy
When the calculation is queued in COMPREDICT, the result of the calculations will be stored temporarily for three days. If the data is private and there are organizational issues in keeping this data stored in COMPREDICT, then you can encrypt the data using RSA. COMPREDICT allow user's to add RSA public key in the Dashboard. Then, COMPREDICT will use the public key to encrypt the stored results. In return, The SDK will use the provided private key to decrypt the returned results.
COMPREDICT will only encrypt the results when:
- The user provide a public key in the dashboard.
- Specify encrypt parameter in the predict function as True.
Here is an example:
# First, you should provide public key in COMPREDICT's dashboard.
# Second, Call predict and set encrypt as True
results = algorithm.run(X_test, evaluate=True, encrypt=True)
if isinstance(results, resources.Task):
if results.status is results.STATUS_FINISHED:
print(results.is_encrypted)
Handling Errors And Timeouts
For whatever reason, the HTTP requests at the heart of the API may not always succeed.
Every method will return false if an error occurred, and you should always check for this before acting on the results of the method call.
In some cases, you may also need to check the reason why the request failed. This would most often be when you tried to save some data that did not validate correctly.
algorithms = compredict_client.get_algorithms()
if not algorithms:
error = compredict_client.last_error
Returning false on errors, and using error objects to provide context is good for writing quick scripts but is not the most robust solution for larger and more long-term applications.
An alternative approach to error handling is to configure the API client to throw exceptions when errors occur. Bear in mind, that if you do this, you will need to catch and handle the exception in code yourself. The exception throwing behavior of the client is controlled using the failOnError method:
compredict_client.fail_on_error()
try:
orders = compredict_client.get_algorithms()
raise compredict.exceptions.CompredictError as e:
...
The exceptions thrown are subclasses of Error, representing client errors and server errors. The API documentation for response codes contains a list of all the possible error conditions the client may encounter.
Verifying SSL certificates
By default, the client will attempt to verify the SSL certificate used by the COMPREDICT AI Core. In cases where this is undesirable, or where an unsigned certificate is being used, you can turn off this behavior using the verifyPeer switch, which will disable certificate checking on all subsequent requests:
compredict_client.verify_peer(False)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for COMPREDICT_AI_SDK-2.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 38d94e1d47c49562551fde782ee8efabef32456b2987a86c753cf300008ea666 |
|
MD5 | 5ed5fdf3301aca913f65b196f10035ec |
|
BLAKE2b-256 | 344ddb92ea11199d2fae1adba0ae1bc3660bad8d99e665bc838497fa23d11e51 |