Add sequence parameter

CHANGELOG.md

@@ -22,6 +22,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Optional/secondary fields of discrete parameter classes are now keyword-only
 
 ### Added
+- `SequenceParameter` class for modeling parameters whose values are configurable-length
+  token sequences from a predefined alphabet
+- `EncoderProtocol` as a public interface for specifying parameter encoders
 - `coefficients` attribute for `DiscreteSumConstraint`, enabling weighted sums. Follows
   the same pattern as `ContinuousLinearConstraint.coefficients`
 - `simplex_coefficients` keyword argument to `SubspaceDiscrete.from_simplex` for
@@ -30,7 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `CandidatesProtocol` as an interface for candidates generation
 - `EmptyCandidates`, `TableCandidates` and `ProductCandidates` classes implementing
   `CandidatesProtocol`
-- `DiscreteParameter.is_finite` property
+- `DiscreteParameter.__len__` and `DiscreteParameter.is_finite` property
 - `SubspaceDiscrete.batch_constraints` field for storing batch-level constraints
 - `SubspaceDiscrete.from_dataframe` now accepts `batch_constraints`
 - `validate_parameter_input` now accepts an `allow_empty` flag to permit zero-row input

baybe/exceptions.py

@@ -180,7 +180,7 @@ class UnsupportedEarlyFilteringError(Exception):
 
 
 class InfiniteSpaceError(Exception):
-    """An operation requires a finite search space but the space is infinite."""
+    """An operation requires a finite space but the space is infinite."""
 
 
 # Collect leftover original slotted classes processed by `attrs.define`

baybe/parameters/__init__.py

@@ -2,6 +2,7 @@
 
 from baybe.parameters.categorical import CategoricalParameter, TaskParameter
 from baybe.parameters.custom import CustomDiscreteParameter
+from baybe.parameters.encoding import EncoderProtocol
 from baybe.parameters.enum import (
     CategoricalEncoding,
     CustomEncoding,
@@ -11,6 +12,7 @@
     NumericalContinuousParameter,
     NumericalDiscreteParameter,
 )
+from baybe.parameters.sequence import SequenceParameter
 from baybe.parameters.substance import SubstanceParameter
 from baybe.utils.metadata import MeasurableMetadata
 
@@ -19,9 +21,11 @@
     "CategoricalParameter",
     "CustomDiscreteParameter",
     "CustomEncoding",
+    "EncoderProtocol",
     "MeasurableMetadata",
     "NumericalContinuousParameter",
     "NumericalDiscreteParameter",
+    "SequenceParameter",
     "SubstanceEncoding",
     "SubstanceParameter",
     "TaskParameter",

baybe/parameters/base.py

@@ -16,6 +16,7 @@
 from narwhals.stable.v2.dependencies import is_into_series
 from typing_extensions import override
 
+from baybe.exceptions import InfiniteSpaceError
 from baybe.serialization import (
     SerialMixin,
 )
@@ -131,11 +132,18 @@ class DiscreteParameter(Parameter, ABC):
     def values(self) -> tuple:
         """The values the parameter can take."""
 
+    def __len__(self) -> int:
+        """Return the number of values the parameter can take."""
+        return len(self.values)
+
     @property
     def is_finite(self) -> bool:
         """Indicates whether the parameter has a finite number of values."""
-        len(self.values)  # <-- raises an error if the parameter is infinite
-        return True
+        try:
+            len(self)
+            return True
+        except InfiniteSpaceError:
+            return False
 
     @property
     def active_values(self) -> tuple:
@@ -242,7 +250,7 @@ def summary(self) -> dict:
         return dict(
             Name=self.name,
             Type=self.__class__.__name__,
-            nValues=len(self.values),
+            nValues=len(self),
         )
 
 
