Remote Sync

Background Sync

By default, data is synced to the remote API in the background while your training runs. Set the GOODSEED_API_KEY environment variable and use workspace/project format for the project name:

import goodseed

run = goodseed.Run(project="my-workspace/my-project", name="experiment-1")
run["learning_rate"] = 0.001
for step in range(100):
    loss = train_step()
    run["train/loss"].log(loss, step=step)
run.close()  # blocks until all data is uploaded

The sync worker runs in a background thread. The local SQLite database serves as the durable queue — if sync is interrupted, unuploaded data is preserved and can be uploaded later.

To disable remote sync (local-only):

run = goodseed.Run(storage="local")

Read Data from Server

Open a run in read-only mode to fetch data from the remote API. No local storage is created and writes are disabled.

import goodseed

run = goodseed.Run(
    project="my-workspace/my-project",
    run_id="bold-falcon",
    read_only=True,
)

# Fetch metric data
paths = run.get_metric_paths()          # ["train/loss", "train/acc"]
data = run.get_metric_data("train/loss")
# data = {path, downsampled, raw_points: [{step, y}]}

# Fetch string series
spaths = run.get_string_paths()         # ["notes", ...]
sdata = run.get_string_data("notes")    # [{step, value}]

# Fetch configs
configs = run.get_configs()
# [{path, type_tag, value, updated_at}]

The API key is read from the GOODSEED_API_KEY environment variable, or can be passed directly via api_key=.

Fetching Methods

These methods work on any run with a remote connection — either read_only=True or storage="cloud" (the default when an API key is set).

Method	Returns
get_metric_paths()	List of metric path strings
get_metric_data(path)	Dict with path, downsampled, raw_points
get_string_paths()	List of string series path strings
get_string_data(path)	List of dicts: [{step, value}]
get_configs()	List of dicts: [{path, type_tag, value, updated_at}]

get_metric_data accepts optional step_min, step_max, and max_points keyword arguments for filtering and downsampling. get_string_data accepts optional limit and offset for pagination.

Manual Upload

If sync was disabled or interrupted, upload remaining data from the CLI:

goodseed upload -p <workspace/project> [-r <run_id>]

Or upload programmatically:

from goodseed.sync import upload_run

upload_run("/path/to/run.sqlite", api_key="gsk_...")