alf_core 0.1.0a0__py3-none-any.whl

alf_core/__init__.py

@@ -0,0 +1,58 @@
+# Copyright 2026 InstaDeep Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This file makes alf_core a Python package
+import importlib.metadata
+
+from alf_core.dataclasses import (
+    Candidate,
+    LabelledCandidates,
+    Modality,
+    Predictions,
+    Results,
+    State,
+    SurrogateEpochMetrics,
+)
+from alf_core.dataset.base_dataset import BaseDataset, BaseDatasetConfig
+from alf_core.model.base_model import BaseModel, BaseTrainConfig
+from alf_core.model.normaliser import (
+    InputNormaliser,
+    InputStandardiser,
+    OutputStandardiser,
+    make_input_transform,
+)
+from alf_core.optimizer.acquisition_function import AcquisitionFunction
+from alf_core.optimizer.optimizer import Optimizer
+from alf_core.optimizer.search import (
+    BaseSearch,
+    DatasetSearch,
+    GeneratorSearch,
+    ModelProtocolSearch,
+    ProtocolSearch,
+    SearchProtocol,
+)
+from alf_core.oracle.oracle import Oracle
+from alf_core.surrogate.surrogate import Surrogate
+from alf_core.tasks.base_task import BaseTask
+from alf_core.tasks.design_task import DesignTask
+from alf_core.tasks.supervised_task import SupervisedTask
+from alf_core.tasks.zeroshot_task import ZeroShotTask
+from alf_core.utils.enums import ProblemType
+from alf_core.utils.state_logger import (
+    FileStateLogger,
+    StateLogger,
+    TerminalStateLogger,
+)
+
+__version__ = importlib.metadata.version("alf-core")

alf_core/dataclasses/__init__.py

@@ -0,0 +1,26 @@
+# Copyright 2026 InstaDeep Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# ruff: noqa: E402
+import beartype.claw
+
+beartype.claw.beartype_this_package()
+
+from alf_core.dataclasses.candidate import Candidate, Modality
+from alf_core.dataclasses.labelled_candidates import LabelledCandidates
+from alf_core.dataclasses.predictions import Predictions
+from alf_core.dataclasses.results import Results
+from alf_core.dataclasses.round_metrics import RoundMetrics
+from alf_core.dataclasses.state import State
+from alf_core.dataclasses.surrogate_epoch_metrics import SurrogateEpochMetrics

alf_core/dataclasses/candidate.py

