Getting Started with AI Ops

This guide gets a subaccount from "AI Ops is off" to "the demand map shows live predictions" in about 15 minutes. You'll need the Levy admin role and a subaccount with at least 14 days of ride history.

1. Confirm the subaccount qualifies

AI Ops needs ride history to learn from. Brand-new subaccounts with fewer than 14 days of rides fall back to a global "city-density-tier" baseline and the recommender is hidden until 30 days are available.

Check the rides count by going to Dashboard > Rides and filtering to the subaccount. If you have less than two weeks of data, hold off — the forecasts will be low-confidence and the recommendations won't generate.

2. Enable the feature flag

AI Ops is gated by ai_ops_enabled and ai_ops_tier on the subaccount. To enable Phase 1 (demand surface only):

• ai_ops_enabled → true
• ai_ops_tier → starter

For the recommender, set ai_ops_tier to pro. For technician routes, set it to enterprise.

You can also tune two related settings:

• tech_cost_per_mile_usd — used by the recommender when subtracting tech cost from projected lift. Default is 0.50.
• rebalance_battery_floor — minimum state-of-charge a vehicle needs to be a rebalance candidate. Default is 30 (percent).

See Feature flags and tiers for the full reference.

3. Run the one-shot backfill

Forecasts run hourly on a cron, but you don't want the dashboard to be empty on day one. The internal backfill endpoint builds two weeks of features and the first set of forecasts in a single call:

curl -X POST "https://fleets.levyelectric.com/api/internal/forecast/backfill" \
  -H "Authorization: Bearer $AI_OPS_INTERNAL_TOKEN" \
  -d '{"subaccountId":"<uuid>"}'

This typically completes in 30-90 seconds depending on ride volume. When it returns, the heat-map page will have something to show.

4. Verify the demand map

Open Dashboard > Analytics > Heat Maps for the subaccount. You should see:

• A map centered on your service area, with H3 hex polygons overlaid.
• Three layer toggles: Predicted demand, Actual history, Unmet demand.
• A horizon picker: 1h, 4h, 24h.
• A time slider running from -7 days to +24 hours.
• Summary tiles showing total predicted rides and the highest-demand hex.

If the map is empty, see Troubleshooting.

5. Wait one cycle, then check recommendations

If you set ai_ops_tier to pro or higher, the recommender runs at minute 25 of each hour. Wait for one full cycle, then open Dashboard > Operations > Rebalance. You should see a ranked card grid of recommended moves.

6. Enable technician routes (Enterprise only)

With ai_ops_tier set to enterprise, the route solver runs every 30 minutes during operating hours (06:00-22:00 local). Routes are assigned to technicians who have the Service Tech role. The technician sees their route inside the operator-app under the Route tab.

Push the operator-app OTA update if your technicians don't already have the Route screen:

cd operator-app
eas update --branch production --message "feat: enable AI Ops Route screen"

What's running behind the scenes

Crons run automatically. You don't need to trigger them manually after the backfill.

Next steps

• Demand forecast map — full guide to the heat-map page.
• Rebalance recommendations — how to read and action the cards.
• Troubleshooting — common setup issues.