Chapter 12: Real-World Scenario: Collaborative ML on Hugging Face Spaces

Introduction

Welcome to Chapter 12! So far, you’ve mastered the fundamentals of Trackio, from setting up individual experiments to diving deep into your local dashboards. But what happens when your machine learning journey becomes a team sport? What if you want to share your brilliant experiment insights with colleagues, get feedback, or showcase your model’s performance to the world?

This chapter is all about taking your Trackio skills to the next level: collaboration. We’ll explore how to seamlessly integrate Trackio with Hugging Face Spaces, transforming your local experiment tracking into a powerful, shared, and interactive experience. You’ll learn how to push your experiment data to a public or private Space, making your results accessible and fostering a truly collaborative ML workflow.

By the end of this chapter, you’ll not only be able to track experiments locally but also share them effortlessly, allowing teammates to view dashboards, compare runs, and contribute to the project’s success. Get ready to make your ML projects truly collaborative!

Core Concepts: Collaborative ML & Trackio on Spaces

Before we dive into the code, let’s understand the “why” and “how” behind collaborative ML with Trackio and Hugging Face Spaces.

What is Collaborative Machine Learning?

In the real world, machine learning isn’t a solo endeavor. It often involves teams of data scientists, engineers, and researchers working together. Collaborative ML refers to the process where multiple individuals contribute to different aspects of an ML project, such as data preprocessing, model development, hyperparameter tuning, and evaluation.

Why is collaboration crucial?

Faster Development: Teams can parallelize tasks, speeding up the iteration cycle.
Diverse Perspectives: Different team members bring unique insights and expertise.
Knowledge Sharing: Everyone stays updated on the latest experiments and findings.
Reproducibility: A shared, well-tracked environment helps ensure experiments can be replicated.

One of the biggest challenges in collaborative ML is keeping track of who ran what experiment, with which parameters, and what results they achieved. This is precisely where Trackio shines when combined with a sharing platform like Hugging Face Spaces.

Hugging Face Spaces for ML Demos & Apps

Hugging Face Spaces provides an incredibly easy way to host and share machine learning demos, models, and applications. Think of it as a GitHub for ML applications, but instead of just code, you get a live, interactive web application.

Key benefits of Hugging Face Spaces:

Easy Deployment: Spin up a web app from a simple Python script (often using Gradio or Streamlit) in minutes.
Sharing and Discovery: Share your work with a link, make it public or private.
Collaboration: Multiple users can contribute to a Space’s code and data.
Version Control: Spaces are backed by Git, meaning all changes are versioned.

Trackio, being built on top of Hugging Face Datasets and Spaces, has a native integration that allows you to host your experiment tracking dashboard directly within a Space. This means your locally tracked experiments can be pushed to a remote Space and viewed by anyone with access, complete with interactive plots and tables.

Trackio’s Role in Collaborative Experiment Tracking

Trackio’s design as a lightweight, local-first experiment tracker makes it a perfect fit for collaborative workflows on Hugging Face Spaces.

Local Development, Remote Sharing: You continue to track experiments on your local machine, leveraging Trackio’s speed and simplicity.
Seamless Sync: With a single command, you can synchronize your local experiment database with a Hugging Face Space. This pushes all your runs, parameters, metrics, and artifacts to the remote Space.
Shared Dashboard: Once synced, the Hugging Face Space automatically renders a Trackio dashboard, identical to your local one. Collaborators can then browse experiments, compare runs, and analyze results directly in their web browser without needing to set up anything locally.
Versioned Experiments: Since Spaces are Git-backed, pushing your Trackio data essentially version-controls your experiment results alongside your code. This ensures a complete record of your project’s evolution.

This collaborative setup allows each team member to work independently on their experiments while ensuring all results converge into a central, shared, and easily accessible dashboard.

Step-by-Step Implementation: Setting Up a Collaborative Trackio Project on Spaces

Let’s get hands-on and set up a project for collaborative experiment tracking.

Prerequisites (as of 2026-01-01)

