feature: add "group by" dropdown to sidebar

.changeset/loose-loops-obey.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:feature: add "group by" dropdown to sidebar

tests/unit/test_local_server_api.py

@@ -100,6 +100,56 @@ def test_local_dashboard_supports_remote_client(temp_dir):
         app.close()
 
 
+def test_get_run_configs_returns_config_per_run(temp_dir):
+    project = "test_run_configs"
+
+    run_a = trackio.init(
+        project=project,
+        name="run-a",
+        config={"lr": 0.01, "model": "resnet"},
+        group="exp-1",
+    )
+    run_a_id = run_a.id
+    trackio.log(metrics={"loss": 0.1})
+    trackio.finish()
+
+    run_b = trackio.init(
+        project=project,
+        name="run-b",
+        config={"lr": 0.02, "model": "vit"},
+    )
+    run_b_id = run_b.id
+    trackio.log(metrics={"loss": 0.2})
+    trackio.finish()
+
+    app, url, _, _ = trackio.show(block_thread=False, open_browser=False)
+
+    try:
+        client = Client(url, verbose=False)
+        configs = client.predict(project, api_name="/get_run_configs")
+
+        assert set(configs.keys()) == {run_a_id, run_b_id}
+        assert configs[run_a_id]["lr"] == 0.01
+        assert configs[run_a_id]["model"] == "resnet"
+        assert configs[run_a_id]["_Group"] == "exp-1"
+        assert configs[run_b_id]["lr"] == 0.02
+        assert configs[run_b_id]["model"] == "vit"
+    finally:
+        trackio.delete_project(project, force=True)
+        app.close()
+
+
+def test_get_run_configs_returns_empty_for_unknown_project(temp_dir):
+    app, url, _, _ = trackio.show(block_thread=False, open_browser=False)
+
+    try:
+        client = Client(url, verbose=False)
+        configs = client.predict("no_such_project", api_name="/get_run_configs")
+        assert configs == {}
+    finally:
+        app.close()
+
+
 def test_server_url_logs_to_self_hosted_server(temp_dir):
     project = "test_self_hosted"
     run_name = "self-hosted-run"

trackio/frontend/src/App.svelte

@@ -14,6 +14,7 @@
   import {
     getAllProjects,
     getRunsForProject,
+    getRunConfigs,
     getAlerts,
     getRunMutationStatus,
     getSettings,
@@ -88,6 +89,7 @@
   let spaceId = $state(null);
   let availableSystemDevices = $state([]);
   let selectedSystemDevices = $state([]);
+  let runConfigs = $state({});
 
   function runKey(run) {
     return run?.id ?? run?.name;
@@ -140,10 +142,14 @@
       selectedRuns = [];
       availableSystemDevices = [];
       selectedSystemDevices = [];
+      runConfigs = {};
       return;
     }
     try {
-      const data = await getRunsForProject(selectedProject);
+      const [data, configs] = await Promise.all([
+        getRunsForProject(selectedProject),
+        getRunConfigs(selectedProject).catch(() => null),
+      ]);
       const newRuns = [...(data || [])].reverse();
 
       if (JSON.stringify(runs) !== JSON.stringify(newRuns)) {
@@ -156,6 +162,7 @@
           prevOrdered,
         );
       }
+      if (configs != null) runConfigs = configs;
     } catch (e) {
       console.error("Failed to load runs:", e);
     }
@@ -401,6 +408,7 @@
       projectLocked={projectLocked}
       bind:selectedProject
       {runs}
+      {runConfigs}
       bind:selectedRuns
       bind:smoothing
       bind:xAxis

trackio/frontend/src/components/Sidebar.svelte

@@ -8,6 +8,7 @@
   import { buildColorMap, getColorForIndex } from "../lib/stores.js";
   import { latestOnlySelection } from "../lib/selection.js";
   import { filterMetricsByRegex } from "../lib/dataProcessing.js";
