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}`