scikit-lab 0.0.1__tar.gz

scikit_lab-0.0.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.3
+Name: scikit-lab
+Version: 0.0.1
+Summary: Add your description here
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: mlflow>=3.8.1 ; extra == 'mlflow'
+Requires-Dist: cmaes>=0.11.1 ; extra == 'optuna'
+Requires-Dist: optuna>=4.6.0 ; extra == 'optuna'
+Requires-Dist: wandb>=0.23.1 ; extra == 'wandb'
+Requires-Python: >=3.11
+Provides-Extra: mlflow
+Provides-Extra: optuna
+Provides-Extra: wandb
+Description-Content-Type: text/markdown
+
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+# 🧪 sklab
+
+A zero-boilerplate experiment runner for sklearn pipelines. One thing, done well: **run experiments**.
+
+**The promise:** Give me a pipeline, I'll give you answers.
+
+## What It Does
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.linear_model import LogisticRegression
+
+from sklab import Experiment
+from sklab.search import GridSearchConfig
+
+pipeline = Pipeline([
+    ("scale", StandardScaler()),
+    ("model", LogisticRegression()),
+])
+
+experiment = Experiment(
+    pipeline=pipeline,
+    scorers={"accuracy": "accuracy", "f1": "f1_macro"},
+)
+
+experiment.fit(X_train, y_train)
+
+result = experiment.evaluate(X_test, y_test)
+
+result = experiment.cross_validate(X, y, cv=5)
+
+result = experiment.search(GridSearchConfig(param_grid={...}), X, y, cv=5)
+```
+
+## 🪄 Why
+
+sklab wants to help data scientist avoid:
+- Writing the same logging code for every experiment
+- Forgetting to save predictions, then needing them later
+- Copy-pasting matplotlib code for confusion matrices and ROC curves
+- Getting a single number from `cross_val_score` with no insight into fold variance
+
+Sklab removes this friction. Results include predictions, probabilities, and diagnostics automatically. Inject a logger once, everything gets tracked. No sprinkling `mlflow.log_*` through your code.
+
+## Install
+
+```bash
+uv add scikit-lab
+
+# With optional integrations
+uv add "scikit-lab[optuna]"   # Optuna search
+uv add "scikit-lab[mlflow]"   # MLflow logging
+uv add "scikit-lab[wandb]"    # W&B logging
+```
+
+## 🤗 Contributing
+
+### Philosophy
+
+Documentation, code and abstraction strive to adhere to the following principles:
+
+- **Be useful** — Every feature solves a real pain point. If it doesn't help you iterate faster, it doesn't belong.
+- **Provide value** — Every line of code must earn its place. We ship what helps, not what's clever.
+- **Abstractions, not obstructions** — We remove tedium, not control. You can always drop down to raw sklearn.
+- **Docs are code** — Every code example runs. If the docs lie, the build fails.
+- **No bloat** — No distributed training, no deployment, no MLOps platform. Just experiments, done well.
+- **Elegance stems from familiarity** — The API feels like sklearn because sklearn got it right, and that's what everybody uses. Don't make people learn new abstractions.
+- **A library, not a framework** — Libraries use familiar concepts; frameworks invent new ones. Study what works in sklearn, HuggingFace, PyTorch - then adopt, don't reinvent. Every new abstraction must earn its place. Design slim wrappers users can see through.
+
+### Coding guidelines
+
+1. Disclose usage of AI Agents. You are free to use them to contribute. We strive to keep this codebase as agent-friendly as possible. However, you **must** own every line of code the agent writes. This means, as a starter, that you must be able to explain and justify the choice. No slop.
+2. Start your feature request in the [discussions](https://github.com/baggiponte/sklab/discussions) tab. Once the core details are ironed out, we'll move it to the issue tracker.
+3. Agents are encouraged to explore the [plans/](plans/) folder to get a sense of the big picture of the ongoing/relevant developments and to create a new plan if needed.
+4. Code is now free to write. The value we bring is in the ideas, taste and judgment to assert the adherence to the principles above. Let's discuss thoroughly those ideas - including the final API - and code will follow naturally. In other words, treat code as an implementation detail, not as the end goal - this is, and always has been, the ideas we bring.
+5. Keep changes small and reviewable
+
+### Setup
+
+```bash
+uv sync
+```
+
+### Commands
+
+```bash
+just format    # Ruff format
+just test      # Run tests with optuna extra
+just lint      # Ruff check + type check
+just docs      # Serve docs locally
+```
+
+### Testing
+
+- **Docs are code**: every code fence in `docs/` is executed by pytest. If the docs lie, the build fails.
+- Integration tests over mocks
+- Fast and deterministic: small datasets, fixed seeds
+
+### Writing Documentation
+
+Documentation is a product. We ship it like one.
+
+> **Docs teach. Code shows. Neither assumes.**
+
+**The three principles:**
+
+1. **Problem first, solution second.** Every explanation starts with *why* before *how*.
+2. **Explain at point of use.** Don't front-load theory. Introduce concepts when the reader needs them.
+3. **Link for depth, explain for correctness.** Provide enough context to use the feature correctly; link to authoritative sources for deeper dives.
+
+**Quick rules:**
+
+| Rule | Example |
+|------|---------|
+| Never assume | Don't say "avoid leakage"—explain what leakage is |
+| Start with the problem | "Most models have hyperparameters that need tuning..." not "Grid search evaluates..." |
+| Show "what happened" | Explain what code did after each block |
+| Provide decision tables | When to use X vs Y in table format |
+| Include "why it matters" | Connect concepts to practical consequences |
+| End with next steps | Link to related tutorials |
+| Cite sources | Link to papers for algorithms |
+
+**Code examples must:**
+
+- Run without modification (tested by pytest)
+- Show all imports
+- Use sklearn's built-in datasets
+- Set random seeds for reproducibility
+
+See [docs/developer/writing-docs.md](docs/developer/writing-docs.md) for the full style guide.

scikit_lab-0.0.1/README.md

@@ -0,0 +1,135 @@
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+# 🧪 sklab
+
+A zero-boilerplate experiment runner for sklearn pipelines. One thing, done well: **run experiments**.
+
+**The promise:** Give me a pipeline, I'll give you answers.
+
+## What It Does
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.linear_model import LogisticRegression
+
+from sklab import Experiment
+from sklab.search import GridSearchConfig
+
+pipeline = Pipeline([
+    ("scale", StandardScaler()),
+    ("model", LogisticRegression()),
+])
+
+experiment = Experiment(
+    pipeline=pipeline,
+    scorers={"accuracy": "accuracy", "f1": "f1_macro"},
+)
+
+experiment.fit(X_train, y_train)
+
+result = experiment.evaluate(X_test, y_test)
+
+result = experiment.cross_validate(X, y, cv=5)
+
+result = experiment.search(GridSearchConfig(param_grid={...}), X, y, cv=5)
+```
+
+## 🪄 Why
+
+sklab wants to help data scientist avoid:
+- Writing the same logging code for every experiment
+- Forgetting to save predictions, then needing them later
+- Copy-pasting matplotlib code for confusion matrices and ROC curves
+- Getting a single number from `cross_val_score` with no insight into fold variance
+
+Sklab removes this friction. Results include predictions, probabilities, and diagnostics automatically. Inject a logger once, everything gets tracked. No sprinkling `mlflow.log_*` through your code.
+
+## Install
+
+```bash
+uv add scikit-lab
+
+# With optional integrations
+uv add "scikit-lab[optuna]"   # Optuna search
+uv add "scikit-lab[mlflow]"   # MLflow logging
+uv add "scikit-lab[wandb]"    # W&B logging
+```
+
+## 🤗 Contributing
+
+### Philosophy
+
+Documentation, code and abstraction strive to adhere to the following principles:
+
+- **Be useful** — Every feature solves a real pain point. If it doesn't help you iterate faster, it doesn't belong.
+- **Provide value** — Every line of code must earn its place. We ship what helps, not what's clever.
+- **Abstractions, not obstructions** — We remove tedium, not control. You can always drop down to raw sklearn.
+- **Docs are code** — Every code example runs. If the docs lie, the build fails.
+- **No bloat** — No distributed training, no deployment, no MLOps platform. Just experiments, done well.
+- **Elegance stems from familiarity** — The API feels like sklearn because sklearn got it right, and that's what everybody uses. Don't make people learn new abstractions.
+- **A library, not a framework** — Libraries use familiar concepts; frameworks invent new ones. Study what works in sklearn, HuggingFace, PyTorch - then adopt, don't reinvent. Every new abstraction must earn its place. Design slim wrappers users can see through.
+
+### Coding guidelines
+
+1. Disclose usage of AI Agents. You are free to use them to contribute. We strive to keep this codebase as agent-friendly as possible. However, you **must** own every line of code the agent writes. This means, as a starter, that you must be able to explain and justify the choice. No slop.
+2. Start your feature request in the [discussions](https://github.com/baggiponte/sklab/discussions) tab. Once the core details are ironed out, we'll move it to the issue tracker.
+3. Agents are encouraged to explore the [plans/](plans/) folder to get a sense of the big picture of the ongoing/relevant developments and to create a new plan if needed.
+4. Code is now free to write. The value we bring is in the ideas, taste and judgment to assert the adherence to the principles above. Let's discuss thoroughly those ideas - including the final API - and code will follow naturally. In other words, treat code as an implementation detail, not as the end goal - this is, and always has been, the ideas we bring.
+5. Keep changes small and reviewable
+
+### Setup
+
+```bash
+uv sync
+```
+
+### Commands
+
+```bash
+just format    # Ruff format
+just test      # Run tests with optuna extra
+just lint      # Ruff check + type check
+just docs      # Serve docs locally
+```
+
+### Testing
+
+- **Docs are code**: every code fence in `docs/` is executed by pytest. If the docs lie, the build fails.
+- Integration tests over mocks
+- Fast and deterministic: small datasets, fixed seeds
+
+### Writing Documentation
+
+Documentation is a product. We ship it like one.
+
+> **Docs teach. Code shows. Neither assumes.**
+
+**The three principles:**
+
+1. **Problem first, solution second.** Every explanation starts with *why* before *how*.
+2. **Explain at point of use.** Don't front-load theory. Introduce concepts when the reader needs them.
+3. **Link for depth, explain for correctness.** Provide enough context to use the feature correctly; link to authoritative sources for deeper dives.
+
+**Quick rules:**
+
+| Rule | Example |
+|------|---------|
+| Never assume | Don't say "avoid leakage"—explain what leakage is |
+| Start with the problem | "Most models have hyperparameters that need tuning..." not "Grid search evaluates..." |
+| Show "what happened" | Explain what code did after each block |
+| Provide decision tables | When to use X vs Y in table format |
+| Include "why it matters" | Connect concepts to practical consequences |
+| End with next steps | Link to related tutorials |
+| Cite sources | Link to papers for algorithms |
+
+**Code examples must:**
+
+- Run without modification (tested by pytest)
+- Show all imports
+- Use sklearn's built-in datasets
+- Set random seeds for reproducibility
+
+See [docs/developer/writing-docs.md](docs/developer/writing-docs.md) for the full style guide.

scikit_lab-0.0.1/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "scikit-lab"
+version = "0.0.1"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "scikit-learn>=1.7.2",
+]
+
+[project.optional-dependencies]
+optuna = [
+    "cmaes>=0.11.1",
+    "optuna>=4.6.0",
+]
+wandb = [
+    "wandb>=0.23.1",
+]
+mlflow = [
+    "mlflow>=3.8.1",
+]
+
+[dependency-groups]
+dev = [
+    "just>=0.8.165",
+    "prek>=0.2.27",
+    "ruff>=0.14.11",
+]
+test = [
+    "scikit-lab[optuna,wandb,mlflow]",
+    "pandas>=2.3.3",
+    "polars>=1.37.0",
+    "pytest-markdown-docs>=0.9.0",
+    "pytest>=9.0.2",
+]
+docs = [
+    "mkdocstrings-python",
+    "zensical",
+]
+
+[tool.uv]
+default-groups = ["dev", "docs", "test"]
+
+[tool.uv.build-backend]
+module-name = "sklab"
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib", "--markdown-docs"]
+testpaths = ["tests", "docs"]
+filterwarnings = [
+    "ignore:The `Scope.user` setter is deprecated:DeprecationWarning:wandb\\..*",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "TID"]
+fixable = ["I", "UP", "TID", "F401"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"

scikit_lab-0.0.1/src/sklab/__init__.py

@@ -0,0 +1 @@
+"""sklab: a library for machine learning experimentation."""

scikit_lab-0.0.1/src/sklab/_lazy.py

@@ -0,0 +1,37 @@
+"""Lazy module loading for optional dependencies."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+
+class LazyModule:
+    """Deferred module import - loads on first attribute access.
+
+    Usage:
+        mlflow = LazyModule("mlflow", install_hint="Install mlflow to use MLflowLogger.")
+
+        # Later, in any method:
+        mlflow.log_params(...)  # Import happens here, on first access
+    """
+
+    def __init__(self, name: str, *, install_hint: str) -> None:
+        self._name = name
+        self._install_hint = install_hint
+        self._module: ModuleType | None = None
+
+    def __getattr__(self, attr: str) -> Any:
+        if self._module is None:
+            try:
+                self._module = import_module(self._name)
+            except ModuleNotFoundError as exc:
+                raise ModuleNotFoundError(
+                    f"{self._name} is not installed. {self._install_hint}"
+                ) from exc
+        return getattr(self._module, attr)
+
+    def __repr__(self) -> str:
+        status = "loaded" if self._module else "not loaded"
+        return f"<LazyModule {self._name!r} ({status})>"

scikit_lab-0.0.1/src/sklab/_logging/mlflow.py

@@ -0,0 +1,51 @@
+"""MLflow logger."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from sklab._lazy import LazyModule
+
+mlflow = LazyModule("mlflow", install_hint="Install mlflow to use MLflowLogger.")
+
+
+@dataclass
+class MLflowLogger:
+    """Logger that tracks experiments with MLflow.
+
+    MLflow uses module-level functions that operate on the active run,
+    so we don't need to store run state.
+    """
+
+    experiment_name: str | None = None
+
+    @contextmanager
+    def start_run(self, name=None, config=None, tags=None, nested=False):
+        if self.experiment_name:
+            mlflow.set_experiment(self.experiment_name)
+        with mlflow.start_run(run_name=name, nested=nested):
+            if config:
+                self.log_params(config)
+            if tags:
+                self.set_tags(tags)
+            yield self
+
+    def log_params(self, params) -> None:
+        mlflow.log_params(dict(params))
+
+    def log_metrics(self, metrics, step: int | None = None) -> None:
+        mlflow.log_metrics(dict(metrics), step=step)
+
+    def set_tags(self, tags) -> None:
+        mlflow.set_tags(dict(tags))
+
+    def log_artifact(self, path: str, name: str | None = None) -> None:
+        if name is None:
+            mlflow.log_artifact(path)
+        else:
+            mlflow.log_artifact(path, name=name)
+
+    def log_model(self, model: Any, name: str | None = None) -> None:
+        mlflow.sklearn.log_model(model, name=name or "model")

scikit_lab-0.0.1/src/sklab/_logging/noop.py

@@ -0,0 +1,34 @@
+"""No-op logger that drops all logging calls."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class NoOpLogger:
+    """Logger that drops all logging calls.
+
+    Useful as the default logger when no external tracking backend is configured.
+    """
+
+    @contextmanager
+    def start_run(self, name=None, config=None, tags=None, nested=False):
+        yield self
+
+    def log_params(self, params) -> None:
+        pass
+
+    def log_metrics(self, metrics, step: int | None = None) -> None:
+        pass
+
+    def set_tags(self, tags) -> None:
+        pass
+
+    def log_artifact(self, path: str, name: str | None = None) -> None:
+        pass
+
+    def log_model(self, model: Any, name: str | None = None) -> None:
+        pass

scikit_lab-0.0.1/src/sklab/_logging/wandb.py

@@ -0,0 +1,59 @@
+"""Weights & Biases logger."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any
+
+from sklab._lazy import LazyModule
+
+wandb = LazyModule(
+    "wandb", install_hint="Install scikit-lab with the 'wandb' extra."
+)
+
+
+@dataclass
+class WandbLogger:
+    """Logger that tracks experiments with Weights & Biases.
+
+    W&B requires calling methods on the run object, so we store
+    a reference to the active run in `self._run`.
+    """
+
+    project: str | None = None
+    entity: str | None = None
+    _run: Any = field(default=None, init=False, repr=False)
+
+    @contextmanager
+    def start_run(self, name=None, config=None, tags=None, nested=False):
+        with wandb.init(
+            project=self.project,
+            entity=self.entity,
+            name=name,
+            config=config or {},
+            tags=list(tags.values()) if tags else None,
+            reinit=nested,
+        ) as run:
+            self._run = run
+            yield self
+        self._run = None
+
+    def log_params(self, params) -> None:
+        self._run.config.update(dict(params), allow_val_change=True)
+
+    def log_metrics(self, metrics, step: int | None = None) -> None:
+        self._run.log(dict(metrics), step=step)
+
+    def set_tags(self, tags) -> None:
+        existing = set(self._run.tags or [])
+        self._run.tags = sorted(existing | set(tags.values()))
+
+    def log_artifact(self, path: str, name: str | None = None) -> None:
+        artifact = wandb.Artifact(name or "artifact", type="file")
+        artifact.add_file(path)
+        self._run.log_artifact(artifact)
+
+    def log_model(self, model: Any, name: str | None = None) -> None:
+        if isinstance(model, str):
+            self.log_artifact(model, name=name or "model")

scikit_lab-0.0.1/src/sklab/_results.py

@@ -0,0 +1,77 @@
+"""Result dataclasses returned by Experiment methods."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+RawT = TypeVar("RawT")
+
+
+@dataclass(slots=True)
+class FitResult:
+    """Result of a single fit run.
+
+    Attributes:
+        estimator: The fitted pipeline/estimator.
+        metrics: Empty dict (fit doesn't compute metrics).
+        params: Merged parameters used for fitting.
+        raw: The fitted estimator (same as estimator, for API consistency).
+    """
+
+    estimator: Any
+    metrics: Mapping[str, float]
+    params: Mapping[str, Any]
+    raw: Any
+
+
+@dataclass(slots=True)
+class EvalResult:
+    """Result of evaluating a fitted estimator on a dataset.
+
+    Attributes:
+        metrics: Computed metric scores.
+        raw: The metrics dict (same as metrics, for API consistency).
+    """
+
+    metrics: Mapping[str, float]
+    raw: Mapping[str, float]
+
+
+@dataclass(slots=True)
+class CVResult:
+    """Result of a cross-validation run.
+
+    Attributes:
+        metrics: Aggregated metrics (mean/std across folds).
+        fold_metrics: Per-fold metric values.
+        estimator: Final refitted estimator (if refit=True), else None.
+        raw: Full sklearn cross_validate() dict, including fit_time,
+            score_time, and test scores for each fold.
+    """
+
+    metrics: Mapping[str, float]
+    fold_metrics: Mapping[str, list[float]]
+    estimator: Any | None
+    raw: Mapping[str, Any]
+
+
+@dataclass(slots=True)
+class SearchResult(Generic[RawT]):
+    """Result of a hyperparameter search run.
+
+    Attributes:
+        best_params: Best hyperparameters found.
+        best_score: Best cross-validation score achieved.
+        estimator: Best estimator refitted on full data (if refit=True).
+        raw: The underlying search object. For OptunaConfig, this is the
+            Optuna Study with full trial history. For sklearn searchers
+            (GridSearchCV, RandomizedSearchCV), this is the fitted searcher
+            with cv_results_ and other attributes.
+    """
+
+    best_params: Mapping[str, Any]
+    best_score: float | None
+    estimator: Any | None
+    raw: RawT

scikit_lab-0.0.1/src/sklab/_search/__init__.py

@@ -0,0 +1 @@
+"""Contains the implementations of the  configurations of hyperparameter search classes."""