Skip to main content
TRA-01 · Transportation & Logistics

Shipment Exception Copilot

Outcome​

Give the logistics coordinator a grounded working surface for in-transit shipment exceptions: detect the milestone miss, explain the root cause from carrier EDI and telemetry evidence, quantify the delivery-promise impact, and draft the carrier and customer response without leaving the exception record.

Portfolio attributeValue
Primary personaLogistics coordinator
Primary aggregateShipmentException
Cosmos DB containers2
Grounding datatracking, orders, routes, capacity, weather
Development estimateUSD 60-220 monthly dev estimate
Runtime optionsPython FastAPI and C# ASP.NET Core

Productivity hypothesis​

These measures reflect the workflow, evidence, decision boundary, and industry risk for this use case.

Impact typeMeasureConservative internal assumptionCustomer measurement
ProductivityException resolution cycle time10-20% reduction(baseline median exception-resolution minutes - assisted median minutes) / baseline median minutes * 100
Quality or riskFirst-pass resolution correctness5-10 percentage-point improvementassisted percentage meeting the resolution-correctness rubric - baseline percentage

Important: Conservative internal pilot assumptions only; not public benchmarks, commitments, or expected customer results. Validate against a comparable baseline or matched control cohort with mandatory human review.

Rationale: Tracking, orders, routes, capacity, and weather support faster exception triage and more complete proposed resolutions.

Pilot guardrail: Coordinators confirm routing, capacity, priority, weather, and customer commitments before action.

Customer validation plan​

  1. Baseline the current workflow with representative users and tasks.
  2. Run the accelerator on the same task mix with human review retained.
  3. Measure exception resolution cycle time and first-pass resolution correctness with the documented formulas.
  4. Replace internal assumptions with customer-observed results before a business case.

Why Azure Cosmos DB​

This AI solution needs an operational data plane, not only a vector index:

  • Hybrid vector and full-text retrieval combines semantic recall with exact identifiers, codes, names, and domain language.
  • Hierarchical partition keys and metadata predicates keep tenant and domain boundaries in the normal query path.
  • Operational JSON, source chunks, workflow and agent state, feedback, and audit records remain together for low-latency reads and governed writes.
  • Change feed reacts to source and operational updates without polling.
  • Autoscale throughput, configurable consistency, and multi-region distribution support variable demand and enterprise availability.

Domain workflow​

Domain workflow

StageActorInput → outputApproval
1. Milestone deviation detectionChange-feed exception detectorTrackingEvent → ExceptionCasePolicy controlled
2. Root-cause evidence assemblyRetrieval orchestratorExceptionCase → evidenceBundlePolicy controlled
3. Recovery option generationShipment exception copilotevidenceBundle → RecoveryPlanDraftPolicy controlled
4. Coordinator adjudication of recovery optionLogistics coordinatorRecoveryPlanDraft → approvedRecoveryPlanHuman required
5. Carrier tender and consignee notificationLogistics coordinator with TMS connectorapprovedRecoveryPlan → CustomerNotificationHuman required

Technical architecture​

Technical architecture

Cosmos DB data model​

ContainerHierarchical partition keyDocumentsSearch paths
shipmentExceptions/tenantId, /shipmentIdShipment, TrackingEvent, ExceptionCase, RecoveryPlanDraft, CustomerNotification/rationaleVectorEmbedding, /rationaleVector
carrierContractLibrary/tenantId, /carrierScacCarrierPolicyChunk/chunkVectorEmbedding, /chunkVector

Query contract​

QueryContainerScopePurpose
OpenExceptionBoardByLaneshipmentExceptionscross-partition-boundedRender the coordinator's morning exception board for a destination region ordered by promise risk. Intentional cross-partition dispatcher board: the tenantId partition-key prefix scopes the scan and the open-exception state plus the destination-stop list bound it to one region's working set.
ShipmentEventReplayshipmentExceptionssingle-partitionRebuild the full carrier status timeline for one shipment as a partition-aligned single-partition read.
LanePolicyHybridRetrievalcarrierContractLibrarysingle-partitionRetrieve the tariff and SLA clauses that constrain accessorials and reroute authority for the carrier on this lane.
UnreviewedRecoveryPlansshipmentExceptionscross-partition-boundedQueue the copilot recommendations awaiting coordinator adjudication, highest ETA impact first. Intentional cross-partition review queue: bounded by the tenantId prefix, the pending review state and the current shift window.

Python and C# services route each document type to its declared container and hierarchical partition key. ETag-based writes protect mutable aggregates, while append-only records and bounded cross-partition queries preserve scale.

Azure deployment​

Azure deployment

Clone the source repository, authenticate with Azure, and run:

Set-Location accelerators/transportation-logistics/shipment-exception-copilot
az login
./Deploy.ps1 -Runtime python -Location eastus2

Change python to csharp to deploy the .NET implementation.

Explore the implementation​

Return to all accelerators