Run Lifecycle

Create a Run

import goodseed

run = goodseed.Run(
    name="my-experiment",           # display name (sys/name)
    project="default",              # group runs by project
    description="Fine-tuning LLM",  # free-form text (sys/description)
    tags=["bert", "finetune"],      # tags (sys/tags)
    run_id="custom-id",             # unique ID (auto-generated if omitted)
    goodseed_home="~/.goodseed",    # data directory override
    log_dir="/path/to/dir",         # override DB file location
)

If run_id is not provided, it falls back to the GOODSEED_RUN_ID environment variable, then auto-generates a readable ID like bold-falcon.

Close

Close the run when you’re done logging:

run = goodseed.Run(name="my-experiment")
run["train/loss"].log(0.5, step=0)
run.close()  # status='finished'

You can also set the status explicitly:

run.close(status='failed') # explicit failure

If you forget to call close(), GoodSeed registers best-effort per-run cleanup at interpreter exit. For guaranteed upload completion, call close() explicitly or use a context manager.

Resume a Run

Resume a previously closed run to add new data or continue training:

run = goodseed.Run(resume_run_id="bold-falcon")

# Continue logging
run["train/loss"].log(0.3, step=123)

# Add new fields
run["eval/f1"] = 0.85

run.close()

A run can only be resumed if it is not currently running. If the run is still active, you’ll get an error.

Tags

Add tags at creation or later via the sys/tags field:

# At creation
run = goodseed.Run(tags=["bert", "finetune"])

# Add more tags later
run["sys/tags"].add("production")
run["sys/tags"].add(["v2", "release"])

Automatic Namespaces

Each run auto-populates three namespaces:

Namespace	Contents
sys/	Run metadata: id, name, description, tags, creation_time, state
monitoring/	Hardware metrics (CPU, GPU), stdout/stderr streams, tracebacks
source_code/	Git info, diffs

You can edit sys/ fields via bracket assignment:

run["sys/name"] = "new-name"
run["sys/description"] = "updated description"