Packvium for Python

Deterministic 3D cartonization and rectangular bin packing. Pure Python, no runtime dependencies, exact integer geometry.

Full documentation, the constraint reference and benchmarks live at packvium.com.

Version 1.2.0 — the public API is frozen. Field names, status codes and the objective vector do not change without a major version, so any 1.x is a safe upgrade from any earlier 1.x. Read docs/GUARANTEES.md before relying on a result.

pip install packvium

Quick start

from packvium import Container, Dimensions, Item, Packer, PackingConfig

result = Packer(PackingConfig.balanced()).pack(
    items=[Item.create("book", Dimensions.mm("210", "140", "30"), quantity=4)],
    containers=[Container.create("box", Dimensions.mm("400", "300", "250"))],
)

print(result.status)                      # feasible
for container in result.containers:
    for placement in container.placements:
        print(placement.item_id, placement.position, placement.orientation)

Fractional inches are exact, not approximated:

Dimensions.inches("12 3/8", "8 1/2", "3/4")

There is also a CLI that reads a JSON request on standard input:

echo '{"items":[{"id":"box","quantity":8,"dimensions":{"length":"50","width":"50","height":"50"}}],
       "containers":[{"id":"carton","inner_dimensions":{"length":"100","width":"100","height":"100"}}]}' \
  | python -m packvium

Examples

Runnable, in examples/. Each one is a single file you can read top to bottom and execute without a project around it. Every one of them is executed by the test suite on each release, so none of them can quietly stop working.

New here? Read basic.py, then objectives.py — between them they cover what most callers need. units.py and serialization.py explain the two design choices that surprise people. extensions.py is last on purpose: reach for it only after the fields in constraints.py have failed you.

PYTHONPATH=src python3 examples/objectives.py

What it does

• Exact arithmetic. Length is measured in ticks of 1/16000 mm and weight in 1/8 µg. No coordinate is ever a float, so no placement decision depends on rounding.
• Real constraints. Weight and payload limits, permitted rotations, keep-upright, floor-only, non-stackable, top-load limits, minimum support ratio, tag incompatibility, clearance and rectangular obstacles.
• A solver portfolio, not one algorithm. Regular-grid, layer, extreme-point, maximal-space and bounded exact search, selected by problem shape and profile.
• Answers you can check. Every solution is re-validated by logic independent of the search. Unplaced items come back with a reason code, not silently missing.
• Deterministic. The same input and seed produce the same result, always.
• Multi-container and nested. Split across containers, or pack containers into containers.
• Extensible. Register your own constraints, item orderings, candidate scorers, container selectors or complete solvers.
• Work orders, not just coordinates. packvium.execution turns a validated result into a plan: solver facts kept apart from the text that cites them, an injected loading order or an honest unavailable, and a canonical form four engines emit byte for byte. packvium.locks lets an operator pin a placement and get a second plan beside the approved one — never an edit of it, and never a placement the engine would refuse.
• Decide before you publish. packvium.simulation and packvium.recommendations compare two catalog scenarios order by order and propose a change only when the paired cohort supports it; packvium.holdout replays that proposal against history it has not seen. Python-only, and supported but not yet signature-frozen — see PUBLIC-API.md.

Documentation

Requirements

Python 3.9 or newer. No dependencies.

The Packvium family

One request and result contract, implemented independently in four engines (Rust, Python, PHP, JavaScript) and held to identical placements on a shared fixture set. Pick the package for your stack; mixing them in one system is safe.

Documentation, the constraint reference and the benchmarks are at packvium.com.

Contributing

See CONTRIBUTING.md. Security reports go through the process in SECURITY.md, not public issues.

License

MIT. See LICENSE.