Before we start, ensure you have the following installed:

Python 3.10+: We recommend Python 3.11 or 3.12 for the latest features and performance.
pip: Python’s package installer.
Hugging Face Hub Account: Create one for free at huggingface.co/join.
Hugging Face CLI: For easy interaction with the Hub. Install with pip install "huggingface_hub[cli]".

Trackio: Install the latest stable version.

pip install trackio==0.2.1  # As of early 2026, 0.2.1 is the latest stable.

Step 1: Create a New Hugging Face Space

First, we need a home for our collaborative project on Hugging Face Spaces.

Log in to Hugging Face Hub: Open your terminal and log in using the CLI:
```
huggingface-cli login
```
You’ll be prompted to enter your Hugging Face token. You can find or generate one in your Hugging Face profile settings under “Access Tokens” (huggingface.co/settings/tokens). Choose a token with “write” access.
Create a new Space: You can create a Space either through the Hugging Face website UI or using the huggingface_hub library’s Python API. For simplicity and to integrate with a command-line workflow, let’s assume you create it via the UI for now.
- Go to huggingface.co/spaces/new.
- Choose a Space name (e.g., my-team/collaborative-ml-project).
- Select Gradio as the SDK (Trackio integrates seamlessly with Gradio).
- Choose a License (e.g., MIT).
- Set Visibility to “Public” or “Private” based on your needs. For collaboration, “Private” is often preferred initially.
- Click “Create Space”.
Once created, you’ll see a page for your new Space, showing instructions to clone its Git repository. Copy the Git URL (e.g., https://huggingface.co/spaces/my-team/collaborative-ml-project).

Step 2: Initialize a Local Trackio Project

Now, let’s set up our local development environment.

Clone your Hugging Face Space locally: Open your terminal and run:
```
git clone https://huggingface.co/spaces/my-team/collaborative-ml-project
cd collaborative-ml-project
```
(Replace the URL with your actual Space’s Git URL).
Initialize Trackio within the cloned directory:
```
trackio init
```
What just happened? Trackio created a hidden directory named .trackio/ in your project. This directory will store your local experiment data (a SQLite database by default) and a config.toml file. This config.toml is where we’ll tell Trackio about our Hugging Face Space.
You should also add .trackio/runs/ to your .gitignore to avoid committing raw run data directly if you only want to commit the synced data to the Space. However, for Trackio to sync, it will manage its own internal Git repository within .trackio/ for the experiment data.

Step 3: Connect Local Trackio to Hugging Face Spaces

This is the crucial step to link your local experiments to your remote Space.

Configure config.toml: Open the config.toml file located inside your .trackio/ directory. It should look something like this initially:
```
# .trackio/config.toml
[core]
# Default database path is .trackio/trackio.db
# db_path = ".trackio/trackio.db"
```
We need to add a [huggingface] section to specify the Space where Trackio should sync.
Edit config.toml to look like this:
```
# .trackio/config.toml
[core]
# Default database path is .trackio/trackio.db
# db_path = ".trackio/trackio.db"

[huggingface]
# Replace with your Hugging Face Space ID, e.g., "my-user/my-space-name"
space_id = "my-team/collaborative-ml-project"
# Optional: Path within the Space where Trackio data will be stored.
# Defaults to "trackio_data"
# repo_path = "trackio_data"
```
Explanation:
- [huggingface]: This section tells Trackio how to interact with Hugging Face.
- space_id = "my-team/collaborative-ml-project": This is the identifier for your Hugging Face Space. It’s usually your-username/your-space-name or your-organization/your-space-name. Make sure this matches the Space you created in Step 1.
Run trackio sync: With the config.toml updated, tell Trackio to prepare for syncing.
```
trackio sync
```
What does trackio sync do? This command doesn’t push data yet. Instead, it initializes the necessary connection and structure. It ensures that Trackio is aware of the remote Space and ready to manage the synchronization of experiment data. It might create a trackio_data/ folder (or whatever repo_path you specified) within your local project, which will eventually hold the synced data that gets pushed to the Space.

Step 4: Run an Experiment and Log Data

Now, let’s create a simple Python script to simulate a machine learning experiment and log some data with Trackio.

Create a file named train.py in your project root:

# train.py
import trackio
import random
from sklearn.linear_model import LogisticRegression
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score

print("Starting experiment...")

# 1. Initialize a Trackio run
# We give it a name to easily identify it later.
with trackio.run(name="Collaborative_LogReg_Experiment") as run:
    # 2. Define hyperparameters and log them
    learning_rate = random.uniform(0.001, 0.1)
    max_iter = random.randint(50, 200)
    solver_type = random.choice(['lbfgs', 'liblinear', 'sag'])

    run.log_params({
        "learning_rate": learning_rate,
        "max_iterations": max_iter,
        "solver": solver_type,
        "dataset_size": 1000
    })
    print(f"Logged parameters: LR={learning_rate:.4f}, MaxIter={max_iter}, Solver={solver_type}")

    # 3. Simulate data generation and model training
    X, y = make_classification(n_samples=1000, n_features=10, random_state=42)
    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

    model = LogisticRegression(random_state=42, solver=solver_type, max_iter=max_iter, C=1.0/learning_rate)
    model.fit(X_train, y_train)

    # 4. Evaluate the model and log metrics
    predictions = model.predict(X_test)
    accuracy = accuracy_score(y_test, predictions)

    run.log_metrics({
        "accuracy": accuracy,
        "f1_score": 0.85 # Placeholder for another metric
    })
    print(f"Logged accuracy: {accuracy:.4f}")

    # 5. Log an artifact (e.g., a dummy model file)
    # In a real scenario, you'd save the actual model.
    with open("dummy_model.txt", "w") as f:
        f.write(f"Model trained with accuracy: {accuracy:.4f}")
    run.log_artifact("dummy_model.txt", name="trained_model_info")
    print("Logged artifact: dummy_model.txt")

print("Experiment finished.")

Explanation of the code:

import trackio: Imports the Trackio library.
with trackio.run(...) as run:: This is the core of Trackio. It starts a new experiment run. All subsequent log_params, log_metrics, and log_artifact calls within this with block will be associated with this specific run. The name argument helps you identify runs.
run.log_params(...): Records the hyperparameters used for this experiment.
run.log_metrics(...): Stores the performance metrics achieved by the model.
run.log_artifact(...): Allows you to save important files related to your experiment, like trained models, plots, or processed data. Trackio stores a reference to these files.

Now, run this script a few times to generate some experiment data:

python train.py
python train.py
python train.py

After running, you can verify your local dashboard:

trackio dashboard

You should see multiple runs with different parameters and metrics.

Step 5: Push Experiment Data to Space

This is where the magic of collaboration happens. We’ll push our local Trackio data to the Hugging Face Space.

Push your Trackio data:
```
trackio push
```
What does trackio push do? This command takes your local .trackio/ database and any associated artifacts, converts them into a format suitable for Hugging Face Datasets, and pushes them to your configured Space. Essentially, it performs a git push of your experiment data to the trackio_data/ (or specified repo_path) directory within your Space’s Git repository.
You might be prompted for your Hugging Face token again if it’s not cached or if permissions are insufficient.

Step 6: View the Dashboard on Hugging Face Spaces

Finally, let’s see your collaborative dashboard in action!

Navigate to your Hugging Face Space: Go to https://huggingface.co/spaces/my-team/collaborative-ml-project (replace with your Space URL).
Observe the Dashboard: After a short build time (Hugging Face needs to process the pushed data), your Space will automatically render the Trackio dashboard. You’ll see all the runs you executed locally, complete with their logged parameters, metrics, and artifacts, displayed in an interactive web interface.
Now, any collaborator with access to this Space can view, filter, and compare your experiments! If another team member pulls the latest changes from the Space, runs their own experiments locally using Trackio, and then pushes, their experiments will also appear on the shared dashboard.

Example Workflow Diagram

Here’s a simple flowchart illustrating the collaborative workflow:

Explanation of the Diagram:

User A initializes Trackio, runs experiments locally (logging to LocalDB_A), and then pushes their results to the Hugging Face Space.
User B can git pull the Space to get the latest code and then optionally trackio pull to get User A’s experiment data locally. User B then runs their own experiments (logging to LocalDB_B) and pushes their results back to the Hugging Face Space.
Both users (and others) can then view all combined experiments on the Shared Trackio Dashboard hosted on Hugging Face Spaces.

Mini-Challenge

It’s your turn to enhance our collaborative project!

Challenge: Modify the train.py script to introduce a new hyperparameter: test_size for the train_test_split function. Log this new parameter and run your experiment at least twice with different test_size values (e.g., 0.1 and 0.3). After running, push your changes to the Hugging Face Space.

Hint:

Remember to add test_size to your run.log_params() dictionary.
You’ll need to modify the train_test_split call.
Run python train.py multiple times, then trackio push.

What to Observe/Learn: Check your Hugging Face Space dashboard. You should now see additional runs, and the new test_size parameter should be visible for those runs. This demonstrates how easily new parameters and experiments can be introduced and shared collaboratively.

Common Pitfalls & Troubleshooting

Even with robust tools, issues can arise. Here are some common problems when working with Trackio and Hugging Face Spaces:

Hugging Face Authentication Issues:
- Symptom: trackio push fails with “Authentication Error” or “Permission Denied.”
- Cause: Your Hugging Face token is missing, expired, or doesn’t have “write” access to the Space.
- Solution: Run huggingface-cli login again to refresh your token. Ensure you generate a token with “write” access from your Hugging Face profile settings.
Dashboard Not Updating on Space:
- Symptom: You pushed data, but the Space dashboard shows old results or an error.
- Cause: The Space might be taking time to rebuild, or there was an issue during the push. Sometimes, the Trackio app inside the Space needs a restart.
- Solution:
  - Wait a few minutes. Hugging Face Spaces can take a moment to rebuild after a push.
  - Check the “Logs” tab on your Space page for any build errors.
  - Ensure you ran trackio push successfully and saw a confirmation message.
  - If the Space is stuck, you can try restarting it from the “Settings” tab on your Space page.
Local trackio push fails or has merge conflicts:
- Symptom: trackio push gives a Git error or reports merge conflicts.
- Cause: This usually happens if multiple collaborators are pushing to the same Space simultaneously without first pulling the latest changes. Trackio’s underlying Git operations might detect conflicts.
- Solution:
  - Before pushing, always run git pull origin main (or your main branch) in your project directory to get the latest code and .trackio_data/ changes.
  - Trackio itself tries to handle merges for its internal data, but if Git reports conflicts in the main project, resolve those first.
  - Consider establishing clear communication within your team about when pushes are happening, especially for larger updates.

Summary

Congratulations! You’ve successfully navigated the exciting world of collaborative machine learning with Trackio and Hugging Face Spaces. Let’s recap what you’ve learned:

Collaborative ML Importance: You understand why working in teams is essential and the challenges it presents for experiment tracking.
Hugging Face Spaces as a Hub: You learned how Spaces serve as a powerful platform for hosting ML demos and, crucially, for sharing Trackio dashboards.
Seamless Integration: You mastered the step-by-step process of connecting your local Trackio project to a Hugging Face Space using trackio init, configuring config.toml, and utilizing trackio sync and trackio push.
Shared Experimentation: You can now run experiments locally, log parameters, metrics, and artifacts, and then push them to a shared Space, making your work visible and accessible to your team.
Troubleshooting: You’re equipped to handle common issues like authentication errors or dashboard update problems.

This chapter has empowered you to move beyond individual experiment tracking to a truly collaborative workflow, leveraging the strengths of Trackio’s lightweight design and Hugging Face’s powerful sharing capabilities. In the next chapter, we’ll delve into more advanced customization options for your Trackio setup, further tailoring it to your specific project needs.

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.