liblaf-cherries 3.0.3

A lightweight Python experiment runner for typed configs, reproducible artifact paths, scalar metrics, and Comet/Git/local logging.

Explore the docs »

Changelog · Report Bug · Request Feature

✨ What Cherries Does

Cherries is a lightweight experiment runner for Python scripts that need just enough structure to be repeatable. It builds typed config objects, resolves stable data and temporary paths, stores scalar metrics as Polars dataframes, and fans run events out to local files, Git, Comet, and custom plugins.

• Typed configs: pass pydantic-settings models into experiments and log them as parameters automatically.
• Reproducible paths: resolve inputs, outputs, and temporary artifacts below the entrypoint-derived run directory.
• Metric history: log one scalar or nested metric mappings such as {"train": {"loss": 0.4}}, then read them back as tables.
• Artifact bundles: log VTK .series frames and optional mesh .landmarks.json companions with their primary artifacts.
• Plugin hooks: compose ordered hooks for local snapshots, logging, Git, Comet, or your own integrations.
• Run profiles: use debug for local work without remote or commit side effects, and default for the full logging pipeline.

📦 Installation

uv add liblaf-cherries

🚀 Quick Start

from pathlib import Path

from liblaf import cherries


class Config(cherries.BaseConfig):
    name: str = "world"
    output: Path = cherries.output("hello.txt", mkdir=True)


def experiment(cfg: Config) -> None:
    message = f"Hello, {cfg.name}!"
    cfg.output.write_text(f"{message}\n")
    cherries.log_params({"name": cfg.name})
    cherries.log_metric("message_length", len(message))


if __name__ == "__main__":
    cherries.main(experiment, profile="debug")

profile="debug" keeps Comet disabled and Git commits off while still copying the entrypoint, logs, and logged artifacts into .cherries/runs/. The default profile enables Comet, commits dirty changes when needed, and records the final Git SHA.

🧭 Core Concepts

• cherries.input() logs existing inputs immediately.
• cherries.output() and cherries.temp() return paths immediately, then log existing files when the run ends.
• cherries.log_metric() records one scalar; cherries.log_metrics() flattens nested mappings with /.
• CHERRIES_NAME sets the human-readable run name; CHERRIES_TAGS attaches a comma-separated tag list to summaries and Comet.
• Plugins subclass liblaf.cherries.core.Plugin, decorate hooks with liblaf.cherries.core.impl(), and use before or after constraints for deterministic order.

⌨️ Local Development

gh repo clone liblaf/cherries
cd cherries
mise run install
uv run pytest
mise run lint
mise run docs:build

🔗 Links

• Documentation
• Source Code
• Issue Tracker
• PyPI Package

---

📝 License

Copyright © 2026 liblaf.
This project is MIT licensed.