Repository navigation
Releases
Packvium 1.11.0
Bottom gussets and standing pouches, a certified bound for the shipping objectives, one money
ceiling, one measure grammar, and request objects that own their mappings.
Added
deformable_boundary.bottom_gusset_depthandorientation: "standing"on a
gusseted_bag. A bottom gusset lengthens the girth along the bag; a standing pouch is packed
upright in aW x H x Lframe.Containergainsbottom_gusset_depth,bag_orientationand
girth.optimality.lower_boundand the gap undershipping_costandlowest_landed_cost;
validatechecks them.examples/checkout.pyandexamples/fulfilment.py.
Changed
- A
rate_tablepriced above 9007199254740991 minor units at its top bracket, surcharge
included, isinvalid_request/above_maximum. A commerce quote refuses an amount above it
instead of answering, and a revision refuses a stock box priced above it. - Measures are ASCII decimals and fractions only:
1e2,1_00,.5,5.,nanand
non-ASCII digits arewrong_type, as in the other engines. hull_verticesholds at most 32 points; a non-list iswrong_type/must be a liston
the object path too.Container.tag_limitsis read-only,metadatais a copy of the caller's dicts and lists,
aCatalogSnapshotholds tuples and aTariff's mappings are read-only. Pickling,copyand
dataclasses.replacework as before.- The "why unpacked" reason no longer depends on a 2 s clock.
Fixed
- A very long measure took time quadratic in its length (48 s for a 1 MB weight); it is
refused in milliseconds. effort_budgetlimits written as1000.0crashed the solver; they now read as integers.
Packvium 1.10.0
New request fields, a bound under three more objectives, and the intelligence modules join the
frozen API. One stricter refusal: a units key other than length (see Changed).
Added
container.pallet_overhang_limit(OverhangLimit): a load may pass the deck by the
stated length at each end and width at each side. Only the deck bears weight, and the packed
pallet reportsachieved_dimensions.- Gusseted bags:
deformable_boundary.kind: "gusseted_bag"withside_gusset_depth;
Containergainsside_gusset_depthandside_gusset_ticks. - 24 rotations for a
convex_hullitem: 18 signed codes such as-L-W+Hbeside the six;
Rotation.every(),is_signed,is_upright.Rotation.all()andupright()are unchanged. placement_idon every placement, whichfixed_placements, revision events,
FixedPlacementandPlacementLockmay quote;validatechecks it.currencyon the request andrate_table, echoed on the result;PackingRequest,
Packer.packandRateTabletake it.optimality.lower_boundundermaximum_value,open_dimension_heightand
maximum_volume, checked byvalidate.NestedPacker(level_beam_width=K)carries the K best carton sets up a level and lets the
outermost level's score choose; 1 (the default) is the greedy chain, answer for answer.- A made-to-measure box may keep a
void_fill_reserve_ratio. packvium.revisions.stock_cut_boxes.
Changed
unitsrefuses every key butlength:invalid_request/not_allowedat
/units/<key>. 1.9 read a bare weight as grams whateverunits.weightsaid.derive_revisionstocks a box already cut to measure that holds a locked or verified
placement, as<type>@<revision>#<instance>;verify_revision_chainthen needs that
revision's artifact and reportsartifact_requiredwithout it.packvium.simulation,recommendations,outcomes,holdout,paretoandlocksare
signature-frozen, like the packing API.
Fixed
- An explicit rotation list emptied by
keep_uprightis refused atallowed_rotations,
with the same named request error the independent validator checks. - Stocking cut boxes indexes artifact lookups once and reports malformed consumed
machine fields as structuredinvalid_revisionerrors. resolve_with_locksreported a held lock asmissingwhen the re-solve opened the same
containers in another order; a lock fromlocks_from_planis now matched byplacement_id.- An artifact export refuses an integer past
2^53 - 1withnumber_out_of_range
rather than printing it. - A compressible item no longer joins a rigid item's grid lattice.
Packvium 1.9.0
No API change, but admission is stricter: some requests 1.8 accepted are now refused (see the
weight and length limits below). Answers now agree with the other engines where 1.8 found them
apart.
Changed
- Under a clearance a compressible item bears its load on its own footprint, so its crush
check is stricter andvalidatemeasures its own compressed volume. - A weight is at most
2^63 - 1ticks, and so is every item's weight times its quantity plus
the heaviest tare: past it,invalid_request/above_maximum; a weight written as a JSON
number past2^53 - 1isinvalid_valueand must be a string. - Agrees with the other engines where 1.8 did not: nesting under a clearance shares the
items' own overlap and a deep nesting column nests in pairs; a length past2^53 - 1ticks or
a box past10^30cubic ticks isinvalid_request/above_maximum; a side that reads as zero
ticks isinvalid_value/must be positive; an obstacle box outside its container is
invalid_value/lies outside inner_dimensions, each at its own pointer. validatechecks the centroid (centre_of_gravity_unsupported) and the whole stack's load
(top_load_exceeded), an item on several bearers shared by contact area. It no longer
holds that item's whole weight against every bearer, so it accepts some results 1.8 rejected
and names the overloaded bearer.- A plan beam wider than 1 compares every container type, whatever the node limit.
- A JSON request is checked once, not twice, on the same objects the request check built.
Fixed
- A narrow nesting item under a clearance reported a negative
used_volume_ticks3, and a
deep nesting column on the lattice returnedinvalid_result. - An obstacle origin with a wrong type is refused with
invalid_request, rather than
being defaulted or raisingAttributeError; an explicit null origin defaults to zero,
including in additional boxes. Null coordinates default to zero, and null
additional_boxesdefaults to an empty list, as request admission already permits.
Packvium 1.8.0
Results now say how far they can be from the best possible answer, optimal means a proof,
and a mistyped flag is refused instead of guessed.
Added
optimality.lower_boundand the gap under thedefaultandlowest_costobjectives.
packvium.validatechecks them;packvium.result_validation.objective_lower_bound(request)
computes the bound.
Changed
- Attaining the bound, not search exhaustion, sets
optimal(proven_optimal). - An effort budget names a stop: a run that ends on exactly its budget is
complete, and
time_limit_msis no longer split across starts. Checktermination.any_start_truncated. keep_upright,stackable,must_be_on_floorandrequire_placement_coordinatesmust
be booleans."no"or1isinvalid_request/wrong_type;ItemandPackingConfig
refuse it when built.
validaterefuses such a request asMalformedResultnaming the field, and readsnullas
the default.- Faster, identical answers: loading-order check about 30%,
validateabout 20%. - Each measure is parsed once per request: the request check hands its parsed values to
deserialisation, whether a measure is written as a string, a number or a{value, unit}object.
The measured macOS unpackable-request paired wall-time median improved about 8%. - Placement under axle limits is about 4x faster: each candidate's axle check is O(1).
Fixed
solvers=["homogeneous_blocks"]packs underfastandbalanced, and a node-limit
stop is no longer reported astime_limit.units.length: nullandoutput.*_unit: nullmean the default instead of raising
AttributeError;Length.of/Weight.ofrefuse a unit that is not a string asinvalid_unit.validatereadsunits: nullandunits.length: nullas millimetres, as the engines do,
and refuses aunitsthat is not an object, or an unknownunits.length, as acontract
MalformedResultnaming the field.units.weightis not a field and is ignored: put the unit
on each weight.
Packvium 1.7.0
The reference validator ships in the package, quality looks ahead in its block solver, and a
request built from objects is refused as its JSON would be. No request or result field changes.
Added
packvium.validate(request, result),packvium.Issueandpackvium.MalformedResult. The
reference validator over the JSON documents: a list ofIssue(code,detail), empty when
the result is valid, andMalformedResultfor a result of the wrong shape. It shares no code
with the engine it checks.
Changed
- A request built from objects is refused as JSON is. A model constructor that
refuses a value raisesInvalidRequestError(code, reason, field""), a subclass of the
ValueErrorit raised before, and a mistyped value is still aTypeErrortoo.Packer.pack
checks the objects with the JSON rules before solving.FixedPlacementwith
container_instancebelow 1 is now refused bypackasinvalid_fixed_placement, not by its
constructor. - Every schema enum value is refused as
not_allowed. A value outside its list in
allowed_rotations, the output and dimensional-weight units,shape_type,
ground_contact_ruleorconfiguration.solversisinvalid_requestwith reasonnot_allowed
at its JSON Pointer, where some raised aKeyError.ticksas an output unit is now
refused; the schema never listed it. qualitylooks ahead in the block solver. Each round completes its leading
blocks greedily and commits the best, so the answer is never worse than the greedy pass. On our
benchmark 87 of 89 answers improved and none got worse, at 6% more CPU. Under a tight effort
budget the block start can now reporttruncated/effort_limit.fastandbalancedare
unchanged.- A
nesting_heightnot below the item's height is refused asinvalid_valueat its
pointer, and with nooutputblock the result is written inunits.length's schema code.
Fixed
- A tall stack no longer raises
RecursionError: the load rules walk stacks iteratively. - The covered ground-contact rule counts only supporters with positive area, so an item no
longer rests on a box it touches only at an edge. - A quantity past 2^53 − 1 on the object path is refused instead of hanging the solver.
- A route violation names its violators in sorted order.
Packvium 1.6.0
Boxes cut to measure, flat bags, stacking groups and a volume-first objective. A request that
uses none of them keeps its meaning; fast and balanced may now answer better.
Added
packvium.MadeToMeasureandContainer(made_to_measure=...). A container becomes an
on-demand box machine (largest box,minimum,increment, board price and weight per m²);
each packed box is the load's extent rounded up onto the machine grid and priced as cut.
PackedContainer.achieved_dimensionsreports the extent.- Flat bags:
Container(deformable_boundary="flat_bag"). A poly mailer admits a load when
length plus thickness and width plus thickness fit; dimensional weight is billed from the
load's size. - Stacking groups:
Item(stacking_group=..., accepts_stacking_groups=...). Which item
classes may rest directly on which. objective="maximum_volume", which ranks the volume left behind ahead of the piece count.- A warning for items resting on nothing when
minimum_support_ratiois 0
(unsupported_placements: N ...inresult.warnings). No answer changes.
Changed
- An unpacked item names the limit that left it out, the same in every engine.
Where the search used to fall back tono_feasible_placementorsearch_exhausted, an item a
fresh container would take but none is left reportscontainer_inventory_exhausted, and one
that overloads an axle wherever it stands alone reportsaxle_overloaded; both are
inferred. Code that matched the old reason for these cases must match the new one. qualityorders its beam by aconvex_hullitem's own solid, not its box, so
it no longer assumes a second wedge cannot fit when it can.- The container plan counts a
convex_hullitem by its own solid too, so
qualityno longer ranks a plan as if wedges that share a container each needed their own. fastandbalancedadd the block solver as one more start on multi-type loads and keep
its answer only when strictly better.
Fixed
quality's beam refinement searches wide again after a late-type ordering wins; it ran
greedily since 0.1.0.- The exact solver ranks volume first under
maximum_volume.
Packvium 1.5.0
Refusals you can name by type, and the replay promise of a result without building an
artifact. A misspelt configuration key is now refused (see Fixed).
Added
UnsupportedFeatureError,UnknownSolverError,UnknownObjectiveErrorand
PolicyErroronpackvium.pack_from_dictalready raised them; they are now importable
from the package root, so a refusal can be caught by type instead of by message.packvium.artifacts.replay_level(result)—"exact"or"not_guaranteed", the promise an
operational artifact of this result would make, without building the artifact.
Changed
- Faster beam and maximal-space search, same results. The beam skips work on expansions
that cannot beat the best plan so far, and the maximal-space solver stops checking for
containing spaces once none can exist. Measured: beam requests 3–6% faster,maximal_spaces
up to 20% faster on large orders. Every result is byte-identical.
Fixed
- A block answer reports the support each item really has.
HomogeneousBlockSolverwrote
support_ratio1.0 for every item, including those of a block set on a smaller one, which
overhang it. The bottom layer of each block now reports the share of its base that rests on
something. Withminimum_support_ratioabove zero the block solver is no longer tried at
all; its answer was built and then discarded by validation. - A misspelt
configurationkey is refused. A key the request schema does not declare in
configurationor itseffort_budget(profileforsolver_profile,top_kfor
alternatives) was silently ignored, so the request ran on defaults.pack_from_dictnow
raisesInvalidRequestErrorwith reasonnot_allowedand the key's pointer, for example
/configuration/profile. - An unknown
objectiveor access direction is a named request error.pack_from_dict
raisedUnknownObjectiveError/InvalidDirectionErrorwith no reason or field; it now raises
InvalidRequestErrorwith reasonnot_allowedand the value's pointer, like every other
refusal. The typedPackerAPI still raisesUnknownObjectiveError. Lengthrefuses a fractional float, asWeightalready did.Length.mm(0.1)silently
became 1600 ticks andLength.mm(1e-9)became 0; both now raiseTypeError. An integral float
such as100.0is exact and still accepted.- Compressible items are no longer laid out as rigid blocks.
HomogeneousBlockSolvernow
hands them to the general solver, asGridSolverdoes. - Refusal messages match
docs/ERRORS.md, e.g. a fixed placement with unknown keys says it
cannot carrythem.
Packvium 1.4.0
Replanning a job that has already started: items already loaded stay where they are, and every
change is recorded against the plan it changed. A request the schema never allowed is now
refused (see Fixed).
Added
fixed_placementsin a request, andFixedPlacementfor typed requests. Each entry pins
an item type to a container type and instance, at the origin a result reports, in one
orientation. Fixed items keep their place, count toward weight, support and top load, and
come back marked"fixed": true. A fixed set that is not a valid packing on its own raises
FixedPlacementError(invalid_fixed_placement: ...) before any search.packvium.revisions—root_revision,derive_revision,apply_events,
verify_revision_chain,document_digestandcanonical_revision_json. A
packvium-plan-revision/v1chain records what happened on the dock —item_missing,
container_substituted,placement_locked,placement_verified— against the artifact it
changed, linked by SHA-256, and carries the request the next plan solves. Every Packvium
engine computes the same bytes from the same inputs.packvium.revision_outcomes— turns a chain's events into outcome events for the
historical evaluation. Supported, not yet signature-frozen, like the rest of that surface.InvalidRequestError. A malformed request names what is wrong:codeis
invalid_request,reasonone of a closed set (missing_field,wrong_type,
below_minimum,above_maximum,negative_measure,invalid_unit,duplicate_id,
not_allowed,invalid_value),fieldthe JSON Pointer of the bad value, and the message
readsinvalid_request: /items/0/quantity: must be at least 1. It is aValueError, so
existing handlers still catch it, andFixedPlacementErroris its subclass.examples/revisions.py.
Changed
packvium.revisions,FixedPlacementandFixedPlacementErrorare in the frozen API
snapshot.
Fixed
- Limits below their floor are refused. A zero or negative
max_items,max_containers
or effort-budget limit was accepted; each now raisesValueError.
Packvium 1.3.0
Portable operational artifacts: hand a packing result to a WMS, a TMS or a printer that runs
no engine. Nothing breaks 1.2.0.
Added
packvium.artifacts—build_operational_artifact(request, result, loading_orders=)and
canonical_artifact_json(). Onepackvium-operational-artifact/v1document carries the
execution plan, exact geometry, the values a work order shows, and the request that produced
it. Every Packvium engine builds the same bytes from the same result.packvium.artifact_exports—export_json,export_csv(RFC 4180, 18 columns) and
export_work_order_html: a printable work order in one HTML file with no scripts and no
external resources.examples/artifacts.py.
Changed
packvium.execution,packvium.artifactsandpackvium.artifact_exportsare in the frozen
API snapshot, with the same guarantee as the rest of the public surface.canonical_plan_jsonwrites RFC 8785. Every plan the engine produces keeps its 1.2.0
bytes. A float, U+2028 or a key outside the Basic Multilingual Plane is now spelled as the
other engines spell it, and an integer beyond 2^53 − 1 raises instead of being written.- Faster commerce lookups, same answers. A pinned catalog or tariff version resolves
without scanning the history (1000 lookups over 16000 versions: 374 ms → 1.2 ms), a
snapshot's SKU lookup builds its index on first use, andpackvium.paretofinds a two-axis
frontier with one sort instead of comparing every pair.
Packvium 1.2.0
Execution plans, operator locks, and the intelligence API. Nothing breaks 1.1.0.
Added
packvium.execution—build_execution_plan()andcanonical_plan_json()turn a
validated result into a work order: what to lift, why a carton was chosen, what was not
packed. Step order is taken fromloading_ordersor reported as"unavailable".packvium.locks— pin a placement and get a constrained re-solve beside the approved
plan (resolve_with_locks,locks_from_plan). A lock can reserve its slot but never force a
placement the engine would refuse; a lock that cannot be honoured is reported, not raised.packvium.simulation,.recommendations,.outcomes,.holdout,.pareto— compare
two scenarios order by order, propose a carton or rule change only on enough paired
evidence, publish it through an explicit approval, and replay it against held-out history.
Supported, but not yet signature-frozen: pin the version if you rely on exact shapes.pack_from_dict(..., extensions=)— keyword-only, defaults toNone.examples/execution.py,examples/intelligence.py.
Fixed
- The new modules imported on Python 3.10+ only; they now import on 3.9, the declared minimum.
- A
NaNmetric is refused with a named error instead of being ranked Pareto-optimal.