API Reference

Bases: LegacyExperiment

Core experiment with dict-like API for logging data.

Supports pythonic dict-like access patterns:

experiment[“key”].append(value) # time series (metrics or files) experiment[“key”].extend(values) # batch time series experiment[“key”] = “value” # static metadata experiment[“key”] = File(“path”) # static file artifact experiment[“key”] # fetch data

Also inherits the legacy method-based API used for backwards compatibility (log_metrics, log_file, log_model, etc.).

Keys must be unique across metadata, artifacts, and metrics.

Initialize an experiment for logging to the https://lightning.ai platform.

Parameters:

• name (str) – A human-friendly name for your experiment.

• log_dir (str) – Local directory where temporary logs/artifacts are stored. Defaults to “lightning_logs”.

• save_logs (bool) – If True, capture and upload terminal output as a file artifact. Defaults to False.

• teamspace (str | Teamspace | None) – Teamspace in which to create and display the charts. If None, uses your default teamspace.

• light_color (str | None) – Hex color of the curve in light mode (overrides the random default). Example: “#FF5733”.

• dark_color (str | None) – Hex color of the curve in dark mode (overrides the random default). Example: “#3498DB”.

• metadata (dict[str, str] | None) – Key-value parameters associated with the experiment (displayed as tags in the UI).

• store_step (bool | None) – Whether to store the provided step for each data point. Defaults to True.

• store_created_at (bool | None) – Whether to store a creation timestamp for each data point. Defaults to False.

• max_batch_size (int) – Number of metric values to batch before uploading. Defaults to 1000.

• rate_limiting_interval (int) – Minimum seconds between uploads. Defaults to 1.

• verbose (bool) – If True, print styled console output. Defaults to True.

finalize(status=None, print_summary=True)

Finalize the experiment and upload all remaining metrics.

This method waits for the background thread to finish uploading all queued metrics, and uploads terminal logs if save_logs=True. It’s automatically called on exit via an atexit handler, but can also be called manually.

This method is idempotent and can be called multiple times safely.

Parameters:

• status (str | None) – Optional status string for the experiment (currently unused, reserved for future use).

• print_summary (bool) – Whether to print the run completion summary. Defaults to True.

Return type:

None

get_file(path, remote_path=None, verbose=True)

Download a file artifact from the cloud for this experiment.

Deprecated since version Use: experiment["key"] to access files instead.

The file is downloaded from cloud storage (previously uploaded via log_file) and saved to the specified local path.

Parameters:

• path (str) – Path where the file should be saved locally. Parent directories are created if needed.

• remote_path (str | None) – Path relative to experiment root where the file is stored. If None, uses the path relative to cwd if under cwd, otherwise basename. Must match the remote_path used during log_file() for correct resolution.

• verbose (bool) – Whether to print a confirmation message after download. Defaults to True.

Returns:

The local path where the file was saved (same as the input path).

Return type:

str

get_model(staging_dir=None, verbose=False, version=None)

Get a model object using litmodels load_model.

Deprecated since version Use: experiment["key"] to access models instead.

Parameters:

• staging_dir (str | None) – Optional directory where the model will be downloaded.

• verbose (bool) – Whether to show progress bar.

• version (str | None) – Optional version string for the model.

Return type:

Any

Returns:

The loaded model object.

get_model_artifact(path, verbose=False, version=None)

Download a model artifact file or directory from cloud storage using litmodels.

Deprecated since version Use: experiment["key"] to access model artifacts instead.

This downloads raw model files or directories that were previously uploaded via log_model_artifact(). The files are saved to the specified local path.

Parameters:

• path (str) – Path where the model should be saved locally. Directories are created if needed.

• verbose (bool) – Whether to show progress bar during download. Defaults to False.

• version (str | None) – Optional version string for the model.

Returns:

The local path where the model was saved (same as the input path).

Return type:

str

log_file(path, remote_path=None, verbose=True)

Upload a file artifact to the cloud for this experiment.

Deprecated since version Use: experiment["key"] = File("path") or experiment["key"].append(File("path")) instead.

The file is uploaded to cloud storage and registered with the experiment, making it visible in the artifacts view and accessible via get_file().

Parameters:

• path (str) – Path to the local file to upload. Can be absolute or relative.

• remote_path (str | None) – Path relative to experiment root for storage and display. If None, uses the path relative to cwd if under cwd, otherwise basename. Example: remote_path=”images/0.png” will store and display as “images/0.png”.

• verbose (bool) – Whether to print a confirmation message after upload. Defaults to True.

Return type:

None

log_files(paths, remote_paths=None, max_workers=10)

Upload multiple file artifacts to the cloud in parallel.

Deprecated since version Use: experiment["key"] = File("path") for each file instead.

This is more efficient than calling log_file() multiple times when you have many files, as it handles them in parallel.

Parameters:

• paths (list[str]) – List of paths to local files to upload.

