API Reference

This page provides a detailed reference for the Jingongo SDK class, its methods, and custom exceptions.

The Jingongo Class

This is the main class for interacting with the Jingongo API.

Jingongo(api_base_url, api_key, verbose)

Initializes the SDK client and validates the provided API key.

from jingongo import Jingongo
 
# Example Initialization
API_BASE_URL = "https://jingongo-backend-api-723715926581.us-central1.run.app"
API_KEY = "YOUR_PERMANENT_API_KEY"
 
client = Jingongo(
    api_base_url=API_BASE_URL, 
    api_key=API_KEY,
    verbose=True  # Optional: enables detailed SDK logging
)

Parameters:

• api_base_url (str): The base URL of your Jingongo cloud API.
• api_key (str): Your long-lived API key for programmatic access.
• verbose (bool, optional): If True, enables detailed logging from the SDK to the console. Defaults to False.

Class Methods

convert_to_fmu(project_path, **kwargs)

Converts a local digital twin project (Python or C) into an FMU via the Jingongo cloud service.

# Example: Convert a Python model
conversion_job = client.convert_to_fmu(
    project_path="./examples/example_models/python_identity_block_model",
    language="python",
    wait_for_completion=True, # Polls until the job is done
    poll_interval=5           # Seconds between status checks
)
 
print(conversion_job)

Parameters:

• project_path (str | Path): The local file path to the root directory of your model project.
• wait_for_completion (bool, optional): If True, the method will block and poll the API until the conversion is COMPLETED or FAILED. Defaults to True.
• poll_interval (int, optional): The number of seconds to wait between status checks when wait_for_completion is True. Defaults to 5.
• **kwargs: Additional configuration options (like model_name, version, language) can be passed as keyword arguments. These will override any values found in a .jingongo.yml file.

Returns:

• (dict): A dictionary containing the final job status from the API.

download_fmu(job_id, download_dir)

Downloads a completed FMU from the cloud to a local directory.

# Example: Download the FMU for a specific job
job_id = "conversion-job-xxxx-yyyy" # Get this from list_models()
local_path = client.download_fmu(job_id, download_dir="./my_fmus")
 
print(f"FMU downloaded to: {local_path}")

Parameters:

• job_id (str): The ID of the completed conversion job for the desired FMU.
• download_dir (str | Path, optional): The local directory to save the file in. Defaults to the current directory (.).

Returns:

• (pathlib.Path): The full Path object to the downloaded FMU file.

list_models(limit)

Retrieves a list of the most recent FMU conversion jobs for your account.

# Example: List the 20 most recent models
models = client.list_models(limit=20)
 
for model in models:
    print(f"ID: {model['job_id']}, Status: {model['status']}")

Parameters:

• limit (int, optional): The maximum number of models to return. Defaults to 20.

Returns:

• (list[dict]): A list of dictionaries, where each dictionary represents a conversion job.

get_conversion_status(job_id)

Retrieves the real-time status of a specific FMU conversion job.

# Example: Get status for a specific job
status = client.get_conversion_status("conversion-job-xxxx-yyyy")
 
print(f"Current status: {status['status']}")

Parameters:

• job_id (str): The ID of the conversion job to check.

Returns:

• (dict): A dictionary containing the current job status details.

check_health()

Checks the health of the remote Jingongo Backend API.

# Example: Verify API connectivity
try:
    health = client.check_health()
    print("API is healthy:", health)
except JingongoAPIError as e:
    print("API is unreachable:", e)

Returns:

• (dict): A dictionary containing the health status from the API.

Static Methods

These methods can be called directly from the class without creating an instance.

Jingongo.generate_api_key_from_token(api_base_url, id_token)

Uses a short-lived user ID token (from the web portal) to generate a new long-lived API key.

# You must first set the TEMPORARY_USER_TOKEN environment variable
import os
from jingongo import Jingongo
 
temp_token = os.environ.get("TEMPORARY_USER_TOKEN")
if temp_token:
    new_key = Jingongo.generate_api_key_from_token(
        api_base_url="https://jingongo-backend-api-723715926581.us-central1.run.app",
        id_token=temp_token
    )
    print("New API Key:", new_key)

Parameters:

• api_base_url (str): The base URL of the Jingongo backend API.
• id_token (str): The short-lived Firebase ID Token obtained from the web portal.

Returns:

• (str): The new, long-lived API key.

Custom Exceptions

The SDK uses custom exceptions to allow for specific error handling.

• JingongoAuthError: Raised for authentication failures (e.g., an invalid API key).
• JingongoAPIError: Raised for general API communication errors (e.g., the server is down, a bad request was sent).
• JingongoConversionError: Raised when a specific FMU conversion job fails on the backend.