Delivery exception type

Read carrier scan notes and the customer's message to tell why a delivery didn't happen as planned.

Problem

Carrier exception codes are inconsistent across carriers and driver notes are free text. Logistics teams spend their time decoding scans before they can fix anything.

Goal

Name the exception so address fixes, redelivery, delay updates, damage claims and traces each start in the right place.

Input / state

The latest carrier events and, when there is one, the customer's message.

carrier_events: Recent tracking events with the driver's notes, as returned by the carrier.
customer_message: The customer's message, if they contacted you.

Decision question

ChoiceQuestion key exception_type

What is the main reason this delivery did not complete as planned?

Options

address_problemThe address is incomplete, wrong or couldn't be found.
recipient_unavailableThe driver reached the address but nobody could receive the parcel.
damaged_in_transitThe carrier reports the parcel or its contents damaged.
delayed_in_networkThe parcel is moving but behind schedule, for example a missed connection or weather.
lost_or_no_scanNo movement for an unusually long time, or the carrier cannot locate the parcel.
customs_holdHeld at customs, for example waiting for documents or duties.

Allowed outcomes

Decided in your code from the answer and its confidence. Thresholds are yours to set and test.

Address problemChoice is address_problem and confidence meets your threshold.
Recipient unavailableChoice is recipient_unavailable and confidence meets your threshold.
Damaged in transitChoice is damaged_in_transit and confidence meets your threshold.
Delayed in networkChoice is delayed_in_network and confidence meets your threshold.
Lost or no scanChoice is lost_or_no_scan and confidence meets your threshold.
Customs holdChoice is customs_hold and confidence meets your threshold.
Logistics agentConfidence is below your threshold: probability is spread across options.

Example scenarios

Predefined demonstrations. No model is called; the outcome shown is an illustrative judgment.

Example state

{
  "carrier_events": [
    {
      "note": "Address incomplete - no flat number, building has 40 units",
      "status": "exception"
    }
  ],
  "customer_message": ""
}

Outcome

Illustrative

Address problem

Choice is address_problem and confidence meets your threshold.

Why

The driver couldn't find the right unit.

Better together with

Complementary classifiers, and what each one adds here.

Address completenessChoice
Address exceptions continue with a check of what exactly is missing.
Combined inDelivery exception routing
Delivery instruction feasibilityNoul
When nobody was home, check whether the customer's instruction for the next attempt can be followed.
Combined inDelivery exception routing
Shipment delay impactScore
Delays and customs holds need an impact read before you decide how proactively to contact the customer.
Combined inDelivery exception routing
Order issue typeChoice
The customer's own description of the problem complements the carrier's view.

Used in chains

Delivery exception routingStep 1 of 4

Sources

Primary documentation this classifier builds on. Scenarios on this page are illustrative, not taken from production use.

SourcedTypeSafe docs · Documentation
System One
Defines the Choice, Score and Noul primitives and walks through a refund request built from a state, independent questions and deterministic checks in code.
SourcedTypeSafe docs · Documentation
Model jaggedness
Lists known failure modes, including literal reading, arithmetic, date comparison, option order and adversarial content.
SourcedTypeSafe docs · Pattern
Routing by confidence
Checks confidence first and sends spread-out answers to a person, then routes the rest on the score.

Using it well

Compute how long the parcel has been without a scan in code and pass the number of days; don't ask the model to compare timestamps.
Normalize events from different carriers to one shape before sending them, so the same exception reads the same way.
Carrier text is external input. If it feeds an assistant later, keep it marked as data.

Request definition

POST https://api.typesafe.ai/v1/systemone

{
  "model": "jev-latest",
  "state": {
    "carrier_events": "<carrier_events>",
    "customer_message": "<customer_message>"
  },
  "questions": {
    "exception_type": {
      "type": "choice",
      "instructions": "What is the main reason this delivery did not complete as planned?",
      "criteria": {
        "address_problem": "The address is incomplete, wrong or couldn't be found.",
        "recipient_unavailable": "The driver reached the address but nobody could receive the parcel.",
        "damaged_in_transit": "The carrier reports the parcel or its contents damaged.",
        "delayed_in_network": "The parcel is moving but behind schedule, for example a missed connection or weather.",
        "lost_or_no_scan": "No movement for an unusually long time, or the carrier cannot locate the parcel.",
        "customs_hold": "Held at customs, for example waiting for documents or duties."
      }
    }
  }
}

Request shape from the System One API reference; a Kev server accepts the same body. Replace the placeholder state with your data. Requests need your own API key or server.

Version History

v1Current Versionabout 8 hours ago@f

Initial version