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
)Copied!

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'Copied!

You can also set the status explicitly:

run.close(status='failed') # explicit failureCopied!

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()Copied!

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"])Copied!

Automatic Namespaces #

Each run auto-populates three namespaces:

You can edit sys/ fields via bracket assignment:

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