treble_tsdk.tsdk

Main TSDK module providing authentication and library access.

Provides the TSDK class for authenticating with the Treble API and accessing material, geometry, device, and source directivity libraries.

class treble_tsdk.tsdk.TSDK

Bases: object

Main SDK client

Provides access to materials, geometries, projects, simulations, and results through organized library interfaces.

__init__(credentials: TSDKCredentials | None = None)

check_for_updates() → SdkVersionDto | None

Check if SDK updates are available.

Returns SdkVersionDto | None:: Update information or None if no updates.

check_rate_limit() → int | None

Check current API rate limit status.

Returns int | None:: Remaining rate limit or None if not available.

check_status(): Check the status of the Treble API service.

check_terms_and_conditions(): Verify that the user has accepted the terms and conditions.

Create a TSDK Project. Projects are used to organize simulation, each simulation belong to a project. The project, and its associated simulations, can later be accessed with the method get_project()

Parameters:

name (str) – Name of the project
description (str) – A short description of the project, defaults to None
tags (list[str]) – Tags to add to the project.

Returns:

A Project object which can be used to add simulations to

Return type:

Project

delete_project(project: Project | str, force: bool = False) → bool

Remove a project from the record. Be careful not to delete anything you are not sure you want to delete

Parameters:

project (Project | str) – The id of the project you want to delete
force (bool) – If true, the project will be deleted even if it contains running simulations. The simulations will be cancelled.

display_user_info(): Display current user information including email and organization.

download_update(download_dir: str) → str | None: Downloads update wheel to the specified directory. Returns the path to the wheel file.

get_by_name(name: str) → Project | None

Gets a project by name, if multiple projects match the name the one created the most recently is returned.

Parameters:: name (str) – Name of project to get.
Returns:: A Project object, containing the requested project or None if no project is found.

get_or_create_project(name: str, description: str | None = None) → Project

Looks for a project with the given name, if it’s not found it will create the project

Parameters:

name (str) – project name
description (str, optional) – description of the project. Defaults to None.

Returns:

loaded or new project

Return type:

Project

get_overview(filter_user: str = False) → OverviewDto

Get a report of running/queued simulations.

Parameters:: filter_user – If true then it will only show/report the simulations the logged in user has created.

get_project(project_id: ProjectDto | str) → Project | None

Get the project with the associated id, from the project object you can access the simulations which belong to that project.

To find the project id, you can run list_projects() and for the relevant entry you can access the id instance attribute of the project

Parameters:: project_id (ProjectDto | str) – Project DTO or unique id of the requested project.
Return Project:: A class instance of Project, containing the requested project

get_project_by_name(name: str) → Project | None

Gets a project by name, if multiple projects match the name the one created the most recently is returned.

Parameters:: name (str) – Name of project to get.
Returns:: A Project object, containing the requested project or None if no project is found.

get_project_from_results_directory(results_dir: str | Path) → Project | None

Get Project object from a results directory.

Parameters:: results_dir (str|Path) – Path to either a simulation_info json file or a directory that contains previously downloaded simulation results.
Returns:: Project that the simulation belongs to.

get_projects() → list[Project]

Listing the projects with information useful to identify the project which is of interest. Each element of the list is an object containing information about the associated project. Elements of the list can be queried to access information such as the ids of the projects

Returns list[Project]:: Returns a list of Project objects.

get_results_object_from_results_directory(results_dir: str | Path, results_type: str = None) → 'Results' | None: Get ResultsObject object from a results directory.

get_simulation_from_results_directory(results_dir: str | Path) → Simulation | None

Get Simulation object from a results directory.

Parameters:: results_dir (str|Path) – Path to either a simulation_info json file or a directory that contains previously downloaded simulation results.
Returns:: Simulation that the simulation_info belongs to.

get_token_status() → TokenStatusDto: Get current status of tokens available to the user/organization.

get_update_url() → str

Get the URL for downloading SDK updates.

Returns str:: Update download URL.

list_my_projects() → list[Project]: list all projects created by the logged in user :returns list[Project]: Returns a list of Project objects.

list_projects() → list[Project]

Returns list[Project]:: Returns a list of Project objects.

static login() → TSDK

Interactive login using OAuth device code flow.

This is the recommended way to authenticate in shared or headless environments (similar to gh auth login, az login --use-device-code, gcloud auth login).

No credentials, secrets, or tokens are needed — the user authenticates in their browser and the SDK receives short-lived tokens automatically.

Uses the same Auth0 tenant and user database as the management portal SSO.

Returns TSDK:: Authenticated TSDK instance.
Raises:: DeviceCodeFlowError – If the device code flow fails.

Example:

from treble_tsdk.tsdk import TSDK

# Interactive login — prints a URL and code, waits for browser auth
tsdk = TSDK.login()

# Then use the SDK as normal
projects = tsdk.list_projects()