@@ -0,0 +1,225 @@
+# Copyright 2026 InstaDeep Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any, TypeAlias, Union
+
+import numpy as np
+
+if TYPE_CHECKING:
+    import torch
+
+    DataFrameCompatible: TypeAlias = Union[
+        str, int, float, bool, dict, list, tuple, np.ndarray, torch.Tensor
+    ]
+else:
+    DataFrameCompatible: TypeAlias = Union[
+        str, int, float, bool, dict, list, tuple, np.ndarray, Any
+    ]
+
+try:
+    import torch
+
+    HAS_TORCH = True
+except ImportError:
+    HAS_TORCH = False
+
+
+class Modality(Enum):
+    """The *kind* of candidate — used to match datasets with compatible models and metrics.
+
+    It is the data's domain where one exists, not how the data is stored. This is why a
+    protein sequence and a SMILES string are distinct modalities (``SEQUENCE`` vs
+    ``MOLECULE``) even though both are stored as ``str``: they pair with different models
+    and metrics. Storage type is never encoded here — it is inferred from ``type(data)``
+    (see :meth:`Candidate.to_serializable`).
+
+    Members:
+        SEQUENCE: Biological sequences (protein / nucleotide), as strings.
+        MOLECULE: Small molecules, as SMILES strings.
+        TABULAR: Domain-agnostic numeric feature vectors (arrays, tensors, scalars, dicts).
+    """
+
+    SEQUENCE = "sequence"
+    MOLECULE = "molecule"
+    TABULAR = "tabular"
+
+
+@dataclass(eq=False, unsafe_hash=False)
+class Candidate:
+    """A candidate is a data point with a modality and features.
+
+    Attributes:
+        data: The raw data of the candidate (e.g., a sequence string, a SMILES string,
+            a feature vector).
+        modality: The data's domain (see :class:`Modality`) — what it represents, e.g.
+            ``"sequence"`` or ``"molecule"``. Not its storage type.
+        features: Optional dictionary of precomputed features for the candidate.
+    """
+
+    data: Any
+    modality: Modality | str
+    features: dict | None = None
+
+    def __post_init__(self) -> None:
+        """Check and convert modality to Modality enum if necessary and
+        initialize features to empty dict if None.
+
+        Raises:
+            ValueError: If the modality is not a valid Modality enum.
+        """
+        if not isinstance(self.modality, Modality):
+            try:
+                self.modality = Modality(self.modality)
+            except ValueError:
+                raise ValueError(f"Invalid modality: {self.modality}")
+
+        if self.features is None:
+            self.features = {}
+
+    def __repr__(self) -> str:
+        """Return a string representation of the candidate.
+
+        Returns:
+            A string representation showing the candidate's data, modality, and features.
+        """
+        return f"Candidate(data={self.data}, modality={self.modality}, features={self.features})"
+
+    def _safe_equal(self, a: Any, b: Any) -> bool:
+        """Compare two values, handling numpy arrays and nested structures.
+
+        Args:
+            a: First value to compare.
+            b: Second value to compare.
+
+        Returns:
+            True if the values are equal, False otherwise.
+        """
+        # Handle None cases
+        if a is None and b is None:
+            return True
+        if a is None or b is None:
+            return False
+
+        # Handle numpy arrays
+        if isinstance(a, np.ndarray) and isinstance(b, np.ndarray):
+            return np.array_equal(a, b, equal_nan=True)
+
+        # Handle torch tensors
+        if HAS_TORCH and isinstance(a, torch.Tensor) and isinstance(b, torch.Tensor):
+            return torch.equal(a, b)
+
+        # Handle dict (for features)
+        if isinstance(a, dict) and isinstance(b, dict):
+            if a.keys() != b.keys():
+                return False
+            return all(self._safe_equal(a[k], b[k]) for k in a.keys())
+
+        # Handle lists/tuples (for nested data)
+        if isinstance(a, (list, tuple)) and isinstance(b, (list, tuple)):
+            if len(a) != len(b):
+                return False
+            return all(self._safe_equal(x, y) for x, y in zip(a, b))
+
+        # Default comparison
+        # Note, if comparison fails, an error will be thrown
+        result = a == b
+        # Handle case where comparison returns array-like object
+        # Convert to boolean if possible
+        if hasattr(result, "__len__") and len(result) == 1:
+            return bool(result[0])
+        elif hasattr(result, "item"):  # For single-element tensors/arrays
+            return bool(result.item())
+        return bool(result)
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two Candidate objects for equality.
+
+        Handles numpy arrays in data and features fields correctly.
+
+        Args:
+            other: The object to compare with.
+
+        Returns:
+            True if the candidates are equal, False otherwise.
+        """
+        if not isinstance(other, Candidate):
+            return False
+
+        return (
+            self._safe_equal(self.data, other.data)
+            and self.modality == other.modality
+            and self._safe_equal(self.features, other.features)
+        )
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def to_serializable(self) -> DataFrameCompatible | None:
+        """Convert candidate data to a format suitable for pandas DataFrame storage.
+
+        Dispatch is based on the **type** of ``data``, not on :attr:`modality`. Modality
+        describes the data's domain (see :class:`Modality`); how it is stored — and
+        therefore how it is serialised — is determined by its Python type:
+
+        - ``str`` (sequences, SMILES, JSON-encoded payloads): returned unchanged.
+        - ``torch.Tensor``: converted to a numpy array for compact storage.
+        - numpy array, scalar (Python ``int``/``float``/``bool`` or a numpy scalar such
+          as ``np.int64``), ``dict``, ``list``, ``tuple``, pandas ``Series``: returned
+          unchanged.
+        - ``None``: returned as ``None``.
+
+        Returns:
+            DataFrameCompatible: The candidate data in a DataFrame-compatible format.
+                Common types include str, dict, np.ndarray, pd.Series, or torch.Tensor.
+
+        Raises:
+            TypeError: If the data type is not DataFrame-compatible.
+
+        Examples:
+            >>> # A sequence or SMILES string is stored as-is
+            >>> Candidate(data="ACDEFG", modality=Modality.SEQUENCE).to_serializable()
+            'ACDEFG'
+
+            >>> Candidate(data="CC(=O)O", modality=Modality.MOLECULE).to_serializable()
+            'CC(=O)O'
+
+            >>> # A feature dict is stored as-is
+            >>> c = Candidate(data={"age": 32, "height": 178}, modality=Modality.TABULAR)
+            >>> c.to_serializable()
+            {'age': 32, 'height': 178}
+        """
+        data = self.data
+        if data is None:
+            return None
+        # Strings (sequences, SMILES, JSON-encoded payloads) are stored as-is.
+        if isinstance(data, str):
+            return data
+        # Torch tensors are converted to numpy arrays for compact storage.
+        if HAS_TORCH and isinstance(data, torch.Tensor):
+            return data.cpu().numpy()
+        # numpy arrays, scalars (incl. numpy scalars like np.int64), and standard
+        # containers are stored as-is.
+        if isinstance(data, (int, float, bool, np.generic, dict, np.ndarray, list, tuple)):
+            return data
+        # pandas Series (checked without importing pandas).
+        if data.__class__.__name__ == "Series":
+            return data
+
+        raise TypeError(
+            f"Cannot serialise candidate data of type {type(data).__name__}. Supported "
+            f"types: str, int, float, bool, dict, list, tuple, numpy.ndarray, "
+            f"pandas.Series, or torch.Tensor."
+        )

alf_core/dataclasses/labelled_candidates.py

@@ -0,0 +1,234 @@
+# Copyright 2026 InstaDeep Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from dataclasses import dataclass
+from typing import Any, Union
+
+import numpy as np
+import pandas as pd
+
+from alf_core.dataclasses.candidate import Candidate
+
+
+@dataclass(eq=False, unsafe_hash=False)
+class LabelledCandidates:
+    """A collection of candidates paired with their labels.
+
+    Attributes:
+        candidates: A list of Candidate objects.
+        labels: A numpy array of labels corresponding to each candidate.
+    """
+
+    candidates: list[Candidate]
+    labels: np.ndarray
+
+    def __post_init__(self) -> None:
+        """Validate that candidates and labels have the same length.
+
+        Raises:
+            AssertionError: If the length of candidates and labels don't match.
+        """
+        assert len(self.candidates) == len(self.labels), (
+            f"Candidates and labels must have the same length, "
+            f"got {len(self.candidates)} candidates and {len(self.labels)} labels"
+        )
+
+    def __len__(self) -> int:
+        """Return the number of candidates in the collection.
+
+        Returns:
+            The number of candidates (and labels) in the collection.
+        """
+        return len(self.candidates)
+
+    def __getitem__(
+        self, index: Union[int, slice, np.ndarray]
+    ) -> tuple[list[Candidate], np.ndarray]:
+        """Make LabelledCandidates subscriptable.
+
+        Args:
+            index: Integer index or slice to select candidates and labels.
+
+        Returns:
+            The candidates and labels at the specified index or slice.
+        """
+        if isinstance(index, int):
+            return ([self.candidates[index]], np.array([self.labels[index]]))
+        elif isinstance(index, np.ndarray):
+            return ([self.candidates[i] for i in index], self.labels[index])
+        else:
+            return (self.candidates[index], self.labels[index])
+
+    @property
+    def data(self) -> list[Any]:
+        """Return the raw data of each candidate.
+
+        Returns:
+            A list containing the raw data (e.g. a sequence string, a SMILES string,
+            a feature vector) of each candidate in the collection.
+        """
+        return [cand.data for cand in self.candidates]
+
+    def append(
+        self,
+        candidates: Union[list[Candidate], "LabelledCandidates"],
+        labels: np.ndarray | None = None,
+    ) -> None:
+        """Append candidates and labels to this collection.
+
+        Args:
+            candidates: Either a list of Candidate objects or another LabelledCandidates
+                object. If a list is provided, labels must also be provided.
+            labels: Optional numpy array of labels. Required if candidates is a list,
+                ignored if candidates is a LabelledCandidates object.
+
+        Raises:
+            AssertionError: If candidates is a list and labels is None, or if the
+                length of candidates and labels don't match.
+        """
+        if isinstance(candidates, LabelledCandidates):
+            self.candidates.extend(candidates.candidates)
+            self.labels = np.concatenate((self.labels, candidates.labels), axis=0)
+        else:
+            assert labels is not None, (
+                "Labels must be provided when appending a list of Candidates "
+                "(pass a LabelledCandidates instead to append "
+                "without providing labels separately)"
+            )
+            assert len(candidates) == len(labels), (
+                f"Candidates and labels must have the same length, "
+                f"got {len(candidates)} candidates and {len(labels)} labels"
+            )
+            self.candidates.extend(candidates)
+            self.labels = np.concatenate((self.labels, labels), axis=0)
+
+    def shuffle(self, seed: int) -> "LabelledCandidates":
+        """Create a new LabelledCandidates object with shuffled candidates and labels.
+
+        Args:
+            seed: Random seed for reproducibility of the shuffle.
+
+        Returns:
+            A new LabelledCandidates object with the same candidates and labels,
+            but in a randomly shuffled order.
+        """
+        shuffled_indices = np.random.RandomState(seed).permutation(len(self.candidates))
+        return LabelledCandidates(
+            candidates=[self.candidates[i] for i in shuffled_indices],
+            labels=self.labels[shuffled_indices],
+        )
+
+    def sort(self, ascending: bool = True) -> "LabelledCandidates":
+        """Sort the candidates and labels by label values.
+
+        Args:
+            ascending: If True, sort in ascending order (lowest to highest).
+                If False, sort in descending order (highest to lowest).
+                Defaults to True.
+
+        Returns:
+            A new LabelledCandidates object with candidates and labels sorted
+            by label values.
+        """
+        sorted_indices = np.argsort(self.labels)
+        if not ascending:
+            sorted_indices = sorted_indices[::-1]
+        return LabelledCandidates(
+            candidates=[self.candidates[i] for i in sorted_indices],
+            labels=self.labels[sorted_indices],
+        )
+
+    def remove(self, candidates: Union[list[Candidate], "LabelledCandidates"]) -> None:
+        """Remove specified candidates and their corresponding labels from this collection.
+
+        Uses identity-based comparison (same object instance) for removal.
+        Candidates not present in the collection are silently ignored.
+
+        Args:
+            candidates: Either a list of Candidate objects or a LabelledCandidates
+                object containing the candidates to remove.
+        """
+        if isinstance(candidates, LabelledCandidates):
+            candidates = candidates.candidates
+
+        # Build set of object IDs to remove for O(1) lookup
+        ids_to_remove = {id(c) for c in candidates}
+
+        # Find indices to keep (single pass)
+        indices_to_keep = [i for i, c in enumerate(self.candidates) if id(c) not in ids_to_remove]
+
+        # Update candidates and labels
+        self.candidates = [self.candidates[i] for i in indices_to_keep]
+        self.labels = self.labels[indices_to_keep]
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """Convert the labelled candidates to a pandas DataFrame.
+
+        Returns:
+            A DataFrame with columns:
+            - "data": The formatted data of each candidate
+            - "label": The label value for each candidate
+            - Additional columns for any features present in the candidates
+        """
+        rows = [
+            {"data": cand.to_serializable(), "label": label}
+            | (cand.features if isinstance(cand.features, dict) else {})
+            for cand, label in zip(self.candidates, self.labels)
+        ]
+        return pd.DataFrame.from_records(rows)
+
+    def get_top_k(self, k: int) -> "LabelledCandidates":
+        """Return the top k candidates based on their label values.
+
+        Args:
+            k: Number of top candidates to select.
+
+        Returns:
+            New LabelledCandidates object containing the top k candidates sorted
+            by label values (highest first).
+        """
+        top_k_indices = self.labels.argsort()[::-1][:k]
+        top_k_candidates = [self.candidates[i] for i in top_k_indices]
+        top_k_labels = self.labels[top_k_indices]
+        return LabelledCandidates(candidates=top_k_candidates, labels=top_k_labels)
+
+    def __iter__(self):
+        """Iterate over candidates and labels, yielding (candidate, label) tuples.
+
+        Yields:
+            Tuple of (Candidate, float): A candidate and its corresponding label
+        """
+        for candidate, label in zip(self.candidates, self.labels):
+            yield candidate, label
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two LabelledCandidates objects for equality.
+
+        Handles numpy array labels correctly.
+
+        Args:
+            other: The object to compare with.
+
+        Returns:
+            True if the labeled candidates are equal, False otherwise.
+        """
+        if not isinstance(other, LabelledCandidates):
+            return False
+
+        return self.candidates == other.candidates and np.array_equal(
+            self.labels, other.labels, equal_nan=True
+        )
+
+    __hash__ = None  # type: ignore[assignment]

