Fix .sync() and add .freeze() as a separate methods (#477)

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

Author: abidlabs

.changeset/five-points-thank.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Fix `.sync()` and add `.freeze()` as a separate methods

docs/source/api.md

@@ -32,6 +32,10 @@
 
 [[autodoc]] sync
 
+## freeze
+
+[[autodoc]] freeze
+
 ## delete_project
 
 [[autodoc]] delete_project

docs/source/cli_commands.md

@@ -23,7 +23,59 @@ For private Spaces, pass `--hf-token` or ensure you are logged in via `huggingfa
 trackio list projects --space username/private-space --hf-token hf_xxxxx
 ```
 
-> **Note:** The `show`, `status`, `sync`, and `skills` commands are local-only and do not support `--space`.
+> **Note:** The `show`, `status`, `sync`, `freeze`, and `skills` commands are local-only and do not support `--space`.
+
+## Sync Command
+
+Upload a local project to a Hugging Face Space:
+
+```sh
+trackio sync --project "my-project" --space-id "username/space_id"
+```
+
+Deploy as a static Space (reads from an HF Bucket, no server needed):
+
+```sh
+trackio sync --project "my-project" --space-id "username/space_id" --sdk static
+```
+
+Sync all projects that have unsynced data to their configured Spaces:
+
+```sh
+trackio sync --all
+```
+
+| Flag | Description |
+|------|-------------|
+| `--project` | The name of the project to sync (required unless `--all` is used) |
+| `--space-id` | The HF Space ID to sync to (e.g. `username/space_id`). If not provided, uses the previously-configured Space |
+| `--all` | Sync all projects with unsynced data |
+| `--sdk` | `gradio` (default) for a live server, or `static` for a read-only bucket-backed Space |
+| `--private` | Make the Space private if creating a new one |
+| `--force` | Overwrite the existing database without prompting |
+
+## Freeze Command
+
+Create a read-only static Space snapshot from a live Gradio Space:
+
+```sh
+trackio freeze --space-id "username/my-space" --project "my-project"
+```
+
+Specify a custom destination Space:
+
+```sh
+trackio freeze --space-id "username/my-space" --project "my-project" --new-space-id "username/my-snapshot"
+```
+
+| Flag | Description |
+|------|-------------|
+| `--space-id` | The source Gradio Space ID (required) |
+| `--project` | The project to freeze (required) |
+| `--new-space-id` | The destination static Space ID. Defaults to `{space_id}_static` |
+| `--private` | Make the new static Space private |
+
+> **Note:** The source must be a Gradio Space with a bucket mounted at `/data`. If the destination Space already exists and is not a Trackio static Space, `freeze` will refuse to overwrite it.
 
 ## List Commands
 

docs/source/deploy_embed.md

@@ -18,6 +18,61 @@ trackio.init(project="my-project", space_id="username/space_id")
 
 it will use an existing or automatically deploy a new Hugging Face Space as needed. You should be logged in with the `huggingface-cli` locally and your token should have write permissions to create the Space.
 
+## Syncing Local Projects to Spaces
+
+If you've been logging locally and want to upload your data to a Space after the fact, use `sync`:
+
+```py
+trackio.sync(project="my-project", space_id="username/space_id")
+```
+
+Or from the CLI:
+
+```sh
+trackio sync --project "my-project" --space-id "username/space_id"
+```
+
+By default, `sync` deploys a **Gradio Space** with a live server. You can also deploy a **static Space** that reads from an HF Bucket (no server needed):
+
+```py
+trackio.sync(project="my-project", space_id="username/space_id", sdk="static")
+```
+
+```sh
+trackio sync --project "my-project" --space-id "username/space_id" --sdk static
+```
+
+Static Spaces are lightweight and free — they serve a read-only dashboard backed by Parquet files in an HF Bucket.
+
+## Freezing a Space Snapshot
+
+If you have a live Gradio Space and want to create a read-only static snapshot of a project's data, use `freeze`:
+
+```py
+trackio.freeze(space_id="username/my-space", project="my-project")
+```
+
+Or from the CLI:
+
+```sh
+trackio freeze --space-id "username/my-space" --project "my-project"
+```
+
+This creates a new static Space (by default named `{space_id}_static`) containing a snapshot of the project's data from the source Space's bucket. The original Space is not modified.
+
+You can customize the destination:
+
+```py
+trackio.freeze(
+    space_id="username/my-space",
+    project="my-project",
+    new_space_id="username/my-snapshot",
+    private=True,
+)
+```
+
+> **Note:** `freeze()` requires the source to be a Gradio Space with a bucket mounted at `/data`. If the destination Space already exists and is not a Trackio static Space, `freeze()` will refuse to overwrite it.
+
 ## Embedding a Trackio Dashboard
 
 One of the reasons we created `trackio` was to make it easy to embed live dashboards on websites, blog posts, or anywhere else you can embed a website.

docs/source/quickstart.md

@@ -128,4 +128,4 @@ trackio.sync(project="my-project", space_id="username/space_id")
 </hfoption>
 </hfoptions>
 
-This will create the Space if it does not already exist, and upload all runs and associated data to the Space.
+This will create the Space if it does not already exist, and upload all runs and associated data to the Space. You can also sync to a lightweight static Space with `sdk="static"`, or create a read-only snapshot of a live Space with [`freeze`](deploy_embed.md#freezing-a-space-snapshot). See the [Deploy and Embed Dashboards](deploy_embed.md) page for more details.

examples/convert-gradio-to-static.py

@@ -1,57 +1,48 @@
 """
-Example: deploy a Gradio Space during training, then convert it to a static Space once done.
+Example: Log locally, sync to a Gradio Space, then freeze a static snapshot.
 
-This demonstrates the Gradio -> Static conversion flow:
-1. Start training with a live Gradio dashboard (real-time updates)
-2. After training finishes, convert the Space to static (no server needed, cheaper)
+This demonstrates the full Gradio -> freeze flow:
+1. Log training metrics locally
+2. Sync the project to a live Gradio Space
+3. Freeze the Gradio Space into a read-only static Space (no server needed)
 
 Usage:
     python examples/convert-gradio-to-static.py
 """
 
 import math
 import random
-import time
 
 import trackio
 
 PROJECT = f"gradio-to-static-{random.randint(100000, 999999)}"
-SPACE_ID = f"convert-demo-{random.randint(100000, 999999)}"
 EPOCHS = 10
 
 for run in range(2):
     trackio.init(
         project=PROJECT,
+        space_id=PROJECT,
         name=f"run-{run}",
         config={"epochs": EPOCHS, "lr": 0.001 * (run + 1), "batch_size": 32},
-        space_id=SPACE_ID,
-        auto_log_gpu=False,
     )
-
     for epoch in range(EPOCHS):
         progress = epoch / EPOCHS
-        loss = 2.0 * math.exp(-3 * progress) + 0.1 + random.gauss(0, 0.05)
-        acc = 0.95 / (1 + math.exp(-6 * (progress - 0.5))) + random.gauss(0, 0.02)
-
+        loss = max(0.01, 2.0 * math.exp(-3 * progress) + 0.1 + random.gauss(0, 0.05))
+        acc = min(
+            0.99,
+            max(
+                0, 0.95 / (1 + math.exp(-6 * (progress - 0.5))) + random.gauss(0, 0.02)
+            ),
+        )
         trackio.log(
-            {
-                "train/loss": round(max(0.01, loss), 4),
-                "train/accuracy": round(min(0.99, max(0, acc)), 4),
-            },
+            {"train/loss": round(loss, 4), "train/accuracy": round(acc, 4)},
             step=epoch,
         )
-
-        trackio.log_system(
-            {
-                "cpu_percent": round(40 + epoch * 3 + random.uniform(-2, 2), 1),
-                "memory_gb": round(4.0 + epoch * 0.1 + random.uniform(-0.05, 0.05), 2),
-            }
-        )
-
-        time.sleep(0.3)
-
     trackio.finish()
 
-print("\nTraining complete. Converting Gradio Space to static...")
-space_id = trackio.sync(project=PROJECT, space_id=SPACE_ID, sdk="static")
-print(f"Static dashboard: https://huggingface.co/spaces/{space_id}")
+
+print("Freezing a static snapshot from the Gradio Space...")
+static_space_id = trackio.freeze(
+    space_id=PROJECT, project=PROJECT, new_space_id=f"{PROJECT}_static"
+)
+print(f"Static snapshot: https://huggingface.co/spaces/{static_space_id}")

examples/sync-gradio-space.py

@@ -0,0 +1,39 @@
+"""
+Example: Log training data locally, then sync the project to a Gradio Space.
+
+Usage:
+    python examples/sync-gradio-space.py
+
+This will:
+1. Log a few runs of fake training metrics locally (no space_id in init)
+2. Call trackio.sync() to upload the local project to a live Gradio Space
+
+Set HF_TOKEN or run `huggingface-cli login` first.
+"""
+
+import math
+import random
+
+import trackio
+
+PROJECT = f"sync-gradio-demo-{random.randint(100000, 999999)}"
+EPOCHS = 15
+
+for run_idx in range(3):
+    trackio.init(
+        project=PROJECT,
+        name=f"run-{run_idx}",
+        config={"lr": 0.001 * (run_idx + 1), "epochs": EPOCHS},
+    )
+    for epoch in range(EPOCHS):
+        progress = epoch / EPOCHS
+        loss = max(0.05, 2.5 * math.exp(-3 * progress) + random.gauss(0, 0.1))
+        acc = min(
+            0.95, 0.9 / (1 + math.exp(-6 * (progress - 0.5))) + random.gauss(0, 0.03)
+        )
+        trackio.log({"train/loss": round(loss, 4), "train/accuracy": round(acc, 4)})
+    trackio.finish()
+
+print("Training complete. Syncing to a Gradio Space...")
+space_id = trackio.sync(project=PROJECT)
+print(f"Dashboard: https://huggingface.co/spaces/{space_id}")

examples/sync-static-space.py

@@ -1,13 +1,14 @@
 """
-Example: Log some fake training data, then sync to a static HF Space.
+Example: Log training data locally, sync to a static Space, then log more and sync again.
 
 Usage:
     python examples/sync-static-space.py
 
 This will:
-1. Log a few runs of fake training metrics locally
-2. Call trackio.sync() which uploads the local project to an HF Bucket
-   and deploys a static dashboard Space (no running server needed)
+1. Log an initial run of fake training metrics locally
+2. Sync to a static HF Space (uploads to an HF Bucket, no server needed)
+3. Log a second run with more data
+4. Sync again -- the static Space now contains both runs
 
 Set HF_TOKEN or run `huggingface-cli login` first.
 """
@@ -21,33 +22,29 @@
 EPOCHS = 15
 
 
-def fake_loss(epoch, max_epochs):
+def fake_metrics(epoch, max_epochs):
     progress = epoch / max_epochs
-    return max(0.05, 2.5 * math.exp(-3 * progress) + random.gauss(0, 0.2))
+    loss = max(0.05, 2.5 * math.exp(-3 * progress) + random.gauss(0, 0.1))
+    acc = min(0.95, 0.9 / (1 + math.exp(-6 * (progress - 0.5))) + random.gauss(0, 0.03))
+    return round(loss, 4), round(acc, 4)
 
 
-def fake_accuracy(epoch, max_epochs):
-    progress = epoch / max_epochs
-    return min(
-        0.95, 0.9 / (1 + math.exp(-6 * (progress - 0.5))) + random.gauss(0, 0.05)
-    )
-
-
-for run_idx in range(3):
-    trackio.init(
-        project=PROJECT,
-        name=f"run-{run_idx}",
-        config={"lr": 0.001 * (run_idx + 1), "epochs": EPOCHS},
-    )
-    for epoch in range(EPOCHS):
-        trackio.log(
-            {
-                "train/loss": round(fake_loss(epoch, EPOCHS), 4),
-                "train/accuracy": round(fake_accuracy(epoch, EPOCHS), 4),
-                "val/loss": round(fake_loss(epoch, EPOCHS) * 1.1, 4),
-            }
-        )
-    trackio.finish()
+trackio.init(project=PROJECT, name="run-0", config={"lr": 0.001, "epochs": EPOCHS})
+for epoch in range(EPOCHS):
+    loss, acc = fake_metrics(epoch, EPOCHS)
+    trackio.log({"train/loss": loss, "train/accuracy": acc})
+trackio.finish()
 
+print("First run complete. Syncing to a static Space...")
 space_id = trackio.sync(project=PROJECT, sdk="static")
 print(f"Dashboard: https://huggingface.co/spaces/{space_id}")
+
+trackio.init(project=PROJECT, name="run-1", config={"lr": 0.003, "epochs": EPOCHS})
+for epoch in range(EPOCHS):
+    loss, acc = fake_metrics(epoch, EPOCHS)
+    trackio.log({"train/loss": loss, "train/accuracy": acc})
+trackio.finish()
+
+print("Second run complete. Syncing again...")
+trackio.sync(project=PROJECT, sdk="static")
+print("Static Space updated with both runs.")

examples/transformers-integration.py

@@ -1,6 +1,6 @@
 # /// script
 # dependencies = [
-#   "trackio>=0.14.2",
+#   "trackio>=0.22.0",
 #   "datasets>=4.4.0",
 #   "transformers[torch]>=5.0.0rc2",
 #   "huggingface_hub>=1.0.0",
@@ -26,9 +26,11 @@
 encodings = tokenizer(texts, truncation=True, padding=True, max_length=64)
 dataset = Dataset.from_dict({**encodings, "labels": labels})
 
-username = huggingface_hub.whoami()["name"]
+username = huggingface_hub.whoami(cache=True)["name"]
 hub_model_id = f"{username}/trackio-transformers-demo"
 
+# Local Trackio logs by default; the first Hub push runs sync(sdk="static") and links the dashboard on the model card.
+
 trainer = Trainer(
     model=model,
     args=TrainingArguments(