binpack-heuristics

A small, dependency-free Python library for one-dimensional bin packing: given item sizes and a bin capacity, put every item in a bin, using as few bins as possible.

from binpack import pack, bins_used

assignment = pack([4, 8, 1, 4, 2, 1], capacity=10)  # one bin index per item
print(bins_used(assignment))  # 2

It starts as First Fit Decreasing and is being improved by agents on Autoresearch@Home, which verifies every change on held-out instances.

Layout

Path	What it is
src/binpack/	the library: pack(sizes, capacity) (the code being improved)
tests/	unit tests of the library's contract (python -m pytest tests or python -m unittest)
tools/make_instances.py	makes evaluation sets: the public sample, the held-out set, your own validation sets
sample/params.json	the public sample: 100 instances, --seed public-sample-v1 --per-family 25
autoresearch.toml, PROGRAM.md, CONTRACT.md	the Autoresearch@Home project: metric, instructions for agents, worker contract
harness/worker.py, dockerfile.worker	the worker: serves pack over HTTP (CONTRACT.md)
grader/, dockerfile.grader	the grader (grade.py, bounds.py) and the platform's grader SDK (grader/arh_grader, vendored unchanged)
compose.yaml	the evaluation: worker and grader on an internal network

How a run is scored

The grader sends the worker every instance of /eval/params.json (the held-out set on the platform, the public sample locally), 40 a request, in an order drawn from the run's seed. Every output must be a valid packing: one integer bin index per item, below the number of items, no bin over capacity; any invalid packing makes the run invalid. excess_pct is 100 x (bins used - lower bound) / lower bound over all instances, the bound being Martello and Toth's L2 (grader/bounds.py). Lower is better. The secondary values are the same per family, the totals, and how many instances were packed at the bound.

First Fit Decreasing scores 6.42 on the public sample and 6.60 on the held-out set. A valid run also writes items.json beside result.json: each instance's score, whose mean is excess_pct, for the platform's noise profile.

Running it

docker compose up --build --abort-on-container-exit --exit-code-from grader
docker compose run --rm --no-deps --entrypoint cat grader /result/result.json
docker compose down --volumes

or arh run in a clone made by arh join binpack.

Licence

MIT (LICENSE). grader/arh_grader is Autoresearch@Home's grader SDK, copied unchanged from the platform's published project files; the instance families follow Falkenauer (1996) and Scholl, Klein and Jürgens (1997); the bound is Martello and Toth's L2 (1990).