• remote_paths (list[str] | None) – Optional list of remote paths, one for each file in paths. If provided, must have same length as paths. If None, each file uses its default remote path (relative to cwd or basename).

• max_workers (int) – Maximum number of concurrent uploads. Defaults to 10.

Return type:

None

log_media(name, path, kind=None, step=None, epoch=None, caption=None, verbose=False)

Upload a media file (image, text, etc.) to the experiment.

Deprecated since version Use: experiment["key"].append(Image(...)) or experiment["key"].append(Text(...)) instead.

Parameters:

• name (str) – Name of the media.

• path (str) – Local path to the media file.

• kind (MediaType | None) – Type of media (MediaType.IMAGE or MediaType.TEXT). If None, attempts to guess from file extension or mime type.

• step (int | None) – Optional training step.

• epoch (int | None) – Optional training epoch.

• caption (str | None) – Optional caption for the media.

• verbose (bool) – Whether to print a confirmation message after upload.

Raises:

• ValueError – If the file type cannot be determined or is not supported.

• FileNotFoundError – If the file does not exist.

Return type:

None

log_metadata(metadata=None, **kwargs)

Add or update metadata tags on the experiment.

Deprecated since version Use: experiment["key"] = "value" instead.

Merges the provided key-value pairs into the experiment’s existing metadata and pushes the update to the cloud immediately.

Parameters:

• metadata (dict[str, str] | None) – Dictionary of metadata key-value pairs to add or update. Example: {“optimizer”: “adam”, “lr”: “0.001”}.

• **kwargs (str) – Additional metadata as keyword arguments. Example: optimizer=”adam”, lr=”0.001”.

Return type:

None

log_metrics(metrics=None, step=None, **kwargs)

Log metrics to the experiment with background uploading.

Deprecated since version Use: experiment["key"].append(value, step=step) instead.

Metrics are buffered locally and uploaded to the cloud in batches to optimize performance. The batch is sent when either 1 second has passed or 1000 values have been logged.

Parameters:

• metrics (dict[str, float] | None) – Dictionary mapping metric names to numeric values. Example: {“loss”: 0.5, “accuracy”: 0.95}.

• step (int | None) – Optional step number for this data point (e.g., training step, epoch). If None and store_step=True, no step is recorded.

• kwargs (float) – Additional metric values. Can be used to provide metrics more natural. Example: loss=0.5, accuracy: 0.95.

Raises:

RuntimeError – If the background thread encountered an error.

Return type:

None

log_metrics_batch(metrics)

Log a batch of metrics through the background queue.

Deprecated since version Use: experiment["key"].extend(values, start_step=step) instead.

This method converts the batch format to Metrics objects and pushes them through the background queue, which handles batching and chunking to respect API limits.

Parameters:

metrics (dict[str, list[dict[str, float]]]) – Dictionary mapping metric names to lists of dicts with “step” and “value” keys.

Return type:

None

Example:

Copy

{
    "loss": [
        {"step": 0, "value": 1.0},
        {"step": 1, "value": 0.5},
    ],
    "accuracy": [
        {"step": 0, "value": 0.6},
        {"step": 1, "value": 0.8},
    ],
}

Raises:

RuntimeError – If the background thread encountered an error.

log_model(model, staging_dir=None, verbose=False, version=None, metadata=None)

Save and upload a model object to cloud storage using litmodels.

Deprecated since version Use: experiment["key"] = File("path") instead.

This saves a live model object (e.g., PyTorch module, LightningModule) to disk using framework-specific serialization, then uploads it to the litmodels registry.

For uploading pre-saved model files, use log_model_artifact() instead.

Parameters:

• model (Any) – The model object to save and upload (e.g., torch.nn.Module, LightningModule).

• staging_dir (str | None) – Optional local directory for staging the model before upload. If None, uses a temp directory.

• verbose (bool) – Whether to show progress bar during upload. Defaults to False.

• version (str | None) – Optional version string for the model.

• metadata (dict[str, str] | None) – Optional metadata dictionary to store with the model (e.g., hyperparameters, metrics).

Returns:

Information about the uploaded model (details from litmodels).

Return type:

str

log_model_artifact(path, verbose=False, version=None)

Upload a model file or directory to cloud storage using litmodels.

Deprecated since version Use: experiment["key"] = File("path") instead.

This uploads raw model files (e.g., weights.pt, checkpoint.ckpt) or entire directories to the litmodels registry. Use this when you have pre-saved model files.

For saving model objects directly, use log_model() instead.

Parameters:

• path (str) – Path to the local model file or directory to upload.

• verbose (bool) – Whether to show progress bar during upload. Defaults to False.

• version (str | None) – Optional version string for the model.

Return type:

None

print_url()

Print the experiment URL and initialization info with styled output.

Return type:

None

update(data)

Bulk-update the experiment with multiple keys at once.

Dispatches each value based on its type:

