alf-core

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.

Installation

pip install alf-core

Quick start

alf-core is the framework layer: you supply your own BaseDataset and BaseModel subclasses (or install alf-tools for ready-made ones), then wire them into the active-learning loop.

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.

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
• API reference: every class and method
• Glossary: terms and benchmark metrics
• Tutorials: tutorials/
• Full documentation: instadeepai.github.io/alf
• Ready-to-use tools: alf-tools

License

Apache License 2.0 — see LICENSE.