Skip to content

Training Data Upload

Additionally, to the training data file upload in the Cockpit, paretos enables you to programmatically upload new training data to your existing use cases. You can either hit our API directly with your requests, or use the Paretos API Connector python package that we build to make your life easier.

Prerequisites

The following prerequisites are required to proceed:

  • A paretos use case ready for training data upload
    • The Use Case ID (see next section)
  • The credentials for your paretos account with access to the use case:
    • Username (usually your E-Mail address)
    • Password
  • File with training data

Retrieve Use Case Id from Cockpit

Login into the Cockpit and navigate to the "Connect" tab. Click on "Automate data exchange" and copy you use case id.

Screenshot Screenshot

This guide will show you how to perform the required requests. You can optionally download a Postman Collection containing the required requests.

[Option 1]: Upload via Paretos API Connector

First, install the paretos package.

pip install paretos

Initialization

With the paretos package installed, you first set up a configuration object that includes your username and password. Follow the example at examples/use_case_example.py, where you set your credentials as environment variables or directly provide them to the Config class.

from paretos import Config

config = Config(username='put here your username', password='put here your password')

With this configuration, the package sets up the token authentication automatically when instantiating the paretos class.

from paretos import Paretos

paretos = Paretos(config)

Uploading Training Data File

try:
    paretos.upload_training_data_file(
        use_case_id='put your use case id here', 
        file_path='put the path to your file here'
    )
except OSError as e:
    pass
except (RequestFailed, InvalidResponseStructure, ResponseParsingError) as e:
    pass

All errors will issue a error message, which you can use to pinpoint what is going wrong. Here is a quick start for the exceptions that you can get: - OSError: Probably has to do with your file or file path, eg. when the path you provide does not point to a file. - RequestFailed: Probably the API cannot be reached. Try setting the USE_CASE_URL environment variable to a URL that you validated you can reach (eg. 'https://use-case.paretos.com') - InvalidResponseStructure, ResponseParsingError: Probably something went wrong in the call, as the response from the API is invalid. If you need help, feel free to contact us!

[Option 2]: Upload via API

Another way to do the same thing is by using our API directly. The relevant API documentation can be found here.

Authentication

The paretos API endpoints require token authentication using a Bearer token. You can request a token using the following endpoint after filling in your credentials in the username and password field.

curl --location --request POST 'https://auth.paretos.io/auth/realms/paretos/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=YOUR_EMAIL' \
--data-urlencode 'password=YOUR_PASSWORD' \
--data-urlencode 'client_id=main' \
--data-urlencode 'grant_type=password'

A request with valid credentials will return a response similar to the following. The required token is the "access token" in the JSON encoded response body.

{
    "access_token": "eyJmRu2QdfM3iVZTtTBLJGkapWnU8I9hxB5kAhfWO2KL1VYJXNZxnV8UGTciCh8IyQC-JSAmXzBQHd9FRA1_CpHMCQO0IGLgJpINx6I-g",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIM6Ly9hdXRoLnBhcmV0b3MuaW8vYXV0aC9yXRvcyIsImFhcmV0b3MiLCJzdWpIZ7py-9XihV-oLnyLCidgzqly8PTE0_s",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "4445f05a-6d30-4833-83de-94b4080200a5",
    "scope": "email profile"
}

Note

The tokens are only valid for a few minutes. You will need to request a new token before accessing the API at a later time.

Uploading Training Data

The following request can be used to upload training data via the API after filling in the these fields:

  • Bearer (access token received by authentication)
  • useCaseId (displayed in Cockpit)
  • trainingDataFile (Path to local training data file)
curl --location --request POST 'https://use-case.paretos.com/v4/trainingDataFiles/upload' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--form 'useCaseId="YOUR_USE_CASE_ID"' \
--form 'trainingDataFile=@"PATH_TO_FILE"'

A request with valid input will return a response similar to the following:

{
    "status": "success",
    "data": {
        "message": "Uploaded FILENAME.csv"
    },
    "meta": {
        "requestId": "5b0a73ef-6b5c-4c9e-bebb-fac56d77c213",
        "service": "use_case_api",
        "version": "2.x.x"
    }
}