🚛 Waybill

Autonomous freight broker agent. Book a truck. Pay the driver. Don't break FMCSA.

---

🎯 TL;DR

A small freight shipper pastes a load in plain English — "Chicago → Dallas, 24 pallets, 38,000 lbs, reefer, $3.20/mi, pickup tomorrow 7am." — and Waybill does the rest:

1. Normalizes the load post via Nemotron 3 Ultra into a Dat.com/EDI-ready JSON.
2. Verifies the shipper's FMCSA MC# (refuses to book if unverified).
3. Scores 3 carrier bids on rate · safety · on-time · equipment match · blacklist.
4. Provisions a per-shipper acct_* Stripe Connect sub-account and a per-load card_* Stripe Issuing fuel card, spend-capped.
5. Dispatches the driver via Twilio with BOL + Mapbox live link.
6. Holds the customer's payout T+7d post-POD (extended to T+14d for high-risk carriers).

The agent is the freight brokerage — closest match to the brief's "fully automated company" archetype, with structural compliance-by-design instead of compliance-by-policy.

---

🎬 The 30-second demo

ACME Roofing needs to move 24 pallets of insulation from Chicago to Dallas tomorrow.

Verbatim shape of npm run demo:waybill — normalize → score → verify → book, mock-first.

 WAYBILL  autonomous freight broker
 runtime.mode  nemotron=mock  hermes=mock(Hermes-4-405B)  safety=mock  stripe=mock  projects=mock

 ① Nemotron normalizes the free-text load post              nemotron latency: 405ms
    { origin_zip:"60607", dest_zip:"75207", equipment:"reefer",
      weight_lbs:38000, commodity:"frozen food", linehaul_per_mile:3.18 }

 ② Provision per-shipper Stripe Connect sub-account   stripe.connect acct_mock_shippera
 ③ Provision the twilio/sms driver-dispatch line
    ⓘ the per-load Issuing fuel card is deferred until FMCSA authority clears (⑤)

 ④ TypeScript bid pre-scoring (printed before Nemotron picks)
    mc          name                  rate  safety  ontime    eq   composite
    ✓ MC-784512  Northwind Logistics   2.95   96.00   96.00  1.00      0.980   ← winner
      MC-442111  AllStateHaul          3.05   88.00   92.00  1.00      0.548
    (a 71-safety carrier is disqualified below the floor, before scoring)

 ⑤ NemoClaw · FMCSA authority verification
    fmcsa.verify(MC-784512) → verified=true  safety=satisfactory
    ⤷ per-load Issuing fuel card issued  card_mock_…  ($500/auth cap) — only now
    ⚠ standard payout — 7-day hold post-POD

 ⑤′ Hermes decides book_load; NVIDIA safety NIM screens the driver dispatch ✔
 ⑥ Buy Dat.com FMCSA credit  $1.00  (transient-500 retried ↻)

 ⑦ Safety — NemoClaw refuses UNVERIFIED MC-000000 ✖
 ⑧ Safety — NemoClaw refuses BLACKLISTED MC-220404 ✖
 ⑨ Balance check before pre-payment  ⑩ injection catalog → blocked

 ⑪ T+7d payout release — platform earns 3% of $2,862.00 = $85.86
 Ledger net (after release): +$84.86   ·   margin 98.84%

---

⚡ Quick start

# from repo root
npm install
npm run demo:waybill

# inspect the append-only audit ledger
tail -f .ledgers/waybill.ndjson | jq .

Add STRIPE_SECRET_KEY=sk_test_… and NVIDIA_NIM_API_KEY=nvapi-… to .env to flip from mock → live. Mock mode is the default.

---

