alf_core 0.1.0__tar.gz

alf_core-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: alf_core
+Version: 0.1.0
+Summary: A Python package for performing active learning experiments.
+Author: InstaDeep Ltd
+License: Apache-2.0
+Project-URL: Homepage, https://instadeepai.github.io/alf/
+Project-URL: Repository, https://github.com/instadeepai/alf
+Project-URL: Documentation, https://instadeepai.github.io/alf/
+Project-URL: Paper, https://arxiv.org/abs/2609.31197
+Project-URL: Bug Tracker, https://github.com/instadeepai/alf/issues
+Keywords: active learning,bayesian optimization,machine learning,scientific discovery
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14.1,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: beartype>=0.18.0
+Requires-Dist: jaxtyping>=0.3.5
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: pydantic
+Requires-Dist: scipy>=1.9.0
+Requires-Dist: scikit-learn>=1.0.0
+
+# <img src="https://raw.githubusercontent.com/instadeepai/alf/main/docs/imgs/alf_cover_gradient.png" alt="ALF" height="40" align="top"> alf-core
+
+[![PyPI](https://img.shields.io/pypi/v/alf-core.svg)](https://pypi.org/project/alf-core/)
+[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://github.com/instadeepai/alf/blob/main/LICENSE)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/surana01/114eb5680493468e40f5a528c08f1888/raw/alf-core-coverage.json)](https://github.com/instadeepai/alf/tree/main/core)
+[![Docs](https://img.shields.io/badge/docs-instadeepai.github.io%2Falf-blue)](https://instadeepai.github.io/alf/)
+
+**The lightweight, dependency-minimal foundation of ALF (Active Learning Framework).**
+
+`alf-core` provides the base classes, core data structures, and the active-learning loop
+for iterative optimisation in computational science — optimising high-dimensional,
+combinatorially vast search spaces where each label is expensive (wet-lab assays,
+simulations, measurements). It ships with no ML-framework dependencies (only numpy,
+pandas, scipy), so it is standalone and domain-agnostic. For ready-to-use models,
+datasets, and acquisition functions, install
+[alf-tools](https://github.com/instadeepai/alf/blob/main/tools/README.md).
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/instadeepai/alf/main/docs/imgs/alf_components.svg" alt="ALF Components" width="70%">
+</div>
+
+## Installation
+
+```bash
+pip install alf-core
+```
+
+## Quick start
+
+`alf-core` is the framework layer: you supply your own `BaseDataset` and `BaseModel`
+subclasses (or install [alf-tools](https://github.com/instadeepai/alf/blob/main/tools/README.md)
+for ready-made ones), then wire them into the active-learning loop.
+
+```python
+from alf_core import (
+    DatasetSearch,
+    DesignTask,
+    Optimizer,
+    Oracle,
+    Surrogate,
+    TerminalStateLogger,
+)
+
+# Bring your own BaseDataset, BaseModel, and AcquisitionFunction subclasses
+dataset = MyDataset(...)
+surrogate = Surrogate(model=MyModel())
+optimizer = Optimizer(acquisition_fn=MyAcquisition(), search_fn=DatasetSearch())
+oracle = Oracle(scorer=dataset)
+
+# Run the active-learning loop for 5 rounds, acquiring 100 candidates per round
+task = DesignTask(num_acq_rounds=5, acq_batch_size=100)
+state = task.setup(dataset=dataset, surrogate=surrogate)
+task.run(
+    state=state,
+    state_loggers=[TerminalStateLogger()],
+    optimizer=optimizer,
+    oracle=oracle,
+)
+```
+
+For a complete, runnable `alf-core`-only example (a bootstrap-ensemble surrogate and a
+Probability of Improvement acquisition function built from scratch with numpy/scipy), see the
+[ALF Core Quickstart notebook](https://github.com/instadeepai/alf/blob/main/tutorials/alf_core_quickstart.ipynb).
+
+## Key concepts
+
+ALF runs the active-learning loop over a small set of swappable components:
+
+- **Dataset** (`BaseDataset`) — loads, splits, and queries candidate data
+- **Model** (`BaseModel`) — the surrogate/oracle/generator backbone you implement
+- **Surrogate** (`Surrogate`) — wraps a model to predict fitness and uncertainty
+- **Oracle** (`Oracle`) — returns ground-truth labels (offline pool or live scorer)
+- **Optimizer** (`Optimizer`) — proposes the next batch via acquisition + search
+- **Acquisition function** (`AcquisitionFunction`) — scores candidates to acquire
+- **Search strategy** (`BaseSearch`) — defines the candidate pool to score
+- **State** (`State`) — tracks rounds, history, and metrics across the loop
+- **Tasks** (`DesignTask`, `SupervisedTask`, `ZeroShotTask`) — drive the multi-round
+  loop, fixed-data training, or no-train evaluation
+
+## Documentation
+
+- **Core concepts:** [how the components fit together](https://instadeepai.github.io/alf/explanation/core-concepts.html)
+- **API reference:** [every class and method](https://instadeepai.github.io/alf/api/alf_core/index.html)
+- **Glossary:** [terms and benchmark metrics](https://instadeepai.github.io/alf/reference/glossary.html)
+- **Tutorials:** [tutorials/](https://github.com/instadeepai/alf/tree/main/tutorials)
+- **Full documentation:** [instadeepai.github.io/alf](https://instadeepai.github.io/alf/)
+- **Ready-to-use tools:** [alf-tools](https://github.com/instadeepai/alf/blob/main/tools/README.md)
+
+## License
+
+Apache License 2.0 — see [LICENSE](https://github.com/instadeepai/alf/blob/main/LICENSE).

alf_core-0.1.0/README.md

@@ -0,0 +1,92 @@
+# <img src="https://raw.githubusercontent.com/instadeepai/alf/main/docs/imgs/alf_cover_gradient.png" alt="ALF" height="40" align="top"> alf-core
+
+[![PyPI](https://img.shields.io/pypi/v/alf-core.svg)](https://pypi.org/project/alf-core/)
+[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://github.com/instadeepai/alf/blob/main/LICENSE)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/surana01/114eb5680493468e40f5a528c08f1888/raw/alf-core-coverage.json)](https://github.com/instadeepai/alf/tree/main/core)
+[![Docs](https://img.shields.io/badge/docs-instadeepai.github.io%2Falf-blue)](https://instadeepai.github.io/alf/)
+
+**The lightweight, dependency-minimal foundation of ALF (Active Learning Framework).**
+
+`alf-core` provides the base classes, core data structures, and the active-learning loop
+for iterative optimisation in computational science — optimising high-dimensional,
+combinatorially vast search spaces where each label is expensive (wet-lab assays,
+simulations, measurements). It ships with no ML-framework dependencies (only numpy,
+pandas, scipy), so it is standalone and domain-agnostic. For ready-to-use models,
+datasets, and acquisition functions, install
+[alf-tools](https://github.com/instadeepai/alf/blob/main/tools/README.md).
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/instadeepai/alf/main/docs/imgs/alf_components.svg" alt="ALF Components" width="70%">
+</div>
+
+## Installation
+
+```bash
+pip install alf-core
+```
+
+## Quick start
+
+`alf-core` is the framework layer: you supply your own `BaseDataset` and `BaseModel`
+subclasses (or install [alf-tools](https://github.com/instadeepai/alf/blob/main/tools/README.md)
+for ready-made ones), then wire them into the active-learning loop.
+
+```python
+from alf_core import (
+    DatasetSearch,
+    DesignTask,
+    Optimizer,
+    Oracle,
+    Surrogate,
+    TerminalStateLogger,
+)
+
+# Bring your own BaseDataset, BaseModel, and AcquisitionFunction subclasses
+dataset = MyDataset(...)
+surrogate = Surrogate(model=MyModel())
+optimizer = Optimizer(acquisition_fn=MyAcquisition(), search_fn=DatasetSearch())
+oracle = Oracle(scorer=dataset)
+
+# Run the active-learning loop for 5 rounds, acquiring 100 candidates per round
+task = DesignTask(num_acq_rounds=5, acq_batch_size=100)
+state = task.setup(dataset=dataset, surrogate=surrogate)
+task.run(
+    state=state,
+    state_loggers=[TerminalStateLogger()],
+    optimizer=optimizer,
+    oracle=oracle,
+)
+```
+
+For a complete, runnable `alf-core`-only example (a bootstrap-ensemble surrogate and a
+Probability of Improvement acquisition function built from scratch with numpy/scipy), see the
+[ALF Core Quickstart notebook](https://github.com/instadeepai/alf/blob/main/tutorials/alf_core_quickstart.ipynb).
+
+## Key concepts
+
+ALF runs the active-learning loop over a small set of swappable components:
+
+- **Dataset** (`BaseDataset`) — loads, splits, and queries candidate data
+- **Model** (`BaseModel`) — the surrogate/oracle/generator backbone you implement
+- **Surrogate** (`Surrogate`) — wraps a model to predict fitness and uncertainty
+- **Oracle** (`Oracle`) — returns ground-truth labels (offline pool or live scorer)
+- **Optimizer** (`Optimizer`) — proposes the next batch via acquisition + search
+- **Acquisition function** (`AcquisitionFunction`) — scores candidates to acquire
+- **Search strategy** (`BaseSearch`) — defines the candidate pool to score
+- **State** (`State`) — tracks rounds, history, and metrics across the loop
+- **Tasks** (`DesignTask`, `SupervisedTask`, `ZeroShotTask`) — drive the multi-round
+  loop, fixed-data training, or no-train evaluation
+
+## Documentation
+
+- **Core concepts:** [how the components fit together](https://instadeepai.github.io/alf/explanation/core-concepts.html)
+- **API reference:** [every class and method](https://instadeepai.github.io/alf/api/alf_core/index.html)
+- **Glossary:** [terms and benchmark metrics](https://instadeepai.github.io/alf/reference/glossary.html)
+- **Tutorials:** [tutorials/](https://github.com/instadeepai/alf/tree/main/tutorials)
+- **Full documentation:** [instadeepai.github.io/alf](https://instadeepai.github.io/alf/)
+- **Ready-to-use tools:** [alf-tools](https://github.com/instadeepai/alf/blob/main/tools/README.md)
+
+## License
+
+Apache License 2.0 — see [LICENSE](https://github.com/instadeepai/alf/blob/main/LICENSE).

alf_core-0.1.0/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-0.1.0/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-0.1.0/alf_core/dataclasses/candidate.py

@@ -0,0 +1,228 @@
+# 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.
+        MATERIALS: Materials-science candidates (chemical composition formula strings or
+            serialized crystal structure), as strings.
+        TABULAR: Domain-agnostic numeric feature vectors (arrays, tensors, scalars, dicts).
+    """
+
+    SEQUENCE = "sequence"
+    MOLECULE = "molecule"
+    MATERIALS = "materials"
+    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."
+        )