leanhebo 0.1.0__py3-none-any.whl

leanhebo/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+# Portions derived from Huawei HEBO; see NOTICE.md.
+
+"""LeanHEBO public package."""
+
+from leanhebo.config import (
+    AcquisitionConfig,
+    GPConfig,
+    LeanHEBOConfig,
+    RuntimeConfig,
+    SearchConfig,
+    WarpConfig,
+)
+from leanhebo.optimizer import LeanHEBO
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AcquisitionConfig",
+    "GPConfig",
+    "LeanHEBO",
+    "LeanHEBOConfig",
+    "RuntimeConfig",
+    "SearchConfig",
+    "WarpConfig",
+    "__version__",
+]

leanhebo/acquisition/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: MIT
+
+"""Posterior and MACE evaluation."""
+
+from leanhebo.acquisition.mace import MACEEvaluator
+from leanhebo.acquisition.posterior import PosteriorEvaluator, PosteriorStats
+
+__all__ = ["MACEEvaluator", "PosteriorEvaluator", "PosteriorStats"]

leanhebo/acquisition/mace.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: MIT
+# Portions derived from Huawei HEBO; see NOTICE.md.
+
+"""HEBO's three-objective MACE acquisition from shared posterior statistics."""
+
+from __future__ import annotations
+
+import math
+
+import torch
+
+from leanhebo.acquisition.posterior import PosteriorEvaluator, PosteriorStats
+from leanhebo.errors import NumericalError
+
+
+class MACEEvaluator:
+    """Compute stochastic LCB, negative log-EI, and negative log-PI."""
+
+    num_objectives = 3
+
+    def __init__(
+        self,
+        posterior: PosteriorEvaluator,
+        *,
+        best_y: torch.Tensor | float,
+        kappa: float,
+        epsilon: float = 1e-4,
+        stochastic: bool = True,
+        generator: torch.Generator | None = None,
+    ) -> None:
+        if kappa < 0:
+            raise ValueError("kappa cannot be negative")
+        if epsilon < 0:
+            raise ValueError("epsilon cannot be negative")
+        self.posterior = posterior
+        self.best_y = best_y
+        self.kappa = kappa
+        self.epsilon = epsilon
+        self.stochastic = stochastic
+        self.generator = generator
+
+    def evaluate(self, continuous: torch.Tensor, categorical: torch.Tensor) -> torch.Tensor:
+        return self.from_stats(self.posterior.evaluate(continuous, categorical))
+
+    def from_stats(self, stats: PosteriorStats) -> torch.Tensor:
+        mean = stats.mean
+        stddev = stats.stddev.clamp_min(torch.finfo(stats.stddev.dtype).eps)
+        tau = torch.as_tensor(self.best_y, device=mean.device, dtype=mean.dtype)
+        if self.stochastic:
+            noise_stddev = (2.0 * stats.noise_variance).sqrt()
+            lcb_noise = torch.randn(
+                mean.shape,
+                device=mean.device,
+                dtype=mean.dtype,
+                generator=self.generator,
+            )
+            improvement_noise = torch.randn(
+                mean.shape,
+                device=mean.device,
+                dtype=mean.dtype,
+                generator=self.generator,
+            )
+            noisy_lcb_mean = mean + noise_stddev * lcb_noise
+            improvement_mean = mean + noise_stddev * improvement_noise
+        else:
+            noisy_lcb_mean = mean
+            improvement_mean = mean
+        lcb = noisy_lcb_mean - self.kappa * stddev
+        normalized = (tau - self.epsilon - improvement_mean) / stddev
+
+        log_phi = -0.5 * normalized.square() - 0.5 * math.log(2.0 * math.pi)
+        probability = torch.special.ndtr(normalized)
+        expected_improvement = stddev * (probability * normalized + torch.exp(log_phi))
+        log_ei = torch.log(expected_improvement)
+        log_pi = torch.log(probability)
+        log_ei_approx = (
+            torch.log(stddev) - 0.5 * normalized.square() - torch.log(normalized.square() - 1.0)
+        )
+        log_pi_approx = (
+            -0.5 * normalized.square() - torch.log(-normalized) - 0.5 * math.log(2.0 * math.pi)
+        )
+        direct = (normalized > -6.0) & torch.isfinite(log_ei) & torch.isfinite(log_pi)
+        negative_log_ei = -torch.where(direct, log_ei, log_ei_approx)
+        negative_log_pi = -torch.where(direct, log_pi, log_pi_approx)
+        objectives = torch.stack((lcb, negative_log_ei, negative_log_pi), dim=-1)
+        if not torch.isfinite(objectives).all():
+            bad = int((~torch.isfinite(objectives)).sum().item())
+            raise NumericalError(f"MACE produced {bad} non-finite objective values")
+        return objectives
+
+    __call__ = evaluate

