@r1z4x/tezgah 1.0.0

package/skills/ai-research/13-mlops/swanlab/SKILL.md

@@ -0,0 +1,406 @@
+---
+name: experiment-tracking-swanlab
+description: Provides guidance for experiment tracking with SwanLab. Use when you need open-source run tracking, local or self-hosted dashboards, and lightweight media logging for ML workflows.
+version: 1.0.0
+author: Orchestra Research
+license: MIT
+tags: [MLOps, SwanLab, Experiment Tracking, Open Source, Visualization, PyTorch, Transformers, PyTorch Lightning, Fastai, Self-Hosted]
+dependencies: [swanlab>=0.7.11, pillow>=9.0.0, soundfile>=0.12.0]
+---
+
+# SwanLab: Open-Source Experiment Tracking
+
+## When to Use This Skill
+
+Use SwanLab when you need to:
+- **Track ML experiments** with metrics, configs, tags, and descriptions
+- **Visualize training** with scalar charts and logged media
+- **Compare runs** across seeds, checkpoints, and hyperparameters
+- **Work locally or self-hosted** instead of depending on managed SaaS
+- **Integrate** with PyTorch, Transformers, PyTorch Lightning, or Fastai
+
+**Deployment**: Cloud, local, or self-hosted | **Media**: images, audio, text, GIFs, point clouds, molecules | **Integrations**: PyTorch, Transformers, PyTorch Lightning, Fastai
+
+## Installation
+
+```bash
+# Install SwanLab plus the media dependencies used in this skill
+pip install "swanlab>=0.7.11" "pillow>=9.0.0" "soundfile>=0.12.0"
+
+# Add local dashboard support for mode="local" and swanlab watch
+pip install "swanlab[dashboard]>=0.7.11"
+
+# Optional framework integrations
+pip install transformers pytorch-lightning fastai
+
+# Login for cloud or self-hosted usage
+swanlab login
+```
+
+`pillow` and `soundfile` are the media dependencies used by the Image and Audio examples in this skill. `swanlab[dashboard]` adds the local dashboard dependency required by `mode="local"` and `swanlab watch`.
+
+## Quick Start
+
+### Basic Experiment Tracking
+
+```python
+import swanlab
+
+run = swanlab.init(
+    project="my-project",
+    experiment_name="baseline",
+    config={
+        "learning_rate": 1e-3,
+        "epochs": 10,
+        "batch_size": 32,
+        "model": "resnet18",
+    },
+)
+
+for epoch in range(run.config.epochs):
+    train_loss = train_epoch()
+    val_loss = validate()
+
+    swanlab.log(
+        {
+            "train/loss": train_loss,
+            "val/loss": val_loss,
+            "epoch": epoch,
+        }
+    )
+
+run.finish()
+```
+
+### With PyTorch
+
+```python
+import torch
+import torch.nn as nn
+import torch.optim as optim
+import swanlab
+
+run = swanlab.init(
+    project="pytorch-demo",
+    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()
+```
+
+## Core Concepts
+
+### 1. Projects and Experiments
+
+**Project**: Collection of related experiments  
+**Experiment**: Single execution of a training or evaluation workflow
+
+```python
+import swanlab
+
+run = swanlab.init(
+    project="image-classification",
+    experiment_name="resnet18-seed42",
+    description="Baseline run on ImageNet subset",
+    tags=["baseline", "resnet18"],
+    config={
+        "model": "resnet18",
+        "seed": 42,
+        "batch_size": 64,
+        "learning_rate": 3e-4,
+    },
+)
+
+print(run.id)
+print(run.config.learning_rate)
+```
+
+### 2. Configuration Tracking
+
+```python
+config = {
+    "model": "resnet18",
+    "seed": 42,
+    "batch_size": 64,
+    "learning_rate": 3e-4,
+    "epochs": 20,
+}
+
+run = swanlab.init(project="my-project", config=config)
+
+learning_rate = run.config.learning_rate
+batch_size = run.config.batch_size
+```
+
+### 3. Metric Logging
+
+```python
+# Log scalars
+swanlab.log({"loss": 0.42, "accuracy": 0.91})
+
+# Log multiple metrics
+swanlab.log(
+    {
+        "train/loss": train_loss,
+        "train/accuracy": train_acc,
+        "val/loss": val_loss,
+        "val/accuracy": val_acc,
+        "lr": current_lr,
+        "epoch": epoch,
+    }
+)
+
+# Log with custom step
+swanlab.log({"loss": loss}, step=global_step)
+```
+
+### 4. Media and Chart Logging
+
+```python
+import numpy as np
+import swanlab
+
+# Image
+image = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
+swanlab.log({"examples/image": swanlab.Image(image, caption="Augmented sample")})
+
+# Audio
+wave = np.sin(np.linspace(0, 8 * np.pi, 16000)).astype("float32")
+swanlab.log({"examples/audio": swanlab.Audio(wave, sample_rate=16000)})
+
+# Text
+swanlab.log({"examples/text": swanlab.Text("Training notes for this run.")})
+
+# GIF video
+swanlab.log({"examples/video": swanlab.Video("predictions.gif", caption="Validation rollout")})
+
+# Point cloud
+points = np.random.rand(128, 3).astype("float32")
+swanlab.log({"examples/point_cloud": swanlab.Object3D(points, caption="Point cloud sample")})
+
+# Molecule
+swanlab.log({"examples/molecule": swanlab.Molecule.from_smiles("CCO", caption="Ethanol")})
+```
+
+```python
+# Custom chart with swanlab.echarts
+line = swanlab.echarts.Line()
+line.add_xaxis(["epoch-1", "epoch-2", "epoch-3"])
+line.add_yaxis("train/loss", [0.92, 0.61, 0.44])
+line.set_global_opts(
+    title_opts=swanlab.echarts.options.TitleOpts(title="Training Loss")
+)
+
+swanlab.log({"charts/loss_curve": line})
+```
+
+See [references/visualization.md](references/visualization.md) for more chart and media patterns.
+
+### 5. Local and Self-Hosted Workflows
+
+```python
+import os
+import swanlab
+
+# Self-hosted or cloud login
+swanlab.login(
+    api_key=os.environ["SWANLAB_API_KEY"],
+    host="http://your-server:5092",
+)
+
+# Local-only logging
+run = swanlab.init(
+    project="offline-demo",
+    mode="local",
+    logdir="./swanlog",
+)
+
+swanlab.log({"loss": 0.35, "epoch": 1})
+run.finish()
+```
+
+```bash
+# View local logs
+swanlab watch -l ./swanlog
+
+# Sync local logs later
+swanlab sync ./swanlog
+```
+
+## Integration Examples
+
+### HuggingFace Transformers
+
+```python
+from transformers import Trainer, TrainingArguments
+
+training_args = TrainingArguments(
+    output_dir="./results",
+    per_device_train_batch_size=8,
+    evaluation_strategy="epoch",
+    logging_steps=50,
+    report_to="swanlab",
+    run_name="bert-finetune",
+)
+
+trainer = Trainer(
+    model=model,
+    args=training_args,
+    train_dataset=train_dataset,
+    eval_dataset=eval_dataset,
+)
+
+trainer.train()
+```
+
+See [references/integrations.md](references/integrations.md) for callback-based setups and additional framework patterns.
+
+### PyTorch Lightning
+
+```python
+import pytorch_lightning as pl
+from swanlab.integration.pytorch_lightning import SwanLabLogger
+
+swanlab_logger = SwanLabLogger(
+    project="lightning-demo",
+    experiment_name="mnist-classifier",
+    config={"batch_size": 64, "max_epochs": 10},
+)
+
+trainer = pl.Trainer(
+    logger=swanlab_logger,
+    max_epochs=10,
+    accelerator="auto",
+)
+
+trainer.fit(model, train_loader, val_loader)
+```
+
+### Fastai
+
+```python
+from fastai.vision.all import accuracy, resnet34, vision_learner
+from swanlab.integration.fastai import SwanLabCallback
+
+learn = vision_learner(dls, resnet34, metrics=accuracy)
+learn.fit(
+    5,
+    cbs=[
+        SwanLabCallback(
+            project="fastai-demo",
+            experiment_name="pets-classification",
+            config={"arch": "resnet34", "epochs": 5},
+        )
+    ],
+)
+```
+
+See [references/integrations.md](references/integrations.md) for fuller framework examples.
+
+## Best Practices
+
+### 1. Use Stable Metric Names
+
+```python
+# Good: grouped metric namespaces
+swanlab.log({
+    "train/loss": train_loss,
+    "train/accuracy": train_acc,
+    "val/loss": val_loss,
+    "val/accuracy": val_acc,
+})
+
+# Avoid mixing flat and grouped names for the same metric family
+```
+
+### 2. Initialize Early and Capture Config Once
+
+```python
+run = swanlab.init(
+    project="image-classification",
+    experiment_name="resnet18-baseline",
+    config={
+        "model": "resnet18",
+        "learning_rate": 3e-4,
+        "batch_size": 64,
+        "seed": 42,
+    },
+)
+```
+
+### 3. Save Checkpoints Locally
+
+```python
+import torch
+import swanlab
+
+checkpoint_path = "checkpoints/best.pth"
+torch.save(model.state_dict(), checkpoint_path)
+
+swanlab.log(
+    {
+        "best/val_accuracy": best_val_accuracy,
+        "artifacts/checkpoint_path": swanlab.Text(checkpoint_path),
+    }
+)
+```
+
+### 4. Use Local Mode for Offline-First Workflows
+
+```python
+run = swanlab.init(project="offline-demo", mode="local", logdir="./swanlog")
+# ... training code ...
+run.finish()
+
+# Inspect later with: swanlab watch -l ./swanlog
+```
+
+### 5. Keep Advanced Patterns in References
+
+- Use [references/visualization.md](references/visualization.md) for advanced chart and media patterns
+- Use [references/integrations.md](references/integrations.md) for callback-based and framework-specific integration details
+
+## Resources
+
+- [Official docs (Chinese)](https://docs.swanlab.cn)
+- [Official docs (English)](https://docs.swanlab.cn/en)
+- [GitHub repo](https://github.com/SwanHubX/SwanLab)
+- [Self-hosted repo](https://github.com/SwanHubX/self-hosted)
+
+## See Also
+
+- [references/integrations.md](references/integrations.md) - Framework-specific examples
+- [references/visualization.md](references/visualization.md) - Charts and media logging patterns

package/skills/ai-research/13-mlops/swanlab/references/integrations.md

@@ -0,0 +1,305 @@
+<!-- vendored from orchestra-research/AI-research-SKILLs@773a52944ba4747a18bd4ae9ade53fff041adcbc 13-mlops/swanlab/references/integrations.md; MIT (c) Orchestra Research -->
+# 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,
+    report_to="none",
+)
+
+trainer = Trainer(
+    model=model,
+    args=training_args,
+    train_dataset=train_dataset,
+    eval_dataset=eval_dataset,
+    callbacks=[
+        SwanLabCallback(
+            project="text-classification",
+            experiment_name="bert-imdb",
+            config={
+                "model": "bert-base-uncased",
+                "batch_size": 16,
+                "epochs": 3,
+            },
+        )
+    ],
+)
+
+trainer.train()
+```
+
+## PyTorch Lightning
+
+`SwanLabLogger` can create the run for you. Prefer passing project metadata directly to the logger.
+
+```python
+import pytorch_lightning as pl
+import torch
+import torch.nn as nn
+from swanlab.integration.pytorch_lightning import SwanLabLogger
+
+class LitClassifier(pl.LightningModule):
+    def __init__(self, learning_rate=1e-3):
+        super().__init__()
+        self.save_hyperparameters()
+        self.model = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(28 * 28, 128),
+            nn.ReLU(),
+            nn.Linear(128, 10),
+        )
+        self.criterion = nn.CrossEntropyLoss()
+
+    def forward(self, x):
+        return self.model(x)
+
+    def training_step(self, batch, batch_idx):
+        x, y = batch
+        logits = self(x)
+        loss = self.criterion(logits, y)
+        self.log("train/loss", loss, prog_bar=True)
+        return loss
+
+    def validation_step(self, batch, batch_idx):
+        x, y = batch
+        logits = self(x)
+        loss = self.criterion(logits, y)
+        acc = (torch.argmax(logits, dim=1) == y).float().mean()
+        self.log("val/loss", loss, prog_bar=True)
+        self.log("val/accuracy", acc, prog_bar=True)
+
+    def configure_optimizers(self):
+        return torch.optim.Adam(self.parameters(), lr=self.hparams.learning_rate)
+
+swanlab_logger = SwanLabLogger(
+    project="lightning-demo",
+    experiment_name="mnist-classifier",
+    config={"learning_rate": 1e-3, "max_epochs": 10},
+)
+
+trainer = pl.Trainer(
+    logger=swanlab_logger,
+    max_epochs=10,
+    accelerator="auto",
+)
+
+trainer.fit(LitClassifier(), train_loader, val_loader)
+```
+
+## Fastai
+
+`SwanLabCallback` accepts the same run metadata you would normally pass to `swanlab.init(...)`.
+
+```python
+from fastai.vision.all import URLs, ImageDataLoaders, Resize, accuracy, get_image_files, resnet34, untar_data, vision_learner
+from swanlab.integration.fastai import SwanLabCallback
+
+path = untar_data(URLs.PETS)
+dls = ImageDataLoaders.from_name_func(
+    path,
+    get_image_files(path / "images"),
+    valid_pct=0.2,
+    label_func=lambda x: x[0].isupper(),
+    item_tfms=Resize(224),
+    bs=64,
+)
+
+learn = vision_learner(dls, resnet34, metrics=accuracy)
+learn.fit(
+    5,
+    cbs=[
+        SwanLabCallback(
+            project="fastai-demo",
+            experiment_name="pets-classification",
+            config={"arch": "resnet34", "epochs": 5, "batch_size": 64},
+        )
+    ],
+)
+```
+
+### Fastai Text
+
+```python
+from fastai.text.all import AWD_LSTM, TextDataLoaders, accuracy, text_classifier_learner, untar_data, URLs
+from swanlab.integration.fastai import SwanLabCallback
+
+path = untar_data(URLs.IMDB)
+dls = TextDataLoaders.from_folder(path, valid="test", bs=64)
+
+learn = text_classifier_learner(
+    dls,
+    AWD_LSTM,
+    drop_mult=0.5,
+    metrics=accuracy,
+)
+
+learn.fit_one_cycle(
+    3,
+    cbs=[
+        SwanLabCallback(
+            project="fastai-text",
+            experiment_name="imdb-sentiment",
+            config={"arch": "AWD_LSTM", "epochs": 3, "batch_size": 64},
+        )
+    ],
+)
+```
+
+## Best Practices
+
+1. Initialize as early as possible so config and environment metadata are captured once.
+2. Use stable metric names such as `train/loss` and `val/accuracy` across runs.
+3. Save checkpoints locally with your framework and log the checkpoint path or score separately.
+4. Prefer `run.finish()` when you manage the run yourself; let framework integrations finalize runs when they own the lifecycle.
+5. Use `mode="local"` plus `swanlab watch -l ./swanlog` when you want an offline-first workflow.