⚠️ Please note: this is a beta release, the main release will follow shortly.

ALF is an active learning framework for optimising expensive, high-dimensional search spaces in computational science — settings where every label costs a wet-lab experiment, a physical measurement, or a long simulation, and the candidate space (protein sequences, small molecules, materials) is far too large to screen exhaustively. It runs the full loop of search, surrogate modelling, and acquisition through modular components you can swap independently.

Why ALF?

In scientific discovery, the bottleneck is rarely compute—it's the experiment. Each label costs a wet-lab assay, a simulation, or a measurement, and you can only afford a handful of rounds. ALF runs the full active-learning loop for you: train a surrogate on what you've measured, use an acquisition function to select the most informative next batch, score it, and repeat—all with modular, swappable components so you can change any one part without rewriting the rest.

→ Full motivation and design rationale

📖 Documentation

https://instadeepai.github.io/alf/ — full docs including API reference, tutorials, and how-to guides.

• 📥 Installation Guide
• 🛠️ Contributing Guide

📦 Package Architecture

ALF is split into two packages:

alf-core — Lightweight framework with base classes, core data structures, and minimal dependencies (numpy, pandas, scipy). No ML framework dependencies. It is standalone and domain-agnostic — see the ALF Core Quickstart for an example. Use this for custom implementations or when integrating into existing systems.

alf-tools — Ready-to-use datasets, models, and acquisition functions with heavier dependencies (PyTorch). Depends on alf-core. Use this for quick-start and prototyping.

📦 Installation

# Core package only (no PyTorch required)
pip install alf-core

# Tools package (includes PyTorch, models, and datasets)
pip install alf-tools

For GPU support, optional extras (ESM2, Chemprop), and development setup, see the Installation Guide.

🚀 Quick Start

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

# A dataset wraps your candidates and their known labels. A small train_ratio
# leaves a large candidate pool for the active-learning loop to acquire from.
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)

# The surrogate is a cheap probabilistic model trained on observed labels
surrogate = Surrogate(model=CNNModel())

# The optimizer picks the next batch: acquisition function scores candidates,
# search function selects from them
optimizer = Optimizer(acquisition_fn=Greedy(), search_fn=DatasetSearch())

# The oracle scores selected candidates (here, it queries the held-out dataset)
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,
)

New to active learning? Start with Why ALF?, then work through the Tutorials.

🐳 Run with Docker

Prefer a zero-setup environment? The repository ships a Dockerfile that bundles the tutorials and benchmark examples with CPU PyTorch:

docker build -t alf .
docker run --rm -p 8888:8888 alf   # JupyterLab with the tutorials at http://localhost:8888

See the Run with Docker guide for benchmark examples, volume mounts, and GPU support.

🎓 Tutorials

Start with an experiment

• Offline Design Tutorial — end-to-end active learning loop with labels from a held-out pool. The best entry point.
• Online Design Tutorial — the same loop, with labels from a live scorer.

Go deeper on models

• GP Tutorial — Gaussian Process surrogate and kernel cheat-sheet
• CNN Tutorial — convolutional sequence surrogate
• Ensemble Tutorial — seed ensembles, MC dropout, and combined ensembles for uncertainty-aware prediction
• ESM-2 Tutorial — protein language model as surrogate or zero-shot scorer
• Chemprop MPNN Tutorial — active learning for small molecules with SMILES inputs

Lightweight (alf-core only)

• ALF Core Quickstart — active learning on MNIST digit classification, with a softmax-regression surrogate and uncertainty-sampling acquisition function implemented from scratch with numpy/scipy

Extend ALF

• Models — create custom models for oracle/surrogate/generator roles
• Datasets — add custom data sources
• Search Functions — implement custom search strategies
• Acquisition Functions — create custom acquisition strategies

🛠️ Development

git clone git@github.com:instadeepai/alf.git
cd alf
uv sync

uv run pytest                                         # run all tests
uv run pytest --cov=alf_core --cov-report term-missing  # with coverage
uv run pre-commit install                             # install pre-commit hooks

See the Installation Guide for GPU configuration and optional extras.

🤝 Contributing

Read our Contributing Guide for development guidelines and the PR process. For questions or discussions, open an issue.

📁 Project Structure

alf/
├── core/                  # alf-core package (base classes, tasks, utilities)
├── tools/                 # alf-tools package (models, datasets, acquisition functions)
├── tutorials/             # Tutorial notebooks
└── docs/                  # Documentation source

See core/README.md and tools/README.md for package-level details.

📚 Building Documentation Locally

uv sync --group docs
uv run sphinx-build -b html docs/source docs/build/html
open docs/build/html/index.html  # macOS

📄 License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.