+  import { computeGroupByOptions, computeGroupedRuns } from "../lib/grouping.js";
 
   let {
     open = $bindable(true),
@@ -27,6 +28,7 @@
     realtimeEnabled = $bindable(true),
     showHeaders = $bindable(true),
     filterText = $bindable(""),
+    runConfigs = {},
     metricColumns = [],
     spacesMode = false,
     runMutationAllowed = true,
@@ -88,6 +90,24 @@
   let runColorMap = $derived(buildColorMap(runs));
   let filteredRunIds = $derived(filteredRuns.map((r) => r.id ?? r.name));
 
+  let groupByRaw = $state("None");
+  let groupByField = $derived(groupByRaw === "None" ? null : groupByRaw);
+
+  $effect(() => {
+    selectedProject;
+    groupByRaw = "None";
+  });
+
+  $effect(() => {
+    if (!groupByOptions.includes(groupByRaw)) {
+      groupByRaw = "None";
+    }
+  });
+
+
+  let groupByOptions = $derived(computeGroupByOptions(runConfigs));
+  let groupedRuns = $derived(computeGroupedRuns(filteredRuns, runConfigs, groupByField));
+
   let latestOnly = $state(false);
   let shareTab = $state("share");
   let copyFeedback = $state(null);
@@ -380,18 +400,72 @@
             placeholder="Type to filter..."
             showLabel={false}
           />
-          <div class="checkbox-list">
-            <ColoredCheckbox
-              choices={filteredRuns}
-              bind:selected={selectedRuns}
-              getKey={(run) => run.id ?? run.name}
-              getLabel={(run) => run.name}
-              colors={filteredRuns.map(
-              (r) => runColorMap[r.id ?? r.name] ?? getColorForIndex(Math.max(0, runs.indexOf(r))),
-            )}
-              ontoggle={() => { latestOnly = false; }}
-            />
-          </div>
+          {#if groupByOptions.length > 1}
+            <div class="group-by-row">
+              <Dropdown
+                label="Group by"
+                choices={groupByOptions}
+                bind:value={groupByRaw}
+                filterable={false}
+              />
+            </div>
+          {/if}
+          {#if groupedRuns}
+            <div class="grouped-runs">
+              {#each [...groupedRuns.entries()] as [groupLabel, groupRunList]}
+                {@const groupIds = groupRunList.map((r) => r.id ?? r.name)}
+                {@const groupSelected = groupIds.filter((id) => selectedRuns.includes(id))}
+                <div class="run-group-section">
+                  <div class="run-group-header">
+                    <label class="select-all-label">
+                      <input
+                        type="checkbox"
+                        class="select-all-cb"
+                        checked={groupSelected.length === groupIds.length && groupIds.length > 0}
+                        use:setIndeterminate={groupSelected.length > 0 && groupSelected.length < groupIds.length}
+                        onchange={() => {
+                          if (groupSelected.length === groupIds.length) {
+                            selectedRuns = selectedRuns.filter((id) => !groupIds.includes(id));
+                          } else {
+                            const toAdd = groupIds.filter((id) => !selectedRuns.includes(id));
+                            selectedRuns = [...selectedRuns, ...toAdd];
+                          }
+                          latestOnly = false;
+                        }}
+                      />
+                      <span class="run-group-label" title={groupLabel}>{groupLabel}</span>
+                      <span class="run-group-count">({groupRunList.length})</span>
+                    </label>
+                  </div>
+                  <div class="checkbox-list group-checkbox-list">
+                    <ColoredCheckbox
+                      choices={groupRunList}
+                      bind:selected={selectedRuns}
+                      getKey={(run) => run.id ?? run.name}
+                      getLabel={(run) => run.name}
+                      colors={groupRunList.map(
+                        (r) => runColorMap[r.id ?? r.name] ?? getColorForIndex(Math.max(0, runs.indexOf(r))),
+                      )}
+                      ontoggle={() => { latestOnly = false; }}
+                    />
+                  </div>
+                </div>
+              {/each}
+            </div>
+          {:else}
+            <div class="checkbox-list">
+              <ColoredCheckbox
+                choices={filteredRuns}
+                bind:selected={selectedRuns}
+                getKey={(run) => run.id ?? run.name}
+                getLabel={(run) => run.name}
+                colors={filteredRuns.map(
+                (r) => runColorMap[r.id ?? r.name] ?? getColorForIndex(Math.max(0, runs.indexOf(r))),
+              )}
+                ontoggle={() => { latestOnly = false; }}
+              />
+            </div>
+          {/if}
           {#if currentPage === "system" && availableSystemDevices.length > 0}
             <div class="device-group">
               <label class="select-all-label">
@@ -868,4 +942,44 @@
     white-space: nowrap;
     color: var(--body-text-color, #1f2937);
   }
+  .group-by-row {
+    margin-top: 8px;
+  }
+  .grouped-runs {
+    margin-top: 8px;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+  .run-group-section {
+    border: 1px solid var(--border-color-primary, #e5e7eb);
+    border-radius: var(--radius-md, 6px);
+    overflow: hidden;
+  }
+  .run-group-header {
+    display: flex;
+    align-items: center;
+    padding: 6px 10px;
+    background: var(--background-fill-secondary, #f9fafb);
+    border-bottom: 1px solid var(--border-color-primary, #e5e7eb);
+  }
+  .run-group-label {
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--body-text-color, #1f2937);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    max-width: 160px;
+  }
+  .run-group-count {
+    font-size: 11px;
+    color: var(--body-text-color-subdued, #9ca3af);
+    margin-left: 4px;
+    flex-shrink: 0;
+  }
+  .group-checkbox-list {
+    padding: 4px 10px;
+    max-height: none;
+  }
 </style>

trackio/frontend/src/lib/api.js

@@ -71,6 +71,11 @@ export async function getRunsForProject(project) {
   return await callApi("/get_runs_for_project", { project });
 }
 
+export async function getRunConfigs(project) {
+  if (await isStaticMode()) return staticApi.getRunConfigs(project);
+  return await callApi("/get_run_configs", { project });
+}
+
 function normalizeRun(run) {
   if (run == null) return { run: null, run_id: null };
   if (typeof run === "string") return { run, run_id: null };

trackio/frontend/src/lib/grouping.js

@@ -0,0 +1,67 @@
+export const PROMOTED_RESERVED_KEYS = Object.freeze({
+  _Group: "Group",
+  _Username: "Username",
+});
+
+function shouldHideKey(key) {
+  return key.startsWith("_") && !(key in PROMOTED_RESERVED_KEYS);
+}
+
+function displayLabelForKey(key) {
+  return PROMOTED_RESERVED_KEYS[key] ?? key;
+}
+
+export function resolveGroupByKey(displayLabel, runConfigs) {
+  if (!displayLabel) return null;
+  for (const [key, label] of Object.entries(PROMOTED_RESERVED_KEYS)) {
+    if (label === displayLabel && promotedKeyHasVariance(runConfigs, key)) return key;
+  }
+  return displayLabel;
+}
+
+function promotedKeyHasVariance(runConfigs, key) {
+  const seen = new Set();
+  for (const cfg of Object.values(runConfigs ?? {})) {
+    if (!cfg || typeof cfg !== "object") continue;
+    const raw = cfg[key];
+    const label = raw === null || raw === undefined ? "(unset)" : String(raw);
+    seen.add(label);
+    if (seen.size >= 2) return true;
+  }
+  return false;
+}
+
+export function computeGroupByOptions(runConfigs) {
+  const promoted = Object.keys(PROMOTED_RESERVED_KEYS)
+    .filter((k) => promotedKeyHasVariance(runConfigs, k))
+    .map(displayLabelForKey);
+  const surfacedPromotedLabels = new Set(promoted);
+
+  const regularKeys = new Set();
+  for (const cfg of Object.values(runConfigs ?? {})) {
+    if (!cfg || typeof cfg !== "object") continue;
+    for (const key of Object.keys(cfg)) {
+      if (cfg[key] === null || cfg[key] === undefined) continue;
+      if (shouldHideKey(key)) continue;
+      if (key in PROMOTED_RESERVED_KEYS) continue;
+      if (surfacedPromotedLabels.has(key)) continue;
+      regularKeys.add(key);
+    }
+  }
+  const regular = [...regularKeys].sort();
+  return ["None", ...promoted, ...regular];
+}
+
+export function computeGroupedRuns(filteredRuns, runConfigs, groupBy) {
+  const realKey = resolveGroupByKey(groupBy, runConfigs);
+  if (!realKey) return null;
+  const groups = new Map();
+  for (const run of filteredRuns) {
+    const cfg = (runConfigs ?? {})[run.id] ?? (runConfigs ?? {})[run.name] ?? {};
+    const raw = cfg[realKey];
+    const label = raw === null || raw === undefined ? "(unset)" : String(raw);
+    if (!groups.has(label)) groups.set(label, []);
+    groups.get(label).push(run);
+  }
+  return groups;
+}