str → metadata (same as experiment[“key”] = “value”) File → static file artifact (same as experiment[“key”] = file) float/int → append a single metric point (same as experiment[“key”].append(value)) list → extend a time series (same as experiment[“key”].extend(values))

Parameters:

data (dict[str, str | float | int | File | list[float | int | File]]) – Dictionary mapping keys to values of mixed types.

Return type:

None

property artifacts

Get all artifacts (static files and file series) logged to this experiment.

Returns:

Mapping of artifact keys to File (static)

or Series (time series of files).

Return type:

dict[str, File | Series]

property metadata

Get the metadata associated with this experiment from the metrics stream.

Returns:

The metadata dictionary with key-value pairs from code-defined tags.

Return type:

dict[str, str]

property metrics

Get all metric time series logged to this experiment.

Returns:

Mapping of metric names to their series of values.

Return type:

dict[str, Series]

property teamspace

Get the teamspace for this experiment.

Returns:

The teamspace object.

Return type:

Teamspace

property url

Get the direct URL to view this experiment in the Lightning.ai web interface.

Returns:

The full URL to the experiment’s visualization page.

Return type:

str

Bases: object

Represents a file to be logged to the experiment.

Parameters:

• path (str) – Path to the local file.

• description (str) – Optional human-readable description of the file.

save(path)

Download the remote file to a local path.

Only works for files that have been uploaded to an experiment.

Parameters:

path (str) – Local path where the file should be saved.

Returns:

The local path where the file was saved.

Return type:

str

Raises:

RuntimeError – If the file has no remote download context.

Bases: File

Represents an image to be logged.

Can take a file path (str) or a Python object (PIL Image, numpy array, or torch Tensor) and will render it to a temporary file for upload.

Parameters:

• data (Any) – The image data - a file path string, PIL Image, numpy array, or torch Tensor.

• format (str) – Image format for rendering objects to disk (default: “png”).

• description (str) – Optional human-readable description of the image.

Bases: File

Represents text content to be logged.

Takes a string and writes it to a temporary file for upload.

Parameters:

• content (str) – The text string to log.

• description (str) – Optional human-readable description of the text.

Bases: File

DEFAULT_FPS = 24

Represents a video to be logged.

Accepts: - a file path string - a MoviePy clip - a numpy array / torch tensor of frames

Supported array shapes: - (T, H, W) grayscale frames - (T, H, W, C) frames in HWC format - (T, C, H, W) frames in CHW format, where C is 1/3/4

Parameters:

• data – Video data or a path to a video file.

• format – Output container/extension, default “mp4”.

• description – Optional description.

• fps – Frames per second used when rendering arrays or clips that do not already carry fps metadata.

Bases: File

Represents a model to be logged.

Can take either a Python model object or a local path to a pre-saved model artifact. Uploads are handled through the model registry.

Parameters:

• data (Any) – Python model object or path to a pre-saved model file/directory.

• name (str | None) – Optional registry name override for this model. Defaults to the experiment name.

• version (str | None) – Optional model version. Defaults to "latest".

• metadata (dict[str, str] | None) – Optional metadata to associate with the model upload.

• staging_dir (str | None) – Optional local staging directory for object-based uploads.

• description (str) – Optional human-readable description of the model.

classmethod from_remote(model_name, kind, version=None)

Create a remote-bound model wrapper for resumed experiments.

Return type:

Model

load(staging_dir=None)

Load a remote model object via the registry helpers.

Return type:

Any

Bases: object

A list-like proxy for time-series data that supports append and extend.

Tracks either metric values (floats) or file series (File objects). The type is determined by the first value appended and cannot be mixed.

append(value, step=None)

Append a value to the time series.

Parameters:

• value (float | File) – A float/int for metric series, or a File for file series.

• step (int | None) – Optional step number for this data point (e.g., training step, epoch).

Raises:

TypeError – If value type doesn’t match existing series type or is unsupported.

Return type:

None

extend(values, start_step=None)

Extend the time series with multiple values.

Parameters:

• values (list[float | int | File]) – List of values to append.

• start_step (int | None) – Optional starting step number. Each subsequent value gets start_step, start_step+1, start_step+2, etc.

Return type:

None

Bases: str, Enum

Type of media to upload.

FILE = 'file'

IMAGE = 'image'

MODEL = 'model'

TEXT = 'text'

VIDEO = 'video'

Bases: str, Enum

Phase of a metrics store lifecycle.

COMPLETED = 'completed'

FAILED = 'failed'

PENDING = 'pending'

RUNNING = 'running'

STOPPED = 'stopped'

Bases: object

A single metric value with optional step and timestamp.

value

The numeric metric value.

step

Optional step number for this value.

created_at

Optional datetime when this value was created.

Bases: object

A collection of metric values for a named metric.

name

The metric name (e.g., “loss”, “accuracy”).

values

List of metric values.

Bases: LitLogger, LitLogger

Deprecated compatibility alias for the upstream Lightning LitLogger.