Metadata-Version: 2.4
Name: AlphaPFN
Version: 0.0.1
Summary: Fast Entropy Search via In-Context Learning (PFN-based amortized acquisition functions for Bayesian Optimization)
Project-URL: Homepage, https://github.com/automl/AlphaPFN
Project-URL: Repository, https://github.com/automl/AlphaPFN
Project-URL: Issues, https://github.com/automl/AlphaPFN/issues
Project-URL: Paper, https://openreview.net/forum?id=7Oonij8oLU
Author: Herilalaina Rakotoarison, Steven Adriaensen, Tom Viering, Carl Hvarfner, Samuel Müller, Frank Hutter, Eytan Bakshy
Maintainer-email: Herilalaina Rakotoarison <rkt.herilalaina@gmail.com>
License: MIT License
        
        Copyright (c) 2026 AutoML-Freiburg-Hannover
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: acquisition-function,amortized-inference,bayesian-optimization,entropy-search,in-context-learning,pfn,prior-fitted-networks,pytorch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: einops
Requires-Dist: gpytorch>=1.5.0
Requires-Dist: networkx
Requires-Dist: numpy<2.0,>=1.21.2
Requires-Dist: packaging
Requires-Dist: platformdirs
Requires-Dist: safetensors
Requires-Dist: torch>=1.9.0
Requires-Dist: typing-extensions
Provides-Extra: botorch
Requires-Dist: botorch>=0.15.0; extra == 'botorch'
Description-Content-Type: text/markdown

# $\alpha$-PFN: Fast Entropy Search via In-Context Learning

[![PyPI version](https://img.shields.io/pypi/v/AlphaPFN.svg)](https://pypi.org/project/AlphaPFN/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Paper](https://img.shields.io/badge/Paper-OpenReview-b31b1b.svg)](https://openreview.net/forum?id=7Oonij8oLU)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/automl/AlphaPFN/blob/main/examples/quickstart.ipynb)

**$\alpha$-PFN** is a Prior-Fitted Network that amortizes information-theoretic acquisition functions. Supported acquisition functions: Predictive Entropy Search (PES), Max-value Entropy Search (MES), and Joint Entropy Search (JES). 

<p align="center">
  <img src="images/hero.gif" alt="Traditional GP-based Entropy Search samples optima via RFF and averages conditional entropies over N MC samples; α-PFN approximates the same acquisition in a single transformer forward pass.">
</p>

> To reproduce our ICML 2026 paper experiments, see branch
> [`icml2026`](https://github.com/automl/AlphaPFN/tree/icml2026).

## Install

```bash
pip install AlphaPFN
```

Or from source:

```bash
git clone https://github.com/automl/AlphaPFN
cd AlphaPFN
uv sync
```

Pretrained checkpoints (~20 MB) download automatically on the first `from_pretrained` call and cache under `~/.cache/alphapfn/`.

## Quick start

A self-contained 6D BO loop on Hartmann, using `botorch.optim.optimize_acqf`. Requires the `[botorch]` extra — `pip install "AlphaPFN[botorch]"`:

```python
import torch
from botorch.optim import optimize_acqf
from botorch.test_functions import Hartmann
from alphapfn import AlphaPFN

# 1. Objective on the unit cube (α-PFN maximizes — `negate=True` flips Hartmann's sign).
hartmann = Hartmann(dim=6, negate=True)

# 2. Initial design.
torch.manual_seed(0)
d, n_init, num_steps = 6, 6, 30
X = torch.rand(n_init, d, dtype=torch.double)
y = hartmann(X)
bounds = torch.stack([torch.zeros(d), torch.ones(d)]).double()

# 3. Load the pretrained acquisition; checkpoints download on first call.
acqf = AlphaPFN.from_pretrained(acquisition="JES")

# 4. BO loop.
for step in range(num_steps):
    acqf.fit(X, y)                            # fit() standardizes y internally
    X_next, _ = optimize_acqf(acqf, bounds=bounds, q=1,
                              num_restarts=10, raw_samples=128)
    y_next = hartmann(X_next.squeeze(0))
    X = torch.cat([X, X_next.detach().double()])
    y = torch.cat([y, y_next.detach().double().reshape(1)])
    print(f"step {step+1:>2}: best so far = {y.max().item():.4f}")
```

Runnable version: [`examples/bo_with_optimize_acqf.py`](examples/bo_with_optimize_acqf.py)
or open the [Colab notebook](https://colab.research.google.com/github/automl/AlphaPFN/blob/main/examples/quickstart.ipynb).

## API

```python
AlphaPFN.from_pretrained(
    acquisition: str | None = None,   # "PES" (default), "MES", or "JES"
    version: str = "v1",
    *,
    load_base_model: bool = False,
    ucb_beta: float = 2.0,
    strict: bool = True,              # pass strict=False to skip input checks
)
```

Before fitting, prepare your data so that:
- **You are maximizing.** To minimize instead, negate your objective.
  This is NOT checked, so forgetting it silently gives wrong results.
- **Each input feature lies in `[0, 1]`.** Rescale your search space accordingly.

`fit()` standardizes targets internally (`standardize_y=True` by default) — pass raw $y$. Pass `standardize_y=False` if you have already standardized. `strict=True` (default) validates the unit-cube contract on every `fit`/`forward`; pass `strict=False` to skip.

## Cite

```bibtex
@inproceedings{
  rakotoarison2026alphapfn,
  title={{$\alpha$}-PFN: Fast Entropy Search via In-Context Learning},
  author={Rakotoarison, Herilalaina and Adriaensen, Steven and Viering, Tom and Hvarfner, Carl and M{\"u}ller, Samuel and Hutter, Frank and Bakshy, Eytan},
  booktitle={Forty-third International Conference on Machine Learning},
  year={2026},
  url={https://openreview.net/forum?id=7Oonij8oLU}
}
```
