Make static Spaces work with Buckets and also allow conversion from Gradio SDK to Static Spaces (#469)

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

Author: abidlabs

.changeset/tall-dryers-take.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Make static Spaces work with Buckets and also allow conversion from Gradio SDK to Static Spaces

examples/convert-gradio-to-static.py

@@ -0,0 +1,57 @@
+"""
+Example: deploy a Gradio Space during training, then convert it to a static Space once done.
+
+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)
+
+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,
+        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)
+
+        trackio.log(
+            {
+                "train/loss": round(max(0.01, loss), 4),
+                "train/accuracy": round(min(0.99, max(0, 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}")

examples/sync-static-space-everything.py

@@ -105,7 +105,7 @@ def main():
     trackio.log({"reports/summary": trackio.Markdown(report_md)})
     trackio.finish()
 
-    space_id = trackio.sync(project=PROJECT)
+    space_id = trackio.sync(project=PROJECT, sdk="static")
     print(f"Dashboard: https://huggingface.co/spaces/{space_id}")
 
 

examples/sync-static-space.py

@@ -49,5 +49,5 @@ def fake_accuracy(epoch, max_epochs):
         )
     trackio.finish()
 
-space_id = trackio.sync(project=PROJECT)
+space_id = trackio.sync(project=PROJECT, sdk="static")
 print(f"Dashboard: https://huggingface.co/spaces/{space_id}")

pyproject.toml

@@ -14,7 +14,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "pandas<3.0.0",
-    "huggingface-hub<2.0.0",
+    "huggingface-hub>=1.9.0,<2",
     "gradio[oauth]>=6.10.0,<7.0.0",
     "numpy<3.0.0",
     "pillow<12.0.0",

tests/unit/test_sqlite_storage.py

@@ -397,3 +397,29 @@ def test_rename_run_with_system_metrics(temp_dir):
 
     new_system_logs = SQLiteStorage.get_system_logs(project, new_name)
     assert new_system_logs[0]["gpu_usage"] == 80.5
+
+
+def test_bucket_upload_paths_match_mount_layout(temp_dir):
+    project = "proj_bucket"
+    SQLiteStorage.log(project=project, run="run1", metrics={"loss": 0.5})
+
+    media_dir = Path(temp_dir) / "media" / project
+    media_dir.mkdir(parents=True)
+    (media_dir / "img.png").write_bytes(b"fake")
+
+    db_path = SQLiteStorage.get_project_db_path(project)
+    files_to_add = [(str(db_path), f"trackio/{db_path.name}")]
+    for media_file in media_dir.rglob("*"):
+        if media_file.is_file():
+            rel = media_file.relative_to(Path(temp_dir))
+            files_to_add.append((str(media_file), f"trackio/{rel}"))
+
+    mount_point = Path("/data")
+    trackio_dir = mount_point / "trackio"
+    for local_path, remote_path in files_to_add:
+        mounted = mount_point / remote_path
+        assert str(mounted).startswith(str(trackio_dir)), (
+            f"Bucket path {remote_path!r} would mount at {mounted}, "
+            f"outside TRACKIO_DIR={trackio_dir}"
+        )
+        assert Path(local_path).exists()

trackio/__init__.py

@@ -259,9 +259,6 @@ def init(
             space_url = deploy.SPACE_HOST_URL.format(
                 user_name=user_name, space_name=space_name
             )
-            print(
-                f"* View dashboard by going to: {deploy._BOLD_ORANGE}{space_url}{deploy._RESET}"
-            )
             if utils.is_in_notebook() and embed:
                 utils.embed_url_in_notebook(space_url)
     context_vars.current_project.set(project)

trackio/bucket_storage.py

@@ -1,4 +1,7 @@
+import shutil
 import sqlite3
+import tempfile
+from pathlib import Path
 
 import huggingface_hub
 from huggingface_hub import sync_bucket
@@ -15,7 +18,7 @@ def download_bucket_to_trackio_dir(bucket_id: str) -> None:
     TRACKIO_DIR.mkdir(parents=True, exist_ok=True)
     sync_bucket(
         source=f"hf://buckets/{bucket_id}",
-        dest=str(TRACKIO_DIR),
+        dest=str(TRACKIO_DIR.parent),
         quiet=True,
     )
 
@@ -28,13 +31,63 @@ def upload_project_to_bucket(project: str, bucket_id: str) -> None:
     with sqlite3.connect(str(db_path), timeout=30.0) as conn:
         conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
 
-    files_to_add = [(str(db_path), db_path.name)]
+    files_to_add = [(str(db_path), f"trackio/{db_path.name}")]
 
     media_dir = MEDIA_DIR / project
     if media_dir.exists():
         for media_file in media_dir.rglob("*"):
             if media_file.is_file():
                 rel = media_file.relative_to(TRACKIO_DIR)
-                files_to_add.append((str(media_file), str(rel)))
+                files_to_add.append((str(media_file), f"trackio/{rel}"))
 
     huggingface_hub.batch_bucket_files(bucket_id, add=files_to_add)
+
+
+def _download_db_from_bucket(project: str, bucket_id: str) -> bool:
+    db_filename = SQLiteStorage.get_project_db_filename(project)
+    remote_path = f"trackio/{db_filename}"
+    local_path = SQLiteStorage.get_project_db_path(project)
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        huggingface_hub.download_bucket_files(
+            bucket_id,
+            files=[(remote_path, str(local_path))],
+        )
+        return local_path.exists()
+    except Exception:
+        return False
+
+
+def _local_db_has_data(project: str) -> bool:
+    db_path = SQLiteStorage.get_project_db_path(project)
+    if not db_path.exists() or db_path.stat().st_size == 0:
+        return False
+    conn = sqlite3.connect(str(db_path), timeout=5.0)
+    try:
+        count = conn.execute("SELECT COUNT(*) FROM metrics").fetchone()[0]
+        return count > 0
+    except Exception:
+        return False
+    finally:
+        conn.close()
+
+
+def upload_project_to_bucket_for_static(project: str, bucket_id: str) -> None:
+    if not _local_db_has_data(project):
+        _download_db_from_bucket(project, bucket_id)
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_dir = Path(tmp_dir)
+        SQLiteStorage.export_for_static_space(project, output_dir)
+
+        media_dir = MEDIA_DIR / project
+        if media_dir.exists():
+            shutil.copytree(media_dir, output_dir / "media")
+
+        files_to_add = []
+        for f in output_dir.rglob("*"):
+            if f.is_file():
+                rel = f.relative_to(output_dir)
+                files_to_add.append((str(f), str(rel)))
+
+        huggingface_hub.batch_bucket_files(bucket_id, add=files_to_add)

trackio/deploy.py

@@ -9,6 +9,7 @@
 import time
 from importlib.resources import files
 from pathlib import Path
+from typing import Literal
 
 if sys.version_info >= (3, 11):
     import tomllib
@@ -20,12 +21,14 @@
 import huggingface_hub
 from gradio_client import Client, handle_file
 from httpx import ReadTimeout
+from huggingface_hub import Volume
 from huggingface_hub.errors import HfHubHTTPError, RepositoryNotFoundError
 
 import trackio
-from trackio.bucket_storage import create_bucket_if_not_exists, upload_project_to_bucket
-from trackio.space_volumes import (
-    attach_bucket_volume,
+from trackio.bucket_storage import (
+    create_bucket_if_not_exists,
+    upload_project_to_bucket,
+    upload_project_to_bucket_for_static,
 )
 from trackio.sqlite_storage import SQLiteStorage
 from trackio.utils import (
@@ -233,14 +236,25 @@ def deploy_as_space(
     if hf_token := huggingface_hub.utils.get_token():
         huggingface_hub.add_space_secret(space_id, "HF_TOKEN", hf_token)
     if bucket_id is not None:
-        changed = attach_bucket_volume(
-            space_id,
-            bucket_id,
-            mount_path="/data",
+        runtime = hf_api.get_space_runtime(space_id)
+        existing = list(runtime.volumes) if runtime.volumes else []
+        already_mounted = any(
+            v.type == "bucket" and v.source == bucket_id and v.mount_path == "/data"
+            for v in existing
         )
-        huggingface_hub.add_space_variable(space_id, "TRACKIO_DIR", "/data/trackio")
-        if changed:
+        if not already_mounted:
+            non_bucket = [
+                v
+                for v in existing
+                if not (v.type == "bucket" and v.source == bucket_id)
+            ]
+            hf_api.set_space_volumes(
+                space_id,
+                non_bucket
+                + [Volume(type="bucket", source=bucket_id, mount_path="/data")],
+            )
             print(f"* Attached bucket {bucket_id} at '/data'")
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_DIR", "/data/trackio")
     elif dataset_id is not None:
         huggingface_hub.add_space_variable(space_id, "TRACKIO_DATASET_ID", dataset_id)
     if logo_light_url := os.environ.get("TRACKIO_LOGO_LIGHT_URL"):
@@ -687,7 +701,7 @@ def sync(
     private: bool | None = None,
     force: bool = False,
     run_in_background: bool = False,
-    sdk: str = "gradio",
+    sdk: Literal["gradio", "static"] = "gradio",
     dataset_id: str | None = None,
     bucket_id: str | None = None,
 ) -> str:
@@ -712,7 +726,7 @@ def sync(
         sdk (`str`, *optional*, defaults to `"gradio"`):
             The type of Space to deploy. `"gradio"` deploys a Gradio Space with a live
             server. `"static"` deploys a static Space that reads from an HF Dataset
-            (no server needed).
+            or HF Bucket (no server needed).
         dataset_id (`str`, *optional*):
             The ID of the HF Dataset to sync to. When provided, uses the legacy
             Dataset backend instead of Buckets.
@@ -734,6 +748,20 @@ def sync(
 
     def _do_sync():
         if sdk == "static":
+            try:
+                info = huggingface_hub.HfApi().space_info(space_id)
+                if info.sdk == "gradio":
+                    if not force:
+                        answer = input(
+                            f"Space '{space_id}' is currently a Gradio Space. "
+                            f"Convert to static? [y/N] "
+                        )
+                        if answer.lower() not in ("y", "yes"):
+                            print("Aborted.")
+                            return
+            except RepositoryNotFoundError:
+                pass
+
             if dataset_id is not None:
                 upload_dataset_for_static(project, dataset_id, private=private)
                 hf_token = huggingface_hub.utils.get_token() if private else None
@@ -746,7 +774,7 @@ def _do_sync():
                 )
             elif bucket_id is not None:
                 create_bucket_if_not_exists(bucket_id, private=private)
-                upload_project_to_bucket(project, bucket_id)
+                upload_project_to_bucket_for_static(project, bucket_id)
                 print(
                     f"* Project data uploaded to bucket: https://huggingface.co/buckets/{bucket_id}"
                 )