saberlib 0.1.0__py3-none-any.whl

saber/__init__.py

@@ -0,0 +1,71 @@
+"""saber — classical supervised machine learning infrastructure."""
+
+from saber._api import evaluate, predict, train
+from saber._version import __version__
+from saber.benchmark import BenchmarkConfig, BenchmarkResult, benchmark
+from saber.config import run_config
+from saber.core import (
+    ALGORITHMS,
+    Categorical,
+    Float,
+    Integer,
+    LogFloat,
+    PredictionResult,
+    SearchSpace,
+    TrainResult,
+)
+from saber.datasets import BioSievePartitionConfig, DatasetBundle, PartitionPlan
+from saber.evaluation import EvaluationResult
+from saber.exceptions import SaberError
+from saber.persistence import (
+    LoadedModelArtifact,
+    inspect_artifact,
+    load_benchmark,
+    load_model,
+    save_benchmark,
+    save_model,
+)
+from saber.preprocessing import PreprocessingConfig
+from saber.tuning import OptimizationResult, TuningConfig, tune
+from saber.validation import ValidationResult, validate
+
+__all__ = [  # noqa: RUF022  # grouped by purpose, not alphabetical
+    # Workflows
+    "train",
+    "validate",
+    "tune",
+    "benchmark",
+    "evaluate",
+    "predict",
+    "run_config",
+    # Persistence
+    "save_model",
+    "load_model",
+    "save_benchmark",
+    "load_benchmark",
+    "inspect_artifact",
+    # Inputs
+    "DatasetBundle",
+    "PartitionPlan",
+    "BioSievePartitionConfig",
+    "PreprocessingConfig",
+    "TuningConfig",
+    "BenchmarkConfig",
+    "SearchSpace",
+    "Categorical",
+    "Integer",
+    "Float",
+    "LogFloat",
+    # Results
+    "TrainResult",
+    "PredictionResult",
+    "EvaluationResult",
+    "ValidationResult",
+    "OptimizationResult",
+    "BenchmarkResult",
+    "LoadedModelArtifact",
+    # Catalog / misc
+    "ALGORITHMS",
+    "SaberError",
+    "__version__",
+]

saber/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for running saber's CLI as a module."""
+
+from saber.cli.main import main
+
+raise SystemExit(main())

saber/_api/__init__.py

@@ -0,0 +1,7 @@
+"""Private implementation of the train/predict/evaluate workflows."""
+
+from saber._api.evaluate import evaluate
+from saber._api.predict import predict
+from saber._api.train import train
+
+__all__ = ["evaluate", "predict", "train"]

saber/_api/_common.py

