🧾 API Reference¶
Main Tracker¶
RuneLog(path='.')
¶
A lightweight tracker for ML experiments.
This class handles the creation of experiments, management of runs, and logging of parameters, metrics, and artifacts to the local filesystem. It also provides a model registry for versioning and managing models.
Initializes the tracker and creates required directories.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
The root directory for storing all tracking data. Defaults to the current directory. |
'.'
|
add_model_tags(model_name, version, tags)
¶
Retrieves the tags for a specific registered model version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model_name
|
str
|
The name of the registered model. |
required |
version
|
str
|
The version from which to retrieve tags. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
A dictionary of the model version's tags. |
Raises:
| Type | Description |
|---|---|
ModelVersionNotFound
|
If the model or version is not found. |
delete_experiment(experiment_name_or_id)
¶
Deletes an experiment and all of its associated runs and artifacts. This is a destructive operation and cannot be undone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
experiment_name_or_id
|
str
|
The name or ID of the experiment to delete. |
required |
Raises:
| Type | Description |
|---|---|
ExperimentNotFound
|
If no experiment with the given name or ID is found. |
delete_run(run_id)
¶
Deletes a run and all of its associated artifacts.
This is a destructive operation and cannot be undone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id
|
str
|
The ID of the run to delete. |
required |
Raises:
| Type | Description |
|---|---|
RunNotFound
|
If no run with the given ID is found. |
get_artifact_abspath(run_id, artifact_name)
¶
Gets the absolute path of a specific artifact from a given run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id
|
str
|
The ID of the run containing the artifact. |
required |
artifact_name
|
str
|
The filename of the artifact. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The absolute, local path to the artifact file. |
Raises:
| Type | Description |
|---|---|
RunNotFound
|
If the run ID does not exist. |
ArtifactNotFound
|
If the artifact name does not exist in the run. |
get_experiment(experiment_id)
¶
Gets the metadata for a single experiment by its ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
experiment_id
|
str
|
The ID of the experiment to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
Optional[Dict]
|
Optional[Dict]: A dictionary containing the experiment's metadata, or None if not found. |
get_experiment_runs(experiment_id, sort_by=None, ascending=True)
¶
Return a list of individual runs for the given experiment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
experiment_id
|
str
|
The ID of the experiment to query. |
required |
sort_by
|
Optional[str]
|
Field to sort runs by (e.g., "timestamp"). Defaults to "timestamp". Set to None to disable sorting. |
None
|
ascending
|
bool
|
Sort order. Defaults to True. |
True
|
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: A list of run dictionaries, each containing: - run_id (str): Folder name or unique ID of the run. - timestamp (str | None): ISO 8601 timestamp of the run, or None. - status (str | None): Run status if available in meta.json. - other metadata keys as present in meta.json. |
get_experiment_summaries(sort_by=None, ascending=True)
¶
Obtain summaries for all experiments, including run statistics: number of runs, the timestamp of the most recent run, and the creation time of the experiment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sort_by
|
Optional[str]
|
Field to sort summaries by (e.g., "name", "num_runs", "last_run"). Defaults to None (no sorting). |
None
|
ascending
|
bool
|
Sort order. Defaults to True. |
True
|
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: A list of dictionaries, each representing a summarized view |
List[Dict]
|
of an experiment. Each dictionary contains: - experiment_id (str): Unique identifier of the experiment. - name (str): Human-readable name of the experiment. - created_at (str | None): ISO 8601 timestamp of the experiment's creation, or None if not available. - num_runs (int): Total number of runs recorded for the experiment. - last_run (str | None): ISO 8601 timestamp of the most recent run, or None if no runs exist. |
get_model_tags(model_name, version)
¶
Retrieves the tags for a specific registered model version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model_name
|
str
|
The name of the registered model. |
required |
version
|
str
|
The version from which to retrieve tags. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
dict
|
A dictionary of the model version's tags. |
Raises:
| Type | Description |
|---|---|
ModelVersionNotFound
|
If the model or version is not found. |
get_model_versions(model_name, sort_by='version', ascending=False)
¶
Gets all versions and their metadata for a registered model.
The versions are returned sorted from newest to oldest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model_name
|
str
|
The name of the model to retrieve versions for. |
required |
sort_by
|
Optional[str]
|
Field to sort by (e.g., "version", "registration_timestamp"). Sorted by 'version' by default. |
'version'
|
ascending
|
bool
|
Sort order. Defaults to True (newest first). |
False
|
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: A list of metadata dictionaries, where each dictionary represents a single version of the model. Returns an empty list if the model is not found. |
get_or_create_experiment(name)
¶
Gets an existing experiment by name or creates a new one.
If an experiment with the given name already exists, its ID is returned. Otherwise, a new experiment is created.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the experiment. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The unique ID of the new or existing experiment. |
get_run(run_id)
¶
Loads the parameters and metrics for a specific run.
This method provides a summarized view of a run's data, primarily for
use in creating tabular summaries like in load_results. It assumes
that run_id is unique across all experiments.
Note
For a more detailed dictionary that includes artifacts, see the
get_run_details() method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id
|
str
|
The unique ID of the run to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
Optional[Dict]
|
Optional[Dict]: A dictionary containing the |
get_run_details(run_id)
¶
Loads all details for a specific run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id
|
str
|
The unique ID of the run to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
Optional[Dict]
|
Optional[Dict]: A dictionary containing the run's 'params', 'metrics', and 'artifacts', or None if the run is not found. |
list_experiments()
¶
Lists all available experiments.
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: A list of dictionaries, where each dictionary contains the metadata of an experiment (e.g., name and ID). |
list_registered_models(ascending=True)
¶
Lists the names of all models in the registry.
Returns:
| Type | Description |
|---|---|
List[str]
|
List[str]: A list of names of all registered models. |
load_registered_model(model_name, version='latest')
¶
Loads a model from the model registry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model_name
|
str
|
The name of the registered model. |
required |
version
|
str
|
The version to load. Can be a specific version number or "latest". Defaults to "latest". |
'latest'
|
Returns:
| Name | Type | Description |
|---|---|---|
Any |
Any
|
The loaded model object. |
Raises:
| Type | Description |
|---|---|
ModelNotFound
|
If no model with the given name is found. |
NoVersionsFound
|
If the model exists but has no versions. |
ModelVersionNotFound
|
If the specified version is not found for the model. |
load_results(experiment_name_or_id, sort_by=None, ascending=True)
¶
Loads all run data from an experiment into a pandas DataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
experiment_name_or_id
|
str
|
The ID of the experiment to load. |
required |
sort_by
|
Optional[str]
|
Column to sort the DataFrame by. Defaults to None (sort by run_id index). |
None
|
ascending
|
bool
|
Sort order. Defaults to True. |
True
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: A DataFrame containing the parameters and metrics
for each run in the experiment, indexed by |
Raises:
| Type | Description |
|---|---|
ExperimentNotFound
|
If no experiment with the given ID is found. |
log_artifact(local_path)
¶
Logs a local file as an artifact of the active run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
local_path
|
str
|
The local path to the file to be logged as an artifact. |
required |
Raises:
| Type | Description |
|---|---|
NoActiveRun
|
If called outside of an active run context. |
ArtifactNotFound
|
If the file at |
log_metric(key, value)
¶
Logs a single metric for the active run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
The name of the metric. |
required |
value
|
float
|
The value of the metric. |
required |
Raises:
| Type | Description |
|---|---|
NoActiveRun
|
If called outside of an active run context. |
log_model(model, name, compress=3)
¶
Logs a trained model as an artifact of the active run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Any
|
The trained model object to be saved (e.g., a scikit-learn model). |
required |
name
|
str
|
The filename for the saved model (e.g., "model.pkl"). |
required |
compress
|
int
|
The level of compression for joblib from 0 to 9. Defaults to 3. |
3
|
Raises:
| Type | Description |
|---|---|
NoActiveRun
|
If called outside of an active run context. |
log_param(key, value)
¶
Logs a single parameter for the active run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
The name of the parameter. |
required |
value
|
Any
|
The value of the parameter. Must be JSON-serializable. |
required |
Raises:
| Type | Description |
|---|---|
NoActiveRun
|
If called outside of an active run context. |
register_model(run_id, artifact_name, model_name, tags=None)
¶
Registers a model from a run's artifacts to the model registry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
run_id
|
str
|
The ID of the run where the model artifact is stored. |
required |
artifact_name
|
str
|
The filename of the model artifact (e.g., "model.pkl"). |
required |
model_name
|
str
|
The name to register the model under. This can be a new or existing model name. |
required |
tags
|
Optional[Dict]
|
A dictionary of tags to add to the new model version. Defaults to None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The new version number of the registered model as a string. |
Raises:
| Type | Description |
|---|---|
RunNotFound
|
If no run with the given ID is found. |
ArtifactNotFound
|
If the specified artifact is not found in the run. |
start_run(experiment_name=None, experiment_id='0', log_git_meta=True, log_env=False, log_code=True)
¶
Starts a new run within an experiment as a context manager.
This is the primary method for creating a new run. It handles run creation, status updates, and can optionally log metadata about the execution environment for reproducibility.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
experiment_name
|
str
|
The name of the experiment. If it
doesn't exist, it will be created. This takes precedence over
|
None
|
experiment_id
|
str
|
The ID of the experiment. If neither name nor ID is provided, it defaults to "0" (the "Default" experiment). Defaults to None. |
'0'
|
log_git_metadata
|
bool
|
If True, logs Git metadata
(commit hash, branch, dirty status) to a |
required |
log_environment
|
bool
|
If True, logs the Python environment
(version, platform, packages) to |
required |
Yields:
| Name | Type | Description |
|---|---|---|
str |
str
|
The unique ID of the newly created run. |
Example
tracker = get_tracker() with tracker.start_run( ... experiment_name="example-experiment", ... log_environment=True ... ) as run_id: ... tracker.log_metric("accuracy", 0.95)