theorist

Prediction-error optimization for Python. One file. Zero dependencies.

Most optimization loops try things and keep what works. Theorist does one thing differently: it guesses first. The prediction error is the learning signal.

predict → run → surprise → learn → transfer

What is Theorist?

A first-principles approach to optimization. Instead of blindly searching, Theorist forces a prediction before each experiment and learns from the error. It builds a theory of why things work,not just what works,and transfers that understanding across tasks.

• No dependencies, pure Python, single file
• No LLM or API keys required, the prediction-error loop runs locally
• Cross-domain transfer, what it learns on one task makes the next task faster
• Drop-in replacement for random search or grid search with better sample efficiency

How is this different from Optuna / Ray Tune / Bayesian optimization?

Those tools model what works. Theorist models why it works, by forcing a prediction before each experiment and learning from the error. This means:

1. It transfers knowledge across different optimization tasks
2. It adapts immediately when the problem changes (e.g., more compute, different dataset)
3. It gets better at predicting, not just searching,understanding instead of memorizing

In our experiments, this approach adapted to a 5x compute shift on the first try. Traditional search had to start over. The same pattern that makes autonomous AI agents fragile,optimizing without understanding,is what makes most hyperparameter tools plateau.

Install

pip install theorist

Or just copy theorist.py into your project. It's one file, ~170 lines of logic.

Quick start

import theorist

@theorist.experiment(
    search_space={"lr": [1e-4, 1e-3, 1e-2], "layers": [2, 4, 8]},
    metric="val_loss",
    minimize=True,
)
def train(config):
    return {"val_loss": run_training(**config)}

results = train.optimize(n=20)

Brain persists at ~/.theorist/. Second task starts smarter.

Cross-domain transfer

@theorist.experiment(search_space={...}, metric="loss", domain="training")
def task1(config): ...

@theorist.experiment(search_space={...}, metric="loss", domain="inference")
def task2(config): ...

task1.optimize(n=20)
task2.optimize(n=20)  # starts smarter,transfers what it learned

Compare vs random search

from theorist import compare
compare(fn=train, space={...}, n=20, metric="loss")

Brain

from theorist import Brain
brain = Brain()
print(brain.summary())
brain.reset()

Origin

This is the SDK version of the prediction-error loop from epistemic-autoresearch.

251 experiments across three autonomous agent types (blind search, reflection, prediction-error). The predicting agent adapted to a 5x compute shift on its first try. The reflecting agent took 7 tries. The searching agent never caught up.

The core insight: an autonomous agent that predicts before it acts builds real understanding. One that only reacts builds nothing. This is why most AI agents are fragile,they optimize without reasoning from first principles.

Theorist packages that loop so any optimization problem can use it.

Research

• Paper + experiments: epistemic-autoresearch
• Previous study: barcaui-predicted-karpathy

License

MIT,Johan David Bonilla