Logistics Ops

The Logistics Ops module is a digital workforce for freight: eight independent agents orchestrated by a central state machine over the shipment lifecycle. Every agent is deterministic and directly callable; the orchestrator is idempotent, so duplicate inbound events are harmless.

Shipment lifecycle

INTAKE ──► RATING ──► TENDER ──► DISPATCH ──► IN_TRANSIT ──► DELIVERED ──► INVOICED
                                                      │
   EXCEPTION ◄── DELAYED ◄── (from IN_TRANSIT)       │
   RESUME ──► IN_TRANSIT                             │
                                                      ▼
                                                   CANCELLED

Transitions are validated by the orchestrator. Reaching a state that is already current is an idempotent no-op (success, no side effects); invalid transitions are rejected with a reason.

Agents

• Intake — extracts route, vehicle, load, pallets, and customer from free text over any channel (web_form, email, whatsapp, voice_stt).
• Rating — deterministic quote: lane history benchmark × vehicle multiplier (ARTIC 1.15, RIGID 1.0, BOX_VAN 0.9, FRIDGE 1.3, FLATBED 1.2, TANKER 1.4) × load multiplier (HAZMAT 1.45, CHILLED 1.25, BULK 1.1, PALLETISED 1.0, GENERAL 0.95) × pallet adjustment. LLMs never compute pricing.
• Carriers — ranks carriers by score (reliability 0.4 + acceptance 0.3 + price 0.2 + lane fit 0.1), opens a tender, and accepts on carrier selection.
• Tracking — idempotent inbound events (event_id + content_hash) driving the playbook: PICKED_UP → IN_TRANSIT, DELIVERED → DELIVERED, DELAYED → EXCEPTION, RESUME → IN_TRANSIT.
• Communication — templates quote, tender, dispatch, and delivery messages in en/fr/es.
• Compliance — generates BOL, POD, INVOICE, RATE_CONFIRMATION documents and the full document set per shipment.
• Analytics — lane performance, carrier reliability, margin summaries; proposes pricing/carrier-mix changes as pending items requiring human approval.
• Orchestrator — the state machine; validates every transition, rejects duplicates, emits logistics.shipment_transitioned.

Idempotency

Every inbound event must carry event_id and content_hash. The system rejects a hash that does not match the event payload, treats a repeated event_id as a no-op, and refuses to reuse an event_id with different content.

Endpoints

GET  /api/v1/logistics-ops                    list shipments
POST /api/v1/logistics-ops/intake            { text, channel }
GET  /api/v1/logistics-ops/:id               shipment detail
POST /api/v1/logistics-ops/tracking          { eventId, shipmentId, status, location }
POST /api/v1/logistics-ops/:id/rate          rate and move to tender stage
POST /api/v1/logistics-ops/:id/tender        open tender with top carrier
POST /api/v1/logistics-ops/:id/accept        { carrierId }
POST /api/v1/logistics-ops/:id/document      { type: "BOL"|"POD"|"INVOICE"|"RATE_CONFIRMATION" }
GET  /api/v1/logistics-ops/analytics         lane + carrier aggregates