Technician Routes
Technician routes are the third capability of AI Ops. The solver takes two kinds of stops — battery swaps and rebalance moves — and packages them into a single ordered route per technician per shift. The technician follows the route inside the operator-app.
This feature is only enabled when the subaccount has ai_ops_tier='enterprise'.
What goes into a route
The route builder runs every 30 minutes during operating hours (06:00-22:00 local). For each technician on shift, it gathers:
- Low-battery vehicles below the swap threshold — these become swap stops.
- Accepted rebalance recommendations — each turns into a pickup stop and a dropoff stop, paired (the same vehicle must be picked up then dropped off).
- The technician's start and end location for the shift.
- The shift window (start time, end time).
- Van capacity — how many vehicles fit in the tech's vehicle at once.
The solver minimizes total travel time subject to all stops fitting within the shift window, all pickup → dropoff pairs being honored in order, and capacity never exceeding the van limit.
Stop types
| Type | What it means |
|---|---|
| swap | Battery swap in place. Tech replaces the battery, scoots on. Vehicle remains in the same hex. |
| pickup | Tech picks up an over-supplied vehicle, loads it into the van. |
| dropoff | Tech drops off a previously-picked-up vehicle at the rebalance destination. |
A route alternates between pickups and dropoffs as the van fills and empties. Swap stops can happen anywhere in the sequence.
Solvers
Levy AI Ops ships with three solver implementations and picks at runtime:
- OR-Tools — Google's open-source vehicle routing solver, exposed as a FastAPI microservice. Honors pickup/delivery pairs, time windows, capacity, and uses the GUIDED_LOCAL_SEARCH metaheuristic with a 5-second time limit. Used by default if
ORTOOLS_SOLVER_ENDPOINTis configured. - Routific — paid API, higher-quality solutions for larger routes. Used when
ROUTIFIC_API_TOKENis set. Best for routes with 30+ stops. - Local savings solver — a pure-TypeScript Clarke-Wright + 2-opt fallback that runs in Node. Adequate for routes up to ~30 stops in under 100ms. Used when neither remote solver is configured.
The active solver is recorded in rebalance_routes.solver_version so you can audit which run used which engine.
The auto-maintenance rule
When a route is built, every vehicle attached to a pickup stop is automatically set to maintenance status. This prevents a rider from grabbing the vehicle before the technician arrives.
The vehicle stays in maintenance until one of:
- The technician completes the pickup stop (vehicle stays in
maintenancewhile in the van, then flips back toavailableat the dropoff). - The route is abandoned (vehicle reverts to
availableimmediately). - The tech completes a swap stop (vehicle flips back to
availableonce the swap is logged).
This is the one piece of AI Ops that takes an action without operator review. It is intentional and limited to the pickup window of an active route.
Routes table
A route is stored in rebalance_routes with these key fields:
| Field | Meaning |
|---|---|
subaccount_id | RLS scope |
technician_id | The user assigned this route |
shift_start / shift_end | The window the solver respected |
status | planned → in_progress → completed / abandoned |
solver_version | Which engine built this route |
total_distance_m | Solver's total distance estimate |
estimated_minutes | Solver's total time estimate |
Each stop sits in rebalance_route_stops:
| Field | Meaning |
|---|---|
sequence | 0-indexed order along the route |
stop_type | pickup / dropoff / swap |
vehicle_uuid | The vehicle this stop acts on |
destination_h3 | For dropoffs, the target hex |
eta | Solver's estimated arrival time |
time_window_end | Latest acceptable arrival |
completed_at | When the tech marked it done |
completion_note | Optional free-text from the tech |
Edge cases
| Situation | What happens |
|---|---|
| Tech doesn't accept the route | Status stays planned. Auto-maintenance is not applied until the tech taps Accept. |
| Tech taps Abandon | Auto-maintenance vehicles revert to available. Incomplete recommendations are re-opened. |
| Too many stops for shift window | Solver returns the longest feasible subset. Surplus stops stay as open recommendations for the next route or the next tech. |
| No technician on shift | Routes aren't generated. Recommendations still accumulate in the operator dashboard. |
| Solver times out (>5s on OR-Tools) | System falls back to the local savings solver for that single run. Sentry warning is emitted. |
Measuring the win
The academic literature on joint swap + rebalance routing claims roughly 50% travel-distance reduction compared to swap-only and rebalance-only routes run independently. In practice, expect 30-50% depending on fleet density and shift length. The total_distance_m field on each route is the measurement: compare a week of AI Ops routes to a week of manually-planned routes to see the delta.
Related
- Operator-app routes — what the technician sees in the app.
- Rebalance recommendations — the input to the route builder.
- Feature flags and tiers —
ai_ops_tier='enterprise'is required.