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 attribute | Value |
|---|---|
| Primary persona | Logistics coordinator |
| Primary aggregate | ShipmentException |
| Cosmos DB containers | 2 |
| Grounding data | tracking, orders, routes, capacity, weather |
| Development estimate | USD 60-220 monthly dev estimate |
| Runtime options | Python FastAPI and C# ASP.NET Core |
Productivity hypothesis
These measures reflect the workflow, evidence, decision boundary, and industry risk for this use case.
| Impact type | Measure | Conservative internal assumption | Customer measurement |
|---|---|---|---|
| Productivity | Exception resolution cycle time | 10-20% reduction | (baseline median exception-resolution minutes - assisted median minutes) / baseline median minutes * 100 |
| Quality or risk | First-pass resolution correctness | 5-10 percentage-point improvement | assisted 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
- Baseline the current workflow with representative users and tasks.
- Run the accelerator on the same task mix with human review retained.
- Measure exception resolution cycle time and first-pass resolution correctness with the documented formulas.
- 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

| Stage | Actor | Input → output | Approval |
|---|---|---|---|
| 1. Milestone deviation detection | Change-feed exception detector | TrackingEvent → ExceptionCase | Policy controlled |
| 2. Root-cause evidence assembly | Retrieval orchestrator | ExceptionCase → evidenceBundle | Policy controlled |
| 3. Recovery option generation | Shipment exception copilot | evidenceBundle → RecoveryPlanDraft | Policy controlled |
| 4. Coordinator adjudication of recovery option | Logistics coordinator | RecoveryPlanDraft → approvedRecoveryPlan | Human required |
| 5. Carrier tender and consignee notification | Logistics coordinator with TMS connector | approvedRecoveryPlan → CustomerNotification | Human required |
Technical architecture

Cosmos DB data model
| Container | Hierarchical partition key | Documents | Search paths |
|---|---|---|---|
shipmentExceptions | /tenantId, /shipmentId | Shipment, TrackingEvent, ExceptionCase, RecoveryPlanDraft, CustomerNotification | /rationaleVectorEmbedding, /rationaleVector |
carrierContractLibrary | /tenantId, /carrierScac | CarrierPolicyChunk | /chunkVectorEmbedding, /chunkVector |
Query contract
| Query | Container | Scope | Purpose |
|---|---|---|---|
| OpenExceptionBoardByLane | shipmentExceptions | cross-partition-bounded | Render 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. |
| ShipmentEventReplay | shipmentExceptions | single-partition | Rebuild the full carrier status timeline for one shipment as a partition-aligned single-partition read. |
| LanePolicyHybridRetrieval | carrierContractLibrary | single-partition | Retrieve the tariff and SLA clauses that constrain accessorials and reroute authority for the carrier on this lane. |
| UnreviewedRecoveryPlans | shipmentExceptions | cross-partition-bounded | Queue 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

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
- Launch signed-in demo
- Implementation article
- Domain data model
- Workflow and API contract
- Python application
- C# application
- Domain container Bicep
- Platform Bicep
- Cost and configuration
- Source repository