The `Client` class¶

Class for querying a Simvue server instance.

Methods¶

init(...)¶

Initialise an instance of the Simvue client

Parameters


server_token	`pydantic.types.SecretStr \| None`	`= None`	specify token, if unset this is read from the config file
server_url	`str \| None`	`= None`	specify URL, if unset this is read from the config file

abort_run(...)¶

Abort a currently active run on the server

Parameters


run_id	`str`		the unique identifier for the run
reason	`str`		reason for abort

Returns

dict | list

response from server

delete_alert(...)¶

Delete an alert from the server by ID

Parameters


alert_id	`str`		the unique identifier for the alert

delete_folder(...)¶

Delete a folder by name

Parameters


folder_path	`Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^/.*')])]`		name of the folder to delete. All paths are prefixed with `/`
recursive	`bool`	`= False`	if folder contains additional folders remove these, else return an error. Default False.
remove_runs	`bool`	`= False`	whether to delete runs associated with this folder, by default False
allow_missing	`bool`	`= False`	allows deletion of folders which do not exist, else raise exception, default is exception raise

Returns

list | None

if a folder is identified the runs also removed during execution

Raises

RuntimeError

if deletion of the folder from the server failed

delete_run(...)¶

Delete run by identifier

Parameters


run_id	`str`		the unique identifier for the run

Returns

dict | None

the request response after deletion

Raises

RuntimeError

if the deletion failed due to server request error

delete_runs(...)¶

Delete runs in a named folder

Parameters


folder_path	`Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^/.*')])]`		the path of the folder on which to perform deletion. All folder paths are prefixed with `/`

Returns

list | None

List of deleted runs

Raises

RuntimeError

if deletion fails due to server request error

delete_tag(...)¶

Delete a tag by its identifier

Parameters


tag_id	`str`		unique identifier for the tag

Raises

RuntimeError

if the deletion failed due to a server request error

get_alerts(...)¶

Retrieve alerts for a given run

Parameters


run_id	`str \| None`	`= None`	The ID of the run to find alerts for
critical_only	`bool`	`= True`	If a run is specified, whether to only return details about alerts which are currently critical, by default True
names_only	`bool`	`= True`	Whether to only return the names of the alerts (otherwise return the full details of the alerts), by default True
start_index	`Optional[Annotated[int, Ge(ge=0)]]`	`= None`	slice results returning only those above this index, by default None
count_limit	`Optional[Annotated[int, Gt(gt=0)]]`	`= None`	limit number of returned results, by default None
sort_by_columns	`list[tuple[str, bool]] \| None`	`= None`	sort by columns in the order given, list of tuples in the form (column_name: str, sort_descending: bool), default is None.

Returns

list[dict[str, Any]]

a list of all alerts for this run which match the constrains specified

Raises

RuntimeError

if there was a failure retrieving data from the server

get_artifact(...)¶

Return the contents of a specified artifact

Parameters


run_id	`str`		the unique identifier of the run from which to retrieve the artifact
name	`str`		the name of the artifact to retrieve
allow_pickle	`bool`	`= False`	whether to de-pickle the retrieved data, by default False

Returns

de-serialized content of artifact if retrieved, else content of the server response

Raises

RuntimeError

if retrieval of artifact from the server failed

get_artifact_as_file(...)¶

Retrieve the specified artifact in the form of a file Information is saved to a file as opposed to deserialized

Parameters


run_id	`str`		unique identifier for the run to be queried
name	`str`		the name of the artifact to be retrieved
output_dir	`Optional[Annotated[pathlib._local.Path, Path(path_type='dir')]]`	`= None`	path to download retrieved content to, the default of None uses the current working directory.

Raises

RuntimeError

if there was a failure during retrieval of information from the server

get_artifacts_as_files(...)¶

Retrieve artifacts from the given run as a set of files

Parameters


run_id	`str`		the unique identifier for the run
category	`Optional[Literal['input', 'output', 'code']]`	`= None`	category of file to retrieve, default of None returns all `input` - this file is an input file. `output` - this file is created by the run. `code` - this file represents an executed script
output_dir	`Optional[Annotated[pathlib._local.Path, Path(path_type='dir')]]`	`= None`	location to download files to, the default of None will download them to the current working directory

