Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/trackio_logo_old.png filter=lfs diff=lfs merge=lfs -text

__init__.py

@@ -0,0 +1,203 @@
+import hashlib
+import os
+import warnings
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+from gradio.blocks import BUILT_IN_THEMES
+from gradio.themes import Default as DefaultTheme
+from gradio.themes import ThemeClass
+from gradio_client import Client
+
+from trackio import context_vars, deploy, utils
+from trackio.imports import import_csv, import_tf_events
+from trackio.media import TrackioImage
+from trackio.run import Run
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.ui import demo
+from trackio.utils import TRACKIO_DIR, TRACKIO_LOGO_DIR
+
+__version__ = Path(__file__).parent.joinpath("version.txt").read_text().strip()
+
+__all__ = ["init", "log", "finish", "show", "import_csv", "import_tf_events", "Image"]
+
+Image = TrackioImage
+
+
+config = {}
+
+DEFAULT_THEME = "citrus"
+
+
+def init(
+    project: str,
+    name: str | None = None,
+    space_id: str | None = None,
+    dataset_id: str | None = None,
+    config: dict | None = None,
+    resume: str = "never",
+    settings: Any = None,
+) -> Run:
+    """
+    Creates a new Trackio project and returns a Run object.
+
+    Args:
+        project: The name of the project (can be an existing project to continue tracking or a new project to start tracking from scratch).
+        name: The name of the run (if not provided, a default name will be generated).
+        space_id: If provided, the project will be logged to a Hugging Face Space instead of a local directory. Should be a complete Space name like "username/reponame" or "orgname/reponame", or just "reponame" in which case the Space will be created in the currently-logged-in Hugging Face user's namespace. If the Space does not exist, it will be created. If the Space already exists, the project will be logged to it.
+        dataset_id: If a space_id is provided, a persistent Hugging Face Dataset will be created and the metrics will be synced to it every 5 minutes. Specify a Dataset with name like "username/datasetname" or "orgname/datasetname", or "datasetname" (uses currently-logged-in Hugging Face user's namespace), or None (uses the same name as the Space but with the "_dataset" suffix). If the Dataset does not exist, it will be created. If the Dataset already exists, the project will be appended to it.
+        config: A dictionary of configuration options. Provided for compatibility with wandb.init()
+        resume: Controls how to handle resuming a run. Can be one of:
+            - "must": Must resume the run with the given name, raises error if run doesn't exist
+            - "allow": Resume the run if it exists, otherwise create a new run
+            - "never": Never resume a run, always create a new one
+        settings: Not used. Provided for compatibility with wandb.init()
+    """
+    if settings is not None:
+        warnings.warn(
+            "* Warning: settings is not used. Provided for compatibility with wandb.init(). Please create an issue at: https://github.com/gradio-app/trackio/issues if you need a specific feature implemented."
+        )
+
+    if space_id is None and dataset_id is not None:
+        raise ValueError("Must provide a `space_id` when `dataset_id` is provided.")
+    space_id, dataset_id = utils.preprocess_space_and_dataset_ids(space_id, dataset_id)
+    url = context_vars.current_server.get()
+
+    if url is None:
+        if space_id is None:
+            _, url, _ = demo.launch(
+                show_api=False,
+                inline=False,
+                quiet=True,
+                prevent_thread_lock=True,
+                show_error=True,
+            )
+        else:
+            url = space_id
+        context_vars.current_server.set(url)
+
+    if (
+        context_vars.current_project.get() is None
+        or context_vars.current_project.get() != project
+    ):
+        print(f"* Trackio project initialized: {project}")
+
+        if dataset_id is not None:
+            os.environ["TRACKIO_DATASET_ID"] = dataset_id
+            print(
+                f"* Trackio metrics will be synced to Hugging Face Dataset: {dataset_id}"
+            )
+        if space_id is None:
+            print(f"* Trackio metrics logged to: {TRACKIO_DIR}")
+            utils.print_dashboard_instructions(project)
+        else:
+            deploy.create_space_if_not_exists(space_id, dataset_id)
+            print(
+                f"* View dashboard by going to: {deploy.SPACE_URL.format(space_id=space_id)}"
+            )
+    context_vars.current_project.set(project)
+
+    client = None
+    if not space_id:
+        client = Client(url, verbose=False)
+
+    if resume == "must":
+        if name is None:
+            raise ValueError("Must provide a run name when resume='must'")
+        if name not in SQLiteStorage.get_runs(project):
+            raise ValueError(f"Run '{name}' does not exist in project '{project}'")
+    elif resume == "allow":
+        if name is not None and name in SQLiteStorage.get_runs(project):
+            print(f"* Resuming existing run: {name}")
+    elif resume == "never":
+        if name is not None and name in SQLiteStorage.get_runs(project):
+            name = None
+    else:
+        raise ValueError("resume must be one of: 'must', 'allow', or 'never'")
+
+    run = Run(
+        url=url,
+        project=project,
+        client=client,
+        name=name,
+        config=config,
+        space_id=space_id,
+    )
+    context_vars.current_run.set(run)
+    globals()["config"] = run.config
+    return run
+
+
+def log(metrics: dict, step: int | None = None) -> None:
+    """
+    Logs metrics to the current run.
+
+    Args:
+        metrics: A dictionary of metrics to log.
+        step: The step number. If not provided, the step will be incremented automatically.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.log().")
+    run.log(
+        metrics=metrics,
+        step=step,
+    )
+
+
+def finish():
+    """
+    Finishes the current run.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.finish().")
+    run.finish()
+
+
+def show(project: str | None = None, theme: str | ThemeClass = DEFAULT_THEME):
+    """
+    Launches the Trackio dashboard.
+
+    Args:
+        project: The name of the project whose runs to show. If not provided, all projects will be shown and the user can select one.
+        theme: The Gradio theme to use. Can be any built-in Gradio theme (e.g. "citrus", "soft", "default"), theme from the Hub (https://huggingface.co/spaces/gradio/theme-gallery), or a custom gradio.themes.ThemeClass
+    """
+    if theme != DEFAULT_THEME:
+        # TODO: It's a little hacky to reproduce this theme-setting logic from Gradio Blocks,
+        # but in Gradio 6.0, the theme will be set in `launch()` instead, which means that we
+        # will be able to remove this code.
+        if isinstance(theme, str):
+            if theme.lower() in BUILT_IN_THEMES:
+                theme = BUILT_IN_THEMES[theme.lower()]
+            else:
+                try:
+                    theme = ThemeClass.from_hub(theme)
+                except Exception as e:
+                    warnings.warn(f"Cannot load {theme}. Caught Exception: {str(e)}")
+                    theme = DefaultTheme()
+        if not isinstance(theme, ThemeClass):
+            warnings.warn("Theme should be a class loaded from gradio.themes")
+            theme = DefaultTheme()
+        demo.theme: ThemeClass = theme
+        demo.theme_css = theme._get_theme_css()
+        demo.stylesheets = theme._stylesheets
+        theme_hasher = hashlib.sha256()
+        theme_hasher.update(demo.theme_css.encode("utf-8"))
+        demo.theme_hash = theme_hasher.hexdigest()
+
+    _, url, share_url = demo.launch(
+        show_api=False,
+        quiet=True,
+        inline=False,
+        prevent_thread_lock=True,
+        favicon_path=TRACKIO_LOGO_DIR / "trackio_logo_light.png",
+        allowed_paths=[TRACKIO_LOGO_DIR],
+    )
+
+    base_url = share_url + "/" if share_url else url
+    dashboard_url = base_url + f"?project={project}" if project else base_url
+    print(f"* Trackio UI launched at: {dashboard_url}")
+    webbrowser.open(dashboard_url)
+    utils.block_except_in_notebook()

cli.py

