Metadata-Version: 2.4
Name: packvium
Version: 0.1.1
Summary: Deterministic, extensible 3D cartonization and rectangular bin-packing library
Author: Packvium contributors
License-Expression: MIT
Keywords: 3d-bin-packing,cartonization,packaging,container-loading
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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

```bash
pip install packvium
```

```python
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:

```python
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](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.
