docs: add TRL integration guide (#537)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Quentin Gallouédec <45557362+qgallouedec@users.noreply.github.com>

Author: 3 people

docs/source/_toctree.yml

@@ -36,9 +36,11 @@
   title: How-to guides
 - sections:
   - local: transformers_integration
-    title: Transformers Trainer
+    title: Running with Transformers
+  - local: trl_integration
+    title: Running with TRL
   - local: rapidfireai_integration
-    title: RapidFire AI
+    title: Running with RapidFire AI
   title: Integration
 - sections:
   - local: api

docs/source/trl_integration.md

@@ -0,0 +1,37 @@
+# TRL Integration
+
+Trackio integrates natively with [TRL](https://github.com/huggingface/trl) so you can log metrics from any TRL trainer (`SFTTrainer`, `DPOTrainer`, `GRPOTrainer`, etc.) with minimal setup. Ensure you have the latest version of `trl` installed (version 1.2.0 or higher).
+
+```python
+from datasets import Dataset
+from trl import SFTConfig, SFTTrainer
+
+# Create a small fake dataset
+prompts = ["The capital of France is", "Hamlet was written by"] * 12
+completions = [" Paris.", " Shakespeare."] * 12
+dataset = Dataset.from_dict({"prompt": prompts, "completion": completions})
+
+# Train a model using the TRL SFTTrainer API
+trainer = SFTTrainer(
+    model="Qwen/Qwen3-0.6B",
+    args=SFTConfig(report_to="trackio", run_name="Qwen3-0.6B-sft"),
+    train_dataset=dataset,
+)
+trainer.train()
+```
+
+## Configuring Project and Space
+
+Set the project and space ID directly in your TRL config (e.g. [`~trl.SFTConfig`], [`~trl.DPOConfig`], [`~trl.GRPOConfig`]):
+
+```python
+from trl import SFTConfig
+
+args = SFTConfig(
+    report_to="trackio",
+    run_name="my-run",
+    project="my-project",
+    trackio_space_id="username/space_id",
+)
+```
+

examples/trl-integration.py

@@ -0,0 +1,50 @@
+# /// script
+# dependencies = [
+#   "trackio>=0.23.0",
+#   "trl>=1.2.0",
+# ]
+# ///
+
+import random
+
+from datasets import Dataset
+from trl import SFTConfig, SFTTrainer
+
+suffix = random.randint(100000, 999999)
+project_name = f"trackio-trl-demo-{suffix}"
+
+prompts = [
+    [{"role": "user", "content": "What is the capital of France?"}],
+    [{"role": "user", "content": "Who wrote Hamlet?"}],
+    [{"role": "user", "content": "What is 2 + 2?"}],
+    [{"role": "user", "content": "What color is the sky?"}],
+    [{"role": "user", "content": "Name a primary color."}],
+    [{"role": "user", "content": "What is the largest planet?"}],
+] * 4
+completions = [
+    [{"role": "assistant", "content": "Paris."}],
+    [{"role": "assistant", "content": "Shakespeare."}],
+    [{"role": "assistant", "content": "4."}],
+    [{"role": "assistant", "content": "Blue."}],
+    [{"role": "assistant", "content": "Red."}],
+    [{"role": "assistant", "content": "Jupiter."}],
+] * 4
+dataset = Dataset.from_dict({"prompt": prompts, "completion": completions})
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen3-0.6B",
+    args=SFTConfig(
+        output_dir="./model_output",
+        num_train_epochs=1,
+        per_device_train_batch_size=4,
+        learning_rate=2e-5,
+        logging_steps=1,
+        report_to="trackio",
+        project=project_name,
+    ),
+    train_dataset=dataset,
+)
+
+trainer.train()
+
+print(f"Run complete. Open with: trackio show --project {project_name}")