🏗️ Architecture (per booking)

            free-text load post from shipper
                       │
                       ▼
        ┌──────────────────────────────┐
        │     Nemotron 3 Ultra         │ ──→ structured JSON
        │   LOAD_NORMALIZE_PROMPT      │
        └──────────┬───────────────────┘
                   │
                   ▼
        ┌──────────────────────────────┐
        │     3 carrier bids            │ ──→ equilibrium pick
        │   CARRIER_PICK_PROMPT        │     (Nemotron-weighted)
        └──────────┬───────────────────┘
                   │
                   ▼
        ┌──────────────────────────────┐    NemoClaw policy gates:
        │     fmcsaCompliance          │ ── ✔ MC# verified? ACT!
        │     podHoldPeriod            │ ── ⚠ 7d payout hold
        │     carrierBlacklist         │ ── BLOCK repeat-offender MC#s
        └──────────┬──────────┬────────┘
                   │          │
              ✔ allowed   ✖ denied  → ledger row `policy-deny`,
                   │                    no Stripe call made
                   ▼
       ┌───────────┼─────────────┐
       │           │             │
       ▼           ▼             ▼
   provision   provision     provision
   stripe-connect     stripe-issuing    spend
   sub-account        fuel card        dat-credits
   acct_…             card_…
                   │
                   ▼
           .ledgers/waybill.ndjson
           (append-only audit log)

---

🛡️ Policy reference (waybill/policy.ts)

Rule id	Predicate	Severity
fmcsaCompliance	mcAuthorityVerified !== true	DENY
fmcsaCompliance	counterpartyRisk === "high"	DENY
podHoldPeriod	default — counterparty risk low	WARN — 7-day payout hold
podHoldPeriod	counterpartyRisk === "medium"	WARN — 14-day payout hold
carrierBlacklist	mcNumber ∈ user.blacklist after any prior load	DENY
provision	Stripe Issuing card spend-cap > $500 / authorization	DENY
provision	per-shipper Connect sub-account already exists for tenantId	ALLOW (idempotent)

The demo's step ⑦ calls fmcsaCompliance with mcAuthorityVerified: false to show the regulatory refuse on stage.

---

📐 What's in vs what's out

✅ In scope	❌ Out of scope (by design)
Reefer / dry-van / flatbed loads (US domestic)	International · hazmat class 1 · containers
Shippers with verified FMCSA MC# (broker authority)	Owner-operator direct dispatch (no broker)
Carrier pool top-100 US carriers (Northwind et al.)	Spot-bid auctions on DAT 144 (legal exposure)
Per-load Stripe Connect sub-accounts	Persistent master Connect accounts (compliance)
7-day payout hold post-POD; 14d for medium-risk	Same-day instant payouts (regulatory risk)
Mapbox live-link dispatch + scheduled phone check-ins	Always-on GPS via Samsara/Geotab integration

---

💰 Revenue model

• Per-load margin. 3% of linehaul, charged on payout_release (after 7-day hold).
• Per-shipper onboarding. $0 — pay-per-use only.
• Fuel card interchange. 15 bps on Issuing authorized volume, pass-through.

---

🧪 Compliance posture (the patch the council demanded)

Waybill never acts as broker of record. It is the AI ops layer above a licensed broker — a tool a freight brokerage uses to automate its back-office, not a substitute for one.

Structural guarantees baked into the runtime:

1. MC# verification = hard gate. NemoClaw refuses to book any carrier (or accept any shipper) whose FMCSA MC# cannot be verified against SAFER + Dat.com at the time of booking.
2. Per-load Connect sub-accounts. Funds are isolated per booking; failure of one load cannot affect another.
3. Per-load Issuing fuel cards. Spend caps are enforced at the Issuing API level — $500/authorization, $2,000/day default.
4. Dispute window is the default. 7 days post-POD; auto-extend to 14 days for medium-risk carriers (safety score < 85).
5. No gray-market carriers. No spot-bidding on DAT 144's public load board. No hazmat-class-1 routing. No international.

The MC# verification is a structural patch: it's a DENY predicate, not a soft warning. We cannot accidentally book unverified freight.

---

📁 File layout

waybill/
├─ README.md         ← you are here
├─ policy.ts         ← NemoClaw rule set (fmcsa + blacklist + podHold)
├─ prompts.ts        ← LOAD_NORMALIZE_PROMPT + CARRIER_PICK_PROMPT
└─ demo.ts           ← `npm run demo:waybill` — 7-step booking tick

---

🪪 License

MIT. Built in <7 days for the Hermes Agent Accelerated Business Hackathon. Every load booked in the demo ledger is mock unless STRIPE_SECRET_KEY is set. FMCSA verification is structural — there is no demo bypass.