Add an id field to Run which is used internally, allowing users to have multiple runs with the same run name (#505)

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/fifty-bugs-make.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Add an `id` field to `Run` which is used internally, allowing users to have multiple runs with the same run name

README.md

@@ -266,7 +266,7 @@ These numbers were measured against a free-tier Hugging Face Space (2 vCPU / 16
 
 ## Note: Trackio is in Beta (DB Schema May Change)
 
-Note that Trackio is in pre-release right now and we may release breaking changes. In particular, the schema of the Trackio sqlite database may change, which may require migrating or deleting existing database files (located by default at: `~/.cache/huggingface/trackio`).  
+Note that Trackio is in pre-release right now and we may release breaking changes. In particular, the schema of the Trackio sqlite database may change. Newer Trackio databases now use a stable `run_id` plus a non-unique `run_name`, while older databases remain readable in compatibility mode by treating `run_name` as the effective run identifier. Existing database files are located by default at: `~/.cache/huggingface/trackio`.  
 
 The current SQLite and parquet layout is documented in the [Storage Schema and Direct Queries](https://huggingface.co/docs/trackio/storage_schema) guide, including examples for `trackio query`.
 

docs/source/python_api.md

@@ -89,11 +89,13 @@ Represents a single run in a project.
 
 #### Properties
 
-- **`id`**: The run name (same as `name`)
-- **`name`**: The run name
+- **`id`**: The stable run identifier used internally by Trackio
+- **`name`**: The human-readable run name. Multiple runs can share the same name.
 - **`project`**: The project this run belongs to
 - **`config`**: The run's configuration dictionary (lazy-loaded)
 
+Note: Multiple runs can share the same `name`, as Trackio will use the `id` identifier to disambiguate them internally. 
+
 #### Methods
 
 - **`delete() -> bool`**: Deletes the run from its project. Returns `True` if successful, `False` otherwise.
@@ -149,4 +151,3 @@ for run in source_runs:
     run.move("archive")
     print(f"Moved {run.name} to archive")
 ```
-

docs/source/track.md

@@ -309,15 +309,26 @@ trackio.finish()
 
 ## Resuming a Run
 
-If you need to continue a run (for example, after an interruption), you can resume it by calling [`init`] again with the same project and run name, and setting `resume="must"`:
+Trackio identifies runs internally by a stable `run_id`. The human-readable `name`
+is no longer required to be unique, so you can create multiple runs with the same
+display name.
+
+If you need to continue the latest run with a given name (for example, after an
+interruption), call [`init`] again with the same project and run name, and set
+`resume="must"`:
 
 ```python
 trackio.init(project="my_project", name="my_first_run", resume="must")
 ```
 
-This will load the existing run so you can keep logging data.
+This will load the most recently created run with that name so you can keep
+logging data using the same `run_id`. But if you set `resume="must"`, and no previous run exists with the same name, Trackio will raise an error. 
+
+For more flexibility, use `resume="allow"`. This will resume the latest run with
+that name if one exists, or create a new run otherwise.
 
-For more flexibility, use `resume="allow"`. This will resume the run if it exists, or create a new one otherwise.
+The default is `resume="never"`, which always creates a fresh run with a new
+`run_id`, even if another run with the same `name` already exists.
 
 ## Tracking Configuration
 

examples/crash-and-resume-same-run-name.py

@@ -0,0 +1,149 @@
+"""
+Demonstrates Trackio's run resume behavior when a job crashes and restarts with
+the same human-readable run name.
+
+Usage:
+  python examples/crash-and-resume-same-run-name.py
+  python examples/crash-and-resume-same-run-name.py --resume never
+  python examples/crash-and-resume-same-run-name.py --resume allow
+  python examples/crash-and-resume-same-run-name.py --resume must
+
+This example runs both phases in a single invocation:
+- phase 1 always starts a fresh run and logs 20 steps
+- a simulated crash interrupts the job
+- phase 2 restarts the job with the configured resume mode and logs 100 more steps
+
+The restart behavior is controlled by `--resume`:
+- `never`: restart creates a second run with the same name and a new run_id
+- `allow`: restart resumes the latest run with that name if it exists
+- `must`: restart must resume an existing run with that name
+"""
+
+import argparse
+import math
+import uuid
+import warnings
+
+warnings.filterwarnings(
+    "ignore",
+    category=SyntaxWarning,
+    module=r"pydub\.utils",
+)
+
+import trackio  # noqa: E402
+
+DEFAULT_PROJECT = f"crash-and-resume-demo-{uuid.uuid4().hex[:8]}"
+DEFAULT_RUN_NAME = "trainer-job-42"
+DEFAULT_CRASH_STEPS = 50
+DEFAULT_RESTART_STEPS = 100
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project", default=DEFAULT_PROJECT)
+    parser.add_argument("--run-name", default=DEFAULT_RUN_NAME)
+    parser.add_argument("--crash-steps", type=int, default=DEFAULT_CRASH_STEPS)
+    parser.add_argument("--restart-steps", type=int, default=DEFAULT_RESTART_STEPS)
+    parser.add_argument(
+        "--resume",
+        choices=["never", "allow", "must"],
+        default="never",
+        help="Resume mode used for the simulated restart phase.",
+    )
+    return parser.parse_args()
+
+
+def log_phase(
+    start_step: int, num_steps: int, start_loss: float, end_loss: float
+) -> None:
+    print(f"Logging steps {start_step}..{start_step + num_steps - 1}")
+    for offset in range(num_steps):
+        progress = offset / max(1, num_steps - 1)
+        loss = (
+            start_loss
+            + ((end_loss - start_loss) * progress)
+            + (0.01 * math.sin(offset / 6))
+        )
+        accuracy = (
+            0.25
+            + (0.7 * (1 - (loss / max(start_loss, 0.01))))
+            + (0.02 * math.cos(offset / 9))
+        )
+        trackio.log(
+            {
+                "loss": round(loss, 4),
+                "accuracy": round(max(0.0, min(0.999, accuracy)), 4),
+                "phase_progress": offset + 1,
+            },
+            step=None,
+        )
+
+
+def start_run(
+    project: str,
+    run_name: str,
+    resume: str,
+    phase: str,
+    crash_steps: int,
+    restart_steps: int,
+):
+    run = trackio.init(
+        project=project,
+        name=run_name,
+        resume=resume,
+        config={
+            "phase": phase,
+            "resume_mode": resume,
+            "crash_steps": crash_steps,
+            "restart_steps": restart_steps,
+        },
+    )
+    print(f"Trackio run name: {run.name}")
+    print(f"Trackio run id:   {run.id}")
+    print(f"Phase:            {phase}")
+    print(f"Resume mode:      {resume}")
+    return run
+
+
+def main() -> None:
+    args = parse_args()
+
+    print("=== phase 1: start fresh run ===")
+    first_run = start_run(
+        project=args.project,
+        run_name=args.run_name,
+        resume="never",
+        phase="crash",
+        crash_steps=args.crash_steps,
+        restart_steps=args.restart_steps,
+    )
+    log_phase(start_step=0, num_steps=args.crash_steps, start_loss=0.7, end_loss=0.6)
+    trackio.finish()
+
+    print(f"Simulated crash after {args.crash_steps} steps. Restarting the job now.")
+
+    print("=== phase 2: restart job ===")
+    restarted_run = start_run(
+        project=args.project,
+        run_name=args.run_name,
+        resume=args.resume,
+        phase="restart",
+        crash_steps=args.crash_steps,
+        restart_steps=args.restart_steps,
+    )
+    log_phase(
+        start_step=args.crash_steps,
+        num_steps=args.restart_steps,
+        start_loss=0.7,
+        end_loss=0.2,
+    )
+    trackio.finish()
+
+    resumed_same_run = restarted_run.id == first_run.id
+    print(f"Restart reused original run id: {resumed_same_run}")
+    print(f"Project:               {args.project}")
+    print("Done. Open the dashboard to inspect the resulting run list and charts.")
+
+
+if __name__ == "__main__":
+    main()

tests/e2e-local/test_api.py

@@ -191,7 +191,8 @@ def test_local_dashboard_supports_remote_client(temp_dir):
         settings = client.predict(api_name="/get_settings")
 
         assert project in projects
-        assert runs == [run_name]
+        assert len(runs) == 1
+        assert runs[0]["name"] == run_name
         assert "logo_urls" in settings
     finally:
         trackio.delete_project(project, force=True)
@@ -362,7 +363,9 @@ async def check_mcp() -> None:
                     "get_runs_for_project",
                     {"project": project},
                 )
-                assert runs.structuredContent["result"] == [run_name]
+                result = runs.structuredContent["result"]
+                assert len(result) == 1
+                assert result[0]["name"] == run_name
 
                 run_summary = await session.call_tool(
                     "get_run_summary",

tests/e2e-spaces/test_metrics_on_spaces.py

@@ -128,9 +128,10 @@ def test_runs_data_persisted_after_restart(test_space_id):
     deadline = time.time() + 300
     while time.time() < deadline:
         try:
-            run_names = client.predict(
+            run_records = client.predict(
                 project=project_name, api_name="/get_runs_for_project"
             )
+            run_names = [r["name"] if isinstance(r, dict) else r for r in run_records]
             if run_name in run_names:
                 break
         except Exception:

tests/e2e-spaces/test_throughput.py

@@ -95,9 +95,10 @@ def worker(thread_idx):
     deadline = time.time() + 120
     while time.time() < deadline:
         try:
-            runs = verify_client.predict(
+            run_records = verify_client.predict(
                 project=project_name, api_name="/get_runs_for_project"
             )
+            runs = [r["name"] if isinstance(r, dict) else r for r in run_records]
             if len(runs) == num_threads:
                 break
         except Exception: