Experiment Tracking Swanlab

# SwanLab Framework Integrations

This document focuses on framework patterns that align with the public SwanLab docs.

## PyTorch

### Basic Training Loop

```python
import torch
import torch.nn as nn
import torch.optim as optim
import swanlab

run = swanlab.init(
    project="pytorch-training",
    experiment_name="mnist-mlp",
    config={
        "learning_rate": 1e-3,
        "batch_size": 64,
        "epochs": 10,
        "hidden_size": 128,
    },
)

model = nn.Sequential(
    nn.Flatten(),
    nn.Linear(28 * 28, run.config.hidden_size),
    nn.ReLU(),
    nn.Linear(run.config.hidden_size, 10),
)
optimizer = optim.Adam(model.parameters(), lr=run.config.learning_rate)
criterion = nn.CrossEntropyLoss()

for epoch in range(run.config.epochs):
    model.train()
    for batch_idx, (data, target) in enumerate(train_loader):
        optimizer.zero_grad()
        logits = model(data)
        loss = criterion(logits, target)
        loss.backward()
        optimizer.step()

        if batch_idx % 100 == 0:
            swanlab.log(
                {
                    "train/loss": loss.item(),
                    "train/epoch": epoch,
                    "train/batch": batch_idx,
                }
            )

run.finish()
```

### Minimal Callback Wrapper

```python
import swanlab

class SwanLabTracker:
    def __init__(self, project, experiment_name=None, config=None):
        self.run = swanlab.init(
            project=project,
            experiment_name=experiment_name,
            config=config,
        )

    def log_metrics(self, metrics, step=None):
        swanlab.log(metrics, step=step)

    def log_images(self, name, images, captions=None):
        if captions is None:
            payload = [swanlab.Image(image) for image in images]
        else:
            payload = [
                swanlab.Image(image, caption=caption)
                for image, caption in zip(images, captions)
            ]
        swanlab.log({name: payload})

    def log_note(self, name, text):
        swanlab.log({name: swanlab.Text(text)})

    def finish(self):
        self.run.finish()
```

This wrapper deliberately omits fake histogram and file helpers that are not present in current SwanLab APIs.

## Transformers

### `transformers>=4.50.0`: official one-line integration

Prefer `report_to="swanlab"` on recent Transformers releases. This is the primary path documented by SwanLab.

```python
from transformers import (
    AutoModelForSequenceClassification,
    AutoTokenizer,
    Trainer,
    TrainingArguments,
)

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModelForSequenceClassification.from_pretrained(
    "bert-base-uncased",
    num_labels=2,
)

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    evaluation_strategy="epoch",
    logging_steps=100,
    report_to="swanlab",
    run_name="bert-imdb",
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
)

trainer.train()
```

Set `SWANLAB_PROJ_NAME` and `SWANLAB_WORKSPACE` environment variables when you need custom routing without switching away from the official integration path.

### `transformers<4.50.0` or custom control: `SwanLabCallback`

Use `SwanLabCallback` as the fallback path for older Transformers versions, or when you want SwanLab-specific control without `report_to="swanlab"`.

```python
from transformers import (
    AutoModelForSequenceClassification,
    AutoTokenizer,
    Trainer,
    TrainingArguments,
)
from swanlab.integration.transformers import SwanLabCallback

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModelForSequenceClassification.from_pretrained(
    "bert-base-uncased",
    num_labels=2,
)

training_args = TrainingArguments(
    output_dir="./results",
    evaluation_strategy="epoch",
    logging_steps=100,
    rep