@@ -0,0 +1,32 @@
+import argparse
+
+from trackio import show
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Trackio CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    ui_parser = subparsers.add_parser(
+        "show", help="Show the Trackio dashboard UI for a project"
+    )
+    ui_parser.add_argument(
+        "--project", required=False, help="Project name to show in the dashboard"
+    )
+    ui_parser.add_argument(
+        "--theme",
+        required=False,
+        default="citrus",
+        help="A Gradio Theme to use for the dashboard instead of the default 'citrus', can be a built-in theme (e.g. 'soft', 'default'), a theme from the Hub (e.g. 'gstaff/xkcd').",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "show":
+        show(args.project, args.theme)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

commit_scheduler.py

@@ -0,0 +1,391 @@
+# Originally copied from https://github.com/huggingface/huggingface_hub/blob/d0a948fc2a32ed6e557042a95ef3e4af97ec4a7c/src/huggingface_hub/_commit_scheduler.py
+
+import atexit
+import logging
+import os
+import time
+from concurrent.futures import Future
+from dataclasses import dataclass
+from io import SEEK_END, SEEK_SET, BytesIO
+from pathlib import Path
+from threading import Lock, Thread
+from typing import Callable, Dict, List, Optional, Union
+
+from huggingface_hub.hf_api import (
+    DEFAULT_IGNORE_PATTERNS,
+    CommitInfo,
+    CommitOperationAdd,
+    HfApi,
+)
+from huggingface_hub.utils import filter_repo_objects
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class _FileToUpload:
+    """Temporary dataclass to store info about files to upload. Not meant to be used directly."""
+
+    local_path: Path
+    path_in_repo: str
+    size_limit: int
+    last_modified: float
+
+
+class CommitScheduler:
+    """
+    Scheduler to upload a local folder to the Hub at regular intervals (e.g. push to hub every 5 minutes).
+
+    The recommended way to use the scheduler is to use it as a context manager. This ensures that the scheduler is
+    properly stopped and the last commit is triggered when the script ends. The scheduler can also be stopped manually
+    with the `stop` method. Checkout the [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#scheduled-uploads)
+    to learn more about how to use it.
+
+    Args:
+        repo_id (`str`):
+            The id of the repo to commit to.
+        folder_path (`str` or `Path`):
+            Path to the local folder to upload regularly.
+        every (`int` or `float`, *optional*):
+            The number of minutes between each commit. Defaults to 5 minutes.
+        path_in_repo (`str`, *optional*):
+            Relative path of the directory in the repo, for example: `"checkpoints/"`. Defaults to the root folder
+            of the repository.
+        repo_type (`str`, *optional*):
+            The type of the repo to commit to. Defaults to `model`.
+        revision (`str`, *optional*):
+            The revision of the repo to commit to. Defaults to `main`.
+        private (`bool`, *optional*):
+            Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists.
+        token (`str`, *optional*):
+            The token to use to commit to the repo. Defaults to the token saved on the machine.
+        allow_patterns (`List[str]` or `str`, *optional*):
+            If provided, only files matching at least one pattern are uploaded.
+        ignore_patterns (`List[str]` or `str`, *optional*):
+            If provided, files matching any of the patterns are not uploaded.
+        squash_history (`bool`, *optional*):
+            Whether to squash the history of the repo after each commit. Defaults to `False`. Squashing commits is
+            useful to avoid degraded performances on the repo when it grows too large.
+        hf_api (`HfApi`, *optional*):
+            The [`HfApi`] client to use to commit to the Hub. Can be set with custom settings (user agent, token,...).
+        on_before_commit (`Callable[[], None]`, *optional*):
+            If specified, a function that will be called before the CommitScheduler lists files to create a commit.
+
+    Example:
+    ```py
+    >>> from pathlib import Path
+    >>> from huggingface_hub import CommitScheduler
+
+    # Scheduler uploads every 10 minutes
+    >>> csv_path = Path("watched_folder/data.csv")
+    >>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10)
+
+    >>> with csv_path.open("a") as f:
+    ...     f.write("first line")
+
+    # Some time later (...)
+    >>> with csv_path.open("a") as f:
+    ...     f.write("second line")
+    ```
+
+    Example using a context manager:
+    ```py
+    >>> from pathlib import Path
+    >>> from huggingface_hub import CommitScheduler
+
+    >>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler:
+    ...     csv_path = Path("watched_folder/data.csv")
+    ...     with csv_path.open("a") as f:
+    ...         f.write("first line")
+    ...     (...)
+    ...     with csv_path.open("a") as f:
+    ...         f.write("second line")
+
+    # Scheduler is now stopped and last commit have been triggered
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        repo_id: str,
+        folder_path: Union[str, Path],
+        every: Union[int, float] = 5,
+        path_in_repo: Optional[str] = None,
+        repo_type: Optional[str] = None,
+        revision: Optional[str] = None,
+        private: Optional[bool] = None,
+        token: Optional[str] = None,
+        allow_patterns: Optional[Union[List[str], str]] = None,
+        ignore_patterns: Optional[Union[List[str], str]] = None,
+        squash_history: bool = False,
+        hf_api: Optional["HfApi"] = None,
+        on_before_commit: Optional[Callable[[], None]] = None,
+    ) -> None:
+        self.api = hf_api or HfApi(token=token)
+        self.on_before_commit = on_before_commit
+
+        # Folder
+        self.folder_path = Path(folder_path).expanduser().resolve()
+        self.path_in_repo = path_in_repo or ""
+        self.allow_patterns = allow_patterns
+
+        if ignore_patterns is None:
+            ignore_patterns = []
+        elif isinstance(ignore_patterns, str):
+            ignore_patterns = [ignore_patterns]
+        self.ignore_patterns = ignore_patterns + DEFAULT_IGNORE_PATTERNS
+
+        if self.folder_path.is_file():
+            raise ValueError(
+                f"'folder_path' must be a directory, not a file: '{self.folder_path}'."
+            )
+        self.folder_path.mkdir(parents=True, exist_ok=True)
+
+        # Repository
+        repo_url = self.api.create_repo(
+            repo_id=repo_id, private=private, repo_type=repo_type, exist_ok=True
+        )
+        self.repo_id = repo_url.repo_id
+        self.repo_type = repo_type
+        self.revision = revision
+        self.token = token
+
+        self.last_uploaded: Dict[Path, float] = {}
+        self.last_push_time: float | None = None
+
+        if not every > 0:
+            raise ValueError(f"'every' must be a positive integer, not '{every}'.")
+        self.lock = Lock()
+        self.every = every
+        self.squash_history = squash_history
+
+        logger.info(
+            f"Scheduled job to push '{self.folder_path}' to '{self.repo_id}' every {self.every} minutes."
+        )
+        self._scheduler_thread = Thread(target=self._run_scheduler, daemon=True)
+        self._scheduler_thread.start()
+        atexit.register(self._push_to_hub)
+
+        self.__stopped = False
+
+    def stop(self) -> None:
+        """Stop the scheduler.
+
+        A stopped scheduler cannot be restarted. Mostly for tests purposes.
+        """
+        self.__stopped = True
+
+    def __enter__(self) -> "CommitScheduler":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        # Upload last changes before exiting
+        self.trigger().result()
+        self.stop()
+        return
+
+    def _run_scheduler(self) -> None:
+        """Dumb thread waiting between each scheduled push to Hub."""
+        while True:
+            self.last_future = self.trigger()
+            time.sleep(self.every * 60)
+            if self.__stopped:
+                break
+
+    def trigger(self) -> Future:
+        """Trigger a `push_to_hub` and return a future.
+
+        This method is automatically called every `every` minutes. You can also call it manually to trigger a commit
+        immediately, without waiting for the next scheduled commit.
+        """
+        return self.api.run_as_future(self._push_to_hub)
+
+    def _push_to_hub(self) -> Optional[CommitInfo]:
+        if self.__stopped:  # If stopped, already scheduled commits are ignored
+            return None
+
+        logger.info("(Background) scheduled commit triggered.")
+        try:
+            value = self.push_to_hub()
+            if self.squash_history:
+                logger.info("(Background) squashing repo history.")
+                self.api.super_squash_history(
+                    repo_id=self.repo_id, repo_type=self.repo_type, branch=self.revision
+                )
+            return value
+        except Exception as e:
+            logger.error(
+                f"Error while pushing to Hub: {e}"
+            )  # Depending on the setup, error might be silenced
+            raise
+
+    def push_to_hub(self) -> Optional[CommitInfo]:
+        """
+        Push folder to the Hub and return the commit info.
+
+        <Tip warning={true}>
+
+        This method is not meant to be called directly. It is run in the background by the scheduler, respecting a
+        queue mechanism to avoid concurrent commits. Making a direct call to the method might lead to concurrency
+        issues.
+
+        </Tip>
+
+        The default behavior of `push_to_hub` is to assume an append-only folder. It lists all files in the folder and
+        uploads only changed files. If no changes are found, the method returns without committing anything. If you want
+        to change this behavior, you can inherit from [`CommitScheduler`] and override this method. This can be useful
+        for example to compress data together in a single file before committing. For more details and examples, check
+        out our [integration guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload#scheduled-uploads).
+        """
+        # Check files to upload (with lock)
+        with self.lock:
+            if self.on_before_commit is not None:
+                self.on_before_commit()
+
+            logger.debug("Listing files to upload for scheduled commit.")
+
+            # List files from folder (taken from `_prepare_upload_folder_additions`)
+            relpath_to_abspath = {
+                path.relative_to(self.folder_path).as_posix(): path
+                for path in sorted(
+                    self.folder_path.glob("**/*")
+                )  # sorted to be deterministic
+                if path.is_file()
+            }
+            prefix = f"{self.path_in_repo.strip('/')}/" if self.path_in_repo else ""
+
+            # Filter with pattern + filter out unchanged files + retrieve current file size
+            files_to_upload: List[_FileToUpload] = []
+            for relpath in filter_repo_objects(
+                relpath_to_abspath.keys(),
+                allow_patterns=self.allow_patterns,
+                ignore_patterns=self.ignore_patterns,
+            ):
+                local_path = relpath_to_abspath[relpath]
+                stat = local_path.stat()
+                if (
+                    self.last_uploaded.get(local_path) is None
+                    or self.last_uploaded[local_path] != stat.st_mtime
+                ):
+                    files_to_upload.append(
+                        _FileToUpload(
+                            local_path=local_path,
+                            path_in_repo=prefix + relpath,
+                            size_limit=stat.st_size,
+                            last_modified=stat.st_mtime,
+                        )
+                    )
+
+        # Return if nothing to upload
+        if len(files_to_upload) == 0:
+            logger.debug("Dropping schedule commit: no changed file to upload.")
+            return None
+
+        # Convert `_FileToUpload` as `CommitOperationAdd` (=> compute file shas + limit to file size)
+        logger.debug("Removing unchanged files since previous scheduled commit.")
+        add_operations = [
+            CommitOperationAdd(
+                # TODO: Cap the file to its current size, even if the user append data to it while a scheduled commit is happening
+                # (requires an upstream fix for XET-535: `hf_xet` should support `BinaryIO` for upload)
+                path_or_fileobj=file_to_upload.local_path,
+                path_in_repo=file_to_upload.path_in_repo,
+            )
+            for file_to_upload in files_to_upload
+        ]
+
+        # Upload files (append mode expected - no need for lock)
+        logger.debug("Uploading files for scheduled commit.")
+        commit_info = self.api.create_commit(
+            repo_id=self.repo_id,
+            repo_type=self.repo_type,
+            operations=add_operations,
+            commit_message="Scheduled Commit",
+            revision=self.revision,
+        )
+
+        for file in files_to_upload:
+            self.last_uploaded[file.local_path] = file.last_modified
+
+        self.last_push_time = time.time()
+
+        return commit_info
+
+
+class PartialFileIO(BytesIO):
+    """A file-like object that reads only the first part of a file.
+
+    Useful to upload a file to the Hub when the user might still be appending data to it. Only the first part of the
+    file is uploaded (i.e. the part that was available when the filesystem was first scanned).
+
+    In practice, only used internally by the CommitScheduler to regularly push a folder to the Hub with minimal
+    disturbance for the user. The object is passed to `CommitOperationAdd`.
+
+    Only supports `read`, `tell` and `seek` methods.
+
+    Args:
+        file_path (`str` or `Path`):
+            Path to the file to read.
+        size_limit (`int`):
+            The maximum number of bytes to read from the file. If the file is larger than this, only the first part
+            will be read (and uploaded).
+    """
+
+    def __init__(self, file_path: Union[str, Path], size_limit: int) -> None:
+        self._file_path = Path(file_path)
+        self._file = self._file_path.open("rb")
+        self._size_limit = min(size_limit, os.fstat(self._file.fileno()).st_size)
+
+    def __del__(self) -> None:
+        self._file.close()
+        return super().__del__()
+
+    def __repr__(self) -> str:
+        return (
+            f"<PartialFileIO file_path={self._file_path} size_limit={self._size_limit}>"
+        )
+
+    def __len__(self) -> int:
+        return self._size_limit
+
+    def __getattribute__(self, name: str):
+        if name.startswith("_") or name in (
+            "read",
+            "tell",
+            "seek",
+        ):  # only 3 public methods supported
+            return super().__getattribute__(name)
+        raise NotImplementedError(f"PartialFileIO does not support '{name}'.")
+
+    def tell(self) -> int:
+        """Return the current file position."""
+        return self._file.tell()
+
+    def seek(self, __offset: int, __whence: int = SEEK_SET) -> int:
+        """Change the stream position to the given offset.
+
+        Behavior is the same as a regular file, except that the position is capped to the size limit.
+        """
+        if __whence == SEEK_END:
+            # SEEK_END => set from the truncated end
+            __offset = len(self) + __offset
+            __whence = SEEK_SET
+
+        pos = self._file.seek(__offset, __whence)
+        if pos > self._size_limit:
+            return self._file.seek(self._size_limit)
+        return pos
+
+    def read(self, __size: Optional[int] = -1) -> bytes:
+        """Read at most `__size` bytes from the file.
+
+        Behavior is the same as a regular file, except that it is capped to the size limit.
+        """
+        current = self._file.tell()
+        if __size is None or __size < 0:
+            # Read until file limit
+            truncated_size = self._size_limit - current
+        else:
+            # Read until file limit or __size
+            truncated_size = min(__size, self._size_limit - current)
+        return self._file.read(truncated_size)

context_vars.py

@@ -0,0 +1,15 @@
+import contextvars
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from trackio.run import Run
+
+current_run: contextvars.ContextVar["Run | None"] = contextvars.ContextVar(
+    "current_run", default=None
+)
+current_project: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_project", default=None
+)
+current_server: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_server", default=None
+)

deploy.py

@@ -0,0 +1,171 @@
+import io
+import os
+import time
+from importlib.resources import files
+from pathlib import Path
+
+import gradio
+import huggingface_hub
+from gradio_client import Client, handle_file
+from httpx import ReadTimeout
+from huggingface_hub.errors import RepositoryNotFoundError
+from requests import HTTPError
+
+from trackio.sqlite_storage import SQLiteStorage
+
+SPACE_URL = "https://huggingface.co/spaces/{space_id}"
+PERSISTENT_STORAGE_DIR = "/data/.huggingface/trackio"
+
+
+def deploy_as_space(
+    space_id: str,
+    dataset_id: str | None = None,
+):
+    if (
+        os.getenv("SYSTEM") == "spaces"
+    ):  # in case a repo with this function is uploaded to spaces
+        return
+
+    trackio_path = files("trackio")
+
+    hf_api = huggingface_hub.HfApi()
+
+    try:
+        huggingface_hub.create_repo(
+            space_id,
+            space_sdk="gradio",
+            repo_type="space",
+            exist_ok=True,
+        )
+    except HTTPError as e:
+        if e.response.status_code in [401, 403]:  # unauthorized or forbidden
+            print("Need 'write' access token to create a Spaces repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+            huggingface_hub.create_repo(
+                space_id,
+                space_sdk="gradio",
+                repo_type="space",
+                exist_ok=True,
+            )
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    with open(Path(trackio_path, "README.md"), "r") as f:
+        readme_content = f.read()
+        readme_content = readme_content.replace("{GRADIO_VERSION}", gradio.__version__)
+        readme_buffer = io.BytesIO(readme_content.encode("utf-8"))
+        hf_api.upload_file(
+            path_or_fileobj=readme_buffer,
+            path_in_repo="README.md",
+            repo_id=space_id,
+            repo_type="space",
+        )
+
+    # We can assume pandas, gradio, and huggingface-hub are already installed in a Gradio Space.
+    # Make sure necessary dependencies are installed by creating a requirements.txt.
+    requirements_content = """
+pyarrow>=21.0
+    """
+    requirements_buffer = io.BytesIO(requirements_content.encode("utf-8"))
+    hf_api.upload_file(
+        path_or_fileobj=requirements_buffer,
+        path_in_repo="requirements.txt",
+        repo_id=space_id,
+        repo_type="space",
+    )
+
+    huggingface_hub.utils.disable_progress_bars()
+    hf_api.upload_folder(
+        repo_id=space_id,
+        repo_type="space",
+        folder_path=trackio_path,
+        ignore_patterns=["README.md"],
+    )
+
+    huggingface_hub.add_space_variable(space_id, "TRACKIO_DIR", PERSISTENT_STORAGE_DIR)
+    if hf_token := huggingface_hub.utils.get_token():
+        huggingface_hub.add_space_secret(space_id, "HF_TOKEN", hf_token)
+    if dataset_id is not None:
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_DATASET_ID", dataset_id)
+
+
+def create_space_if_not_exists(
+    space_id: str,
+    dataset_id: str | None = None,
+) -> None:
+    """
+    Creates a new Hugging Face Space if it does not exist. If a dataset_id is provided, it will be added as a space variable.
+
+    Args:
+        space_id: The ID of the Space to create.
+        dataset_id: The ID of the Dataset to add to the Space.
+    """
+    if "/" not in space_id:
+        raise ValueError(
+            f"Invalid space ID: {space_id}. Must be in the format: username/reponame or orgname/reponame."
+        )
+    if dataset_id is not None and "/" not in dataset_id:
+        raise ValueError(
+            f"Invalid dataset ID: {dataset_id}. Must be in the format: username/datasetname or orgname/datasetname."
+        )
+    try:
+        huggingface_hub.repo_info(space_id, repo_type="space")
+        print(f"* Found existing space: {SPACE_URL.format(space_id=space_id)}")
+        if dataset_id is not None:
+            huggingface_hub.add_space_variable(
+                space_id, "TRACKIO_DATASET_ID", dataset_id
+            )
+        return
+    except RepositoryNotFoundError:
+        pass
+    except HTTPError as e:
+        if e.response.status_code in [401, 403]:  # unauthorized or forbidden
+            print("Need 'write' access token to create a Spaces repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+            huggingface_hub.add_space_variable(
+                space_id, "TRACKIO_DATASET_ID", dataset_id
+            )
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    print(f"* Creating new space: {SPACE_URL.format(space_id=space_id)}")
+    deploy_as_space(space_id, dataset_id)
+
+
+def wait_until_space_exists(
+    space_id: str,
+) -> None:
+    """
+    Blocks the current thread until the space exists.
+    May raise a TimeoutError if this takes quite a while.
+
+    Args:
+        space_id: The ID of the Space to wait for.
+    """
+    delay = 1
+    for _ in range(10):
+        try:
+            Client(space_id, verbose=False)
+            return
+        except (ReadTimeout, ValueError):
+            time.sleep(delay)
+            delay = min(delay * 2, 30)
+    raise TimeoutError("Waiting for space to exist took longer than expected")
+
+
+def upload_db_to_space(project: str, space_id: str) -> None:
+    """
+    Uploads the database of a local Trackio project to a Hugging Face Space.
+
+    Args:
+        project: The name of the project to upload.
+        space_id: The ID of the Space to upload to.
+    """
+    db_path = SQLiteStorage.get_project_db_path(project)
+    client = Client(space_id, verbose=False)
+    client.predict(
+        api_name="/upload_db_to_space",
+        project=project,
+        uploaded_db=handle_file(db_path),
+        hf_token=huggingface_hub.utils.get_token(),
+    )

dummy_commit_scheduler.py

@@ -0,0 +1,12 @@
+# A dummy object to fit the interface of huggingface_hub's CommitScheduler
+class DummyCommitSchedulerLock:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, exception_type, exception_value, exception_traceback):
+        pass
+
+
+class DummyCommitScheduler:
+    def __init__(self):
+        self.lock = DummyCommitSchedulerLock()

file_storage.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+
+from PIL import Image as PILImage
+
+try:  # absolute imports when installed
+    from trackio.utils import TRACKIO_DIR
+except ImportError:  # relative imports for local execution on Spaces
+    from utils import TRACKIO_DIR
+
+
+class FileStorage:
+    @staticmethod
+    def get_project_media_path(
+        project: str,
+        run: str | None = None,
+        step: int | None = None,
+        filename: str | None = None,
+    ) -> Path:
+        if filename is not None and step is None:
+            raise ValueError("filename requires step")
+        if step is not None and run is None:
+            raise ValueError("step requires run")
+
+        path = TRACKIO_DIR / "media" / project
+        if run:
+            path /= run
+        if step is not None:
+            path /= str(step)
+        if filename:
+            path /= filename
+        return path
+
+    @staticmethod
+    def init_project_media_path(
+        project: str, run: str | None = None, step: int | None = None
+    ) -> Path:
+        path = FileStorage.get_project_media_path(project, run, step)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    @staticmethod
+    def save_image(
+        image: PILImage.Image,
+        project: str,
+        run: str,
+        step: int,
+        filename: str,
+        format: str = "PNG",
+    ) -> Path:
+        path = FileStorage.init_project_media_path(project, run, step) / filename
+        image.save(path, format=format)
+        return path
+
+    @staticmethod
+    def get_image(project: str, run: str, step: int, filename: str) -> PILImage.Image:
+        path = FileStorage.get_project_media_path(project, run, step, filename)
+        if not path.exists():
+            raise FileNotFoundError(f"Image file not found: {path}")
+        return PILImage.open(path).convert("RGBA")

imports.py

@@ -0,0 +1,245 @@
+import os
+from pathlib import Path
+
+import pandas as pd
+
+from trackio import deploy, utils
+from trackio.sqlite_storage import SQLiteStorage
+
+
+def import_csv(
+    csv_path: str | Path,
+    project: str,
+    name: str | None = None,
+    space_id: str | None = None,
+    dataset_id: str | None = None,
+) -> None:
+    """
+    Imports a CSV file into a Trackio project. The CSV file must contain a "step" column, may optionally
+    contain a "timestamp" column, and any other columns will be treated as metrics. It should also include
+    a header row with the column names.
+
+    TODO: call init() and return a Run object so that the user can continue to log metrics to it.
+
+    Args:
+        csv_path: The str or Path to the CSV file to import.
+        project: The name of the project to import the CSV file into. Must not be an existing project.
+        name: The name of the Run to import the CSV file into. If not provided, a default name will be generated.
+        name: The name of the run (if not provided, a default name will be generated).
+        space_id: If provided, the project will be logged to a Hugging Face Space instead of a local directory. Should be a complete Space name like "username/reponame" or "orgname/reponame", or just "reponame" in which case the Space will be created in the currently-logged-in Hugging Face user's namespace. If the Space does not exist, it will be created. If the Space already exists, the project will be logged to it.
+        dataset_id: If provided, a persistent Hugging Face Dataset will be created and the metrics will be synced to it every 5 minutes. Should be a complete Dataset name like "username/datasetname" or "orgname/datasetname", or just "datasetname" in which case the Dataset will be created in the currently-logged-in Hugging Face user's namespace. If the Dataset does not exist, it will be created. If the Dataset already exists, the project will be appended to it. If not provided, the metrics will be logged to a local SQLite database, unless a `space_id` is provided, in which case a Dataset will be automatically created with the same name as the Space but with the "_dataset" suffix.
+    """
+    if SQLiteStorage.get_runs(project):
+        raise ValueError(
+            f"Project '{project}' already exists. Cannot import CSV into existing project."
+        )
+
+    csv_path = Path(csv_path)
+    if not csv_path.exists():
+        raise FileNotFoundError(f"CSV file not found: {csv_path}")
+
+    df = pd.read_csv(csv_path)
+    if df.empty:
+        raise ValueError("CSV file is empty")
+
+    column_mapping = utils.simplify_column_names(df.columns.tolist())
+    df = df.rename(columns=column_mapping)
+
+    step_column = None
+    for col in df.columns:
+        if col.lower() == "step":
+            step_column = col
+            break
+
+    if step_column is None:
+        raise ValueError("CSV file must contain a 'step' or 'Step' column")
+
+    if name is None:
+        name = csv_path.stem
+
+    metrics_list = []
+    steps = []
+    timestamps = []
+
+    numeric_columns = []
+    for column in df.columns:
+        if column == step_column:
+            continue
+        if column == "timestamp":
+            continue
+
+        try:
+            pd.to_numeric(df[column], errors="raise")
+            numeric_columns.append(column)
+        except (ValueError, TypeError):
+            continue
+
+    for _, row in df.iterrows():
+        metrics = {}
+        for column in numeric_columns:
+            value = row[column]
+            if bool(pd.notna(value)):
+                metrics[column] = float(value)
+
+        if metrics:
+            metrics_list.append(metrics)
+            steps.append(int(row[step_column]))
+
+            if "timestamp" in df.columns and bool(pd.notna(row["timestamp"])):
+                timestamps.append(str(row["timestamp"]))
+            else:
+                timestamps.append("")
+
+    if metrics_list:
+        SQLiteStorage.bulk_log(
+            project=project,
+            run=name,
+            metrics_list=metrics_list,
+            steps=steps,
+            timestamps=timestamps,
+        )
+
+    print(
+        f"* Imported {len(metrics_list)} rows from {csv_path} into project '{project}' as run '{name}'"
+    )
+    print(f"* Metrics found: {', '.join(metrics_list[0].keys())}")
+
+    space_id, dataset_id = utils.preprocess_space_and_dataset_ids(space_id, dataset_id)
+    if dataset_id is not None:
+        os.environ["TRACKIO_DATASET_ID"] = dataset_id
+        print(f"* Trackio metrics will be synced to Hugging Face Dataset: {dataset_id}")
+
+    if space_id is None:
+        utils.print_dashboard_instructions(project)
+    else:
+        deploy.create_space_if_not_exists(space_id, dataset_id)
+        deploy.wait_until_space_exists(space_id)
+        deploy.upload_db_to_space(project, space_id)
+        print(
+            f"* View dashboard by going to: {deploy.SPACE_URL.format(space_id=space_id)}"
+        )
+
+
+def import_tf_events(
+    log_dir: str | Path,
+    project: str,
+    name: str | None = None,
+    space_id: str | None = None,
+    dataset_id: str | None = None,
+) -> None:
+    """
+    Imports TensorFlow Events files from a directory into a Trackio project.
+    Each subdirectory in the log directory will be imported as a separate run.
+
+    Args:
+        log_dir: The str or Path to the directory containing TensorFlow Events files.
+        project: The name of the project to import the TensorFlow Events files into. Must not be an existing project.
+        name: The name prefix for runs (if not provided, will use directory names). Each subdirectory will create a separate run.
+        space_id: If provided, the project will be logged to a Hugging Face Space instead of a local directory. Should be a complete Space name like username/reponame" ororgname/reponame", or just "reponame" in which case the Space will be created in the currently-logged-in Hugging Face user's namespace. If the Space does not exist, it will be created. If the Space already exists, the project will be logged to it.
+        dataset_id: If provided, a persistent Hugging Face Dataset will be created and the metrics will be synced to it every 5 minutes. Should be a complete Dataset name likeusername/datasetname" or "orgname/datasetname", or just "datasetname" in which case the Dataset will be created in the currently-logged-in Hugging Face user's namespace. If the Dataset does not exist, it will be created. If the Dataset already exists, the project will be appended to it. If not provided, the metrics will be logged to a local SQLite database, unless a `space_id` is provided, in which case a Dataset will be automatically created with the same name as the Space but with the_dataset suffix.
+    """
+    try:
+        from tbparse import SummaryReader
+    except ImportError:
+        raise ImportError(
+            "The `tbparse` package is not installed but is required for `import_tf_events`. Please install trackio with the `tensorboard` extra: `pip install trackio[tensorboard]`."
+        )
+
+    if SQLiteStorage.get_runs(project):
+        raise ValueError(
+            f"Project '{project}' already exists. Cannot import TF events into existing project."
+        )
+
+    path = Path(log_dir)
+    if not path.exists():
+        raise FileNotFoundError(f"TF events directory not found: {path}")
+
+    # Use tbparse to read all tfevents files in the directory structure
+    reader = SummaryReader(str(path), extra_columns={"dir_name"})
+    df = reader.scalars
+
+    if df.empty:
+        raise ValueError(f"No TensorFlow events data found in {path}")
+
+    total_imported = 0
+    imported_runs = []
+
+    # Group by dir_name to create separate runs
+    for dir_name, group_df in df.groupby("dir_name"):
+        try:
+            # Determine run name based on directory name
+            if dir_name == "":
+                run_name = "main"  # For files in the root directory
+            else:
+                run_name = dir_name  # Use directory name
+
+            if name:
+                run_name = f"{name}_{run_name}"
+
+            if group_df.empty:
+                print(f"* Skipping directory {dir_name}: no scalar data found")
+                continue
+
+            metrics_list = []
+            steps = []
+            timestamps = []
+
+            for _, row in group_df.iterrows():
+                # Convert row values to appropriate types
+                tag = str(row["tag"])
+                value = float(row["value"])
+                step = int(row["step"])
+
+                metrics = {tag: value}
+                metrics_list.append(metrics)
+                steps.append(step)
+
+                # Use wall_time if present, else fallback
+                if "wall_time" in group_df.columns and not bool(
+                    pd.isna(row["wall_time"])
+                ):
+                    timestamps.append(str(row["wall_time"]))
+                else:
+                    timestamps.append("")
+
+            if metrics_list:
+                SQLiteStorage.bulk_log(
+                    project=project,
+                    run=str(run_name),
+                    metrics_list=metrics_list,
+                    steps=steps,
+                    timestamps=timestamps,
+                )
+
+                total_imported += len(metrics_list)
+                imported_runs.append(run_name)
+
+                print(
+                    f"* Imported {len(metrics_list)} scalar events from directory '{dir_name}' as run '{run_name}'"
+                )
+                print(f"* Metrics in this run: {', '.join(set(group_df['tag']))}")
+
+        except Exception as e:
+            print(f"* Error processing directory {dir_name}: {e}")
+            continue
+
+    if not imported_runs:
+        raise ValueError("No valid TensorFlow events data could be imported")
+
+    print(f"* Total imported events: {total_imported}")
+    print(f"* Created runs: {', '.join(imported_runs)}")
+
+    space_id, dataset_id = utils.preprocess_space_and_dataset_ids(space_id, dataset_id)
+    if dataset_id is not None:
+        os.environ["TRACKIO_DATASET_ID"] = dataset_id
+        print(f"* Trackio metrics will be synced to Hugging Face Dataset: {dataset_id}")
+
+    if space_id is None:
+        utils.print_dashboard_instructions(project)
+    else:
+        deploy.create_space_if_not_exists(space_id, dataset_id)
+        deploy.wait_until_space_exists(space_id)
+        deploy.upload_db_to_space(project, space_id)
+        print(
+            f"* View dashboard by going to: {deploy.SPACE_URL.format(space_id=space_id)}"
+        )

media.py

@@ -0,0 +1,100 @@
+import uuid
+from pathlib import Path
+
+import numpy as np
+from PIL import Image as PILImage
+
+try:  # absolute imports when installed
+    from trackio.file_storage import FileStorage
+    from trackio.utils import TRACKIO_DIR
+except ImportError:  # relative imports for local execution on Spaces
+    from file_storage import FileStorage
+    from utils import TRACKIO_DIR
+
+
+class TrackioImage:
+    """
+    Creates an image that can be logged with trackio.
+
+    Demo: fake-training-images
+    """
+
+    TYPE = "trackio.image"
+
+    def __init__(
+        self, value: str | np.ndarray | PILImage.Image, caption: str | None = None
+    ):
+        """
+        Parameters:
+            value: A string path to an image, a numpy array, or a PIL Image.
+            caption: A string caption for the image.
+        """
+        self.caption = caption
+        self._pil = TrackioImage._as_pil(value)
+        self._file_path: Path | None = None
+        self._file_format: str | None = None
+
+    @staticmethod
+    def _as_pil(value: str | np.ndarray | PILImage.Image) -> PILImage.Image:
+        try:
+            if isinstance(value, str):
+                return PILImage.open(value).convert("RGBA")
+            elif isinstance(value, np.ndarray):
+                arr = np.asarray(value).astype("uint8")
+                return PILImage.fromarray(arr).convert("RGBA")
+            elif isinstance(value, PILImage.Image):
+                return value.convert("RGBA")
+        except Exception as e:
+            raise ValueError(f"Failed to process image data: {value}") from e
+
+    def _save(self, project: str, run: str, step: int = 0, format: str = "PNG") -> str:
+        if not self._file_path:
+            # Save image as {TRACKIO_DIR}/media/{project}/{run}/{step}/{uuid}.{ext}
+            filename = f"{uuid.uuid4()}.{format.lower()}"
+            path = FileStorage.save_image(
+                self._pil, project, run, step, filename, format=format
+            )
+            self._file_path = path.relative_to(TRACKIO_DIR)
+            self._file_format = format
+        return str(self._file_path)
+
+    def _get_relative_file_path(self) -> Path | None:
+        return self._file_path
+
+    def _get_absolute_file_path(self) -> Path | None:
+        return TRACKIO_DIR / self._file_path
+
+    def _to_dict(self) -> dict:
+        if not self._file_path:
+            raise ValueError("Image must be saved to file before serialization")
+        return {
+            "_type": self.TYPE,
+            "file_path": str(self._get_relative_file_path()),
+            "file_format": self._file_format,
+            "caption": self.caption,
+        }
+
+    @classmethod
+    def _from_dict(cls, obj: dict) -> "TrackioImage":
+        if not isinstance(obj, dict):
+            raise TypeError(f"Expected dict, got {type(obj).__name__}")
+        if obj.get("_type") != cls.TYPE:
+            raise ValueError(f"Wrong _type: {obj.get('_type')!r}")
+
+        file_path = obj.get("file_path")
+        if not isinstance(file_path, str):
+            raise TypeError(
+                f"'file_path' must be string, got {type(file_path).__name__}"
+            )
+
+        absolute_path = TRACKIO_DIR / file_path
+        try:
+            if not absolute_path.is_file():
+                raise ValueError(f"Image file not found: {file_path}")
+            pil = PILImage.open(absolute_path).convert("RGBA")
+            instance = cls(pil, caption=obj.get("caption"))
+            instance._file_path = Path(file_path)
+            instance._file_format = obj.get("file_format")
+            return instance
+        except Exception as e:
+            raise ValueError(f"Failed to load image from file: {absolute_path}") from e

run.py

@@ -0,0 +1,140 @@
+import threading
+import time
+
+import huggingface_hub
+from gradio_client import Client, handle_file
+
+from trackio.media import TrackioImage
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.typehints import LogEntry, UploadEntry
+from trackio.utils import RESERVED_KEYS, fibo, generate_readable_name
+
+BATCH_SEND_INTERVAL = 0.5
+
+
+class Run:
+    def __init__(
+        self,
+        url: str,
+        project: str,
+        client: Client | None,
+        name: str | None = None,
+        config: dict | None = None,
+        space_id: str | None = None,
+    ):
+        self.url = url
+        self.project = project
+        self._client_lock = threading.Lock()
+        self._client_thread = None
+        self._client = client
+        self._space_id = space_id
+        self.name = name or generate_readable_name(
+            SQLiteStorage.get_runs(project), space_id
+        )
+        self.config = config or {}
+        self._queued_logs: list[LogEntry] = []
+        self._queued_uploads: list[UploadEntry] = []
+        self._stop_flag = threading.Event()
+
+        self._client_thread = threading.Thread(target=self._init_client_background)
+        self._client_thread.daemon = True
+        self._client_thread.start()
+
+    def _batch_sender(self):
+        """Send batched logs every BATCH_SEND_INTERVAL."""
+        while not self._stop_flag.is_set() or len(self._queued_logs) > 0:
+            # If the stop flag has been set, then just quickly send all
+            # the logs and exit.
+            if not self._stop_flag.is_set():
+                time.sleep(BATCH_SEND_INTERVAL)
+
+            with self._client_lock:
+                if self._queued_logs and self._client is not None:
+                    logs_to_send = self._queued_logs.copy()
+                    self._queued_logs.clear()
+                    self._client.predict(
+                        api_name="/bulk_log",
+                        logs=logs_to_send,
+                        hf_token=huggingface_hub.utils.get_token(),
+                    )
+                if self._queued_uploads and self._client is not None:
+                    uploads_to_send = self._queued_uploads.copy()
+                    self._queued_uploads.clear()
+                    self._client.predict(
+                        api_name="/bulk_upload_media",
+                        uploads=uploads_to_send,
+                        hf_token=huggingface_hub.utils.get_token(),
+                    )
+
+    def _init_client_background(self):
+        if self._client is None:
+            fib = fibo()
+            for sleep_coefficient in fib:
+                try:
+                    client = Client(self.url, verbose=False)
+
+                    with self._client_lock:
+                        self._client = client
+                    break
+                except Exception:
+                    pass
+                if sleep_coefficient is not None:
+                    time.sleep(0.1 * sleep_coefficient)
+
+        self._batch_sender()
+
+    def _process_media(self, metrics, step: int | None) -> dict:
+        """
+        Serialize media in metrics and upload to space if needed.
+        """
+        serializable_metrics = {}
+        if not step:
+            step = 0
+        for key, value in metrics.items():
+            if isinstance(value, TrackioImage):
+                value._save(self.project, self.name, step)
+                serializable_metrics[key] = value._to_dict()
+                if self._space_id:
+                    # Upload local media when deploying to space
+                    upload_entry: UploadEntry = {
+                        "project": self.project,
+                        "run": self.name,
+                        "step": step,
+                        "uploaded_file": handle_file(value._get_absolute_file_path()),
+                    }
+                    with self._client_lock:
+                        self._queued_uploads.append(upload_entry)
+            else:
+                serializable_metrics[key] = value
+        return serializable_metrics
+
+    def log(self, metrics: dict, step: int | None = None):
+        for k in metrics.keys():
+            if k in RESERVED_KEYS or k.startswith("__"):
+                raise ValueError(
+                    f"Please do not use this reserved key as a metric: {k}"
+                )
+
+        metrics = self._process_media(metrics, step)
+        log_entry: LogEntry = {
+            "project": self.project,
+            "run": self.name,
+            "metrics": metrics,
+            "step": step,
+        }
+
+        with self._client_lock:
+            self._queued_logs.append(log_entry)
+
+    def finish(self):
+        """Cleanup when run is finished."""
+        self._stop_flag.set()
+
+        # Wait for the batch sender to finish before joining the client thread.
+        time.sleep(2 * BATCH_SEND_INTERVAL)
+
+        if self._client_thread is not None:
+            print(
+                f"* Run finished. Uploading logs to Trackio Space: {self.url} (please wait...)"
+            )
+            self._client_thread.join()

sqlite_storage.py

@@ -0,0 +1,384 @@
+import json
+import os
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from threading import Lock
+
+import huggingface_hub as hf
+import pandas as pd
+
+try:  # absolute imports when installed
+    from trackio.commit_scheduler import CommitScheduler
+    from trackio.dummy_commit_scheduler import DummyCommitScheduler
+    from trackio.utils import TRACKIO_DIR
+except Exception:  # relative imports for local execution on Spaces
+    from commit_scheduler import CommitScheduler
+    from dummy_commit_scheduler import DummyCommitScheduler
+    from utils import TRACKIO_DIR
+
+
+class SQLiteStorage:
+    _dataset_import_attempted = False
+    _current_scheduler: CommitScheduler | DummyCommitScheduler | None = None
+    _scheduler_lock = Lock()
+
+    @staticmethod
+    def _get_connection(db_path: Path) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(db_path))
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    @staticmethod
+    def get_project_db_filename(project: str) -> Path:
+        """Get the database filename for a specific project."""
+        safe_project_name = "".join(
+            c for c in project if c.isalnum() or c in ("-", "_")
+        ).rstrip()
+        if not safe_project_name:
+            safe_project_name = "default"
+        return f"{safe_project_name}.db"
+
+    @staticmethod
+    def get_project_db_path(project: str) -> Path:
+        """Get the database path for a specific project."""
+        filename = SQLiteStorage.get_project_db_filename(project)
+        return TRACKIO_DIR / filename
+
+    @staticmethod
+    def init_db(project: str) -> Path:
+        """
+        Initialize the SQLite database with required tables.
+        If there is a dataset ID provided, copies from that dataset instead.
+        Returns the database path.
+        """
+        db_path = SQLiteStorage.get_project_db_path(project)
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        with SQLiteStorage.get_scheduler().lock:
+            with sqlite3.connect(db_path) as conn:
+                cursor = conn.cursor()
+                cursor.execute("""
+                    CREATE TABLE IF NOT EXISTS metrics (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        timestamp TEXT NOT NULL,
+                        run_name TEXT NOT NULL,
+                        step INTEGER NOT NULL,
+                        metrics TEXT NOT NULL
+                    )
+                """)
+                cursor.execute(
+                    """
+                    CREATE INDEX IF NOT EXISTS idx_metrics_run_step
+                    ON metrics(run_name, step)
+                    """
+                )
+                conn.commit()
+        return db_path
+
+    @staticmethod
+    def export_to_parquet():
+        """
+        Exports all projects' DB files as Parquet under the same path but with extension ".parquet".
+        """
+        # don't attempt to export (potentially wrong/blank) data before importing for the first time
+        if not SQLiteStorage._dataset_import_attempted:
+            return
+        all_paths = os.listdir(TRACKIO_DIR)
+        db_paths = [f for f in all_paths if f.endswith(".db")]
+        for db_path in db_paths:
+            db_path = TRACKIO_DIR / db_path
+            parquet_path = db_path.with_suffix(".parquet")
+            if (not parquet_path.exists()) or (
+                db_path.stat().st_mtime > parquet_path.stat().st_mtime
+            ):
+                with sqlite3.connect(db_path) as conn:
+                    df = pd.read_sql("SELECT * from metrics", conn)
+                # break out the single JSON metrics column into individual columns
+                metrics = df["metrics"].copy()
+                metrics = pd.DataFrame(
+                    metrics.apply(json.loads).values.tolist(), index=df.index
+                )
+                del df["metrics"]
+                for col in metrics.columns:
+                    df[col] = metrics[col]
+                df.to_parquet(parquet_path)
+
+    @staticmethod
+    def import_from_parquet():
+        """
+        Imports to all DB files that have matching files under the same path but with extension ".parquet".
+        """
+        all_paths = os.listdir(TRACKIO_DIR)
+        parquet_paths = [f for f in all_paths if f.endswith(".parquet")]
+        for parquet_path in parquet_paths:
+            parquet_path = TRACKIO_DIR / parquet_path
+            db_path = parquet_path.with_suffix(".db")
+            df = pd.read_parquet(parquet_path)
+            with sqlite3.connect(db_path) as conn:
+                # fix up df to have a single JSON metrics column
+                if "metrics" not in df.columns:
+                    # separate other columns from metrics
+                    metrics = df.copy()
+                    other_cols = ["id", "timestamp", "run_name", "step"]
+                    df = df[other_cols]
+                    for col in other_cols:
+                        del metrics[col]
+                    # combine them all into a single metrics col
+                    metrics = json.loads(metrics.to_json(orient="records"))
+                    df["metrics"] = [json.dumps(row) for row in metrics]
+                df.to_sql("metrics", conn, if_exists="replace", index=False)
+
+    @staticmethod
+    def get_scheduler():
+        """
+        Get the scheduler for the database based on the environment variables.
+        This applies to both local and Spaces.
+        """
+        with SQLiteStorage._scheduler_lock:
+            if SQLiteStorage._current_scheduler is not None:
+                return SQLiteStorage._current_scheduler
+            hf_token = os.environ.get("HF_TOKEN")
+            dataset_id = os.environ.get("TRACKIO_DATASET_ID")
+            space_repo_name = os.environ.get("SPACE_REPO_NAME")
+            if dataset_id is None or space_repo_name is None:
+                scheduler = DummyCommitScheduler()
+            else:
+                scheduler = CommitScheduler(
+                    repo_id=dataset_id,
+                    repo_type="dataset",
+                    folder_path=TRACKIO_DIR,
+                    private=True,
+                    allow_patterns=["*.parquet", "media/**/*"],
+                    squash_history=True,
+                    token=hf_token,
+                    on_before_commit=SQLiteStorage.export_to_parquet,
+                )
+            SQLiteStorage._current_scheduler = scheduler
+            return scheduler
+
+    @staticmethod
+    def log(project: str, run: str, metrics: dict, step: int | None = None):
+        """
+        Safely log metrics to the database. Before logging, this method will ensure the database exists
+        and is set up with the correct tables. It also uses the scheduler to lock the database so
+        that there is no race condition when logging / syncing to the Hugging Face Dataset.
+        """
+        db_path = SQLiteStorage.init_db(project)
+
+        with SQLiteStorage.get_scheduler().lock:
+            with SQLiteStorage._get_connection(db_path) as conn:
+                cursor = conn.cursor()
+
+                cursor.execute(
+                    """
+                    SELECT MAX(step) 
+                    FROM metrics 
+                    WHERE run_name = ?
+                    """,
+                    (run,),
+                )
+                last_step = cursor.fetchone()[0]
+                if step is None:
+                    current_step = 0 if last_step is None else last_step + 1
+                else:
+                    current_step = step
+
+                current_timestamp = datetime.now().isoformat()
+
+                cursor.execute(
+                    """
+                    INSERT INTO metrics
+                    (timestamp, run_name, step, metrics)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (
+                        current_timestamp,
+                        run,
+                        current_step,
+                        json.dumps(metrics),
+                    ),
+                )
+                conn.commit()
+
+    @staticmethod
+    def bulk_log(
+        project: str,
+        run: str,
+        metrics_list: list[dict],
+        steps: list[int] | None = None,
+        timestamps: list[str] | None = None,
+    ):
+        """Bulk log metrics to the database with specified steps and timestamps."""
+        if not metrics_list:
+            return
+
+        if timestamps is None:
+            timestamps = [datetime.now().isoformat()] * len(metrics_list)
+
+        db_path = SQLiteStorage.init_db(project)
+        with SQLiteStorage.get_scheduler().lock:
+            with SQLiteStorage._get_connection(db_path) as conn:
+                cursor = conn.cursor()
+
+                if steps is None:
+                    steps = list(range(len(metrics_list)))
+                elif any(s is None for s in steps):
+                    cursor.execute(
+                        "SELECT MAX(step) FROM metrics WHERE run_name = ?", (run,)
+                    )
+                    last_step = cursor.fetchone()[0]
+                    current_step = 0 if last_step is None else last_step + 1
+
+                    processed_steps = []
+                    for step in steps:
+                        if step is None:
+                            processed_steps.append(current_step)
+                            current_step += 1
+                        else:
+                            processed_steps.append(step)
+                    steps = processed_steps
+
+                if len(metrics_list) != len(steps) or len(metrics_list) != len(
+                    timestamps
+                ):
+                    raise ValueError(
+                        "metrics_list, steps, and timestamps must have the same length"
+                    )
+
+                data = []
+                for i, metrics in enumerate(metrics_list):
+                    data.append(
+                        (
+                            timestamps[i],
+                            run,
+                            steps[i],
+                            json.dumps(metrics),
+                        )
+                    )
+
+                cursor.executemany(
+                    """
+                    INSERT INTO metrics
+                    (timestamp, run_name, step, metrics)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    data,
+                )
+                conn.commit()
+
+    @staticmethod
+    def get_logs(project: str, run: str) -> list[dict]:
+        """Retrieve logs for a specific run. Logs include the step count (int) and the timestamp (datetime object)."""
+        db_path = SQLiteStorage.get_project_db_path(project)
+        if not db_path.exists():
+            return []
+
+        with SQLiteStorage._get_connection(db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                """
+                SELECT timestamp, step, metrics
+                FROM metrics
+                WHERE run_name = ?
+                ORDER BY timestamp
+                """,
+                (run,),
+            )
+
+            rows = cursor.fetchall()
+            results = []
+            for row in rows:
+                metrics = json.loads(row["metrics"])
+                metrics["timestamp"] = row["timestamp"]
+                metrics["step"] = row["step"]
+                results.append(metrics)
+            return results
+
+    @staticmethod
+    def load_from_dataset():
+        dataset_id = os.environ.get("TRACKIO_DATASET_ID")
+        space_repo_name = os.environ.get("SPACE_REPO_NAME")
+        if dataset_id is not None and space_repo_name is not None:
+            hfapi = hf.HfApi()
+            updated = False
+            if not TRACKIO_DIR.exists():
+                TRACKIO_DIR.mkdir(parents=True, exist_ok=True)
+            with SQLiteStorage.get_scheduler().lock:
+                try:
+                    files = hfapi.list_repo_files(dataset_id, repo_type="dataset")
+                    for file in files:
+                        # Download parquet and media assets
+                        if not (file.endswith(".parquet") or file.startswith("media/")):
+                            continue
+                        hf.hf_hub_download(
+                            dataset_id, file, repo_type="dataset", local_dir=TRACKIO_DIR
+                        )
+                        updated = True
+                except hf.errors.EntryNotFoundError:
+                    pass
+                except hf.errors.RepositoryNotFoundError:
+                    pass
+                if updated:
+                    SQLiteStorage.import_from_parquet()
+        SQLiteStorage._dataset_import_attempted = True
+
+    @staticmethod
+    def get_projects() -> list[str]:
+        """
+        Get list of all projects by scanning the database files in the trackio directory.
+        """
+        if not SQLiteStorage._dataset_import_attempted:
+            SQLiteStorage.load_from_dataset()
+
+        projects: set[str] = set()
+        if not TRACKIO_DIR.exists():
+            return []
+
+        for db_file in TRACKIO_DIR.glob("*.db"):
+            project_name = db_file.stem
+            projects.add(project_name)
+        return sorted(projects)
+
+    @staticmethod
+    def get_runs(project: str) -> list[str]:
+        """Get list of all runs for a project."""
+        db_path = SQLiteStorage.get_project_db_path(project)
+        if not db_path.exists():
+            return []
+
+        with SQLiteStorage._get_connection(db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT DISTINCT run_name FROM metrics",
+            )
+            return [row[0] for row in cursor.fetchall()]
+
+    @staticmethod
+    def get_max_steps_for_runs(project: str, runs: list[str]) -> dict[str, int]:
+        """Efficiently get the maximum step for multiple runs in a single query."""
+        db_path = SQLiteStorage.get_project_db_path(project)
+        if not db_path.exists():
+            return {run: 0 for run in runs}
+
+        with SQLiteStorage._get_connection(db_path) as conn:
+            cursor = conn.cursor()
+            placeholders = ",".join("?" * len(runs))
+            cursor.execute(
+                f"""
+                SELECT run_name, MAX(step) as max_step
+                FROM metrics
+                WHERE run_name IN ({placeholders})
+                GROUP BY run_name
+                """,
+                runs,
+            )
+
+            results = {run: 0 for run in runs}  # Default to 0 for runs with no data
+            for row in cursor.fetchall():
+                results[row["run_name"]] = row["max_step"]
+
+            return results
+
+    def finish(self):
+        """Cleanup when run is finished."""
+        pass

typehints.py

@@ -0,0 +1,17 @@
+from typing import Any, TypedDict
+
+from gradio import FileData
+
+
+class LogEntry(TypedDict):
+    project: str
+    run: str
+    metrics: dict[str, Any]
+    step: int | None
+
+
+class UploadEntry(TypedDict):
+    project: str
+    run: str
+    step: int | None
+    uploaded_file: FileData

ui.py

@@ -0,0 +1,711 @@
+import os
+import re
+import shutil
+from typing import Any
+
+import gradio as gr
+import huggingface_hub as hf
+import numpy as np
+import pandas as pd
+
+HfApi = hf.HfApi()
+
+try:
+    import trackio.utils as utils
+    from trackio.file_storage import FileStorage
+    from trackio.media import TrackioImage
+    from trackio.sqlite_storage import SQLiteStorage
+    from trackio.typehints import LogEntry, UploadEntry
+except:  # noqa: E722
+    import utils
+    from file_storage import FileStorage
+    from media import TrackioImage
+    from sqlite_storage import SQLiteStorage
+    from typehints import LogEntry, UploadEntry
+
+
+def get_project_info() -> str | None:
+    dataset_id = os.environ.get("TRACKIO_DATASET_ID")
+    space_id = os.environ.get("SPACE_ID")
+    persistent_storage_enabled = os.environ.get(
+        "PERSISTANT_STORAGE_ENABLED"
+    )  # Space env name has a typo
+    if persistent_storage_enabled:
+        return "✨ Persistent Storage is enabled, logs are stored directly in this Space."
+    if dataset_id:
+        sync_status = utils.get_sync_status(SQLiteStorage.get_scheduler())
+        upgrade_message = f"New changes are synced every 5 min <span class='info-container'><input type='checkbox' class='info-checkbox' id='upgrade-info'><label for='upgrade-info' class='info-icon'>&#9432;</label><span class='info-expandable'> To avoid losing data between syncs, <a href='https://huggingface.co/spaces/{space_id}/settings' class='accent-link'>click here</a> to open this Space's settings and add Persistent Storage.</span></span>"
+        if sync_status is not None:
+            info = f"&#x21bb; Backed up {sync_status} min ago to <a href='https://huggingface.co/datasets/{dataset_id}' target='_blank' class='accent-link'>{dataset_id}</a> | {upgrade_message}"
+        else:
+            info = f"&#x21bb; Not backed up yet to <a href='https://huggingface.co/datasets/{dataset_id}' target='_blank' class='accent-link'>{dataset_id}</a> | {upgrade_message}"
+        return info
+    return None
+
+
+def get_projects(request: gr.Request):
+    projects = SQLiteStorage.get_projects()
+    if project := request.query_params.get("project"):
+        interactive = False
+    else:
+        interactive = True
+        project = projects[0] if projects else None
+
+    return gr.Dropdown(
+        label="Project",
+        choices=projects,
+        value=project,
+        allow_custom_value=True,
+        interactive=interactive,
+        info=get_project_info(),
+    )
+
+
+def get_runs(project) -> list[str]:
+    if not project:
+        return []
+    return SQLiteStorage.get_runs(project)
+
+
+def get_available_metrics(project: str, runs: list[str]) -> list[str]:
+    """Get all available metrics across all runs for x-axis selection."""
+    if not project or not runs:
+        return ["step", "time"]
+
+    all_metrics = set()
+    for run in runs:
+        metrics = SQLiteStorage.get_logs(project, run)
+        if metrics:
+            df = pd.DataFrame(metrics)
+            numeric_cols = df.select_dtypes(include="number").columns
+            numeric_cols = [c for c in numeric_cols if c not in utils.RESERVED_KEYS]
+            all_metrics.update(numeric_cols)
+
+    all_metrics.add("step")
+    all_metrics.add("time")
+
+    sorted_metrics = utils.sort_metrics_by_prefix(list(all_metrics))
+
+    result = ["step", "time"]
+    for metric in sorted_metrics:
+        if metric not in result:
+            result.append(metric)
+
+    return result
+
+
+def extract_images(logs: list[dict]) -> dict[str, list[TrackioImage]]:
+    image_data = {}
+    logs = sorted(logs, key=lambda x: x.get("step", 0))
+    for log in logs:
+        for key, value in log.items():
+            if isinstance(value, dict) and value.get("_type") == TrackioImage.TYPE:
+                if key not in image_data:
+                    image_data[key] = []
+                try:
+                    image_data[key].append(TrackioImage._from_dict(value))
+                except Exception as e:
+                    print(f"Image not currently available: {key}: {e}")
+    return image_data
+
+
+def load_run_data(
+    project: str | None,
+    run: str | None,
+    smoothing: bool,
+    x_axis: str,
+    log_scale: bool = False,
+) -> tuple[pd.DataFrame, dict]:
+    if not project or not run:
+        return None, None
+
+    logs = SQLiteStorage.get_logs(project, run)
+    if not logs:
+        return None, None
+
+    images = extract_images(logs)
+    df = pd.DataFrame(logs)
+
+    if "step" not in df.columns:
+        df["step"] = range(len(df))
+
+    if x_axis == "time" and "timestamp" in df.columns:
+        df["timestamp"] = pd.to_datetime(df["timestamp"])
+        first_timestamp = df["timestamp"].min()
+        df["time"] = (df["timestamp"] - first_timestamp).dt.total_seconds()
+        x_column = "time"
+    elif x_axis == "step":
+        x_column = "step"
+    else:
+        x_column = x_axis
+
+    if log_scale and x_column in df.columns:
+        x_vals = df[x_column]
+        if (x_vals <= 0).any():
+            df[x_column] = np.log10(np.maximum(x_vals, 0) + 1)
+        else:
+            df[x_column] = np.log10(x_vals)
+
+    if smoothing:
+        numeric_cols = df.select_dtypes(include="number").columns
+        numeric_cols = [c for c in numeric_cols if c not in utils.RESERVED_KEYS]
+
+        df_original = df.copy()
+        df_original["run"] = f"{run}_original"
+        df_original["data_type"] = "original"
+
+        df_smoothed = df.copy()
+        window_size = max(3, min(10, len(df) // 10))  # Adaptive window size
+        df_smoothed[numeric_cols] = (
+            df_smoothed[numeric_cols]
+            .rolling(window=window_size, center=True, min_periods=1)
+            .mean()
+        )
+        df_smoothed["run"] = f"{run}_smoothed"
+        df_smoothed["data_type"] = "smoothed"
+
+        combined_df = pd.concat([df_original, df_smoothed], ignore_index=True)
+        combined_df["x_axis"] = x_column
+        return combined_df, images
+    else:
+        df["run"] = run
+        df["data_type"] = "original"
+        df["x_axis"] = x_column
+        return df, images
+
+
+def update_runs(project, filter_text, user_interacted_with_runs=False):
+    if project is None:
+        runs = []
+        num_runs = 0
+    else:
+        runs = get_runs(project)
+        num_runs = len(runs)
+        if filter_text:
+            runs = [r for r in runs if filter_text in r]
+    if not user_interacted_with_runs:
+        return gr.CheckboxGroup(choices=runs, value=runs), gr.Textbox(
+            label=f"Runs ({num_runs})"
+        )
+    else:
+        return gr.CheckboxGroup(choices=runs), gr.Textbox(label=f"Runs ({num_runs})")
+
+
+def filter_runs(project, filter_text):
+    runs = get_runs(project)
+    runs = [r for r in runs if filter_text in r]
+    return gr.CheckboxGroup(choices=runs, value=runs)
+
+
+def update_x_axis_choices(project, runs):
+    """Update x-axis dropdown choices based on available metrics."""
+    available_metrics = get_available_metrics(project, runs)
+    return gr.Dropdown(
+        label="X-axis",
+        choices=available_metrics,
+        value="step",
+    )
+
+
+def toggle_timer(cb_value):
+    if cb_value:
+        return gr.Timer(active=True)
+    else:
+        return gr.Timer(active=False)
+
+
+def check_auth(hf_token: str | None) -> None:
+    if os.getenv("SYSTEM") == "spaces":  # if we are running in Spaces
+        # check auth token passed in
+        if hf_token is None:
+            raise PermissionError(
+                "Expected a HF_TOKEN to be provided when logging to a Space"
+            )
+        who = HfApi.whoami(hf_token)
+        access_token = who["auth"]["accessToken"]
+        owner_name = os.getenv("SPACE_AUTHOR_NAME")
+        repo_name = os.getenv("SPACE_REPO_NAME")
+        # make sure the token user is either the author of the space,
+        # or is a member of an org that is the author.
+        orgs = [o["name"] for o in who["orgs"]]
+        if owner_name != who["name"] and owner_name not in orgs:
+            raise PermissionError(
+                "Expected the provided hf_token to be the user owner of the space, or be a member of the org owner of the space"
+            )
+        # reject fine-grained tokens without specific repo access
+        if access_token["role"] == "fineGrained":
+            matched = False
+            for item in access_token["fineGrained"]["scoped"]:
+                if (
+                    item["entity"]["type"] == "space"
+                    and item["entity"]["name"] == f"{owner_name}/{repo_name}"
+                    and "repo.write" in item["permissions"]
+                ):
+                    matched = True
+                    break
+                if (
+                    (
+                        item["entity"]["type"] == "user"
+                        or item["entity"]["type"] == "org"
+                    )
+                    and item["entity"]["name"] == owner_name
+                    and "repo.write" in item["permissions"]
+                ):
+                    matched = True
+                    break
+            if not matched:
+                raise PermissionError(
+                    "Expected the provided hf_token with fine grained permissions to provide write access to the space"
+                )
+        # reject read-only tokens
+        elif access_token["role"] != "write":
+            raise PermissionError(
+                "Expected the provided hf_token to provide write permissions"
+            )
+
+
+def upload_db_to_space(
+    project: str, uploaded_db: gr.FileData, hf_token: str | None
+) -> None:
+    check_auth(hf_token)
+    db_project_path = SQLiteStorage.get_project_db_path(project)
+    if os.path.exists(db_project_path):
+        raise gr.Error(
+            f"Trackio database file already exists for project {project}, cannot overwrite."
+        )
+    os.makedirs(os.path.dirname(db_project_path), exist_ok=True)
+    shutil.copy(uploaded_db["path"], db_project_path)
+
+
+def bulk_upload_media(uploads: list[UploadEntry], hf_token: str | None) -> None:
+    check_auth(hf_token)
+    for upload in uploads:
+        media_path = FileStorage.init_project_media_path(
+            upload["project"], upload["run"], upload["step"]
+        )
+        shutil.copy(upload["uploaded_file"]["path"], media_path)
+
+
+def log(
+    project: str,
+    run: str,
+    metrics: dict[str, Any],
+    step: int | None,
+    hf_token: str | None,
+) -> None:
+    check_auth(hf_token)
+    SQLiteStorage.log(project=project, run=run, metrics=metrics, step=step)
+
+
+def bulk_log(
+    logs: list[LogEntry],
+    hf_token: str | None,
+) -> None:
+    check_auth(hf_token)
+
+    logs_by_run = {}
+    for log_entry in logs:
+        key = (log_entry["project"], log_entry["run"])
+        if key not in logs_by_run:
+            logs_by_run[key] = {"metrics": [], "steps": []}
+        logs_by_run[key]["metrics"].append(log_entry["metrics"])
+        logs_by_run[key]["steps"].append(log_entry.get("step"))
+
+    for (project, run), data in logs_by_run.items():
+        SQLiteStorage.bulk_log(
+            project=project,
+            run=run,
+            metrics_list=data["metrics"],
+            steps=data["steps"],
+        )
+
+
+def filter_metrics_by_regex(metrics: list[str], filter_pattern: str) -> list[str]:
+    """
+    Filter metrics using regex pattern.
+
+    Args:
+        metrics: List of metric names to filter
+        filter_pattern: Regex pattern to match against metric names
+
+    Returns:
+        List of metric names that match the pattern
+    """
+    if not filter_pattern.strip():
+        return metrics
+
+    try:
+        pattern = re.compile(filter_pattern, re.IGNORECASE)
+        return [metric for metric in metrics if pattern.search(metric)]
+    except re.error:
+        return [
+            metric for metric in metrics if filter_pattern.lower() in metric.lower()
+        ]
+
+
+def configure(request: gr.Request):
+    sidebar_param = request.query_params.get("sidebar")
+    match sidebar_param:
+        case "collapsed":
+            sidebar = gr.Sidebar(open=False, visible=True)
+        case "hidden":
+            sidebar = gr.Sidebar(open=False, visible=False)
+        case _:
+            sidebar = gr.Sidebar(open=True, visible=True)
+
+    if metrics := request.query_params.get("metrics"):
+        return metrics.split(","), sidebar
+    else:
+        return [], sidebar
+
+
+def create_image_section(images_by_run: dict[str, dict[str, list[TrackioImage]]]):
+    with gr.Accordion(label="media"):
+        with gr.Group(elem_classes=("media-group")):
+            for run, images_by_key in images_by_run.items():
+                with gr.Tab(label=run, elem_classes=("media-tab")):
+                    for key, images in images_by_key.items():
+                        gr.Gallery(
+                            [(image._pil, image.caption) for image in images],
+                            label=key,
+                            columns=6,
+                            elem_classes=("media-gallery"),
+                        )
+
+
+css = """
+#run-cb .wrap { gap: 2px; }
+#run-cb .wrap label {
+    line-height: 1;
+    padding: 6px;
+}
+.logo-light { display: block; } 
+.logo-dark { display: none; }
+.dark .logo-light { display: none; }
+.dark .logo-dark { display: block; }
+.dark .caption-label { color: white; }
+
+.info-container {
+    position: relative;
+    display: inline;
+}
+.info-checkbox {
+    position: absolute;
+    opacity: 0;
+    pointer-events: none;
+}
+.info-icon {
+    border-bottom: 1px dotted;
+    cursor: pointer;
+    user-select: none;
+    color: var(--color-accent);
+}
+.info-expandable {
+    display: none;
+    opacity: 0;
+    transition: opacity 0.2s ease-in-out;
+}
+.info-checkbox:checked ~ .info-expandable {
+    display: inline;
+    opacity: 1;
+}
+.info-icon:hover { opacity: 0.8; }
+.accent-link { font-weight: bold; }
+
+.media-gallery { max-height: 325px; }
+.media-group, .media-group > div { background: none; }
+.media-group .tabs { padding: 0.5em; }
+"""
+
+with gr.Blocks(theme="citrus", title="Trackio Dashboard", css=css) as demo:
+    with gr.Sidebar(open=False) as sidebar:
+        logo = gr.Markdown(
+            f"""
+                <img src='/gradio_api/file={utils.TRACKIO_LOGO_DIR}/trackio_logo_type_light_transparent.png' width='80%' class='logo-light'>
+                <img src='/gradio_api/file={utils.TRACKIO_LOGO_DIR}/trackio_logo_type_dark_transparent.png' width='80%' class='logo-dark'>            
+            """
+        )
+        project_dd = gr.Dropdown(label="Project", allow_custom_value=True)
+        run_tb = gr.Textbox(label="Runs", placeholder="Type to filter...")
+        run_cb = gr.CheckboxGroup(
+            label="Runs", choices=[], interactive=True, elem_id="run-cb"
+        )
+        gr.HTML("<hr>")
+        realtime_cb = gr.Checkbox(label="Refresh metrics realtime", value=True)
+        smoothing_cb = gr.Checkbox(label="Smooth metrics", value=True)
+        x_axis_dd = gr.Dropdown(
+            label="X-axis",
+            choices=["step", "time"],
+            value="step",
+        )
+        log_scale_cb = gr.Checkbox(label="Log scale X-axis", value=False)
+        metric_filter_tb = gr.Textbox(
+            label="Metric Filter (regex)",
+            placeholder="e.g., loss|ndcg@10|gpu",
+            value="",
+            info="Filter metrics using regex patterns. Leave empty to show all metrics.",
+        )
+
+    timer = gr.Timer(value=1)
+    metrics_subset = gr.State([])
+    user_interacted_with_run_cb = gr.State(False)
+
+    gr.on([demo.load], fn=configure, outputs=[metrics_subset, sidebar])
+    gr.on(
+        [demo.load],
+        fn=get_projects,
+        outputs=project_dd,
+        show_progress="hidden",
+    )
+    gr.on(
+        [timer.tick],
+        fn=update_runs,
+        inputs=[project_dd, run_tb, user_interacted_with_run_cb],
+        outputs=[run_cb, run_tb],
+        show_progress="hidden",
+    )
+    gr.on(
+        [timer.tick],
+        fn=lambda: gr.Dropdown(info=get_project_info()),
+        outputs=[project_dd],
+        show_progress="hidden",
+    )
+    gr.on(
+        [demo.load, project_dd.change],
+        fn=update_runs,
+        inputs=[project_dd, run_tb],
+        outputs=[run_cb, run_tb],
+        show_progress="hidden",
+    )
+    gr.on(
+        [demo.load, project_dd.change, run_cb.change],
+        fn=update_x_axis_choices,
+        inputs=[project_dd, run_cb],
+        outputs=x_axis_dd,
+        show_progress="hidden",
+    )
+
+    realtime_cb.change(
+        fn=toggle_timer,
+        inputs=realtime_cb,
+        outputs=timer,
+        api_name="toggle_timer",
+    )
+    run_cb.input(
+        fn=lambda: True,
+        outputs=user_interacted_with_run_cb,
+    )
+    run_tb.input(
+        fn=filter_runs,
+        inputs=[project_dd, run_tb],
+        outputs=run_cb,
+    )
+
+    gr.api(
+        fn=upload_db_to_space,
+        api_name="upload_db_to_space",
+    )
+    gr.api(
+        fn=bulk_upload_media,
+        api_name="bulk_upload_media",
+    )
+    gr.api(
+        fn=log,
+        api_name="log",
+    )
+    gr.api(
+        fn=bulk_log,
+        api_name="bulk_log",
+    )
+
+    x_lim = gr.State(None)
+    last_steps = gr.State({})
+
+    def update_x_lim(select_data: gr.SelectData):
+        return select_data.index
+
+    def update_last_steps(project, runs):
+        """Update the last step from all runs to detect when new data is available."""
+        if not project or not runs:
+            return {}
+
+        return SQLiteStorage.get_max_steps_for_runs(project, runs)
+
+    timer.tick(
+        fn=update_last_steps,
+        inputs=[project_dd, run_cb],
+        outputs=last_steps,
+        show_progress="hidden",
+    )
+
+    @gr.render(
+        triggers=[
+            demo.load,
+            run_cb.change,
+            last_steps.change,
+            smoothing_cb.change,
+            x_lim.change,
+            x_axis_dd.change,
+            log_scale_cb.change,
+            metric_filter_tb.change,
+        ],
+        inputs=[
+            project_dd,
+            run_cb,
+            smoothing_cb,
+            metrics_subset,
+            x_lim,
+            x_axis_dd,
+            log_scale_cb,
+            metric_filter_tb,
+        ],
+        show_progress="hidden",
+    )
+    def update_dashboard(
+        project,
+        runs,
+        smoothing,
+        metrics_subset,
+        x_lim_value,
+        x_axis,
+        log_scale,
+        metric_filter,
+    ):
+        dfs = []
+        images_by_run = {}
+        original_runs = runs.copy()
+
+        for run in runs:
+            df, images_by_key = load_run_data(
+                project, run, smoothing, x_axis, log_scale
+            )
+            if df is not None:
+                dfs.append(df)
+                images_by_run[run] = images_by_key
+        if dfs:
+            master_df = pd.concat(dfs, ignore_index=True)
+        else:
+            master_df = pd.DataFrame()
+
+        if master_df.empty:
+            return
+
+        x_column = "step"
+        if dfs and not dfs[0].empty and "x_axis" in dfs[0].columns:
+            x_column = dfs[0]["x_axis"].iloc[0]
+
+        numeric_cols = master_df.select_dtypes(include="number").columns
+        numeric_cols = [c for c in numeric_cols if c not in utils.RESERVED_KEYS]
+        if metrics_subset:
+            numeric_cols = [c for c in numeric_cols if c in metrics_subset]
+
+        if metric_filter and metric_filter.strip():
+            numeric_cols = filter_metrics_by_regex(list(numeric_cols), metric_filter)
+
+        nested_metric_groups = utils.group_metrics_with_subprefixes(list(numeric_cols))
+        color_map = utils.get_color_mapping(original_runs, smoothing)
+
+        metric_idx = 0
+        for group_name in sorted(nested_metric_groups.keys()):
+            group_data = nested_metric_groups[group_name]
+
+            with gr.Accordion(
+                label=group_name,
+                open=True,
+                key=f"accordion-{group_name}",
+                preserved_by_key=["value", "open"],
+            ):
+                # Render direct metrics at this level
+                if group_data["direct_metrics"]:
+                    with gr.Row(key=f"row-{group_name}-direct"):
+                        for metric_name in group_data["direct_metrics"]:
+                            metric_df = master_df.dropna(subset=[metric_name])
+                            color = "run" if "run" in metric_df.columns else None
+                            if not metric_df.empty:
+                                plot = gr.LinePlot(
+                                    utils.downsample(
+                                        metric_df,
+                                        x_column,
+                                        metric_name,
+                                        color,
+                                        x_lim_value,
+                                    ),
+                                    x=x_column,
+                                    y=metric_name,
+                                    y_title=metric_name.split("/")[-1],
+                                    color=color,
+                                    color_map=color_map,
+                                    title=metric_name,
+                                    key=f"plot-{metric_idx}",
+                                    preserved_by_key=None,
+                                    x_lim=x_lim_value,
+                                    show_fullscreen_button=True,
+                                    min_width=400,
+                                )
+                                plot.select(
+                                    update_x_lim,
+                                    outputs=x_lim,
+                                    key=f"select-{metric_idx}",
+                                )
+                                plot.double_click(
+                                    lambda: None,
+                                    outputs=x_lim,
+                                    key=f"double-{metric_idx}",
+                                )
+                            metric_idx += 1
+
+                # If there are subgroups, create nested accordions
+                if group_data["subgroups"]:
+                    for subgroup_name in sorted(group_data["subgroups"].keys()):
+                        subgroup_metrics = group_data["subgroups"][subgroup_name]
+
+                        with gr.Accordion(
+                            label=subgroup_name,
+                            open=True,
+                            key=f"accordion-{group_name}-{subgroup_name}",
+                            preserved_by_key=["value", "open"],
+                        ):
+                            with gr.Row(key=f"row-{group_name}-{subgroup_name}"):
+                                for metric_name in subgroup_metrics:
+                                    metric_df = master_df.dropna(subset=[metric_name])
+                                    color = (
+                                        "run" if "run" in metric_df.columns else None
+                                    )
+                                    if not metric_df.empty:
+                                        plot = gr.LinePlot(
+                                            utils.downsample(
+                                                metric_df,
+                                                x_column,
+                                                metric_name,
+                                                color,
+                                                x_lim_value,
+                                            ),
+                                            x=x_column,
+                                            y=metric_name,
+                                            y_title=metric_name.split("/")[-1],
+                                            color=color,
+                                            color_map=color_map,
+                                            title=metric_name,
+                                            key=f"plot-{metric_idx}",
+                                            preserved_by_key=None,
+                                            x_lim=x_lim_value,
+                                            show_fullscreen_button=True,
+                                            min_width=400,
+                                        )
+                                        plot.select(
+                                            update_x_lim,
+                                            outputs=x_lim,
+                                            key=f"select-{metric_idx}",
+                                        )
+                                        plot.double_click(
+                                            lambda: None,
+                                            outputs=x_lim,
+                                            key=f"double-{metric_idx}",
+                                        )
+                                    metric_idx += 1
+        if images_by_run and any(any(images) for images in images_by_run.values()):
+            create_image_section(images_by_run)
+
+
+if __name__ == "__main__":
+    demo.launch(allowed_paths=[utils.TRACKIO_LOGO_DIR], show_api=False, show_error=True)

utils.py

@@ -0,0 +1,568 @@
+import re
+import sys
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import huggingface_hub
+import numpy as np
+import pandas as pd
+from huggingface_hub.constants import HF_HOME
+
+if TYPE_CHECKING:
+    from trackio.commit_scheduler import CommitScheduler
+    from trackio.dummy_commit_scheduler import DummyCommitScheduler
+
+RESERVED_KEYS = ["project", "run", "timestamp", "step", "time", "metrics"]
+TRACKIO_DIR = Path(HF_HOME) / "trackio"
+
+TRACKIO_LOGO_DIR = Path(__file__).parent / "assets"
+
+
+def generate_readable_name(used_names: list[str], space_id: str | None = None) -> str:
+    """
+    Generates a random, readable name like "dainty-sunset-0".
+    If space_id is provided, generates username-timestamp format instead.
+    """
+    if space_id is not None:
+        username = huggingface_hub.whoami()["name"]
+        timestamp = int(time.time())
+        return f"{username}-{timestamp}"
+    adjectives = [
+        "dainty",
+        "brave",
+        "calm",
+        "eager",
+        "fancy",
+        "gentle",
+        "happy",
+        "jolly",
+        "kind",
+        "lively",
+        "merry",
+        "nice",
+        "proud",
+        "quick",
+        "hugging",
+        "silly",
+        "tidy",
+        "witty",
+        "zealous",
+        "bright",
+        "shy",
+        "bold",
+        "clever",
+        "daring",
+        "elegant",
+        "faithful",
+        "graceful",
+        "honest",
+        "inventive",
+        "jovial",
+        "keen",
+        "lucky",
+        "modest",
+        "noble",
+        "optimistic",
+        "patient",
+        "quirky",
+        "resourceful",
+        "sincere",
+        "thoughtful",
+        "upbeat",
+        "valiant",
+        "warm",
+        "youthful",
+        "zesty",
+        "adventurous",
+        "breezy",
+        "cheerful",
+        "delightful",
+        "energetic",
+        "fearless",
+        "glad",
+        "hopeful",
+        "imaginative",
+        "joyful",
+        "kindly",
+        "luminous",
+        "mysterious",
+        "neat",
+        "outgoing",
+        "playful",
+        "radiant",
+        "spirited",
+        "tranquil",
+        "unique",
+        "vivid",
+        "wise",
+        "zany",
+        "artful",
+        "bubbly",
+        "charming",
+        "dazzling",
+        "earnest",
+        "festive",
+        "gentlemanly",
+        "hearty",
+        "intrepid",
+        "jubilant",
+        "knightly",
+        "lively",
+        "magnetic",
+        "nimble",
+        "orderly",
+        "peaceful",
+        "quick-witted",
+        "robust",
+        "sturdy",
+        "trusty",
+        "upstanding",
+        "vibrant",
+        "whimsical",
+    ]
+    nouns = [
+        "sunset",
+        "forest",
+        "river",
+        "mountain",
+        "breeze",
+        "meadow",
+        "ocean",
+        "valley",
+        "sky",
+        "field",
+        "cloud",
+        "star",
+        "rain",
+        "leaf",
+        "stone",
+        "flower",
+        "bird",
+        "tree",
+        "wave",
+        "trail",
+        "island",
+        "desert",
+        "hill",
+        "lake",
+        "pond",
+        "grove",
+        "canyon",
+        "reef",
+        "bay",
+        "peak",
+        "glade",
+        "marsh",
+        "cliff",
+        "dune",
+        "spring",
+        "brook",
+        "cave",
+        "plain",
+        "ridge",
+        "wood",
+        "blossom",
+        "petal",
+        "root",
+        "branch",
+        "seed",
+        "acorn",
+        "pine",
+        "willow",
+        "cedar",
+        "elm",
+        "falcon",
+        "eagle",
+        "sparrow",
+        "robin",
+        "owl",
+        "finch",
+        "heron",
+        "crane",
+        "duck",
+        "swan",
+        "fox",
+        "wolf",
+        "bear",
+        "deer",
+        "moose",
+        "otter",
+        "beaver",
+        "lynx",
+        "hare",
+        "badger",
+        "butterfly",
+        "bee",
+        "ant",
+        "beetle",
+        "dragonfly",
+        "firefly",
+        "ladybug",
+        "moth",
+        "spider",
+        "worm",
+        "coral",
+        "kelp",
+        "shell",
+        "pebble",
+        "face",
+        "boulder",
+        "cobble",
+        "sand",
+        "wavelet",
+        "tide",
+        "current",
+        "mist",
+    ]
+    number = 0
+    name = f"{adjectives[0]}-{nouns[0]}-{number}"
+    while name in used_names:
+        number += 1
+        adjective = adjectives[number % len(adjectives)]
+        noun = nouns[number % len(nouns)]
+        name = f"{adjective}-{noun}-{number}"
+    return name
+
+
+def block_except_in_notebook():
+    in_notebook = bool(getattr(sys, "ps1", sys.flags.interactive))
+    if in_notebook:
+        return
+    try:
+        while True:
+            time.sleep(0.1)
+    except (KeyboardInterrupt, OSError):
+        print("Keyboard interruption in main thread... closing dashboard.")
+
+
+def simplify_column_names(columns: list[str]) -> dict[str, str]:
+    """
+    Simplifies column names to first 10 alphanumeric or "/" characters with unique suffixes.
+
+    Args:
+        columns: List of original column names
+
+    Returns:
+        Dictionary mapping original column names to simplified names
+    """
+    simplified_names = {}
+    used_names = set()
+
+    for col in columns:
+        alphanumeric = re.sub(r"[^a-zA-Z0-9/]", "", col)
+        base_name = alphanumeric[:10] if alphanumeric else f"col_{len(used_names)}"
+
+        final_name = base_name
+        suffix = 1
+        while final_name in used_names:
+            final_name = f"{base_name}_{suffix}"
+            suffix += 1
+
+        simplified_names[col] = final_name
+        used_names.add(final_name)
+
+    return simplified_names
+
+
+def print_dashboard_instructions(project: str) -> None:
+    """
+    Prints instructions for viewing the Trackio dashboard.
+
+    Args:
+        project: The name of the project to show dashboard for.
+    """
+    YELLOW = "\033[93m"
+    BOLD = "\033[1m"
+    RESET = "\033[0m"
+
+    print("* View dashboard by running in your terminal:")
+    print(f'{BOLD}{YELLOW}trackio show --project "{project}"{RESET}')
+    print(f'* or by running in Python: trackio.show(project="{project}")')
+
+
+def preprocess_space_and_dataset_ids(
+    space_id: str | None, dataset_id: str | None
+) -> tuple[str | None, str | None]:
+    if space_id is not None and "/" not in space_id:
+        username = huggingface_hub.whoami()["name"]
+        space_id = f"{username}/{space_id}"
+    if dataset_id is not None and "/" not in dataset_id:
+        username = huggingface_hub.whoami()["name"]
+        dataset_id = f"{username}/{dataset_id}"
+    if space_id is not None and dataset_id is None:
+        dataset_id = f"{space_id}-dataset"
+    return space_id, dataset_id
+
+
+def fibo():
+    """Generator for Fibonacci backoff: 1, 1, 2, 3, 5, 8, ..."""
+    a, b = 1, 1
+    while True:
+        yield a
+        a, b = b, a + b
+
+
+COLOR_PALETTE = [
+    "#3B82F6",
+    "#EF4444",
+    "#10B981",
+    "#F59E0B",
+    "#8B5CF6",
+    "#EC4899",
+    "#06B6D4",
+    "#84CC16",
+    "#F97316",
+    "#6366F1",
+]
+
+
+def get_color_mapping(runs: list[str], smoothing: bool) -> dict[str, str]:
+    """Generate color mapping for runs, with transparency for original data when smoothing is enabled."""
+    color_map = {}
+
+    for i, run in enumerate(runs):
+        base_color = COLOR_PALETTE[i % len(COLOR_PALETTE)]
+
+        if smoothing:
+            color_map[f"{run}_smoothed"] = base_color
+            color_map[f"{run}_original"] = base_color + "4D"
+        else:
+            color_map[run] = base_color
+
+    return color_map
+
+
+def downsample(
+    df: pd.DataFrame,
+    x: str,
+    y: str,
+    color: str | None,
+    x_lim: tuple[float, float] | None = None,
+) -> pd.DataFrame:
+    if df.empty:
+        return df
+
+    columns_to_keep = [x, y]
+    if color is not None and color in df.columns:
+        columns_to_keep.append(color)
+    df = df[columns_to_keep].copy()
+
+    n_bins = 100
+
+    if color is not None and color in df.columns:
+        groups = df.groupby(color)
+    else:
+        groups = [(None, df)]
+
+    downsampled_indices = []
+
+    for _, group_df in groups:
+        if group_df.empty:
+            continue
+
+        group_df = group_df.sort_values(x)
+
+        if x_lim is not None:
+            x_min, x_max = x_lim
+            before_point = group_df[group_df[x] < x_min].tail(1)
+            after_point = group_df[group_df[x] > x_max].head(1)
+            group_df = group_df[(group_df[x] >= x_min) & (group_df[x] <= x_max)]
+        else:
+            before_point = after_point = None
+            x_min = group_df[x].min()
+            x_max = group_df[x].max()
+
+        if before_point is not None and not before_point.empty:
+            downsampled_indices.extend(before_point.index.tolist())
+        if after_point is not None and not after_point.empty:
+            downsampled_indices.extend(after_point.index.tolist())
+
+        if group_df.empty:
+            continue
+
+        if x_min == x_max:
+            min_y_idx = group_df[y].idxmin()
+            max_y_idx = group_df[y].idxmax()
+            if min_y_idx != max_y_idx:
+                downsampled_indices.extend([min_y_idx, max_y_idx])
+            else:
+                downsampled_indices.append(min_y_idx)
+            continue
+
+        if len(group_df) < 500:
+            downsampled_indices.extend(group_df.index.tolist())
+            continue
+
+        bins = np.linspace(x_min, x_max, n_bins + 1)
+        group_df["bin"] = pd.cut(
+            group_df[x], bins=bins, labels=False, include_lowest=True
+        )
+
+        for bin_idx in group_df["bin"].dropna().unique():
+            bin_data = group_df[group_df["bin"] == bin_idx]
+            if bin_data.empty:
+                continue
+
+            min_y_idx = bin_data[y].idxmin()
+            max_y_idx = bin_data[y].idxmax()
+
+            downsampled_indices.append(min_y_idx)
+            if min_y_idx != max_y_idx:
+                downsampled_indices.append(max_y_idx)
+
+    unique_indices = list(set(downsampled_indices))
+
+    downsampled_df = df.loc[unique_indices].copy()
+    downsampled_df = downsampled_df.sort_values(x).reset_index(drop=True)
+    downsampled_df = downsampled_df.drop(columns=["bin"], errors="ignore")
+
+    return downsampled_df
+
+
+def sort_metrics_by_prefix(metrics: list[str]) -> list[str]:
+    """
+    Sort metrics by grouping prefixes together for dropdown/list display.
+    Metrics without prefixes come first, then grouped by prefix.
+
+    Args:
+        metrics: List of metric names
+
+    Returns:
+        List of metric names sorted by prefix
+
+    Example:
+    Input: ["train/loss", "loss", "train/acc", "val/loss"]
+    Output: ["loss", "train/acc", "train/loss", "val/loss"]
+    """
+    groups = group_metrics_by_prefix(metrics)
+    result = []
+
+    if "charts" in groups:
+        result.extend(groups["charts"])
+
+    for group_name in sorted(groups.keys()):
+        if group_name != "charts":
+            result.extend(groups[group_name])
+
+    return result
+
+
+def group_metrics_by_prefix(metrics: list[str]) -> dict[str, list[str]]:
+    """
+    Group metrics by their prefix. Metrics without prefix go to 'charts' group.
+
+    Args:
+        metrics: List of metric names
+
+    Returns:
+        Dictionary with prefix names as keys and lists of metrics as values
+
+    Example:
+        Input: ["loss", "accuracy", "train/loss", "train/acc", "val/loss"]
+        Output: {
+            "charts": ["loss", "accuracy"],
+            "train": ["train/loss", "train/acc"],
+            "val": ["val/loss"]
+        }
+    """
+    no_prefix = []
+    with_prefix = []
+
+    for metric in metrics:
+        if "/" in metric:
+            with_prefix.append(metric)
+        else:
+            no_prefix.append(metric)
+
+    no_prefix.sort()
+
+    prefix_groups = {}
+    for metric in with_prefix:
+        prefix = metric.split("/")[0]
+        if prefix not in prefix_groups:
+            prefix_groups[prefix] = []
+        prefix_groups[prefix].append(metric)
+
+    for prefix in prefix_groups:
+        prefix_groups[prefix].sort()
+
+    groups = {}
+    if no_prefix:
+        groups["charts"] = no_prefix
+
+    for prefix in sorted(prefix_groups.keys()):
+        groups[prefix] = prefix_groups[prefix]
+
+    return groups
+
+
+def group_metrics_with_subprefixes(metrics: list[str]) -> dict:
+    """
+    Group metrics with simple 2-level nested structure detection.
+
+    Returns a dictionary where each prefix group can have:
+    - direct_metrics: list of metrics at this level (e.g., "train/acc")
+    - subgroups: dict of subgroup name -> list of metrics (e.g., "loss" -> ["train/loss/norm", "train/loss/unnorm"])
+
+    Example:
+        Input: ["loss", "train/acc", "train/loss/normalized", "train/loss/unnormalized", "val/loss"]
+        Output: {
+            "charts": {
+                "direct_metrics": ["loss"],
+                "subgroups": {}
+            },
+            "train": {
+                "direct_metrics": ["train/acc"],
+                "subgroups": {
+                    "loss": ["train/loss/normalized", "train/loss/unnormalized"]
+                }
+            },
+            "val": {
+                "direct_metrics": ["val/loss"],
+                "subgroups": {}
+            }
+        }
+    """
+    result = {}
+
+    for metric in metrics:
+        if "/" not in metric:
+            if "charts" not in result:
+                result["charts"] = {"direct_metrics": [], "subgroups": {}}
+            result["charts"]["direct_metrics"].append(metric)
+        else:
+            parts = metric.split("/")
+            main_prefix = parts[0]
+
+            if main_prefix not in result:
+                result[main_prefix] = {"direct_metrics": [], "subgroups": {}}
+
+            if len(parts) == 2:
+                result[main_prefix]["direct_metrics"].append(metric)
+            else:
+                subprefix = parts[1]
+                if subprefix not in result[main_prefix]["subgroups"]:
+                    result[main_prefix]["subgroups"][subprefix] = []
+                result[main_prefix]["subgroups"][subprefix].append(metric)
+
+    for group_data in result.values():
+        group_data["direct_metrics"].sort()
+        for subgroup_metrics in group_data["subgroups"].values():
+            subgroup_metrics.sort()
+
+    if "charts" in result and not result["charts"]["direct_metrics"]:
+        del result["charts"]
+
+    return result
+
+
+def get_sync_status(scheduler: "CommitScheduler | DummyCommitScheduler") -> int | None:
+    """Get the sync status from the CommitScheduler in an integer number of minutes, or None if not synced yet."""
+    if getattr(
+        scheduler, "last_push_time", None
+    ):  # DummyCommitScheduler doesn't have last_push_time
+        time_diff = time.time() - scheduler.last_push_time
+        return int(time_diff / 60)
+    else:
+        return None

version.txt

@@ -0,0 +1 @@
+0.2.9