@@ -0,0 +1,71 @@
+"""Shared helpers for the public high-level API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from saber.core.prediction import PredictionResult, collect_model_outputs
+from saber.core.results import TrainResult
+from saber.exceptions import ValidationContractError
+from saber.persistence import LoadedModelArtifact, load_model
+from saber.preprocessing.pipeline import pipeline_input
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def load_active_model(model: Any) -> TrainResult | LoadedModelArtifact:
+    """Resolve an artifact path, TrainResult, or LoadedModelArtifact to a fitted model."""
+    if isinstance(model, (str, Path)):
+        return load_model(model)
+    if isinstance(model, (TrainResult, LoadedModelArtifact)):
+        return model
+    raise ValidationContractError("model must be an artifact path, LoadedModelArtifact, or TrainResult.")
+
+
+def predict_model(
+    model: TrainResult | LoadedModelArtifact,
+    X: Any,
+    *,
+    feature_names: Sequence[str] | None = None,
+    sample_ids: Sequence[Any] | None = None,
+    positive_class: Any | None = None,
+) -> PredictionResult:
+    """Generate a structured prediction from a resolved fitted model."""
+    if X is None:
+        raise ValidationContractError("Prediction requires a feature matrix or DatasetBundle.")
+    if isinstance(model, LoadedModelArtifact):
+        return model._predict_result(  # noqa: SLF001  # the artifact's own inference path
+            X,
+            feature_names=feature_names,
+            sample_ids=sample_ids,
+            positive_class=positive_class,
+        )
+
+    fitted = model.model
+    if fitted is None:
+        raise ValidationContractError("TrainResult does not contain a fitted model.")
+
+    if model.feature_schema is not None:
+        # Validate against the training schema before the NumPy conversion.
+        model.feature_schema.validate_compatible(X, feature_names=feature_names)
+    X = pipeline_input(fitted, X)
+    capabilities = model.spec.resolved_capabilities
+    outputs = collect_model_outputs(
+        fitted,
+        X,
+        task=model.spec.task,
+        use_proba=capabilities.predict_proba,
+        use_decision=capabilities.decision_function,
+    )
+
+    return PredictionResult(
+        task=model.spec.task,
+        **outputs,
+        positive_class=model.positive_class if positive_class is None else positive_class,
+        sample_ids=None if sample_ids is None else np.asarray(sample_ids),
+        metadata={"algorithm": model.spec.name},
+    )

saber/_api/evaluate.py

@@ -0,0 +1,43 @@
+"""High-level direct evaluation API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from saber._api._common import load_active_model, predict_model
+from saber.core.results import TrainResult
+from saber.evaluation import EvaluationResult, evaluate_prediction
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from saber.datasets import DatasetBundle
+    from saber.persistence import LoadedModelArtifact
+
+
+def evaluate(
+    model: str | Path | TrainResult | LoadedModelArtifact,
+    dataset: DatasetBundle,
+    *,
+    metrics: Sequence[str] | None = None,
+    positive_class: Any | None = None,
+) -> EvaluationResult:
+    """Evaluate one already-fitted model on a labeled prepared dataset."""
+    active = load_active_model(model)
+    dataset.validate(task=active.spec.task if isinstance(active, TrainResult) else active.task)
+    prediction = predict_model(
+        active,
+        dataset.X,
+        feature_names=dataset.feature_names,
+        sample_ids=dataset.sample_ids,
+        positive_class=positive_class,
+    )
+    result = evaluate_prediction(dataset.y, prediction, metrics=metrics)
+    result.metadata.update(
+        algorithm=prediction.metadata.get("algorithm"), dataset_fingerprint=dataset.fingerprint
+    )
+    return result
+
+
+__all__ = ["evaluate"]

saber/_api/predict.py

@@ -0,0 +1,50 @@
+"""High-level structured prediction API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from saber._api._common import load_active_model, predict_model
+from saber.datasets import DatasetBundle
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from saber.core.prediction import PredictionResult
+    from saber.core.results import TrainResult
+    from saber.persistence import LoadedModelArtifact
+
+
+def predict(
+    model: str | Path | TrainResult | LoadedModelArtifact,
+    X: Any,
+    *,
+    sample_ids: Sequence[Any] | None = None,
+    positive_class: Any | None = None,
+) -> PredictionResult:
+    """Generate a structured PredictionResult from a fitted or persisted model.
+
+    ``X`` is a :class:`DatasetBundle`, a NumPy array, or a Polars/pandas
+    DataFrame.  DataFrames and datasets are checked against the training
+    feature names/order; a NumPy array only against the feature count.  A path
+    is loaded with :func:`saber.load_model` defaults; call ``load_model``
+    yourself for ``strict_environment`` or ``verify`` control.
+    """
+    active = load_active_model(model)
+    feature_names = None
+    if isinstance(X, DatasetBundle):
+        feature_names = X.feature_names
+        if sample_ids is None:
+            sample_ids = X.sample_ids
+        X = X.X
+    return predict_model(
+        active,
+        X,
+        feature_names=feature_names,
+        sample_ids=sample_ids,
+        positive_class=positive_class,
+    )
+
+
+__all__ = ["predict"]

saber/_api/train.py

@@ -0,0 +1,68 @@
+"""High-level final-model training API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from saber.core.registry import get_algorithm
+from saber.core.results import TrainResult
+from saber.preprocessing.pipeline import build_model_pipeline, pipeline_input, preprocessing_summary
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from saber.datasets import DatasetBundle
+    from saber.preprocessing import PreprocessingConfig
+
+
+def train(
+    *,
+    dataset: DatasetBundle,
+    algorithm: str,
+    model_params: Mapping[str, Any] | None = None,
+    preprocessing: PreprocessingConfig | None = None,
+    random_state: int | None = None,
+    positive_class: Any | None = None,
+) -> TrainResult:
+    """Fit a final supervised model on all supplied samples.
+
+    This is a final-fit operation.  Model assessment belongs to ``validate`` or
+    ``benchmark``; hyperparameter selection belongs to ``tune``.  Persist the
+    result with :func:`saber.save_model`.
+    """
+    spec = get_algorithm(algorithm)
+    dataset.validate(task=spec.task)
+
+    estimator = spec.build_estimator(random_state=random_state, **(model_params or {}))
+    pipeline = build_model_pipeline(
+        spec=spec,
+        estimator=estimator,
+        training_data=dataset,
+        preprocessing=preprocessing,
+    )
+    pipeline.fit(
+        pipeline_input(pipeline, dataset.X),
+        dataset.y,
+        **spec.sample_weight_fit_params(dataset.sample_weight),
+    )
+
+    return TrainResult(
+        model=pipeline,
+        spec=spec,
+        parameters=dict(pipeline.named_steps["estimator"].get_params(deep=False)),
+        feature_schema=dataset.feature_schema,
+        positive_class=positive_class,
+        metadata={
+            "algorithm": spec.name,
+            "provider": spec.provider,
+            "task": spec.task,
+            "dataset_fingerprint": dataset.fingerprint,
+            "n_samples": dataset.n_samples,
+            "n_features": dataset.n_features,
+            "random_state": random_state,
+            "preprocessing": preprocessing_summary(preprocessing),
+        },
+    )
+
+
+__all__ = ["train"]

