Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,5 @@ 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
+trackio/assets/badge.png filter=lfs diff=lfs merge=lfs -text
+trackio/assets/trackio_logo_old.png filter=lfs diff=lfs merge=lfs -text

trackio/CHANGELOG.md

@@ -0,0 +1,304 @@
+# trackio
+
+## 0.26.0
+
+### Features
+
+- [#553](https://github.com/gradio-app/trackio/pull/553) [`06011ac`](https://github.com/gradio-app/trackio/commit/06011acc9c73341fd234f9cd8eaf96d5a34ad8ce) - fix: serve static-Space assets at /static/trackio.  Thanks @abidlabs!
+- [#563](https://github.com/gradio-app/trackio/pull/563) [`551569c`](https://github.com/gradio-app/trackio/commit/551569c16fb56ec63249ebdc28348d326ccf7126) - Fix Traces UI a bit.  Thanks @abidlabs!
+- [#550](https://github.com/gradio-app/trackio/pull/550) [`5690acd`](https://github.com/gradio-app/trackio/commit/5690acda5da303c63ad332451afeab3e9750fd1a) - fix: keep sparse metrics sparse through smoothing.  Thanks @abidlabs!
+- [#551](https://github.com/gradio-app/trackio/pull/551) [`0ef7266`](https://github.com/gradio-app/trackio/commit/0ef72660695cf932f3906ddbf33d41d087280a22) - add "group by" dropdown to sidebar.  Thanks @Saba9!
+- [#538](https://github.com/gradio-app/trackio/pull/538) [`a15c1a8`](https://github.com/gradio-app/trackio/commit/a15c1a8877c07514e0596630bb7c7299299994a9) - Subdue empty dashboard tabs.  Thanks @abidlabs!
+- [#559](https://github.com/gradio-app/trackio/pull/559) [`0b53a41`](https://github.com/gradio-app/trackio/commit/0b53a413909598f92138b6b6395a91c2d5034faf) - Store traces separately from metrics.  Thanks @abidlabs!
+- [#556](https://github.com/gradio-app/trackio/pull/556) [`d110001`](https://github.com/gradio-app/trackio/commit/d110001dbd9f6b262dfe41f2b702e3a71aa0cfc9) - fix: keep selected x-axis option in dropdown and dismiss dropdown on re-click.  Thanks @Saba9!
+- [#560](https://github.com/gradio-app/trackio/pull/560) [`aee2923`](https://github.com/gradio-app/trackio/commit/aee2923d3ada4f74d62d065c16f1f6a56a295e48) - Paginate Traces tab with step filter.  Thanks @abidlabs!
+
+### Fixes
+
+- [#540](https://github.com/gradio-app/trackio/pull/540) [`0b674ac`](https://github.com/gradio-app/trackio/commit/0b674ac6438738de89bc5b3fb700ccfd8a39368c) - raise default metrics sampling cap from 1500 to 3000 so client-side smoothing on the Metrics tab runs over higher-resolution data.  Thanks @edbeeching!
+
+## 0.25.1
+
+### Features
+
+- [#535](https://github.com/gradio-app/trackio/pull/535) [`d7f1b27`](https://github.com/gradio-app/trackio/commit/d7f1b27a98f185d2d97ef54975d5865e0b5243c9) - Avoid HF token leaks in static snapshots.  Thanks @abidlabs!
+
+## 0.25.0
+
+### Features
+
+- [#533](https://github.com/gradio-app/trackio/pull/533) [`08bc5eb`](https://github.com/gradio-app/trackio/commit/08bc5eb090525d3ff5f7fa4233c30c42162aa74c) - Fix Windows-only emoji mojibake when uploading Space README.  Thanks @tomaarsen!
+- [#518](https://github.com/gradio-app/trackio/pull/518) [`e7ed176`](https://github.com/gradio-app/trackio/commit/e7ed176da53d8b49290fddd890b3d18c0b9b958f) - Traces in Trackio.  Thanks @abidlabs!
+- [#531](https://github.com/gradio-app/trackio/pull/531) [`27a50a3`](https://github.com/gradio-app/trackio/commit/27a50a37362020304b774344b4c774ff548985b6) - Add configurable custom frontends for Trackio.  Thanks @abidlabs!
+
+## 0.24.2
+
+### Features
+
+- [#527](https://github.com/gradio-app/trackio/pull/527) [`7d1c0b9`](https://github.com/gradio-app/trackio/commit/7d1c0b9c37ce9a9845e6bbe6c083da9d36084caf) - Fix dashboard UX issues: smoothing in share URL, run selection, and run filtering.  Thanks @abidlabs!
+- [#526](https://github.com/gradio-app/trackio/pull/526) [`643878a`](https://github.com/gradio-app/trackio/commit/643878a82985fab9e6675f769ff0107cb46e042a) - Add emoji to README and deploy README content.  Thanks @qgallouedec!
+- [#529](https://github.com/gradio-app/trackio/pull/529) [`a77972b`](https://github.com/gradio-app/trackio/commit/a77972b68541ebe9e056824e69c9bbca3979ece4) - Remove pydub dependency.  Thanks @abidlabs!
+
+## 0.24.1
+
+### Features
+
+- [#524](https://github.com/gradio-app/trackio/pull/524) [`65a6897`](https://github.com/gradio-app/trackio/commit/65a6897561b465fc8f05550562f8da1ba3c99060) - Fix `trackio skills add`.  Thanks @abidlabs!
+- [#522](https://github.com/gradio-app/trackio/pull/522) [`05aaca7`](https://github.com/gradio-app/trackio/commit/05aaca7f166bf7667b60b40656d677532a4bdd6e) - relax `starlette` dependency and fix import style.  Thanks @abidlabs!
+- [#525](https://github.com/gradio-app/trackio/pull/525) [`32c05c5`](https://github.com/gradio-app/trackio/commit/32c05c5d5e3aa84ca7099a6fa08a9093ccd4b95f) - Restore sidebar share and embed snippets, and fix query parameter regression.  Thanks @abidlabs!
+
+## 0.24.0
+
+### Features
+
+- [#502](https://github.com/gradio-app/trackio/pull/502) [`3b397df`](https://github.com/gradio-app/trackio/commit/3b397dfbaff9de137b088f3cad528117e14faab1) - Add docs on SQL & Parquet schema / format, as well as a new CLI command: `trackio query project --project PROJECT --sql SQL_QUERY`.  Thanks @abidlabs!
+- [#506](https://github.com/gradio-app/trackio/pull/506) [`498bbc4`](https://github.com/gradio-app/trackio/commit/498bbc47f66cc90cc5776f363d001a5571941c00) - Scope bucket sync to trackio/ subtree to avoid walking the HF cache.  Thanks @abidlabs!
+- [#505](https://github.com/gradio-app/trackio/pull/505) [`8e26ab9`](https://github.com/gradio-app/trackio/commit/8e26ab93b5d9caa2f81334f6fff42fb9cefbb232) - Add an `id` field to `Run` which is used internally, allowing users to have multiple runs with the same run name.  Thanks @abidlabs!
+- [#517](https://github.com/gradio-app/trackio/pull/517) [`29e1034`](https://github.com/gradio-app/trackio/commit/29e1034b795567ec5ed6d19c5a946915a6498e2a) - Fix static exports, Space bucket handling, and other misc issues.  Thanks @abidlabs!
+- [#489](https://github.com/gradio-app/trackio/pull/489) [`1b96db3`](https://github.com/gradio-app/trackio/commit/1b96db39c8fd4326e621ee2336b0fca4f263a18a) - Remove `gradio` dependency in `trackio` -- only `gradio_client` is needed locally anymore. Also lazily import `pandas` and remove it as a dependency.  Thanks @abidlabs!
+- [#513](https://github.com/gradio-app/trackio/pull/513) [`d54d290`](https://github.com/gradio-app/trackio/commit/d54d290fcb1bb08358b558a43a962f78abe990ea) - Reduce HF Spaces 429s: polling tuning and batched metric logs API.  Thanks @abidlabs!
+- [#516](https://github.com/gradio-app/trackio/pull/516) [`afe2959`](https://github.com/gradio-app/trackio/commit/afe295988928a3ea3ded38bdb5bb05cca85d3c74) - Fix run list order and legend overflow.  Thanks @abidlabs!
+- [#515](https://github.com/gradio-app/trackio/pull/515) [`0a242b8`](https://github.com/gradio-app/trackio/commit/0a242b85127b02f532b24c7fd2bb046580cc7641) - Add Gradio-compatible /gradio_api routes on Spaces.  Thanks @abidlabs!
+- [#510](https://github.com/gradio-app/trackio/pull/510) [`60bbc86`](https://github.com/gradio-app/trackio/commit/60bbc86b4e7f880de72075e5bf31b093709bb5a4) - Add server_url and TRACKIO_SERVER_URL for self-hosted servers; space_id and TRACKIO_SPACE_ID take precedence when both are set.  Thanks @abidlabs!
+- [#509](https://github.com/gradio-app/trackio/pull/509) [`21c099a`](https://github.com/gradio-app/trackio/commit/21c099aa830a278973fab4c7c58a0139f417caa4) - Fix: Open browser with write_token so trackio show allows mutations.  Thanks @abidlabs!
+
+## 0.23.0
+
+### Features
+
+- [#494](https://github.com/gradio-app/trackio/pull/494) [`e8a897d`](https://github.com/gradio-app/trackio/commit/e8a897d2266d9b2558f72d768b0b21f4d0a8781b) - Add a settings/CLI page to Trackio.  Thanks @abidlabs!
+- [#481](https://github.com/gradio-app/trackio/pull/481) [`882647e`](https://github.com/gradio-app/trackio/commit/882647ec1599cf04500d03b5ca75ddc2733682e2) - Add multi-GPU system metrics support.  Thanks @Saba9!
+- [#485](https://github.com/gradio-app/trackio/pull/485) [`46a3cc3`](https://github.com/gradio-app/trackio/commit/46a3cc3758719e171417612efee102a487e71ebd) - Fix/remove flaky E2E space tests.  Thanks @abidlabs!
+- [#501](https://github.com/gradio-app/trackio/pull/501) [`06ea885`](https://github.com/gradio-app/trackio/commit/06ea8852f5e40ab3f1cf629a0a01af5c17f847a1) - Fix SQLite corruption on bucket-mounted Spaces.  Thanks @abidlabs!
+- [#496](https://github.com/gradio-app/trackio/pull/496) [`af23d74`](https://github.com/gradio-app/trackio/commit/af23d74438b146c4a3512ace15ea984656e943ed) - Prevent trackio errors from crashing the user's training loop.  Thanks @abidlabs!
+
+## 0.22.0
+
+### Features
+
+- [#484](https://github.com/gradio-app/trackio/pull/484) [`cc05ada`](https://github.com/gradio-app/trackio/commit/cc05ada8e89773f3a894af99b801ef680f64418f) - Fix duplicate columns in parquet export.  Thanks @abidlabs!
+- [#487](https://github.com/gradio-app/trackio/pull/487) [`853f764`](https://github.com/gradio-app/trackio/commit/853f7646a70d12633afaa4f69db86425aa665413) - Relax `PIL` dependency and remove `plotly` as it's no longer used.  Thanks @abidlabs!
+
+## 0.21.2
+
+### Features
+
+- [#482](https://github.com/gradio-app/trackio/pull/482) [`f62180a`](https://github.com/gradio-app/trackio/commit/f62180a0218bc99a259d5ca110a0384a6cae11c8) - Use server-side bucket copy when freezing Spaces.  Thanks @abidlabs!
+
+## 0.21.1
+
+### Features
+
+- [#475](https://github.com/gradio-app/trackio/pull/475) [`fcb476c`](https://github.com/gradio-app/trackio/commit/fcb476cd37a40923e9679aaf966f41d582a878a8) - Tweaks.  Thanks @abidlabs!
+- [#477](https://github.com/gradio-app/trackio/pull/477) [`7d52dfd`](https://github.com/gradio-app/trackio/commit/7d52dfdce5b6eff6a34501a6d5a620220663cf09) - Fix `.sync()` and add `.freeze()` as a separate methods.  Thanks @abidlabs!
+
+## 0.21.0
+
+### Features
+
+- [#467](https://github.com/gradio-app/trackio/pull/467) [`f357deb`](https://github.com/gradio-app/trackio/commit/f357debf78957e4c1f2b901bee4f77cf397298b4) - Allow logged metrics as x-axis choices.  Thanks @abidlabs!
+- [#474](https://github.com/gradio-app/trackio/pull/474) [`655673d`](https://github.com/gradio-app/trackio/commit/655673d4c6b7c8b7ee8f87f2589f2dbbc3d2ef91) - Fix file descriptor leak from `sqlite3.connect`.  Thanks @abidlabs!
+- [#470](https://github.com/gradio-app/trackio/pull/470) [`bea8c9d`](https://github.com/gradio-app/trackio/commit/bea8c9dcae0b59d071b6c779c97ee525c9bbf6e7) - Restores tooltips to line plots and fixes the call to uses TTL instead of OAuth.  Thanks @abidlabs!
+- [#471](https://github.com/gradio-app/trackio/pull/471) [`246fce0`](https://github.com/gradio-app/trackio/commit/246fce0a01619e1c2c538c67b3e460883334d500) - Deprecate dataset backend in favor of buckets.  Thanks @abidlabs!
+- [#465](https://github.com/gradio-app/trackio/pull/465) [`3e11174`](https://github.com/gradio-app/trackio/commit/3e1117438bb8168b802245a33059affa558ae519) - Use HF buckets as backend.  Thanks @abidlabs!
+- [#469](https://github.com/gradio-app/trackio/pull/469) [`915d170`](https://github.com/gradio-app/trackio/commit/915d17045133172b59195acfdcc70709229668aa) - Make static Spaces work with Buckets and also allow conversion from Gradio SDK to Static Spaces.  Thanks @abidlabs!
+
+## 0.20.2
+
+### Features
+
+- [#464](https://github.com/gradio-app/trackio/pull/464) [`c89ebb3`](https://github.com/gradio-app/trackio/commit/c89ebb3b50f695bc7f16cbc6f46dce86f79a01e9) - Improve rendering of curves.  Thanks @abidlabs!
+- [#462](https://github.com/gradio-app/trackio/pull/462) [`9160b78`](https://github.com/gradio-app/trackio/commit/9160b78ff6f258f0b87a4f34a24e7d0b5dfbf2fb) - Refactor plot title to display only the metric name without the path.  Thanks @qgallouedec!
+
+## 0.20.1
+
+### Features
+
+- [#454](https://github.com/gradio-app/trackio/pull/454) [`22881db`](https://github.com/gradio-app/trackio/commit/22881dbbbb6b81197a00a19853771007093d61e4) - Bar chart single point.  Thanks @abidlabs!
+- [#455](https://github.com/gradio-app/trackio/pull/455) [`f8db51a`](https://github.com/gradio-app/trackio/commit/f8db51a20ca61ef703f3f2c2ee1ebd9c4f239cf2) - Adds a static Trackio mode via `trackio.sync(sdk="static")` and support for the `TRACKIO_SPACE_ID` environment variable.  Thanks @abidlabs!
+
+## 0.20.0
+
+### Features
+
+- [#450](https://github.com/gradio-app/trackio/pull/450) [`b0571ef`](https://github.com/gradio-app/trackio/commit/b0571ef6207a1ce346696f858ad2b7b584dd194f) - Use Svelte source for Gradio components directly in Trackio dashboard.  Thanks @abidlabs!
+
+## 0.19.0
+
+### Features
+
+- [#445](https://github.com/gradio-app/trackio/pull/445) [`cef4a58`](https://github.com/gradio-app/trackio/commit/cef4a583cb76f4091fc6c0e5783124ee84f8e243) - Add remote HF Space support to CLI.  Thanks @abidlabs!
+- [#444](https://github.com/gradio-app/trackio/pull/444) [`358f2a9`](https://github.com/gradio-app/trackio/commit/358f2a9ca238ee8b90b5a8c96220da287e0698fb) - Fix alerts placeholder flashing on reports page.  Thanks @abidlabs!
+
+## 0.18.0
+
+### Features
+
+- [#435](https://github.com/gradio-app/trackio/pull/435) [`4a47112`](https://github.com/gradio-app/trackio/commit/4a471128e18a39e45fad48a67fd711c5ae9e4aed) - feat: allow hiding section header accordions.  Thanks @Saba9!
+- [#439](https://github.com/gradio-app/trackio/pull/439) [`18e9650`](https://github.com/gradio-app/trackio/commit/18e96503d5a3a7cf926e92782d457e23c19942bd) - Add alerts with webhooks, CLI, and documentation.  Thanks @abidlabs!
+- [#438](https://github.com/gradio-app/trackio/pull/438) [`0875ccd`](https://github.com/gradio-app/trackio/commit/0875ccd3d8a41b1376f64030f21cfe8cdcc73b05) - Add "share this view" functionality.  Thanks @qgallouedec!
+- [#409](https://github.com/gradio-app/trackio/pull/409) [`9282403`](https://github.com/gradio-app/trackio/commit/9282403d8896d48679b0f888208a7ba5bdd4271a) - Add Apple Silicon GPU and system monitoring support.  Thanks @znation!
+- [#434](https://github.com/gradio-app/trackio/pull/434) [`4193223`](https://github.com/gradio-app/trackio/commit/41932230a3a2e1c16405dba08ecba5a42f11d1a8) - fix: table slider crash.  Thanks @Saba9!
+
+### Fixes
+
+- [#441](https://github.com/gradio-app/trackio/pull/441) [`3a2d11d`](https://github.com/gradio-app/trackio/commit/3a2d11dab0b4b37c925abc30ef84b0e2910321ee) - preserve x-axis step when toggling run checkboxes.  Thanks @Saba9!
+
+## 0.17.0
+
+### Features
+
+- [#428](https://github.com/gradio-app/trackio/pull/428) [`f7dd1ce`](https://github.com/gradio-app/trackio/commit/f7dd1ce2dc8a1936f9983467fcbcf93bfef01e09) - feat: add ability to rename runs.  Thanks @Saba9!
+- [#437](https://github.com/gradio-app/trackio/pull/437) [`2727c0b`](https://github.com/gradio-app/trackio/commit/2727c0b0755f48f7f186162ea45185c98f6b5516) - Add markdown reports across Trackio.  Thanks @abidlabs!
+- [#427](https://github.com/gradio-app/trackio/pull/427) [`5aeb9ed`](https://github.com/gradio-app/trackio/commit/5aeb9edcfd2068d309d9d64f172dcbcc327be1ab) - Make Trackio logging much more robust.  Thanks @abidlabs!
+
+## 0.16.1
+
+### Features
+
+- [#431](https://github.com/gradio-app/trackio/pull/431) [`c7ce55b`](https://github.com/gradio-app/trackio/commit/c7ce55b14dd5eb0c2165fb15df17dd60721c9325) - Lazy load the UI when trackio is imported.  Thanks @abidlabs!
+
+## 0.16.0
+
+### Features
+
+- [#426](https://github.com/gradio-app/trackio/pull/426) [`ead4dc8`](https://github.com/gradio-app/trackio/commit/ead4dc8e74ee2d8e47d61bca0a7668456acf49be) - Fix redundant double rendering of group checkboxes.  Thanks @abidlabs!
+- [#413](https://github.com/gradio-app/trackio/pull/413) [`39c4750`](https://github.com/gradio-app/trackio/commit/39c4750951d554ba6eb4d58847c6bb444b2891a8) - Check `dist-packages` when checking for source installation.  Thanks @sergiopaniego!
+- [#423](https://github.com/gradio-app/trackio/pull/423) [`2e52ab3`](https://github.com/gradio-app/trackio/commit/2e52ab303e3041718a6a56fbf84d0848aca9ad67) - Fix legend outline visibility issue.  Thanks @Raghunath-Balaji!
+- [#407](https://github.com/gradio-app/trackio/pull/407) [`c8a384d`](https://github.com/gradio-app/trackio/commit/c8a384ddfe5a295cecf862a26178d40e48acb424) - Fix pytests that were failling locally on MacOS.  Thanks @abidlabs!
+- [#405](https://github.com/gradio-app/trackio/pull/405) [`35aae4e`](https://github.com/gradio-app/trackio/commit/35aae4e3aa3e2b2888887528478b9dc6a9808bda) - Add conditional padding for HF Space dashboard when not in iframe.  Thanks @znation!
+
+## 0.15.0
+
+### Features
+
+- [#397](https://github.com/gradio-app/trackio/pull/397) [`6b38ad0`](https://github.com/gradio-app/trackio/commit/6b38ad02e5d73a0df49c4eede7e91331282ece04) - Adds `--host` cli option support.  Thanks @abidlabs!
+- [#396](https://github.com/gradio-app/trackio/pull/396) [`4a4d1ab`](https://github.com/gradio-app/trackio/commit/4a4d1ab85e63d923132a3fa7afa5d90e16431bec) - Fix run selection issue.  Thanks @abidlabs!
+- [#394](https://github.com/gradio-app/trackio/pull/394) [`c47a3a3`](https://github.com/gradio-app/trackio/commit/c47a3a31f8c4b83bce1aa7fc22eeba3d9021ad3d) - Add wandb-compatible API for trackio.  Thanks @abidlabs!
+- [#378](https://github.com/gradio-app/trackio/pull/378) [`b02046a`](https://github.com/gradio-app/trackio/commit/b02046a5b0dad7c9854e099a87f884afba4aecb2) - Add JSON export button for line plots and upgrade gradio dependency.  Thanks @JamshedAli18!
+
+## 0.14.2
+
+### Features
+
+- [#386](https://github.com/gradio-app/trackio/pull/386) [`f9452cd`](https://github.com/gradio-app/trackio/commit/f9452cdb8f0819368f3610f7ac0ed08957305275) - Fixing some issues related to deployed Trackio Spaces.  Thanks @abidlabs!
+
+## 0.14.1
+
+### Features
+
+- [#382](https://github.com/gradio-app/trackio/pull/382) [`44fe9bb`](https://github.com/gradio-app/trackio/commit/44fe9bb264fb2aafb0ec302ff15227c045819a2c) - Fix app file path when Trackio is not installed from source.  Thanks @abidlabs!
+- [#380](https://github.com/gradio-app/trackio/pull/380) [`c3f4cff`](https://github.com/gradio-app/trackio/commit/c3f4cff74bc5676e812773d8571454894fcdc7cc) - Add CLI commands for querying projects, runs, and metrics.  Thanks @abidlabs!
+
+## 0.14.0
+
+### Features
+
+- [#377](https://github.com/gradio-app/trackio/pull/377) [`5c5015b`](https://github.com/gradio-app/trackio/commit/5c5015b68c85c5de51111dad983f735c27b9a05f) - fixed wrapping issue in Runs table.  Thanks @gaganchapa!
+- [#374](https://github.com/gradio-app/trackio/pull/374) [`388e26b`](https://github.com/gradio-app/trackio/commit/388e26b9e9f24cd7ad203affe9b709be885b3d24) - Save Optimized Parquet files.  Thanks @lhoestq!
+- [#371](https://github.com/gradio-app/trackio/pull/371) [`fbace9c`](https://github.com/gradio-app/trackio/commit/fbace9cd7732c166f34d268f54b05bb06846cc5d) - Add GPU metrics logging.  Thanks @kashif!
+- [#367](https://github.com/gradio-app/trackio/pull/367) [`862840c`](https://github.com/gradio-app/trackio/commit/862840c13e30fc960cbee5b9eac4d3c25beba9de) - Add option to only show latest run, and fix the double logo issue.  Thanks @abidlabs!
+
+## 0.13.1
+
+### Features
+
+- [#369](https://github.com/gradio-app/trackio/pull/369) [`767e9fe`](https://github.com/gradio-app/trackio/commit/767e9fe095d7c6ed102016caf927c1517fb8618c) - tiny pr removing unnecessary code.  Thanks @abidlabs!
+
+## 0.13.0
+
+### Features
+
+- [#358](https://github.com/gradio-app/trackio/pull/358) [`073715d`](https://github.com/gradio-app/trackio/commit/073715d1caf8282f68890117f09c3ac301205312) - Improvements to `trackio.sync()`.  Thanks @abidlabs!
+
+## 0.12.0
+
+### Features
+
+- [#357](https://github.com/gradio-app/trackio/pull/357) [`02ba815`](https://github.com/gradio-app/trackio/commit/02ba815358060f1966052de051a5bdb09702920e) - Redesign media and tables to show up on separate page.  Thanks @abidlabs!
+- [#359](https://github.com/gradio-app/trackio/pull/359) [`08fe9c9`](https://github.com/gradio-app/trackio/commit/08fe9c9ddd7fe99ee811555fdfb62df9ab88e939) - docs: Improve docstrings.  Thanks @qgallouedec!
+
+## 0.11.0
+
+### Features
+
+- [#355](https://github.com/gradio-app/trackio/pull/355) [`ea51f49`](https://github.com/gradio-app/trackio/commit/ea51f4954922f21be76ef828700420fe9a912c4b) - Color code run checkboxes and match with plot lines.  Thanks @abidlabs!
+- [#353](https://github.com/gradio-app/trackio/pull/353) [`8abe691`](https://github.com/gradio-app/trackio/commit/8abe6919aeefe21fc7a23af814883efbb037c21f) - Remove show_api from demo.launch.  Thanks @sergiopaniego!
+- [#351](https://github.com/gradio-app/trackio/pull/351) [`8a8957e`](https://github.com/gradio-app/trackio/commit/8a8957e530dd7908d1fef7f2df030303f808101f) - Add `trackio.save()`.  Thanks @abidlabs!
+
+## 0.10.0
+
+### Features
+
+- [#305](https://github.com/gradio-app/trackio/pull/305) [`e64883a`](https://github.com/gradio-app/trackio/commit/e64883a51f7b8b93f7d48b8afe55acdb62238b71) - bump to gradio 6.0, make `trackio` compatible, and fix related issues.  Thanks @abidlabs!
+
+## 0.9.1
+
+### Features
+
+- [#344](https://github.com/gradio-app/trackio/pull/344) [`7e01024`](https://github.com/gradio-app/trackio/commit/7e010241d9a34794e0ce0dc19c1a6f0cf94ba856) - Avoid redundant calls to /whoami-v2.  Thanks @Wauplin!
+
+## 0.9.0
+
+### Features
+
+- [#343](https://github.com/gradio-app/trackio/pull/343) [`51bea30`](https://github.com/gradio-app/trackio/commit/51bea30f2877adff8e6497466d3a799400a0a049) - Sync offline projects to Hugging Face spaces.  Thanks @candemircan!
+- [#341](https://github.com/gradio-app/trackio/pull/341) [`4fd841f`](https://github.com/gradio-app/trackio/commit/4fd841fa190e15071b02f6fba7683ef4f393a654) - Adds a basic UI test to `trackio`.  Thanks @abidlabs!
+- [#339](https://github.com/gradio-app/trackio/pull/339) [`011d91b`](https://github.com/gradio-app/trackio/commit/011d91bb6ae266516fd250a349285670a8049d05) - Allow customzing the trackio color palette.  Thanks @abidlabs!
+
+## 0.8.1
+
+### Features
+
+- [#336](https://github.com/gradio-app/trackio/pull/336) [`5f9f51d`](https://github.com/gradio-app/trackio/commit/5f9f51dac8677f240d7c42c3e3b2660a22aee138) - Support a list of `Trackio.Image` in a `trackio.Table` cell.  Thanks @abidlabs!
+
+## 0.8.0
+
+### Features
+
+- [#331](https://github.com/gradio-app/trackio/pull/331) [`2c02d0f`](https://github.com/gradio-app/trackio/commit/2c02d0fd0a5824160528782402bb0dd4083396d5) - Truncate table string values that are greater than 250 characters (configuirable via env variable).  Thanks @abidlabs!
+- [#324](https://github.com/gradio-app/trackio/pull/324) [`50b2122`](https://github.com/gradio-app/trackio/commit/50b2122e7965ac82a72e6cb3b7d048bc10a2a6b1) - Add log y-axis functionality to UI.  Thanks @abidlabs!
+- [#326](https://github.com/gradio-app/trackio/pull/326) [`61dc1f4`](https://github.com/gradio-app/trackio/commit/61dc1f40af2f545f8e70395ddf0dbb8aee6b60d5) - Fix: improve table rendering for metrics in Trackio Dashboard.  Thanks @vigneshwaran!
+- [#328](https://github.com/gradio-app/trackio/pull/328) [`6857cbb`](https://github.com/gradio-app/trackio/commit/6857cbbe557a59a4642f210ec42566d108294e63) - Support trackio.Table with trackio.Image columns.  Thanks @abidlabs!
+- [#323](https://github.com/gradio-app/trackio/pull/323) [`6857cbb`](https://github.com/gradio-app/trackio/commit/6857cbbe557a59a4642f210ec42566d108294e63) - add Trackio client implementations in Go, Rust, and JS.  Thanks @vaibhav-research!
+
+## 0.7.0
+
+### Features
+
+- [#277](https://github.com/gradio-app/trackio/pull/277) [`db35601`](https://github.com/gradio-app/trackio/commit/db35601b9c023423c4654c9909b8ab73e58737de) - fix: make grouped runs view reflect live updates.  Thanks @Saba9!
+- [#320](https://github.com/gradio-app/trackio/pull/320) [`24ae739`](https://github.com/gradio-app/trackio/commit/24ae73969b09fb3126acd2f91647cdfbf8cf72a1) - Add additional query parms for xmin, xmax, and smoothing.  Thanks @abidlabs!
+- [#270](https://github.com/gradio-app/trackio/pull/270) [`cd1dfc3`](https://github.com/gradio-app/trackio/commit/cd1dfc3dc641b4499ac6d4a1b066fa8e2b52c57b) - feature: add support for logging audio.  Thanks @Saba9!
+
+## 0.6.0
+
+### Features
+
+- [#309](https://github.com/gradio-app/trackio/pull/309) [`1df2353`](https://github.com/gradio-app/trackio/commit/1df23534d6c01938c8db9c0f584ffa23e8d6021d) - Add histogram support with wandb-compatible API.  Thanks @abidlabs!
+- [#315](https://github.com/gradio-app/trackio/pull/315) [`76ba060`](https://github.com/gradio-app/trackio/commit/76ba06055dc43ca8f03b79f3e72d761949bd19a8) - Add guards to avoid silent fails.  Thanks @Xmaster6y!
+- [#313](https://github.com/gradio-app/trackio/pull/313) [`a606b3e`](https://github.com/gradio-app/trackio/commit/a606b3e1c5edf3d4cf9f31bd50605226a5a1c5d0) - No longer prevent certain keys from being used. Instead, dunderify them to prevent collisions with internal usage.  Thanks @abidlabs!
+- [#317](https://github.com/gradio-app/trackio/pull/317) [`27370a5`](https://github.com/gradio-app/trackio/commit/27370a595d0dbdf7eebbe7159d2ba778f039da44) - quick fixes for trackio.histogram.  Thanks @abidlabs!
+- [#312](https://github.com/gradio-app/trackio/pull/312) [`aa0f3bf`](https://github.com/gradio-app/trackio/commit/aa0f3bf372e7a0dd592a38af699c998363830eeb) - Fix video logging by adding TRACKIO_DIR to allowed_paths.  Thanks @abidlabs!
+
+## 0.5.3
+
+### Features
+
+- [#300](https://github.com/gradio-app/trackio/pull/300) [`5e4cacf`](https://github.com/gradio-app/trackio/commit/5e4cacf2e7ce527b4ce60de3a5bc05d2c02c77fb) - Adds more environment variables to allow customization of Trackio dashboard.  Thanks @abidlabs!
+
+## 0.5.2
+
+### Features
+
+- [#293](https://github.com/gradio-app/trackio/pull/293) [`64afc28`](https://github.com/gradio-app/trackio/commit/64afc28d3ea1dfd821472dc6bf0b8ed35a9b74be) - Ensures that the TRACKIO_DIR environment variable is respected.  Thanks @abidlabs!
+- [#287](https://github.com/gradio-app/trackio/pull/287) [`cd3e929`](https://github.com/gradio-app/trackio/commit/cd3e9294320949e6b8b829239069a43d5d7ff4c1) - fix(sqlite): unify .sqlite extension, allow export when DBs exist, clean WAL sidecars on import.  Thanks @vaibhav-research!
+
+### Fixes
+
+- [#291](https://github.com/gradio-app/trackio/pull/291) [`3b5adc3`](https://github.com/gradio-app/trackio/commit/3b5adc3d1f452dbab7a714d235f4974782f93730) - Fix the wheel build.  Thanks @pngwn!
+
+## 0.5.1
+
+### Fixes
+
+- [#278](https://github.com/gradio-app/trackio/pull/278) [`314c054`](https://github.com/gradio-app/trackio/commit/314c05438007ddfea3383e06fd19143e27468e2d) - Fix row orientation of metrics plots.  Thanks @abidlabs!

trackio/__init__.py

@@ -0,0 +1,1122 @@
+import atexit
+import glob
+import json
+import logging
+import os
+import shutil
+import warnings
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+import huggingface_hub
+from gradio_client import handle_file
+from huggingface_hub import SpaceStorage
+from huggingface_hub.errors import LocalTokenNotFoundError
+
+from trackio import context_vars, deploy, utils
+from trackio.alerts import AlertLevel
+from trackio.api import Api
+from trackio.apple_gpu import apple_gpu_available
+from trackio.apple_gpu import log_apple_gpu as _log_apple_gpu
+from trackio.deploy import freeze, sync
+from trackio.frontend_config import resolve_frontend_dir
+from trackio.gpu import gpu_available
+from trackio.gpu import log_gpu as _log_nvidia_gpu
+from trackio.histogram import Histogram
+from trackio.imports import import_csv, import_tf_events
+from trackio.launch import launch_trackio_dashboard
+from trackio.markdown import Markdown
+from trackio.media import (
+    TrackioAudio,
+    TrackioImage,
+    TrackioVideo,
+    get_project_media_path,
+)
+from trackio.remote_client import RemoteClient
+from trackio.run import Run
+from trackio.server import TrackioDashboardApp, build_starlette_app_only
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.table import Table
+from trackio.trace import Trace
+from trackio.typehints import UploadEntry
+from trackio.utils import TRACKIO_DIR, TRACKIO_LOGO_DIR, _emit_nonfatal_warning
+
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+__version__ = json.loads(Path(__file__).parent.joinpath("package.json").read_text())[
+    "version"
+]
+
+
+class _TupleNoPrint(tuple):
+    def __repr__(self) -> str:
+        return ""
+
+
+__all__ = [
+    "init",
+    "log",
+    "log_system",
+    "log_gpu",
+    "finish",
+    "alert",
+    "AlertLevel",
+    "show",
+    "sync",
+    "freeze",
+    "delete_project",
+    "import_csv",
+    "import_tf_events",
+    "save",
+    "Image",
+    "Video",
+    "Audio",
+    "Table",
+    "Trace",
+    "Histogram",
+    "Markdown",
+    "Api",
+    "TRACKIO_LOGO_DIR",
+]
+
+Audio = TrackioAudio
+Image = TrackioImage
+Video = TrackioVideo
+
+
+config = {}
+
+_atexit_registered = False
+_projects_notified_auto_log_hw: set[str] = set()
+
+
+def _cleanup_current_run():
+    run = context_vars.current_run.get()
+    if run is not None:
+        try:
+            run.finish()
+        except Exception:
+            pass
+
+
+def _safe_get_runs_for_init(
+    project: str,
+    space_id: str | None,
+    server_base_url: str | None,
+    write_token: str | None,
+    resume: str,
+    remote_client: RemoteClient | None = None,
+    check_existing_for_never: bool = False,
+) -> list[str]:
+    if space_id is not None:
+        if resume == "never" and not check_existing_for_never:
+            return []
+        try:
+            client = remote_client or RemoteClient(
+                space_id,
+                hf_token=huggingface_hub.utils.get_token(),
+                verbose=False,
+            )
+            runs = client.predict(project=project, api_name="/get_runs_for_project")
+            return runs if isinstance(runs, list) else []
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not inspect existing runs for project '{project}' on Space '{space_id}': {e}. Continuing without resume metadata."
+            )
+            return []
+    if server_base_url is not None:
+        if resume == "never" and not check_existing_for_never:
+            return []
+        try:
+            client = remote_client or RemoteClient(
+                server_base_url,
+                hf_token=None,
+                write_token=write_token,
+                verbose=False,
+            )
+            runs = client.predict(project=project, api_name="/get_runs_for_project")
+            return runs if isinstance(runs, list) else []
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not inspect existing runs for project '{project}' on self-hosted server '{server_base_url}': {e}. Continuing without resume metadata."
+            )
+            return []
+    try:
+        return SQLiteStorage.get_runs(project)
+    except Exception as e:
+        _emit_nonfatal_warning(
+            f"trackio.init() could not inspect existing runs for project '{project}': {e}. Continuing without resume metadata."
+        )
+        return []
+
+
+def _safe_get_latest_run_for_init(
+    project: str,
+    name: str,
+    space_id: str | None = None,
+    server_base_url: str | None = None,
+    write_token: str | None = None,
+    remote_client: RemoteClient | None = None,
+) -> dict | None:
+    if space_id is not None:
+        try:
+            client = remote_client or RemoteClient(
+                space_id,
+                hf_token=huggingface_hub.utils.get_token(),
+                verbose=False,
+            )
+            runs = client.predict(project=project, api_name="/get_runs_for_project")
+            if not isinstance(runs, list):
+                return None
+            matches = [r for r in runs if isinstance(r, dict) and r.get("name") == name]
+            if not matches:
+                return None
+            matches.sort(key=lambda r: r.get("created_at") or "", reverse=True)
+            return matches[0]
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not inspect existing runs for project '{project}' on Space '{space_id}': {e}. Continuing without resume metadata."
+            )
+            return None
+    if server_base_url is not None:
+        try:
+            client = remote_client or RemoteClient(
+                server_base_url,
+                hf_token=None,
+                write_token=write_token,
+                verbose=False,
+            )
+            runs = client.predict(project=project, api_name="/get_runs_for_project")
+            if not isinstance(runs, list):
+                return None
+            matches = [r for r in runs if isinstance(r, dict) and r.get("name") == name]
+            if not matches:
+                return None
+            matches.sort(key=lambda r: r.get("created_at") or "", reverse=True)
+            return matches[0]
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not inspect existing runs for project '{project}' on self-hosted server '{server_base_url}': {e}. Continuing without resume metadata."
+            )
+            return None
+    try:
+        return SQLiteStorage.get_latest_run_record_by_name(project, name)
+    except Exception as e:
+        _emit_nonfatal_warning(
+            f"trackio.init() could not inspect existing runs for project '{project}': {e}. Continuing without resume metadata."
+        )
+        return None
+
+
+def _safe_get_last_step_for_init(
+    project: str,
+    run_name: str,
+    space_id: str | None,
+    server_base_url: str | None,
+    write_token: str | None,
+    resumed: bool,
+    run_id: str | None = None,
+    remote_client: RemoteClient | None = None,
+) -> int | None:
+    if not resumed:
+        return None
+    if space_id is not None:
+        try:
+            client = remote_client or RemoteClient(
+                space_id,
+                hf_token=huggingface_hub.utils.get_token(),
+                verbose=False,
+            )
+            summary_kwargs: dict[str, Any] = {
+                "project": project,
+                "api_name": "/get_run_summary",
+            }
+            if run_id is not None:
+                summary_kwargs["run_id"] = run_id
+            else:
+                summary_kwargs["run"] = run_name
+            summary = client.predict(**summary_kwargs)
+            if isinstance(summary, dict):
+                last_step = summary.get("last_step")
+                return last_step if isinstance(last_step, int) else None
+            return None
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not recover the previous step for run '{run_name}' on Space '{space_id}': {e}. Continuing from step 0."
+            )
+            return None
+    if server_base_url is not None:
+        try:
+            client = remote_client or RemoteClient(
+                server_base_url,
+                hf_token=None,
+                write_token=write_token,
+                verbose=False,
+            )
+            summary_kwargs = {
+                "project": project,
+                "api_name": "/get_run_summary",
+            }
+            if run_id is not None:
+                summary_kwargs["run_id"] = run_id
+            else:
+                summary_kwargs["run"] = run_name
+            summary = client.predict(**summary_kwargs)
+            if isinstance(summary, dict):
+                last_step = summary.get("last_step")
+                return last_step if isinstance(last_step, int) else None
+            return None
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not recover the previous step for run '{run_name}' on self-hosted server '{server_base_url}': {e}. Continuing from step 0."
+            )
+            return None
+    try:
+        return SQLiteStorage.get_max_step_for_run(project, run_name, run_id=run_id)
+    except Exception as e:
+        _emit_nonfatal_warning(
+            f"trackio.init() could not recover the previous step for run '{run_name}': {e}. Continuing from step 0."
+        )
+        return None
+
+
+def init(
+    project: str,
+    name: str | None = None,
+    group: str | None = None,
+    space_id: str | None = None,
+    server_url: str | None = None,
+    space_storage: SpaceStorage | None = None,
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    config: dict | None = None,
+    resume: str = "never",
+    settings: Any = None,
+    private: bool | None = None,
+    embed: bool = True,
+    auto_log_gpu: bool | None = None,
+    gpu_log_interval: float = 10.0,
+    webhook_url: str | None = None,
+    webhook_min_level: AlertLevel | str | None = None,
+) -> Run:
+    """
+    Creates a new Trackio project and returns a [`Run`] object.
+
+    Args:
+        project (`str`):
+            The name of the project (can be an existing project to continue tracking or
+            a new project to start tracking from scratch).
+        name (`str`, *optional*):
+            The name of the run (if not provided, a default name will be generated).
+        group (`str`, *optional*):
+            The name of the group which this run belongs to in order to help organize
+            related runs together. You can toggle the entire group's visibility in the
+            dashboard.
+        space_id (`str`, *optional*):
+            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. Can also be set
+            via the `TRACKIO_SPACE_ID` environment variable. You cannot log to a
+            Space that has been **frozen** (converted to the static SDK); use
+            ``trackio.sync(..., sdk="static")`` only after you are done logging.
+            Takes precedence over `server_url` and `TRACKIO_SERVER_URL` when more than
+            one is set.
+        server_url (`str`, *optional*):
+            Base URL of a self-hosted Trackio server (``http://`` or ``https://``), or the
+            write-access URL from ``trackio.show()`` which may include a ``write_token`` query
+            parameter. The client sends that token on each request (``X-Trackio-Write-Token``);
+            you can also set ``TRACKIO_WRITE_TOKEN`` instead of embedding the token in the URL.
+            When set, metrics are sent to that server over HTTP instead of creating or syncing
+            to a Hugging Face Space. Can also be set via the ``TRACKIO_SERVER_URL`` environment
+            variable. Ignored when ``space_id`` or ``TRACKIO_SPACE_ID`` is set.
+        space_storage ([`~huggingface_hub.SpaceStorage`], *optional*):
+            Choice of persistent storage tier.
+        dataset_id (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        bucket_id (`str`, *optional*):
+            The ID of the Hugging Face Bucket to use for metric persistence. By default,
+            when a `space_id` is provided and `bucket_id` is not explicitly set, a
+            bucket is auto-generated from the space_id. Buckets provide
+            S3-like storage without git overhead - the SQLite database is stored directly
+            via `hf-mount` in the Space. Specify a Bucket with name like
+            `"username/bucketname"` or just `"bucketname"`.
+        config (`dict`, *optional*):
+            A dictionary of configuration options. Provided for compatibility with
+            `wandb.init()`.
+        resume (`str`, *optional*, defaults to `"never"`):
+            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
+        private (`bool`, *optional*):
+            Whether to make the Space 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.
+        settings (`Any`, *optional*):
+            Not used. Provided for compatibility with `wandb.init()`.
+        embed (`bool`, *optional*, defaults to `True`):
+            If running inside a Jupyter/Colab notebook, whether the dashboard should
+            automatically be embedded in the cell when trackio.init() is called. For
+            local runs, this launches a local Trackio dashboard and embeds it. For Space runs,
+            this embeds the Space URL. In Colab, the local dashboard will be accessible
+            via a public share URL when `share=True`.
+        auto_log_gpu (`bool` or `None`, *optional*, defaults to `None`):
+            Controls automatic GPU metrics logging. If `None` (default), GPU logging
+            is automatically enabled when `nvidia-ml-py` is installed and an NVIDIA
+            GPU or Apple M series is detected. Set to `True` to force enable or
+            `False` to disable.
+        gpu_log_interval (`float`, *optional*, defaults to `10.0`):
+            The interval in seconds between automatic GPU metric logs.
+            Only used when `auto_log_gpu=True`.
+        webhook_url (`str`, *optional*):
+            A webhook URL to POST alert payloads to when `trackio.alert()` is
+            called. Supports Slack and Discord webhook URLs natively (payloads
+            are formatted automatically). Can also be set via the
+            `TRACKIO_WEBHOOK_URL` environment variable. Individual alerts can
+            override this URL by passing `webhook_url` to `trackio.alert()`.
+        webhook_min_level (`AlertLevel` or `str`, *optional*):
+            Minimum alert level that should trigger webhook delivery.
+            For example, `AlertLevel.WARN` sends only `WARN` and `ERROR`
+            alerts to the webhook destination. Can also be set via
+            `TRACKIO_WEBHOOK_MIN_LEVEL`.
+    Returns:
+        `Run`: A [`Run`] object that can be used to log metrics and finish the run.
+    """
+    if settings is not None:
+        _emit_nonfatal_warning(
+            "* 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."
+        )
+
+    previous_run = context_vars.current_run.get()
+    if previous_run is not None:
+        try:
+            previous_run.finish()
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not finish the previous run '{previous_run.name}': {e}. Continuing with new run."
+            )
+        context_vars.current_run.set(None)
+
+    bucket_id_was_explicit = bucket_id is not None
+    space_id, server_url = utils.resolve_space_id_and_server_url(space_id, server_url)
+    if bucket_id is None and utils.on_spaces():
+        bucket_id = os.environ.get("TRACKIO_BUCKET_ID")
+    if server_url is not None and not server_url.startswith(("http://", "https://")):
+        raise ValueError(
+            f"`server_url` must be a full URL starting with http:// or https://, got: {server_url!r}"
+        )
+    server_base_url: str | None = None
+    write_token_resolved: str | None = None
+    if server_url is not None:
+        server_base_url, tok = utils.parse_trackio_server_url(server_url)
+        write_token_resolved = tok or os.environ.get("TRACKIO_WRITE_TOKEN")
+        if not write_token_resolved:
+            raise ValueError(
+                "Self-hosted logging requires a write token: add write_token to the server URL, "
+                "or set the TRACKIO_WRITE_TOKEN environment variable."
+            )
+    if server_url is not None and (dataset_id is not None or bucket_id is not None):
+        raise ValueError(
+            "`dataset_id` and `bucket_id` are Hugging Face Spaces concepts and are not "
+            "compatible with `server_url`. Configure storage on the self-hosted server."
+        )
+    if space_id is None and dataset_id is not None:
+        raise ValueError("Must provide a `space_id` when `dataset_id` is provided.")
+    if dataset_id is not None and bucket_id is not None:
+        raise ValueError("Cannot provide both `dataset_id` and `bucket_id`.")
+    try:
+        space_id, dataset_id, bucket_id = utils.preprocess_space_and_dataset_ids(
+            space_id, dataset_id, bucket_id
+        )
+        if (
+            space_id is not None
+            and dataset_id is None
+            and bucket_id is not None
+            and not bucket_id_was_explicit
+            and not utils.on_spaces()
+        ):
+            bucket_id = deploy.resolve_auto_bucket_id(space_id, bucket_id)
+    except LocalTokenNotFoundError as e:
+        raise LocalTokenNotFoundError(
+            f"You must be logged in to Hugging Face locally when `space_id` is provided to deploy to a Space. {e}"
+        ) from e
+
+    if space_id is None and bucket_id is not None:
+        _emit_nonfatal_warning(
+            "trackio.init() has `bucket_id` set but `space_id` is None: metrics will be logged "
+            "locally only. Pass `space_id` to create or use a Hugging Face Space, which will be "
+            "attached to the Hugging Face Bucket.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    if space_id is not None:
+        deploy.raise_if_space_is_frozen_for_logging(space_id)
+
+    remote_source = space_id or server_base_url
+
+    if remote_source is not None:
+        url = remote_source
+        context_vars.current_server.set(url)
+        if space_id is not None:
+            context_vars.current_space_id.set(space_id)
+            context_vars.current_server_write_token.set(None)
+        else:
+            context_vars.current_space_id.set(None)
+            context_vars.current_server_write_token.set(write_token_resolved)
+    else:
+        url = None
+        context_vars.current_server.set(None)
+        context_vars.current_space_id.set(None)
+        context_vars.current_server_write_token.set(None)
+
+    _should_embed_local = False
+
+    if (
+        context_vars.current_project.get() is None
+        or context_vars.current_project.get() != project
+    ):
+        print(f"* Trackio project initialized: {project}")
+
+        if bucket_id is not None:
+            if utils.on_spaces():
+                os.environ["TRACKIO_BUCKET_ID"] = bucket_id
+            bucket_url = f"https://huggingface.co/buckets/{bucket_id}"
+            print(
+                f"* Trackio metrics will be synced to Hugging Face Bucket: {bucket_url}"
+            )
+        elif dataset_id is not None:
+            if utils.on_spaces():
+                os.environ["TRACKIO_DATASET_ID"] = dataset_id
+            print(
+                f"* Trackio metrics will be synced to Hugging Face Dataset: {dataset_id}"
+            )
+        if remote_source is None:
+            print(f"* Trackio metrics logged to: {TRACKIO_DIR}")
+            _should_embed_local = embed and utils.is_in_notebook()
+            if not _should_embed_local:
+                utils.print_dashboard_instructions(project)
+        elif server_base_url is not None:
+            print(
+                f"* Trackio metrics will be sent to self-hosted server: {server_base_url}"
+            )
+            if utils.is_in_notebook() and embed:
+                utils.embed_url_in_notebook(server_base_url)
+        else:
+            try:
+                deploy.create_space_if_not_exists(
+                    space_id,
+                    space_storage,
+                    dataset_id,
+                    bucket_id,
+                    private,
+                )
+                user_name, space_name = space_id.split("/")
+                space_url = deploy.SPACE_HOST_URL.format(
+                    user_name=user_name, space_name=space_name
+                )
+                if utils.is_in_notebook() and embed:
+                    utils.embed_url_in_notebook(space_url)
+            except Exception as e:
+                _emit_nonfatal_warning(
+                    f"trackio.init() could not prepare Space '{space_id}': {e}. Logging will continue in local fallback mode until the Space is reachable."
+                )
+    context_vars.current_project.set(project)
+
+    remote_client = None
+    if space_id is not None:
+        try:
+            remote_client = RemoteClient(
+                space_id,
+                hf_token=huggingface_hub.utils.get_token(),
+                verbose=False,
+            )
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not create a remote client for Space '{space_id}': {e}. Continuing with local fallback metadata lookups."
+            )
+    elif server_base_url is not None:
+        try:
+            remote_client = RemoteClient(
+                server_base_url,
+                hf_token=None,
+                write_token=write_token_resolved,
+                verbose=False,
+            )
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not create a remote client for '{server_base_url}': {e}. Continuing with local fallback metadata lookups."
+            )
+
+    existing_run_records = _safe_get_runs_for_init(
+        project,
+        space_id,
+        server_base_url,
+        write_token_resolved,
+        resume,
+        remote_client=remote_client,
+        check_existing_for_never=name is not None,
+    )
+    existing_runs = [
+        r["name"] if isinstance(r, dict) else r for r in existing_run_records
+    ]
+
+    existing_run = (
+        _safe_get_latest_run_for_init(
+            project,
+            name,
+            space_id=space_id,
+            server_base_url=server_base_url,
+            write_token=write_token_resolved,
+            remote_client=remote_client,
+        )
+        if name is not None
+        else None
+    )
+    resolved_run_id = None
+
+    if resume == "must":
+        if name is None:
+            raise ValueError("Must provide a run name when resume='must'")
+        if existing_run is None:
+            raise ValueError(f"Run '{name}' does not exist in project '{project}'")
+        resumed = True
+        resolved_run_id = existing_run["id"]
+    elif resume == "allow":
+        resumed = existing_run is not None
+        if resumed:
+            resolved_run_id = existing_run["id"]
+    elif resume == "never":
+        resumed = False
+    else:
+        raise ValueError("resume must be one of: 'must', 'allow', or 'never'")
+
+    initial_last_step = (
+        _safe_get_last_step_for_init(
+            project,
+            name,
+            space_id,
+            server_base_url,
+            write_token_resolved,
+            resumed,
+            run_id=resolved_run_id,
+            remote_client=remote_client,
+        )
+        if name is not None
+        else None
+    )
+
+    if auto_log_gpu is None:
+        nvidia_available = gpu_available()
+        apple_available = apple_gpu_available()
+        auto_log_gpu = nvidia_available or apple_available
+        if project not in _projects_notified_auto_log_hw:
+            if nvidia_available:
+                print("* NVIDIA GPU detected, enabling automatic GPU metrics logging")
+            elif apple_available:
+                print(
+                    "* Apple Silicon detected, enabling automatic system metrics logging"
+                )
+            if nvidia_available or apple_available:
+                _projects_notified_auto_log_hw.add(project)
+
+    run = Run(
+        url=url,
+        project=project,
+        client=None,
+        name=name,
+        run_id=resolved_run_id,
+        group=group,
+        config=config,
+        space_id=space_id,
+        server_base_url=server_base_url,
+        write_token=write_token_resolved,
+        existing_runs=existing_runs,
+        initial_last_step=initial_last_step,
+        auto_log_gpu=auto_log_gpu,
+        gpu_log_interval=gpu_log_interval,
+        webhook_url=webhook_url,
+        webhook_min_level=webhook_min_level,
+    )
+
+    if space_id is not None:
+        try:
+            SQLiteStorage.set_project_metadata(project, "space_id", space_id)
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not persist Space metadata for project '{project}': {e}. Logging will continue."
+            )
+        try:
+            if SQLiteStorage.has_pending_data(project):
+                run._has_local_buffer = True
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not inspect pending buffered data for project '{project}': {e}. Logging will continue."
+            )
+
+    global _atexit_registered
+    if not _atexit_registered:
+        atexit.register(_cleanup_current_run)
+        _atexit_registered = True
+
+    if resumed:
+        print(f"* Resumed existing run: {run.name}")
+    else:
+        print(f"* Created new run: {run.name}")
+
+    context_vars.current_run.set(run)
+    globals()["config"] = run.config
+
+    if _should_embed_local:
+        try:
+            show(project=project, open_browser=False, block_thread=False)
+        except Exception as e:
+            _emit_nonfatal_warning(
+                f"trackio.init() could not auto-launch the dashboard: {e}. Logging will continue."
+            )
+
+    return run
+
+
+def log(metrics: dict, step: int | None = None) -> None:
+    """
+    Logs metrics to the current run.
+
+    Args:
+        metrics (`dict`):
+            A dictionary of metrics to log.
+        step (`int`, *optional*):
+            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 log_system(metrics: dict) -> None:
+    """
+    Logs system metrics (GPU, etc.) to the current run using timestamps instead of steps.
+
+    Args:
+        metrics (`dict`):
+            A dictionary of system metrics to log.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.log_system().")
+    run.log_system(metrics=metrics)
+
+
+def log_gpu(run: Run | None = None, device: int | None = None) -> dict:
+    """
+    Log GPU metrics to the current or specified run as system metrics.
+    Automatically detects whether an NVIDIA or Apple GPU is available and calls
+    the appropriate logging method.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+        device: CUDA device index to collect metrics from (NVIDIA GPUs only).
+                If None, collects from all GPUs visible to this process.
+                This parameter is ignored for Apple GPUs.
+
+    Returns:
+        dict: The GPU metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_gpu()
+        trackio.log_gpu(device=0)
+        ```
+    """
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_gpu().")
+
+    if gpu_available():
+        return _log_nvidia_gpu(run=run, device=device)
+    elif apple_gpu_available():
+        return _log_apple_gpu(run=run)
+    else:
+        _emit_nonfatal_warning(
+            "No GPU detected. Install nvidia-ml-py for NVIDIA GPU support "
+            "or psutil for Apple Silicon support."
+        )
+        return {}
+
+
+def finish():
+    """
+    Finishes the current run.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.finish().")
+    try:
+        run.finish()
+    finally:
+        context_vars.current_run.set(None)
+
+
+def alert(
+    title: str,
+    text: str | None = None,
+    level: AlertLevel = AlertLevel.WARN,
+    webhook_url: str | None = None,
+) -> None:
+    """
+    Fires an alert immediately on the current run. The alert is printed to the
+    terminal, stored in the database, and displayed in the dashboard. If a
+    webhook URL is configured (via `trackio.init()`, the `TRACKIO_WEBHOOK_URL`
+    environment variable, or the `webhook_url` parameter here), the alert is
+    also POSTed to that URL.
+
+    Args:
+        title (`str`):
+            A short title for the alert.
+        text (`str`, *optional*):
+            A longer description with details about the alert.
+        level (`AlertLevel`, *optional*, defaults to `AlertLevel.WARN`):
+            The severity level. One of `AlertLevel.INFO`, `AlertLevel.WARN`,
+            or `AlertLevel.ERROR`.
+        webhook_url (`str`, *optional*):
+            A webhook URL to send this specific alert to. Overrides any
+            URL set in `trackio.init()` or the `TRACKIO_WEBHOOK_URL`
+            environment variable. Supports Slack and Discord webhook
+            URLs natively.
+    """
+    run = context_vars.current_run.get()
+    if run is None:
+        raise RuntimeError("Call trackio.init() before trackio.alert().")
+    run.alert(title=title, text=text, level=level, webhook_url=webhook_url)
+
+
+def delete_project(project: str, force: bool = False) -> bool:
+    """
+    Deletes a project by removing its local SQLite database.
+
+    Args:
+        project (`str`):
+            The name of the project to delete.
+        force (`bool`, *optional*, defaults to `False`):
+            If `True`, deletes the project without prompting for confirmation.
+            If `False`, prompts the user to confirm before deleting.
+
+    Returns:
+        `bool`: `True` if the project was deleted, `False` otherwise.
+    """
+    db_path = SQLiteStorage.get_project_db_path(project)
+
+    if not db_path.exists():
+        print(f"* Project '{project}' does not exist.")
+        return False
+
+    if not force:
+        response = input(
+            f"Are you sure you want to delete project '{project}'? "
+            f"This will permanently delete all runs and metrics. (y/N): "
+        )
+        if response.lower() not in ["y", "yes"]:
+            print("* Deletion cancelled.")
+            return False
+
+    try:
+        db_path.unlink()
+
+        for suffix in ("-wal", "-shm"):
+            sidecar = Path(str(db_path) + suffix)
+            if sidecar.exists():
+                sidecar.unlink()
+
+        print(f"* Project '{project}' has been deleted.")
+        return True
+    except Exception as e:
+        print(f"* Error deleting project '{project}': {e}")
+        return False
+
+
+def save(
+    glob_str: str | Path,
+    project: str | None = None,
+) -> str:
+    """
+    Saves files to a project (not linked to a specific run). If Trackio is running
+    locally, the file(s) will be copied to the project's files directory. If Trackio is
+    running in a Space, the file(s) will be uploaded to the Space's files directory.
+
+    Args:
+        glob_str (`str` or `Path`):
+            The file path or glob pattern to save. Can be a single file or a pattern
+            matching multiple files (e.g., `"*.py"`, `"models/**/*.pth"`).
+        project (`str`, *optional*):
+            The name of the project to save files to. If not provided, uses the current
+            project from `trackio.init()`. If no project is initialized, raises an
+            error.
+
+    Returns:
+        `str`: The path where the file(s) were saved (project's files directory).
+
+    Example:
+        ```python
+        import trackio
+
+        trackio.init(project="my-project")
+        trackio.save("config.yaml")
+        trackio.save("models/*.pth")
+        ```
+    """
+    if project is None:
+        project = context_vars.current_project.get()
+        if project is None:
+            raise RuntimeError(
+                "No project specified. Either call trackio.init() first or provide a "
+                "project parameter to trackio.save()."
+            )
+
+    glob_str = Path(glob_str)
+    base_path = Path.cwd().resolve()
+
+    matched_files = []
+    if glob_str.is_file():
+        matched_files = [glob_str.resolve()]
+    else:
+        pattern = str(glob_str)
+        if not glob_str.is_absolute():
+            pattern = str((Path.cwd() / glob_str).resolve())
+        matched_files = [
+            Path(f).resolve()
+            for f in glob.glob(pattern, recursive=True)
+            if Path(f).is_file()
+        ]
+
+    if not matched_files:
+        raise ValueError(f"No files found matching pattern: {glob_str}")
+
+    current_run = context_vars.current_run.get()
+    is_local = (
+        current_run._is_local
+        if current_run is not None
+        else (
+            context_vars.current_space_id.get() is None
+            and context_vars.current_server.get() is None
+        )
+    )
+
+    if is_local:
+        for file_path in matched_files:
+            try:
+                relative_to_base = file_path.relative_to(base_path)
+            except ValueError:
+                relative_to_base = Path(file_path.name)
+
+            if current_run is not None:
+                current_run._queue_upload(
+                    file_path,
+                    step=None,
+                    relative_path=str(relative_to_base.parent),
+                    use_run_name=False,
+                )
+            else:
+                media_path = get_project_media_path(
+                    project=project,
+                    run=None,
+                    step=None,
+                    relative_path=str(relative_to_base),
+                )
+                shutil.copy(str(file_path), str(media_path))
+    else:
+        url = context_vars.current_server.get()
+
+        upload_entries = []
+        for file_path in matched_files:
+            try:
+                relative_to_base = file_path.relative_to(base_path)
+            except ValueError:
+                relative_to_base = Path(file_path.name)
+
+            if current_run is not None:
+                current_run._queue_upload(
+                    file_path,
+                    step=None,
+                    relative_path=str(relative_to_base.parent),
+                    use_run_name=False,
+                )
+            else:
+                upload_entry: UploadEntry = {
+                    "project": project,
+                    "run": None,
+                    "step": None,
+                    "relative_path": str(relative_to_base),
+                    "uploaded_file": handle_file(file_path),
+                }
+                upload_entries.append(upload_entry)
+
+        if upload_entries:
+            if url is None:
+                raise RuntimeError(
+                    "No server available. Call trackio.init() before trackio.save() to start the server."
+                )
+
+            try:
+                wt = context_vars.current_server_write_token.get()
+                if wt is not None:
+                    client = RemoteClient(
+                        url,
+                        hf_token=None,
+                        write_token=wt,
+                        httpx_kwargs={"timeout": 90},
+                    )
+                else:
+                    client = RemoteClient(
+                        url,
+                        hf_token=huggingface_hub.utils.get_token(),
+                        httpx_kwargs={"timeout": 90},
+                    )
+                client.predict(
+                    api_name="/bulk_upload_media",
+                    uploads=upload_entries,
+                    hf_token=huggingface_hub.utils.get_token() if wt is None else None,
+                )
+            except Exception as e:
+                _emit_nonfatal_warning(
+                    f"Failed to upload files: {e}. "
+                    "Files may not be available in the dashboard."
+                )
+
+    return str(utils.MEDIA_DIR / project / "files")
+
+
+def show(
+    project: str | None = None,
+    *,
+    theme: Any = None,
+    mcp_server: bool | None = None,
+    footer: bool = True,
+    color_palette: list[str] | None = None,
+    open_browser: bool = True,
+    block_thread: bool | None = None,
+    host: str | None = None,
+    share: bool | None = None,
+    server_port: int | None = None,
+    frontend_dir: str | Path | None = None,
+):
+    """
+    Launches the Trackio dashboard.
+
+    Args:
+        project (`str`, *optional*):
+            The name of the project whose runs to show. If not provided, all projects
+            will be shown and the user can select one.
+        theme (`Any`, *optional*):
+            Ignored. Kept for backward compatibility; Trackio no longer uses Gradio themes.
+        mcp_server (`bool`, *optional*):
+            If `True`, the dashboard exposes an MCP server at `/mcp` when the optional
+            `trackio[mcp]` dependency is installed. If `None` (default), the
+            `GRADIO_MCP_SERVER` environment variable is used (e.g. on Spaces).
+        footer (`bool`, *optional*, defaults to `True`):
+            Whether to include `footer=false` in the write-token URL when `False`.
+            This can also be controlled via the `footer` query parameter in the URL.
+        color_palette (`list[str]`, *optional*):
+            A list of hex color codes to use for plot lines. If not provided, the
+            `TRACKIO_COLOR_PALETTE` environment variable will be used (comma-separated
+            hex codes), or if that is not set, the default color palette will be used.
+            Example: `['#FF0000', '#00FF00', '#0000FF']`
+        open_browser (`bool`, *optional*, defaults to `True`):
+            If `True` and not in a notebook, a new browser tab will be opened with the
+            dashboard. If `False`, the browser will not be opened.
+        block_thread (`bool`, *optional*):
+            If `True`, the main thread will be blocked until the dashboard is closed.
+            If `None` (default behavior), then the main thread will not be blocked if the
+            dashboard is launched in a notebook, otherwise the main thread will be blocked.
+        host (`str`, *optional*):
+            The host to bind the server to. If not provided, defaults to `'127.0.0.1'`
+            (localhost only). Set to `'0.0.0.0'` to allow remote access.
+        share (`bool`, *optional*):
+            If `True`, creates a temporary public URL (Gradio-compatible tunnel). On Colab
+            or hosted notebooks, defaults to `True` unless overridden.
+        server_port (`int`, *optional*):
+            Port to bind. If not set, scans from `GRADIO_SERVER_PORT` (default 7860).
+        frontend_dir (`str | Path`, *optional*):
+            Directory containing a custom static frontend. Must contain `index.html`.
+            If not provided, Trackio checks `TRACKIO_FRONTEND_DIR`, then the persistent
+            Trackio config, then the bundled frontend. If an explicit `frontend_dir`
+            points to a missing or empty directory, Trackio copies in the starter
+            template and serves that directory.
+
+        Returns:
+            `app`: The dashboard handle (`.close()` stops the server).
+            `url`: The local URL of the dashboard.
+            `share_url`: The public share URL, if any.
+            `full_url`: The full URL including the write token (share URL when sharing, else local).
+    """
+    if theme is not None and theme != "default":
+        warnings.warn(
+            "The theme argument is ignored; Trackio no longer depends on Gradio themes.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    if color_palette is not None:
+        os.environ["TRACKIO_COLOR_PALETTE"] = ",".join(color_palette)
+
+    _mcp_server = (
+        mcp_server
+        if mcp_server is not None
+        else os.environ.get("GRADIO_MCP_SERVER", "False") == "True"
+    )
+
+    resolved_frontend = resolve_frontend_dir(frontend_dir, announce=True)
+    starlette_app, wt = build_starlette_app_only(
+        mcp_server=_mcp_server,
+        frontend_dir=str(resolved_frontend.path),
+    )
+    local_url, share_url, _local_api_url, uv_server = launch_trackio_dashboard(
+        starlette_app,
+        server_name=host,
+        server_port=server_port,
+        share=share,
+        mcp_server=_mcp_server,
+        quiet=True,
+    )
+    server = TrackioDashboardApp(starlette_app, uv_server, wt)
+
+    base_root = (share_url or local_url).rstrip("/")
+    base_url = base_root + "/"
+    dashboard_url = base_url
+    if project:
+        dashboard_url += f"?project={project}"
+    full_url = utils.get_full_url(
+        base_root,
+        project=project,
+        write_token=wt,
+        footer=footer,
+    )
+
+    if not utils.is_in_notebook():
+        print(f"\033[1m\033[38;5;208m* Trackio UI launched at: {dashboard_url}\033[0m")
+        utils.print_write_token_instructions(full_url)
+        if open_browser:
+            webbrowser.open(full_url)
+        block_thread = block_thread if block_thread is not None else True
+    else:
+        utils.embed_url_in_notebook(full_url)
+        block_thread = block_thread if block_thread is not None else False
+
+    if block_thread:
+        utils.block_main_thread_until_keyboard_interrupt()
+    return _TupleNoPrint((server, local_url, share_url, full_url))

trackio/_vendor/gradio_exceptions.py

@@ -0,0 +1,6 @@
+class ChecksumMismatchError(Exception):
+    pass
+
+
+class ShareCertificateWriteError(Exception):
+    pass

trackio/_vendor/networking.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+import time
+import warnings
+from pathlib import Path
+from urllib.parse import urlparse, urlunparse
+
+import httpx
+
+from trackio._vendor.gradio_exceptions import ShareCertificateWriteError
+from trackio._vendor.tunneling import CERTIFICATE_PATH, Tunnel
+
+GRADIO_API_SERVER = "https://api.gradio.app/v3/tunnel-request"
+GRADIO_SHARE_SERVER_ADDRESS = os.getenv("GRADIO_SHARE_SERVER_ADDRESS")
+
+
+def setup_tunnel(
+    local_host: str,
+    local_port: int,
+    share_token: str,
+    share_server_address: str | None,
+    share_server_tls_certificate: str | None,
+) -> str:
+    share_server_address = (
+        GRADIO_SHARE_SERVER_ADDRESS
+        if share_server_address is None
+        else share_server_address
+    )
+    if share_server_address is None:
+        try:
+            response = httpx.get(GRADIO_API_SERVER, timeout=30)
+            payload = response.json()[0]
+            remote_host, remote_port = payload["host"], int(payload["port"])
+            certificate = payload["root_ca"]
+        except Exception as e:
+            raise RuntimeError(
+                "Could not get share link from Gradio API Server."
+            ) from e
+        try:
+            Path(CERTIFICATE_PATH).parent.mkdir(parents=True, exist_ok=True)
+            with open(CERTIFICATE_PATH, "w") as f:
+                f.write(certificate)
+        except Exception as e:
+            raise ShareCertificateWriteError(
+                f"{e}. This can happen if the current working directory is read-only."
+            ) from e
+        share_server_tls_certificate = CERTIFICATE_PATH
+
+    else:
+        remote_host, remote_port = share_server_address.split(":")
+        remote_port = int(remote_port)
+    tunnel = Tunnel(
+        remote_host,
+        remote_port,
+        local_host,
+        local_port,
+        share_token,
+        share_server_tls_certificate,
+    )
+    address = tunnel.start_tunnel()
+    return address
+
+
+def url_ok(url: str) -> bool:
+    try:
+        for _ in range(5):
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore")
+                r = httpx.head(url, timeout=3, verify=False)
+            if r.status_code in (200, 401, 302, 303, 307):
+                return True
+            time.sleep(0.500)
+    except (ConnectionError, httpx.ConnectError, httpx.TimeoutException):
+        return False
+    return False
+
+
+def normalize_share_url(share_url: str, share_server_protocol: str) -> str:
+    parsed_url = urlparse(share_url)
+    return urlunparse((share_server_protocol,) + parsed_url[1:])

trackio/_vendor/tunneling.py

@@ -0,0 +1,191 @@
+import atexit
+import hashlib
+import os
+import platform
+import re
+import stat
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+from huggingface_hub.constants import HF_HOME
+
+from trackio._vendor.gradio_exceptions import ChecksumMismatchError
+
+VERSION = "0.3"
+CURRENT_TUNNELS: list["Tunnel"] = []
+
+machine = platform.machine()
+if machine == "x86_64":
+    machine = "amd64"
+elif machine == "aarch64":
+    machine = "arm64"
+
+BINARY_REMOTE_NAME = f"frpc_{platform.system().lower()}_{machine.lower()}"
+EXTENSION = ".exe" if os.name == "nt" else ""
+BINARY_URL = f"https://cdn-media.huggingface.co/frpc-gradio-{VERSION}/{BINARY_REMOTE_NAME}{EXTENSION}"
+
+CHECKSUMS = {
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_windows_amd64.exe": "14bc0ea470be5d67d79a07412bd21de8a0a179c6ac1116d7764f68e942dc9ceb",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_amd64": "c791d1f047b41ff5885772fc4bf20b797c6059bbd82abb9e31de15e55d6a57c4",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_arm64": "823ced25104de6dc3c9f4798dbb43f20e681207279e6ab89c40e2176ccbf70cd",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_darwin_amd64": "930f8face3365810ce16689da81b7d1941fda4466225a7bbcbced9a2916a6e15",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_darwin_arm64": "dfac50c690aca459ed5158fad8bfbe99f9282baf4166cf7c410a6673fbc1f327",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_arm": "4b563beb2e36c448cc688174e20b53af38dc1ff2b5e362d4ddd1401f2affbfb7",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_freebsd_386": "cb0a56c764ecf96dd54ed601d240c564f060ee4e58202d65ffca17c1a51ce19c",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_freebsd_amd64": "516d9e6903513869a011ddcd1ec206167ad1eb5dd6640d21057acc258edecbbb",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_386": "4c2f2a48cd71571498c0ac8a4d42a055f22cb7f14b4b5a2b0d584220fd60a283",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mips": "b309ecd594d4f0f7f33e556a80d4b67aef9319c00a8334648a618e56b23cb9e0",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mips64": "0372ef5505baa6f3b64c6295a86541b24b7b0dbe4ef28b344992e21f47624b7b",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_riscv64": "1658eed7e8c14ea76e1d95749d58441ce24147c3d559381832c725c29cfc3df3",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mipsle": "a2aaba16961d3372b79bd7a28976fcd0f0bbaebc2b50d5a7a71af2240747960f",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_windows_386.exe": "721b90550195a83e15f2176d8f85a48d5a25822757cb872e9723d4bccc4e5bb6",
+    "https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_linux_mips64le": "796481edd609f31962b45cc0ab4c9798d040205ae3bf354ed1b72fb432d796b8",
+}
+
+CHUNK_SIZE = 128
+
+BINARY_FILENAME = f"{BINARY_REMOTE_NAME}_v{VERSION}"
+BINARY_FOLDER = Path(HF_HOME) / "trackio" / "frpc"
+BINARY_PATH = str(BINARY_FOLDER / BINARY_FILENAME)
+
+TUNNEL_TIMEOUT_SECONDS = 30
+TUNNEL_ERROR_MESSAGE = (
+    "Could not create share URL. "
+    "Please check the appended log from frpc for more information:"
+)
+
+CERTIFICATE_PATH = ".trackio/certificate.pem"
+
+
+class Tunnel:
+    def __init__(
+        self,
+        remote_host: str,
+        remote_port: int,
+        local_host: str,
+        local_port: int,
+        share_token: str,
+        share_server_tls_certificate: str | None,
+    ):
+        self.proc = None
+        self.url = None
+        self.remote_host = remote_host
+        self.remote_port = remote_port
+        self.local_host = local_host
+        self.local_port = local_port
+        self.share_token = share_token
+        self.share_server_tls_certificate = share_server_tls_certificate
+
+    @staticmethod
+    def download_binary():
+        if not Path(BINARY_PATH).exists():
+            Path(BINARY_FOLDER).mkdir(parents=True, exist_ok=True)
+            resp = httpx.get(BINARY_URL, timeout=30)
+
+            if resp.status_code == 403:
+                raise OSError(
+                    f"Cannot set up a share link as this platform is incompatible. Please "
+                    f"create a GitHub issue with information about your platform: {platform.uname()}"
+                )
+
+            resp.raise_for_status()
+
+            with open(BINARY_PATH, "wb") as file:
+                file.write(resp.content)
+            st = os.stat(BINARY_PATH)
+            os.chmod(BINARY_PATH, st.st_mode | stat.S_IEXEC)
+
+            if BINARY_URL in CHECKSUMS:
+                sha = hashlib.sha256()
+                with open(BINARY_PATH, "rb") as f:
+                    for chunk in iter(lambda: f.read(CHUNK_SIZE * sha.block_size), b""):
+                        sha.update(chunk)
+                calculated_hash = sha.hexdigest()
+
+                if calculated_hash != CHECKSUMS[BINARY_URL]:
+                    raise ChecksumMismatchError()
+
+    def start_tunnel(self) -> str:
+        self.download_binary()
+        self.url = self._start_tunnel(BINARY_PATH)
+        return self.url
+
+    def kill(self):
+        if self.proc is not None:
+            print(f"Killing tunnel {self.local_host}:{self.local_port} <> {self.url}")
+            self.proc.terminate()
+            self.proc = None
+
+    def _start_tunnel(self, binary: str) -> str:
+        CURRENT_TUNNELS.append(self)
+        command = [
+            binary,
+            "http",
+            "-n",
+            self.share_token,
+            "-l",
+            str(self.local_port),
+            "-i",
+            self.local_host,
+            "--uc",
+            "--sd",
+            "random",
+            "--ue",
+            "--server_addr",
+            f"{self.remote_host}:{self.remote_port}",
+            "--disable_log_color",
+        ]
+        if self.share_server_tls_certificate is not None:
+            command.extend(
+                [
+                    "--tls_enable",
+                    "--tls_trusted_ca_file",
+                    self.share_server_tls_certificate,
+                ]
+            )
+        self.proc = subprocess.Popen(
+            command, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        )
+        atexit.register(self.kill)
+        return self._read_url_from_tunnel_stream()
+
+    def _read_url_from_tunnel_stream(self) -> str:
+        start_timestamp = time.time()
+
+        log = []
+        url = ""
+
+        def _raise_tunnel_error():
+            log_text = "\n".join(log)
+            print(log_text, file=sys.stderr)
+            raise ValueError(f"{TUNNEL_ERROR_MESSAGE}\n{log_text}")
+
+        while url == "":
+            if time.time() - start_timestamp >= TUNNEL_TIMEOUT_SECONDS:
+                _raise_tunnel_error()
+
+            assert self.proc is not None  # noqa: S101
+            if self.proc.stdout is None:
+                continue
+
+            line = self.proc.stdout.readline()
+            line = line.decode("utf-8")
+
+            if line == "":
+                continue
+
+            log.append(line.strip())
+
+            if "start proxy success" in line:
+                result = re.search("start proxy success: (.+)\n", line)
+                if result is None:
+                    _raise_tunnel_error()
+                else:
+                    url = result.group(1)
+            elif "login to server failed" in line:
+                _raise_tunnel_error()
+
+        return url

trackio/alerts.py

@@ -0,0 +1,184 @@
+import json
+import logging
+import ssl
+import urllib.request
+from enum import Enum
+
+try:
+    import certifi
+
+    _SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())
+except ImportError:
+    _SSL_CONTEXT = None
+
+logger = logging.getLogger(__name__)
+
+
+class AlertLevel(str, Enum):
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+
+
+ALERT_LEVEL_ORDER = {
+    AlertLevel.INFO: 0,
+    AlertLevel.WARN: 1,
+    AlertLevel.ERROR: 2,
+}
+
+ALERT_COLORS = {
+    AlertLevel.INFO: "\033[94m",
+    AlertLevel.WARN: "\033[93m",
+    AlertLevel.ERROR: "\033[91m",
+}
+RESET_COLOR = "\033[0m"
+
+LEVEL_EMOJI = {
+    AlertLevel.INFO: "ℹ️",
+    AlertLevel.WARN: "⚠️",
+    AlertLevel.ERROR: "🚨",
+}
+
+
+def format_alert_terminal(
+    level: AlertLevel, title: str, text: str | None, step: int | None
+) -> str:
+    color = ALERT_COLORS.get(level, "")
+    step_str = f" (step {step})" if step is not None else ""
+    if text:
+        return f"{color}[TRACKIO {level.value.upper()}]{RESET_COLOR} {title}: {text}{step_str}"
+    return f"{color}[TRACKIO {level.value.upper()}]{RESET_COLOR} {title}{step_str}"
+
+
+def _is_slack_url(url: str) -> bool:
+    return "hooks.slack.com" in url
+
+
+def _is_discord_url(url: str) -> bool:
+    return "discord.com/api/webhooks" in url or "discordapp.com/api/webhooks" in url
+
+
+def _build_slack_payload(
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+) -> dict:
+    emoji = LEVEL_EMOJI.get(level, "")
+    step_str = f"  •  Step {step}" if step is not None else ""
+    header = f"{emoji} *[{level.value.upper()}] {title}*"
+    context = f"Project: {project}  •  Run: {run}{step_str}"
+    blocks = [
+        {"type": "section", "text": {"type": "mrkdwn", "text": header}},
+    ]
+    if text:
+        blocks.append({"type": "section", "text": {"type": "mrkdwn", "text": text}})
+    blocks.append(
+        {"type": "context", "elements": [{"type": "mrkdwn", "text": context}]}
+    )
+    return {"blocks": blocks}
+
+
+def _build_discord_payload(
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+) -> dict:
+    color_map = {
+        AlertLevel.INFO: 3447003,
+        AlertLevel.WARN: 16776960,
+        AlertLevel.ERROR: 15158332,
+    }
+    emoji = LEVEL_EMOJI.get(level, "")
+    step_str = f"  •  Step {step}" if step is not None else ""
+    embed = {
+        "title": f"{emoji} [{level.value.upper()}] {title}",
+        "color": color_map.get(level, 0),
+        "footer": {"text": f"Project: {project}  •  Run: {run}{step_str}"},
+    }
+    if text:
+        embed["description"] = text
+    return {"embeds": [embed]}
+
+
+def _build_generic_payload(
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+    timestamp: str | None,
+) -> dict:
+    return {
+        "level": level.value,
+        "title": title,
+        "text": text,
+        "project": project,
+        "run": run,
+        "step": step,
+        "timestamp": timestamp,
+    }
+
+
+def parse_alert_level(level: AlertLevel | str) -> AlertLevel:
+    if isinstance(level, AlertLevel):
+        return level
+    normalized = level.lower().strip()
+    try:
+        return AlertLevel(normalized)
+    except ValueError as e:
+        allowed = ", ".join(lvl.value for lvl in AlertLevel)
+        raise ValueError(
+            f"Invalid alert level '{level}'. Expected one of: {allowed}."
+        ) from e
+
+
+def resolve_webhook_min_level(
+    webhook_min_level: AlertLevel | str | None,
+) -> AlertLevel | None:
+    if webhook_min_level is None:
+        return None
+    return parse_alert_level(webhook_min_level)
+
+
+def should_send_webhook(
+    level: AlertLevel, webhook_min_level: AlertLevel | None
+) -> bool:
+    if webhook_min_level is None:
+        return True
+    return ALERT_LEVEL_ORDER[level] >= ALERT_LEVEL_ORDER[webhook_min_level]
+
+
+def send_webhook(
+    url: str,
+    level: AlertLevel,
+    title: str,
+    text: str | None,
+    project: str,
+    run: str,
+    step: int | None,
+    timestamp: str | None = None,
+) -> None:
+    if _is_slack_url(url):
+        payload = _build_slack_payload(level, title, text, project, run, step)
+    elif _is_discord_url(url):
+        payload = _build_discord_payload(level, title, text, project, run, step)
+    else:
+        payload = _build_generic_payload(
+            level, title, text, project, run, step, timestamp
+        )
+
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, headers={"Content-Type": "application/json"}
+    )
+    try:
+        urllib.request.urlopen(req, timeout=10, context=_SSL_CONTEXT)
+    except Exception as e:
+        logger.warning(f"Failed to send webhook to {url}: {e}")

trackio/api.py

@@ -0,0 +1,95 @@
+from typing import Iterator
+
+from trackio.sqlite_storage import SQLiteStorage
+
+
+class Run:
+    def __init__(self, project: str, name: str, run_id: str | None = None):
+        self.project = project
+        self.name = name
+        self._id = run_id or name
+        self._config = None
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def config(self) -> dict | None:
+        if self._config is None:
+            self._config = SQLiteStorage.get_run_config(
+                self.project, self.name, run_id=self.id
+            )
+        return self._config
+
+    def alerts(self, level: str | None = None, since: str | None = None) -> list[dict]:
+        return SQLiteStorage.get_alerts(
+            self.project, run_name=self.name, run_id=self.id, level=level, since=since
+        )
+
+    def delete(self) -> bool:
+        return SQLiteStorage.delete_run(self.project, self.name, run_id=self.id)
+
+    def move(self, new_project: str) -> bool:
+        success = SQLiteStorage.move_run(
+            self.project, self.name, new_project, run_id=self.id
+        )
+        if success:
+            self.project = new_project
+        return success
+
+    def rename(self, new_name: str) -> "Run":
+        SQLiteStorage.rename_run(self.project, self.name, new_name, run_id=self.id)
+        self.name = new_name
+        return self
+
+    def __repr__(self) -> str:
+        return f"<Run {self.name} in project {self.project}>"
+
+
+class Runs:
+    def __init__(self, project: str):
+        self.project = project
+        self._runs = None
+
+    def _load_runs(self):
+        if self._runs is None:
+            records = SQLiteStorage.get_run_records(self.project)
+            self._runs = [
+                Run(self.project, str(record["name"]), run_id=str(record["id"]))
+                for record in records
+            ]
+
+    def __iter__(self) -> Iterator[Run]:
+        self._load_runs()
+        return iter(self._runs)
+
+    def __getitem__(self, index: int) -> Run:
+        self._load_runs()
+        return self._runs[index]
+
+    def __len__(self) -> int:
+        self._load_runs()
+        return len(self._runs)
+
+    def __repr__(self) -> str:
+        self._load_runs()
+        return f"<Runs project={self.project} count={len(self._runs)}>"
+
+
+class Api:
+    def runs(self, project: str) -> Runs:
+        if not SQLiteStorage.get_project_db_path(project).exists():
+            raise ValueError(f"Project '{project}' does not exist")
+        return Runs(project)
+
+    def alerts(
+        self,
+        project: str,
+        run: str | None = None,
+        level: str | None = None,
+        since: str | None = None,
+    ) -> list[dict]:
+        if not SQLiteStorage.get_project_db_path(project).exists():
+            raise ValueError(f"Project '{project}' does not exist")
+        return SQLiteStorage.get_alerts(project, run_name=run, level=level, since=since)

trackio/apple_gpu.py

@@ -0,0 +1,253 @@
+import platform
+import subprocess
+import sys
+import threading
+import warnings
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from trackio.run import Run
+
+psutil: Any = None
+PSUTIL_AVAILABLE = False
+_monitor_lock = threading.Lock()
+
+
+def _ensure_psutil():
+    global PSUTIL_AVAILABLE, psutil
+    if PSUTIL_AVAILABLE:
+        return psutil
+    try:
+        import psutil as _psutil
+
+        psutil = _psutil
+        PSUTIL_AVAILABLE = True
+        return psutil
+    except ImportError:
+        raise ImportError(
+            "psutil is required for Apple Silicon monitoring. "
+            "Install it with: pip install psutil"
+        )
+
+
+def is_apple_silicon() -> bool:
+    """Check if running on Apple Silicon (M1/M2/M3/M4)."""
+    if platform.system() != "Darwin":
+        return False
+
+    try:
+        result = subprocess.run(
+            ["sysctl", "-n", "machdep.cpu.brand_string"],
+            capture_output=True,
+            text=True,
+            timeout=1,
+        )
+        cpu_brand = result.stdout.strip()
+        return "Apple" in cpu_brand
+    except Exception:
+        return False
+
+
+def get_gpu_info() -> dict[str, Any]:
+    """Get Apple GPU information using ioreg."""
+    try:
+        result = subprocess.run(
+            ["ioreg", "-r", "-d", "1", "-w", "0", "-c", "IOAccelerator"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+
+        if result.returncode == 0 and result.stdout:
+            lines = result.stdout.strip().split("\n")
+            for line in lines:
+                if "IOAccelerator" in line and "class" in line:
+                    return {"detected": True, "type": "Apple GPU"}
+        else:
+            print("Error collecting Apple GPU info. ioreg stdout was:", file=sys.stderr)
+            print(result.stdout, file=sys.stderr)
+            print("ioreg stderr was:", file=sys.stderr)
+            print(result.stderr, file=sys.stderr)
+
+        result = subprocess.run(
+            ["system_profiler", "SPDisplaysDataType"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+
+        if result.returncode == 0 and "Apple" in result.stdout:
+            for line in result.stdout.split("\n"):
+                if "Chipset Model:" in line:
+                    model = line.split(":")[-1].strip()
+                    return {"detected": True, "type": model}
+
+    except Exception:
+        pass
+
+    return {"detected": False}
+
+
+def apple_gpu_available() -> bool:
+    """
+    Check if Apple GPU monitoring is available.
+
+    Returns True if running on Apple Silicon (M-series chips) and psutil is installed.
+    """
+    try:
+        _ensure_psutil()
+        return is_apple_silicon()
+    except ImportError:
+        return False
+    except Exception:
+        return False
+
+
+def collect_apple_metrics() -> dict:
+    """
+    Collect system metrics for Apple Silicon.
+
+    Returns:
+        Dictionary of system metrics including CPU, memory, and GPU info.
+    """
+    if not PSUTIL_AVAILABLE:
+        try:
+            _ensure_psutil()
+        except ImportError:
+            return {}
+
+    metrics = {}
+
+    try:
+        cpu_percent = psutil.cpu_percent(interval=0.1, percpu=False)
+        metrics["cpu/utilization"] = cpu_percent
+    except Exception:
+        pass
+
+    try:
+        cpu_percents = psutil.cpu_percent(interval=0.1, percpu=True)
+        for i, percent in enumerate(cpu_percents):
+            metrics[f"cpu/{i}/utilization"] = percent
+    except Exception:
+        pass
+
+    try:
+        cpu_freq = psutil.cpu_freq()
+        if cpu_freq:
+            metrics["cpu/frequency"] = cpu_freq.current
+            if cpu_freq.max > 0:
+                metrics["cpu/frequency_max"] = cpu_freq.max
+    except Exception:
+        pass
+
+    try:
+        mem = psutil.virtual_memory()
+        metrics["memory/used"] = mem.used / (1024**3)
+        metrics["memory/total"] = mem.total / (1024**3)
+        metrics["memory/available"] = mem.available / (1024**3)
+        metrics["memory/percent"] = mem.percent
+    except Exception:
+        pass
+
+    try:
+        swap = psutil.swap_memory()
+        metrics["swap/used"] = swap.used / (1024**3)
+        metrics["swap/total"] = swap.total / (1024**3)
+        metrics["swap/percent"] = swap.percent
+    except Exception:
+        pass
+
+    try:
+        sensors_temps = psutil.sensors_temperatures()
+        if sensors_temps:
+            for name, entries in sensors_temps.items():
+                for i, entry in enumerate(entries):
+                    label = entry.label or f"{name}_{i}"
+                    metrics[f"temp/{label}"] = entry.current
+    except Exception:
+        pass
+
+    gpu_info = get_gpu_info()
+    if gpu_info.get("detected"):
+        metrics["gpu/detected"] = 1
+        if "type" in gpu_info:
+            pass
+
+    return metrics
+
+
+class AppleGpuMonitor:
+    def __init__(self, run: "Run", interval: float = 10.0):
+        self._run = run
+        self._interval = interval
+        self._stop_flag = threading.Event()
+        self._thread: "threading.Thread | None" = None
+
+    def start(self):
+        if not is_apple_silicon():
+            warnings.warn(
+                "auto_log_gpu=True but not running on Apple Silicon. "
+                "Apple GPU logging disabled."
+            )
+            return
+
+        if not PSUTIL_AVAILABLE:
+            try:
+                _ensure_psutil()
+            except ImportError:
+                warnings.warn(
+                    "auto_log_gpu=True but psutil not installed. "
+                    "Install with: pip install psutil"
+                )
+                return
+
+        self._thread = threading.Thread(target=self._monitor_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_flag.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+
+    def _monitor_loop(self):
+        while not self._stop_flag.is_set():
+            try:
+                metrics = collect_apple_metrics()
+                if metrics:
+                    self._run.log_system(metrics)
+            except Exception:
+                pass
+
+            self._stop_flag.wait(timeout=self._interval)
+
+
+def log_apple_gpu(run: "Run | None" = None) -> dict:
+    """
+    Log Apple Silicon system metrics to the current or specified run.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+
+    Returns:
+        dict: The system metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_apple_gpu()
+        ```
+    """
+    from trackio import context_vars
+
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_apple_gpu().")
+
+    metrics = collect_apple_metrics()
+    if metrics:
+        run.log_system(metrics)
+    return metrics

trackio/asgi_app.py

@@ -0,0 +1,507 @@
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+import math
+import secrets
+import tempfile
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, get_args, get_origin
+from urllib.parse import unquote
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import FileResponse, JSONResponse, Response, StreamingResponse
+from starlette.routing import Route
+
+from trackio.exceptions import TrackioAPIError
+from trackio.remote_client import HTTP_API_VERSION
+from trackio.utils import on_spaces
+
+logger = logging.getLogger("trackio.asgi_app")
+
+_PACKAGE_JSON_PATH = Path(__file__).parent / "package.json"
+_TRACKIO_PACKAGE_VERSION = json.loads(_PACKAGE_JSON_PATH.read_text())["version"]
+
+
+def _normalize_allowed_file_roots(
+    allowed_file_roots: list[str | Path] | None,
+) -> tuple[Path, ...]:
+    roots = []
+    for root in allowed_file_roots or []:
+        roots.append(Path(root).resolve())
+    return tuple(roots)
+
+
+def _is_allowed_file_path(path: Path, allowed_roots: tuple[Path, ...]) -> bool:
+    resolved_path = path.resolve(strict=False)
+    for root in allowed_roots:
+        try:
+            resolved_path.relative_to(root)
+            return True
+        except ValueError:
+            continue
+    return False
+
+
+def _json_safe(data: Any) -> Any:
+    if data is None or isinstance(data, (str, bool, int)):
+        return data
+    if isinstance(data, float):
+        return data if math.isfinite(data) else None
+    if isinstance(data, dict):
+        return {k: _json_safe(v) for k, v in data.items()}
+    if isinstance(data, (list, tuple)):
+        return [_json_safe(v) for v in data]
+    if hasattr(data, "item"):
+        try:
+            return _json_safe(data.item())
+        except Exception:
+            pass
+    return str(data)
+
+
+def register_uploaded_temp_file(request: Request, file_path: str | Path) -> None:
+    resolved_path = Path(file_path).resolve(strict=False)
+    with request.app.state.uploaded_temp_files_lock:
+        request.app.state.uploaded_temp_files.add(resolved_path)
+
+
+def consume_uploaded_temp_file(request: Request, file_data: Any) -> Path:
+    file_path = file_data.get("path") if isinstance(file_data, dict) else None
+    if not isinstance(file_path, str) or not file_path:
+        raise TrackioAPIError("Expected uploaded file metadata with a valid path.")
+
+    resolved_path = Path(file_path).resolve(strict=False)
+    with request.app.state.uploaded_temp_files_lock:
+        if resolved_path not in request.app.state.uploaded_temp_files:
+            raise TrackioAPIError(
+                "Uploaded file was not created by this Trackio server."
+            )
+        request.app.state.uploaded_temp_files.remove(resolved_path)
+
+    if not resolved_path.is_file():
+        raise TrackioAPIError("Uploaded file is missing.")
+
+    return resolved_path
+
+
+def cleanup_uploaded_temp_file(file_path: str | Path) -> None:
+    try:
+        Path(file_path).unlink(missing_ok=True)
+    except Exception:
+        pass
+
+
+def _invoke_handler(
+    fn: Any,
+    request: Request,
+    args: list[Any] | None = None,
+    kwargs: dict[str, Any] | None = None,
+) -> Any:
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+    positional_args: list[Any] = []
+    keyword_args: dict[str, Any] = {}
+    args = list(args or [])
+    kwargs = dict(kwargs or {})
+    data_index = 0
+
+    for param in params:
+        if param.name == "request":
+            keyword_args["request"] = request
+        elif param.kind == inspect.Parameter.VAR_POSITIONAL:
+            positional_args.extend(args[data_index:])
+            data_index = len(args)
+        elif param.kind == inspect.Parameter.VAR_KEYWORD:
+            keyword_args.update(kwargs)
+            kwargs.clear()
+        elif param.name in kwargs:
+            keyword_args[param.name] = kwargs.pop(param.name)
+        elif param.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        ) and data_index < len(args):
+            positional_args.append(args[data_index])
+            data_index += 1
+        elif param.default is inspect.Signature.empty and param.kind not in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            raise TrackioAPIError(f"Missing required parameter: {param.name}")
+
+    return fn(*positional_args, **keyword_args)
+
+
+async def version_handler(request: Request) -> Response:
+    mcp_enabled = bool(getattr(request.app.state, "mcp_enabled", False))
+    return JSONResponse(
+        {
+            "version": _TRACKIO_PACKAGE_VERSION,
+            "api_version": HTTP_API_VERSION,
+            "api_transport": "http",
+            "mcp_enabled": mcp_enabled,
+            "mcp_path": "/mcp" if mcp_enabled else None,
+        }
+    )
+
+
+def _json_schema_and_python_type(annotation: Any) -> tuple[dict[str, Any], str]:
+    if annotation is inspect.Parameter.empty:
+        return {"type": "object"}, "Any"
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    if origin is not None and args:
+        non_none = tuple(a for a in args if a is not type(None))
+        if len(non_none) == 1 and len(args) > 1:
+            return _json_schema_and_python_type(non_none[0])
+        if origin is list:
+            inner, py_inner = _json_schema_and_python_type(
+                args[0] if args else inspect.Parameter.empty
+            )
+            return {"type": "array", "items": inner}, f"list[{py_inner}]"
+        if origin is dict:
+            return {"type": "object"}, "dict"
+    if annotation in (str, bytes):
+        return {"type": "string"}, "str"
+    if annotation is int:
+        return {"type": "integer"}, "int"
+    if annotation is float:
+        return {"type": "number"}, "float"
+    if annotation is bool:
+        return {"type": "boolean"}, "bool"
+    name = getattr(annotation, "__name__", None)
+    if name:
+        return {"type": "object"}, name
+    return {"type": "object"}, "Any"
+
+
+def build_gradio_api_info(api_registry: dict[str, Any]) -> dict[str, Any]:
+    named_endpoints: dict[str, Any] = {}
+    for name in sorted(api_registry.keys()):
+        fn = api_registry[name]
+        if not callable(fn):
+            continue
+        sig = inspect.signature(fn)
+        parameters: list[dict[str, Any]] = []
+        for pname, param in sig.parameters.items():
+            if pname == "request":
+                continue
+            jtype, pytype = _json_schema_and_python_type(param.annotation)
+            has_default = param.default is not inspect.Parameter.empty
+            parameters.append(
+                {
+                    "label": pname,
+                    "parameter_name": pname,
+                    "parameter_has_default": has_default,
+                    "parameter_default": None if not has_default else param.default,
+                    "type": jtype,
+                    "python_type": {"type": pytype, "description": ""},
+                    "component": "Api",
+                    "example_input": None,
+                }
+            )
+        ret_ann = sig.return_annotation
+        if ret_ann is inspect.Signature.empty:
+            ret_ann = Any
+        rjtype, rpytype = _json_schema_and_python_type(ret_ann)
+        returns = [
+            {
+                "label": "result",
+                "type": rjtype,
+                "python_type": {"type": rpytype, "description": ""},
+                "component": "Api",
+            }
+        ]
+        named_endpoints[f"/{name}"] = {
+            "parameters": parameters,
+            "returns": returns,
+            "api_visibility": "public",
+        }
+    return {"named_endpoints": named_endpoints, "unnamed_endpoints": {}}
+
+
+_MAX_GRADIO_CALL_EVENTS = 256
+
+
+def _hf_token_value_is_unset(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, str) and value.strip() == "":
+        return True
+    return False
+
+
+def _authorization_bearer_token(request: Request) -> str | None:
+    auth = request.headers.get("authorization") or request.headers.get("Authorization")
+    if not auth:
+        return None
+    parts = auth.split()
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        return None
+    tok = parts[1].strip()
+    return tok or None
+
+
+def _maybe_apply_hf_token_from_authorization(
+    request: Request, fn: Any, args: list[Any], kwargs: dict[str, Any]
+) -> None:
+    if not on_spaces():
+        return
+    token = _authorization_bearer_token(request)
+    if not token:
+        return
+    sig = inspect.signature(fn)
+    if "hf_token" not in sig.parameters:
+        return
+    params = [p for p in sig.parameters.values() if p.name != "request"]
+    names = [p.name for p in params]
+    if "hf_token" not in names:
+        return
+    idx = names.index("hf_token")
+    if "hf_token" in kwargs:
+        if _hf_token_value_is_unset(kwargs["hf_token"]):
+            kwargs["hf_token"] = token
+        return
+    if idx < len(args):
+        if _hf_token_value_is_unset(args[idx]):
+            args[idx] = token
+        return
+    kwargs["hf_token"] = token
+
+
+def _store_gradio_call_result(
+    request: Request, event_id: str, api_name: str, data: Any
+) -> None:
+    with request.app.state.gradio_call_events_lock:
+        d = request.app.state.gradio_call_events
+        while len(d) >= _MAX_GRADIO_CALL_EVENTS:
+            d.pop(next(iter(d)))
+        d[event_id] = {"api_name": api_name, "data": data}
+
+
+async def run_api_request(request: Request, api_name: str) -> Response:
+    api_registry = request.app.state.api_registry
+    fn = api_registry.get(api_name)
+    if fn is None:
+        return JSONResponse({"error": f"Unknown API: {api_name}"}, status_code=404)
+
+    try:
+        body = await request.json()
+    except Exception:
+        body = {}
+
+    args: list[Any] = []
+    kwargs: dict[str, Any] = {}
+    if isinstance(body, dict):
+        if "args" in body or "kwargs" in body:
+            args = body.get("args") or []
+            kwargs = body.get("kwargs") or {}
+        elif "data" in body and isinstance(body["data"], list):
+            args = body["data"]
+        else:
+            kwargs = body
+    elif isinstance(body, list):
+        args = body
+    elif body is not None:
+        args = [body]
+
+    if not isinstance(args, list):
+        args = [args]
+    if not isinstance(kwargs, dict):
+        kwargs = {}
+
+    _maybe_apply_hf_token_from_authorization(request, fn, args, kwargs)
+
+    try:
+        result = _invoke_handler(fn, request, args=args, kwargs=kwargs)
+        return JSONResponse({"data": _json_safe(result)})
+    except TrackioAPIError as e:
+        return JSONResponse({"error": str(e)}, status_code=400)
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+async def api_handler(request: Request) -> Response:
+    return await run_api_request(request, request.path_params["api_name"])
+
+
+async def gradio_api_info_handler(request: Request) -> Response:
+    return JSONResponse(
+        build_gradio_api_info(request.app.state.api_registry),
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+async def gradio_call_post_handler(request: Request) -> Response:
+    api_name = request.path_params["api_name"]
+    resp = await run_api_request(request, api_name)
+    if resp.status_code != 200:
+        return resp
+    body = json.loads(bytes(resp.body).decode())
+    event_id = secrets.token_urlsafe(16)
+    _store_gradio_call_result(request, event_id, api_name, body["data"])
+    return JSONResponse({"event_id": event_id})
+
+
+async def gradio_call_poll_handler(request: Request) -> Response:
+    api_name = request.path_params["api_name"]
+    event_id = request.path_params["event_id"]
+    with request.app.state.gradio_call_events_lock:
+        event = request.app.state.gradio_call_events.pop(event_id, None)
+    if event is None:
+        logger.info("gradio_api poll: unknown or expired event_id")
+        return JSONResponse({"error": "Unknown or expired event_id"}, status_code=404)
+    if event.get("api_name") != api_name:
+        logger.info(
+            "gradio_api poll: api_name mismatch (path=%r, stored=%r)",
+            api_name,
+            event.get("api_name"),
+        )
+        with request.app.state.gradio_call_events_lock:
+            d = request.app.state.gradio_call_events
+            while len(d) >= _MAX_GRADIO_CALL_EVENTS:
+                d.pop(next(iter(d)))
+            d[event_id] = event
+        return JSONResponse({"error": "Unknown or expired event_id"}, status_code=404)
+
+    data = event["data"]
+    payload = json.dumps(_json_safe([data]))
+
+    async def sse() -> Any:
+        yield f"event: complete\ndata: {payload}\n\n"
+
+    return StreamingResponse(
+        sse(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-store",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+async def upload_handler(request: Request) -> Response:
+    upload_authorizer = getattr(request.app.state, "upload_authorizer", None)
+    if callable(upload_authorizer):
+        try:
+            upload_authorizer(request)
+        except TrackioAPIError as e:
+            return JSONResponse({"error": str(e)}, status_code=400)
+
+    form = await request.form()
+    uploads = form.getlist("files")
+    saved_paths = []
+    for upload in uploads:
+        suffix = Path(getattr(upload, "filename", "") or "").suffix
+        with tempfile.NamedTemporaryFile(
+            delete=False,
+            prefix="trackio-upload-",
+            suffix=suffix,
+        ) as tmp:
+            tmp.write(await upload.read())
+            register_uploaded_temp_file(request, tmp.name)
+            saved_paths.append(tmp.name)
+    return JSONResponse({"paths": saved_paths})
+
+
+async def gradio_upload_alias_handler(request: Request) -> Response:
+    return await upload_handler(request)
+
+
+_DISALLOWED_FILE_SUFFIXES = frozenset(
+    {".db", ".db-journal", ".db-wal", ".db-shm", ".sqlite", ".sqlite3"}
+)
+
+
+async def file_handler(request: Request) -> Response:
+    fs_path = request.query_params.get("path")
+    if fs_path is None:
+        return Response("Missing path", status_code=400)
+    fp = Path(unquote(fs_path)).resolve(strict=False)
+    if fp.suffix.lower() in _DISALLOWED_FILE_SUFFIXES:
+        return Response("Not found", status_code=404)
+    allowed_roots = getattr(request.app.state, "allowed_file_roots", ())
+    if fp.is_file() and _is_allowed_file_path(fp, allowed_roots):
+        return FileResponse(str(fp))
+    return Response("Not found", status_code=404)
+
+
+def create_trackio_starlette_app(
+    oauth_routes: list[Route],
+    api_registry: dict[str, Any],
+    extra_routes: list[Any] | None = None,
+    mcp_lifespan: Any = None,
+    mcp_enabled: bool = False,
+    allowed_file_roots: list[str | Path] | None = None,
+    upload_authorizer: Callable[[Request], None] | None = None,
+) -> Starlette:
+    routes: list[Any] = list(oauth_routes)
+    routes.extend(
+        [
+            Route("/version", endpoint=version_handler, methods=["GET"]),
+            Route("/api/upload", endpoint=upload_handler, methods=["POST"]),
+            Route("/api/{api_name:str}", endpoint=api_handler, methods=["POST"]),
+            Route("/file", endpoint=file_handler, methods=["GET"]),
+        ]
+    )
+    if on_spaces():
+        routes.extend(
+            [
+                Route(
+                    "/gradio_api/info",
+                    endpoint=gradio_api_info_handler,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/gradio_api/info/",
+                    endpoint=gradio_api_info_handler,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/gradio_api/upload",
+                    endpoint=gradio_upload_alias_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/upload/",
+                    endpoint=gradio_upload_alias_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}",
+                    endpoint=gradio_call_post_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}/",
+                    endpoint=gradio_call_post_handler,
+                    methods=["POST"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}/{event_id:str}",
+                    endpoint=gradio_call_poll_handler,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/gradio_api/call/{api_name:str}/{event_id:str}/",
+                    endpoint=gradio_call_poll_handler,
+                    methods=["GET"],
+                ),
+            ]
+        )
+    routes.extend(extra_routes or [])
+    app = Starlette(routes=routes, lifespan=mcp_lifespan)
+    app.state.api_registry = api_registry
+    app.state.mcp_enabled = mcp_enabled
+    app.state.allowed_file_roots = _normalize_allowed_file_roots(allowed_file_roots)
+    app.state.upload_authorizer = upload_authorizer
+    app.state.uploaded_temp_files = set()
+    app.state.uploaded_temp_files_lock = threading.Lock()
+    if on_spaces():
+        app.state.gradio_call_events = {}
+        app.state.gradio_call_events_lock = threading.Lock()
+    return app

trackio/bucket_storage.py

@@ -0,0 +1,151 @@
+import shutil
+import tempfile
+from pathlib import Path
+
+import huggingface_hub
+
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.utils import MEDIA_DIR, TRACKIO_DIR
+
+
+def create_bucket_if_not_exists(bucket_id: str, private: bool | None = None) -> None:
+    huggingface_hub.create_bucket(bucket_id, private=private, exist_ok=True)
+
+
+def _list_bucket_file_paths(bucket_id: str, prefix: str | None = None) -> list[str]:
+    items = huggingface_hub.list_bucket_tree(bucket_id, prefix=prefix, recursive=True)
+    return [
+        item.path
+        for item in items
+        if getattr(item, "type", None) == "file" and getattr(item, "path", None)
+    ]
+
+
+def download_bucket_to_trackio_dir(bucket_id: str) -> None:
+    TRACKIO_DIR.mkdir(parents=True, exist_ok=True)
+    huggingface_hub.sync_bucket(
+        source=f"hf://buckets/{bucket_id}/trackio",
+        dest=str(TRACKIO_DIR),
+        quiet=True,
+    )
+
+
+def upload_project_to_bucket(project: str, bucket_id: str) -> None:
+    db_path = SQLiteStorage.get_project_db_path(project)
+    if not db_path.exists():
+        raise FileNotFoundError(f"No database found for project '{project}'")
+
+    with SQLiteStorage._get_connection(
+        db_path, configure_pragmas=False, row_factory=None
+    ) as conn:
+        conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+
+    files_to_add = [(str(db_path), f"trackio/{db_path.name}")]
+
+    media_dir = MEDIA_DIR / project
+    if media_dir.exists():
+        for media_file in media_dir.rglob("*"):
+            if media_file.is_file():
+                rel = media_file.relative_to(TRACKIO_DIR)
+                files_to_add.append((str(media_file), f"trackio/{rel}"))
+
+    huggingface_hub.batch_bucket_files(bucket_id, add=files_to_add)
+
+
+def _download_db_from_bucket(
+    project: str, bucket_id: str, dest_path: Path | None = None
+) -> bool:
+    db_filename = SQLiteStorage.get_project_db_filename(project)
+    remote_path = f"trackio/{db_filename}"
+    local_path = dest_path or SQLiteStorage.get_project_db_path(project)
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        huggingface_hub.download_bucket_files(
+            bucket_id,
+            files=[(remote_path, str(local_path))],
+            token=huggingface_hub.utils.get_token(),
+        )
+        return local_path.exists()
+    except Exception:
+        return False
+
+
+def _local_db_has_data(project: str) -> bool:
+    db_path = SQLiteStorage.get_project_db_path(project)
+    if not db_path.exists() or db_path.stat().st_size == 0:
+        return False
+    try:
+        with SQLiteStorage._get_connection(
+            db_path, configure_pragmas=False, row_factory=None
+        ) as conn:
+            count = conn.execute("SELECT COUNT(*) FROM metrics").fetchone()[0]
+            return count > 0
+    except Exception:
+        return False
+
+
+def _export_and_upload_static(
+    project: str,
+    dest_bucket_id: str,
+    db_path: Path,
+    media_dir: Path | None = None,
+) -> None:
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_dir = Path(tmp_dir)
+        SQLiteStorage.export_for_static_space(
+            project, output_dir, db_path_override=db_path
+        )
+
+        if media_dir and media_dir.exists():
+            shutil.copytree(media_dir, output_dir / "media")
+
+        files_to_add = []
+        for f in output_dir.rglob("*"):
+            if f.is_file():
+                rel = f.relative_to(output_dir)
+                files_to_add.append((str(f), str(rel)))
+
+        huggingface_hub.batch_bucket_files(dest_bucket_id, add=files_to_add)
+
+
+def _copy_project_media_between_buckets(
+    source_bucket_id: str, dest_bucket_id: str, project: str
+) -> None:
+    source_media_prefix = f"trackio/media/{project}/"
+    media_to_copy = _list_bucket_file_paths(
+        source_bucket_id, prefix=source_media_prefix
+    )
+    if not media_to_copy:
+        return
+
+    huggingface_hub.copy_files(
+        f"hf://buckets/{source_bucket_id}/{source_media_prefix}",
+        f"hf://buckets/{dest_bucket_id}/media/",
+    )
+
+
+def upload_project_to_bucket_for_static(project: str, bucket_id: str) -> None:
+    if not _local_db_has_data(project):
+        _download_db_from_bucket(project, bucket_id)
+
+    db_path = SQLiteStorage.get_project_db_path(project)
+    _export_and_upload_static(project, bucket_id, db_path, MEDIA_DIR / project)
+
+
+def export_from_bucket_for_static(
+    source_bucket_id: str,
+    dest_bucket_id: str,
+    project: str,
+) -> None:
+    with tempfile.TemporaryDirectory() as work_dir:
+        work_path = Path(work_dir)
+        db_path = work_path / SQLiteStorage.get_project_db_filename(project)
+
+        if not _download_db_from_bucket(project, source_bucket_id, dest_path=db_path):
+            raise FileNotFoundError(
+                f"Could not download database for project '{project}' "
+                f"from bucket '{source_bucket_id}'."
+            )
+
+        _export_and_upload_static(project, dest_bucket_id, db_path)
+        _copy_project_media_between_buckets(source_bucket_id, dest_bucket_id, project)

trackio/cli.py

@@ -0,0 +1,1419 @@
+import argparse
+import os
+
+from trackio import freeze, show, sync
+from trackio.cli_helpers import (
+    error_exit,
+    format_alerts,
+    format_json,
+    format_list,
+    format_metric_values,
+    format_project_summary,
+    format_query_result,
+    format_run_summary,
+    format_snapshot,
+    format_system_metric_names,
+    format_system_metrics,
+)
+from trackio.frontend_config import (
+    TRACKIO_CONFIG_PATH,
+    get_persisted_frontend_dir,
+    set_persisted_frontend_dir,
+    unset_persisted_frontend_dir,
+)
+from trackio.markdown import Markdown
+from trackio.server import get_project_summary, get_run_summary
+from trackio.sqlite_storage import SQLiteStorage
+
+
+def _get_space(args):
+    return getattr(args, "space", None)
+
+
+def _get_remote(args):
+    from trackio.remote_client import RemoteClient
+
+    space = _get_space(args)
+    if not space:
+        return None
+    hf_token = getattr(args, "hf_token", None)
+    return RemoteClient(space, hf_token=hf_token)
+
+
+def _handle_status():
+    print("Reading local Trackio projects...\n")
+    projects = SQLiteStorage.get_projects()
+    if not projects:
+        print("No Trackio projects found.")
+        return
+
+    local_projects = []
+    synced_projects = []
+    unsynced_projects = []
+
+    for project in projects:
+        space_id = SQLiteStorage.get_space_id(project)
+        if space_id is None:
+            local_projects.append(project)
+        elif SQLiteStorage.has_pending_data(project):
+            unsynced_projects.append(project)
+        else:
+            synced_projects.append(project)
+
+    print("Finished reading Trackio projects")
+    if local_projects:
+        print(f"  * {len(local_projects)} local trackio project(s) [OK]")
+    if synced_projects:
+        print(f"  * {len(synced_projects)} trackio project(s) synced to Spaces [OK]")
+    if unsynced_projects:
+        print(
+            f"  * {len(unsynced_projects)} trackio project(s) with unsynced changes [WARNING]:"
+        )
+        for p in unsynced_projects:
+            print(f"    - {p}")
+
+    if unsynced_projects:
+        print(
+            f"\nRun `trackio sync --project {unsynced_projects[0]}` to sync. "
+            "Or run `trackio sync --all` to sync all unsynced changes."
+        )
+
+
+def _handle_sync(args):
+    from trackio.deploy import sync_incremental
+
+    if args.sync_all and args.project:
+        error_exit("Cannot use --all and --project together.")
+    if not args.sync_all and not args.project:
+        error_exit("Must provide either --project or --all.")
+
+    if args.sync_all:
+        projects = SQLiteStorage.get_projects()
+        synced_any = False
+        for project in projects:
+            space_id = SQLiteStorage.get_space_id(project)
+            if space_id and SQLiteStorage.has_pending_data(project):
+                sync_incremental(
+                    project,
+                    space_id,
+                    private=args.private,
+                    pending_only=True,
+                    frontend_dir=args.frontend,
+                )
+                synced_any = True
+        if not synced_any:
+            print("No projects with unsynced data found.")
+    else:
+        space_id = args.space_id
+        if space_id is None:
+            space_id = SQLiteStorage.get_space_id(args.project)
+        sync(
+            project=args.project,
+            space_id=space_id,
+            private=args.private,
+            force=args.force,
+            sdk=args.sdk,
+            frontend_dir=args.frontend,
+        )
+
+
+def _handle_config(args):
+    if args.config_command == "get":
+        frontend_dir = get_persisted_frontend_dir()
+        if frontend_dir is None:
+            print("No Trackio frontend config is set.")
+            print(f"Config file: {TRACKIO_CONFIG_PATH}")
+            return
+        print(f"frontend: {frontend_dir}")
+        print(f"config: {TRACKIO_CONFIG_PATH}")
+        return
+
+    if args.config_command == "set":
+        try:
+            frontend_dir = set_persisted_frontend_dir(args.frontend)
+        except ValueError as e:
+            error_exit(str(e))
+        print(f"Saved Trackio default frontend: {frontend_dir}")
+        print("Reset with `trackio config unset frontend`.")
+        return
+
+    if args.config_command == "unset":
+        removed = unset_persisted_frontend_dir()
+        if removed:
+            print("Removed Trackio default frontend.")
+        else:
+            print("No Trackio default frontend was set.")
+        return
+
+
+def _extract_reports(
+    run: str, logs: list[dict], report_name: str | None = None
+) -> list[dict]:
+    reports = []
+    for log in logs:
+        timestamp = log.get("timestamp")
+        step = log.get("step")
+        for key, value in log.items():
+            if report_name is not None and key != report_name:
+                continue
+            if isinstance(value, dict) and value.get("_type") == Markdown.TYPE:
+                content = value.get("_value")
+                if isinstance(content, str):
+                    reports.append(
+                        {
+                            "run": run,
+                            "report": key,
+                            "step": step,
+                            "timestamp": timestamp,
+                            "content": content,
+                        }
+                    )
+    return reports
+
+
+def _handle_query(args):
+    remote = _get_remote(args)
+    try:
+        if remote:
+            result = remote.predict(args.project, args.sql, api_name="/query_project")
+        else:
+            result = SQLiteStorage.query_project(args.project, args.sql)
+    except FileNotFoundError as e:
+        error_exit(str(e))
+    except ValueError as e:
+        error_exit(str(e))
+
+    if args.json:
+        print(format_json(result))
+    else:
+        print(format_query_result(result))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Trackio CLI")
+    parser.add_argument(
+        "--space",
+        required=False,
+        help="HF Space ID (e.g. 'user/space') or Space URL to query remotely.",
+    )
+    parser.add_argument(
+        "--hf-token",
+        required=False,
+        help="HF token for accessing private Spaces.",
+    )
+    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="default",
+        help="A Gradio Theme to use for the dashboard instead of the default, can be a built-in theme (e.g. 'soft', 'citrus'), or a theme from the Hub (e.g. 'gstaff/xkcd').",
+    )
+    ui_parser.add_argument(
+        "--mcp-server",
+        action="store_true",
+        help="Enable MCP server functionality. The Trackio dashboard will be set up as an MCP server and certain functions will be exposed as MCP tools.",
+    )
+    ui_parser.add_argument(
+        "--footer",
+        action="store_true",
+        default=True,
+        help="Show the Gradio footer. Use --no-footer to hide it.",
+    )
+    ui_parser.add_argument(
+        "--no-footer",
+        dest="footer",
+        action="store_false",
+        help="Hide the Gradio footer.",
+    )
+    ui_parser.add_argument(
+        "--color-palette",
+        required=False,
+        help="Comma-separated list of hex color codes for plot lines (e.g. '#FF0000,#00FF00,#0000FF'). If not provided, the TRACKIO_COLOR_PALETTE environment variable will be used, or the default palette if not set.",
+    )
+    ui_parser.add_argument(
+        "--host",
+        required=False,
+        help="Host to bind the server to (e.g. '0.0.0.0' for remote access). If not provided, defaults to '127.0.0.1' (localhost only).",
+    )
+    ui_parser.add_argument(
+        "--frontend",
+        required=False,
+        help="Custom frontend directory to serve. Must contain index.html.",
+    )
+
+    subparsers.add_parser(
+        "status",
+        help="Show the status of all local Trackio projects, including sync status.",
+    )
+
+    sync_parser = subparsers.add_parser(
+        "sync",
+        help="Sync a local project's database to a Hugging Face Space. If the Space does not exist, it will be created.",
+    )
+    sync_parser.add_argument(
+        "--project",
+        required=False,
+        help="The name of the local project.",
+    )
+    sync_parser.add_argument(
+        "--space-id",
+        required=False,
+        help="The Hugging Face Space ID where the project will be synced (e.g. username/space_id). If not provided, uses the previously-configured Space.",
+    )
+    sync_parser.add_argument(
+        "--all",
+        action="store_true",
+        dest="sync_all",
+        help="Sync all projects that have unsynced data to their configured Spaces.",
+    )
+    sync_parser.add_argument(
+        "--private",
+        action="store_true",
+        help="Make the Hugging Face Space private if creating a new Space. By default, the repo will be public unless the organization's default is private. This value is ignored if the repo already exists.",
+    )
+    sync_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite the existing database without prompting for confirmation.",
+    )
+    sync_parser.add_argument(
+        "--sdk",
+        choices=["gradio", "static"],
+        default="gradio",
+        help="The type of Space to deploy. 'gradio' (default) deploys a live Gradio server. 'static' deploys a static Space that reads from an HF Bucket.",
+    )
+    sync_parser.add_argument(
+        "--frontend",
+        required=False,
+        help="Custom frontend directory to deploy. Must contain index.html.",
+    )
+
+    freeze_parser = subparsers.add_parser(
+        "freeze",
+        help="Create a one-time static Space snapshot from a project's data.",
+    )
+    freeze_parser.add_argument(
+        "--space-id",
+        required=True,
+        help="The source Gradio Space ID (e.g. username/space_id).",
+    )
+    freeze_parser.add_argument(
+        "--project",
+        required=True,
+        help="The name of the project to freeze into a static snapshot.",
+    )
+    freeze_parser.add_argument(
+        "--new-space-id",
+        required=False,
+        help="The Space ID for the new static Space. Defaults to {space_id}_static.",
+    )
+    freeze_parser.add_argument(
+        "--private",
+        action="store_true",
+        help="Make the new static Space private.",
+    )
+    freeze_parser.add_argument(
+        "--frontend",
+        required=False,
+        help="Custom frontend directory to deploy to the frozen static Space.",
+    )
+
+    config_parser = subparsers.add_parser(
+        "config",
+        help="Manage persistent Trackio configuration.",
+    )
+    config_subparsers = config_parser.add_subparsers(
+        dest="config_command",
+        required=True,
+    )
+    config_subparsers.add_parser("get", help="Show current Trackio config.")
+    config_set_parser = config_subparsers.add_parser(
+        "set",
+        help="Set a persistent Trackio config value.",
+    )
+    config_set_parser.add_argument(
+        "key",
+        choices=["frontend"],
+        help="Config key to set.",
+    )
+    config_set_parser.add_argument(
+        "frontend",
+        help="Frontend directory to persist.",
+    )
+    config_unset_parser = config_subparsers.add_parser(
+        "unset",
+        help="Unset a persistent Trackio config value.",
+    )
+    config_unset_parser.add_argument(
+        "key",
+        choices=["frontend"],
+        help="Config key to unset.",
+    )
+
+    list_parser = subparsers.add_parser(
+        "list",
+        help="List projects, runs, or metrics",
+    )
+    list_subparsers = list_parser.add_subparsers(dest="list_type", required=True)
+
+    list_projects_parser = list_subparsers.add_parser(
+        "projects",
+        help="List all projects",
+    )
+    list_projects_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_runs_parser = list_subparsers.add_parser(
+        "runs",
+        help="List runs for a project",
+    )
+    list_runs_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_runs_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_metrics_parser = list_subparsers.add_parser(
+        "metrics",
+        help="List metrics for a run",
+    )
+    list_metrics_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_metrics_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    list_metrics_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_system_metrics_parser = list_subparsers.add_parser(
+        "system-metrics",
+        help="List system metrics for a run",
+    )
+    list_system_metrics_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_system_metrics_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    list_system_metrics_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    list_alerts_parser = list_subparsers.add_parser(
+        "alerts",
+        help="List alerts for a project or run",
+    )
+    list_alerts_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_alerts_parser.add_argument(
+        "--run",
+        required=False,
+        help="Run name (optional)",
+    )
+    list_alerts_parser.add_argument(
+        "--level",
+        required=False,
+        help="Filter by alert level (info, warn, error)",
+    )
+    list_alerts_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+    list_alerts_parser.add_argument(
+        "--since",
+        required=False,
+        help="Only show alerts after this ISO 8601 timestamp",
+    )
+
+    list_reports_parser = list_subparsers.add_parser(
+        "reports",
+        help="List markdown reports for a project or run",
+    )
+    list_reports_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    list_reports_parser.add_argument(
+        "--run",
+        required=False,
+        help="Run name (optional)",
+    )
+    list_reports_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_parser = subparsers.add_parser(
+        "get",
+        help="Get project, run, or metric information",
+    )
+    get_subparsers = get_parser.add_subparsers(dest="get_type", required=True)
+
+    get_project_parser = get_subparsers.add_parser(
+        "project",
+        help="Get project summary",
+    )
+    get_project_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_project_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_run_parser = get_subparsers.add_parser(
+        "run",
+        help="Get run summary",
+    )
+    get_run_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_run_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_run_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_metric_parser = get_subparsers.add_parser(
+        "metric",
+        help="Get metric values for a run",
+    )
+    get_metric_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_metric_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_metric_parser.add_argument(
+        "--metric",
+        required=True,
+        help="Metric name",
+    )
+    get_metric_parser.add_argument(
+        "--step",
+        type=int,
+        required=False,
+        help="Get metric at exactly this step",
+    )
+    get_metric_parser.add_argument(
+        "--around",
+        type=int,
+        required=False,
+        help="Get metrics around this step (use with --window)",
+    )
+    get_metric_parser.add_argument(
+        "--at-time",
+        required=False,
+        help="Get metrics around this ISO 8601 timestamp (use with --window)",
+    )
+    get_metric_parser.add_argument(
+        "--window",
+        type=int,
+        required=False,
+        default=10,
+        help="Window size: ±steps for --around, ±seconds for --at-time (default: 10)",
+    )
+    get_metric_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_snapshot_parser = get_subparsers.add_parser(
+        "snapshot",
+        help="Get all metrics at/around a step or timestamp",
+    )
+    get_snapshot_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_snapshot_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_snapshot_parser.add_argument(
+        "--step",
+        type=int,
+        required=False,
+        help="Get all metrics at exactly this step",
+    )
+    get_snapshot_parser.add_argument(
+        "--around",
+        type=int,
+        required=False,
+        help="Get all metrics around this step (use with --window)",
+    )
+    get_snapshot_parser.add_argument(
+        "--at-time",
+        required=False,
+        help="Get all metrics around this ISO 8601 timestamp (use with --window)",
+    )
+    get_snapshot_parser.add_argument(
+        "--window",
+        type=int,
+        required=False,
+        default=10,
+        help="Window size: ±steps for --around, ±seconds for --at-time (default: 10)",
+    )
+    get_snapshot_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_system_metric_parser = get_subparsers.add_parser(
+        "system-metric",
+        help="Get system metric values for a run",
+    )
+    get_system_metric_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_system_metric_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_system_metric_parser.add_argument(
+        "--metric",
+        required=False,
+        help="System metric name (optional, if not provided returns all system metrics)",
+    )
+    get_system_metric_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    get_alerts_parser = get_subparsers.add_parser(
+        "alerts",
+        help="Get alerts for a project or run",
+    )
+    get_alerts_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_alerts_parser.add_argument(
+        "--run",
+        required=False,
+        help="Run name (optional)",
+    )
+    get_alerts_parser.add_argument(
+        "--level",
+        required=False,
+        help="Filter by alert level (info, warn, error)",
+    )
+    get_alerts_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+    get_alerts_parser.add_argument(
+        "--since",
+        required=False,
+        help="Only show alerts after this ISO 8601 timestamp",
+    )
+
+    get_report_parser = get_subparsers.add_parser(
+        "report",
+        help="Get markdown report entries for a run",
+    )
+    get_report_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    get_report_parser.add_argument(
+        "--run",
+        required=True,
+        help="Run name",
+    )
+    get_report_parser.add_argument(
+        "--report",
+        required=True,
+        help="Report metric name",
+    )
+    get_report_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    query_parser = subparsers.add_parser(
+        "query",
+        help="Run a read-only SQL query against a project database",
+    )
+    query_subparsers = query_parser.add_subparsers(dest="query_type", required=True)
+    query_project_parser = query_subparsers.add_parser(
+        "project",
+        help="Run a read-only SQL query against a project's SQLite database",
+    )
+    query_project_parser.add_argument(
+        "--project",
+        required=True,
+        help="Project name",
+    )
+    query_project_parser.add_argument(
+        "--sql",
+        required=True,
+        help="Read-only SQL query to execute",
+    )
+    query_project_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+
+    skills_parser = subparsers.add_parser(
+        "skills",
+        help="Manage Trackio skills for AI coding assistants",
+    )
+    skills_subparsers = skills_parser.add_subparsers(
+        dest="skills_action", required=True
+    )
+    skills_add_parser = skills_subparsers.add_parser(
+        "add",
+        help="Download and install the Trackio skill for an AI assistant",
+    )
+    skills_add_parser.add_argument(
+        "--cursor",
+        action="store_true",
+        help="Install for Cursor",
+    )
+    skills_add_parser.add_argument(
+        "--claude",
+        action="store_true",
+        help="Install for Claude Code",
+    )
+    skills_add_parser.add_argument(
+        "--codex",
+        action="store_true",
+        help="Install for Codex",
+    )
+    skills_add_parser.add_argument(
+        "--opencode",
+        action="store_true",
+        help="Install for OpenCode",
+    )
+    skills_add_parser.add_argument(
+        "--global",
+        dest="global_",
+        action="store_true",
+        help="Install globally (user-level) instead of in the current project directory",
+    )
+    skills_add_parser.add_argument(
+        "--dest",
+        type=str,
+        required=False,
+        help="Install into a custom destination (path to skills directory)",
+    )
+    skills_add_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing skill if it already exists",
+    )
+
+    args, unknown_args = parser.parse_known_args()
+    if unknown_args:
+        trailing_global_parser = argparse.ArgumentParser(add_help=False)
+        trailing_global_parser.add_argument("--space", required=False)
+        trailing_global_parser.add_argument("--hf-token", required=False)
+        trailing_globals, remaining_unknown = trailing_global_parser.parse_known_args(
+            unknown_args
+        )
+        if remaining_unknown:
+            parser.error(f"unrecognized arguments: {' '.join(remaining_unknown)}")
+        if trailing_globals.space is not None:
+            args.space = trailing_globals.space
+        if trailing_globals.hf_token is not None:
+            args.hf_token = trailing_globals.hf_token
+
+    if args.command in ("show", "status", "sync", "freeze", "skills") and _get_space(
+        args
+    ):
+        error_exit(
+            f"The '{args.command}' command does not support --space (remote mode)."
+        )
+
+    if args.command == "show":
+        color_palette = None
+        if args.color_palette:
+            color_palette = [color.strip() for color in args.color_palette.split(",")]
+        show(
+            project=args.project,
+            theme=args.theme,
+            mcp_server=args.mcp_server,
+            footer=args.footer,
+            color_palette=color_palette,
+            host=args.host,
+            frontend_dir=args.frontend,
+        )
+    elif args.command == "status":
+        _handle_status()
+    elif args.command == "sync":
+        _handle_sync(args)
+    elif args.command == "freeze":
+        freeze(
+            space_id=args.space_id,
+            project=args.project,
+            new_space_id=args.new_space_id,
+            private=args.private,
+            frontend_dir=args.frontend,
+        )
+    elif args.command == "config":
+        _handle_config(args)
+    elif args.command == "list":
+        remote = _get_remote(args)
+        if args.list_type == "projects":
+            if remote:
+                projects = remote.predict(api_name="/get_all_projects")
+            else:
+                projects = SQLiteStorage.get_projects()
+            if args.json:
+                print(format_json({"projects": projects}))
+            else:
+                print(format_list(projects, "Projects"))
+        elif args.list_type == "runs":
+            if remote:
+                run_records = remote.predict(
+                    args.project, api_name="/get_runs_for_project"
+                )
+                runs = [r["name"] if isinstance(r, dict) else r for r in run_records]
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+            if args.json:
+                print(format_json({"project": args.project, "runs": runs}))
+            else:
+                print(format_list(runs, f"Runs in '{args.project}'"))
+        elif args.list_type == "metrics":
+            if remote:
+                metrics = remote.predict(
+                    args.project, args.run, api_name="/get_metrics_for_run"
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                metrics = SQLiteStorage.get_all_metrics_for_run(args.project, args.run)
+            if args.json:
+                print(
+                    format_json(
+                        {"project": args.project, "run": args.run, "metrics": metrics}
+                    )
+                )
+            else:
+                print(
+                    format_list(
+                        metrics, f"Metrics for '{args.run}' in '{args.project}'"
+                    )
+                )
+        elif args.list_type == "system-metrics":
+            if remote:
+                system_metrics = remote.predict(
+                    args.project, args.run, api_name="/get_system_metrics_for_run"
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                system_metrics = SQLiteStorage.get_all_system_metrics_for_run(
+                    args.project, args.run
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "system_metrics": system_metrics,
+                        }
+                    )
+                )
+            else:
+                print(format_system_metric_names(system_metrics))
+        elif args.list_type == "alerts":
+            if remote:
+                alerts = remote.predict(
+                    args.project,
+                    args.run,
+                    args.level,
+                    args.since,
+                    api_name="/get_alerts",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                alerts = SQLiteStorage.get_alerts(
+                    args.project,
+                    run_name=args.run,
+                    level=args.level,
+                    since=args.since,
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "level": args.level,
+                            "since": args.since,
+                            "alerts": alerts,
+                        }
+                    )
+                )
+            else:
+                print(format_alerts(alerts))
+        elif args.list_type == "reports":
+            if remote:
+                run_records = remote.predict(
+                    args.project, api_name="/get_runs_for_project"
+                )
+                runs = [r["name"] if isinstance(r, dict) else r for r in run_records]
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+            if args.run and args.run not in runs:
+                error_exit(f"Run '{args.run}' not found in project '{args.project}'.")
+
+            target_runs = [args.run] if args.run else runs
+            all_reports = []
+            for run_name in target_runs:
+                if remote:
+                    logs = remote.predict(args.project, run_name, api_name="/get_logs")
+                else:
+                    logs = SQLiteStorage.get_logs(args.project, run_name)
+                all_reports.extend(_extract_reports(run_name, logs))
+
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "reports": all_reports,
+                        }
+                    )
+                )
+            else:
+                report_lines = [
+                    f"{entry['run']} | {entry['report']} | step={entry['step']} | {entry['timestamp']}"
+                    for entry in all_reports
+                ]
+                if args.run:
+                    print(
+                        format_list(
+                            report_lines,
+                            f"Reports for '{args.run}' in '{args.project}'",
+                        )
+                    )
+                else:
+                    print(format_list(report_lines, f"Reports in '{args.project}'"))
+    elif args.command == "get":
+        remote = _get_remote(args)
+        if args.get_type == "project":
+            if remote:
+                summary = remote.predict(args.project, api_name="/get_project_summary")
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                summary = get_project_summary(args.project)
+            if args.json:
+                print(format_json(summary))
+            else:
+                print(format_project_summary(summary))
+        elif args.get_type == "run":
+            if remote:
+                summary = remote.predict(
+                    args.project, args.run, api_name="/get_run_summary"
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                summary = get_run_summary(args.project, args.run)
+            if args.json:
+                print(format_json(summary))
+            else:
+                print(format_run_summary(summary))
+        elif args.get_type == "metric":
+            at_time = getattr(args, "at_time", None)
+            if remote:
+                values = remote.predict(
+                    args.project,
+                    args.run,
+                    args.metric,
+                    args.step,
+                    args.around,
+                    at_time,
+                    args.window,
+                    api_name="/get_metric_values",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                metrics = SQLiteStorage.get_all_metrics_for_run(args.project, args.run)
+                if args.metric not in metrics:
+                    error_exit(
+                        f"Metric '{args.metric}' not found in run '{args.run}' of project '{args.project}'."
+                    )
+                values = SQLiteStorage.get_metric_values(
+                    args.project,
+                    args.run,
+                    args.metric,
+                    step=args.step,
+                    around_step=args.around,
+                    at_time=at_time,
+                    window=args.window,
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "metric": args.metric,
+                            "values": values,
+                        }
+                    )
+                )
+            else:
+                print(format_metric_values(values))
+        elif args.get_type == "snapshot":
+            if not args.step and not args.around and not getattr(args, "at_time", None):
+                error_exit(
+                    "Provide --step, --around (with --window), or --at-time (with --window)."
+                )
+            at_time = getattr(args, "at_time", None)
+            if remote:
+                snapshot = remote.predict(
+                    args.project,
+                    args.run,
+                    args.step,
+                    args.around,
+                    at_time,
+                    args.window,
+                    api_name="/get_snapshot",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                snapshot = SQLiteStorage.get_snapshot(
+                    args.project,
+                    args.run,
+                    step=args.step,
+                    around_step=args.around,
+                    at_time=at_time,
+                    window=args.window,
+                )
+            if args.json:
+                result = {
+                    "project": args.project,
+                    "run": args.run,
+                    "metrics": snapshot,
+                }
+                if args.step is not None:
+                    result["step"] = args.step
+                if args.around is not None:
+                    result["around"] = args.around
+                    result["window"] = args.window
+                if at_time is not None:
+                    result["at_time"] = at_time
+                    result["window"] = args.window
+                print(format_json(result))
+            else:
+                print(format_snapshot(snapshot))
+        elif args.get_type == "system-metric":
+            if remote:
+                system_metrics = remote.predict(
+                    args.project, args.run, api_name="/get_system_logs"
+                )
+                if args.metric:
+                    all_system_metric_names = remote.predict(
+                        args.project,
+                        args.run,
+                        api_name="/get_system_metrics_for_run",
+                    )
+                    if args.metric not in all_system_metric_names:
+                        error_exit(
+                            f"System metric '{args.metric}' not found in run '{args.run}' of project '{args.project}'."
+                        )
+                    filtered_metrics = [
+                        {
+                            k: v
+                            for k, v in entry.items()
+                            if k == "timestamp" or k == args.metric
+                        }
+                        for entry in system_metrics
+                        if args.metric in entry
+                    ]
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "metric": args.metric,
+                                    "values": filtered_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(filtered_metrics))
+                else:
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "system_metrics": system_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(system_metrics))
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                if args.metric:
+                    system_metrics = SQLiteStorage.get_system_logs(
+                        args.project, args.run
+                    )
+                    all_system_metric_names = (
+                        SQLiteStorage.get_all_system_metrics_for_run(
+                            args.project, args.run
+                        )
+                    )
+                    if args.metric not in all_system_metric_names:
+                        error_exit(
+                            f"System metric '{args.metric}' not found in run '{args.run}' of project '{args.project}'."
+                        )
+                    filtered_metrics = [
+                        {
+                            k: v
+                            for k, v in entry.items()
+                            if k == "timestamp" or k == args.metric
+                        }
+                        for entry in system_metrics
+                        if args.metric in entry
+                    ]
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "metric": args.metric,
+                                    "values": filtered_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(filtered_metrics))
+                else:
+                    system_metrics = SQLiteStorage.get_system_logs(
+                        args.project, args.run
+                    )
+                    if args.json:
+                        print(
+                            format_json(
+                                {
+                                    "project": args.project,
+                                    "run": args.run,
+                                    "system_metrics": system_metrics,
+                                }
+                            )
+                        )
+                    else:
+                        print(format_system_metrics(system_metrics))
+        elif args.get_type == "alerts":
+            if remote:
+                alerts = remote.predict(
+                    args.project,
+                    args.run,
+                    args.level,
+                    args.since,
+                    api_name="/get_alerts",
+                )
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                alerts = SQLiteStorage.get_alerts(
+                    args.project,
+                    run_name=args.run,
+                    level=args.level,
+                    since=args.since,
+                )
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "level": args.level,
+                            "since": args.since,
+                            "alerts": alerts,
+                        }
+                    )
+                )
+            else:
+                print(format_alerts(alerts))
+        elif args.get_type == "report":
+            if remote:
+                logs = remote.predict(args.project, args.run, api_name="/get_logs")
+            else:
+                db_path = SQLiteStorage.get_project_db_path(args.project)
+                if not db_path.exists():
+                    error_exit(f"Project '{args.project}' not found.")
+                runs = SQLiteStorage.get_runs(args.project)
+                if args.run not in runs:
+                    error_exit(
+                        f"Run '{args.run}' not found in project '{args.project}'."
+                    )
+                logs = SQLiteStorage.get_logs(args.project, args.run)
+
+            reports = _extract_reports(args.run, logs, report_name=args.report)
+            if not reports:
+                error_exit(
+                    f"Report '{args.report}' not found in run '{args.run}' of project '{args.project}'."
+                )
+
+            if args.json:
+                print(
+                    format_json(
+                        {
+                            "project": args.project,
+                            "run": args.run,
+                            "report": args.report,
+                            "values": reports,
+                        }
+                    )
+                )
+            else:
+                output = []
+                for idx, entry in enumerate(reports, start=1):
+                    output.append(
+                        f"Entry {idx} | step={entry['step']} | timestamp={entry['timestamp']}"
+                    )
+                    output.append(entry["content"])
+                    if idx < len(reports):
+                        output.append("-" * 80)
+                print("\n".join(output))
+    elif args.command == "query":
+        if args.query_type == "project":
+            _handle_query(args)
+    elif args.command == "skills":
+        if args.skills_action == "add":
+            _handle_skills_add(args)
+    else:
+        parser.print_help()
+
+
+def _handle_skills_add(args):
+    import shutil
+    from pathlib import Path
+
+    CENTRAL_LOCAL = Path(".agents/skills")
+    CENTRAL_GLOBAL = Path("~/.agents/skills")
+    CLAUDE_LOCAL = Path(".claude/skills")
+    CLAUDE_GLOBAL = Path("~/.claude/skills")
+
+    SKILL_ID = "trackio"
+    GITHUB_RAW = "https://raw.githubusercontent.com/gradio-app/trackio/main"
+    SKILL_PREFIX = ".agents/skills/trackio"
+    SKILL_FILES = [
+        "SKILL.md",
+        "alerts.md",
+        "logging_metrics.md",
+        "retrieving_metrics.md",
+        "storage_schema.md",
+    ]
+
+    if not (args.cursor or args.claude or args.codex or args.opencode or args.dest):
+        error_exit(
+            "Pick a destination via --cursor, --claude, --codex, --opencode, or --dest."
+        )
+
+    def download(url: str) -> str:
+        from huggingface_hub.utils import get_session
+
+        try:
+            response = get_session().get(url)
+            response.raise_for_status()
+        except Exception as e:
+            error_exit(
+                f"Failed to download {url}\n{e}\n\n"
+                "Make sure you have internet access. The skill files are fetched from "
+                "the Trackio GitHub repository."
+            )
+        return response.text
+
+    def remove_existing(path: Path, force: bool):
+        if not (path.exists() or path.is_symlink()):
+            return
+        if not force:
+            error_exit(
+                f"Skill already exists at {path}.\nRe-run with --force to overwrite."
+            )
+        if path.is_dir() and not path.is_symlink():
+            shutil.rmtree(path)
+        else:
+            path.unlink()
+
+    def install_to(skills_dir: Path, force: bool) -> Path:
+        skills_dir = skills_dir.expanduser().resolve()
+        skills_dir.mkdir(parents=True, exist_ok=True)
+        dest = skills_dir / SKILL_ID
+        remove_existing(dest, force)
+        dest.mkdir()
+        for fname in SKILL_FILES:
+            content = download(f"{GITHUB_RAW}/{SKILL_PREFIX}/{fname}")
+            (dest / fname).write_text(content, encoding="utf-8")
+        return dest
+
+    def create_symlink(
+        agent_skills_dir: Path, central_skill_path: Path, force: bool
+    ) -> Path:
+        agent_skills_dir = agent_skills_dir.expanduser().resolve()
+        agent_skills_dir.mkdir(parents=True, exist_ok=True)
+        link_path = agent_skills_dir / SKILL_ID
+        remove_existing(link_path, force)
+        link_path.symlink_to(os.path.relpath(central_skill_path, agent_skills_dir))
+        return link_path
+
+    global_targets = {
+        "cursor": Path("~/.cursor/skills"),
+        "claude": CLAUDE_GLOBAL,
+        "codex": Path("~/.codex/skills"),
+        "opencode": Path("~/.opencode/skills"),
+    }
+    local_targets = {
+        "cursor": Path(".cursor/skills"),
+        "claude": CLAUDE_LOCAL,
+        "codex": Path(".codex/skills"),
+        "opencode": Path(".opencode/skills"),
+    }
+    targets_dict = global_targets if args.global_ else local_targets
+
+    if args.dest:
+        if args.cursor or args.claude or args.codex or args.opencode or args.global_:
+            error_exit("--dest cannot be combined with agent flags or --global.")
+        skill_dest = install_to(Path(args.dest), args.force)
+        print(f"Installed '{SKILL_ID}' to {skill_dest}")
+        return
+
+    agent_targets = []
+    if args.cursor:
+        agent_targets.append(targets_dict["cursor"])
+    if args.claude:
+        agent_targets.append(targets_dict["claude"])
+    if args.codex:
+        agent_targets.append(targets_dict["codex"])
+    if args.opencode:
+        agent_targets.append(targets_dict["opencode"])
+
+    central_path = CENTRAL_GLOBAL if args.global_ else CENTRAL_LOCAL
+    central_skill_path = install_to(central_path, args.force)
+    print(f"Installed '{SKILL_ID}' to central location: {central_skill_path}")
+
+    for agent_target in agent_targets:
+        link_path = create_symlink(agent_target, central_skill_path, args.force)
+        print(f"Created symlink: {link_path}")
+
+
+if __name__ == "__main__":
+    main()

trackio/cli_helpers.py

@@ -0,0 +1,204 @@
+import json
+import sys
+from typing import Any
+
+
+def format_json(data: Any) -> str:
+    """Format data as JSON."""
+    return json.dumps(data, indent=2)
+
+
+def format_list(items: list[str], title: str | None = None) -> str:
+    """Format a list of items in human-readable format."""
+    if not items:
+        return f"No {title.lower() if title else 'items'} found."
+
+    output = []
+    if title:
+        output.append(f"{title}:")
+
+    for item in items:
+        output.append(f"  - {item}")
+
+    return "\n".join(output)
+
+
+def format_project_summary(summary: dict) -> str:
+    """Format project summary in human-readable format."""
+    output = [f"Project: {summary['project']}"]
+    output.append(f"Number of runs: {summary['num_runs']}")
+
+    if summary["runs"]:
+        output.append("\nRuns:")
+        for run in summary["runs"]:
+            output.append(f"  - {run}")
+    else:
+        output.append("\nNo runs found.")
+
+    if summary.get("last_activity"):
+        output.append(f"\nLast activity (max step): {summary['last_activity']}")
+
+    return "\n".join(output)
+
+
+def format_run_summary(summary: dict) -> str:
+    """Format run summary in human-readable format."""
+    output = [f"Project: {summary['project']}"]
+    output.append(f"Run: {summary['run']}")
+    output.append(f"Number of logs: {summary['num_logs']}")
+
+    if summary.get("last_step") is not None:
+        output.append(f"Last step: {summary['last_step']}")
+
+    if summary.get("metrics"):
+        output.append("\nMetrics:")
+        for metric in summary["metrics"]:
+            output.append(f"  - {metric}")
+    else:
+        output.append("\nNo metrics found.")
+
+    config = summary.get("config")
+    if config:
+        output.append("\nConfig:")
+        config_display = {k: v for k, v in config.items() if not k.startswith("_")}
+        if config_display:
+            for key, value in config_display.items():
+                output.append(f"  {key}: {value}")
+        else:
+            output.append("  (no config)")
+    else:
+        output.append("\nConfig: (no config)")
+
+    return "\n".join(output)
+
+
+def format_metric_values(values: list[dict]) -> str:
+    """Format metric values in human-readable format."""
+    if not values:
+        return "No metric values found."
+
+    output = [f"Found {len(values)} value(s):\n"]
+    output.append("Step | Timestamp | Value")
+    output.append("-" * 50)
+
+    for value in values:
+        step = value.get("step", "N/A")
+        timestamp = value.get("timestamp", "N/A")
+        val = value.get("value", "N/A")
+        output.append(f"{step} | {timestamp} | {val}")
+
+    return "\n".join(output)
+
+
+def format_system_metrics(metrics: list[dict]) -> str:
+    """Format system metrics in human-readable format."""
+    if not metrics:
+        return "No system metrics found."
+
+    output = [f"Found {len(metrics)} system metric entry/entries:\n"]
+
+    for i, entry in enumerate(metrics):
+        timestamp = entry.get("timestamp", "N/A")
+        output.append(f"\nEntry {i + 1} (Timestamp: {timestamp}):")
+        for key, value in entry.items():
+            if key != "timestamp":
+                output.append(f"  {key}: {value}")
+
+    return "\n".join(output)
+
+
+def format_system_metric_names(names: list[str]) -> str:
+    """Format system metric names in human-readable format."""
+    return format_list(names, "System Metrics")
+
+
+def format_snapshot(snapshot: dict[str, list[dict]]) -> str:
+    """Format a metrics snapshot in human-readable format."""
+    if not snapshot:
+        return "No metrics found in the specified range."
+
+    output = []
+    for metric_name, values in sorted(snapshot.items()):
+        output.append(f"\n{metric_name}:")
+        output.append("  Step | Timestamp | Value")
+        output.append("  " + "-" * 48)
+        for v in values:
+            step = v.get("step", "N/A")
+            ts = v.get("timestamp", "N/A")
+            val = v.get("value", "N/A")
+            output.append(f"  {step} | {ts} | {val}")
+
+    return "\n".join(output)
+
+
+def format_alerts(alerts: list[dict]) -> str:
+    """Format alerts in human-readable format."""
+    if not alerts:
+        return "No alerts found."
+
+    output = [f"Found {len(alerts)} alert(s):\n"]
+    output.append("Timestamp | Run | Level | Title | Text | Step")
+    output.append("-" * 80)
+
+    for a in alerts:
+        ts = a.get("timestamp", "N/A")
+        run = a.get("run", "N/A")
+        level = a.get("level", "N/A").upper()
+        title = a.get("title", "")
+        text = a.get("text", "") or ""
+        step = a.get("step", "N/A")
+        output.append(f"{ts} | {run} | {level} | {title} | {text} | {step}")
+
+    return "\n".join(output)
+
+
+def format_query_result(result: dict[str, Any]) -> str:
+    """Format SQL query results in human-readable format."""
+    columns = result.get("columns", [])
+    rows = result.get("rows", [])
+    row_count = result.get("row_count", 0)
+
+    if not columns:
+        return f"Query returned {row_count} row(s)."
+
+    rendered_rows = []
+    for row in rows:
+        rendered_rows.append(
+            [
+                "" if row.get(column) is None else str(row.get(column))
+                for column in columns
+            ]
+        )
+
+    widths = []
+    for idx, column in enumerate(columns):
+        cell_width = max(
+            (len(rendered_row[idx]) for rendered_row in rendered_rows), default=0
+        )
+        widths.append(max(len(column), cell_width))
+
+    header = " | ".join(
+        column.ljust(width) for column, width in zip(columns, widths, strict=False)
+    )
+    separator = "-+-".join("-" * width for width in widths)
+    output = [f"Query returned {row_count} row(s).", header, separator]
+
+    if not rendered_rows:
+        output.append("(no rows)")
+        return "\n".join(output)
+
+    for rendered_row in rendered_rows:
+        output.append(
+            " | ".join(
+                value.ljust(width)
+                for value, width in zip(rendered_row, widths, strict=False)
+            )
+        )
+
+    return "\n".join(output)
+
+
+def error_exit(message: str, code: int = 1) -> None:
+    """Print error message and exit."""
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(code)

trackio/commit_scheduler.py

@@ -0,0 +1,310 @@
+# Originally copied from https://github.com/huggingface/huggingface_hub/blob/d0a948fc2a32ed6e557042a95ef3e4af97ec4a7c/src/huggingface_hub/_commit_scheduler.py
+
+import atexit
+import logging
+import time
+from concurrent.futures import Future
+from dataclasses import dataclass
+from pathlib import Path
+from threading import Lock, Thread
+from typing import Callable, Dict, List, 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: str | None = None,
+        repo_type: str | None = None,
+        revision: str | None = None,
+        private: bool | None = None,
+        token: str | None = None,
+        allow_patterns: list[str] | str | None = None,
+        ignore_patterns: list[str] | str | None = None,
+        squash_history: bool = False,
+        hf_api: HfApi | None = None,
+        on_before_commit: Callable[[], None] | 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) -> CommitInfo | None:
+        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) -> CommitInfo | None:
+        """
+        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

trackio/context_vars.py

@@ -0,0 +1,21 @@
+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
+)
+current_space_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_space_id", default=None
+)
+current_server_write_token: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_server_write_token", default=None
+)

trackio/deploy.py

@@ -0,0 +1,1252 @@
+import importlib.metadata
+import io
+import json as json_mod
+import os
+import shutil
+import sys
+import tempfile
+import threading
+import time
+import warnings
+from collections import Counter
+from importlib.resources import files
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import httpx
+import huggingface_hub
+from gradio_client import handle_file
+from httpx import ReadTimeout
+from huggingface_hub import Volume
+from huggingface_hub.errors import (
+    BucketNotFoundError,
+    HfHubHTTPError,
+    RepositoryNotFoundError,
+)
+
+import trackio
+from trackio.bucket_storage import (
+    create_bucket_if_not_exists,
+    export_from_bucket_for_static,
+    upload_project_to_bucket,
+    upload_project_to_bucket_for_static,
+)
+from trackio.frontend_config import resolve_frontend_dir
+from trackio.remote_client import RemoteClient
+from trackio.sqlite_storage import SQLiteStorage
+from trackio.utils import (
+    MEDIA_DIR,
+    get_or_create_project_hash,
+    on_spaces,
+    preprocess_space_and_dataset_ids,
+)
+
+SPACE_HOST_URL = "https://{user_name}-{space_name}.hf.space/"
+SPACE_URL = "https://huggingface.co/spaces/{space_id}"
+_BOLD_ORANGE = "\033[1m\033[38;5;208m"
+_RESET = "\033[0m"
+
+
+def raise_if_space_is_frozen_for_logging(space_id: str) -> None:
+    try:
+        info = huggingface_hub.HfApi().space_info(space_id)
+    except RepositoryNotFoundError:
+        return
+    if getattr(info, "sdk", None) == "static":
+        raise RuntimeError(
+            f"Cannot log to Hugging Face Space '{space_id}' because it has been frozen "
+            f"(it uses the static SDK: a read-only dashboard with no live Trackio server).\n\n"
+            f"Use a different space_id for training, or create a new Gradio Trackio Space. "
+            f"Freezing converts a live Gradio Space to static after a run; a frozen Space "
+            f'cannot accept new logs. See trackio.sync(..., sdk="static") in the Trackio docs.'
+        )
+
+
+def _readme_linked_hub_yaml(dataset_id: str | None) -> str:
+    if dataset_id is not None:
+        return f"datasets:\n - {dataset_id}\n"
+    return ""
+
+
+_CUSTOM_SPACE_FRONTEND_DIR = "trackio_custom_frontend"
+
+
+def _space_app_py(frontend_dir: str | None = None) -> str:
+    if frontend_dir is None:
+        return "import trackio\ntrackio.show()\n"
+    return f'import trackio\ntrackio.show(frontend_dir="{frontend_dir}")\n'
+
+
+def _upload_frontend_folder(
+    hf_api: huggingface_hub.HfApi,
+    *,
+    repo_id: str,
+    repo_type: str,
+    folder_path: str | Path,
+    path_in_repo: str | None = None,
+) -> None:
+    kwargs = {
+        "repo_id": repo_id,
+        "repo_type": repo_type,
+        "folder_path": str(folder_path),
+    }
+    if path_in_repo is not None:
+        kwargs["path_in_repo"] = path_in_repo
+    hf_api.upload_folder(**kwargs)
+
+
+def _retry_hf_write(op_name: str, fn, retries: int = 4, initial_delay: float = 1.5):
+    delay = initial_delay
+    for attempt in range(1, retries + 1):
+        try:
+            return fn()
+        except ReadTimeout:
+            if attempt == retries:
+                raise
+            print(
+                f"* {op_name} timed out (attempt {attempt}/{retries}). Retrying in {delay:.1f}s..."
+            )
+            time.sleep(delay)
+            delay = min(delay * 2, 12)
+        except HfHubHTTPError as e:
+            status = e.response.status_code if e.response is not None else None
+            if status is None or status < 500 or attempt == retries:
+                raise
+            print(
+                f"* {op_name} failed with HTTP {status} (attempt {attempt}/{retries}). Retrying in {delay:.1f}s..."
+            )
+            time.sleep(delay)
+            delay = min(delay * 2, 12)
+
+
+def _get_space_volumes(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> list[Volume]:
+    """
+    Return mounted volumes for a Space.
+
+    `HfApi.get_space_runtime()` does not always populate `volumes`, even when the
+    mount exists. Fall back to `space_info().runtime.volumes`, which currently
+    carries the volume metadata for running Spaces.
+    """
+    hf_api = hf_api or huggingface_hub.HfApi()
+    runtime = hf_api.get_space_runtime(space_id)
+    if runtime.volumes:
+        return list(runtime.volumes)
+
+    info = hf_api.space_info(space_id)
+    if info.runtime and info.runtime.volumes:
+        return list(info.runtime.volumes)
+
+    return []
+
+
+def _get_space_bucket_at_data_mount(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str | None:
+    for volume in _get_space_volumes(space_id, hf_api=hf_api):
+        if volume.type == "bucket" and volume.mount_path == "/data":
+            return volume.source
+    return None
+
+
+def _get_existing_space_bucket(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str | None:
+    """Return the Trackio bucket for a Space, preferring the canonical /data mount."""
+    bucket_at_data = _get_space_bucket_at_data_mount(space_id, hf_api=hf_api)
+    if bucket_at_data is not None:
+        return bucket_at_data
+
+    for volume in _get_space_volumes(space_id, hf_api=hf_api):
+        if volume.type == "bucket":
+            return volume.source
+    return None
+
+
+def _get_existing_static_space_bucket(
+    space_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str | None:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    try:
+        config_path = hf_api.hf_hub_download(
+            repo_id=space_id,
+            repo_type="space",
+            filename="config.json",
+        )
+    except (FileNotFoundError, HfHubHTTPError, OSError, ValueError):
+        return None
+
+    try:
+        with open(config_path, encoding="utf-8") as config_file:
+            config = json_mod.load(config_file)
+    except (OSError, ValueError, TypeError):
+        return None
+
+    bucket_id = config.get("bucket_id")
+    if isinstance(bucket_id, str) and bucket_id:
+        return bucket_id
+    return None
+
+
+def _ensure_bucket_mounted_at_data(
+    space_id: str,
+    bucket_id: str,
+    hf_api: huggingface_hub.HfApi | None = None,
+) -> None:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    existing = _get_space_volumes(space_id, hf_api=hf_api)
+    already_mounted = any(
+        v.type == "bucket" and v.source == bucket_id and v.mount_path == "/data"
+        for v in existing
+    )
+    if not already_mounted:
+        preserved = [
+            v
+            for v in existing
+            if not (
+                v.type == "bucket"
+                and (v.source == bucket_id or v.mount_path == "/data")
+            )
+        ]
+        hf_api.set_space_volumes(
+            space_id,
+            preserved + [Volume(type="bucket", source=bucket_id, mount_path="/data")],
+        )
+        print(f"* Attached bucket {bucket_id} at '/data'")
+
+    existing_variables = hf_api.get_space_variables(space_id)
+    current_trackio_dir = getattr(existing_variables.get("TRACKIO_DIR"), "value", None)
+    if current_trackio_dir != "/data/trackio":
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_DIR", "/data/trackio")
+    current_bucket_id = getattr(
+        existing_variables.get("TRACKIO_BUCKET_ID"), "value", None
+    )
+    if current_bucket_id != bucket_id:
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_BUCKET_ID", bucket_id)
+
+
+def _bucket_exists(bucket_id: str, hf_api: huggingface_hub.HfApi | None = None) -> bool:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    try:
+        hf_api.bucket_info(bucket_id)
+        return True
+    except BucketNotFoundError:
+        return False
+
+
+def _find_available_bucket_id(
+    preferred_bucket_id: str, hf_api: huggingface_hub.HfApi | None = None
+) -> str:
+    hf_api = hf_api or huggingface_hub.HfApi()
+    if not _bucket_exists(preferred_bucket_id, hf_api):
+        return preferred_bucket_id
+
+    suffix = 2
+    while True:
+        candidate = f"{preferred_bucket_id}-{suffix}"
+        if not _bucket_exists(candidate, hf_api):
+            return candidate
+        suffix += 1
+
+
+def resolve_auto_bucket_id(
+    space_id: str,
+    preferred_bucket_id: str,
+    hf_api: huggingface_hub.HfApi | None = None,
+) -> str:
+    """
+    Resolve the bucket to use for an auto-generated bucket ID.
+
+    Rules:
+    - Existing Space with a bucket mounted at /data -> reuse that bucket.
+    - Existing static Space with a bucket_id in config.json -> reuse that bucket.
+    - Otherwise -> use the preferred auto bucket ID if free, or a suffixed variant.
+    """
+    hf_api = hf_api or huggingface_hub.HfApi()
+    try:
+        info = hf_api.space_info(space_id)
+    except RepositoryNotFoundError:
+        pass
+    else:
+        existing_bucket_id = _get_existing_space_bucket(space_id, hf_api=hf_api)
+        if existing_bucket_id is None and getattr(info, "sdk", None) == "static":
+            existing_bucket_id = _get_existing_static_space_bucket(
+                space_id, hf_api=hf_api
+            )
+        if existing_bucket_id is not None:
+            return existing_bucket_id
+
+    bucket_id = _find_available_bucket_id(preferred_bucket_id, hf_api)
+    if bucket_id != preferred_bucket_id:
+        print(
+            f"* Auto-generated bucket {preferred_bucket_id} already exists; "
+            f"using {bucket_id} instead"
+        )
+    return bucket_id
+
+
+def _get_source_install_dependencies() -> str:
+    """Get trackio dependencies from pyproject.toml for source installs."""
+    trackio_path = files("trackio")
+    pyproject_path = Path(trackio_path).parent / "pyproject.toml"
+    with open(pyproject_path, "rb") as f:
+        pyproject = tomllib.load(f)
+    deps = pyproject["project"]["dependencies"]
+    spaces_deps = (
+        pyproject["project"].get("optional-dependencies", {}).get("spaces", [])
+    )
+    mcp_deps = pyproject["project"].get("optional-dependencies", {}).get("mcp", [])
+    return "\n".join(deps + spaces_deps + mcp_deps)
+
+
+def _get_space_install_requirement() -> str:
+    return f"trackio[spaces,mcp]=={trackio.__version__}"
+
+
+def _is_trackio_installed_from_source() -> bool:
+    """Check if trackio is installed from source/editable install vs PyPI."""
+    try:
+        trackio_file = trackio.__file__
+        if "site-packages" not in trackio_file and "dist-packages" not in trackio_file:
+            return True
+
+        dist = importlib.metadata.distribution("trackio")
+        if dist.files:
+            files = list(dist.files)
+            has_pth = any(".pth" in str(f) for f in files)
+            if has_pth:
+                return True
+
+        return False
+    except (
+        AttributeError,
+        importlib.metadata.PackageNotFoundError,
+        importlib.metadata.MetadataError,
+        ValueError,
+        TypeError,
+    ):
+        return True
+
+
+def deploy_as_space(
+    space_id: str,
+    space_storage: huggingface_hub.SpaceStorage | None = None,
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    private: bool | None = None,
+    frontend_dir: str | Path | None = None,
+):
+    if on_spaces():  # in case a repo with this function is uploaded to spaces
+        return
+
+    if dataset_id is not None and bucket_id is not None:
+        raise ValueError(
+            "Cannot use bucket volume options together with dataset_id; use one persistence mode."
+        )
+
+    trackio_path = files("trackio")
+
+    hf_api = huggingface_hub.HfApi()
+
+    try:
+        huggingface_hub.create_repo(
+            space_id,
+            private=private,
+            space_sdk="gradio",
+            space_storage=space_storage,
+            repo_type="space",
+            exist_ok=True,
+        )
+    except HfHubHTTPError 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,
+                private=private,
+                space_sdk="gradio",
+                space_storage=space_storage,
+                repo_type="space",
+                exist_ok=True,
+            )
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    # We can assume huggingface-hub is available; requirements.txt pins trackio.
+    # Make sure necessary dependencies are installed by creating a requirements.txt.
+    is_source_install = _is_trackio_installed_from_source()
+    resolved_frontend = resolve_frontend_dir(frontend_dir, announce=True)
+
+    if bucket_id is not None:
+        create_bucket_if_not_exists(bucket_id, private=private)
+
+    with open(Path(trackio_path, "README.md"), "r", encoding="utf-8") as f:
+        readme_content = f.read()
+        readme_content = readme_content.replace("sdk_version: {GRADIO_VERSION}\n", "")
+        readme_content = readme_content.replace("{APP_FILE}", "app.py")
+        readme_content = readme_content.replace(
+            "{LINKED_HUB_METADATA}", _readme_linked_hub_yaml(dataset_id)
+        )
+        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",
+        )
+
+    if is_source_install:
+        requirements_content = _get_source_install_dependencies()
+    else:
+        requirements_content = _get_space_install_requirement()
+
+    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()
+
+    if is_source_install:
+        dist_index = (
+            Path(trackio.__file__).resolve().parent / "frontend" / "dist" / "index.html"
+        )
+        if not dist_index.is_file() and not resolved_frontend.is_custom:
+            raise ValueError(
+                "The Trackio frontend build is missing. From the repository root run "
+                "`cd trackio/frontend && npm ci && npm run build`, then deploy again."
+            )
+        hf_api.upload_folder(
+            repo_id=space_id,
+            repo_type="space",
+            folder_path=trackio_path,
+            path_in_repo="trackio",
+            ignore_patterns=[
+                "README.md",
+                "frontend/node_modules/**",
+                "frontend/src/**",
+                "frontend/.gitignore",
+                "frontend/package.json",
+                "frontend/package-lock.json",
+                "frontend/vite.config.js",
+                "frontend/svelte.config.js",
+                "**/__pycache__/**",
+                "*.pyc",
+            ],
+        )
+
+    if resolved_frontend.is_custom:
+        _upload_frontend_folder(
+            hf_api,
+            repo_id=space_id,
+            repo_type="space",
+            folder_path=resolved_frontend.path,
+            path_in_repo=_CUSTOM_SPACE_FRONTEND_DIR,
+        )
+
+    app_file_content = _space_app_py(
+        _CUSTOM_SPACE_FRONTEND_DIR if resolved_frontend.is_custom else None
+    )
+    app_file_buffer = io.BytesIO(app_file_content.encode("utf-8"))
+    hf_api.upload_file(
+        path_or_fileobj=app_file_buffer,
+        path_in_repo="app.py",
+        repo_id=space_id,
+        repo_type="space",
+    )
+
+    if hf_token := huggingface_hub.utils.get_token():
+        huggingface_hub.add_space_secret(space_id, "HF_TOKEN", hf_token)
+    if bucket_id is not None:
+        _ensure_bucket_mounted_at_data(space_id, bucket_id, hf_api)
+    elif dataset_id is not None:
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_DATASET_ID", dataset_id)
+    if logo_light_url := os.environ.get("TRACKIO_LOGO_LIGHT_URL"):
+        huggingface_hub.add_space_variable(
+            space_id, "TRACKIO_LOGO_LIGHT_URL", logo_light_url
+        )
+    if logo_dark_url := os.environ.get("TRACKIO_LOGO_DARK_URL"):
+        huggingface_hub.add_space_variable(
+            space_id, "TRACKIO_LOGO_DARK_URL", logo_dark_url
+        )
+    if plot_order := os.environ.get("TRACKIO_PLOT_ORDER"):
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_PLOT_ORDER", plot_order)
+    if theme := os.environ.get("TRACKIO_THEME"):
+        huggingface_hub.add_space_variable(space_id, "TRACKIO_THEME", theme)
+    huggingface_hub.add_space_variable(space_id, "GRADIO_MCP_SERVER", "True")
+
+
+def create_space_if_not_exists(
+    space_id: str,
+    space_storage: huggingface_hub.SpaceStorage | None = None,
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    private: bool | None = None,
+    frontend_dir: str | Path | None = None,
+) -> None:
+    """
+    Creates a new Hugging Face Space if it does not exist.
+
+    Args:
+        space_id (`str`):
+            The ID of the Space to create.
+        space_storage ([`~huggingface_hub.SpaceStorage`], *optional*):
+            Choice of persistent storage tier for the Space.
+        dataset_id (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        bucket_id (`str`, *optional*):
+            Full Hub bucket id (`namespace/name`) to attach via the Hub volumes API (platform mount).
+            Sets `TRACKIO_DIR` to the mount path.
+        private (`bool`, *optional*):
+            Whether to make the Space 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.
+    """
+    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."
+        )
+    if bucket_id is not None and "/" not in bucket_id:
+        raise ValueError(
+            f"Invalid bucket ID: {bucket_id}. Must be in the format: username/bucketname or orgname/bucketname."
+        )
+    try:
+        huggingface_hub.repo_info(space_id, repo_type="space")
+        print(
+            f"* Found existing space: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+        )
+        if bucket_id is not None:
+            create_bucket_if_not_exists(bucket_id, private=private)
+            _ensure_bucket_mounted_at_data(space_id, bucket_id)
+        elif dataset_id is not None:
+            huggingface_hub.add_space_variable(
+                space_id, "TRACKIO_DATASET_ID", dataset_id
+            )
+        resolved_frontend = resolve_frontend_dir(frontend_dir, announce=False)
+        if resolved_frontend.is_custom:
+            deploy_as_space(
+                space_id,
+                space_storage,
+                dataset_id,
+                bucket_id,
+                private,
+                frontend_dir=frontend_dir,
+            )
+        return
+    except RepositoryNotFoundError:
+        pass
+    except HfHubHTTPError 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)
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    print(
+        f"* Creating new space: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+    )
+    deploy_as_space(
+        space_id,
+        space_storage,
+        dataset_id,
+        bucket_id,
+        private,
+        frontend_dir=frontend_dir,
+    )
+    print("* Waiting for Space to be ready...")
+    _wait_until_space_running(space_id)
+
+
+def _wait_until_space_running(space_id: str, timeout: int = 300) -> None:
+    hf_api = huggingface_hub.HfApi()
+    start = time.time()
+    delay = 2
+    request_timeout = 45.0
+    failure_stages = frozenset(
+        ("NO_APP_FILE", "CONFIG_ERROR", "BUILD_ERROR", "RUNTIME_ERROR")
+    )
+    while time.time() - start < timeout:
+        try:
+            info = hf_api.space_info(space_id, timeout=request_timeout)
+            if info.runtime:
+                stage = str(info.runtime.stage)
+                if stage in failure_stages:
+                    raise RuntimeError(
+                        f"Space {space_id} entered terminal stage {stage}. "
+                        "Fix README.md or app files; see build logs on the Hub."
+                    )
+                if stage == "RUNNING":
+                    return
+        except RuntimeError:
+            raise
+        except (huggingface_hub.utils.HfHubHTTPError, httpx.RequestError):
+            pass
+        time.sleep(delay)
+        delay = min(delay * 1.5, 15)
+    raise TimeoutError(
+        f"Space {space_id} did not reach RUNNING within {timeout}s. "
+        "Check status and build logs on the Hub."
+    )
+
+
+def wait_until_space_exists(
+    space_id: str,
+) -> None:
+    """
+    Blocks the current thread until the Space exists.
+
+    Args:
+        space_id (`str`):
+            The ID of the Space to wait for.
+
+    Raises:
+        `TimeoutError`: If waiting for the Space takes longer than expected.
+    """
+    hf_api = huggingface_hub.HfApi()
+    delay = 1
+    for _ in range(30):
+        try:
+            hf_api.space_info(space_id)
+            return
+        except (huggingface_hub.utils.HfHubHTTPError, httpx.RequestError):
+            time.sleep(delay)
+            delay = min(delay * 2, 60)
+    raise TimeoutError("Waiting for space to exist took longer than expected")
+
+
+def upload_db_to_space(project: str, space_id: str, force: bool = False) -> None:
+    """
+    Uploads the database of a local Trackio project to a Hugging Face Space.
+
+    This uses the Trackio remote client so newer Trackio Spaces can speak the direct
+    HTTP API while older Gradio-based Spaces still work through `gradio_client`.
+
+    Args:
+        project (`str`):
+            The name of the project to upload.
+        space_id (`str`):
+            The ID of the Space to upload to.
+        force (`bool`, *optional*, defaults to `False`):
+            If `True`, overwrites the existing database without prompting. If `False`,
+            prompts for confirmation.
+    """
+    db_path = SQLiteStorage.get_project_db_path(project)
+    client = RemoteClient(
+        space_id,
+        hf_token=huggingface_hub.utils.get_token(),
+        httpx_kwargs={"timeout": 90},
+    )
+
+    if not force:
+        try:
+            existing_projects = client.predict(api_name="/get_all_projects")
+            if project in existing_projects:
+                response = input(
+                    f"Database for project '{project}' already exists on Space '{space_id}'. "
+                    f"Overwrite it? (y/N): "
+                )
+                if response.lower() not in ["y", "yes"]:
+                    print("* Upload cancelled.")
+                    return
+        except Exception as e:
+            print(f"* Warning: Could not check if project exists on Space: {e}")
+            print("* Proceeding with upload...")
+
+    client.predict(
+        api_name="/upload_db_to_space",
+        project=project,
+        uploaded_db=handle_file(db_path),
+        hf_token=huggingface_hub.utils.get_token(),
+    )
+
+
+SYNC_BATCH_SIZE = 500
+
+
+def sync_incremental(
+    project: str,
+    space_id: str,
+    private: bool | None = None,
+    pending_only: bool = False,
+    frontend_dir: str | Path | None = None,
+) -> None:
+    """
+    Syncs a local Trackio project to a Space via the bulk_log API endpoints
+    instead of uploading the entire DB file. Supports incremental sync.
+
+    Args:
+        project: The name of the project to sync.
+        space_id: The HF Space ID to sync to.
+        private: Whether to make the Space private if creating.
+        pending_only: If True, only sync rows tagged with space_id (pending data).
+    """
+    print(
+        f"* Syncing project '{project}' to: {SPACE_URL.format(space_id=space_id)} (please wait...)"
+    )
+    create_space_if_not_exists(space_id, private=private, frontend_dir=frontend_dir)
+    wait_until_space_exists(space_id)
+    hf_token = huggingface_hub.utils.get_token()
+    expected_run_counts: Counter[str] = Counter()
+
+    client = RemoteClient(
+        space_id,
+        hf_token=hf_token,
+        httpx_kwargs={"timeout": 90},
+    )
+
+    if pending_only:
+        pending_logs = SQLiteStorage.get_pending_logs(project)
+        if pending_logs:
+            logs = pending_logs["logs"]
+            expected_run_counts.update(log["run"] for log in logs)
+            for i in range(0, len(logs), SYNC_BATCH_SIZE):
+                batch = logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing metrics: {min(i + SYNC_BATCH_SIZE, len(logs))}/{len(logs)}..."
+                )
+                client.predict(api_name="/bulk_log", logs=batch, hf_token=hf_token)
+            SQLiteStorage.clear_pending_logs(project, pending_logs["ids"])
+
+        pending_sys = SQLiteStorage.get_pending_system_logs(project)
+        if pending_sys:
+            logs = pending_sys["logs"]
+            for i in range(0, len(logs), SYNC_BATCH_SIZE):
+                batch = logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing system metrics: {min(i + SYNC_BATCH_SIZE, len(logs))}/{len(logs)}..."
+                )
+                client.predict(
+                    api_name="/bulk_log_system", logs=batch, hf_token=hf_token
+                )
+            SQLiteStorage.clear_pending_system_logs(project, pending_sys["ids"])
+
+        pending_uploads = SQLiteStorage.get_pending_uploads(project)
+        if pending_uploads:
+            upload_entries = []
+            for u in pending_uploads["uploads"]:
+                fp = u["file_path"]
+                if os.path.exists(fp):
+                    upload_entries.append(
+                        {
+                            "project": u["project"],
+                            "run": u["run"],
+                            "step": u["step"],
+                            "relative_path": u["relative_path"],
+                            "uploaded_file": handle_file(fp),
+                        }
+                    )
+            if upload_entries:
+                print(f"  Syncing {len(upload_entries)} media files...")
+                client.predict(
+                    api_name="/bulk_upload_media",
+                    uploads=upload_entries,
+                    hf_token=hf_token,
+                )
+            SQLiteStorage.clear_pending_uploads(project, pending_uploads["ids"])
+    else:
+        all_logs = SQLiteStorage.get_all_logs_for_sync(project)
+        if all_logs:
+            expected_run_counts.update(log["run"] for log in all_logs)
+            for i in range(0, len(all_logs), SYNC_BATCH_SIZE):
+                batch = all_logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing metrics: {min(i + SYNC_BATCH_SIZE, len(all_logs))}/{len(all_logs)}..."
+                )
+                client.predict(api_name="/bulk_log", logs=batch, hf_token=hf_token)
+
+        all_sys_logs = SQLiteStorage.get_all_system_logs_for_sync(project)
+        if all_sys_logs:
+            for i in range(0, len(all_sys_logs), SYNC_BATCH_SIZE):
+                batch = all_sys_logs[i : i + SYNC_BATCH_SIZE]
+                print(
+                    f"  Syncing system metrics: {min(i + SYNC_BATCH_SIZE, len(all_sys_logs))}/{len(all_sys_logs)}..."
+                )
+                client.predict(
+                    api_name="/bulk_log_system", logs=batch, hf_token=hf_token
+                )
+
+    _wait_for_remote_sync(client, project, expected_run_counts)
+    SQLiteStorage.set_project_metadata(project, "space_id", space_id)
+    print(
+        f"* Synced successfully to space: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+    )
+
+
+def _build_remote_client_with_retry(
+    space_id: str,
+    timeout: int = 360,
+    verbose: bool = False,
+) -> RemoteClient:
+    deadline = time.time() + timeout
+    delay = 2
+    last_error: Exception | None = None
+    while time.time() < deadline:
+        try:
+            return RemoteClient(space_id, verbose=verbose, httpx_kwargs={"timeout": 90})
+        except (ValueError, ConnectionError) as e:
+            last_error = e
+            time.sleep(delay)
+            delay = min(delay * 1.5, 15)
+    raise ConnectionError(
+        f"Could not connect to Space '{space_id}' within {timeout}s: {last_error}"
+    )
+
+
+def _wait_for_remote_sync(
+    client: RemoteClient,
+    project: str,
+    expected_run_counts: Counter[str],
+    timeout: int = 180,
+) -> None:
+    if not expected_run_counts:
+        return
+
+    deadline = time.time() + timeout
+    delay = 2
+    last_error: Exception | None = None
+    pending = dict(expected_run_counts)
+
+    while time.time() < deadline and pending:
+        completed = []
+        for run_name, expected_num_logs in pending.items():
+            try:
+                summary = client.predict(
+                    project=project, run=run_name, api_name="/get_run_summary"
+                )
+                if summary.get("num_logs") == expected_num_logs:
+                    completed.append(run_name)
+            except Exception as e:
+                last_error = e
+        for run_name in completed:
+            pending.pop(run_name, None)
+        if pending:
+            time.sleep(delay)
+            delay = min(delay * 1.5, 15)
+
+    if pending:
+        raise TimeoutError(
+            f"Remote sync for project '{project}' did not become visible for runs "
+            f"{sorted(pending.items())} within {timeout}s. "
+            f"Last error: {last_error!r}"
+        )
+
+
+def upload_dataset_for_static(
+    project: str,
+    dataset_id: str,
+    private: bool | None = None,
+) -> None:
+    hf_api = huggingface_hub.HfApi()
+
+    try:
+        huggingface_hub.create_repo(
+            dataset_id,
+            private=private,
+            repo_type="dataset",
+            exist_ok=True,
+        )
+    except HfHubHTTPError as e:
+        if e.response.status_code in [401, 403]:
+            print("Need 'write' access token to create a Dataset repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+            huggingface_hub.create_repo(
+                dataset_id,
+                private=private,
+                repo_type="dataset",
+                exist_ok=True,
+            )
+        else:
+            raise ValueError(f"Failed to create Dataset: {e}")
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_dir = Path(tmp_dir)
+        SQLiteStorage.export_for_static_space(project, output_dir)
+
+        media_dir = MEDIA_DIR / project
+        if media_dir.exists():
+            dest = output_dir / "media"
+            shutil.copytree(media_dir, dest)
+
+        _retry_hf_write(
+            "Dataset upload",
+            lambda: hf_api.upload_folder(
+                repo_id=dataset_id,
+                repo_type="dataset",
+                folder_path=str(output_dir),
+            ),
+        )
+
+    print(f"* Dataset uploaded: https://huggingface.co/datasets/{dataset_id}")
+
+
+def deploy_as_static_space(
+    space_id: str,
+    dataset_id: str | None,
+    project: str,
+    bucket_id: str | None = None,
+    private: bool | None = None,
+    hf_token: str | None = None,
+    frontend_dir: str | Path | None = None,
+) -> None:
+    if on_spaces():
+        return
+
+    if private is True:
+        raise ValueError(
+            "private=True is not supported for static Trackio Spaces. Static Spaces "
+            "run entirely in the browser, so their snapshot data must be public. "
+            "Use sdk='gradio' for a private dashboard."
+        )
+    hf_api = huggingface_hub.HfApi()
+
+    try:
+        huggingface_hub.create_repo(
+            space_id,
+            private=False,
+            space_sdk="static",
+            repo_type="space",
+            exist_ok=True,
+        )
+    except HfHubHTTPError as e:
+        if e.response.status_code in [401, 403]:
+            print("Need 'write' access token to create a Spaces repo.")
+            huggingface_hub.login(add_to_git_credential=False)
+            huggingface_hub.create_repo(
+                space_id,
+                private=False,
+                space_sdk="static",
+                repo_type="space",
+                exist_ok=True,
+            )
+        else:
+            raise ValueError(f"Failed to create Space: {e}")
+
+    linked = _readme_linked_hub_yaml(dataset_id)
+    readme_content = (
+        f"---\nemoji: 🎯\nsdk: static\npinned: false\ntags:\n - trackio\n{linked}---\n"
+    )
+    _retry_hf_write(
+        "Static Space README upload",
+        lambda: hf_api.upload_file(
+            path_or_fileobj=io.BytesIO(readme_content.encode("utf-8")),
+            path_in_repo="README.md",
+            repo_id=space_id,
+            repo_type="space",
+        ),
+    )
+
+    resolved_frontend = resolve_frontend_dir(frontend_dir, announce=True)
+
+    _retry_hf_write(
+        "Static Space frontend upload",
+        lambda: hf_api.upload_folder(
+            repo_id=space_id,
+            repo_type="space",
+            folder_path=str(resolved_frontend.path),
+        ),
+    )
+
+    config = {
+        "mode": "static",
+        "project": project,
+        "private": bool(private),
+    }
+    if bucket_id is not None:
+        config["bucket_id"] = bucket_id
+    if dataset_id is not None:
+        config["dataset_id"] = dataset_id
+    if hf_token is not None:
+        warnings.warn(
+            "`hf_token` is ignored by deploy_as_static_space() for static Space "
+            "deployment and will be removed in a future release.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+    _retry_hf_write(
+        "Static Space config upload",
+        lambda: hf_api.upload_file(
+            path_or_fileobj=io.BytesIO(json_mod.dumps(config).encode("utf-8")),
+            path_in_repo="config.json",
+            repo_id=space_id,
+            repo_type="space",
+        ),
+    )
+
+    assets_dir = Path(trackio.__file__).resolve().parent / "assets"
+    if assets_dir.is_dir():
+        _retry_hf_write(
+            "Static Space assets upload",
+            lambda: hf_api.upload_folder(
+                repo_id=space_id,
+                repo_type="space",
+                folder_path=str(assets_dir),
+                path_in_repo="static/trackio",
+            ),
+        )
+
+    print(
+        f"* Static Space deployed: {_BOLD_ORANGE}{SPACE_URL.format(space_id=space_id)}{_RESET}"
+    )
+
+
+def sync(
+    project: str,
+    space_id: str | None = None,
+    private: bool | None = None,
+    force: bool = False,
+    run_in_background: bool = False,
+    sdk: str = "gradio",
+    dataset_id: str | None = None,
+    bucket_id: str | None = None,
+    frontend_dir: str | Path | None = None,
+) -> str:
+    """
+    Syncs a local Trackio project's database to a Hugging Face Space.
+    If the Space does not exist, it will be created. Local data is never deleted.
+
+    **Freezing:** Passing ``sdk="static"`` deploys a static Space backed by an HF Bucket
+    (read-only dashboard, no Gradio server). You can sync the same project again later to
+    refresh that static Space. If you want a one-time snapshot of an existing Gradio Space,
+    use ``freeze()`` instead.
+
+    Args:
+        project (`str`): The name of the project to upload.
+        space_id (`str`, *optional*): The ID of the Space to upload to (e.g., `"username/space_id"`).
+            If not provided, checks project metadata first, then generates a random space_id.
+        private (`bool`, *optional*):
+            Whether to make the Space 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. Not supported with ``sdk="static"`` because
+            static Trackio dashboards read snapshot data directly from the browser.
+        force (`bool`, *optional*, defaults to `False`):
+            If `True`, overwrite the existing database without prompting for confirmation.
+            If `False`, prompt the user before overwriting an existing database.
+        run_in_background (`bool`, *optional*, defaults to `False`):
+            If `True`, the Space creation and database upload will be run in a background thread.
+            If `False`, all the steps will be run synchronously.
+        sdk (`str`, *optional*, defaults to `"gradio"`):
+            The type of Space to deploy. `"gradio"` deploys a Gradio Space with a live
+            server. `"static"` freezes the Space: deploys a static Space that reads from an HF Bucket
+            (no server needed).
+        dataset_id (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        bucket_id (`str`, *optional*):
+            The ID of the HF Bucket to sync to. By default, a bucket is auto-generated
+            from the space_id.
+    Returns:
+        `str`: The Space ID of the synced project.
+    """
+    if sdk not in ("gradio", "static"):
+        raise ValueError(f"sdk must be 'gradio' or 'static', got '{sdk}'")
+    if sdk == "static" and private is True:
+        raise ValueError(
+            "private=True is not supported for static Trackio Spaces. Static Spaces "
+            "run entirely in the browser, so their snapshot data must be public. "
+            "Use sdk='gradio' for a private dashboard."
+        )
+    bucket_id_was_explicit = bucket_id is not None
+
+    if space_id is None:
+        space_id = SQLiteStorage.get_space_id(project)
+    if space_id is None:
+        space_id = f"{project}-{get_or_create_project_hash(project)}"
+    space_id, dataset_id, bucket_id = preprocess_space_and_dataset_ids(
+        space_id, dataset_id, bucket_id
+    )
+    if dataset_id is None and bucket_id is not None and not bucket_id_was_explicit:
+        bucket_id = resolve_auto_bucket_id(space_id, bucket_id)
+
+    def _do_sync():
+        try:
+            info = huggingface_hub.HfApi().space_info(space_id)
+            existing_sdk = info.sdk
+            if existing_sdk and existing_sdk != sdk:
+                raise ValueError(
+                    f"Space '{space_id}' is a '{existing_sdk}' Space but sdk='{sdk}' was requested. "
+                    f"The sdk must match the existing Space type."
+                )
+        except RepositoryNotFoundError:
+            pass
+
+        if sdk == "static":
+            if dataset_id is not None:
+                upload_dataset_for_static(project, dataset_id, private=False)
+                deploy_as_static_space(
+                    space_id,
+                    dataset_id,
+                    project,
+                    private=False,
+                    frontend_dir=frontend_dir,
+                )
+            elif bucket_id is not None:
+                create_bucket_if_not_exists(bucket_id, private=False)
+                upload_project_to_bucket_for_static(project, bucket_id)
+                print(
+                    f"* Project data uploaded to bucket: https://huggingface.co/buckets/{bucket_id}"
+                )
+                deploy_as_static_space(
+                    space_id,
+                    None,
+                    project,
+                    bucket_id=bucket_id,
+                    private=False,
+                    frontend_dir=frontend_dir,
+                )
+        else:
+            if bucket_id is not None:
+                create_bucket_if_not_exists(bucket_id, private=private)
+                upload_project_to_bucket(project, bucket_id)
+                print(
+                    f"* Project data uploaded to bucket: https://huggingface.co/buckets/{bucket_id}"
+                )
+                create_space_if_not_exists(
+                    space_id,
+                    bucket_id=bucket_id,
+                    private=private,
+                    frontend_dir=frontend_dir,
+                )
+                _wait_until_space_running(space_id)
+                _wait_for_remote_sync(
+                    _build_remote_client_with_retry(space_id),
+                    project,
+                    Counter(
+                        log["run"]
+                        for log in SQLiteStorage.get_all_logs_for_sync(project)
+                    ),
+                )
+            else:
+                sync_incremental(
+                    project,
+                    space_id,
+                    private=private,
+                    pending_only=False,
+                    frontend_dir=frontend_dir,
+                )
+        SQLiteStorage.set_project_metadata(project, "space_id", space_id)
+
+    if run_in_background:
+        threading.Thread(target=_do_sync).start()
+    else:
+        _do_sync()
+    return space_id
+
+
+def _get_source_bucket(space_id: str) -> str:
+    bucket_id = _get_existing_space_bucket(space_id)
+    if bucket_id is not None:
+        _ensure_bucket_mounted_at_data(space_id, bucket_id)
+        return bucket_id
+    raise ValueError(
+        f"Space '{space_id}' has no bucket mounted at '/data'. "
+        f"freeze() requires the source Space to use bucket storage."
+    )
+
+
+def freeze(
+    space_id: str,
+    project: str,
+    new_space_id: str | None = None,
+    private: bool | None = None,
+    bucket_id: str | None = None,
+    frontend_dir: str | Path | None = None,
+) -> str:
+    """
+    Creates a new static Hugging Face Space containing a read-only snapshot of
+    the data for the specified project from the source Gradio Space. The data is
+    read from the bucket attached to the source Space at freeze time. The original
+    Space is not modified, and the new static Space does not automatically reflect
+    metrics uploaded to the original Gradio Space after the freeze completes.
+
+    Args:
+        space_id (`str`):
+            The ID of the source Gradio Space (e.g., `"username/my-space"` or a
+            short repo name with the logged-in namespace inferred, like `init()`).
+            Must be a Gradio Space with a bucket mounted at `/data`.
+        project (`str`):
+            The name of the project whose data to include in the frozen Space.
+        new_space_id (`str`, *optional*):
+            The ID for the new static Space. If not provided, defaults to
+            `"{space_id}_static"`.
+        private (`bool`, *optional*):
+            Not supported. Frozen static dashboards read snapshot data directly
+            from the browser, so the destination snapshot must be public.
+        bucket_id (`str`, *optional*):
+            The ID of the HF Bucket for the new static Space's data storage.
+            If not provided, one is auto-generated from the new Space ID.
+
+    Returns:
+        `str`: The Space ID of the newly created static Space.
+    """
+    if private is True:
+        raise ValueError(
+            "private=True is not supported for frozen static Trackio Spaces. Static "
+            "Spaces run entirely in the browser, so their snapshot data must be "
+            "public. Use a Gradio Space if the frozen dashboard must stay private."
+        )
+    space_id, _, _ = preprocess_space_and_dataset_ids(space_id, None, None)
+
+    try:
+        info = huggingface_hub.HfApi().space_info(space_id)
+        if info.sdk != "gradio":
+            raise ValueError(
+                f"Space '{space_id}' is not a Gradio Space (sdk='{info.sdk}'). "
+                f"freeze() requires a Gradio Space as the source."
+            )
+    except RepositoryNotFoundError:
+        raise ValueError(
+            f"Space '{space_id}' not found. Provide an existing Gradio Space ID."
+        )
+
+    source_bucket_id = _get_source_bucket(space_id)
+    print(f"* Reading project data from bucket: {source_bucket_id}")
+
+    bucket_id_was_explicit = bucket_id is not None
+
+    if new_space_id is None:
+        new_space_id = f"{space_id}_static"
+    new_space_id, _dataset_id, bucket_id = preprocess_space_and_dataset_ids(
+        new_space_id, None, bucket_id
+    )
+    if bucket_id is not None and not bucket_id_was_explicit:
+        bucket_id = resolve_auto_bucket_id(new_space_id, bucket_id)
+
+    hf_api = huggingface_hub.HfApi()
+    try:
+        dest_info = hf_api.space_info(new_space_id)
+        tags = dest_info.tags or []
+        if dest_info.sdk != "static" or "trackio" not in tags:
+            raise ValueError(
+                f"Space '{new_space_id}' already exists and is not a Trackio static Space "
+                f"(sdk='{dest_info.sdk}', tags={tags}). Choose a different new_space_id "
+                f"or delete the existing Space first."
+            )
+    except RepositoryNotFoundError:
+        pass
+
+    create_bucket_if_not_exists(bucket_id, private=False)
+    export_from_bucket_for_static(source_bucket_id, bucket_id, project)
+    print(
+        f"* Project data uploaded to bucket: https://huggingface.co/buckets/{bucket_id}"
+    )
+    deploy_as_static_space(
+        new_space_id,
+        None,
+        project,
+        bucket_id=bucket_id,
+        private=False,
+        frontend_dir=frontend_dir,
+    )
+    return new_space_id

trackio/dummy_commit_scheduler.py

@@ -0,0 +1,19 @@
+from concurrent.futures import Future
+
+
+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()
+
+    def trigger(self) -> Future:
+        fut: Future = Future()
+        fut.set_result(None)
+        return fut

trackio/exceptions.py

@@ -0,0 +1,2 @@
+class TrackioAPIError(Exception):
+    pass

trackio/frontend/dist/assets/index-BcnSteuj.css

@@ -0,0 +1 @@
+:root{--primary-50: #fff7ed;--primary-100: #ffedd5;--primary-200: #fed7aa;--primary-300: #fdba74;--primary-400: #fb923c;--primary-500: #f97316;--primary-600: #ea580c;--primary-700: #c2410c;--primary-800: #9a3412;--primary-900: #7c2d12;--primary-950: #6c2e12;--secondary-50: #eff6ff;--secondary-100: #dbeafe;--secondary-200: #bfdbfe;--secondary-300: #93c5fd;--secondary-400: #60a5fa;--secondary-500: #3b82f6;--secondary-600: #2563eb;--secondary-700: #1d4ed8;--secondary-800: #1e40af;--secondary-900: #1e3a8a;--secondary-950: #1d3660;--neutral-50: #f9fafb;--neutral-100: #f3f4f6;--neutral-200: #e5e7eb;--neutral-300: #d1d5db;--neutral-400: #9ca3af;--neutral-500: #6b7280;--neutral-600: #4b5563;--neutral-700: #374151;--neutral-800: #1f2937;--neutral-900: #111827;--neutral-950: #0b0f19;--size-0-5: 2px;--size-1: 4px;--size-2: 8px;--size-3: 12px;--size-4: 16px;--size-5: 20px;--size-6: 24px;--size-8: 32px;--size-14: 56px;--size-16: 64px;--size-28: 112px;--size-full: 100%;--spacing-xxs: 1px;--spacing-xs: 2px;--spacing-sm: 4px;--spacing-md: 6px;--spacing-lg: 8px;--spacing-xl: 10px;--spacing-xxl: 16px;--radius-xxs: 1px;--radius-xs: 2px;--radius-sm: 3px;--radius-md: 4px;--radius-lg: 5px;--radius-xl: 8px;--radius-xxl: 12px;--text-xxs: 9px;--text-xs: 10px;--text-sm: 12px;--text-md: 14px;--text-lg: 16px;--text-xl: 22px;--text-xxl: 26px;--line-sm: 1.4;--background-fill-primary: white;--background-fill-secondary: var(--neutral-50);--body-text-color: var(--neutral-900);--body-text-color-subdued: var(--neutral-600);--border-color-primary: var(--neutral-200);--color-accent: var(--primary-500);--color-accent-soft: var(--primary-50);--shadow-drop: rgba(0, 0, 0, .05) 0px 1px 2px 0px;--shadow-drop-lg: 0 1px 3px 0 rgb(0 0 0 / .1), 0 1px 2px -1px rgb(0 0 0 / .1);--shadow-inset: rgba(0, 0, 0, .05) 0px 2px 4px 0px inset;--shadow-spread: 3px;--block-title-text-color: var(--neutral-500);--block-title-text-size: var(--text-md);--block-title-text-weight: 400;--block-info-text-color: var(--body-text-color-subdued);--block-info-text-size: var(--text-sm);--input-background-fill: white;--input-background-fill-focus: var(--primary-500);--input-border-color: var(--border-color-primary);--input-border-color-focus: var(--primary-300);--input-border-width: 1px;--input-padding: var(--spacing-xl);--input-placeholder-color: var(--neutral-400);--input-radius: var(--radius-lg);--input-shadow: 0 0 0 var(--shadow-spread) transparent, var(--shadow-inset);--input-shadow-focus: 0 0 0 var(--shadow-spread) var(--primary-50), var(--shadow-inset);--input-text-size: var(--text-md);--checkbox-background-color: var(--background-fill-primary);--checkbox-background-color-focus: var(--checkbox-background-color);--checkbox-background-color-hover: var(--checkbox-background-color);--checkbox-background-color-selected: var(--primary-600);--checkbox-border-color: var(--neutral-300);--checkbox-border-color-focus: var(--primary-500);--checkbox-border-color-hover: var(--neutral-300);--checkbox-border-color-selected: var(--primary-600);--checkbox-border-radius: var(--radius-sm);--checkbox-border-width: var(--input-border-width);--checkbox-label-gap: var(--spacing-lg);--checkbox-label-padding: var(--spacing-md) calc(2 * var(--spacing-md));--checkbox-label-text-size: var(--text-md);--checkbox-shadow: var(--input-shadow);--checkbox-check: url("data:image/svg+xml,%3csvg viewBox='0 0 16 16' fill='white' xmlns='http://www.w3.org/2000/svg'%3e%3cpath d='M12.207 4.793a1 1 0 010 1.414l-5 5a1 1 0 01-1.414 0l-2-2a1 1 0 011.414-1.414L6.5 9.086l4.293-4.293a1 1 0 011.414 0z'/%3e%3c/svg%3e");--slider-color: var(--primary-500);--container-radius: var(--radius-lg);--layer-top: 9999}.navbar.svelte-d8j1hi{display:flex;align-items:stretch;border-bottom:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);padding:0;flex-shrink:0;min-height:44px}.nav-spacer.svelte-d8j1hi{flex:1 1 0;min-width:0}.nav-tabs.svelte-d8j1hi{display:flex;gap:0;flex-shrink:0;padding-right:8px}.nav-link.svelte-d8j1hi{padding:10px 16px;border:none;background:none;color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-md, 14px);cursor:pointer;white-space:nowrap;border-bottom:2px solid transparent;transition:color .15s;font-weight:400}.nav-link.empty.svelte-d8j1hi:not(.active){color:var(--body-text-color-subdued, #9ca3af);opacity:.48}.nav-link.svelte-d8j1hi:hover{color:var(--body-text-color, #1f2937);opacity:1}.nav-link.active.svelte-d8j1hi{color:var(--body-text-color, #1f2937);border-bottom-color:var(--body-text-color, #1f2937);font-weight:500}.settings-btn.svelte-d8j1hi{display:flex;align-items:center;gap:6px}.settings-btn.svelte-d8j1hi svg:where(.svelte-d8j1hi){flex-shrink:0}.checkbox-group.svelte-17gmtkf{display:flex;flex-direction:column}.checkbox-item.svelte-17gmtkf{display:flex;align-items:center;gap:8px;padding:3px 0;cursor:pointer;font-size:13px}.checkbox-item.svelte-17gmtkf input[type=checkbox]:where(.svelte-17gmtkf){-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;margin:0;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);box-shadow:var(--checkbox-shadow);cursor:pointer;flex-shrink:0;transition:background-color .15s,border-color .15s}.checkbox-item.svelte-17gmtkf input[type=checkbox]:where(.svelte-17gmtkf):checked{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}.checkbox-item.svelte-17gmtkf input[type=checkbox]:where(.svelte-17gmtkf):hover{border-color:var(--checkbox-border-color-hover, #d1d5db)}.color-dot.svelte-17gmtkf{width:10px;height:10px;border-radius:50%;flex-shrink:0}.run-name.svelte-17gmtkf{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--body-text-color, #1f2937)}.dropdown-container.svelte-kgylqb{width:100%;margin-bottom:4px}.label.svelte-kgylqb{display:block;font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);margin-bottom:6px}.info.svelte-kgylqb{display:block;font-size:12px;color:var(--body-text-color-subdued, #9ca3af);margin-bottom:4px}.wrap.svelte-kgylqb{position:relative;border-radius:var(--input-radius, 8px);background:var(--input-background-fill, white);border:1px solid var(--border-color-primary, #e5e7eb);transition:border-color .15s,box-shadow .15s}.wrap.focused.svelte-kgylqb{border-color:var(--input-border-color-focus, #fdba74);box-shadow:0 0 0 2px var(--primary-50, #fff7ed)}.wrap-inner.svelte-kgylqb{display:flex;position:relative;align-items:center;padding:0 10px}.secondary-wrap.svelte-kgylqb{display:flex;flex:1;align-items:center}input.svelte-kgylqb{margin:0;outline:none;border:none;background:inherit;width:100%;color:var(--body-text-color, #1f2937);font-size:13px;font-family:inherit;padding:7px 0}input.svelte-kgylqb::placeholder{color:var(--input-placeholder-color, #9ca3af)}input[readonly].svelte-kgylqb{cursor:pointer}.icon-wrap.svelte-kgylqb{color:var(--body-text-color-subdued, #9ca3af);width:16px;flex-shrink:0;pointer-events:none}.options.svelte-kgylqb{position:fixed;z-index:var(--layer-top, 9999);margin:0;padding:4px 0;box-shadow:0 4px 12px #0000001f;border-radius:var(--input-radius, 8px);border:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);min-width:fit-content;overflow:auto;color:var(--body-text-color, #1f2937);list-style:none}.item.svelte-kgylqb{display:flex;cursor:pointer;padding:6px 10px;font-size:13px;word-break:break-word}.item.svelte-kgylqb:hover,.item.active.svelte-kgylqb{background:var(--background-fill-secondary, #f9fafb)}.item.selected.svelte-kgylqb{font-weight:500}.check-mark.svelte-kgylqb{padding-right:6px;min-width:16px;font-size:12px}.check-mark.hide.svelte-kgylqb{visibility:hidden}.checkbox-container.svelte-oj84db{display:flex;align-items:center;gap:8px;cursor:pointer;padding:3px 0}.label-text.svelte-oj84db{color:var(--body-text-color, #1f2937);font-size:13px;line-height:1.4}input[type=checkbox].svelte-oj84db{--ring-color: transparent;position:relative;-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;box-shadow:var(--checkbox-shadow);border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);flex-shrink:0;cursor:pointer;transition:background-color .15s,border-color .15s}input[type=checkbox].svelte-oj84db:checked,input[type=checkbox].svelte-oj84db:checked:hover,input[type=checkbox].svelte-oj84db:checked:focus{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}input[type=checkbox].svelte-oj84db:hover{border-color:var(--checkbox-border-color-hover, #d1d5db);background-color:var(--checkbox-background-color-hover, white)}input[type=checkbox].svelte-oj84db:focus{border-color:var(--checkbox-border-color-focus, #f97316);background-color:var(--checkbox-background-color-focus, white);outline:none}.slider-wrap.svelte-wei6ev{display:flex;flex-direction:column;width:100%}.head.svelte-wei6ev{margin-bottom:4px;display:flex;justify-content:space-between;align-items:center;width:100%}.label.svelte-wei6ev{flex:1;font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280)}.info.svelte-wei6ev{display:block;font-size:12px;color:var(--body-text-color-subdued, #9ca3af);margin-bottom:4px}.slider-input-container.svelte-wei6ev{display:flex;align-items:center;gap:6px}input[type=range].svelte-wei6ev{-webkit-appearance:none;-moz-appearance:none;appearance:none;width:100%;cursor:pointer;outline:none;border-radius:var(--radius-xl, 12px);min-width:var(--size-28, 112px);background:transparent}input[type=range].svelte-wei6ev::-webkit-slider-runnable-track{height:6px;border-radius:var(--radius-xl, 12px);background:linear-gradient(to right,var(--slider-color, #f97316) var(--range_progress, 50%),var(--neutral-200, #e5e7eb) var(--range_progress, 50%))}input[type=range].svelte-wei6ev::-webkit-slider-thumb{-webkit-appearance:none;-moz-appearance:none;appearance:none;height:16px;width:16px;background-color:var(--slider-color, #f97316);border:2px solid var(--background-fill-primary, white);border-radius:50%;margin-top:-5px;box-shadow:0 0 0 1px var(--border-color-primary, rgba(0, 0, 0, .08)),0 1px 3px #0003}input[type=range].svelte-wei6ev::-moz-range-track{height:6px;background:var(--neutral-200, #e5e7eb);border-radius:var(--radius-xl, 12px)}input[type=range].svelte-wei6ev::-moz-range-thumb{-webkit-appearance:none;-moz-appearance:none;appearance:none;height:16px;width:16px;background-color:var(--slider-color, #f97316);border:2px solid var(--background-fill-primary, white);border-radius:50%;box-shadow:0 0 0 1px var(--border-color-primary, rgba(0, 0, 0, .08)),0 1px 3px #0003}input[type=range].svelte-wei6ev::-moz-range-progress{height:6px;background-color:var(--slider-color, #f97316);border-radius:var(--radius-xl, 12px)}.bound.svelte-wei6ev{font-size:11px;color:var(--body-text-color-subdued, #9ca3af);min-width:12px;text-align:center}.textbox-container.svelte-6yncpg{width:100%}.label.svelte-6yncpg{display:block;font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);margin-bottom:6px}.info.svelte-6yncpg{display:block;font-size:12px;color:var(--body-text-color-subdued, #9ca3af);margin-bottom:4px}.input-wrap.svelte-6yncpg{border-radius:var(--input-radius, 8px);background:var(--input-background-fill, white);border:1px solid var(--border-color-primary, #e5e7eb);transition:border-color .15s,box-shadow .15s}.input-wrap.svelte-6yncpg:focus-within{border-color:var(--input-border-color-focus, #fdba74);box-shadow:0 0 0 2px var(--primary-50, #fff7ed)}input.svelte-6yncpg{width:100%;padding:7px 10px;outline:none;border:none;background:transparent;color:var(--body-text-color, #1f2937);font-size:13px;font-family:inherit;border-radius:var(--input-radius, 8px)}input.svelte-6yncpg::placeholder{color:var(--input-placeholder-color, #9ca3af)}.sidebar.svelte-181dlmc{width:290px;min-width:290px;background:var(--background-fill-primary, white);border-right:1px solid var(--border-color-primary, #e5e7eb);display:flex;flex-direction:column;position:relative;overflow:hidden;transition:width .2s,min-width .2s}.sidebar.collapsed.svelte-181dlmc{width:40px;min-width:40px}.toggle-btn.svelte-181dlmc{position:absolute;top:12px;right:8px;z-index:10;border:none;background:none;color:var(--body-text-color-subdued, #9ca3af);cursor:pointer;padding:4px;display:flex;align-items:center;justify-content:center;border-radius:var(--radius-sm, 4px);transition:color .15s,background-color .15s}.toggle-btn.svelte-181dlmc:hover{color:var(--body-text-color, #1f2937);background-color:var(--background-fill-secondary, #f9fafb)}.sidebar-content.svelte-181dlmc{padding:16px;flex:1;min-height:0;display:flex;flex-direction:column}.sidebar-scroll.svelte-181dlmc{overflow-y:auto;flex:1;min-height:0}.oauth-footer.svelte-181dlmc{flex-shrink:0;margin-top:12px;padding-top:12px;border-top:1px solid var(--border-color-primary, #e5e7eb)}.readonly-footer.svelte-181dlmc{flex-shrink:0;margin-top:12px;padding-top:12px;border-top:1px solid var(--border-color-primary, #e5e7eb);display:flex;align-items:center;gap:8px;flex-wrap:wrap}.readonly-badge.svelte-181dlmc{display:inline-flex;align-items:center;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:999px;padding:2px 8px;font-size:10px;letter-spacing:.06em;font-weight:600;color:var(--body-text-color-subdued, #6b7280);background:var(--background-fill-secondary, #f9fafb)}.readonly-link.svelte-181dlmc{font-size:12px;color:var(--body-text-color-subdued, #6b7280);text-decoration:none;max-width:100%;overflow-wrap:anywhere}.readonly-link.svelte-181dlmc:hover{color:var(--body-text-color, #1f2937);text-decoration:underline}.oauth-line.svelte-181dlmc{margin:0;font-size:12px;line-height:1.4;color:var(--body-text-color-subdued, #6b7280)}.oauth-warn.svelte-181dlmc{color:var(--body-text-color, #92400e)}.hf-login-btn.svelte-181dlmc{display:inline-flex;align-items:center;justify-content:center;gap:8px;width:100%;padding:8px 12px;font-size:13px;font-weight:600;color:#fff;background:#141c2e;border-radius:var(--radius-lg, 8px);text-decoration:none;border:none;cursor:pointer;box-sizing:border-box}.hf-login-btn.svelte-181dlmc:hover{background:#283042}.hf-logo.svelte-181dlmc{width:20px;height:20px;flex-shrink:0}.oauth-hint.svelte-181dlmc{margin:8px 0 0;font-size:11px;line-height:1.35;color:var(--body-text-color-subdued, #9ca3af)}.oauth-signed-in.svelte-181dlmc{margin:0;font-size:12px;color:var(--body-text-color-subdued, #6b7280)}.oauth-logout.svelte-181dlmc{font-size:12px;color:var(--body-text-color-subdued, #9ca3af);text-decoration:none;cursor:pointer}.oauth-logout.svelte-181dlmc:hover{text-decoration:underline;color:var(--body-text-color, #1f2937)}.logo-section.svelte-181dlmc{margin-bottom:20px}.logo.svelte-181dlmc{width:80%;max-width:200px}.section.svelte-181dlmc{margin-top:2px;margin-bottom:18px}.share-tabs.svelte-181dlmc{display:flex;gap:6px;margin-bottom:8px}.share-tab-btn.svelte-181dlmc{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);padding:4px 8px;font-size:12px;color:var(--body-text-color-subdued, #6b7280);background:var(--background-fill-primary, white);cursor:pointer}.share-tab-btn.active.svelte-181dlmc{color:var(--body-text-color, #1f2937);background:var(--background-fill-secondary, #f9fafb)}.share-field.svelte-181dlmc{display:flex;flex-direction:column;gap:6px}.share-input-row.svelte-181dlmc{display:flex;gap:6px;align-items:stretch}.share-input-row.svelte-181dlmc input:where(.svelte-181dlmc),.share-input-row.svelte-181dlmc textarea:where(.svelte-181dlmc){width:100%;min-width:0;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);padding:6px 8px;font-size:12px;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;color:var(--body-text-color, #1f2937);background:var(--background-fill-secondary, #f9fafb);resize:vertical}.copy-btn.svelte-181dlmc{box-sizing:border-box;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);padding:6px 10px;min-width:3.25rem;display:inline-flex;align-items:center;justify-content:center;font-size:12px;line-height:1;color:var(--body-text-color, #1f2937);background:var(--background-fill-primary, white);cursor:pointer;flex-shrink:0}.copy-btn-check.svelte-181dlmc{display:block;color:var(--color-accent, #f97316)}.share-hint.svelte-181dlmc{margin:0;font-size:12px;line-height:1.4;color:var(--body-text-color-subdued, #9ca3af)}.section-label.svelte-181dlmc{font-size:13px;font-weight:500;color:var(--body-text-color-subdued, #6b7280)}.locked-project.svelte-181dlmc{margin-top:4px;font-size:13px;font-weight:500;color:var(--body-text-color, #1f2937);padding:8px 10px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-secondary, #f9fafb)}.runs-header.svelte-181dlmc{display:flex;align-items:center;justify-content:space-between;margin-bottom:6px}.select-all-label.svelte-181dlmc{display:flex;align-items:center;gap:6px;cursor:pointer}.select-all-cb.svelte-181dlmc{-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);cursor:pointer;flex-shrink:0;position:relative;transition:background-color .15s,border-color .15s}.select-all-cb.svelte-181dlmc:checked{background-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));border-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));background-image:var(--checkbox-check)}.select-all-cb.svelte-181dlmc:indeterminate{background-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));border-color:var(--checkbox-background-color-selected, var(--color-accent, #f97316));background-image:url("data:image/svg+xml,%3Csvg viewBox='0 0 16 16' fill='white' xmlns='http://www.w3.org/2000/svg'%3E%3Crect x='3' y='7' width='10' height='2' rx='1'/%3E%3C/svg%3E");background-size:12px;background-position:center;background-repeat:no-repeat}.latest-toggle.svelte-181dlmc{display:flex;align-items:center;gap:6px;font-size:12px;color:var(--body-text-color-subdued, #6b7280);cursor:pointer}.latest-toggle.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc){-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;margin:0;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);box-shadow:var(--checkbox-shadow);cursor:pointer;flex-shrink:0;transition:background-color .15s,border-color .15s}.latest-toggle.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc):checked{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}.checkbox-list.svelte-181dlmc{max-height:300px;overflow-y:auto;margin-top:8px}.device-group.svelte-181dlmc{margin-top:14px;padding-top:12px;border-top:1px solid var(--border-color-primary, #e5e7eb)}.section-sublabel.svelte-181dlmc{font-size:12px;font-weight:600;color:var(--body-text-color-subdued, #6b7280)}.checkbox-group.svelte-181dlmc{display:flex;flex-direction:column;margin-top:8px}.checkbox-item.svelte-181dlmc{display:flex;align-items:center;gap:8px;padding:3px 0;cursor:pointer;font-size:13px}.checkbox-item.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc){-moz-appearance:none;appearance:none;-webkit-appearance:none;width:16px;height:16px;margin:0;border:1px solid var(--checkbox-border-color, #d1d5db);border-radius:var(--checkbox-border-radius, 4px);background-color:var(--checkbox-background-color, white);box-shadow:var(--checkbox-shadow);cursor:pointer;flex-shrink:0;transition:background-color .15s,border-color .15s}.checkbox-item.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc):checked{background-image:var(--checkbox-check);background-color:var(--checkbox-background-color-selected, #f97316);border-color:var(--checkbox-border-color-selected, #f97316)}.checkbox-item.svelte-181dlmc input[type=checkbox]:where(.svelte-181dlmc):hover{border-color:var(--checkbox-border-color-hover, #d1d5db)}.run-name.svelte-181dlmc{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--body-text-color, #1f2937)}.group-by-row.svelte-181dlmc{margin-top:8px}.grouped-runs.svelte-181dlmc{margin-top:8px;display:flex;flex-direction:column;gap:6px}.run-group-section.svelte-181dlmc{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);overflow:hidden}.run-group-header.svelte-181dlmc{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.svelte-181dlmc{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.svelte-181dlmc{font-size:11px;color:var(--body-text-color-subdued, #9ca3af);margin-left:4px;flex-shrink:0}.group-checkbox-list.svelte-181dlmc{padding:4px 10px;max-height:none}.alert-panel.svelte-x5aqew{position:fixed;bottom:16px;right:16px;width:380px;max-height:400px;background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);box-shadow:var(--shadow-drop-lg);z-index:1000;overflow:hidden;display:flex;flex-direction:column}.alert-panel.collapsed.svelte-x5aqew{max-height:none}.alert-header.svelte-x5aqew{padding:10px 12px;border:none;border-bottom:1px solid var(--border-color-primary, #e5e7eb);background:none;width:100%;display:flex;align-items:center;justify-content:space-between;cursor:pointer;gap:8px}.alert-panel.collapsed.svelte-x5aqew .alert-header:where(.svelte-x5aqew){border-bottom:none}.collapse-icon.svelte-x5aqew{color:var(--body-text-color-subdued, #9ca3af);flex-shrink:0;transition:transform .15s}.collapse-icon.rotated.svelte-x5aqew{transform:rotate(-90deg)}.alert-title.svelte-x5aqew{font-size:13px;font-weight:600;color:var(--body-text-color, #1f2937)}.filter-pills.svelte-x5aqew{display:flex;gap:4px}.pill.svelte-x5aqew{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-xxl, 22px);padding:2px 8px;font-size:11px;background:var(--background-fill-secondary, #f9fafb);color:var(--body-text-color-subdued, #6b7280);cursor:pointer}.pill.active.svelte-x5aqew{background:var(--color-accent, #f97316);color:#fff;border-color:var(--color-accent, #f97316)}.alert-list.svelte-x5aqew{overflow-y:auto;flex:1}.alert-item.svelte-x5aqew{border-bottom:1px solid var(--neutral-100, #f3f4f6)}.alert-row.svelte-x5aqew{display:flex;align-items:center;gap:8px;width:100%;padding:8px 12px;border:none;background:none;text-align:left;cursor:pointer;font-size:var(--text-sm, 12px)}.alert-row.svelte-x5aqew:hover{background:var(--background-fill-secondary, #f9fafb)}.alert-text.svelte-x5aqew{flex:1;color:var(--body-text-color, #1f2937)}.alert-meta.svelte-x5aqew{font-size:var(--text-xs, 10px);color:var(--body-text-color-subdued, #9ca3af);white-space:nowrap}.alert-detail.svelte-x5aqew{padding:4px 12px 8px 32px;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.plot-container.svelte-9thu1j{min-width:350px;flex:1;background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:12px;overflow:hidden;position:relative}.plot-container[draggable=true].svelte-9thu1j{cursor:grab}.plot-container[draggable=true].svelte-9thu1j:active{cursor:grabbing}.hidden-plot.svelte-9thu1j{visibility:hidden;height:0;padding:0;margin:0;border:none;overflow:hidden;pointer-events:none}.drag-handle.svelte-9thu1j{position:absolute;top:8px;left:8px;color:var(--body-text-color-subdued, #9ca3af);opacity:0;transition:opacity .15s;z-index:5}.plot-container.svelte-9thu1j:hover .drag-handle:where(.svelte-9thu1j){opacity:.5}.drag-handle.svelte-9thu1j:hover{opacity:1!important}.plot-toolbar.svelte-9thu1j{position:absolute;top:8px;right:8px;display:flex;gap:4px;z-index:5;opacity:0;transition:opacity .15s}.plot-container.svelte-9thu1j:hover .plot-toolbar:where(.svelte-9thu1j){opacity:1}.toolbar-btn.svelte-9thu1j{border:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;padding:4px 6px;border-radius:var(--radius-sm, 4px);display:flex;align-items:center;justify-content:center}.toolbar-btn.svelte-9thu1j:hover{background:var(--neutral-100, #f3f4f6);color:var(--body-text-color, #1f2937)}.plot-chart-wrap.svelte-9thu1j{position:relative;width:100%}.plot-chart-wrap--fs.svelte-9thu1j{flex:1;min-height:0;display:flex;flex-direction:column}.reset-zoom-btn.svelte-9thu1j{position:absolute;bottom:1px;right:1px;z-index:6;display:inline-flex;align-items:center;justify-content:center;margin:0;min-width:52px;padding:5px 12px 5px 10px;border:none;border-radius:4px;background:transparent;color:var(--body-text-color-subdued, #334155);cursor:pointer;opacity:.92;transform:translateY(6px);transition:opacity .15s ease,color .15s ease,background .15s ease;box-shadow:none}.reset-zoom-btn.svelte-9thu1j:hover{opacity:1;color:var(--body-text-color, #0f172a);background:var(--background-fill-secondary, rgba(226, 232, 240, .85));transform:translateY(6px)}.reset-zoom-btn.svelte-9thu1j svg:where(.svelte-9thu1j){display:block;flex-shrink:0;filter:drop-shadow(0 0 .5px rgba(255,255,255,.95))}.plot.svelte-9thu1j{width:100%}.plot.svelte-9thu1j .vega-embed{width:100%!important}.plot.svelte-9thu1j .vega-embed summary{display:none}.fullscreen-host.svelte-9thu1j{position:fixed;top:0;right:0;bottom:0;left:0;z-index:10000;box-sizing:border-box;display:flex;flex-direction:column;background:var(--background-fill-primary, white);padding:12px;gap:8px;pointer-events:auto}.fullscreen-host.svelte-9thu1j:fullscreen{width:100%;height:100%}.fullscreen-host.svelte-9thu1j:-webkit-full-screen{width:100%;height:100%}.fullscreen-toolbar.svelte-9thu1j{flex-shrink:0;display:flex;justify-content:flex-end;gap:4px;z-index:5}.fullscreen-chart-wrap.svelte-9thu1j{flex:1;min-height:0;display:flex;flex-direction:column}.fullscreen-legend.svelte-9thu1j{flex-shrink:0}.fullscreen-plot.svelte-9thu1j{flex:1;min-height:0;width:100%;overflow:hidden}.fullscreen-plot.svelte-9thu1j .vega-embed{width:100%!important;height:100%!important;min-height:0;display:flex;flex-direction:column}.fullscreen-plot.svelte-9thu1j .vega-embed .vega-view{flex:1;min-height:0}.fullscreen-plot.svelte-9thu1j .vega-embed summary{display:none}.custom-legend.svelte-9thu1j{display:flex;align-items:center;justify-content:center;gap:12px;padding:6px 0 0;flex-wrap:wrap}.legend-title.svelte-9thu1j{font-size:11px;color:var(--body-text-color-subdued, #6b7280);font-weight:600}.legend-item.svelte-9thu1j{display:flex;align-items:center;gap:4px}.legend-dot.svelte-9thu1j{width:10px;height:10px;border-radius:50%;flex-shrink:0}.legend-line-swatch.svelte-9thu1j{width:24px;height:10px;flex-shrink:0;color:var(--body-text-color, #1f2937)}.legend-label.svelte-9thu1j{font-size:11px;color:var(--body-text-color-subdued, #6b7280)}.legend-toggle.svelte-9thu1j{font-size:11px;color:var(--body-text-color-subdued, #6b7280);background:none;border:none;padding:0 4px;cursor:pointer;text-decoration:underline}.legend-toggle.svelte-9thu1j:hover{color:var(--body-text-color, #1f2937)}.plot-container.svelte-1swghqy{min-width:350px;flex:1;background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:12px;overflow:hidden;position:relative}.plot-container[draggable=true].svelte-1swghqy{cursor:grab}.plot-container[draggable=true].svelte-1swghqy:active{cursor:grabbing}.hidden-plot.svelte-1swghqy{visibility:hidden;height:0;padding:0;margin:0;border:none;overflow:hidden;pointer-events:none}.drag-handle.svelte-1swghqy{position:absolute;top:8px;left:8px;color:var(--body-text-color-subdued, #9ca3af);opacity:0;transition:opacity .15s;z-index:5}.plot-container.svelte-1swghqy:hover .drag-handle:where(.svelte-1swghqy){opacity:.5}.drag-handle.svelte-1swghqy:hover{opacity:1!important}.plot-toolbar.svelte-1swghqy{position:absolute;top:8px;right:8px;display:flex;gap:4px;z-index:5;opacity:0;transition:opacity .15s}.plot-container.svelte-1swghqy:hover .plot-toolbar:where(.svelte-1swghqy){opacity:1}.toolbar-btn.svelte-1swghqy{border:1px solid var(--border-color-primary, #e5e7eb);background:var(--background-fill-primary, white);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;padding:4px 6px;border-radius:var(--radius-sm, 4px);display:flex;align-items:center;justify-content:center}.toolbar-btn.svelte-1swghqy:hover{background:var(--neutral-100, #f3f4f6);color:var(--body-text-color, #1f2937)}.plot-chart-wrap.svelte-1swghqy{position:relative;width:100%}.plot-chart-wrap--fs.svelte-1swghqy{flex:1;min-height:0;display:flex;flex-direction:column}.plot.svelte-1swghqy{width:100%}.plot.svelte-1swghqy .vega-embed{width:100%!important}.plot.svelte-1swghqy .vega-embed summary{display:none}.fullscreen-host.svelte-1swghqy{position:fixed;top:0;right:0;bottom:0;left:0;z-index:10000;box-sizing:border-box;display:flex;flex-direction:column;background:var(--background-fill-primary, white);padding:12px;gap:8px;pointer-events:auto}.fullscreen-host.svelte-1swghqy:fullscreen{width:100%;height:100%}.fullscreen-host.svelte-1swghqy:-webkit-full-screen{width:100%;height:100%}.fullscreen-toolbar.svelte-1swghqy{flex-shrink:0;display:flex;justify-content:flex-end;gap:4px;z-index:5}.fullscreen-chart-wrap.svelte-1swghqy{flex:1;min-height:0;display:flex;flex-direction:column}.fullscreen-legend.svelte-1swghqy{flex-shrink:0}.fullscreen-plot.svelte-1swghqy{flex:1;min-height:0;width:100%;overflow:hidden}.fullscreen-plot.svelte-1swghqy .vega-embed{width:100%!important;height:100%!important;min-height:0;display:flex;flex-direction:column}.fullscreen-plot.svelte-1swghqy .vega-embed .vega-view{flex:1;min-height:0}.fullscreen-plot.svelte-1swghqy .vega-embed summary{display:none}.custom-legend.svelte-1swghqy{display:flex;align-items:center;justify-content:center;gap:12px;padding:6px 0 0;flex-wrap:wrap}.legend-item.svelte-1swghqy{display:flex;align-items:center;gap:4px}.legend-dot.svelte-1swghqy{width:10px;height:10px;border-radius:50%;flex-shrink:0}.legend-label.svelte-1swghqy{font-size:11px;color:var(--body-text-color-subdued, #6b7280)}.legend-toggle.svelte-1swghqy{font-size:11px;color:var(--body-text-color-subdued, #6b7280);background:none;border:none;padding:0 4px;cursor:pointer;text-decoration:underline}.legend-toggle.svelte-1swghqy:hover{color:var(--body-text-color, #1f2937)}.accordion.svelte-1jep0a{margin-bottom:12px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);background:var(--background-fill-primary, white);overflow:hidden}.accordion-hidden.svelte-1jep0a{margin-bottom:8px}.accordion-header.svelte-1jep0a{display:flex;align-items:center;gap:8px;width:100%;padding:10px 14px;border:none;background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:var(--text-md, 14px);font-weight:600;cursor:pointer;text-align:left}.accordion-header.svelte-1jep0a:hover{background:var(--background-fill-secondary, #f9fafb)}.arrow.svelte-1jep0a{font-size:14px;transition:transform .15s;color:var(--body-text-color, #1f2937);display:inline-block}.arrow.svelte-1jep0a:not(.rotated){transform:rotate(-90deg)}.accordion-body.svelte-1jep0a{padding:0 14px 14px}.trackio-loading.svelte-1kc6b2l{display:flex;align-items:center;justify-content:center;width:100%;min-height:min(70vh,640px);padding:32px 24px;box-sizing:border-box;background:transparent}.logo-stack.svelte-1kc6b2l{position:relative;width:min(100%,200px);max-width:min(92vw,200px);line-height:0;background:transparent;isolation:isolate}.logo-base.svelte-1kc6b2l{display:block;background:transparent}.logo-img.svelte-1kc6b2l{width:100%;height:auto;display:block;background:transparent}.logo-overlay.svelte-1kc6b2l{position:absolute;left:0;top:0;width:100%;animation:svelte-1kc6b2l-trackio-logo-sweep 4s linear infinite;pointer-events:none;background:transparent}.logo-overlay.svelte-1kc6b2l .logo-img:where(.svelte-1kc6b2l){width:100%;height:auto;object-position:left center}.logo-img--gray.svelte-1kc6b2l{filter:grayscale(1)}@keyframes svelte-1kc6b2l-trackio-logo-sweep{0%{clip-path:inset(0 0 0 0)}50%{clip-path:inset(0 0 0 100%)}to{clip-path:inset(0 0 0 0)}}@media(prefers-reduced-motion:reduce){.logo-overlay.svelte-1kc6b2l{display:none}}.sr-only.svelte-1kc6b2l{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.metrics-page.svelte-2bul55{padding:20px 24px;overflow-y:auto;flex:1;min-height:0}.plot-grid.svelte-2bul55{display:flex;flex-wrap:wrap;gap:16px}.subgroup-list.svelte-2bul55{margin-top:16px}.empty-state.svelte-2bul55{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-2bul55 h2:where(.svelte-2bul55){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-2bul55 p:where(.svelte-2bul55){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-2bul55 pre:where(.svelte-2bul55){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-2bul55 code:where(.svelte-2bul55){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-2bul55 pre:where(.svelte-2bul55) code:where(.svelte-2bul55){background:none;padding:0}.traces-page.svelte-1s32ifo{padding:20px 24px;overflow-y:auto;flex:1;background:var(--background-fill-primary, white)}.toolbar.svelte-1s32ifo{display:flex;align-items:center;gap:12px;margin-bottom:16px}.search-wrap.svelte-1s32ifo{flex:1}.search-wrap.svelte-1s32ifo input:where(.svelte-1s32ifo),.filter-wrap.svelte-1s32ifo select:where(.svelte-1s32ifo){width:100%;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:14px;padding:10px 12px;font-family:inherit}.filter-wrap.svelte-1s32ifo{display:flex;align-items:center;gap:8px;color:var(--body-text-color, #1f2937);font-size:14px;white-space:nowrap}.count.svelte-1s32ifo{margin-left:auto;color:var(--body-text-color-subdued, #6b7280);font-size:14px;white-space:nowrap}.traces-table-wrap.svelte-1s32ifo{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);overflow:hidden;transition:opacity .15s ease}.traces-table-wrap.dim.svelte-1s32ifo{opacity:.55}.traces-table.svelte-1s32ifo{width:100%;border-collapse:collapse;font-size:14px;table-layout:fixed}.trace-id-col.svelte-1s32ifo{width:140px}.request-col.svelte-1s32ifo{width:auto}.run-col.svelte-1s32ifo{width:180px}.step-col.svelte-1s32ifo{width:76px}.request-time-col.svelte-1s32ifo{width:150px}.traces-table.svelte-1s32ifo th:where(.svelte-1s32ifo){text-align:left;padding:10px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:12px;text-transform:uppercase;letter-spacing:.05em;background:var(--background-fill-primary, white)}.traces-table.svelte-1s32ifo td:where(.svelte-1s32ifo){padding:10px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937);vertical-align:top}.trace-row.svelte-1s32ifo{cursor:pointer}.trace-row.svelte-1s32ifo:hover{background:var(--background-fill-secondary, #f9fafb)}.trace-id-chip.svelte-1s32ifo{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:13px;color:var(--body-text-color, #1f2937)}.request.svelte-1s32ifo{font-weight:500;margin-bottom:4px}.preview.svelte-1s32ifo{color:var(--body-text-color-subdued, #6b7280);font-size:13px;line-height:1.45;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}.expanded-row.svelte-1s32ifo td:where(.svelte-1s32ifo){padding:0;background:var(--background-fill-secondary, #fafafa)}.trace-detail.svelte-1s32ifo{padding:16px 18px 18px}.detail-meta.svelte-1s32ifo{display:flex;gap:16px;flex-wrap:wrap;color:var(--body-text-color-subdued, #6b7280);font-size:13px;margin-bottom:14px}.conversation.svelte-1s32ifo{display:flex;flex-direction:column;gap:12px}.message.svelte-1s32ifo{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-primary, white);padding:12px}.message-role.svelte-1s32ifo{margin-bottom:8px;color:var(--body-text-color-subdued, #6b7280);font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:.05em;display:flex;align-items:center;gap:8px;flex-wrap:wrap}.message-tag.svelte-1s32ifo{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:999px;padding:2px 8px;font-size:11px;font-weight:500;text-transform:none;letter-spacing:0}.message-content.svelte-1s32ifo,.tool-block.svelte-1s32ifo{margin:0;white-space:pre-wrap;word-break:break-word;font-family:inherit;color:var(--body-text-color, #1f2937);line-height:1.5}.message-details.svelte-1s32ifo summary:where(.svelte-1s32ifo){cursor:pointer;margin-bottom:8px;color:var(--body-text-color-subdued, #6b7280)}.tool-blocks.svelte-1s32ifo{display:flex;flex-direction:column;gap:8px;margin-top:10px}.tool-block.svelte-1s32ifo{background:var(--background-fill-secondary, #f9fafb);border-radius:var(--radius-md, 6px);padding:10px;overflow-x:auto}.message-parts.svelte-1s32ifo{display:flex;flex-direction:column;gap:10px}.trace-image.svelte-1s32ifo{max-width:100%;max-height:360px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px)}.empty-state.svelte-1s32ifo{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1s32ifo h2:where(.svelte-1s32ifo){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1s32ifo p:where(.svelte-1s32ifo){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.pagination.svelte-1s32ifo{display:flex;align-items:center;justify-content:center;gap:12px;padding:16px 0 4px}.pagination.svelte-1s32ifo button:where(.svelte-1s32ifo){border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 6px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:14px;padding:8px 14px;cursor:pointer;font-family:inherit}.pagination.svelte-1s32ifo button:where(.svelte-1s32ifo):hover:not(:disabled){background:var(--background-fill-secondary, #f9fafb)}.pagination.svelte-1s32ifo button:where(.svelte-1s32ifo):disabled{opacity:.5;cursor:not-allowed}.page-info.svelte-1s32ifo{color:var(--body-text-color-subdued, #6b7280);font-size:14px;min-width:120px;text-align:center}@media(max-width:1100px){.toolbar.svelte-1s32ifo{flex-wrap:wrap}.count.svelte-1s32ifo{margin-left:0}}.system-page.svelte-nv5os4{padding:20px 24px;overflow-y:auto;flex:1;min-height:0}.plot-grid.svelte-nv5os4{display:flex;flex-wrap:wrap;gap:12px}.subgroup-list.svelte-nv5os4{margin-top:16px}.empty-state.svelte-nv5os4{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-nv5os4 h2:where(.svelte-nv5os4){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-nv5os4 p:where(.svelte-nv5os4){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-nv5os4 pre:where(.svelte-nv5os4){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-nv5os4 ul:where(.svelte-nv5os4){list-style:disc;padding-left:20px;margin:4px 0 0}.empty-state.svelte-nv5os4 li:where(.svelte-nv5os4){margin:4px 0;color:var(--body-text-color, #1f2937)}.empty-state.svelte-nv5os4 code:where(.svelte-nv5os4){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-nv5os4 pre:where(.svelte-nv5os4) code:where(.svelte-nv5os4){background:none;padding:0}.wave-wrap.svelte-19wbodf{--wave-base: var(--body-text-color-subdued, #9ca3af);--wave-played: var(--color-accent, #f97316);display:flex;align-items:center;gap:8px;padding:8px 10px;background:var(--background-fill-secondary, #f9fafb);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);color:var(--body-text-color, #1f2937)}.play-btn.svelte-19wbodf{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;border-radius:50%;background:var(--color-accent, #f97316);color:#fff;border:none;cursor:pointer;flex-shrink:0;padding:0}.play-btn.svelte-19wbodf:disabled{opacity:.4;cursor:not-allowed}.play-btn.svelte-19wbodf:hover:not(:disabled){filter:brightness(1.1)}.wave.svelte-19wbodf{flex:1;height:32px;min-width:0;cursor:pointer}.time.svelte-19wbodf{font-size:11px;color:var(--body-text-color-subdued, #6b7280);font-variant-numeric:tabular-nums;flex-shrink:0}audio.svelte-19wbodf{display:none}.media-page.svelte-outb32{padding:20px 24px;overflow-y:auto;flex:1}.section.svelte-outb32{margin:16px 0}.section-summary.svelte-outb32{display:flex;align-items:center;gap:6px;cursor:pointer;list-style:none;-webkit-user-select:none;user-select:none;padding:4px 0;margin-bottom:8px}.section-summary.svelte-outb32::-webkit-details-marker{display:none}.chevron.svelte-outb32{color:var(--body-text-color-subdued, #6b7280);transform:rotate(-90deg);transition:transform .15s ease;flex-shrink:0}details[open].svelte-outb32>.section-summary:where(.svelte-outb32) .chevron:where(.svelte-outb32){transform:rotate(0)}.section-title.svelte-outb32{font-size:var(--text-lg, 16px);font-weight:600;color:var(--body-text-color, #1f2937)}.media-label.svelte-outb32{font-size:var(--text-sm, 12px);font-weight:500;color:var(--body-text-color, #1f2937);word-break:break-word}.meta.svelte-outb32{display:flex;align-items:center;gap:3px;font-size:var(--text-xs, 11px);color:var(--body-text-color-subdued, #9ca3af);font-variant-numeric:tabular-nums}.meta.svelte-outb32 .run-dot:where(.svelte-outb32){width:8px;height:8px;border-radius:50%;flex-shrink:0;margin:0 2px}.meta-text.svelte-outb32{white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.table-header.svelte-outb32{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:6px}.runs-table.svelte-outb32{width:100%;border-collapse:collapse;font-size:var(--text-md, 14px)}.runs-table.svelte-outb32 th:where(.svelte-outb32){text-align:left;padding:8px 12px;border-bottom:2px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:var(--text-sm, 12px);text-transform:uppercase;letter-spacing:.05em}.runs-table.svelte-outb32 td:where(.svelte-outb32){padding:8px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.runs-table.svelte-outb32 tbody:where(.svelte-outb32) tr:where(.svelte-outb32):nth-child(odd){background:var(--table-odd-background-fill, var(--background-fill-primary, white))}.runs-table.svelte-outb32 tbody:where(.svelte-outb32) tr:where(.svelte-outb32):nth-child(2n){background:var(--table-even-background-fill, var(--background-fill-secondary, #f9fafb))}.runs-table.svelte-outb32 tr:where(.svelte-outb32):hover{background:var(--background-fill-secondary, #f3f4f6)}.table-image.svelte-outb32{max-height:80px;max-width:120px;border-radius:var(--radius-sm, 4px);display:block;object-fit:contain}.table-image-list.svelte-outb32{display:flex;flex-wrap:wrap;gap:4px}.gallery.svelte-outb32{display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:12px}.gallery-item.svelte-outb32{display:flex;flex-direction:column;gap:6px;padding:8px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);background:var(--background-fill-secondary, #f9fafb);overflow:hidden}.gallery-item.svelte-outb32 img:where(.svelte-outb32),.gallery-item.svelte-outb32 video:where(.svelte-outb32){width:100%;display:block;border-radius:var(--radius-sm, 4px)}.audio-gallery-item.svelte-outb32{justify-content:space-between}.caption.svelte-outb32{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #9ca3af)}.table-section.svelte-outb32{margin-bottom:16px;overflow-x:auto}.empty-state.svelte-outb32{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-outb32 h2:where(.svelte-outb32){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-outb32 p:where(.svelte-outb32){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-outb32 pre:where(.svelte-outb32){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-outb32 code:where(.svelte-outb32){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-outb32 pre:where(.svelte-outb32) code:where(.svelte-outb32){background:none;padding:0}.reports-page.svelte-iufsej{padding:20px 24px;overflow-y:auto;flex:1}.controls.svelte-iufsej{display:flex;gap:16px;margin-bottom:16px;flex-wrap:wrap;align-items:flex-end}.control.svelte-iufsej{min-width:200px}.filter-pills.svelte-iufsej{display:flex;gap:4px}.pill.svelte-iufsej{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-xxl, 22px);padding:4px 12px;font-size:var(--text-sm, 12px);background:var(--background-fill-secondary, #f9fafb);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;transition:background-color .15s,color .15s}.pill.svelte-iufsej:hover{background:var(--neutral-100, #f3f4f6)}.pill.active.svelte-iufsej{background:var(--color-accent, #f97316);color:#fff;border-color:var(--color-accent, #f97316)}.empty-state.svelte-iufsej{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-iufsej h2:where(.svelte-iufsej){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-iufsej p:where(.svelte-iufsej){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-iufsej pre:where(.svelte-iufsej){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-iufsej code:where(.svelte-iufsej){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-iufsej pre:where(.svelte-iufsej) code:where(.svelte-iufsej){background:none;padding:0}.alerts-table.svelte-iufsej{width:100%;border-collapse:collapse;font-size:var(--text-md, 14px)}.alerts-table.svelte-iufsej th:where(.svelte-iufsej){text-align:left;padding:8px 12px;border-bottom:2px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:var(--text-sm, 12px);text-transform:uppercase;letter-spacing:.05em}.alerts-table.svelte-iufsej td:where(.svelte-iufsej){padding:8px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.alerts-table.svelte-iufsej tbody:where(.svelte-iufsej) tr:where(.svelte-iufsej):nth-child(odd){background:var(--table-odd-background-fill, var(--background-fill-primary, white))}.alerts-table.svelte-iufsej tbody:where(.svelte-iufsej) tr:where(.svelte-iufsej):nth-child(2n){background:var(--table-even-background-fill, var(--background-fill-secondary, #f9fafb))}.alerts-table.svelte-iufsej tr:where(.svelte-iufsej):hover{background:var(--background-fill-secondary, #f3f4f6)}.section-title.svelte-iufsej{font-size:16px;font-weight:700;margin:0 0 12px;color:var(--body-text-color, #1f2937)}.reports-section.svelte-iufsej,.alerts-section.svelte-iufsej{margin-bottom:32px}.report-card.svelte-iufsej{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:16px 20px;margin-bottom:12px;background:var(--background-fill-primary, white)}.report-meta.svelte-iufsej{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);margin-bottom:8px}.report-content.svelte-iufsej{font-size:var(--text-md, 14px);color:var(--body-text-color, #1f2937);line-height:1.6}.report-content.svelte-iufsej h2{font-size:18px;font-weight:700;margin:0 0 8px}.report-content.svelte-iufsej h3{font-size:16px;font-weight:600;margin:12px 0 6px}.report-content.svelte-iufsej h4{font-size:14px;font-weight:600;margin:10px 0 4px}.report-content.svelte-iufsej code{background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.report-content.svelte-iufsej ul{margin:4px 0;padding-left:20px}.report-content.svelte-iufsej li{margin:2px 0}.report-content.svelte-iufsej p{margin:6px 0}.filter-empty.svelte-iufsej{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-md, 14px)}.runs-page.svelte-1yb6d54{padding:20px 24px;overflow-y:auto;flex:1}.empty-state.svelte-1yb6d54{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1yb6d54 h2:where(.svelte-1yb6d54){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1yb6d54 p:where(.svelte-1yb6d54){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-1yb6d54 pre:where(.svelte-1yb6d54){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-1yb6d54 code:where(.svelte-1yb6d54){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-1yb6d54 pre:where(.svelte-1yb6d54) code:where(.svelte-1yb6d54){background:none;padding:0}.filter-count-row.svelte-1yb6d54{margin-bottom:12px}.filter-count.svelte-1yb6d54{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.runs-table.svelte-1yb6d54{width:100%;border-collapse:collapse;font-size:var(--text-md, 14px)}.runs-table.svelte-1yb6d54 th:where(.svelte-1yb6d54){text-align:left;padding:8px 12px;border-bottom:2px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color-subdued, #6b7280);font-weight:600;font-size:var(--text-sm, 12px);text-transform:uppercase;letter-spacing:.05em}.runs-table.svelte-1yb6d54 td:where(.svelte-1yb6d54){padding:8px 12px;border-bottom:1px solid var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.runs-table.svelte-1yb6d54 tbody:where(.svelte-1yb6d54) tr:where(.svelte-1yb6d54):nth-child(odd){background:var(--table-odd-background-fill, var(--background-fill-primary, white))}.runs-table.svelte-1yb6d54 tbody:where(.svelte-1yb6d54) tr:where(.svelte-1yb6d54):nth-child(2n){background:var(--table-even-background-fill, var(--background-fill-secondary, #f9fafb))}.runs-table.svelte-1yb6d54 tr:where(.svelte-1yb6d54):hover{background:var(--background-fill-secondary, #f3f4f6)}.run-name-cell.svelte-1yb6d54{font-weight:500}.run-name-with-dot.svelte-1yb6d54{display:inline-flex;align-items:center;gap:8px;max-width:100%}.run-dot.svelte-1yb6d54{width:10px;height:10px;border-radius:50%;flex-shrink:0}.link-btn.svelte-1yb6d54{background:none;border:none;color:var(--color-accent, #f97316);cursor:pointer;font:inherit;font-weight:500;padding:0;text-align:left}.link-btn.svelte-1yb6d54:hover{text-decoration:underline}.rename-input.svelte-1yb6d54{font:inherit;padding:2px 6px;border:1px solid var(--color-accent, #f97316);border-radius:var(--radius-sm, 4px);outline:none;width:100%}.actions-wrap.svelte-1yb6d54{display:flex;gap:4px;align-items:center}.action-btn.svelte-1yb6d54{background:none;border:1px solid transparent;color:var(--body-text-color-subdued, #6b7280);cursor:pointer;padding:4px;border-radius:var(--radius-sm, 4px);display:flex;align-items:center}.action-btn.svelte-1yb6d54:hover{background:var(--background-fill-secondary, #f9fafb);border-color:var(--border-color-primary, #e5e7eb);color:var(--body-text-color, #1f2937)}.delete-btn.svelte-1yb6d54:hover{color:#dc2626;border-color:#fecaca;background:#fef2f2}.action-btn.svelte-1yb6d54:disabled{opacity:.45;cursor:not-allowed;pointer-events:none}.run-detail-page.svelte-1bpgsx2{padding:20px 24px;overflow-y:auto;flex:1}.detail-card.svelte-1bpgsx2{background:var(--background-fill-primary, white);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);padding:24px;max-width:800px}.detail-card.svelte-1bpgsx2 h2:where(.svelte-1bpgsx2){color:var(--body-text-color, #1f2937);margin:0 0 16px;font-size:var(--text-xl, 22px)}.detail-card.svelte-1bpgsx2 h3:where(.svelte-1bpgsx2){color:var(--body-text-color, #1f2937);margin:20px 0 8px;font-size:var(--text-lg, 16px)}.detail-grid.svelte-1bpgsx2{display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:12px}.detail-item.svelte-1bpgsx2{display:flex;flex-direction:column;gap:2px}.detail-label.svelte-1bpgsx2{font-size:var(--text-xs, 10px);font-weight:600;color:var(--body-text-color-subdued, #9ca3af);text-transform:uppercase}.detail-value.svelte-1bpgsx2{font-size:var(--text-md, 14px);color:var(--body-text-color, #1f2937)}.config-block.svelte-1bpgsx2{background:var(--background-fill-secondary, #f9fafb);padding:12px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:var(--text-sm, 12px);color:var(--body-text-color, #1f2937);overflow-x:auto}.empty-state.svelte-1bpgsx2{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1bpgsx2 h2:where(.svelte-1bpgsx2){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1bpgsx2 p:where(.svelte-1bpgsx2){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-1bpgsx2 pre:where(.svelte-1bpgsx2){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-1bpgsx2 code:where(.svelte-1bpgsx2){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-1bpgsx2 pre:where(.svelte-1bpgsx2) code:where(.svelte-1bpgsx2){background:none;padding:0}.files-page.svelte-1xvfk9n{padding:20px 24px;overflow-y:auto;flex:1}.page-title.svelte-1xvfk9n{color:var(--body-text-color, #1f2937);font-size:16px;font-weight:700;margin:0 0 4px}.page-subtitle.svelte-1xvfk9n{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);margin:0 0 16px}.file-list.svelte-1xvfk9n{display:flex;flex-direction:column;gap:4px}.file-item.svelte-1xvfk9n{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);background:var(--background-fill-primary, white);overflow:hidden}.file-item.expanded.svelte-1xvfk9n{border-color:var(--color-accent, #f97316)}.file-row.svelte-1xvfk9n{display:flex;align-items:center;justify-content:space-between;padding:10px 14px;gap:12px}.file-name.svelte-1xvfk9n{display:flex;align-items:center;gap:8px;background:none;border:none;padding:0;font-size:var(--text-md, 14px);color:var(--body-text-color, #1f2937);cursor:pointer;text-align:left}.file-name.svelte-1xvfk9n:hover{color:var(--color-accent, #f97316)}.file-icon.svelte-1xvfk9n{font-size:14px;flex-shrink:0}.file-actions.svelte-1xvfk9n{display:flex;align-items:center;gap:12px;flex-shrink:0}.file-size.svelte-1xvfk9n{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);white-space:nowrap}.download-btn.svelte-1xvfk9n{display:flex;align-items:center;justify-content:center;width:28px;height:28px;border-radius:var(--radius-md, 6px);color:var(--body-text-color-subdued, #6b7280);transition:background-color .15s,color .15s}.download-btn.svelte-1xvfk9n:hover{background:var(--background-fill-secondary, #f3f4f6);color:var(--body-text-color, #1f2937)}.file-preview.svelte-1xvfk9n{border-top:1px solid var(--border-color-primary, #e5e7eb);padding:12px 14px;background:var(--background-fill-secondary, #f9fafb)}.preview-code.svelte-1xvfk9n{margin:0;font-size:12px;line-height:1.5;max-height:400px;overflow:auto;white-space:pre-wrap;word-break:break-all;color:var(--body-text-color, #1f2937)}.preview-loading.svelte-1xvfk9n,.preview-unavailable.svelte-1xvfk9n{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);padding:8px 0}.preview-unavailable.svelte-1xvfk9n a:where(.svelte-1xvfk9n){color:var(--color-accent, #f97316);text-decoration:none}.preview-unavailable.svelte-1xvfk9n a:where(.svelte-1xvfk9n):hover{text-decoration:underline}.empty-state.svelte-1xvfk9n{max-width:640px;padding:40px 24px;color:var(--body-text-color, #1f2937)}.empty-state.svelte-1xvfk9n h2:where(.svelte-1xvfk9n){margin:0 0 8px;font-size:20px;font-weight:700}.empty-state.svelte-1xvfk9n p:where(.svelte-1xvfk9n){margin:12px 0 8px;color:var(--body-text-color-subdued, #6b7280)}.empty-state.svelte-1xvfk9n pre:where(.svelte-1xvfk9n){background:var(--background-fill-secondary, #f9fafb);padding:16px;border-radius:var(--radius-lg, 8px);border:1px solid var(--border-color-primary, #e5e7eb);font-size:13px;overflow-x:auto}.empty-state.svelte-1xvfk9n code:where(.svelte-1xvfk9n){background:var(--background-fill-secondary, #f0f0f0);padding:1px 5px;border-radius:var(--radius-sm, 4px);font-size:13px}.empty-state.svelte-1xvfk9n pre:where(.svelte-1xvfk9n) code:where(.svelte-1xvfk9n){background:none;padding:0}.settings-page.svelte-1ozf5k3{padding:24px 32px;overflow-y:auto;flex:1}.page-title.svelte-1ozf5k3{color:var(--body-text-color, #1f2937);font-size:18px;font-weight:700;margin:0 0 24px}.two-col.svelte-1ozf5k3{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:32px;align-items:start}@media(max-width:900px){.two-col.svelte-1ozf5k3{grid-template-columns:1fr}}.settings-section.svelte-1ozf5k3{margin-bottom:32px}.section-title.svelte-1ozf5k3{color:var(--body-text-color, #1f2937);font-size:15px;font-weight:600;margin:0 0 4px}.section-desc.svelte-1ozf5k3{color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);margin:0 0 12px;line-height:1.5}.section-desc.svelte-1ozf5k3 code:where(.svelte-1ozf5k3){background:var(--background-fill-secondary, #f3f4f6);padding:1px 5px;border-radius:var(--radius-sm, 3px);font-size:11px}.section-desc.svelte-1ozf5k3 strong:where(.svelte-1ozf5k3){color:var(--color-accent, #f97316)}.theme-switcher.svelte-1ozf5k3{display:inline-flex;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);overflow:hidden}.theme-option.svelte-1ozf5k3{display:inline-flex;align-items:center;gap:6px;padding:8px 20px;border:none;background:var(--background-fill-primary, white);color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-md, 14px);cursor:pointer;transition:all .15s;border-right:1px solid var(--border-color-primary, #e5e7eb)}.theme-option.svelte-1ozf5k3:last-child{border-right:none}.theme-option.svelte-1ozf5k3:hover{color:var(--body-text-color, #1f2937);background:var(--background-fill-secondary, #f9fafb)}.theme-option.selected.svelte-1ozf5k3{background:var(--color-accent, #f97316);color:#fff;font-weight:500}.project-selector.svelte-1ozf5k3{display:flex;align-items:center;gap:10px;margin-bottom:12px}.selector-label.svelte-1ozf5k3{font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280);flex-shrink:0}.selector-select.svelte-1ozf5k3{padding:6px 10px;border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 4px);background:var(--background-fill-primary, white);color:var(--body-text-color, #1f2937);font-size:var(--text-sm, 12px);min-width:160px;cursor:pointer}.selector-select.svelte-1ozf5k3:focus{outline:none;border-color:var(--color-accent, #f97316)}.commands-table.svelte-1ozf5k3{border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-lg, 8px);overflow:hidden}.command-row.svelte-1ozf5k3{display:flex;align-items:center;gap:16px;padding:10px 14px;border-bottom:1px solid var(--border-color-primary, #e5e7eb)}.command-row.svelte-1ozf5k3:last-child{border-bottom:none}.command-label.svelte-1ozf5k3{width:180px;flex-shrink:0;font-size:var(--text-sm, 12px);color:var(--body-text-color-subdued, #6b7280)}.command-value.svelte-1ozf5k3{flex:1;display:flex;align-items:center;gap:8px;min-width:0}.command-value.svelte-1ozf5k3 code:where(.svelte-1ozf5k3){flex:1;font-family:SFMono-Regular,Consolas,Liberation Mono,Menlo,monospace;font-size:12px;color:var(--body-text-color, #1f2937);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.copy-btn.svelte-1ozf5k3{display:flex;align-items:center;justify-content:center;width:26px;height:26px;flex-shrink:0;border:none;background:none;border-radius:var(--radius-md, 4px);color:var(--body-text-color-subdued, #6b7280);cursor:pointer;transition:background-color .15s,color .15s}.copy-btn.svelte-1ozf5k3:hover{background:var(--background-fill-secondary, #f3f4f6);color:var(--body-text-color, #1f2937)}.copy-btn.copied.svelte-1ozf5k3{color:var(--color-accent, #f97316)}.agent-tabs.svelte-1ozf5k3{display:flex;border-bottom:1px solid var(--border-color-primary, #e5e7eb);gap:0;margin-bottom:0}.agent-tab.svelte-1ozf5k3{padding:8px 16px;border:none;background:none;color:var(--body-text-color-subdued, #6b7280);font-size:var(--text-sm, 12px);cursor:pointer;border-bottom:2px solid transparent;transition:all .15s;white-space:nowrap}.agent-tab.svelte-1ozf5k3:hover{color:var(--body-text-color, #1f2937)}.agent-tab.active.svelte-1ozf5k3{color:var(--color-accent, #f97316);border-bottom-color:var(--color-accent, #f97316);font-weight:500}.agent-panel.svelte-1ozf5k3{border:1px solid var(--border-color-primary, #e5e7eb);border-top:none;border-radius:0 0 var(--radius-lg, 8px) var(--radius-lg, 8px);padding:16px}.install-block.svelte-1ozf5k3{margin-bottom:16px}.install-label.svelte-1ozf5k3{display:block;font-size:11px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);text-transform:uppercase;letter-spacing:.04em;margin-bottom:6px}.install-cmd.svelte-1ozf5k3{display:flex;align-items:center;gap:8px;background:var(--background-fill-secondary, #f3f4f6);border-radius:var(--radius-md, 4px);padding:8px 10px}.install-cmd.svelte-1ozf5k3 code:where(.svelte-1ozf5k3){flex:1;font-family:SFMono-Regular,Consolas,Liberation Mono,Menlo,monospace;font-size:12px;color:var(--body-text-color, #1f2937);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.example-block.svelte-1ozf5k3{background:var(--background-fill-secondary, #f9fafb);border:1px solid var(--border-color-primary, #e5e7eb);border-radius:var(--radius-md, 4px);padding:12px}.example-header.svelte-1ozf5k3{display:flex;align-items:center;justify-content:space-between;margin-bottom:8px}.example-label.svelte-1ozf5k3{font-size:11px;font-weight:500;color:var(--body-text-color-subdued, #6b7280);text-transform:uppercase;letter-spacing:.04em}.example-text.svelte-1ozf5k3{margin:0;font-size:var(--text-sm, 12px);color:var(--body-text-color, #1f2937);line-height:1.6;font-style:italic}*{margin:0;padding:0;box-sizing:border-box}body{font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif;background:var(--background-fill-primary, #fff);color:var(--body-text-color, #1f2937);font-size:var(--text-md, 14px);-webkit-font-smoothing:antialiased}.app.svelte-1n46o8q{display:flex;height:100vh;overflow:hidden}.main.svelte-1n46o8q{flex:1;display:flex;flex-direction:column;overflow:hidden;min-width:0}.page-content.svelte-1n46o8q{flex:1;overflow:hidden;display:flex;background:var(--bg-primary)}

trackio/frontend/dist/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Trackio Dashboard</title>
+    <link rel="icon" type="image/png" href="/static/trackio/trackio_logo_light.png" />
+    <script type="module" crossorigin src="/assets/index-lHoXQDkP.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BcnSteuj.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

trackio/frontend/eslint.config.js

@@ -0,0 +1,42 @@
+import js from "@eslint/js";
+import svelte from "eslint-plugin-svelte";
+import svelteParser from "svelte-eslint-parser";
+import globals from "globals";
+
+export default [
+  { ignores: ["dist/**", "node_modules/**"] },
+  {
+    files: ["**/*.js"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.es2021,
+        $state: "readonly",
+        $derived: "readonly",
+        $effect: "readonly",
+        $props: "readonly",
+        $bindable: "readonly",
+        $inspect: "readonly",
+      },
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      "no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "no-empty": "off",
+    },
+  },
+  {
+    files: ["**/*.svelte"],
+    languageOptions: {
+      parser: svelteParser,
+      globals: { ...globals.browser, ...globals.es2021 },
+    },
+    plugins: { svelte },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...svelte.configs.recommended.rules,
+      "no-unused-vars": ["error", { argsIgnorePattern: "^_", varsIgnorePattern: "^\\$" }],
+      "no-empty": "off",
+    },
+  },
+];

trackio/frontend/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Trackio Dashboard</title>
+    <link rel="icon" type="image/png" href="/static/trackio/trackio_logo_light.png" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

trackio/frontend_config.py

@@ -0,0 +1,175 @@
+import json
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from huggingface_hub.constants import HF_HOME
+
+TRACKIO_USER_HOME = Path(HF_HOME) / "trackio"
+TRACKIO_CONFIG_PATH = TRACKIO_USER_HOME / "config.json"
+BUNDLED_FRONTEND_DIR = Path(__file__).parent / "frontend" / "dist"
+STARTER_FRONTEND_DIR = Path(__file__).parent / "frontend_templates" / "starter"
+
+
+@dataclass(frozen=True)
+class ResolvedFrontend:
+    path: Path
+    source: str
+    is_custom: bool
+    used_fallback: bool = False
+    requested_path: Path | None = None
+
+
+def _normalize_frontend_path(path: str | Path) -> Path:
+    return Path(path).expanduser().resolve()
+
+
+def is_valid_frontend_dir(path: str | Path | None) -> bool:
+    if path is None:
+        return False
+    frontend_dir = _normalize_frontend_path(path)
+    return frontend_dir.is_dir() and (frontend_dir / "index.html").is_file()
+
+
+def _is_empty_directory(path: Path) -> bool:
+    return path.is_dir() and not any(path.iterdir())
+
+
+def _copy_starter_template(destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    for child in STARTER_FRONTEND_DIR.iterdir():
+        target = destination / child.name
+        if child.is_dir():
+            shutil.copytree(child, target, dirs_exist_ok=True)
+        else:
+            shutil.copy2(child, target)
+
+
+def _materialize_argument_frontend_dir(candidate: Path) -> bool:
+    existed_before = candidate.exists()
+    if existed_before and not _is_empty_directory(candidate):
+        return False
+
+    _copy_starter_template(candidate)
+    state = "did not exist" if not existed_before else "was empty"
+    print(
+        f"* Trackio frontend directory from argument {state}: {candidate}. "
+        "Copied the starter template into it and serving that directory."
+    )
+    return True
+
+
+def load_trackio_config() -> dict:
+    if not TRACKIO_CONFIG_PATH.is_file():
+        return {}
+    try:
+        data = json.loads(TRACKIO_CONFIG_PATH.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_trackio_config(config: dict) -> None:
+    TRACKIO_USER_HOME.mkdir(parents=True, exist_ok=True)
+    TRACKIO_CONFIG_PATH.write_text(json.dumps(config, indent=2, sort_keys=True) + "\n")
+
+
+def get_persisted_frontend_dir() -> Path | None:
+    frontend_dir = load_trackio_config().get("frontend_dir")
+    if not frontend_dir:
+        return None
+    return _normalize_frontend_path(frontend_dir)
+
+
+def set_persisted_frontend_dir(path: str | Path) -> Path:
+    frontend_dir = _normalize_frontend_path(path)
+    if not is_valid_frontend_dir(frontend_dir):
+        raise ValueError(
+            f"Invalid frontend directory: {frontend_dir}. Expected a directory containing index.html."
+        )
+    config = load_trackio_config()
+    config["frontend_dir"] = str(frontend_dir)
+    save_trackio_config(config)
+    return frontend_dir
+
+
+def unset_persisted_frontend_dir() -> bool:
+    config = load_trackio_config()
+    if "frontend_dir" not in config:
+        return False
+    del config["frontend_dir"]
+    if config:
+        save_trackio_config(config)
+    elif TRACKIO_CONFIG_PATH.exists():
+        TRACKIO_CONFIG_PATH.unlink()
+    return True
+
+
+def _configured_frontend_candidates(
+    frontend_dir: str | Path | None,
+) -> list[tuple[str, Path]]:
+    candidates: list[tuple[str, Path]] = []
+    if frontend_dir is not None:
+        candidates.append(("argument", _normalize_frontend_path(frontend_dir)))
+    env_dir = os.environ.get("TRACKIO_FRONTEND_DIR")
+    if env_dir:
+        candidates.append(("env", _normalize_frontend_path(env_dir)))
+    persisted_dir = get_persisted_frontend_dir()
+    if persisted_dir is not None:
+        candidates.append(("config", persisted_dir))
+    return candidates
+
+
+def _announce_config_frontend(frontend_dir: Path) -> None:
+    print(
+        f"* Using Trackio custom frontend from config: {frontend_dir}\n"
+        "  Reset with `trackio config unset frontend`."
+    )
+
+
+def resolve_frontend_dir(
+    frontend_dir: str | Path | None = None,
+    *,
+    announce: bool = False,
+) -> ResolvedFrontend:
+    for source, candidate in _configured_frontend_candidates(frontend_dir):
+        if source == "argument":
+            if not candidate.exists() or _is_empty_directory(candidate):
+                _materialize_argument_frontend_dir(candidate)
+
+        if is_valid_frontend_dir(candidate):
+            if source == "config" and announce:
+                _announce_config_frontend(candidate)
+            return ResolvedFrontend(
+                path=candidate,
+                source=source,
+                is_custom=True,
+            )
+        if source == "argument":
+            print(
+                f"* Trackio frontend from {source} is invalid: {candidate}. "
+                f"Falling back to starter template at {STARTER_FRONTEND_DIR}."
+            )
+            return ResolvedFrontend(
+                path=STARTER_FRONTEND_DIR,
+                source="starter",
+                is_custom=True,
+                used_fallback=True,
+                requested_path=candidate,
+            )
+        print(f"* Trackio frontend from {source} is invalid: {candidate}. Ignoring it.")
+
+    if is_valid_frontend_dir(BUNDLED_FRONTEND_DIR):
+        return ResolvedFrontend(
+            path=BUNDLED_FRONTEND_DIR,
+            source="bundled",
+            is_custom=False,
+        )
+
+    return ResolvedFrontend(
+        path=STARTER_FRONTEND_DIR,
+        source="starter",
+        is_custom=True,
+        used_fallback=True,
+    )

trackio/frontend_server.py

@@ -0,0 +1,145 @@
+"""Serves a static frontend alongside the Trackio HTTP API."""
+
+import hashlib
+import logging
+from pathlib import Path
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import FileResponse, HTMLResponse, JSONResponse
+from starlette.routing import Mount, Route
+from starlette.staticfiles import StaticFiles
+
+ASSETS_DIR = Path(__file__).parent / "assets"
+
+_logger = logging.getLogger(__name__)
+
+_LIVE_RELOAD_SCRIPT = """
+<script>
+(() => {
+  const endpoint = "/__trackio/frontend_version";
+  let currentVersion = null;
+
+  async function poll() {
+    try {
+      const response = await fetch(endpoint, { cache: "no-store" });
+      const payload = await response.json();
+      if (currentVersion === null) {
+        currentVersion = payload.version;
+        return;
+      }
+      if (payload.version !== currentVersion) {
+        window.location.reload();
+      }
+    } catch (error) {
+      console.warn("Trackio live reload poll failed", error);
+    }
+  }
+
+  poll();
+  setInterval(poll, 1000);
+})();
+</script>
+""".strip()
+
+
+def _frontend_version(frontend_root: Path) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(frontend_root.rglob("*")):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(frontend_root)
+        digest.update(str(relative).encode("utf-8"))
+        stat = path.stat()
+        digest.update(str(stat.st_mtime_ns).encode("utf-8"))
+        digest.update(str(stat.st_size).encode("utf-8"))
+    return digest.hexdigest()
+
+
+def _inject_live_reload(html: str) -> str:
+    if "/__trackio/frontend_version" in html:
+        return html
+    if "</body>" in html:
+        return html.replace("</body>", f"{_LIVE_RELOAD_SCRIPT}\n  </body>")
+    return html + _LIVE_RELOAD_SCRIPT
+
+
+def _html_response(path: Path) -> HTMLResponse:
+    html = path.read_text(encoding="utf-8")
+    return HTMLResponse(_inject_live_reload(html))
+
+
+class FrontendMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, frontend_root: Path, index_html_path: Path):
+        super().__init__(app)
+        self.frontend_root = frontend_root
+        self.index_html_path = index_html_path
+        self.reserved_prefixes = (
+            "/api/",
+            "/file",
+            "/version",
+            "/static/trackio",
+            "/__trackio/frontend_version",
+            "/oauth/",
+            "/login/",
+            "/mcp",
+        )
+        self.reserved_exact = {
+            "/api",
+            "/oauth",
+            "/login",
+        }
+
+    async def dispatch(self, request, call_next):
+        if request.method not in {"GET", "HEAD"}:
+            return await call_next(request)
+
+        path = request.url.path
+        if path in self.reserved_exact or path.startswith(self.reserved_prefixes):
+            return await call_next(request)
+
+        relative_path = path.lstrip("/")
+        requested_path = (self.frontend_root / relative_path).resolve()
+        if (
+            relative_path
+            and requested_path.is_file()
+            and requested_path.is_relative_to(self.frontend_root)
+        ):
+            if requested_path.suffix.lower() == ".html":
+                return _html_response(requested_path)
+            return FileResponse(requested_path)
+
+        return _html_response(self.index_html_path)
+
+
+def mount_frontend(app, frontend_dir: str | Path):
+    frontend_root = Path(frontend_dir).resolve()
+    if not frontend_root.exists():
+        _logger.warning(
+            "Trackio dashboard UI was not mounted: %s is missing. "
+            "Build the frontend or provide a custom frontend directory.",
+            frontend_root,
+        )
+        return
+
+    index_html_path = frontend_root / "index.html"
+    if not index_html_path.exists():
+        _logger.warning(
+            "Trackio dashboard UI was not mounted: %s is missing.",
+            index_html_path,
+        )
+        return
+
+    async def frontend_version(_request):
+        return JSONResponse({"version": _frontend_version(frontend_root)})
+
+    static_assets = StaticFiles(directory=str(ASSETS_DIR))
+
+    app.add_middleware(
+        FrontendMiddleware,
+        frontend_root=frontend_root,
+        index_html_path=index_html_path,
+    )
+    app.routes.append(Mount("/static/trackio", app=static_assets))
+    app.routes.append(
+        Route("/__trackio/frontend_version", frontend_version, methods=["GET"])
+    )

trackio/frontend_templates/starter/app.js

@@ -0,0 +1,555 @@
+const projectSelectEl = document.querySelector("#project-select");
+const runListEl = document.querySelector("#run-list");
+const metricsTitleEl = document.querySelector("#metrics-title");
+const metricsSubtitleEl = document.querySelector("#metrics-subtitle");
+const metricsGridEl = document.querySelector("#metrics-grid");
+const tracesSubtitleEl = document.querySelector("#traces-subtitle");
+const tracesBodyEl = document.querySelector("#traces-body");
+const navButtons = Array.from(document.querySelectorAll(".nav-link"));
+const pages = Array.from(document.querySelectorAll(".page"));
+
+const state = {
+  projects: [],
+  selectedProject: null,
+  runs: [],
+  selectedRunIds: [],
+};
+
+/*
+Trackio routes used by this starter today:
+- /api/get_all_projects
+- /api/get_runs_for_project
+- /api/get_metrics_for_run
+- /api/get_metric_values
+- /api/get_traces
+
+Useful routes for expanding this starter toward the full dashboard:
+- /api/get_system_metrics_for_run
+- /api/get_system_logs
+- /api/get_system_logs_batch
+- /api/get_logs
+- /api/get_logs_batch
+- /api/get_snapshot
+- /api/get_alerts
+- /api/query_project
+- /api/get_project_summary
+- /api/get_run_summary
+- /api/get_project_files
+- /api/get_settings
+- /api/get_run_mutation_status
+- /api/delete_run
+- /api/rename_run
+- /api/force_sync
+- /api/bulk_upload_media
+- /api/upload
+
+File/media URLs:
+- /file?path=ABSOLUTE_PATH_FROM_API
+*/
+const RUN_COLORS = [
+  "#1f77b4",
+  "#ff7f0e",
+  "#2ca02c",
+  "#d62728",
+  "#9467bd",
+  "#8c564b",
+  "#e377c2",
+  "#7f7f7f",
+  "#bcbd22",
+  "#17becf",
+];
+
+async function api(name, payload = {}) {
+  const response = await fetch(`/api/${name}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const json = await response.json();
+  if (!response.ok || json.error) {
+    throw new Error(json.error || `Request failed for ${name}`);
+  }
+  return json.data;
+}
+
+function runKey(run) {
+  return run.id || run.name;
+}
+
+function colorForRun(run) {
+  const index = state.runs.findIndex((candidate) => runKey(candidate) === runKey(run));
+  return RUN_COLORS[((index >= 0 ? index : 0) % RUN_COLORS.length + RUN_COLORS.length) % RUN_COLORS.length];
+}
+
+function formatValue(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return String(value);
+  }
+  if (Math.abs(value) >= 1000 || Math.abs(value) < 0.01) {
+    return value.toExponential(2);
+  }
+  return value.toFixed(3);
+}
+
+function getQueryParams() {
+  return new URLSearchParams(window.location.search);
+}
+
+function setQueryParams(params) {
+  const next = new URL(window.location.href);
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null || value === "" || (Array.isArray(value) && value.length === 0)) {
+      next.searchParams.delete(key);
+      continue;
+    }
+    next.searchParams.set(key, Array.isArray(value) ? value.join(",") : value);
+  }
+  window.history.replaceState({}, "", next);
+}
+
+function setActivePage(pageName) {
+  navButtons.forEach((button) => {
+    button.classList.toggle("active", button.dataset.pageTarget === pageName);
+  });
+  pages.forEach((page) => {
+    page.classList.toggle("active", page.dataset.page === pageName);
+  });
+}
+
+function bindNavigation() {
+  navButtons.forEach((button) => {
+    button.addEventListener("click", () => setActivePage(button.dataset.pageTarget));
+  });
+}
+
+function pickInitialProject(projects) {
+  const params = getQueryParams();
+  const project = params.get("project");
+  if (project && projects.includes(project)) {
+    return project;
+  }
+  return projects[0] || null;
+}
+
+function pickInitialRunIds(runs) {
+  const params = getQueryParams();
+  const fromUrl = (params.get("run_ids") || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  const validIds = runs.map(runKey);
+  const selected = fromUrl.filter((id) => validIds.includes(id));
+  if (selected.length) {
+    return selected;
+  }
+  return runs.slice(0, 2).map(runKey);
+}
+
+function renderProjectSelect() {
+  projectSelectEl.innerHTML = "";
+  if (!state.projects.length) {
+    const option = document.createElement("option");
+    option.value = "";
+    option.textContent = "No projects";
+    projectSelectEl.appendChild(option);
+    projectSelectEl.disabled = true;
+    return;
+  }
+
+  projectSelectEl.disabled = false;
+  for (const project of state.projects) {
+    const option = document.createElement("option");
+    option.value = project;
+    option.textContent = project;
+    option.selected = project === state.selectedProject;
+    projectSelectEl.appendChild(option);
+  }
+}
+
+function renderRunList() {
+  runListEl.innerHTML = "";
+  if (!state.runs.length) {
+    const empty = document.createElement("div");
+    empty.className = "sidebar-empty";
+    empty.textContent = "No runs yet";
+    runListEl.appendChild(empty);
+    return;
+  }
+
+  for (const run of state.runs) {
+    const wrapper = document.createElement("label");
+    wrapper.className = "run-option";
+
+    const input = document.createElement("input");
+    input.type = "checkbox";
+    input.checked = state.selectedRunIds.includes(runKey(run));
+    input.addEventListener("change", async () => {
+      if (input.checked) {
+        state.selectedRunIds = [...new Set([...state.selectedRunIds, runKey(run)])];
+      } else {
+        state.selectedRunIds = state.selectedRunIds.filter((id) => id !== runKey(run));
+      }
+      setQueryParams({
+        project: state.selectedProject,
+        run_ids: state.selectedRunIds,
+      });
+      await renderDashboard();
+    });
+
+    const marker = document.createElement("span");
+    marker.className = "run-color-dot";
+    marker.style.backgroundColor = colorForRun(run);
+
+    const text = document.createElement("span");
+    text.className = "run-option-text";
+    text.innerHTML = `<strong>${run.name || "Unnamed run"}</strong>`;
+
+    wrapper.appendChild(input);
+    wrapper.appendChild(marker);
+    wrapper.appendChild(text);
+    runListEl.appendChild(wrapper);
+  }
+}
+
+function chartPoints(rows, width, height, padding, min, max) {
+  const span = max - min || 1;
+  return rows.map((row, index) => {
+    const x = padding + (index / Math.max(rows.length - 1, 1)) * (width - padding * 2);
+    const y = height - padding - ((row.value - min) / span) * (height - padding * 2);
+    return [x, y];
+  });
+}
+
+function pathFromPoints(points) {
+  return points.map(([x, y], index) => `${index === 0 ? "M" : "L"} ${x} ${y}`).join(" ");
+}
+
+function renderMetricCard(metricName, seriesByRun) {
+  const card = document.createElement("article");
+  card.className = "metric-card";
+  const nonEmptySeries = seriesByRun.filter((entry) => entry.rows.length);
+  if (!nonEmptySeries.length) {
+    card.innerHTML = `
+      <div class="metric-card-head">
+        <div>
+          <h3>${metricName}</h3>
+          <div class="metric-run">Selected runs</div>
+        </div>
+      </div>
+      <div class="metric-empty">No numeric values logged for this metric.</div>
+    `;
+    return card;
+  }
+
+  const width = 640;
+  const height = 220;
+  const padding = 20;
+  const values = nonEmptySeries.flatMap((entry) => entry.rows.map((row) => row.value));
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const lineMarkup = nonEmptySeries
+    .map((entry) => {
+      const points = chartPoints(entry.rows, width, height, padding, min, max);
+      const markers = points
+        .map(([x, y]) => `<circle class="plot-marker" cx="${x}" cy="${y}" r="3.5" style="stroke:${entry.color}"></circle>`)
+        .join("");
+      return `
+        <path class="plot-line" d="${pathFromPoints(points)}" stroke="${entry.color}"></path>
+        ${markers}
+      `;
+    })
+    .join("");
+  const legendMarkup = nonEmptySeries
+    .map(
+      (entry) => `
+        <span class="metric-legend-item">
+          <span class="metric-legend-dot" style="background:${entry.color}"></span>
+          ${entry.runName}
+        </span>
+      `,
+    )
+    .join("");
+  const latestSummary = nonEmptySeries
+    .map((entry) => `${entry.runName}: ${formatValue(entry.rows.at(-1).value)}`)
+    .join(" | ");
+
+  card.innerHTML = `
+    <div class="metric-card-head">
+      <div>
+        <h3>${metricName}</h3>
+        <div class="metric-run">${nonEmptySeries.length} run${nonEmptySeries.length === 1 ? "" : "s"} overlaid</div>
+      </div>
+      <div class="metric-latest">${latestSummary}</div>
+    </div>
+    <div class="plot-shell">
+      <svg viewBox="0 0 ${width} ${height}" role="img" aria-label="${metricName} line plot">
+        <line class="plot-axis" x1="${padding}" y1="${height - padding}" x2="${width - padding}" y2="${height - padding}"></line>
+        ${lineMarkup}
+      </svg>
+    </div>
+    <div class="metric-legend">${legendMarkup}</div>
+    <div class="metric-meta">Comparing ${nonEmptySeries.length} selected runs on the same metric scale.</div>
+  `;
+  return card;
+}
+
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (typeof part?.text === "string") return part.text;
+        if (typeof part?.content === "string") return part.content;
+        return "";
+      })
+      .filter(Boolean)
+      .join(" ");
+  }
+  if (typeof content?.text === "string") return content.text;
+  return "";
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function renderMessageContent(content) {
+  if (typeof content === "string") {
+    return `<div class="trace-message-text">${escapeHtml(content)}</div>`;
+  }
+  if (Array.isArray(content)) {
+    const items = content
+      .map((part) => {
+        if (typeof part === "string") {
+          return `<div class="trace-message-text">${escapeHtml(part)}</div>`;
+        }
+        if (typeof part?.text === "string") {
+          return `<div class="trace-message-text">${escapeHtml(part.text)}</div>`;
+        }
+        if (typeof part?.content === "string") {
+          return `<div class="trace-message-text">${escapeHtml(part.content)}</div>`;
+        }
+        return `<div class="trace-message-text trace-message-muted">[non-text content]</div>`;
+      })
+      .join("");
+    return items || '<div class="trace-message-text trace-message-muted">(empty)</div>';
+  }
+  if (typeof content?.text === "string") {
+    return `<div class="trace-message-text">${escapeHtml(content.text)}</div>`;
+  }
+  return '<div class="trace-message-text trace-message-muted">(empty)</div>';
+}
+
+function renderTraceDetail(trace) {
+  const messages = Array.isArray(trace.messages) ? trace.messages : [];
+  if (!messages.length) {
+    return '<div class="trace-message-text trace-message-muted">No trace messages.</div>';
+  }
+  return messages
+    .map((message) => {
+      const role = escapeHtml(message?.role || "unknown");
+      return `
+        <div class="trace-message">
+          <div class="trace-message-role">${role}</div>
+          ${renderMessageContent(message?.content)}
+        </div>
+      `;
+    })
+    .join("");
+}
+
+function formatTraceTime(timestamp) {
+  if (!timestamp) return "—";
+  const date = new Date(timestamp);
+  if (Number.isNaN(date.getTime())) {
+    return timestamp;
+  }
+  return date.toLocaleString();
+}
+
+function renderTraceRows(traces) {
+  tracesBodyEl.innerHTML = "";
+  if (!traces.length) {
+    const row = document.createElement("tr");
+    row.innerHTML = '<td colspan="5" class="empty-row">No traces for the selected runs.</td>';
+    tracesBodyEl.appendChild(row);
+    return;
+  }
+
+  for (const trace of traces) {
+    const request = textFromContent(
+      (trace.messages || []).find((message) => message?.role === "user")?.content,
+    ) || "(no user message)";
+    const row = document.createElement("tr");
+    row.className = "trace-summary-row";
+    row.setAttribute("role", "button");
+    row.setAttribute("tabindex", "0");
+    row.setAttribute("aria-expanded", "false");
+    row.innerHTML = `
+      <td><span class="trace-id">${trace.id}</span></td>
+      <td class="trace-request">${request}</td>
+      <td>${trace.run || "—"}</td>
+      <td>${trace.step ?? "—"}</td>
+      <td>${formatTraceTime(trace.timestamp)}</td>
+    `;
+    const detailRow = document.createElement("tr");
+    detailRow.className = "trace-detail-row";
+    detailRow.hidden = true;
+    detailRow.innerHTML = `
+      <td colspan="5">
+        <div class="trace-detail-shell">
+          <div class="trace-detail-head">
+            <div>
+              <strong>${escapeHtml(trace.id)}</strong>
+              <div class="trace-detail-meta">${escapeHtml(trace.run || "—")} | step ${escapeHtml(trace.step ?? "—")} | ${escapeHtml(formatTraceTime(trace.timestamp))}</div>
+            </div>
+          </div>
+          <div class="trace-message-list">
+            ${renderTraceDetail(trace)}
+          </div>
+        </div>
+      </td>
+    `;
+    const toggleRow = () => {
+      const expanded = row.getAttribute("aria-expanded") === "true";
+      row.setAttribute("aria-expanded", expanded ? "false" : "true");
+      row.classList.toggle("expanded", !expanded);
+      detailRow.hidden = expanded;
+    };
+    row.addEventListener("click", toggleRow);
+    row.addEventListener("keydown", (event) => {
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        toggleRow();
+      }
+    });
+    tracesBodyEl.appendChild(row);
+    tracesBodyEl.appendChild(detailRow);
+  }
+}
+
+async function loadRuns() {
+  if (!state.selectedProject) {
+    state.runs = [];
+    state.selectedRunIds = [];
+    renderRunList();
+    await renderDashboard();
+    return;
+  }
+
+  state.runs = await api("get_runs_for_project", { project: state.selectedProject });
+  state.selectedRunIds = pickInitialRunIds(state.runs);
+  renderRunList();
+  await renderDashboard();
+}
+
+async function renderDashboard() {
+  metricsGridEl.innerHTML = "";
+  tracesBodyEl.innerHTML = "";
+
+  const selectedRuns = state.runs.filter((run) => state.selectedRunIds.includes(runKey(run)));
+  metricsTitleEl.textContent = state.selectedProject || "Metrics";
+
+  if (!state.selectedProject) {
+    metricsSubtitleEl.textContent = "No Trackio projects found.";
+    tracesSubtitleEl.textContent = "No traces available.";
+    return;
+  }
+
+  if (!selectedRuns.length) {
+    metricsSubtitleEl.textContent = "Select one or more runs in the sidebar.";
+    tracesSubtitleEl.textContent = "Select one or more runs to load traces.";
+    metricsGridEl.innerHTML = '<div class="empty-panel">No runs selected.</div>';
+    renderTraceRows([]);
+    return;
+  }
+
+  metricsSubtitleEl.textContent = `Plot cards for ${selectedRuns.length} selected run${selectedRuns.length === 1 ? "" : "s"}.`;
+  tracesSubtitleEl.textContent = `Recent traces for ${selectedRuns.length} selected run${selectedRuns.length === 1 ? "" : "s"}.`;
+
+  const traceGroups = [];
+  const metricMap = new Map();
+
+  for (const run of selectedRuns) {
+    const metrics = await api("get_metrics_for_run", {
+      project: state.selectedProject,
+      run: run.name,
+      run_id: run.id,
+    });
+
+    const metricSeries = await Promise.all(
+      metrics.slice(0, 3).map(async (metricName) => ({
+        metricName,
+        rows: await api("get_metric_values", {
+          project: state.selectedProject,
+          run: run.name,
+          run_id: run.id,
+          metric_name: metricName,
+        }),
+      })),
+    );
+
+    metricSeries.forEach(({ metricName, rows }) => {
+      const numericRows = rows.filter((row) => typeof row.value === "number" && Number.isFinite(row.value));
+      if (!metricMap.has(metricName)) {
+        metricMap.set(metricName, []);
+      }
+      metricMap.get(metricName).push({
+        runName: run.name || "Unnamed run",
+        color: colorForRun(run),
+        rows: numericRows,
+      });
+    });
+
+    const runTraces = await api("get_traces", {
+      project: state.selectedProject,
+      run: run.name,
+      run_id: run.id,
+      sort: "request_time_desc",
+      limit: 6,
+    });
+    traceGroups.push(...runTraces);
+  }
+
+  for (const [metricName, seriesByRun] of metricMap.entries()) {
+    metricsGridEl.appendChild(renderMetricCard(metricName, seriesByRun));
+  }
+
+  if (!metricsGridEl.children.length) {
+    metricsGridEl.innerHTML = '<div class="empty-panel">No numeric metrics available.</div>';
+  }
+
+  traceGroups.sort((left, right) => String(right.timestamp || "").localeCompare(String(left.timestamp || "")));
+  renderTraceRows(traceGroups.slice(0, 12));
+}
+
+async function load() {
+  bindNavigation();
+  projectSelectEl.addEventListener("change", async () => {
+    state.selectedProject = projectSelectEl.value || null;
+    setQueryParams({ project: state.selectedProject, run_ids: null });
+    await loadRuns();
+    renderProjectSelect();
+  });
+  try {
+    state.projects = await api("get_all_projects");
+    state.selectedProject = pickInitialProject(state.projects);
+    renderProjectSelect();
+    await loadRuns();
+  } catch (error) {
+    projectSelectEl.innerHTML = '<option value="">Error</option>';
+    projectSelectEl.disabled = true;
+    metricsSubtitleEl.textContent = "Could not load Trackio data.";
+    metricsGridEl.innerHTML = '<div class="empty-panel">The starter could not reach the Trackio API.</div>';
+    tracesSubtitleEl.textContent = "Could not load traces.";
+    renderTraceRows([]);
+  }
+}
+
+load();

trackio/frontend_templates/starter/index.html

@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Starter</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <div class="app-shell">
+      <aside class="sidebar">
+        <div class="sidebar-scroll">
+          <div class="logo-section">
+            <img
+              src="/static/trackio/trackio_logo_type_light_transparent.png"
+              alt="Trackio"
+              class="logo"
+            />
+          </div>
+
+          <section class="sidebar-section">
+            <div class="section-label">Project</div>
+            <div class="dropdown-wrap">
+              <select id="project-select" class="project-select" aria-label="Project"></select>
+              <div class="dropdown-icon" aria-hidden="true">
+                <svg width="16" height="16" viewBox="0 0 18 18" fill="none">
+                  <path d="M5.25 7.5L9 11.25L12.75 7.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+                </svg>
+              </div>
+            </div>
+          </section>
+
+          <section class="sidebar-section">
+            <div class="section-label">Runs</div>
+            <div id="run-list" class="run-list"></div>
+          </section>
+
+          <section class="sidebar-section">
+            <div class="section-label">Notes</div>
+            <p class="sidebar-note">
+              This starter mirrors the Trackio dashboard structure, but stays plain
+              HTML, CSS, and JavaScript so you can replace pieces quickly.
+            </p>
+          </section>
+        </div>
+      </aside>
+
+      <main class="main-shell">
+        <nav class="navbar">
+          <div class="nav-spacer"></div>
+          <div class="nav-tabs">
+            <button class="nav-link active" data-page-target="metrics">Metrics</button>
+            <button class="nav-link" data-page-target="traces">Traces</button>
+            <!--
+            Trackio's full dashboard also includes tabs like these.
+            Uncomment them when you implement the corresponding page sections.
+
+            <button class="nav-link" data-page-target="system">System Metrics</button>
+            <button class="nav-link" data-page-target="media">Media & Tables</button>
+            <button class="nav-link" data-page-target="reports">Alerts & Reports</button>
+            <button class="nav-link" data-page-target="runs">Runs</button>
+            <button class="nav-link" data-page-target="files">Files</button>
+            <button class="nav-link" data-page-target="settings">Settings</button>
+            -->
+          </div>
+        </nav>
+
+        <section class="page active" data-page="metrics">
+          <header class="page-header">
+            <div>
+              <p class="eyebrow">Starter Dashboard</p>
+              <h1 id="metrics-title">Metrics</h1>
+              <p id="metrics-subtitle" class="page-subtitle">Loading Trackio data.</p>
+            </div>
+          </header>
+          <div id="metrics-grid" class="metrics-grid"></div>
+        </section>
+
+        <section class="page" data-page="traces">
+          <header class="page-header">
+            <div>
+              <p class="eyebrow">Starter Dashboard</p>
+              <h1>Traces</h1>
+              <p id="traces-subtitle" class="page-subtitle">Recent traces for the selected runs.</p>
+            </div>
+          </header>
+          <div class="traces-table-wrap">
+            <table class="traces-table">
+              <thead>
+                <tr>
+                  <th>Trace ID</th>
+                  <th>Request</th>
+                  <th>Run</th>
+                  <th>Step</th>
+                  <th>Request time</th>
+                </tr>
+              </thead>
+              <tbody id="traces-body"></tbody>
+            </table>
+          </div>
+        </section>
+
+        <!--
+        Future page shells you may want to add:
+
+        <section class="page" data-page="system">
+          Build this from /api/get_system_metrics_for_run and /api/get_system_logs.
+        </section>
+
+        <section class="page" data-page="media">
+          Build this from /api/get_logs, /api/get_snapshot, /api/get_project_files, and /file?path=...
+        </section>
+
+        <section class="page" data-page="reports">
+          Build this from /api/get_alerts and /api/query_project.
+        </section>
+
+        <section class="page" data-page="runs">
+          Build this from /api/get_runs_for_project, /api/get_run_summary, /api/delete_run, and /api/rename_run.
+        </section>
+
+        <section class="page" data-page="files">
+          Build this from /api/get_project_files and /file?path=...
+        </section>
+
+        <section class="page" data-page="settings">
+          Build this from /api/get_settings, /api/force_sync, and /api/get_run_mutation_status.
+        </section>
+        -->
+      </main>
+    </div>
+
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

trackio/frontend_templates/starter/styles.css

@@ -0,0 +1,467 @@
+:root {
+  color-scheme: light;
+  --background-fill-primary: #ffffff;
+  --background-fill-secondary: #f9fafb;
+  --background-fill-tertiary: #f3f4f6;
+  --border-color-primary: #e5e7eb;
+  --border-color-accent: #d1d5db;
+  --body-text-color: #111827;
+  --body-text-color-subdued: #6b7280;
+  --body-text-color-soft: #9ca3af;
+  --accent: #1d4ed8;
+  --shadow-soft: 0 1px 2px rgba(16, 24, 40, 0.04);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  min-height: 100%;
+  background: var(--background-fill-secondary);
+  color: var(--body-text-color);
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+}
+
+button,
+input,
+select,
+table {
+  font: inherit;
+}
+
+.app-shell {
+  display: grid;
+  grid-template-columns: 320px minmax(0, 1fr);
+  min-height: 100vh;
+}
+
+.sidebar {
+  border-right: 1px solid var(--border-color-primary);
+  background: var(--background-fill-primary);
+}
+
+.sidebar-scroll {
+  height: 100vh;
+  overflow-y: auto;
+  padding: 18px 16px 28px;
+}
+
+.logo-section {
+  padding: 10px 10px 18px;
+  border-bottom: 1px solid var(--border-color-primary);
+}
+
+.logo {
+  display: block;
+  width: 138px;
+  max-width: 100%;
+}
+
+.sidebar-section {
+  padding: 18px 10px 0;
+}
+
+.section-label,
+.eyebrow {
+  margin: 0 0 10px;
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.run-list {
+  display: grid;
+  gap: 8px;
+}
+
+.dropdown-wrap {
+  position: relative;
+}
+
+.project-select {
+  width: 100%;
+  padding: 10px 40px 10px 12px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 10px;
+  background: var(--background-fill-primary);
+  color: var(--body-text-color);
+  appearance: none;
+  -webkit-appearance: none;
+}
+
+.project-select:focus {
+  outline: none;
+  border-color: var(--border-color-accent);
+  box-shadow: 0 0 0 3px rgba(29, 78, 216, 0.08);
+}
+
+.dropdown-icon {
+  position: absolute;
+  top: 50%;
+  right: 12px;
+  transform: translateY(-50%);
+  color: var(--body-text-color-subdued);
+  pointer-events: none;
+}
+
+.run-option {
+  display: grid;
+  grid-template-columns: 18px 10px minmax(0, 1fr);
+  gap: 10px;
+  align-items: start;
+  padding: 10px 12px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 10px;
+  background: var(--background-fill-primary);
+  cursor: pointer;
+}
+
+.run-option input {
+  margin: 2px 0 0;
+  accent-color: var(--accent);
+}
+
+.run-color-dot {
+  width: 10px;
+  height: 10px;
+  margin-top: 5px;
+  border-radius: 999px;
+  background: var(--accent);
+}
+
+.run-option-text strong,
+.run-option-text span {
+  display: block;
+}
+
+.run-option-text strong {
+  color: var(--body-text-color);
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.run-option-text span,
+.sidebar-note,
+.sidebar-empty {
+  color: var(--body-text-color-subdued);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.main-shell {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.navbar {
+  display: flex;
+  align-items: stretch;
+  min-height: 44px;
+  border-bottom: 1px solid var(--border-color-primary);
+  background: var(--background-fill-primary);
+}
+
+.nav-spacer {
+  flex: 1 1 0;
+}
+
+.nav-tabs {
+  display: flex;
+  padding-right: 8px;
+}
+
+.nav-link {
+  padding: 10px 16px;
+  border: none;
+  border-bottom: 2px solid transparent;
+  background: none;
+  color: var(--body-text-color-subdued);
+  cursor: pointer;
+}
+
+.nav-link.active {
+  border-bottom-color: var(--body-text-color);
+  color: var(--body-text-color);
+  font-weight: 500;
+}
+
+.page {
+  display: none;
+  min-width: 0;
+  padding: 24px 28px 36px;
+}
+
+.page.active {
+  display: block;
+}
+
+.page-header {
+  margin-bottom: 22px;
+}
+
+.page-header h1 {
+  margin: 0;
+  font-size: 32px;
+  line-height: 1.1;
+}
+
+.page-subtitle {
+  margin: 8px 0 0;
+  color: var(--body-text-color-subdued);
+  font-size: 15px;
+}
+
+.metrics-grid {
+  display: grid;
+  gap: 18px;
+}
+
+.metric-card {
+  padding: 18px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+  box-shadow: var(--shadow-soft);
+}
+
+.metric-card-head {
+  display: flex;
+  align-items: start;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.metric-card h3 {
+  margin: 0;
+  font-size: 18px;
+}
+
+.metric-run,
+.metric-meta,
+.metric-empty,
+.metric-latest {
+  color: var(--body-text-color-subdued);
+  font-size: 13px;
+}
+
+.metric-latest {
+  color: var(--body-text-color);
+  max-width: 50%;
+  font-size: 13px;
+  font-weight: 600;
+  text-align: right;
+}
+
+.plot-shell {
+  margin-top: 14px;
+  padding: 10px 12px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 12px;
+  background: linear-gradient(180deg, #ffffff, #f9fafb);
+}
+
+.plot-shell svg {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.plot-axis {
+  stroke: var(--border-color-accent);
+  stroke-width: 1.2;
+}
+
+.plot-line {
+  fill: none;
+  stroke-width: 2.25;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.plot-marker {
+  fill: var(--background-fill-primary);
+  stroke: var(--body-text-color);
+  stroke-width: 1.5;
+}
+
+.metric-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px 14px;
+  margin-top: 12px;
+}
+
+.metric-legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--body-text-color-subdued);
+  font-size: 13px;
+}
+
+.metric-legend-dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 999px;
+}
+
+.traces-table-wrap {
+  overflow: auto;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+  box-shadow: var(--shadow-soft);
+}
+
+.traces-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.traces-table thead {
+  background: var(--background-fill-secondary);
+}
+
+.traces-table th,
+.traces-table td {
+  padding: 14px 16px;
+  border-bottom: 1px solid var(--border-color-primary);
+  text-align: left;
+  vertical-align: top;
+  font-size: 14px;
+}
+
+.traces-table th {
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.trace-summary-row {
+  cursor: pointer;
+}
+
+.trace-summary-row:hover {
+  background: var(--background-fill-secondary);
+}
+
+.trace-summary-row.expanded {
+  background: var(--background-fill-secondary);
+}
+
+.trace-id {
+  color: var(--body-text-color);
+  font-family:
+    ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    monospace;
+  font-size: 12px;
+}
+
+.trace-request {
+  max-width: 520px;
+  color: var(--body-text-color);
+}
+
+.trace-detail-row td {
+  padding: 0;
+  background: var(--background-fill-secondary);
+}
+
+.trace-detail-shell {
+  padding: 18px 20px;
+  border-top: 1px solid var(--border-color-primary);
+}
+
+.trace-detail-head strong {
+  display: block;
+  color: var(--body-text-color);
+  font-size: 14px;
+}
+
+.trace-detail-meta {
+  margin-top: 4px;
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+}
+
+.trace-message-list {
+  display: grid;
+  gap: 12px;
+  margin-top: 16px;
+}
+
+.trace-message {
+  padding: 12px 14px;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 12px;
+  background: var(--background-fill-primary);
+}
+
+.trace-message-role {
+  margin-bottom: 8px;
+  color: var(--body-text-color-subdued);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.trace-message-text {
+  color: var(--body-text-color);
+  font-size: 14px;
+  line-height: 1.55;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.trace-message-muted {
+  color: var(--body-text-color-subdued);
+}
+
+.empty-row,
+.empty-panel {
+  color: var(--body-text-color-subdued);
+  text-align: center;
+}
+
+.empty-panel {
+  padding: 48px 20px;
+  border: 1px dashed var(--border-color-accent);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+}
+
+@media (max-width: 960px) {
+  .app-shell {
+    grid-template-columns: 1fr;
+  }
+
+  .sidebar {
+    border-right: none;
+    border-bottom: 1px solid var(--border-color-primary);
+  }
+
+  .sidebar-scroll {
+    height: auto;
+  }
+
+  .page {
+    padding: 18px;
+  }
+}

trackio/gpu.py

@@ -0,0 +1,381 @@
+import os
+import threading
+import warnings
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from trackio.run import Run
+
+pynvml: Any = None
+PYNVML_AVAILABLE = False
+_nvml_initialized = False
+_nvml_lock = threading.Lock()
+_energy_baseline: dict[int, float] = {}
+
+
+def _ensure_pynvml():
+    global PYNVML_AVAILABLE, pynvml
+    if PYNVML_AVAILABLE:
+        return pynvml
+    try:
+        import pynvml as _pynvml
+
+        pynvml = _pynvml
+        PYNVML_AVAILABLE = True
+        return pynvml
+    except ImportError:
+        raise ImportError(
+            "nvidia-ml-py is required for GPU monitoring. "
+            "Install it with: pip install nvidia-ml-py"
+        )
+
+
+def _init_nvml() -> bool:
+    global _nvml_initialized
+    with _nvml_lock:
+        if _nvml_initialized:
+            return True
+        try:
+            nvml = _ensure_pynvml()
+            nvml.nvmlInit()
+            _nvml_initialized = True
+            return True
+        except Exception:
+            return False
+
+
+def get_gpu_count() -> tuple[int, list[int]]:
+    """
+    Get the number of GPUs visible to this process and their physical indices.
+    Respects CUDA_VISIBLE_DEVICES environment variable.
+
+    Returns:
+        Tuple of (count, physical_indices) where:
+        - count: Number of visible GPUs
+        - physical_indices: List mapping logical index to physical GPU index.
+          e.g., if CUDA_VISIBLE_DEVICES=2,3 returns (2, [2, 3])
+          meaning logical GPU 0 = physical GPU 2, logical GPU 1 = physical GPU 3
+    """
+    if not _init_nvml():
+        return 0, []
+
+    cuda_visible = os.environ.get("CUDA_VISIBLE_DEVICES")
+    if cuda_visible is not None and cuda_visible.strip():
+        try:
+            indices = [int(x.strip()) for x in cuda_visible.split(",") if x.strip()]
+            return len(indices), indices
+        except ValueError:
+            pass
+
+    try:
+        total = pynvml.nvmlDeviceGetCount()
+        return total, list(range(total))
+    except Exception:
+        return 0, []
+
+
+def get_all_gpu_count() -> tuple[int, list[int]]:
+    """
+    Get the total number of physical GPUs on the machine, ignoring CUDA_VISIBLE_DEVICES.
+
+    Returns:
+        Tuple of (count, physical_indices) for ALL GPUs on the machine.
+        e.g., on a 4-GPU machine returns (4, [0, 1, 2, 3]) regardless of
+        CUDA_VISIBLE_DEVICES setting.
+    """
+    if not _init_nvml():
+        return 0, []
+
+    try:
+        total = pynvml.nvmlDeviceGetCount()
+        return total, list(range(total))
+    except Exception:
+        return 0, []
+
+
+def gpu_available() -> bool:
+    """
+    Check if GPU monitoring is available.
+
+    Returns True if nvidia-ml-py is installed and at least one NVIDIA GPU is detected.
+    This is used for auto-detection of GPU logging.
+    """
+    try:
+        _ensure_pynvml()
+        count, _ = get_gpu_count()
+        return count > 0
+    except ImportError:
+        return False
+    except Exception:
+        return False
+
+
+def reset_energy_baseline():
+    """Reset the energy baseline for all GPUs. Called when a new run starts."""
+    global _energy_baseline
+    _energy_baseline = {}
+
+
+def collect_gpu_metrics(device: int | None = None, all_gpus: bool = False) -> dict:
+    """
+    Collect GPU metrics for visible GPUs.
+
+    Args:
+        device: CUDA device index to collect metrics from. If None, collects
+                from all GPUs visible to this process (respects CUDA_VISIBLE_DEVICES).
+                The device index is the logical CUDA index (0, 1, 2...), not the
+                physical GPU index.
+        all_gpus: If True and device is None, collect metrics for ALL physical GPUs
+                  on the machine, ignoring CUDA_VISIBLE_DEVICES. Used by GpuMonitor
+                  to report system-wide GPU metrics in distributed training.
+
+    Returns:
+        Dictionary of GPU metrics. Keys use device indices (gpu/0/, gpu/1/, etc.).
+    """
+    if not _init_nvml():
+        return {}
+
+    if all_gpus and device is None:
+        gpu_count, visible_gpus = get_all_gpu_count()
+    else:
+        gpu_count, visible_gpus = get_gpu_count()
+    if gpu_count == 0:
+        return {}
+
+    if device is not None:
+        if device < 0 or device >= gpu_count:
+            return {}
+        gpu_indices = [(device, visible_gpus[device])]
+    else:
+        gpu_indices = list(enumerate(visible_gpus))
+
+    metrics = {}
+    total_util = 0.0
+    total_mem_used_gib = 0.0
+    total_power = 0.0
+    max_temp = 0.0
+    valid_util_count = 0
+
+    for logical_idx, physical_idx in gpu_indices:
+        prefix = f"gpu/{logical_idx}"
+        try:
+            handle = pynvml.nvmlDeviceGetHandleByIndex(physical_idx)
+
+            try:
+                util = pynvml.nvmlDeviceGetUtilizationRates(handle)
+                metrics[f"{prefix}/utilization"] = util.gpu
+                metrics[f"{prefix}/memory_utilization"] = util.memory
+                total_util += util.gpu
+                valid_util_count += 1
+            except Exception:
+                pass
+
+            try:
+                mem = pynvml.nvmlDeviceGetMemoryInfo(handle)
+                mem_used_gib = mem.used / (1024**3)
+                mem_total_gib = mem.total / (1024**3)
+                metrics[f"{prefix}/allocated_memory"] = mem_used_gib
+                metrics[f"{prefix}/total_memory"] = mem_total_gib
+                if mem.total > 0:
+                    metrics[f"{prefix}/memory_usage"] = mem.used / mem.total
+                total_mem_used_gib += mem_used_gib
+            except Exception:
+                pass
+
+            try:
+                power_mw = pynvml.nvmlDeviceGetPowerUsage(handle)
+                power_w = power_mw / 1000.0
+                metrics[f"{prefix}/power"] = power_w
+                total_power += power_w
+            except Exception:
+                pass
+
+            try:
+                power_limit_mw = pynvml.nvmlDeviceGetPowerManagementLimit(handle)
+                power_limit_w = power_limit_mw / 1000.0
+                metrics[f"{prefix}/power_limit"] = power_limit_w
+                if power_limit_w > 0 and f"{prefix}/power" in metrics:
+                    metrics[f"{prefix}/power_percent"] = (
+                        metrics[f"{prefix}/power"] / power_limit_w
+                    ) * 100
+            except Exception:
+                pass
+
+            try:
+                temp = pynvml.nvmlDeviceGetTemperature(
+                    handle, pynvml.NVML_TEMPERATURE_GPU
+                )
+                metrics[f"{prefix}/temp"] = temp
+                max_temp = max(max_temp, temp)
+            except Exception:
+                pass
+
+            try:
+                sm_clock = pynvml.nvmlDeviceGetClockInfo(handle, pynvml.NVML_CLOCK_SM)
+                metrics[f"{prefix}/sm_clock"] = sm_clock
+            except Exception:
+                pass
+
+            try:
+                mem_clock = pynvml.nvmlDeviceGetClockInfo(handle, pynvml.NVML_CLOCK_MEM)
+                metrics[f"{prefix}/memory_clock"] = mem_clock
+            except Exception:
+                pass
+
+            try:
+                fan_speed = pynvml.nvmlDeviceGetFanSpeed(handle)
+                metrics[f"{prefix}/fan_speed"] = fan_speed
+            except Exception:
+                pass
+
+            try:
+                pstate = pynvml.nvmlDeviceGetPerformanceState(handle)
+                metrics[f"{prefix}/performance_state"] = pstate
+            except Exception:
+                pass
+
+            try:
+                energy_mj = pynvml.nvmlDeviceGetTotalEnergyConsumption(handle)
+                if physical_idx not in _energy_baseline:
+                    _energy_baseline[physical_idx] = energy_mj
+                energy_consumed_mj = energy_mj - _energy_baseline[physical_idx]
+                metrics[f"{prefix}/energy_consumed"] = energy_consumed_mj / 1000.0
+            except Exception:
+                pass
+
+            try:
+                pcie_tx = pynvml.nvmlDeviceGetPcieThroughput(
+                    handle, pynvml.NVML_PCIE_UTIL_TX_BYTES
+                )
+                pcie_rx = pynvml.nvmlDeviceGetPcieThroughput(
+                    handle, pynvml.NVML_PCIE_UTIL_RX_BYTES
+                )
+                metrics[f"{prefix}/pcie_tx"] = pcie_tx / 1024.0
+                metrics[f"{prefix}/pcie_rx"] = pcie_rx / 1024.0
+            except Exception:
+                pass
+
+            try:
+                throttle = pynvml.nvmlDeviceGetCurrentClocksThrottleReasons(handle)
+                metrics[f"{prefix}/throttle_thermal"] = int(
+                    bool(throttle & pynvml.nvmlClocksThrottleReasonSwThermalSlowdown)
+                )
+                metrics[f"{prefix}/throttle_power"] = int(
+                    bool(throttle & pynvml.nvmlClocksThrottleReasonSwPowerCap)
+                )
+                metrics[f"{prefix}/throttle_hw_slowdown"] = int(
+                    bool(throttle & pynvml.nvmlClocksThrottleReasonHwSlowdown)
+                )
+                metrics[f"{prefix}/throttle_apps"] = int(
+                    bool(
+                        throttle
+                        & pynvml.nvmlClocksThrottleReasonApplicationsClocksSetting
+                    )
+                )
+            except Exception:
+                pass
+
+            try:
+                ecc_corrected = pynvml.nvmlDeviceGetTotalEccErrors(
+                    handle,
+                    pynvml.NVML_MEMORY_ERROR_TYPE_CORRECTED,
+                    pynvml.NVML_VOLATILE_ECC,
+                )
+                metrics[f"{prefix}/corrected_memory_errors"] = ecc_corrected
+            except Exception:
+                pass
+
+            try:
+                ecc_uncorrected = pynvml.nvmlDeviceGetTotalEccErrors(
+                    handle,
+                    pynvml.NVML_MEMORY_ERROR_TYPE_UNCORRECTED,
+                    pynvml.NVML_VOLATILE_ECC,
+                )
+                metrics[f"{prefix}/uncorrected_memory_errors"] = ecc_uncorrected
+            except Exception:
+                pass
+
+        except Exception:
+            continue
+
+    if valid_util_count > 0:
+        metrics["gpu/mean_utilization"] = total_util / valid_util_count
+    if total_mem_used_gib > 0:
+        metrics["gpu/total_allocated_memory"] = total_mem_used_gib
+    if total_power > 0:
+        metrics["gpu/total_power"] = total_power
+    if max_temp > 0:
+        metrics["gpu/max_temp"] = max_temp
+
+    return metrics
+
+
+class GpuMonitor:
+    def __init__(self, run: "Run", interval: float = 10.0):
+        self._run = run
+        self._interval = interval
+        self._stop_flag = threading.Event()
+        self._thread: "threading.Thread | None" = None
+
+    def start(self):
+        count, _ = get_all_gpu_count()
+        if count == 0:
+            warnings.warn(
+                "auto_log_gpu=True but no NVIDIA GPUs detected. GPU logging disabled."
+            )
+            return
+
+        reset_energy_baseline()
+        self._thread = threading.Thread(target=self._monitor_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_flag.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+
+    def _monitor_loop(self):
+        while not self._stop_flag.is_set():
+            try:
+                metrics = collect_gpu_metrics(all_gpus=True)
+                if metrics:
+                    self._run.log_system(metrics)
+            except Exception:
+                pass
+
+            self._stop_flag.wait(timeout=self._interval)
+
+
+def log_gpu(run: "Run | None" = None, device: int | None = None) -> dict:
+    """
+    Log GPU metrics to the current or specified run as system metrics.
+
+    Args:
+        run: Optional Run instance. If None, uses current run from context.
+        device: CUDA device index to collect metrics from. If None, collects
+                from all GPUs visible to this process (respects CUDA_VISIBLE_DEVICES).
+
+    Returns:
+        dict: The GPU metrics that were logged.
+
+    Example:
+        ```python
+        import trackio
+
+        run = trackio.init(project="my-project")
+        trackio.log({"loss": 0.5})
+        trackio.log_gpu()  # logs all visible GPUs
+        trackio.log_gpu(device=0)  # logs only CUDA device 0
+        ```
+    """
+    from trackio import context_vars
+
+    if run is None:
+        run = context_vars.current_run.get()
+        if run is None:
+            raise RuntimeError("Call trackio.init() before trackio.log_gpu().")
+
+    metrics = collect_gpu_metrics(device=device)
+    if metrics:
+        run.log_system(metrics)
+    return metrics

trackio/histogram.py

@@ -0,0 +1,71 @@
+from typing import Sequence
+
+import numpy as np
+
+
+class Histogram:
+    """
+    Histogram data type for Trackio, compatible with wandb.Histogram.
+
+    Args:
+        sequence (`np.ndarray` or `Sequence[float]` or `Sequence[int]`, *optional*):
+            Sequence of values to create the histogram from.
+        np_histogram (`tuple`, *optional*):
+            Pre-computed NumPy histogram as a `(hist, bins)` tuple.
+        num_bins (`int`, *optional*, defaults to `64`):
+            Number of bins for the histogram (maximum `512`).
+
+    Example:
+        ```python
+        import trackio
+        import numpy as np
+
+        # Create histogram from sequence
+        data = np.random.randn(1000)
+        trackio.log({"distribution": trackio.Histogram(data)})
+
+        # Create histogram from numpy histogram
+        hist, bins = np.histogram(data, bins=30)
+        trackio.log({"distribution": trackio.Histogram(np_histogram=(hist, bins))})
+
+        # Specify custom number of bins
+        trackio.log({"distribution": trackio.Histogram(data, num_bins=50)})
+        ```
+    """
+
+    TYPE = "trackio.histogram"
+
+    def __init__(
+        self,
+        sequence: np.ndarray | Sequence[float] | Sequence[int] | None = None,
+        np_histogram: tuple | None = None,
+        num_bins: int = 64,
+    ):
+        if sequence is None and np_histogram is None:
+            raise ValueError("Must provide either sequence or np_histogram")
+
+        if sequence is not None and np_histogram is not None:
+            raise ValueError("Cannot provide both sequence and np_histogram")
+
+        num_bins = min(num_bins, 512)
+
+        if np_histogram is not None:
+            self.histogram, self.bins = np_histogram
+            self.histogram = np.asarray(self.histogram)
+            self.bins = np.asarray(self.bins)
+        else:
+            data = np.asarray(sequence).flatten()
+            data = data[np.isfinite(data)]
+            if len(data) == 0:
+                self.histogram = np.array([])
+                self.bins = np.array([])
+            else:
+                self.histogram, self.bins = np.histogram(data, bins=num_bins)
+
+    def _to_dict(self) -> dict:
+        """Convert histogram to dictionary for storage."""
+        return {
+            "_type": self.TYPE,
+            "bins": self.bins.tolist(),
+            "values": self.histogram.tolist(),
+        }

trackio/imports.py

@@ -0,0 +1,300 @@
+import csv
+import os
+from pathlib import Path
+
+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,
+    private: bool | None = None,
+    force: bool = False,
+) -> 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 (`str` or `Path`):
+            The str or Path to the CSV file to import.
+        project (`str`):
+            The name of the project to import the CSV file into. Must not be an existing
+            project.
+        name (`str`, *optional*):
+            The name of the Run to import the CSV file into. If not provided, a default
+            name will be generated.
+        name (`str`, *optional*):
+            The name of the run (if not provided, a default name will be generated).
+        space_id (`str`, *optional*):
+            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 (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        private (`bool`, *optional*):
+            Whether to make the Space 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.
+    """
+    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}")
+
+    with csv_path.open(newline="", encoding="utf-8") as csv_file:
+        reader = csv.DictReader(csv_file)
+        source_columns = reader.fieldnames or []
+        rows = list(reader)
+
+    if not rows:
+        raise ValueError("CSV file is empty")
+
+    column_mapping = utils.simplify_column_names(source_columns)
+    normalized_rows = [
+        {column_mapping[key]: value for key, value in row.items()} for row in rows
+    ]
+    columns = list(normalized_rows[0].keys())
+
+    step_column = None
+    for col in 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 columns:
+        if column == step_column:
+            continue
+        if column == "timestamp":
+            continue
+
+        try:
+            for row in normalized_rows:
+                value = row[column]
+                if value in ("", None):
+                    continue
+                float(value)
+        except (ValueError, TypeError):
+            continue
+        numeric_columns.append(column)
+
+    for row in normalized_rows:
+        metrics = {}
+        for column in numeric_columns:
+            value = row[column]
+            if value not in ("", None):
+                metrics[column] = float(value)
+
+        if metrics:
+            metrics_list.append(metrics)
+            steps.append(int(float(row[step_column])))
+
+            if "timestamp" in row and row["timestamp"] not in ("", None):
+                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=space_id, dataset_id=dataset_id, private=private
+        )
+        deploy.wait_until_space_exists(space_id=space_id)
+        deploy.upload_db_to_space(project=project, space_id=space_id, force=force)
+        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,
+    private: bool | None = None,
+    force: bool = False,
+) -> 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 (`str` or `Path`):
+            The str or Path to the directory containing TensorFlow Events files.
+        project (`str`):
+            The name of the project to import the TensorFlow Events files into. Must not
+            be an existing project.
+        name (`str`, *optional*):
+            The name prefix for runs (if not provided, will use directory names). Each
+            subdirectory will create a separate run.
+        space_id (`str`, *optional*):
+            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 (`str`, *optional*):
+            Deprecated. Use `bucket_id` instead.
+        private (`bool`, *optional*):
+            Whether to make the Space 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.
+    """
+    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 utils.is_missing_value(
+                    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=dataset_id, private=private
+        )
+        deploy.wait_until_space_exists(space_id)
+        deploy.upload_db_to_space(project, space_id, force=force)
+        print(
+            f"* View dashboard by going to: {deploy.SPACE_URL.format(space_id=space_id)}"
+        )

trackio/launch.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import os
+import secrets
+import socket
+import threading
+import time
+import warnings
+from pathlib import Path
+from typing import Any
+
+import httpx
+import uvicorn
+from uvicorn.config import Config
+
+from trackio._vendor.gradio_exceptions import ChecksumMismatchError
+from trackio._vendor.networking import normalize_share_url, setup_tunnel, url_ok
+from trackio._vendor.tunneling import BINARY_PATH
+from trackio.launch_utils import colab_check, is_hosted_notebook
+
+INITIAL_PORT_VALUE = int(os.getenv("GRADIO_SERVER_PORT", "7860"))
+TRY_NUM_PORTS = int(os.getenv("GRADIO_NUM_PORTS", "100"))
+LOCALHOST_NAME = os.getenv("GRADIO_SERVER_NAME", "127.0.0.1")
+
+
+class _UvicornServer(uvicorn.Server):
+    def install_signal_handlers(self) -> None:
+        pass
+
+    def run_in_thread(self) -> None:
+        self.thread = threading.Thread(target=self.run, daemon=True)
+        self.thread.start()
+        start = time.time()
+        while not self.started:
+            time.sleep(1e-3)
+            if time.time() - start > 60:
+                raise RuntimeError(
+                    "Server failed to start. Please check that the port is available."
+                )
+
+
+def _bind_host(server_name: str) -> str:
+    if server_name.startswith("[") and server_name.endswith("]"):
+        return server_name[1:-1]
+    return server_name
+
+
+def start_server(
+    app: Any,
+    server_name: str | None = None,
+    server_port: int | None = None,
+    ssl_keyfile: str | None = None,
+    ssl_certfile: str | None = None,
+    ssl_keyfile_password: str | None = None,
+) -> tuple[str, int, str, _UvicornServer]:
+    server_name = server_name or LOCALHOST_NAME
+    url_host_name = "localhost" if server_name == "0.0.0.0" else server_name
+
+    host = _bind_host(server_name)
+
+    server_ports = (
+        [server_port]
+        if server_port is not None
+        else range(INITIAL_PORT_VALUE, INITIAL_PORT_VALUE + TRY_NUM_PORTS)
+    )
+
+    port_used = None
+    server = None
+    for port in server_ports:
+        try:
+            socket_family = socket.AF_INET6 if ":" in host else socket.AF_INET
+            with socket.socket(socket_family, socket.SOCK_STREAM) as s:
+                s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                s.bind((host, port))
+            config = Config(
+                app=app,
+                port=port,
+                host=host,
+                log_level="warning",
+                ssl_keyfile=ssl_keyfile,
+                ssl_certfile=ssl_certfile,
+                ssl_keyfile_password=ssl_keyfile_password,
+            )
+            server = _UvicornServer(config=config)
+            server.run_in_thread()
+            port_used = port
+            break
+        except (OSError, RuntimeError):
+            continue
+    else:
+        raise OSError(
+            f"Cannot find empty port in range: {min(server_ports)}-{max(server_ports)}. "
+            "Set GRADIO_SERVER_PORT or pass server_port to trackio.show()."
+        )
+
+    assert port_used is not None and server is not None
+
+    if ssl_keyfile is not None:
+        path_to_local_server = f"https://{url_host_name}:{port_used}/"
+    else:
+        path_to_local_server = f"http://{url_host_name}:{port_used}/"
+
+    return server_name, port_used, path_to_local_server, server
+
+
+def launch_trackio_dashboard(
+    starlette_app: Any,
+    *,
+    server_name: str | None = None,
+    server_port: int | None = None,
+    share: bool | None = None,
+    share_server_address: str | None = None,
+    share_server_protocol: str | None = None,
+    share_server_tls_certificate: str | None = None,
+    mcp_server: bool = False,
+    ssl_verify: bool = True,
+    quiet: bool = False,
+) -> tuple[str | None, str | None, str | None, Any]:
+    is_colab = colab_check()
+    is_hosted_nb = is_hosted_notebook()
+    space_id = os.getenv("SPACE_ID")
+
+    if share is None:
+        if is_colab or is_hosted_nb:
+            if not quiet:
+                print(
+                    "It looks like you are running Trackio on a hosted Jupyter notebook, which requires "
+                    "`share=True`. Automatically setting `share=True` "
+                    "(set `share=False` in `show()` to disable).\n"
+                )
+            share = True
+        else:
+            share = os.getenv("GRADIO_SHARE", "").lower() == "true"
+
+    sn = server_name
+    if sn is None and os.getenv("SYSTEM") == "spaces":
+        sn = "0.0.0.0"
+    elif sn is None:
+        sn = LOCALHOST_NAME
+
+    server_name_r, server_port_r, local_url, uv_server = start_server(
+        starlette_app,
+        server_name=sn,
+        server_port=server_port,
+    )
+
+    local_api_url = f"{local_url.rstrip('/')}/api/"
+    try:
+        httpx.get(f"{local_url.rstrip('/')}/version", verify=ssl_verify, timeout=10)
+    except Exception as e:
+        raise RuntimeError(
+            f"Could not reach Trackio server at {local_url.rstrip('/')}/version: {e}"
+        ) from e
+
+    if share and space_id:
+        warnings.warn("Setting share=True is not supported on Hugging Face Spaces")
+        share = False
+
+    share_url: str | None = None
+    if share:
+        try:
+            share_tok = secrets.token_urlsafe(32)
+            proto = share_server_protocol or (
+                "http" if share_server_address is not None else "https"
+            )
+            raw = setup_tunnel(
+                local_host=server_name_r,
+                local_port=server_port_r,
+                share_token=share_tok,
+                share_server_address=share_server_address,
+                share_server_tls_certificate=share_server_tls_certificate,
+            )
+            share_url = normalize_share_url(raw, proto)
+            if not quiet:
+                print(f"* Running on public URL: {share_url}")
+                print(
+                    "\nThis share link expires in 1 week. For permanent hosting, deploy to Hugging Face Spaces."
+                )
+        except Exception as e:
+            share_url = None
+            if not quiet:
+                if isinstance(e, ChecksumMismatchError):
+                    print(
+                        "\nCould not create share link. Checksum mismatch for frpc binary."
+                    )
+                elif Path(BINARY_PATH).exists():
+                    print(
+                        "\nCould not create share link. Check your internet connection or https://status.gradio.app."
+                    )
+                else:
+                    print(
+                        f"\nCould not create share link. Missing frpc at {BINARY_PATH}. {e}"
+                    )
+
+    if not share_url and not quiet:
+        print("* To create a public link, set `share=True` in `trackio.show()`.")
+
+    return local_url, share_url, local_api_url, uv_server
+
+
+def url_ok_local(local_url: str) -> bool:
+    return url_ok(local_url)

trackio/launch_utils.py

@@ -0,0 +1,33 @@
+import os
+
+
+def colab_check() -> bool:
+    is_colab = False
+    try:
+        from IPython.core.getipython import get_ipython  # noqa: PLC0415
+
+        from_ipynb = get_ipython()
+        if "google.colab" in str(from_ipynb):
+            is_colab = True
+    except (ImportError, NameError):
+        pass
+    return is_colab
+
+
+def is_hosted_notebook() -> bool:
+    return bool(
+        os.environ.get("KAGGLE_KERNEL_RUN_TYPE")
+        or os.path.exists("/home/ec2-user/SageMaker")
+    )
+
+
+def ipython_check() -> bool:
+    is_ipython = False
+    try:
+        from IPython.core.getipython import get_ipython  # noqa: PLC0415
+
+        if get_ipython() is not None:
+            is_ipython = True
+    except (ImportError, NameError):
+        pass
+    return is_ipython

trackio/markdown.py

@@ -0,0 +1,21 @@
+class Markdown:
+    """
+    Markdown report data type for Trackio.
+
+    Args:
+        text (`str`):
+            Markdown content to log.
+    """
+
+    TYPE = "trackio.markdown"
+
+    def __init__(self, text: str = ""):
+        if not isinstance(text, str):
+            raise ValueError("Markdown text must be a string")
+        self.text = text
+
+    def _to_dict(self) -> dict:
+        return {
+            "_type": self.TYPE,
+            "_value": self.text,
+        }

trackio/mcp_setup.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import os
+import secrets
+from contextlib import asynccontextmanager
+from typing import Any
+
+from starlette.routing import Mount
+
+from trackio.sqlite_storage import SQLiteStorage
+
+
+def _assert_mcp_mutation_access(
+    *,
+    hf_token: str | None = None,
+    write_token: str | None = None,
+) -> None:
+    import trackio.server as trackio_server  # noqa: PLC0415
+
+    if os.getenv("SYSTEM") == "spaces":
+        try:
+            trackio_server.check_hf_token_has_write_access(hf_token)
+        except PermissionError as e:
+            raise ValueError(str(e)) from e
+        return
+
+    if not secrets.compare_digest(write_token or "", trackio_server.write_token or ""):
+        raise ValueError(
+            "A write_token is required for Trackio MCP mutations. "
+            "Use the write token from the dashboard URL."
+        )
+
+
+def create_mcp_integration() -> tuple[list[Any], Any]:
+    from mcp.server.fastmcp import FastMCP  # noqa: PLC0415
+
+    import trackio.server as trackio_server  # noqa: PLC0415
+
+    mcp = FastMCP(
+        "Trackio",
+        instructions="Inspect and manage Trackio experiment data.",
+        streamable_http_path="/",
+        log_level="WARNING",
+    )
+
+    mcp.add_tool(
+        trackio_server.get_all_projects,
+        description="List all Trackio projects available on this server.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_runs_for_project,
+        description="List runs for a given Trackio project.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_metrics_for_run,
+        description="List metric names recorded for a given Trackio run.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_project_summary,
+        description="Return summary metadata for a Trackio project.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_run_summary,
+        description="Return summary metadata for a Trackio run.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_metric_values,
+        description="Fetch metric values for a run, optionally around a step or time.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_system_metrics_for_run,
+        description="List system metric names recorded for a run.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_system_logs,
+        description="Fetch system metric logs for a run.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_snapshot,
+        description="Fetch a single Trackio snapshot around a step or timestamp.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_logs,
+        description="Fetch Trackio metric logs for a run.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_alerts,
+        description="Fetch alerts for a project, optionally filtered by run or level.",
+        structured_output=True,
+    )
+    mcp.add_tool(
+        trackio_server.get_settings,
+        description="Return Trackio dashboard settings and asset configuration.",
+        structured_output=True,
+    )
+
+    @mcp.tool(
+        description="Delete a run. On Spaces, pass an hf_token with write access.",
+        structured_output=True,
+    )
+    def delete_run(
+        project: str,
+        run: str,
+        hf_token: str | None = None,
+        write_token: str | None = None,
+    ) -> bool:
+        _assert_mcp_mutation_access(hf_token=hf_token, write_token=write_token)
+        return SQLiteStorage.delete_run(project, run)
+
+    @mcp.tool(
+        description="Rename a run. On Spaces, pass an hf_token with write access.",
+        structured_output=True,
+    )
+    def rename_run(
+        project: str,
+        old_name: str,
+        new_name: str,
+        hf_token: str | None = None,
+        write_token: str | None = None,
+    ) -> bool:
+        _assert_mcp_mutation_access(hf_token=hf_token, write_token=write_token)
+        SQLiteStorage.rename_run(project, old_name, new_name)
+        return True
+
+    @mcp.tool(
+        description=(
+            "Trigger a Trackio export/sync pass. On Spaces, pass an hf_token with "
+            "write access."
+        ),
+        structured_output=True,
+    )
+    def trigger_sync(
+        hf_token: str | None = None,
+        write_token: str | None = None,
+    ) -> bool:
+        _assert_mcp_mutation_access(hf_token=hf_token, write_token=write_token)
+        return trackio_server.force_sync()
+
+    mcp_app = mcp.streamable_http_app()
+
+    @asynccontextmanager
+    async def mcp_lifespan_context(app):
+        async with mcp.session_manager.run():
+            yield
+
+    return [Mount("/mcp", app=mcp_app)], mcp_lifespan_context

trackio/media/__init__.py

@@ -0,0 +1,27 @@
+"""
+Media module for Trackio.
+
+This module contains all media-related functionality including:
+- TrackioImage, TrackioVideo, TrackioAudio classes
+- Video writing utilities
+- Audio conversion utilities
+"""
+
+from trackio.media.audio import TrackioAudio
+from trackio.media.image import TrackioImage
+from trackio.media.media import TrackioMedia
+from trackio.media.utils import get_project_media_path
+from trackio.media.video import TrackioVideo
+
+write_audio = TrackioAudio.write_audio
+write_video = TrackioVideo.write_video
+
+__all__ = [
+    "TrackioMedia",
+    "TrackioImage",
+    "TrackioVideo",
+    "TrackioAudio",
+    "get_project_media_path",
+    "write_video",
+    "write_audio",
+]

trackio/media/audio.py

@@ -0,0 +1,189 @@
+import os
+import shutil
+import subprocess
+import warnings
+import wave
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+
+from trackio.media.media import TrackioMedia
+from trackio.media.utils import check_ffmpeg_installed, check_path
+
+SUPPORTED_FORMATS = ["wav", "mp3"]
+AudioFormatType = Literal["wav", "mp3"]
+TrackioAudioSourceType = str | Path | np.ndarray
+
+
+class TrackioAudio(TrackioMedia):
+    """
+    Initializes an Audio object.
+
+    Example:
+        ```python
+        import trackio
+        import numpy as np
+
+        # Generate a 1-second 440 Hz sine wave (mono)
+        sr = 16000
+        t = np.linspace(0, 1, sr, endpoint=False)
+        wave = 0.2 * np.sin(2 * np.pi * 440 * t)
+        audio = trackio.Audio(wave, caption="A4 sine", sample_rate=sr, format="wav")
+        trackio.log({"tone": audio})
+
+        # Stereo from numpy array (shape: samples, 2)
+        stereo = np.stack([wave, wave], axis=1)
+        audio = trackio.Audio(stereo, caption="Stereo", sample_rate=sr, format="mp3")
+        trackio.log({"stereo": audio})
+
+        # From an existing file
+        audio = trackio.Audio("path/to/audio.wav", caption="From file")
+        trackio.log({"file_audio": audio})
+        ```
+
+    Args:
+        value (`str`, `Path`, or `numpy.ndarray`, *optional*):
+            A path to an audio file, or a numpy array.
+            The array should be shaped `(samples,)` for mono or `(samples, 2)` for stereo.
+            Float arrays will be peak-normalized and converted to 16-bit PCM; integer arrays will be converted to 16-bit PCM as needed.
+        caption (`str`, *optional*):
+            A string caption for the audio.
+        sample_rate (`int`, *optional*):
+            Sample rate in Hz. Required when `value` is a numpy array.
+        format (`Literal["wav", "mp3"]`, *optional*):
+            Audio format used when `value` is a numpy array. Default is "wav".
+    """
+
+    TYPE = "trackio.audio"
+
+    def __init__(
+        self,
+        value: TrackioAudioSourceType,
+        caption: str | None = None,
+        sample_rate: int | None = None,
+        format: AudioFormatType | None = None,
+    ):
+        super().__init__(value, caption)
+        if isinstance(value, np.ndarray):
+            if sample_rate is None:
+                raise ValueError("Sample rate is required when value is an ndarray")
+            if format is None:
+                format = "wav"
+        self._format = format
+        self._sample_rate = sample_rate
+
+    def _save_media(self, file_path: Path):
+        if isinstance(self._value, np.ndarray):
+            TrackioAudio.write_audio(
+                data=self._value,
+                sample_rate=self._sample_rate,
+                filename=file_path,
+                format=self._format,
+            )
+        elif isinstance(self._value, str | Path):
+            if os.path.isfile(self._value):
+                shutil.copy(self._value, file_path)
+            else:
+                raise ValueError(f"File not found: {self._value}")
+
+    @staticmethod
+    def ensure_int16_pcm(data: np.ndarray) -> np.ndarray:
+        """
+        Convert input audio array to contiguous int16 PCM.
+        Peak normalization is applied to floating inputs.
+        """
+        arr = np.asarray(data)
+        if arr.ndim not in (1, 2):
+            raise ValueError("Audio data must be 1D (mono) or 2D ([samples, channels])")
+
+        if arr.dtype != np.int16:
+            warnings.warn(
+                f"Converting {arr.dtype} audio to int16 PCM; pass int16 to avoid conversion.",
+                stacklevel=2,
+            )
+
+        arr = np.nan_to_num(arr, copy=False)
+
+        # Floating types: normalize to peak 1.0, then scale to int16
+        if np.issubdtype(arr.dtype, np.floating):
+            max_abs = float(np.max(np.abs(arr))) if arr.size else 0.0
+            if max_abs > 0.0:
+                arr = arr / max_abs
+            out = (arr * 32767.0).clip(-32768, 32767).astype(np.int16, copy=False)
+            return np.ascontiguousarray(out)
+
+        converters: dict[np.dtype, callable] = {
+            np.dtype(np.int16): lambda a: a,
+            np.dtype(np.int32): lambda a: (a.astype(np.int32) // 65536).astype(
+                np.int16, copy=False
+            ),
+            np.dtype(np.uint16): lambda a: (a.astype(np.int32) - 32768).astype(
+                np.int16, copy=False
+            ),
+            np.dtype(np.uint8): lambda a: (a.astype(np.int32) * 257 - 32768).astype(
+                np.int16, copy=False
+            ),
+            np.dtype(np.int8): lambda a: (a.astype(np.int32) * 256).astype(
+                np.int16, copy=False
+            ),
+        }
+
+        conv = converters.get(arr.dtype)
+        if conv is not None:
+            out = conv(arr)
+            return np.ascontiguousarray(out)
+        raise TypeError(f"Unsupported audio dtype: {arr.dtype}")
+
+    @staticmethod
+    def write_audio(
+        data: np.ndarray,
+        sample_rate: int,
+        filename: str | Path,
+        format: AudioFormatType = "wav",
+    ) -> None:
+        if not isinstance(sample_rate, int) or sample_rate <= 0:
+            raise ValueError(f"Invalid sample_rate: {sample_rate}")
+        if format not in SUPPORTED_FORMATS:
+            raise ValueError(
+                f"Unsupported format: {format}. Supported: {SUPPORTED_FORMATS}"
+            )
+
+        check_path(filename)
+
+        pcm = TrackioAudio.ensure_int16_pcm(data)
+
+        if format != "wav":
+            check_ffmpeg_installed()
+
+        channels = 1 if pcm.ndim == 1 else pcm.shape[1]
+        pcm_bytes = pcm.tobytes()
+
+        if format == "wav":
+            with wave.open(str(filename), "wb") as wf:
+                wf.setnchannels(channels)
+                wf.setsampwidth(2)
+                wf.setframerate(sample_rate)
+                wf.writeframes(pcm_bytes)
+        else:
+            cmd = [
+                "ffmpeg",
+                "-y",
+                "-loglevel",
+                "error",
+                "-f",
+                "s16le",
+                "-ar",
+                str(sample_rate),
+                "-ac",
+                str(channels),
+                "-i",
+                "pipe:0",
+                str(filename),
+            ]
+            proc = subprocess.run(
+                cmd, input=pcm_bytes, capture_output=True, check=False
+            )
+            if proc.returncode != 0:
+                stderr = proc.stderr.decode("utf-8", errors="replace").strip()
+                raise RuntimeError(f"ffmpeg failed to encode {format} audio: {stderr}")

trackio/media/image.py

@@ -0,0 +1,84 @@
+import os
+import shutil
+from pathlib import Path
+
+import numpy as np
+from PIL import Image as PILImage
+
+from trackio.media.media import TrackioMedia
+
+TrackioImageSourceType = str | Path | np.ndarray | PILImage.Image
+
+
+class TrackioImage(TrackioMedia):
+    """
+    Initializes an Image object.
+
+    Example:
+        ```python
+        import trackio
+        import numpy as np
+        from PIL import Image
+
+        # Create an image from numpy array
+        image_data = np.random.randint(0, 255, (64, 64, 3), dtype=np.uint8)
+        image = trackio.Image(image_data, caption="Random image")
+        trackio.log({"my_image": image})
+
+        # Create an image from PIL Image
+        pil_image = Image.new('RGB', (100, 100), color='red')
+        image = trackio.Image(pil_image, caption="Red square")
+        trackio.log({"red_image": image})
+
+        # Create an image from file path
+        image = trackio.Image("path/to/image.jpg", caption="Photo from file")
+        trackio.log({"file_image": image})
+        ```
+
+    Args:
+        value (`str`, `Path`, `numpy.ndarray`, or `PIL.Image`, *optional*):
+            A path to an image, a PIL Image, or a numpy array of shape (height, width, channels).
+            If numpy array, should be of type `np.uint8` with RGB values in the range `[0, 255]`.
+        caption (`str`, *optional*):
+            A string caption for the image.
+    """
+
+    TYPE = "trackio.image"
+
+    def __init__(self, value: TrackioImageSourceType, caption: str | None = None):
+        super().__init__(value, caption)
+        self._format: str | None = None
+
+        if not isinstance(self._value, TrackioImageSourceType):
+            raise ValueError(
+                f"Invalid value type, expected {TrackioImageSourceType}, got {type(self._value)}"
+            )
+        if isinstance(self._value, np.ndarray) and self._value.dtype != np.uint8:
+            raise ValueError(
+                f"Invalid value dtype, expected np.uint8, got {self._value.dtype}"
+            )
+        if (
+            isinstance(self._value, np.ndarray | PILImage.Image)
+            and self._format is None
+        ):
+            self._format = "png"
+
+    def _as_pil(self) -> PILImage.Image | None:
+        try:
+            if isinstance(self._value, np.ndarray):
+                arr = np.asarray(self._value).astype("uint8")
+                return PILImage.fromarray(arr).convert("RGBA")
+            if isinstance(self._value, PILImage.Image):
+                return self._value.convert("RGBA")
+        except Exception as e:
+            raise ValueError(f"Failed to process image data: {self._value}") from e
+        return None
+
+    def _save_media(self, file_path: Path):
+        if pil := self._as_pil():
+            pil.save(file_path, format=self._format)
+        elif isinstance(self._value, str | Path):
+            if os.path.isfile(self._value):
+                shutil.copy(self._value, file_path)
+            else:
+                raise ValueError(f"File not found: {self._value}")

trackio/media/media.py

@@ -0,0 +1,79 @@
+import os
+import uuid
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from trackio.media.utils import get_project_media_path
+from trackio.utils import MEDIA_DIR
+
+
+class TrackioMedia(ABC):
+    """
+    Abstract base class for Trackio media objects
+    Provides shared functionality for file handling and serialization.
+    """
+
+    TYPE: str
+
+    def __init_subclass__(cls, **kwargs):
+        """Ensure subclasses define the TYPE attribute."""
+        super().__init_subclass__(**kwargs)
+        if not hasattr(cls, "TYPE") or cls.TYPE is None:
+            raise TypeError(f"Class {cls.__name__} must define TYPE attribute")
+
+    def __init__(self, value, caption: str | None = None):
+        """
+        Saves the value and caption, and if the value is a file path, checks if the file exists.
+        """
+        self.caption = caption
+        self._value = value
+        self._file_path: Path | None = None
+
+        if isinstance(self._value, str | Path):
+            if not os.path.isfile(self._value):
+                raise ValueError(f"File not found: {self._value}")
+
+    def _file_extension(self) -> str:
+        if self._file_path:
+            return self._file_path.suffix[1:].lower()
+        if isinstance(self._value, str | Path):
+            path = Path(self._value)
+            return path.suffix[1:].lower()
+        if hasattr(self, "_format") and self._format:
+            return self._format
+        return "unknown"
+
+    def _get_relative_file_path(self) -> Path | None:
+        return self._file_path
+
+    def _get_absolute_file_path(self) -> Path | None:
+        if self._file_path:
+            return MEDIA_DIR / self._file_path
+        return None
+
+    def _save(self, project: str, run: str, step: int = 0):
+        if self._file_path:
+            return
+
+        media_dir = get_project_media_path(project=project, run=run, step=step)
+        filename = f"{uuid.uuid4()}.{self._file_extension()}"
+        file_path = media_dir / filename
+
+        self._save_media(file_path)
+        self._file_path = file_path.relative_to(MEDIA_DIR)
+
+    @abstractmethod
+    def _save_media(self, file_path: Path):
+        """
+        Performs the actual media saving logic.
+        """
+        pass
+
+    def _to_dict(self) -> dict:
+        if not self._file_path:
+            raise ValueError("Media must be saved to file before serialization")
+        return {
+            "_type": self.TYPE,
+            "file_path": str(self._get_relative_file_path()),
+            "caption": self.caption,
+        }

trackio/media/utils.py

@@ -0,0 +1,60 @@
+import shutil
+from pathlib import Path
+
+from trackio.utils import MEDIA_DIR
+
+
+def check_path(file_path: str | Path) -> None:
+    """Raise an error if the parent directory does not exist."""
+    file_path = Path(file_path)
+    if not file_path.parent.exists():
+        try:
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            raise ValueError(
+                f"Failed to create parent directory {file_path.parent}: {e}"
+            )
+
+
+def check_ffmpeg_installed() -> None:
+    """Raise an error if ffmpeg is not available on the system PATH."""
+    if shutil.which("ffmpeg") is None:
+        raise RuntimeError(
+            "ffmpeg is required to write this media format but was not found on your system. "
+            "Please install ffmpeg and ensure it is available on your PATH."
+        )
+
+
+def get_project_media_path(
+    project: str,
+    run: str | None = None,
+    step: int | None = None,
+    relative_path: str | Path | None = None,
+) -> Path:
+    """
+    Get the full path where uploaded files are stored for a Trackio project (and create the directory if it doesn't exist).
+    If a run is not provided, the files are stored in a project-level directory with the given relative path.
+
+    Args:
+        project: The project name
+        run: The run name
+        step: The step number
+        relative_path: The relative path within the directory (only used if run is not provided)
+
+    Returns:
+        The full path to the media file
+    """
+    if step is not None and run is None:
+        raise ValueError("Uploading files at a specific step requires a run")
+
+    path = MEDIA_DIR / project
+    if run:
+        path /= run
+        if step is not None:
+            path /= str(step)
+    else:
+        path /= "files"
+        if relative_path:
+            path /= relative_path
+    path.mkdir(parents=True, exist_ok=True)
+    return path

trackio/media/video.py

@@ -0,0 +1,246 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+
+from trackio.media.media import TrackioMedia
+from trackio.media.utils import check_ffmpeg_installed, check_path
+
+TrackioVideoSourceType = str | Path | np.ndarray
+TrackioVideoFormatType = Literal["gif", "mp4", "webm"]
+VideoCodec = Literal["h264", "vp9", "gif"]
+
+
+class TrackioVideo(TrackioMedia):
+    """
+    Initializes a Video object.
+
+    Example:
+        ```python
+        import trackio
+        import numpy as np
+
+        # Create a simple video from numpy array
+        frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
+        video = trackio.Video(frames, caption="Random video", fps=30)
+
+        # Create a batch of videos
+        batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
+        batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)
+
+        # Create video from file path
+        video = trackio.Video("path/to/video.mp4", caption="Video from file")
+        ```
+
+    Args:
+        value (`str`, `Path`, or `numpy.ndarray`, *optional*):
+            A path to a video file, or a numpy array.
+            If numpy array, should be of type `np.uint8` with RGB values in the range `[0, 255]`.
+            It is expected to have shape of either (frames, channels, height, width) or (batch, frames, channels, height, width).
+            For the latter, the videos will be tiled into a grid.
+        caption (`str`, *optional*):
+            A string caption for the video.
+        fps (`int`, *optional*):
+            Frames per second for the video. Only used when value is an ndarray. Default is `24`.
+        format (`Literal["gif", "mp4", "webm"]`, *optional*):
+            Video format ("gif", "mp4", or "webm"). Only used when value is an ndarray. Default is "gif".
+    """
+
+    TYPE = "trackio.video"
+
+    def __init__(
+        self,
+        value: TrackioVideoSourceType,
+        caption: str | None = None,
+        fps: int | None = None,
+        format: TrackioVideoFormatType | None = None,
+    ):
+        super().__init__(value, caption)
+
+        if not isinstance(self._value, TrackioVideoSourceType):
+            raise ValueError(
+                f"Invalid value type, expected {TrackioVideoSourceType}, got {type(self._value)}"
+            )
+        if isinstance(self._value, np.ndarray):
+            if self._value.dtype != np.uint8:
+                raise ValueError(
+                    f"Invalid value dtype, expected np.uint8, got {self._value.dtype}"
+                )
+            if format is None:
+                format = "gif"
+            if fps is None:
+                fps = 24
+        self._fps = fps
+        self._format = format
+
+    @staticmethod
+    def _check_array_format(video: np.ndarray) -> None:
+        """Raise an error if the array is not in the expected format."""
+        if not (video.ndim == 4 and video.shape[-1] == 3):
+            raise ValueError(
+                f"Expected RGB input shaped (F, H, W, 3), got {video.shape}. "
+                f"Input has {video.ndim} dimensions, expected 4."
+            )
+        if video.dtype != np.uint8:
+            raise TypeError(
+                f"Expected dtype=uint8, got {video.dtype}. "
+                "Please convert your video data to uint8 format."
+            )
+
+    @staticmethod
+    def write_video(
+        file_path: str | Path, video: np.ndarray, fps: float, codec: VideoCodec
+    ) -> None:
+        """RGB uint8 only, shape (F, H, W, 3)."""
+        check_ffmpeg_installed()
+        check_path(file_path)
+
+        if codec not in {"h264", "vp9", "gif"}:
+            raise ValueError("Unsupported codec. Use h264, vp9, or gif.")
+
+        arr = np.asarray(video)
+        TrackioVideo._check_array_format(arr)
+
+        frames = np.ascontiguousarray(arr)
+        _, height, width, _ = frames.shape
+        out_path = str(file_path)
+
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-f",
+            "rawvideo",
+            "-s",
+            f"{width}x{height}",
+            "-pix_fmt",
+            "rgb24",
+            "-r",
+            str(fps),
+            "-i",
+            "-",
+            "-an",
+        ]
+
+        if codec == "gif":
+            video_filter = "split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse"
+            cmd += [
+                "-vf",
+                video_filter,
+                "-loop",
+                "0",
+            ]
+        elif codec == "h264":
+            cmd += [
+                "-vcodec",
+                "libx264",
+                "-pix_fmt",
+                "yuv420p",
+                "-movflags",
+                "+faststart",
+            ]
+        elif codec == "vp9":
+            bpp = 0.08
+            bps = int(width * height * fps * bpp)
+            if bps >= 1_000_000:
+                bitrate = f"{round(bps / 1_000_000)}M"
+            elif bps >= 1_000:
+                bitrate = f"{round(bps / 1_000)}k"
+            else:
+                bitrate = str(max(bps, 1))
+            cmd += [
+                "-vcodec",
+                "libvpx-vp9",
+                "-b:v",
+                bitrate,
+                "-pix_fmt",
+                "yuv420p",
+            ]
+        cmd += [out_path]
+        proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+        try:
+            for frame in frames:
+                proc.stdin.write(frame.tobytes())
+        finally:
+            if proc.stdin:
+                proc.stdin.close()
+            stderr = (
+                proc.stderr.read().decode("utf-8", errors="ignore")
+                if proc.stderr
+                else ""
+            )
+            ret = proc.wait()
+            if ret != 0:
+                raise RuntimeError(f"ffmpeg failed with code {ret}\n{stderr}")
+
+    @property
+    def _codec(self) -> str:
+        match self._format:
+            case "gif":
+                return "gif"
+            case "mp4":
+                return "h264"
+            case "webm":
+                return "vp9"
+            case _:
+                raise ValueError(f"Unsupported format: {self._format}")
+
+    def _save_media(self, file_path: Path):
+        if isinstance(self._value, np.ndarray):
+            video = TrackioVideo._process_ndarray(self._value)
+            TrackioVideo.write_video(file_path, video, fps=self._fps, codec=self._codec)
+        elif isinstance(self._value, str | Path):
+            if os.path.isfile(self._value):
+                shutil.copy(self._value, file_path)
+            else:
+                raise ValueError(f"File not found: {self._value}")
+
+    @staticmethod
+    def _process_ndarray(value: np.ndarray) -> np.ndarray:
+        # Verify value is either 4D (single video) or 5D array (batched videos).
+        # Expected format: (frames, channels, height, width) or (batch, frames, channels, height, width)
+        if value.ndim < 4:
+            raise ValueError(
+                "Video requires at least 4 dimensions (frames, channels, height, width)"
+            )
+        if value.ndim > 5:
+            raise ValueError(
+                "Videos can have at most 5 dimensions (batch, frames, channels, height, width)"
+            )
+        if value.ndim == 4:
+            # Reshape to 5D with single batch: (1, frames, channels, height, width)
+            value = value[np.newaxis, ...]
+
+        value = TrackioVideo._tile_batched_videos(value)
+        return value
+
+    @staticmethod
+    def _tile_batched_videos(video: np.ndarray) -> np.ndarray:
+        """
+        Tiles a batch of videos into a grid of videos.
+
+        Input format: (batch, frames, channels, height, width) - original FCHW format
+        Output format: (frames, total_height, total_width, channels)
+        """
+        batch_size, frames, channels, height, width = video.shape
+
+        next_pow2 = 1 << (batch_size - 1).bit_length()
+        if batch_size != next_pow2:
+            pad_len = next_pow2 - batch_size
+            pad_shape = (pad_len, frames, channels, height, width)
+            padding = np.zeros(pad_shape, dtype=video.dtype)
+            video = np.concatenate((video, padding), axis=0)
+            batch_size = next_pow2
+
+        n_rows = 1 << ((batch_size.bit_length() - 1) // 2)
+        n_cols = batch_size // n_rows
+
+        # Reshape to grid layout: (n_rows, n_cols, frames, channels, height, width)
+        video = video.reshape(n_rows, n_cols, frames, channels, height, width)
+
+        # Rearrange dimensions to (frames, total_height, total_width, channels)
+        video = video.transpose(2, 0, 4, 1, 5, 3)
+        video = video.reshape(frames, n_rows * height, n_cols * width, channels)
+        return video