owlab 0.1.1

A Python toolkit for ML experiment management based on SwanLab and Lark

OwLab

ML experiments, tracked & notified.

A Python toolkit for the full lifecycle of machine learning experiments — experiment tracking with SwanLab, notifications & data management with Lark (Feishu), and local storage.

---

✨ Features

📈	Experiment tracking — Metrics and runs with SwanLab
📊	Experiment data management — Results in Feishu spreadsheets
📢	Message notifications — Start/end alerts via Lark webhook
💾	Multi-backend backup — Local output + Lark; logs, results, and models saved

---

🚀 Quick Start

Install from PyPI:

pip install owlab
# or: uv pip install owlab

from owlab import OwLab

owlab = OwLab()
owlab.init(project="my_project", experiment_name="run_1", config={"lr": 0.01, "epochs": 10})

for step in range(10):
    owlab.log({"loss": 1.0 - step * 0.1, "acc": step * 0.1}, step=step)

owlab.finish(results=[{"method": "baseline", "dataset1": {"measure": "MCM", "accuracy": 0.95}}])

Without any config, OwLab runs in local-only mode: results go to ./output/ and no Lark/SwanLab calls are made.

---

📦 Installation

Method	Command
PyPI (recommended)	pip install owlab — Download on PyPI
uv	uv pip install owlab
From source	git clone https://github.com/Lounwb/OwLab.git && cd OwLab && pip install -e .

---

⚙️ Configuration

To enable Lark (Feishu) and SwanLab, put your credentials in one of:

• File: ~/.owlab/config.json or ./.owlab/config.json
• Environment: OWLAB_LARK__WEBHOOK__WEBHOOK_URL, OWLAB_LARK__API__APP_ID, etc.

Example config file (use .owlab/config.json.example as a template):

{
  "lark": {
    "webhook": {
      "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/...",
      "signature": "your_signature"
    },
    "api": {
      "app_id": "your_app_id",
      "app_secret": "your_app_secret",
      "root_folder_token": "your_root_folder_token"
    }
  },
  "swanlab": {
    "api_key": "your_swanlab_api_key"
  },
  "storage": {
    "local_path": "./output"
  }
}

Environment variables follow the pattern OWLAB_<SECTION>__<KEY>__<SUBKEY> (e.g. OWLAB_LARK__WEBHOOK__WEBHOOK_URL).

---

📖 Usage

1. Initialize

from owlab import OwLab

owlab = OwLab()
owlab.init(
    project="my_project",           # Required
    experiment_name="exp_001",      # Optional; defaults to project
    description="Short description",
    type="baseline",                # e.g. baseline / debug / ablation — used for folder naming
    version="1.0",                 # Experiment version
    tags=["baseline"],             # Optional tags
    config={
        "methods": [...],          # Method definitions for result tables
        "datasets": [...],
        "metrics": [...],
        "measures": [...],
        "experiment_params": {"learning_rate": 0.01, "batch_size": 32},
        "seed": 42,
    },
)

2. Log metrics during training

for epoch in range(100):
    owlab.log({"loss": loss, "accuracy": acc}, step=epoch)

3. Finish and save results

Call finish(results=...) with a list of result rows. Each row can include method, dataset, measure, and metric values. These are written to local files and, when configured, to Feishu spreadsheets.

owlab.finish(results=[
    {
        "method": "method1",
        "dataset1": {"measure": "MCM", "accuracy": 0.95, "loss": 0.05},
        "dataset2": {"measure": "MCM", "accuracy": 0.92, "loss": 0.08},
        "Average": {"measure": "MCM", "accuracy": 0.935, "loss": 0.065},
    },
    # ...
])

4. Output layout

• Local: ./output/<type>/<experiment_name>_<timestamp>/
  • results.csv, results.json, owlab.log, model/
• Lark: Notifications via webhook; result tables written to Feishu via API (when configured).
• SwanLab: Metrics and runs visible in your SwanLab project (when api_key is set).

---

📄 License & Links

• PyPI: pypi.org/project/owlab
• License: MIT
• Repository: github.com/Lounwb/OwLab
• Issues: github.com/Lounwb/OwLab/issues

---

🙏 Acknowledgments

• SwanLab — experiment tracking
• Lark / Feishu — notifications and spreadsheets

⭐ Star History