leitwerk 0.7.3

Evolutionary strategy with JSON checkpoints and schema reconciliation.

Leitwerk

Tune your magic numbers with stochastic optimization.

leitwerk is a schema-based evolutionary optimizer for long-running training loops.

It offers:

• parameters as plain dataclasses in your code
• JSON checkpoints you can inspect and resume
• schema reconciliation, so you can keep developing and retain progress

Links

• Documentation
• Integration Guide
• API Reference

Installation

Requires: Python >=3.11,<3.14

pip install leitwerk

For a local development setup with testing, linting and burnysc2:

pip install -e .[dev,docs,benchmark]

The StarCraft II example also requires the game itself or Docker to be installed.

Minimal Example

At base level, leitwerk is a sequential ask/tell function maximizer:

from leitwerk import Optimizer, Parameter

opt = Optimizer({"x": Parameter()})
for _ in range(100):
    x = opt.ask()["x"]
    fx = -(x - 1)**2
    opt.tell(fx)

>>> opt.mean
{'x': 1.0007710964577097}

Everything else is wrapping for easier representation, bounds, typing and persistence.

Example - StarCraft II Bot

For a real training loop showcasing most features, see https://raw.githubusercontent.com/phantomsc2/leitwerk/main/examples/train_sc2_bot.py:

• a simple worker rush bot with two parameters
• runs games continually against the built-in AI
• scores each game using win/loss and a combat heuristic
• persists state with OptimizerSession and plot results

Run it directly if you want to observe the games:

python examples/train_sc2_bot.py

Alternatively, use the headless Docker setup:

cd examples
docker compose up --build

On the first run, this will download and unpack the SC2 Linux installation inside the container. Afterward, it will run significantly faster than the rendered game on the host.

Training Results

The example saves progress in examples/data after each game:

• params.json: optimizer state
• plot.png: graphs showing parameter samples and results with a moving average
• history.json: helper file

Developer Commands

• make fix: auto-format
• make check: lint and test
• make docs: build docs
• make docs-serve: serve docs locally