changes

Author: abidlabs

.cursor/commands/validate-examples.md

@@ -0,0 +1,26 @@
+---
+description: Stress-test the Trackio library via random examples, CLI, and Playwright UI
+argument-hint: "[--count 3] [--seed 42] [--jobs 3] [--space username/space] [--continue-on-failure]"
+---
+
+Run the Trackio library validator (examples are only the workload; failures are interpreted as possible Trackio regressions):
+
+`python scripts/validate_examples.py $ARGUMENTS`
+
+If dependencies are missing, install dev dependencies first:
+
+`pip install -e .[dev,tensorboard]`
+
+Behavior:
+
+- Runs a random subset of `examples/` scripts (default `--count 3`) to exercise logging, imports, and CLI
+- Uses isolated `TRACKIO_DIR` per run (one shared DB when `--jobs 1`, separate sandboxes when `--jobs` > 1)
+- **Sequential vs parallel:** default is **parallel** (`--jobs 3`). Use **`--jobs N`** to tune worker count; use `--jobs 1` for sequential mode. CLI checks and UI driving stay sequential afterward so ports and Playwright stay stable
+- After successful example runs, validates **Trackio CLI** (`list` / `get` with JSON) and the **dashboard** via Playwright (tabs, checkboxes, screenshots)
+- Collects **Trackio-related** signals (tracebacks touching `trackio`, CLI failures, dashboard console/page issues, etc.), **deduplicates** them, and prints a **`=== Trackio library health report ===`** section at the end. Exit code is non-zero if anything was collected or an example run failed (unless you stop early without `--continue-on-failure`)
+- Writes `summary.json` under the artifacts directory (includes `trackio_issues` and paths)
+- For remote Spaces data, pass **`--space`** to CLI-backed checks as documented in the Trackio CLI
+
+Optional:
+
+- `--continue-on-failure` — run the remaining examples after a failure; CLI/UI run only for examples that completed successfully

README.md

@@ -20,13 +20,20 @@
 
 </div>
 
-Welcome to `trackio`: a lightweight, <u>free</u> experiment tracking library built by Hugging Face 🤗. Trackio is local-first, supports very high logging throughputs for many parallel experiments, and provides an easy CLI interface for querying, perfect for LLM-driven experimenting.
+Welcome to `trackio`: a lightweight, <u>free</u> experiment tracking library built by Hugging Face for humans and AI agents 🤗. 
 
-For human users, Trackio ships with a Gradio-based dashboard so you can view metrics, media, tables, alerts, etc.:
+Why Trackio when other experiment-tracking libraries exist? Trackio has a few qualities that make it particularly useful for  agents: 
+* It is local-first, because you shouldn't need to make an account to log data
+* Logs are stored in SQLite database (with support for "freezing" logs to Parquet), which not only supports very high throughputs for many parallel experiments, but also
+* provides an easy CLI interface for querying data (including directly on the SQL data), perfect for LLM-driven analysis.
+
+So whether you are using agents to run entire research experiments autonomously or whether you are just using LLMs to analyze data, Trackio is for you.
+
+For human users, Trackio _also_ ships with a Gradio-inspired dashboard so you can view metrics, media, tables, alerts, etc.:
 
 ![Screen Recording 2025-11-06 at 5 34 50 PM](https://github.com/user-attachments/assets/8c9c1b96-f17a-401c-83a4-26ac754f89c7)
 
-Trackio's main features:
+### Trackio's main features:
 
 - **API compatible** with `wandb.init`, `wandb.log`, and `wandb.finish`. Drop-in replacement: just 
 
@@ -35,16 +42,14 @@ Trackio's main features:
   ```
   and keep your existing logging code.
 
-- **Local-first** design: dashboard runs locally by default. You can also send metrics to a Hugging Face Space with `space_id` for free or to a self-hosted Trackio server you run yourself with `server_url`
-  - Persists logs in a Sqlite database locally (or on the remote target you chose: Space, or the machine hosting your self-hosted server)
-  - Visualize experiments with a **Svelte 5** dashboard locally, on Hugging Face Spaces, or on your own host when you self-host the server
+- **Local-first** design: dashboard runs locally by default. But note that you can also log metrics to a Hugging Face Space with `space_id` for free, which is useful for collaborative experiments.
 - **LLM-friendly**: Built with autonomous ML experiments in mind, Trackio includes a CLI for programmatic access and a Python API for run management, making it easy for LLMs to log metrics and query experiment data.
   - Use `trackio query project --project <name> --sql "SELECT ..."` for read-only SQL when `trackio list` and `trackio get` are not enough
   - See the storage schema and direct query reference at https://huggingface.co/docs/trackio/storage_schema
 
 - **Free**: Everything here, including hosting on Hugging Face, is free!
 
-Trackio is designed to be lightweight and _forkable_: **Python** for the backend and API, **Svelte 5** for the dashboard, and **Gradio component** code where UI widgets need to match Gradio behavior—so developers can fork the repository and extend either side.
+Trackio is designed to be lightweight and _forkable_: **Python** for the backend and API, **Svelte 5** for the dashboard, so developers can fork the repository and extend either side.
 
 ## Installation