@@ -261,7 +269,7 @@ class _EncodedDiscreteParameter(DiscreteParameter, ABC):
     _active_values: tuple[str | bool, ...] | None = field(
         default=None,
         converter=optional_c(
-            Converter(  # type: ignore[misc, call-overload]
+            Converter(  # type: ignore[misc]
                 nonstring_to_tuple, takes_self=True, takes_field=True
             )
         ),
@@ -301,10 +309,10 @@ def _validate_active_values(  # noqa: DOC101, DOC103
             )
         if len(set(content)) != len(content):
             raise ValueError("The active parameter values must be unique.")
-        if not all(v in self.values for v in content):
+        if invalid := [v for v in content if not self.is_in_range(v)]:
             raise ValueError(
-                f"All active values must be valid parameter choices from: "
-                f"{self.values}, provided: {content}"
+                f"All active values must be valid parameter choices. "
+                f"Provided invalid values: {invalid}"
             )
 
     @override

baybe/parameters/categorical.py

@@ -49,7 +49,7 @@ class CategoricalParameter(_EncodedDiscreteParameter):
     encoding: CategoricalEncoding = field(
         default=CategoricalEncoding.OHE, converter=CategoricalEncoding, kw_only=True
     )
-    # See base class.
+    """The encoding used the generate the parameters computational representation."""
 
     @override
     @property
@@ -108,7 +108,7 @@ class TaskParameter(CategoricalParameter):
     """Parameter class for task parameters."""
 
     encoding: CategoricalEncoding = field(default=CategoricalEncoding.INT, init=False)
-    # See base class.
+    """The encoding used the generate the parameters computational representation."""
 
 
 # Collect leftover original slotted classes processed by `attrs.define`

baybe/parameters/encoding.py

@@ -0,0 +1,133 @@
+"""Sequence encoders."""
+
+from __future__ import annotations
+
+import gc
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+import narwhals.stable.v2 as nw
+from attrs import define, field
+from attrs.validators import instance_of
+from exceptiongroup import ExceptionGroup
+
+from baybe.settings import active_settings
+from baybe.utils.dataframe import _df_with_backend
+
+if TYPE_CHECKING:
+    from narwhals.stable.v2.typing import IntoDataFrame, IntoSeries
+
+
+@runtime_checkable
+class EncoderProtocol(Protocol):
+    """Type protocol specifying the interface encoders need to implement."""
+
+    # Use slots so that derived classes also remain slotted
+    # See also: https://www.attrs.org/en/stable/glossary.html#term-slotted-classes
+    __slots__ = ()
+
+    def __call__(self, series: IntoSeries, /) -> IntoDataFrame:
+        """Encode a given series of values.
+
+        Args:
+            series: A series in an arbitrary backend, containing the values to encode.
+
+        Returns:
+            A dataframe containing the encoded representations of the input values, in
+            the same backend as the input series and with the same row order.
+        """
+
+
+@define
+class _Encoder:
+    """A narwhals wrapper for user-specified encoders to hide their native backend.
+
+    Wraps a user-provided instance of an :class:`EncoderProtocol` and automatically
+    infers which native dataframe backend it expects via trial and error. The inferred
+    backend is cached after the first successful call so that trial-and-error detection
+    runs only once.
+    """
+
+    _encoder: EncoderProtocol = field(
+        alias="encoder", validator=instance_of(EncoderProtocol)
+    )
+    """The user-provided encoder."""
+
+    _implementation: nw.Implementation | None = field(
+        default=None, init=False, eq=False
+    )
+    """The inferred native backend, cached after the first successful call."""
+
+    def __call__(self, series: nw.Series, /) -> nw.DataFrame:
+        """Encode a narwhals series, inferring the required backend if not yet known.
+
+        On the first call, tries available backends in order (starting with
+        :attr:`~baybe.settings.Settings.default_dataframe_backend`) until the wrapped
+        callable succeeds. The successful backend is cached for all subsequent calls.
+
+        Args:
+            series: A narwhals series containing the values to encode.
+
+        Returns:
+            A narwhals dataframe containing the encoded representations, collected into
+            the same backend used for the input series.
+        """
+        if self._implementation is None:
+            self._implementation, result = self._infer_backend(series)
+            return result
+
+        return self._encode(series, self._implementation)
+
+    def _infer_backend(
+        self, series: nw.Series, /
+    ) -> tuple[nw.Implementation, nw.DataFrame]:
+        """Infer the encoder's backend by trial-and-error across available backends.
+
+        Args:
+            series: The series to use for probing.
+
+        Returns:
+            A tuple containing:
+
+                * the first backend for which the encoder succeeds
+                * the resulting encoded dataframe
+
+        Raises:
+            ExceptionGroup: If the encoder raises an exception for every tried backend.
+        """
+        preferred = active_settings.default_dataframe_backend
+        ordered = [preferred] + [b for b in nw.Implementation if b is not preferred]
+        backends = [b for b in ordered if _is_backend_imported(b)]
+
+        exceptions: list[Exception] = []
+        for backend in backends:
+            try:
+                result = self._encode(series, backend)
+                return backend, result
+            except Exception as ex:  # noqa: BLE001
+                exceptions.append(ex)
+
+        raise ExceptionGroup("The encoder failed for all tried backends", exceptions)
+
+    def _encode(self, series: nw.Series, backend: nw.Implementation, /) -> nw.DataFrame:
+        """Call the encoder with the given series using the specified backend.
+
+        Args:
+            series: The series to encode.
+            backend: The native backend to convert the series to before encoding.
+
+        Returns:
+            A narwhals dataframe in the original series backend.
+        """
+        native_series = _df_with_backend(series, backend).to_native()
+        result = nw.from_native(self._encoder(native_series), eager_only=True)
+        return _df_with_backend(result, series.implementation)
+
+
+def _is_backend_imported(backend: nw.Implementation) -> bool:
+    """Check if the given native backend has already been imported."""
+    getter = getattr(nw.dependencies, f"get_{backend.value}", None)
+    return getter is not None and getter() is not None
+
+
+# Collect leftover original slotted classes processed by `attrs.define`
+gc.collect()