Feature Flags and Tiers
AI Ops is controlled by four columns on the subaccounts table. They take effect immediately — no redeploy needed — and every cron job reads them at runtime.
The four settings
| Column | Type | Default | What it does |
|---|---|---|---|
ai_ops_enabled | boolean | false | Master switch. Off = AI Ops crons skip this subaccount entirely. |
ai_ops_tier | text | null | One of starter, pro, enterprise. Determines which capabilities run. |
tech_cost_per_mile_usd | numeric | 0.50 | Subtracted from projected lift in the recommender. |
rebalance_battery_floor | integer | 30 | Minimum state-of-charge (percent) for a vehicle to be a rebalance candidate. |
Tier matrix
| Capability | Starter | Pro | Enterprise |
|---|---|---|---|
Demand forecast surface (/dashboard/analytics/heat-maps) | yes | yes | yes |
| Unmet-demand heatmap | yes | yes | yes |
Rebalance recommender (/dashboard/operations/rebalance) | no | yes | yes |
| Top-3 widget on operations dashboard | no | yes | yes |
| Joint swap+rebalance routes | no | no | yes |
| Operator-app Route tab | no | no | yes |
| Auto-maintenance rule | no | no | yes |
| OR-Tools VRP solver | n/a | n/a | yes |
| Routific solver (when token configured) | n/a | n/a | yes |
Tuning tech_cost_per_mile_usd
This setting represents the marginal cost of moving a vehicle one mile. For an operator paying contractors a flat hourly rate, a reasonable estimate is hourly rate divided by average miles-per-hour for the territory.
- Lower values make the recommender more aggressive — more moves at lower individual lift.
- Higher values make it conservative — only the highest-lift moves clear the bar.
Default 0.50 is a good starting point for urban scooter operators. Suburban and tour operators with longer travel distances often raise it to 0.75 or 1.00.
The cost is subtracted directly from projected lift:
projected_lift_usd = (dest_gain - src_loss) * avg_fare - distance_miles * tech_cost_per_mile_usd
If the result is negative, the recommendation is never written.
Tuning rebalance_battery_floor
A vehicle won't be picked up for a rebalance move if its battery is below this floor. The default 30 (percent) is a safe threshold for most scooter fleets — leaves enough range for the tech to load and offload without an in-transit failure.
- For e-bikes or vehicles with longer range, you can drop the floor to
15-20. - For ultra-conservative operators (e.g. winter conditions), raise it to
40-50.
Vehicles below the floor are not rebalanced. They are instead candidates for the swap stop type in technician routes, which brings them up before they're moved.
How tier changes propagate
| Action | Effect |
|---|---|
Set ai_ops_enabled = false | All AI Ops crons skip this subaccount on the next run. Existing forecasts and recommendations stay in the DB but no new ones generate. |
Downgrade ai_ops_tier from enterprise to pro | The route-solver cron skips this subaccount. Existing in-progress routes continue until completed or abandoned. |
Upgrade starter → pro | The recommender cron starts generating recs on its next run. |
Upgrade pro → enterprise | The route solver starts running on its next 30-minute tick (during operating hours). |
Tier changes take effect on the next cron run. They do not retroactively undo work done by earlier runs.
Where to set the flags
Today the flags are set directly on the subaccounts row via the admin API (PATCH /api/admin/super-subaccounts/[id]) or Supabase SQL. A first-class UI in the admin dashboard is on the roadmap.
For pilot rollout the recommended SQL is:
UPDATE subaccounts
SET ai_ops_enabled = TRUE,
ai_ops_tier = 'starter',
tech_cost_per_mile_usd = 0.50,
rebalance_battery_floor = 30
WHERE id IN ('<pilot_uuid_1>', '<pilot_uuid_2>');
Related
- Getting started — full setup walkthrough.
- Rebalance recommendations — where
tech_cost_per_mile_usdis applied. - Technician routes — requires the Enterprise tier.