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 uploadedCopied!

The sync process runs as a separate OS process. The local SQLite database serves as the durable queue — if the process is interrupted, unuploaded data is preserved and can be uploaded later.

To disable remote sync (local-only):

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

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}]Copied!

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).

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:

Or upload programmatically:

from goodseed.sync import upload_run

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