Python SDK

starforge.report — get curves into the console from any training script.

from starforge.report import init, log, finish

init(hparams={"lr": 1e-6, "kl_coef": 0.05})

for step, batch in enumerate(loader):
    loss = train_step(batch)
    log({"loss": loss, "reward": batch_reward}, step=step)

finish()

Three functions. No training framework is imported, nothing is subclassed, and the module works in any image that has starforge-core installed.

Install

Already present in every catalog image. For a custom image:

pip install starforge-core

The design constraints, because they change how you use it

Never raises

Reporting is a side channel. If collection breaks, your training keeps running. You do not need to wrap calls in try.

No-op without credentials

Running the same script on your laptop does nothing and makes no network calls, so there is no separate “local mode” branch to maintain.

Imports anywhere

Standard library only. It will not fail to import because an image is missing requests.

init()

init(
    hparams: Mapping[str, Any] | None = None,
    monitor_hardware: bool = True,
    monitor_interval: float | None = None,
) -> bool

Starts the reporting session. Returns whether reporting is actually on — False on a laptop, and that is not an error. Idempotent: calling it twice is safe, and passing hparams the second time adds them.

hparams · Mapping

Hyperparameters for the console’s Config panel. Nested dictionaries are flattened with dots, so {"policy": {"lr": 1e-6}} becomes policy.lr.

monitor_hardware · bool · default: "True"

Starts a background thread that samples GPU utilisation, memory and network for the System tab. Set False if something else in your job already reports hardware.

monitor_interval · float · default: "10"

Seconds between hardware samples. STARFORGE_MONITOR_INTERVAL overrides the default.

log()

log(metrics: Mapping[str, Any], step: int | None = None, prefix: str = "") -> None

Sends one batch of scalars.

log({"loss": 0.42, "reward": 0.71})                    # step auto-increments
log({"loss": 0.41}, step=121)                          # explicit step
log({"loss": 0.41}, prefix="eval")                     # becomes eval/loss
log({"grad": {"norm": 1.2, "clip": 0.8}}, step=121)    # becomes grad.norm, grad.clip

Non-scalar values are reduced to their mean where that is meaningful and dropped where it is not — a tensor of per-token losses becomes one number, a string becomes nothing. Omitting step increments an internal counter, which is what you want in a reward function that has no notion of a global step.

log() calls init() for you if you have not. Inside a reward function or an environment, a bare from starforge.report import log is enough — no setup, no plumbing an object through.

log_hparams() and finish()

log_hparams(params: Mapping[str, Any]) -> None
finish() -> None

log_hparams adds to the Config panel after init. finish stops hardware collection and flushes the buffer; it is idempotent and also registered with atexit, so a script that exits normally does not strictly need to call it. Call it anyway — a process killed before atexit runs loses whatever is still buffered.

Hugging Face and TRL

from starforge.report import StarForgeCallback
from trl import GRPOTrainer

trainer = GRPOTrainer(..., callbacks=[StarForgeCallback()])

Handles init, per-log-step log, and finish on the Trainer’s own lifecycle. Works with any transformers.Trainer and every TRL trainer built on it.

StarForgeCallback(monitor_hardware: bool = True, prefix: str = "")

It does not subclass transformers.TrainerCallback — Hugging Face dispatches callbacks by method name, so duck typing is enough, and not subclassing keeps starforge.report importable in an image with no transformers.

Confirm it worked

Submit the job and open its Charts tab. A point appears within a few seconds of your first log().

If the logs are moving and the charts stay empty, the reporting call is not running. Check inside the container:

echo $STARFORGE_ENABLED   # must be 1

If it is 1 and there are still no points, init() was never reached — put a print next to it and resubmit.

The rest of the SDK

starforge.report is the public surface. The package also exports the JobSpec contract types (JobSpec, Recipe, ResourceSpec, …) and Reporter, the low-level client the platform’s own framework bridges use. Those are documented as the ingest contract and JobSpec; reach for them when writing a framework adapter, not when instrumenting a training script.