Add markdown reports across Trackio (#437)

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

Author: 3 people

.changeset/ready-rats-kneel.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Add markdown reports across Trackio

docs/source/cli_commands.md

@@ -60,6 +60,26 @@ Output in JSON format:
 trackio list system-metrics --project "my-project" --run "my-run" --json
 ```
 
+### List Reports
+
+List markdown reports in a project (across all runs):
+
+```sh
+trackio list reports --project "my-project"
+```
+
+List markdown reports for a specific run:
+
+```sh
+trackio list reports --project "my-project" --run "my-run"
+```
+
+Output in JSON format:
+
+```sh
+trackio list reports --project "my-project" --run "my-run" --json
+```
+
 ## Get Commands
 
 ### Get Project Summary
@@ -140,6 +160,20 @@ Output in JSON format:
 trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization" --json
 ```
 
+### Get Report Content
+
+Print markdown report entries for a specific report name in a run:
+
+```sh
+trackio get report --project "my-project" --run "my-run" --report "training_report"
+```
+
+Output in JSON format:
+
+```sh
+trackio get report --project "my-project" --run "my-run" --report "training_report" --json
+```
+
 ## Output Formats
 
 All commands support two output formats:
@@ -154,6 +188,7 @@ The CLI commands include comprehensive validation and error handling:
 - If a project doesn't exist, an error message is displayed
 - If a run doesn't exist in a project, an error message is displayed
 - If a metric doesn't exist in a run, an error message is displayed
+- If a report doesn't exist in a run, an error message is displayed
 
 All errors are written to stderr and the command exits with a non-zero exit code.
 
@@ -182,6 +217,12 @@ trackio get metric --project "my-project" --run "my-run" --metric "loss"
 
 # 7. Get system metrics (if available)
 trackio list system-metrics --project "my-project" --run "my-run"
+
+# 8. List reports in a run
+trackio list reports --project "my-project" --run "my-run"
+
+# 9. Print report markdown in terminal
+trackio get report --project "my-project" --run "my-run" --report "training_report"
 ```
 
 ## Use Cases

docs/source/track.md

@@ -91,6 +91,30 @@ trackio.log(
     style="border:0;">
 </iframe>
 
+### Logging reports (Markdown)
+
+You can log markdown reports using the [`Markdown`] class. Reports are shown in the **Reports** page in the dashboard, where the newest report appears first.
+
+```python
+trackio.log(
+    {
+        "training_report": trackio.Markdown(
+            """# Training Report
+
+Final validation accuracy: **0.92**
+
+- Best epoch: 18
+- Early stopping: enabled
+"""
+        )
+    }
+)
+```
+
+You can log reports multiple times during a run (for example, one report per checkpoint), and Trackio will keep the full history across steps.
+
+For a complete runnable script, see `examples/training-with-report.py`.
+
 ### Logging images
 
 You can log images using the [`Image`] class.

examples/training-with-report.py

@@ -0,0 +1,51 @@
+import random
+import time
+
+import trackio
+
+PROJECT_ID = random.randint(100000, 999999)
+PROJECT_NAME = f"report-demo-{PROJECT_ID}"
+
+trackio.init(
+    project=PROJECT_NAME,
+    name="run-with-report",
+    config={"epochs": 12, "learning_rate": 0.001},
+)
+
+loss_values = []
+accuracy_values = []
+
+for step in range(12):
+    loss = round(1.2 / (step + 1) + random.uniform(-0.03, 0.03), 4)
+    accuracy = round(min(0.98, 0.5 + step * 0.04 + random.uniform(-0.02, 0.02)), 4)
+    loss_values.append(loss)
+    accuracy_values.append(accuracy)
+
+    trackio.log(
+        {
+            "train/loss": loss,
+            "train/accuracy": accuracy,
+        },
+        step=step,
+    )
+    time.sleep(0.1)
+
+best_accuracy = max(accuracy_values)
+final_loss = loss_values[-1]
+final_accuracy = accuracy_values[-1]
+
+report_md = f"""# Training Report
+
+Training completed for `{PROJECT_NAME}`.
+
+## Final Metrics
+
+- Final loss: `{final_loss}`
+- Final accuracy: `{final_accuracy}`
+- Best accuracy: `{best_accuracy}`
+"""
+
+trackio.log({"training_report": trackio.Markdown(report_md)})
+trackio.finish()
+
+print(f"Run complete. Open with: trackio show --project {PROJECT_NAME}")

tests/unit/test_run.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from trackio import Run, init
+from trackio import Markdown, Run, init
 from trackio.sqlite_storage import SQLiteStorage
 
 
@@ -28,6 +28,23 @@ def test_run_log_writes_to_sqlite_locally(temp_dir):
     assert config is not None
 
 
+def test_markdown_logging(temp_dir):
+    run = Run(url=None, project="proj", client=None, name="run-report", space_id=None)
+    run.log({"loss": 0.1, "summary": Markdown("# Training summary")})
+    run.finish()
+
+    logs = SQLiteStorage.get_logs("proj", "run-report")
+
+    markdown_entries = [
+        entry
+        for entry in logs
+        if isinstance(entry.get("summary"), dict)
+        and entry["summary"].get("_type") == Markdown.TYPE
+    ]
+    assert len(markdown_entries) == 1
+    assert markdown_entries[0]["summary"]["_value"] == "# Training summary"
+
+
 def test_run_log_calls_client_for_spaces(temp_dir):
     client = DummyClient()
     run = Run(

trackio/__init__.py

@@ -22,6 +22,7 @@
 from trackio.gpu import gpu_available, log_gpu
 from trackio.histogram import Histogram
 from trackio.imports import import_csv, import_tf_events
+from trackio.markdown import Markdown
 from trackio.media import (
     TrackioAudio,
     TrackioImage,
@@ -64,6 +65,7 @@
     "Audio",
     "Table",
     "Histogram",
+    "Markdown",
     "Api",
 ]
 
@@ -165,7 +167,6 @@ def init(
         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`.
-
     Returns:
         `Run`: A [`Run`] object that can be used to log metrics and finish the run.
     """