Metadata-Version: 2.4
Name: alf_tools
Version: 0.1.0b0
Summary: A Python package with tools 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: Bug Tracker, https://github.com/instadeepai/alf/issues
Keywords: active learning,bayesian optimization,machine learning,scientific discovery,pytorch
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: alf_core
Requires-Dist: requests>=2.25.0
Requires-Dist: huggingface_hub<2.0,>=0.27.0
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: jaxtyping>=0.3.5
Requires-Dist: torch>=2.10.0
Requires-Dist: gpytorch<2.0,>=1.9.0
Requires-Dist: scipy>=1.9.0
Requires-Dist: botorch<1.0,>=0.17.0
Provides-Extra: transformers
Requires-Dist: transformers>=4.36.0; extra == "transformers"
Provides-Extra: chemprop
Requires-Dist: chemprop<3.0.0,>=2.0.0; extra == "chemprop"
Provides-Extra: esm2
Requires-Dist: alf_tools[transformers]; extra == "esm2"
Provides-Extra: esmfold
Requires-Dist: alf_tools[transformers]; extra == "esmfold"
Requires-Dist: accelerate>=0.26.0; extra == "esmfold"
Provides-Extra: guacamol
Requires-Dist: rdkit>=2022.9.0; extra == "guacamol"
Provides-Extra: mlip
Requires-Dist: mlip>=0.2.0; extra == "mlip"
Provides-Extra: mlip-cuda13
Requires-Dist: mlip[cuda13]>=0.2.0; extra == "mlip-cuda13"
Provides-Extra: protein
Requires-Dist: alf_tools[esm2,esmfold]; extra == "protein"
Provides-Extra: molecule
Requires-Dist: alf_tools[chemprop,guacamol,mlip]; extra == "molecule"

# <img src="https://raw.githubusercontent.com/instadeepai/alf/main/docs/imgs/alf_cover_gradient.png" alt="ALF" height="40" align="top"> alf-tools

[![PyPI](https://img.shields.io/pypi/v/alf-tools.svg)](https://pypi.org/project/alf-tools/)
[![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/25ce4b64d5b9cda177203366146f5bf0/raw/alf-tools-coverage.json)](https://github.com/instadeepai/alf/tree/main/tools)
[![Docs](https://img.shields.io/badge/docs-instadeepai.github.io%2Falf-blue)](https://instadeepai.github.io/alf/)

**Ready-to-use models, datasets, and acquisition functions for ALF (Active Learning Framework).**

`alf-tools` builds on [alf-core](https://github.com/instadeepai/alf/blob/main/core/README.md)
to give you everything needed to run active-learning experiments out of the box — example
datasets (GFP, ProteinGym, FLIP, GuacaMol), models (CNN, Gaussian Process, ESM-2, Chemprop),
acquisition functions, and search strategies. Use it for quick-start and prototyping; reach for
`alf-core` alone when you want the lightweight framework with no ML-framework dependencies.

<div align="center">
  <img src="https://raw.githubusercontent.com/instadeepai/alf/main/docs/imgs/alf_main_figure.png" alt="ALF active-learning loop overview" width="70%">
</div>

## Installation

```bash
pip install alf-tools
```

This installs PyTorch and the core dependencies. Some models need additional dependencies —
see [Optional Extras](#optional-extras) below.

### Optional Extras

Some models require additional dependencies. Append one or more extras to the package name.
Per-model extras (`esm2`, `esmfold`, `chemprop`, `guacamol`) install exactly one model's
dependencies; workflow umbrellas (`protein`, `molecule`) group the extras you are likely to use
together.

```bash
pip install "alf-tools[esm2]"      # ESM-2 protein language model (ESM2Model)
pip install "alf-tools[esmfold]"   # ESMFold structure-prediction oracle (ESMFoldModel)
pip install "alf-tools[chemprop]"  # Chemprop small-molecule MPNN (ChempropModel)
pip install "alf-tools[guacamol]"  # GuacaMol RDKit-based dataset/scoring
pip install "alf-tools[protein]"   # umbrella: esm2 + esmfold
pip install "alf-tools[molecule]"  # umbrella: chemprop + guacamol
```

## Documentation

- **Full documentation:** [instadeepai.github.io/alf](https://instadeepai.github.io/alf/)
- **API reference:** [alf-tools API](https://instadeepai.github.io/alf/api/alf_tools/index.html)
- **Installation guide:** [instadeepai.github.io/alf/installation.html](https://instadeepai.github.io/alf/installation.html)
- **Core framework:** [alf-core](https://github.com/instadeepai/alf/blob/main/core/README.md)
- **Tutorials:** [tutorials/](https://github.com/instadeepai/alf/tree/main/tutorials)

## What's included

`alf-tools` bundles example datasets (GFP, ProteinGym, FLIP, GuacaMol), surrogate and oracle
models (CNN, Gaussian Process, ESM-2, ESMFold, Chemprop, PyRosetta, plus an ensemble wrapper),
acquisition functions (Greedy, UCB, Expected Improvement, Thompson Sampling, CoreSet, and a
BoTorch wrapper), and search strategies. See the
[API reference](https://instadeepai.github.io/alf/api/alf_tools/index.html) for the full
catalogue and configuration options.

## Quick example

```python
from alf_core import (
    BaseDatasetConfig,
    DatasetSearch,
    DesignTask,
    Optimizer,
    Oracle,
    Surrogate,
    TerminalStateLogger,
)
from alf_tools.datasets import GFP
from alf_tools.models import CNNModel
from alf_tools.optimizer.acquisition_functions import Greedy

# Configure and load the dataset
config = BaseDatasetConfig(
    name="gfp",
    modality="sequence",
    seed=42,
    train_ratio=0.1,
    validation_frac=0.5,
    test_ratio=0.2,
    split_type="random",
    problem_type="regression",
)
dataset = GFP(config)
surrogate = Surrogate(model=CNNModel())
optimizer = Optimizer(acquisition_fn=Greedy(), search_fn=DatasetSearch())
oracle = Oracle(scorer=dataset)

# Run active learning
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,
)
```

## Normalisation

Models support input normalisation and output standardisation through their train configs
(`BaseTrainConfig`). `GPModel` enables both by default (`minmax` inputs, standardised outputs);
the other models default to neither. See the
[API reference](https://instadeepai.github.io/alf/api/alf_tools/index.html) for per-model
defaults and configuration.

## Creating custom components

All components subclass the `alf_core` base classes (`BaseDataset`, `BaseModel`,
`AcquisitionFunction`, `BaseSearch`). See the
[how-to guides](https://instadeepai.github.io/alf/how-to/index.html) for step-by-step instructions.

## License

Apache License 2.0 — see [LICENSE](https://github.com/instadeepai/alf/blob/main/LICENSE).
