Shipment Delay Prediction

Predict whether a shipment will arrive late, and how late, so operations can intervene before a delay reaches the customer. This example makes two predictions for each shipment: a yes or no classification of whether it will be delayed, and a numeric estimate of the delay in days. Kumo Engine learns both from each shipment’s own details and from the order, customer, and handling history connected to it in the graph.

Data and relationships

The example assumes a prepared Kumo Engine graph, a matching snapshot, and these tables:

Table	Required columns	Purpose
`shipments`	`shipment_id`, `order_id`, `ship_date`, `delay_duration`	The shipments to score. `delay_duration` records how many days late a past shipment arrived, where `0` means it was on time.
`orders`	`order_id` as the primary key, plus `order_date`	The order each shipment fulfills, for order context and timing.
`customers`	`customer_id` as the primary key	The customer each order belongs to.
`shipment_events`	`event_id`, `shipment_id`, `event_date`, `event_type`	Handling events recorded for a shipment, such as pickup and transit scans.

Connect shipments.order_id to orders.order_id, orders.customer_id to customers.customer_id, and shipment_events.shipment_id to shipments.shipment_id. Mark ship_date as the time column of the shipments table and shipment_id as its primary key, so each prediction is anchored at the moment the shipment leaves and uses only earlier information. Mark order_date and event_date as the time columns of their tables. delay_duration is the value each query predicts, so it is the label rather than a feature.

Predict whether a shipment will be delayed

This query classifies each shipment as delayed or on time. The target shipments.delay_duration > 0 turns the recorded delay into a yes or no label, and FOR EACH shipments.shipment_id produces one prediction per shipment. Because the shipments table is anchored at ship_date, the model learns from the order, customer, and handling history that exists before the shipment departs.

from kumo.engine import PredictiveQuery
query_text = (
    "PREDICT shipments.delay_duration > 0 "
    "FOR EACH shipments.shipment_id"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # binary_classification

Predict how long the delay will be

When operations needs to reschedule or reset a delivery estimate, a yes or no answer is not enough. This query predicts the delay itself as a number of days. It uses the same entity and anchor, but the target is the raw shipments.delay_duration value, so the task is a regression forecast rather than a classification.

query_text = (
    "PREDICT shipments.delay_duration "
    "FOR EACH shipments.shipment_id"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # regression

Reading the predictions

The classification query returns a probability that each shipment will be delayed, which lets operations rank shipments by risk and act on the ones most likely to arrive late. The regression query returns an estimated number of days late, which supports concrete choices such as revising a promised delivery date or expediting a carrier. A predicted delay of zero means the model expects the shipment to arrive on time.

Both predictions are estimates from past shipment behavior, not guarantees, and both are anchored at the shipment’s departure, so they use only what is known when the shipment leaves. Refresh them as new shipments and handling events arrive so each decision reflects the latest history.