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.4.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

Errors

A request that no engine may answer raises packvium.InvalidRequestError, a ValueError, before anything is solved. It names the problem instead of describing it:

from packvium import InvalidRequestError, pack_from_dict

try:
    result = pack_from_dict(request)
except InvalidRequestError as error:
    error.code     # "invalid_request"
    error.reason   # "below_minimum"
    error.field    # "/items/0/quantity" -- a JSON Pointer into your request
    str(error)     # "invalid_request: /items/0/quantity: must be at least 1"

reason is one of missing_field, wrong_type, below_minimum, above_maximum, negative_measure, invalid_unit, duplicate_id, not_allowed or invalid_value. FixedPlacementError is a subclass, with code invalid_fixed_placement and reason malformed or cannot_hold. The message is the same in every Packvium engine. Branch on reason and field; show the message to a person. A request that is valid but does not fit completely is not an error: the result lists what was left out, and why, in unpacked_items.

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.
• Artifacts a warehouse system can use without an engine. packvium.artifacts wraps the plan with geometry, display values and provenance, including the request itself and an honest replay level. packvium.artifact_exports writes it as RFC 8785 JSON, CSV or a self-contained HTML work order, byte for byte what the other engines write.
• Items already in place, and replanning around them. fixed_placements pins items to known positions before the solve: they keep their place, carry weight and support, and come back marked fixed: true. packvium.revisions records what changed on the dock — a missing item, a substituted container, a lock, a verification — as an append-only chain linked by SHA-256, and derives the request the next plan solves. packvium.revision_outcomes feeds those events to the historical evaluation (Python only).
• 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.