preliminary_checks(): Run preliminary checks including cache cleanup, rate limits, updates, and terms acceptance.

refresh_authentication(cred: TSDKCredentials | None = None)

Re-authenticate the SDK using updated credentials.

Works with all authentication methods:

Device code (TSDK.login()): call with no arguments to re-run the interactive device code flow automatically.
SSO: pass TSDKCredentials.sso(token) with a fresh token.
Client credentials: pass a new TSDKCredentials or leave empty to reload from the environment.

Parameters:: cred (TSDKCredentials) – Updated credentials to use. When None and auth_method is device-code, the interactive flow is re-run; other sessions reload credentials from the environment.

rename_project(project: Project, new_name: str) → Project | None

Rename a project.

Parameters:

project (Project) – Project object to rename.
new_name (str) – New name for project.

set_random_seed(seed: int | None = None): Set the random seed for random number generators used by the SDK. This will set global random seeds for np.random and python random.

property boundary_velocity_submodel_library: BoundaryVelocitySubmodelLibrary

Library for browsing and retrieving boundary velocity submodels.

Provides methods to search and manage submodel definitions used as boundary velocity sources in simulations.

property collections: CollectionsLibrary

Access to the collections library for managing data collections.

Returns CollectionsLibrary:: Collections library instance.

property datasets

Access to the datasets library for viewing and purchasing datasets (MOCKUP VERSION).

Returns DatasetLibrary:: Dataset library instance.

property device_library: DeviceLibrary

Library for managing device definitions.

Provides methods to upload, browse, and delete device microphone array configurations.

property geometry_component_library: GeometryComponentLibrary

Library for browsing and retrieving geometry components.

Provides methods to search and manage reusable geometry component definitions for building simulation models.

property geometry_library: GeometryLibrary

Library for browsing and retrieving pre-built geometry objects.

Provides methods to search, download, and manage geometry datasets for use in simulation projects.

property material_library: MaterialLibrary

Library for browsing and retrieving acoustic materials.

Provides methods to search materials by name, ID, or category for use in simulation models.

property source_directivity_library: SourceDirectivityLibrary

Library for browsing and retrieving source directivity patterns.

Provides methods to search, import, and manage directivity data for acoustic sources.

property source_receiver_device_library: SourceReceiverDeviceLibrary

Library for managing source receiver devices.

Provides methods to create, browse, rename, and delete source receiver devices.

class treble_tsdk.tsdk.TSDKCredentials

Bases: object

TSDK credentials container. Credentials can be stored

exception CredentialsNotFoundException

Bases: Exception

__init__(*args, **kwargs)

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception InvalidEnvironmentNameException

Bases: Exception

Exception raised when an invalid environment name is provided.

Valid environments are: local, test, dev, prod.

__init__(*args, **kwargs)

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

__init__(client_id: str, client_secret: str | None = None, environment: str | None = None, is_sso: bool = False)

Creates a TSDKCredentials container. This class can either be initialized by supplying a TSDK credentials string or client_id and client_secret variables. F.ex: cred = TSDKCredentials(“bG9vayBhdCB5b3UsIGhhY2tlcg==”) cred = TSDKCredentials(“my client_id”, “my client_secret”)

Parameters:

client_id – client_id or credentials string
client_secret – if client_id is provided then client_secret is required.
environment – Environment should be set if using client_id+client_secret and connecting to a specific environment.

static device_code() → TSDKCredentials

Create credentials using the interactive OAuth device code flow.

This is the recommended authentication method for shared or headless environments. No secrets are needed — the user authenticates in their browser.

The flow:

A device code and user code are displayed
The user visits the verification URL and enters the code
The user authenticates in their browser
The SDK receives short-lived tokens automatically

This uses the same Auth0 tenant, API, and user database as the existing management portal SSO flow. The only requirement is a Native-type Auth0 application with the “Device Code” grant type enabled.

Returns TSDKCredentials:

Credentials object for device code authentication.

Raises:

DeviceCodeFlowError – If the device code flow fails.
DeviceCodeExpiredError – If the code expires before authentication.
DeviceCodeAccessDeniedError – If the user denies authorization.

Example:

from treble_tsdk.tsdk import TSDK, TSDKCredentials

# Interactive login (prints instructions, waits for browser auth)
cred = TSDKCredentials.device_code()
tsdk = TSDK(cred)

# Or use the convenience method:
tsdk = TSDK.login()

static from_file(cred_file_path: str) → TSDKCredentials

Load TSDKCredentials container from a credentials file.

Parameters:: cred_file_path – Path to TSDK .cred file.

static sso(token: str | None = None) → TSDKCredentials

Create credentials from SSO token.

Parameters:: token (str) – SSO token string, or None to read from TSDK_SSO_TOKEN environment variable.
Returns TSDKCredentials:: Credentials object for SSO authentication.