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:
- It transfers knowledge across different optimization tasks
- It adapts immediately when the problem changes (e.g., more compute, different dataset)
- 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
Metadata
Release files for theorist 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| theorist-0.1.0.tar.gz | 21.4 kB | Without provenance | Details for theorist-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| theorist-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for theorist-0.1.0-py3-none-any.whl |
Total release size: 40.3 kB
Release files / theorist-0.1.0.tar.gz
| Download URL | theorist-0.1.0.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ac48fce7d4d26a1a7bf05ea3d16cfc3e888764cb2eb9156cabfe14022bf03f1
|
|
BLAKE2b-256 checksum How to use checksums |
396dbc95354d4c082fc6eb73ec8c0aae33ccde07975c5031ba3734d3d994e0a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / theorist-0.1.0-py3-none-any.whl
| Download URL | theorist-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e92d628bf43f02de7ac83ab30ea84bb840da2d4db1e0f577544fb8c8ce193cab
|
|
BLAKE2b-256 checksum How to use checksums |
23b906dbe686a52f677318c34a2e72d03209fc31d81228cd6b0e5b1782218cd1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for theorist 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.