Skip to main content

00. jinko-sdk usage

How to use the jinko-sdk library​

The jinko-sdk library provides Python helper functions to simplify the use of Jinko's API, which is designed for trial simulation and design optimization. Jinko is an innovative SaaS and CaaS platform that offers programmatic access to a wide range of functionalities, facilitating integration with various tools and enhancing collaboration.
Package source can be found on Github: jinko-sdk

Installation​

To install the jinko-api-helpers-python library, you can use either pip or poetry:

pip install jinko-sdk

or

poetry add jinko-sdk

About the SDK​

The jinko-sdk is a Python SDK that includes useful functions to interact with Jinko's API. Please note that it is still in its early version, and while it provides essential functionalities, further enhancements and features are expected in future releases. We appreciate your feedback and contributions as we continue to develop this library.

Importing jinko_helpers​

In the rest of the documentation, we will import jinko_helpers as jinko.

Key Functions in jinko-sdk​

1. make_request​

The make_request function is used to send HTTP requests to the Jinko API. It handles different data formats, such as JSON and CSV, and offers flexible options for headers and response formats through the make_requestOptions class.

Function Definition:​

def make_request(
    path: str,
    method: str = "GET",
    json=None,
    csv_data=None,
    options: make_requestOptions = None,
    data=None,
) -> Response:
    """Makes an HTTP request to the Jinko API.
    
    Args:
        path (str): HTTP path
        method (str, optional): HTTP method. Defaults to 'GET'
        json (Any, optional): input payload as JSON. Defaults to None
        csv_data (str, optional): input payload as a CSV formatted string. Defaults to None
        options (make_requestOptions, optional): additional options. Defaults to None
        data (Any, optional): raw input payload. Defaults to None
    
    Returns:
        Response: HTTP response object
    
    Raises:
        requests.exceptions.HTTPError: if HTTP status code is not 200
    """

make_requestOptions​

The make_requestOptions class allows you to customize requests with attributes like:

  • name: The name for the project item.
  • description: A description for the project item.
  • folder_id: The folder where the item should be saved.
  • version_name: Version name for the project item.
  • input_format: The content type of the input (e.g., JSON or CSV).
  • output_format: The expected response format (e.g., JSON or CSV).

Usage Examples:​

  • Sending a simple GET request:

    response = jinko.make_request('/app/v1/auth/check')
    print(response.json())

  • Sending a POST request with JSON data and custom options:

    vpop_data = {...}
    jinko.make_request(
        path='/core/v2/vpop_manager/vpop',
        method='POST',
        json=vpop_data,
        options={
            "name": "My VPOP",
            "description": "Virtual population for drug simulation",
            "folder_id": folder_id,
            "input_format": "application/json",
            "output_format": "application/json"
        }
    )

  • Sending a POST request with CSV data:

    csv_data = "patientIndex,age,weight\n1,30,70\n2,45,80"
    jinko.make_request(
        path='/core/v2/vpop_manager/vpop',
        method='POST',
        data=csv_data,
        options={'input_format': 'text/csv'}
    )

2. get_core_item_id​

The get_core_item_id function retrieves the CoreItemId for a given project item using its short ID. This is helpful when working with project items like trials or models, where the CoreItemId is required for further operations.

Function Definition:​

def get_core_item_id(shortId: str, revision: int | None = None) -> CoreItemId:
    """Retrieves the CoreItemId corresponding to a ProjectItem.
    
    Args:
        shortId (str): short Id of the ProjectItem
        revision (int | None, optional): revision number. Defaults to None
    
    Returns:
        CoreItemId: corresponding CoreItemId
    
    Raises:
        Exception: if HTTP status code is not 200
        Exception: if this type of ProjectItem has no CoreItemId
    """

Usage Examples:​

  • Retrieve the CoreItemId of a project item:

    core_item_id = jinko.get_core_item_id('tr-EUsp-WjjI')
    print(core_item_id)

  • Retrieve the CoreItemId for a specific revision:

    core_item_id = jinko.get_core_item_id('tr-EUsp-WjjI', revision=2)
    print(core_item_id)

3. get_project_item_info_from_response​

The get_project_item_info_from_response function extracts important project item information from the response headers of a Jinko API request. This is particularly useful when creating or updating a project item, as the response contains metadata about the newly created or modified item.

Function Definition:​

def get_project_item_info_from_response(
    response: _requests.Response,
) -> ProjectItemInfoFromResponse | None:
    """Retrieves the information contained in the "X-jinko-project-item"
    header of the response.
    
    Args:
        response (Response): HTTP response object
    
    Returns:
        ProjectItemInfoFromResponse | None: ProjectItem informations or None if header does not exist
    """

Usage Examples:​

  • Extracting project item information after posting a model: 
    response = jinko.make_request(
        path="/core/v2/model_manager/jinko_model",
        method="POST",
        json={"model": model_data, "solvingOptions": solving_options}
    )
    project_item_info = jinko.get_project_item_info_from_response(response)
    print(project_item_info)

The get_project_item_info_from_response function will return a dictionary with metadata such as the sid, kind, and the CoreItemId and snapshotId of the project item.

4. get_project_item​

The get_project_item function retrieves a ProjectItem from its CoreItemId, snapshotId, or its SID and revision. This function allows flexible retrieval using different identifiers and is useful for accessing project items in Jinko's API.

Function Definition:​

def get_project_item(
    core_item_id=None,
    snapshot_id=None,
    sid: Optional[str] = None,
    url: Optional[str] = None,
    revision: Optional[float] = None,
    label: Optional[str] = None,
):
    """
    Retrieve a ProjectItem from its CoreItemId, snapshotId, or its SID and revision.

    Args:
        core_item_id (str, optional): The CoreItemId of the ProjectItem.
        snapshot_id (str, optional): The snapshotId of the ProjectItem.
        sid (str, optional): The SID of the ProjectItem.
        url (str, optional): The URL of the ProjectItem.
        revision (int, optional): The revision of the ProjectItem.
        label (str, optional): The label of the ProjectItem.

    Returns:
        ProjectItem, optional: The retrieved ProjectItem, or None if not found.

    Raises:
        ValueError: If neither 'sid' nor 'core_item_id' is provided.
        Exception: If the parameters are ambiguous, i.e., they do not point to the same project item.
    """

Usage Examples:​

  • Retrieving a project item using core_item_id:

    project_item = jinko.get_project_item(core_item_id="12345")
    print(project_item)

  • Retrieving a project item using sid and revision:

    project_item = jinko.get_project_item(sid="tr-EUsp-WjjI", revision=2)
    print(project_item)

  • Retrieving a project item using the url:

    project_item = jinko.get_project_item(url="https://jinko.ai/tr-EUsp-WjjI", label="v1.0")
    print(project_item)

  • Retrieving a project item using a labeled version:

    project_item = jinko.get_project_item(sid="tr-EUsp-WjjI", label="v1.0")
    print(project_item)