trackio

Warnings

• breaking Trackio is currently in beta, and its SQLite database schema may change in future releases. This could necessitate migrating or deleting existing database files (located by default at `~/.cache/huggingface/trackio`) to maintain compatibility.
  Fix: Be prepared to delete or migrate local database files when updating to new major/minor versions. Consult release notes for migration instructions.
• gotcha The `trackio.init()` function must be called at the beginning of your script or experiment run before any other `trackio` logging functions (`log`, `save`, etc.) are used. Failing to do so will result in errors as the tracking context will not be established.
  Fix: Always call `trackio.init()` once per experiment run to establish the tracking environment.
• gotcha While Trackio provides API compatibility with `wandb`, it is intentionally lightweight and does not yet support all advanced features found in Weights & Biases, such as artifact versioning, comprehensive custom visualizations, or advanced sweeps management.
  Fix: Review the official Trackio documentation for supported features if migrating from `wandb` or expecting specific advanced functionalities.
• gotcha When using `space_id` in `trackio.init()` to sync logs to Hugging Face Spaces, your local `huggingface-cli` must be logged in and configured with a token that has write permissions for the specified Space or to create a new one.
  Fix: Ensure you are logged in via `huggingface-cli login` and your token has the necessary write access before initializing runs with `space_id`.

Install

• pip install trackio Default Install
• pip install trackio[gpu] GPU Monitoring (NVIDIA)
• pip install trackio[apple-gpu] System Monitoring (Apple Silicon)
• pip install trackio[tensorboard] TensorBoard Import
• pip install trackio[dev] Development Install
• pip install trackio[spaces] Hugging Face Spaces Integration

Imports

• trackio

  import trackio

  The primary interaction is through the main 'trackio' module, often aliased as 'wandb' for compatibility.
• wandb_alias

  import trackio as wandb

  For direct compatibility with existing Weights & Biases codebases, `trackio` can be imported as `wandb`.

Quickstart

This quickstart demonstrates how to initialize a tracking run, log metrics within a simulated training loop, and finalize the run. It uses `trackio.init` to set up the project and configuration, `trackio.log` to record scalar metrics, and `trackio.finish` to conclude the experiment. To view the collected metrics, open a new terminal and run `trackio show`.

import trackio
import random
import time
import os

# Initialize a new experiment run
# For Spaces integration, add space_id='your_username/your_space_name'
run = trackio.init(project="my-awesome-project", 
                   name=f"run-{int(time.time())}",
                   config={
                       "learning_rate": 0.001,
                       "epochs": 5,
                       "batch_size": 32
                   })

print(f"Starting run: {run.name} in project: {run.project_name}")

# Simulate a training loop
for epoch in range(run.config["epochs"]):
    # Simulate metrics
    train_loss = 1.0 / (epoch + 1) + random.uniform(-0.1, 0.1)
    val_loss = 0.8 / (epoch + 1) + random.uniform(-0.05, 0.05)
    accuracy = 0.5 + (epoch / run.config["epochs"]) * 0.4 + random.uniform(-0.03, 0.03)
    
    # Log metrics
    trackio.log({"epoch": epoch, "train_loss": train_loss, "val_loss": val_loss, "accuracy": accuracy})
    print(f"Epoch {epoch}: Train Loss = {train_loss:.4f}, Val Loss = {val_loss:.4f}, Accuracy = {accuracy:.4f}")
    time.sleep(0.5)

# Finish the run
trackio.finish()
print("Run finished. To view the dashboard, run `trackio show` in your terminal.")