Merge pull request #6 from fleetbase/feature/orchestrator-vehicle-packing-reference

Document orchestrator vehicle packing options

Author: roncodes

postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/VROOM Capacity Only Allocation.example.yaml

@@ -16,9 +16,11 @@ request:
         "options": {
           "engine": "vroom",
           "allocation_strategy": "capacity_only",
+          "vehicle_packing": "minimize_vehicles",
+          "vehicle_fixed_cost": 100000,
           "respect_capacity": true,
           "respect_skills": true,
-          "balance_workload": true
+          "balance_workload": false
         }
       }
 response:
@@ -42,9 +44,9 @@ response:
           },
           {
             "order_id": "order_cold_02",
-            "vehicle_id": "vehicle_cold_van_01",
+            "vehicle_id": "vehicle_capacity_truck_01",
             "driver_id": null,
-            "sequence": 1,
+            "sequence": 2,
             "arrival": 0,
             "duration": 0,
             "distance": 0
@@ -54,7 +56,9 @@ response:
         "summary": {
           "engine": "vroom",
           "allocation_strategy": "capacity_only",
-          "routes": 2,
+          "vehicle_packing": "minimize_vehicles",
+          "vehicle_fixed_cost": 100000,
+          "routes": 1,
           "unassigned": 1
         }
       }

postman/collections/Fleetbase API/Orchestrator/.resources/definition.yaml

@@ -4,5 +4,5 @@ description: |-
 
   `POST /orchestrator/run` supports route-aware VROOM allocation, VROOM capacity-only allocation, native Fleetbase capacity-only allocation, driver assignment, route optimization, and multi-phase prior-assignment flows.
 
-  Capacity-only allocation is for clients who need to answer which vehicles can carry selected orders by weight, volume, pallet count, parcel count, skills, and task limits without relying on vehicle GPS positions.
+  Capacity-only allocation is for clients who need to answer which vehicles can carry selected orders by weight, volume, pallet count, parcel count, skills, and task limits without relying on vehicle GPS positions. VROOM capacity-only allocation supports `vehicle_packing` to prefer fewer, fuller vehicles.
 order: 8500

postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.params.yaml

@@ -38,6 +38,12 @@ fields:
       - name: allocation_strategy
         type: string
         description: Allocation strategy for engines that support multiple modes. Use `route_aware` for normal route-aware VROOM allocation, or `capacity_only` with `engine: vroom` to run VROOM with a synthetic matrix and no vehicle locations.
+      - name: vehicle_packing
+        type: string
+        description: VROOM capacity-only packing policy. Use `minimize_vehicles` to prefer filling feasible vehicles before opening another vehicle. Use `balanced` or `none` to omit the vehicle fixed-cost packing bias. Defaults to `minimize_vehicles` when `engine` is `vroom` and `allocation_strategy` is `capacity_only`.
+      - name: vehicle_fixed_cost
+        type: integer
+        description: Optional VROOM fixed cost per vehicle used when `vehicle_packing` is `minimize_vehicles`. Defaults to `100000`.
       - name: geometry
         type: boolean
         description: Whether supported engines should request route geometry.

postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.request.yaml

@@ -4,7 +4,7 @@ description: |-
 
   For normal route-aware VROOM allocation, send `options.engine: "vroom"` and omit `allocation_strategy` or set it to `route_aware`. Vehicles must have usable positions because VROOM will solve against route coordinates.
 
-  For capacity-only VROOM allocation, send `options.engine: "vroom"` and `options.allocation_strategy: "capacity_only"`. This mode answers which vehicles can carry the selected orders by weight, volume, pallets, parcels, skills, and task limits without requiring vehicle locations.
+  For capacity-only VROOM allocation, send `options.engine: "vroom"` and `options.allocation_strategy: "capacity_only"`. This mode answers which vehicles can carry the selected orders by weight, volume, pallets, parcels, skills, and task limits without requiring vehicle locations. Use `options.vehicle_packing: "minimize_vehicles"` to bias VROOM toward filling feasible vehicles before opening another vehicle; use `balanced` or `none` to disable that packing bias.
 
   For Fleetbase's deterministic built-in capacity allocation, send `options.engine: "capacity"`. This native engine is useful as a fallback and debugging baseline for capacity-only allocation without VROOM.