alf_core/dataclasses/predictions.py

@@ -0,0 +1,119 @@
+# Copyright 2026 InstaDeep Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from alf_core.dataclasses.candidate import Candidate
+from alf_core.utils.enums import ProblemType
+
+logger = logging.getLogger("alf-core")
+
+
+@dataclass
+class Predictions:
+    """A data class for storing and managing predictions from a model.
+
+    Attributes:
+        means: A numpy array of mean predictions across all candidates.
+        variances: An optional numpy array of prediction variances, representing
+            the model's uncertainty for each prediction.
+        empirical_dist: An optional 2D numpy array containing predictions
+            from individual models in an ensemble. Typically has the shape
+            (num_candidates, num_ensemble_models).
+    """
+
+    means: np.ndarray
+    variances: np.ndarray | None = None
+    empirical_dist: np.ndarray | None = None
+
+    def __post_init__(self) -> None:
+        """Validate prediction arrays have consistent lengths.
+
+        Raises:
+            AssertionError: If means is empty, or if variances or empirical_dist
+                don't match the length of means.
+        """
+        assert len(self.means) > 0, (
+            "Means must have at least one prediction — expected shape (num_candidates,)"
+        )
+        if self.variances is not None:
+            assert len(self.variances) == len(self.means), (
+                "Variances must have the same length as means (num_candidates,), "
+                f"got {len(self.variances)} variances and {len(self.means)} means"
+            )
+        if self.empirical_dist is not None:
+            assert len(self.empirical_dist) == len(self.means), (
+                "Empirical_dist must have the same length as means - "
+                "shape (num_candidates, num_ensemble_models), "
+                f"but its first dimension ({len(self.empirical_dist)}) does not match "
+                f"len(means) ({len(self.means)})"
+            )
+
+    def __len__(self) -> int:
+        """Return the number of predictions.
+
+        Returns:
+            The number of predictions (length of the means array).
+        """
+        return len(self.means)
+
+    def to_dataframe(
+        self,
+        candidates: list[Candidate],
+        targets: np.ndarray,
+        problem_type: ProblemType,
+    ) -> pd.DataFrame:
+        """Convert predictions to a DataFrame.
+
+        Creates a DataFrame with predictions, targets, and optionally variances
+        and ensemble predictions.
+
+        Args:
+            candidates: List of Candidate objects corresponding to the predictions.
+            targets: Ground truth target values corresponding to each candidate.
+            problem_type: ProblemType to determine the predictions type.
+
+        Returns:
+            A DataFrame with predictions, targets, and optionally variances
+            and ensemble predictions.
+        """
+        predictions_list = []
+        is_classification = problem_type in [ProblemType.BINARY, ProblemType.MULTICLASS]
+
+        for i in range(len(self.means)):
+            record_i: dict[str, str | float | np.floating | list[float] | np.ndarray] = {
+                "data": candidates[i].data,
+                "targets": targets[i],
+            }
+
+            if is_classification:
+                for cls_idx in range(self.means.shape[1]):
+                    record_i[f"prob_class_{cls_idx}"] = self.means[i, cls_idx]
+            else:
+                record_i["mean"] = self.means[i]
+                record_i["variance"] = self.variances[i] if self.variances is not None else 0
+
+            if self.empirical_dist is not None:
+                for j in range(self.empirical_dist.shape[1]):
+                    record_i[f"ensemble_pred_{j}"] = self.empirical_dist[i, j]
+
+            predictions_list.append(record_i)
+
+        df = pd.DataFrame.from_records(predictions_list)
+        return df