Raises

RuntimeError

if there was a failure retrieving artifacts from the server

get_events(...)¶

Return events for a specified run

Parameters


run_id	`str`		the unique identifier of the run to query
message_contains	`str \| None`	`= None`	filter to events with message containing this expression, by default None
start_index	`Optional[Annotated[int, Ge(ge=0)]]`	`= None`	slice results returning only those above this index, by default None
count_limit	`Optional[Annotated[int, Gt(gt=0)]]`	`= None`	limit number of returned results, by default None

Returns

list[dict[str, str]]

list of matching events containing entries with message and timestamp data

Raises

RuntimeError

if there was a failure retrieving information from the server

get_folder(...)¶

Retrieve a folder by identifier

Parameters


folder_path	`Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^/.*')])]`		the path of the folder to retrieve on the server. Paths are prefixed with `/`
read_only	`bool`	`= True`	whether the returned object should be editable or not, default is True, the object is a cached copy of data from the server.

Returns

Folder | None

data for the requested folder if it exists else None

Raises

RuntimeError

if there was a failure when retrieving information from the server

get_folders(...)¶

Retrieve folders from the server

Parameters


filters	`list[str] \| None`	`= None`	set of filters to apply to the search
count	`Annotated[int, Gt(gt=0)]`	`= 100`	maximum number of entries to return. Default is 100.
start_index	`Annotated[int, Ge(ge=0)]`	`= 0`	the index from which to count entries. Default is 0.
sort_by_columns	`list[tuple[str, bool]] \| None`	`= None`	sort by columns in the order given, list of tuples in the form (column_name: str, sort_descending: bool), default is None.

Returns

Generator[str, Folder]

all data for folders matching the filter request in form (id, Folder)

Raises

RuntimeError

if there was a failure retrieving data from the server

get_metric_values(...)¶

Retrieve the values for a given metric across multiple runs Uses filters to specify which runs should be retrieved. NOTE if the number of runs exceeds 100 'aggregated' will be set to True, and aggregated is not supported for the 'timestamp' xaxis format

Parameters


metric_names	`list[str]`		the names of metrics to return values for
xaxis	`Literal['step', 'time', 'timestamp']`		the x-axis type `step` - enumeration. `time` - time in seconds. `timestamp` - time stamp.
output_format	`Literal['dataframe', 'dict']`	`= dict`	the format of the output `dict` - python dictionary of values (default). `dataframe` - values as dataframe (requires Pandas).
run_ids	`list[str] \| None`	`= None`	list of runs by id to include within metric retrieval
run_filters	`list[str] \| None`	`= None`	filters for specifying runs to include
use_run_names	`bool`	`= False`	use run names as opposed to IDs, note this is not recommended for multiple runs with the same name. Default is False.
aggregate	`bool`	`= False`	return results as averages (not compatible with xaxis=timestamp), default is False
max_points	`Optional[Annotated[int, Gt(gt=0)]]`	`= None`	maximum number of data points, by default None (all)

Returns

dict or DataFrame or None

values for the given metric at each time interval if no runs pass filtering then return None

get_metrics_names(...)¶

Return information on all metrics within a run

Parameters


run_id	`str`		unique identifier of the run

Returns

Generator[str, None, None]

names of metrics in the given run

Raises

RuntimeError

if there was a failure retrieving information from the server

get_run(...)¶

Retrieve a single run

Parameters


run_id	`str`		the unique identifier for this run

Returns

dict[str, Any]

response containing information on the given run

Raises

RuntimeError

if retrieval of information from the server on this run failed

get_run_id_from_name(...)¶

Get Run ID from the server matching the specified name Assumes a unique name for this run. If multiple results are found this method will fail.

Parameters


name	`Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^[a-zA-Z0-9\\-\\_\\s\\/\\.:]+$')])]`		the name of the run

Returns

str

the unique identifier for this run

Raises

RuntimeError

if either information could not be retrieved from the server, or multiple/no runs are found

