Packvium for Python

Framework-independent Python library for deterministic packing of rigid cuboids into rectangular containers.

Supports Python 3.9–3.14. Python 3.9 is retained as a legacy-compatibility runtime; production deployments should use a version still supported upstream.

pip install packvium

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"))],
)

Quotes, policy and catalog versions

packvium.commerce prices a shipment, decides an eligibility question, and reports which catalog version a reference resolves to. Three deterministic functions over one JSON document you supply — no clock, no network, no hidden state:

from packvium.commerce import quote

document = {"tariffs": [{
    "carrier_id": "acme", "service_id": "ground",
    "versions": [{
        "effective_at": 0,
        "dimensional_weight_divisor": 5000,          # mm^3 per gram of dimensional weight
        "cost_per_dimensional_kg_minor": {"zone-a": 450},   # cents per billed kilogram
        "minimum_charge_minor": 900,
        "fuel_surcharge_permille": 120,              # 120 = 12.0%
        "accessorials": [{"accessorial_id": "liftgate", "flat_charge_minor": 250}],
    }],
}]}

result = quote(document, {
    "carrier_id": "acme", "service_id": "ground",
    "tariff_version": 1,            # or "as_of": <instant>, never both
    "zone": "zone-a", "actual_weight_g": 1200, "volume_mm3": 6_000_000,
    "requested_accessorials": ["liftgate"],
})
result["quote"]["total_minor"]      # 1258, itemised alongside in the same object

evaluate_policy(document, request) returns the decision and the rule id and version that made it. catalog_version_info(document, request) reports which version a pin or an as_of resolves to, what it contains, and whether it was a rollback.

A runnable walk-through of all three, including both kinds of failure, is in examples/commerce.py.

Two kinds of failure, and they are not interchangeable:

• a malformed document or request is your bug and is raised/thrown;
• a request the model simply cannot answer — no tariff effective at that instant, no rate for that zone — is a successful call returning "status": "rejected" with a code from a closed set and structured fields naming what was missing.

The full contract — document format, every result shape, all ten rejection codes, complexity and limitations — is docs/COMMERCE-API.md in the suite repository.

Highlights:

• exact integer geometry for millimetres and fractional inches;
• immutable requests and results;
• Grid, Layer, Extreme Point, Maximal Space and bounded exact-small solvers;
• weight, rotation, clearance, support, top-load, floor-only, compatibility and obstacle constraints;
• deterministic multi-start search and top-K alternatives;
• independent post-solve validation;
• JSON/CLI API and nested packing;
• stable extension protocols for custom constraints, item ordering and solvers.

The complete architecture, algorithms, complexity, conformance and publishing documentation is intentionally stored in the parent packvium-suite/docs directory, outside this package repository.