saber/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.1.0"

saber/benchmark/__init__.py

@@ -0,0 +1,13 @@
+"""Systematic supervised model benchmarking."""
+
+from saber.benchmark.config import BenchmarkConfig, BenchmarkMode
+from saber.benchmark.engine import benchmark
+from saber.benchmark.results import BenchmarkResult, BenchmarkRun
+
+__all__ = [
+    "BenchmarkConfig",
+    "BenchmarkMode",
+    "BenchmarkResult",
+    "BenchmarkRun",
+    "benchmark",
+]

saber/benchmark/config.py

@@ -0,0 +1,47 @@
+"""Benchmark execution configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal, get_args
+
+if TYPE_CHECKING:
+    from saber.tuning import TuningConfig
+
+BenchmarkMode = Literal["untuned", "tuned"]
+
+
+@dataclass(frozen=True, slots=True)
+class BenchmarkConfig:
+    """Benchmark-specific controls of the algorithm x representation x partition matrix.
+
+    Workflow knobs shared with ``validate``/``tune`` (``metrics``,
+    ``evaluation_role``, ...) are keyword arguments of :func:`benchmark`.
+    Each seed in ``seeds`` is the ``random_state`` of one set of runs.
+    """
+
+    seeds: tuple[int | None, ...] = (42,)
+    modes: tuple[BenchmarkMode, ...] = ("untuned",)
+    include_baselines: bool = True
+    fail_fast: bool = False
+    tuning: TuningConfig | None = None
+    metadata: dict[str, object] = field(default_factory=dict, compare=False)
+
+    def __post_init__(self) -> None:
+        """Deduplicate seeds/modes and validate the tuned-mode contract."""
+        seeds = tuple(dict.fromkeys(self.seeds))
+        modes = tuple(dict.fromkeys(self.modes))
+
+        if not seeds:
+            raise ValueError("BenchmarkConfig.seeds must contain at least one seed.")
+        if not modes:
+            raise ValueError("BenchmarkConfig.modes must contain at least one mode.")
+        invalid = set(modes) - set(get_args(BenchmarkMode))
+        if invalid:
+            raise ValueError(f"Unsupported benchmark modes: {sorted(invalid)!r}.")
+        if "tuned" in modes and self.tuning is None:
+            raise ValueError("Tuned benchmarks require an explicit TuningConfig.")
+
+        object.__setattr__(self, "seeds", seeds)
+        object.__setattr__(self, "modes", modes)
+        object.__setattr__(self, "metadata", dict(self.metadata))