get_run_name_from_id(...)¶

Retrieve the name of a run from its identifier

Parameters


run_id	`str`		the unique identifier for the run

Returns

str

the registered name for the run

get_runs(...)¶

Retrieve all runs matching filters.

Parameters


filters	`list[str] \| None`		set of filters to apply to query results. If None is specified return all results without filtering.
metadata	`bool`	`= False`	whether to include metadata information in the response. Default False.
metrics	`bool`	`= False`	whether to include metrics information in the response. Default False.
alerts	`bool`	`= False`	whether to include alert information in the response. Default False.
output_format	`Literal['dict', 'objects', 'dataframe']`	`= objects`	the structure of the response `dict` - dictionary of values. `objects` - a dictionary of objects (default). `dataframe` - a dataframe (Pandas must be installed).
count_limit	`Optional[Annotated[int, Gt(gt=0)]]`	`= 100`	maximum number of entries to return. Default is 100.
start_index	`Annotated[int, Ge(ge=0)]`	`= 0`	the index from which to count entries. Default is 0.
show_shared	`bool`	`= False`	whether to include runs shared with the current user. Default is False.
sort_by_columns	`list[tuple[str, bool]] \| None`	`= None`	sort by columns in the order given, list of tuples in the form (column_name: str, sort_descending: bool), default is None.

Yields

tuple[str, Run]

identifier and Run object

Returns

pandas.DataFrame | Generator[tuple[str, Run], None, None]

either the JSON response from the runs request or the results in the form of a Pandas DataFrame

Raises

ValueError

if a value outside of 'dict' or 'dataframe' is specified RuntimeError if there was a failure in data retrieval from the server

get_tag(...)¶

Retrieve a single tag

Parameters


tag_id	`str`		the unique identifier for this tag

Returns

Tag

response containing information on the given tag

Raises

RuntimeError

if retrieval of information from the server on this tag failed

get_tags(...)¶

Retrieve tags

Parameters


start_index	`Optional[Annotated[int, Ge(ge=0)]]`	`= None`	slice results returning only those above this index, by default None
count_limit	`Optional[Annotated[int, Gt(gt=0)]]`	`= None`	limit number of returned results, by default None
sort_by_columns	`list[tuple[str, bool]] \| None`	`= None`	sort by columns in the order given, list of tuples in the form (column_name: str, sort_descending: bool), default is None.

Returns

yields

tag identifier tag object

Raises

RuntimeError

if there was a failure retrieving data from the server

list_artifacts(...)¶

Retrieve artifacts for a given run

Parameters


run_id	`str`		unique identifier for the run
sort_by_columns	`list[tuple[str, bool]] \| None`	`= None`	sort by columns in the order given, list of tuples in the form (column_name: str, sort_descending: bool), default is None.

Yields

str, Artifact

ID and artifact entry for relevant artifacts

Raises

RuntimeError

if retrieval of artifacts failed when communicating with the server

plot_metrics(...)¶

Plt the time series values for multiple metrics/runs

Parameters


run_ids	`list[str]`		unique identifiers for runs to plot
metric_names	`list[str]`		names of metrics to plot
xaxis	`Literal['step', 'time']`		the x axis to plot against
max_points	`int \| None`	`= None`	maximum number of data points, by default None (all)

Returns

Figure

plot figure object

Raises

ValueError

if invalid arguments are provided

The Client class¶

Methods¶

__init__(...)¶

abort_run(...)¶

delete_alert(...)¶

delete_folder(...)¶

delete_run(...)¶

delete_runs(...)¶

delete_tag(...)¶

get_alerts(...)¶

get_artifact(...)¶

get_artifact_as_file(...)¶

get_artifacts_as_files(...)¶

get_events(...)¶

get_folder(...)¶

get_folders(...)¶

get_metric_values(...)¶

get_metrics_names(...)¶

get_run(...)¶

get_run_id_from_name(...)¶

get_run_name_from_id(...)¶

get_runs(...)¶

get_tag(...)¶

get_tags(...)¶

list_artifacts(...)¶

plot_metrics(...)¶

The `Client` class¶

init(...)¶