leanhebo/acquisition/posterior.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: MIT
+
+"""One-call-per-chunk exact-GP posterior evaluation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import torch
+
+
+class PosteriorProvider(Protocol):
+    posterior_cache_version: int
+
+    def predict(
+        self, continuous: torch.Tensor, categorical: torch.Tensor
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class PosteriorStats:
+    mean: torch.Tensor
+    variance: torch.Tensor
+    stddev: torch.Tensor
+    noise_variance: torch.Tensor
+
+    def index_select(self, indices: torch.Tensor) -> PosteriorStats:
+        return PosteriorStats(
+            mean=self.mean.index_select(0, indices),
+            variance=self.variance.index_select(0, indices),
+            stddev=self.stddev.index_select(0, indices),
+            noise_variance=self.noise_variance,
+        )
+
+
+class PosteriorEvaluator:
+    """Evaluate and optionally cache shared posterior statistics."""
+
+    def __init__(
+        self,
+        provider: PosteriorProvider,
+        *,
+        batch_size: int | None = 4096,
+        cache: bool = True,
+    ) -> None:
+        if batch_size is not None and batch_size < 1:
+            raise ValueError("batch_size must be positive or None")
+        self.provider = provider
+        self.batch_size = batch_size
+        self.cache = cache
+        self._cache_key: tuple[object, ...] | None = None
+        self._cache_value: PosteriorStats | None = None
+        self._cache_inputs: tuple[torch.Tensor, torch.Tensor] | None = None
+
+    def invalidate(self) -> None:
+        self._cache_key = None
+        self._cache_value = None
+        self._cache_inputs = None
+
+    def evaluate(self, continuous: torch.Tensor, categorical: torch.Tensor) -> PosteriorStats:
+        if continuous.shape[0] != categorical.shape[0]:
+            raise ValueError("continuous and categorical batch lengths differ")
+        key = self._key(continuous, categorical)
+        if self.cache and key == self._cache_key and self._cache_value is not None:
+            return self._cache_value
+        count = continuous.shape[0]
+        if count == 0:
+            empty = continuous.new_empty((0,))
+            result = PosteriorStats(empty, empty, empty, continuous.new_zeros(()))
+            if self.cache:
+                self._cache_key = key
+                self._cache_value = result
+                self._cache_inputs = (continuous, categorical)
+            return result
+        chunk_size = count if self.batch_size is None else self.batch_size
+        means: list[torch.Tensor] = []
+        variances: list[torch.Tensor] = []
+        noise: torch.Tensor | None = None
+        for start in range(0, count, chunk_size):
+            end = min(start + chunk_size, count)
+            mean, variance, chunk_noise = self.provider.predict(
+                continuous[start:end], categorical[start:end]
+            )
+            means.append(mean)
+            variances.append(variance)
+            noise = chunk_noise if noise is None else noise
+        mean = torch.cat(means)
+        variance = torch.cat(variances).clamp_min(torch.finfo(continuous.dtype).eps)
+        assert noise is not None
+        result = PosteriorStats(mean, variance, variance.sqrt(), noise)
+        if self.cache:
+            self._cache_key = key
+            self._cache_value = result
+            # Retaining the input objects prevents allocator pointer reuse from
+            # making unrelated tensors look like the cached evaluation.
+            self._cache_inputs = (continuous, categorical)
+        return result
+
+    def _key(self, continuous: torch.Tensor, categorical: torch.Tensor) -> tuple[object, ...]:
+        return (
+            self.provider.posterior_cache_version,
+            id(continuous),
+            continuous.data_ptr(),
+            tuple(continuous.shape),
+            tuple(continuous.stride()),
+            continuous.storage_offset(),
+            continuous.dtype,
+            continuous.device,
+            continuous._version,
+            id(categorical),
+            categorical.data_ptr(),
+            tuple(categorical.shape),
+            tuple(categorical.stride()),
+            categorical.storage_offset(),
+            categorical.dtype,
+            categorical.device,
+            categorical._version,
+        )

leanhebo/checkpoint.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+
+"""Versioned, tensor-and-primitive-only LeanHEBO checkpoints."""
+
+from __future__ import annotations
+
+import os
+import pickle
+import struct
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import torch
+
+from leanhebo.errors import CheckpointError
+
+CHECKPOINT_KIND = "leanhebo.optimizer"
+CHECKPOINT_SCHEMA_VERSION = 1
+
+
+def make_checkpoint(payload: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "kind": CHECKPOINT_KIND,
+        "schema_version": CHECKPOINT_SCHEMA_VERSION,
+        "payload": dict(payload),
+    }
+
+
+def save_checkpoint(path: str | os.PathLike[str], payload: Mapping[str, Any]) -> None:
+    """Atomically save a versioned checkpoint using Torch's tensor-aware format."""
+
+    destination = Path(path).expanduser().resolve()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    handle, temporary_name = tempfile.mkstemp(
+        prefix=f".{destination.name}.", suffix=".tmp", dir=destination.parent
+    )
+    os.close(handle)
+    temporary = Path(temporary_name)
+    try:
+        torch.save(make_checkpoint(payload), temporary)
+        os.replace(temporary, destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def load_checkpoint(
+    path: str | os.PathLike[str],
+    *,
+    map_location: str | torch.device | None = None,
+) -> dict[str, Any]:
+    """Load and validate a checkpoint without permitting arbitrary pickled objects."""
+
+    try:
+        state = torch.load(path, map_location=map_location, weights_only=True)
+    except (
+        EOFError,
+        OSError,
+        RuntimeError,
+        ValueError,
+        pickle.UnpicklingError,
+        struct.error,
+    ) as exc:
+        raise CheckpointError(f"failed to load LeanHEBO checkpoint: {exc}") from exc
+    if not isinstance(state, Mapping) or state.get("kind") != CHECKPOINT_KIND:
+        raise CheckpointError("file is not a LeanHEBO optimizer checkpoint")
+    if state.get("schema_version") != CHECKPOINT_SCHEMA_VERSION:
+        raise CheckpointError(f"unsupported checkpoint schema: {state.get('schema_version')!r}")
+    payload = state.get("payload")
+    if not isinstance(payload, Mapping):
+        raise CheckpointError("checkpoint payload is missing or malformed")
+    return dict(payload)

leanhebo/config.py

@@ -0,0 +1,263 @@
+# SPDX-License-Identifier: MIT
+# Portions derived from Huawei HEBO; see NOTICE.md.
+
+"""Explicit, serializable configuration for LeanHEBO."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal, TypeVar
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeConfig:
+    """Device, precision, randomness, and evaluation controls."""
+
+    device: str = "cpu"
+    dtype: Literal["float32", "float64"] = "float32"
+    seed: int | None = None
+    deterministic: bool = False
+    acquisition_batch_size: int | None = 4096
+    synchronize_device_for_timing: bool = True
+    enable_torch_compile: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.device:
+            raise ValueError("device must be a non-empty Torch device string")
+        if self.dtype not in ("float32", "float64"):
+            raise ValueError("dtype must be 'float32' or 'float64'")
+        if self.acquisition_batch_size is not None and self.acquisition_batch_size < 1:
+            raise ValueError("acquisition_batch_size must be positive or None")
+
+
+@dataclass(frozen=True, slots=True)
+class GPConfig:
+    """Exact-GP fitting and lifecycle controls."""
+
+    learning_rate: float = 1e-2
+    optimizer: Literal["psgld", "adam", "lbfgs"] = "psgld"
+    initial_steps: int = 100
+    update_steps: int = 10
+    full_refit_interval: int | None = 25
+    full_refit_growth_factor: float | None = 1.5
+    reuse_parameters: bool = True
+    reuse_optimizer_state: bool = True
+    use_set_train_data: bool = True
+    use_fantasy_updates: bool = False
+    noise_lower_bound: float = 8e-4
+    noise_initial: float = 1e-2
+    predict_observation_noise: bool = False
+    ard: bool = True
+    early_stopping: bool = False
+    patience: int = 10
+    relative_tolerance: float = 1e-4
+    max_cholesky_size: int | None = None
+    max_preconditioner_size: int | None = None
+    cg_tolerance: float | None = None
+    eval_cg_tolerance: float | None = None
+    fast_pred_var: bool = True
+    kernel_initialization_samples: int = 1000
+    lengthscale_lower_bound: float = 0.02
+    jitter_initial: float = 1e-8
+    jitter_multiplier: float = 10.0
+    jitter_max: float = 1.0
+    max_jitter_retries: int = 9
+    lbfgs_max_iter: int = 5
+
+    def __post_init__(self) -> None:
+        if not math.isfinite(self.learning_rate) or self.learning_rate <= 0:
+            raise ValueError("learning_rate must be positive and finite")
+        if self.initial_steps < 0 or self.update_steps < 0:
+            raise ValueError("GP step counts cannot be negative")
+        if self.full_refit_interval is not None and self.full_refit_interval < 1:
+            raise ValueError("full_refit_interval must be positive or None")
+        if self.full_refit_growth_factor is not None and (
+            not math.isfinite(self.full_refit_growth_factor) or self.full_refit_growth_factor <= 1
+        ):
+            raise ValueError("full_refit_growth_factor must exceed 1 or be None")
+        if (
+            not math.isfinite(self.noise_lower_bound)
+            or not math.isfinite(self.noise_initial)
+            or self.noise_lower_bound <= 0
+            or self.noise_initial <= 0
+        ):
+            raise ValueError("noise bounds and initial value must be positive and finite")
+        if self.noise_initial <= self.noise_lower_bound:
+            raise ValueError("noise_initial must be strictly greater than noise_lower_bound")
+        if self.use_fantasy_updates and self.update_steps != 0:
+            raise ValueError("fantasy updates require update_steps=0 so their cache remains valid")
+        if self.use_fantasy_updates and not self.reuse_parameters:
+            raise ValueError("fantasy updates require reuse_parameters=True")
+        if self.patience < 1:
+            raise ValueError("patience must be positive")
+        if not math.isfinite(self.relative_tolerance) or self.relative_tolerance < 0:
+            raise ValueError("relative_tolerance must be finite and non-negative")
+        if self.kernel_initialization_samples < 2:
+            raise ValueError("kernel_initialization_samples must be at least 2")
+        if not math.isfinite(self.lengthscale_lower_bound) or self.lengthscale_lower_bound <= 0:
+            raise ValueError("lengthscale_lower_bound must be positive and finite")
+        if (
+            not math.isfinite(self.jitter_initial)
+            or not math.isfinite(self.jitter_multiplier)
+            or self.jitter_initial <= 0
+            or self.jitter_multiplier <= 1
+        ):
+            raise ValueError("invalid jitter schedule")
+        if (
+            not math.isfinite(self.jitter_max)
+            or self.jitter_max < self.jitter_initial
+            or self.max_jitter_retries < 0
+        ):
+            raise ValueError("invalid maximum jitter settings")
+        if self.lbfgs_max_iter < 1:
+            raise ValueError("lbfgs_max_iter must be positive")
+        if self.max_cholesky_size is not None and self.max_cholesky_size < 0:
+            raise ValueError("max_cholesky_size cannot be negative")
+        if self.max_preconditioner_size is not None and self.max_preconditioner_size < 0:
+            raise ValueError("max_preconditioner_size cannot be negative")
+        for name, value in (
+            ("cg_tolerance", self.cg_tolerance),
+            ("eval_cg_tolerance", self.eval_cg_tolerance),
+        ):
+            if value is not None and (not math.isfinite(value) or value <= 0):
+                raise ValueError(f"{name} must be positive and finite or None")
+
+
+@dataclass(frozen=True, slots=True)
+class WarpConfig:
+    """Output standardization and power-transform controls."""
+
+    method: Literal["auto", "none", "box-cox", "yeo-johnson"] = "auto"
+    standardize_before_warp: bool = True
+    refit_interval: int | None = 1
+    minimum_points: int = 3
+    minimum_transformed_std: float = 0.5
+    lambda_lower_bound: float = -5.0
+    lambda_upper_bound: float = 5.0
+    lambda_tolerance: float = 1e-5
+
+    def __post_init__(self) -> None:
+        if self.refit_interval is not None and self.refit_interval < 1:
+            raise ValueError("refit_interval must be positive or None")
+        if self.minimum_points < 1:
+            raise ValueError("minimum_points must be positive")
+        if not math.isfinite(self.minimum_transformed_std) or self.minimum_transformed_std < 0:
+            raise ValueError("minimum_transformed_std must be finite and non-negative")
+        if (
+            not math.isfinite(self.lambda_lower_bound)
+            or not math.isfinite(self.lambda_upper_bound)
+            or self.lambda_lower_bound >= self.lambda_upper_bound
+        ):
+            raise ValueError("lambda bounds must be strictly increasing")
+        if not math.isfinite(self.lambda_tolerance) or self.lambda_tolerance <= 0:
+            raise ValueError("lambda_tolerance must be positive and finite")
+
+
+@dataclass(frozen=True, slots=True)
+class AcquisitionConfig:
+    """MACE policy controls."""
+
+    epsilon: float = 1e-4
+    upsi: float = 0.5
+    delta: float = 0.01
+    kappa: float | None = None
+    stochastic: bool = True
+    posterior_cache: bool = True
+
+    def __post_init__(self) -> None:
+        if not math.isfinite(self.epsilon) or self.epsilon < 0:
+            raise ValueError("epsilon must be finite and non-negative")
+        if not math.isfinite(self.upsi) or self.upsi <= 0:
+            raise ValueError("upsi must be positive and finite")
+        if not math.isfinite(self.delta) or not 0 < self.delta < 1:
+            raise ValueError("delta must lie strictly between zero and one")
+        if self.kappa is not None and (not math.isfinite(self.kappa) or self.kappa < 0):
+            raise ValueError("kappa must be finite and non-negative or None")
+
+
+@dataclass(frozen=True, slots=True)
+class SearchConfig:
+    """Tensor-native NSGA-II controls."""
+
+    population_size: int = 100
+    generations: int = 100
+    crossover_probability: float = 0.9
+    crossover_eta: float = 15.0
+    mutation_probability: float | None = None
+    mutation_eta: float = 20.0
+    tournament_size: int = 2
+    eliminate_duplicates: bool = True
+    reuse_previous_population: bool = False
+    keep_history: bool = False
+    seed: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.population_size < 2:
+            raise ValueError("population_size must be at least 2")
+        if self.generations < 0:
+            raise ValueError("generations cannot be negative")
+        if not 0 <= self.crossover_probability <= 1:
+            raise ValueError("crossover_probability must be between zero and one")
+        if (
+            not math.isfinite(self.crossover_eta)
+            or not math.isfinite(self.mutation_eta)
+            or self.crossover_eta <= 0
+            or self.mutation_eta <= 0
+        ):
+            raise ValueError("crossover_eta and mutation_eta must be positive and finite")
+        if self.mutation_probability is not None and not 0 <= self.mutation_probability <= 1:
+            raise ValueError("mutation_probability must be between zero and one")
+        if self.tournament_size < 2:
+            raise ValueError("tournament_size must be at least 2")
+
+
+@dataclass(frozen=True, slots=True)
+class LeanHEBOConfig:
+    """Complete LeanHEBO configuration; there are deliberately no presets."""
+
+    random_samples: int | None = None
+    nonfinite_policy: Literal["drop", "raise"] = "drop"
+    runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
+    gp: GPConfig = field(default_factory=GPConfig)
+    warp: WarpConfig = field(default_factory=WarpConfig)
+    acquisition: AcquisitionConfig = field(default_factory=AcquisitionConfig)
+    search: SearchConfig = field(default_factory=SearchConfig)
+
+    def __post_init__(self) -> None:
+        if self.random_samples is not None and self.random_samples < 2:
+            raise ValueError("random_samples must be at least 2 or None")
+        if self.nonfinite_policy not in ("drop", "raise"):
+            raise ValueError("nonfinite_policy must be 'drop' or 'raise'")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a checkpoint- and JSON-friendly representation."""
+
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> LeanHEBOConfig:
+        """Reconstruct a configuration from :meth:`to_dict` output."""
+
+        root = dict(value)
+        return cls(
+            random_samples=root.get("random_samples"),
+            nonfinite_policy=root.get("nonfinite_policy", "drop"),
+            runtime=_construct(RuntimeConfig, root.get("runtime", {})),
+            gp=_construct(GPConfig, root.get("gp", {})),
+            warp=_construct(WarpConfig, root.get("warp", {})),
+            acquisition=_construct(AcquisitionConfig, root.get("acquisition", {})),
+            search=_construct(SearchConfig, root.get("search", {})),
+        )
+
+
+ConfigT = TypeVar("ConfigT", RuntimeConfig, GPConfig, WarpConfig, AcquisitionConfig, SearchConfig)
+
+
+def _construct(config_type: type[ConfigT], value: object) -> ConfigT:
+    if isinstance(value, config_type):
+        return value
+    if not isinstance(value, Mapping):
+        raise TypeError(f"expected a mapping for {config_type.__name__}")
+    return config_type(**dict(value))

leanhebo/data/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+
+"""Tensor-native batch and observation data APIs."""
+
+from typing import TYPE_CHECKING, Any
+
+from leanhebo.data.batch import CandidateBatch, EncodedBatch
+
+if TYPE_CHECKING:
+    from leanhebo.data.store import NonFinitePolicy, ObservationBatch, ObservationStore
+
+__all__ = [
+    "CandidateBatch",
+    "EncodedBatch",
+    "NonFinitePolicy",
+    "ObservationBatch",
+    "ObservationStore",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # CompiledSpace imports the adapter package.  Keeping store exports lazy
+    # avoids a package-initialization cycle while preserving the concise public
+    # ``from leanhebo.data import ObservationStore`` spelling.
+    if name in {"NonFinitePolicy", "ObservationBatch", "ObservationStore"}:
+        from leanhebo.data import store
+
+        return getattr(store, name)
+    raise AttributeError(name)

leanhebo/data/adapters/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Public adapter registry exports."""
+
+from leanhebo.data.adapters.registry import (
+    DEFAULT_ADAPTERS,
+    InputAdapterRegistry,
+    columns_from_input,
+)
+
+__all__ = ["DEFAULT_ADAPTERS", "InputAdapterRegistry", "columns_from_input"]

leanhebo/data/adapters/numpy.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+
+"""NumPy input adapter."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+
+
+def numpy_to_columns(value: np.ndarray, names: Sequence[str]) -> dict[str, list[object]]:
+    """Convert a regular or structured ndarray to named Python columns."""
+
+    if value.dtype.names is not None:
+        missing = [name for name in names if name not in value.dtype.names]
+        if missing:
+            raise ValueError(f"NumPy structured array is missing columns: {missing}")
+        return {name: value[name].reshape(-1).tolist() for name in names}
+    if value.ndim == 1:
+        if value.size != len(names):
+            raise ValueError(
+                f"one-dimensional NumPy input must contain {len(names)} values, got {value.size}"
+            )
+        value = value.reshape(1, -1)
+    if value.ndim != 2:
+        raise ValueError("NumPy input must have one or two dimensions")
+    if value.shape[1] != len(names):
+        raise ValueError(f"NumPy input must have {len(names)} columns, got {value.shape[1]}")
+    return {name: value[:, index].tolist() for index, name in enumerate(names)}

leanhebo/data/adapters/pandas.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+
+"""Pandas input adapter with no import-time Pandas dependency."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+
+def pandas_to_columns(value: Any, names: Sequence[str]) -> dict[str, list[object]]:
+    missing = [name for name in names if name not in value.columns]
+    if missing:
+        raise ValueError(f"Pandas DataFrame is missing columns: {missing}")
+    return {name: value[name].tolist() for name in names}