freight/docs/LOADETA_DOMAIN_EXTRACT.md

LoadETA Domain Intelligence & Agent Training Specification

Extracted directly from ~/Projects/loadeta (backend/livekit/src/assistant/). This document defines the exact production schemas, speech rules, equipment validation constraints, and negotiation workflow states used to fine-tune Qwen 3.8 9B for LoadETA.

---

1. Speech Hygiene & Pronunciation Rules (PronunciationRules.ts)

These rules are strictly enforced during voice synthesis (TTS/STT in LiveKit):

• Money & Currencies: Always pronounce naturally (e.g. $2,450 $\to$ "twenty-four fifty dollars" or "twenty-four hundred and fifty dollars"). Never read digit-by-digit.
• IDs, Load Numbers & MCs: Read digit-by-digit (e.g. MC 782914 $\to$ "Motor Carrier Number seven eight two nine one four").
• Terminology Override: Always say "Motor Carrier Number", never "MC" or "mac".
• Entity Suffix Stripping: NEVER say "LLC", "INC", "CORP", or "LTD" on the phone. Only say the base name (e.g. "Apex Logistics", not "Apex Logistics Incorporated").
• State Names: Always pronounce state abbreviations in full ("Illinois" for IL, "Texas" for TX, "Georgia" for GA).
• Silence on Acknowledgment: When the broker or driver says "yes", "okay", or "right", the agent remains silent and proceeds directly to the next question.

---

2. Mandatory 6-Step Workflow State Machine (WorkflowSequence.ts)

Every LiveKit negotiation call follows this strict linear progression:

[1. Verify MC] ──> [2. Rate Floor Negotiation] ──> [3. Equipment / Tarps]
       │
       └──> [4. Driver Name & Phone] ──> [5. Email Exchange] ──> [6. Send Rate Con]

1. verify_mc: Look up FMCSA authority, check if active, inspect safety rating and credit score (>85).
2. negotiate_rate: Compute effective rate floor: $\text{Effective Floor} = \max(\text{minTotalUsd}, \text{minRatePerMile} \times \text{loadedMiles})$. Protect accessorials (2 hours free detention, $75/hr after).
3. truck_info: Confirm equipment code (V=Van, R=Reefer, F=Flatbed, SD=Stepdeck, PO=Power Only) and tarp size (8ft vs 12ft).
4. driver_info: Collect Driver First/Last Name and 10-digit mobile number for dispatch tracking.
5. email_exchange: Exchange dispatch email address for rate confirmation delivery.
6. send_rate_con: Execute booking in database, dispatch confirmation email, and close call politely.

---

3. Equipment & HOS Constraints (agentEquipmentValidators.ts)

• Hours of Service (HOS): $$\text{Driving Time} = \frac{\text{Trip Miles}}{50.0\text{ mph}}$$
  • If driving time $> 8$ hours, add 30-minute mandatory rest break.
  • If driving time $> 11$ hours, add 10-hour sleeper berth reset per 11-hour driving block.
• Tarp Verification (Flatbed/Stepdeck):
  • Validate minimum tarp drops (8ft tarps for machinery, 12ft tarps for tall lumber/steel).
• Reefer Modes:
  • Continuous (-10°F to 0°F frozen foods) vs Start-Stop (+34°F to +45°F fresh produce). Mandatory pre-cool verification before loading.

---

4. Exact LoadETA Tool Schemas

1. fmcsa_verify_mc:
   • Args: {"mc_number": string, "broker_name": string}
   • Returns: {"status": "CLEAN"|"FLAGGED", "active": boolean, "credit_score": number, "days_active": number}
2. calculate_rate_floor:
   • Args: {"origin": string, "destination": string, "equipment_type": string, "mileage": number, "weight": number}
   • Returns: {"rate_floor": number, "recommended_target": number, "rpm_floor": number}
3. get_truck_route_distance:
   • Args: {"origin": string, "destination": string, "truck_type": string}
   • Returns: {"distance_miles": number, "toll_roads_usd": number, "estimated_drive_hours": number}
4. book_load_offer:
   • Args: {"broker_name": string, "mc_number": string, "rate_agreed": number, "detention_rate_per_hr": number, "driver_name": string, "driver_phone": string, "dispatch_email": string}
   • Returns: {"status": "BOOKED", "confirmation_code": string}