For developers
Welcome to Practicus AI Model API documentation. You can use the Practicus AI App or the SDK to build, distribute and deploy AI/ML models and then consume these models with the app or any other REST API compatible system.
Model prefix concept
Practicus AI models are logically grouped with the model prefix concept using the https:// [some.address.com] / [some/model/prefix] / [model-name] format. E.g. https://practicus.company.com/models/marketing/churn can be a model API address where models/marketing is the prefix and churn is the model.
Model Documentation
Models under a prefix can be viewed by using Practicus AI App. If your admin enabled them, you can also view the documentation by visiting ../prefix/redoc or ../prefix/docs or E.g. https://practicus.company.com/models/marketing/redoc
Model Deployment concept
Models are physically deployed to Kubernetes deployment(s). These have several characteristics including capacity, auto-scaling, additional security etc.
Authentication
Consuming models inside the Practicus AI app does not require additional authentication. For external use, you will need an access token. An admin can create tokens at the model prefix or individual model level.
Submitting data in batches
Practicus AI app will automatically split large data into mini-batches to improve performance and avoid memory issues. You are encouraged to do the same and submit data in a volume compatible with your model deployment capacity. E.g. If your model deployment pods have 1 GB RAM, it is advisable to submit data in 250MB or less batch size.
Compression
Practicus AI app automatically compresses requests and responses for the model API. You can also compress using 'lz4', 'zlib', 'deflate', 'gzip' compression algorithms. All you need to do is to compress, and send the algorithm using 'content-encoding' http header, or by simply naming the attached file with the compression extension. E.g. my_data.lz4
Model Metadata
You can learn more about any AI model by simply requesting it's meta data using ?get_meta=true query string. E.g. https://practicus.company.com/models/marketing/churn?get_meta=true
Sample Python code
import requests
headers = {'authorization': 'Bearer _your_access_token_'}
api_url = 'https://practicus.company.com/models/marketing/churn/'
r = requests.get(api_url + '?get_meta=true', headers=headers)
print('Model details: ', r.text)
r = requests.get(api_url, headers=headers, files={'data.csv': open('data.csv', 'rb')})
print('Prediction result: ', r.text)
Streaming code
By setting the necessary http request headers you can submit the data using as a stream.
import requests
headers = {'authorization': 'Bearer _your_access_token_',
'content-type': 'application/octet-stream',
'content-disposition': 'attachment; filename=data.csv',
'content-encoding': 'text/csv'}
api_url = 'https://practicus.company.com/models/marketing/churn/'
r = requests.get(api_url, headers=headers, data=open('data.csv', 'rb'), stream=True)
print('Prediction result: ', r.text)
Compression code
With or without streaming, you can submit the data after compressing with lz4', 'zlib', 'deflate', 'gzip' algorithms. If you compress the request, the response will also arrive using the same compression algorithm.
import lz4.frame
import requests
headers = {'authorization': 'Bearer _your_access_token_',
'content-type': 'application/octet-stream',
'content-disposition': 'attachment; filename=data.lz4',
'content-encoding': 'lz4'}
api_url = 'https://practicus.company.com/models/marketing/churn/'
data = lz4.frame.compress(some_bytes)
r = requests.get(api_url, headers=headers, data=data, stream=True)
print('Prediction result: ', r.text)
Pandas and compression code
It is a very common scenario to submit a pandas dataframe and add the response back to the original dataframe as a new column.
import pandas as pd
import requests
import lz4.frame
my_df = pd.read_csv('some_data.csv')
headers = {'authorization': 'Bearer _your_access_token_',
'content-type': 'application/octet-stream',
'content-disposition': 'attachment; filename=data.lz4',
'content-encoding': 'lz4'}
api_url = 'https://practicus.company.com/models/marketing/churn/'
data = lz4.frame.compress(my_df.to_string().encode())
r = requests.get(api_url, headers=headers, data=data, stream=True)
...