Fontes de Dados: Clima e Eventos

A previsão de demanda do AI Ops é condicionada a quatro fontes de dados. Três são externas; uma é o seu próprio histórico de corridas. Esta página cobre o que são, onde ficam e o que acontece quando uma delas fica indisponível.

Corridas históricas

A base da previsão é sua própria tabela rides. Mais precisamente, o pipeline de features lê de ride_events_ts, uma view materializada que agrega inícios de corrida em buckets de hex H3 × 1 hora.

• O lookback de treino é de no mínimo 90 dias e no máximo 365 dias.
• Um feature de lag semanal (corridas no mesmo hex 168 horas antes) captura sazonalidade por dia da semana.
• Efeitos fixos por subaccount permitem que o modelo global se ajuste à linha de base de cada operador.

Se o subaccount tem menos de 14 dias de corridas, o modelo cai em uma baseline global por tier de densidade da cidade. O recomendador continua oculto até completar 30 dias de histórico.

Clima: Tomorrow.io

O clima é puxado da Tomorrow.io. Foi escolhida pela acurácia hiperlocal e pelo custo no nosso volume.

Três features são extraídos:

• temp_c — temperatura em Celsius
• precip_prob — probabilidade de precipitação (0,00 a 1,00)
• wind_kph — velocidade do vento em km/h

As observações ficam em cache na tabela weather_observations, chaveadas por hex H3 × hora. O cache é compartilhado entre subaccounts da mesma cidade, evitando chamadas duplicadas.

Quando a Tomorrow.io cai

O cliente em weather.ts degrada graciosamente para um stub de climatologia quando TOMORROW_IO_API_KEY não está definido ou a API está inalcançável. O stub usa médias de longo prazo por hora-da-semana.

Se a queda passar de 2 horas, um alerta no Sentry dispara. O modelo continua produzindo previsões durante a queda, mas a acurácia cai para hexes em que o clima é o sinal dominante.

Eventos: PredictHQ

Eventos locais (shows, esportes, festivais) deslocam a demanda de forma significativa. Nós os puxamos da PredictHQ, que pontua o impacto de cada evento por localização.

Para cada hex × hora, o pipeline calcula um único feature event_count: o número de eventos impactantes dentro do hex naquela hora.

Quando a PredictHQ cai

O cliente em events.ts cai para um stub cíclico determinístico quando PREDICTHQ_API_KEY não está definido ou a API falha. O stub retorna event_count = 0 com uma pequena modulação por dia da semana.

Recomendações geradas durante uma queda da API de eventos são marcadas como "weather/events incomplete" na tabela de auditoria, deixando claro que a previsão rodou com entradas degradadas.

Feriados

Uma tabela holiday_calendar mantida manualmente guarda feriados nacionais por país. A Fase 1 cobre:

• Estados Unidos
• Canadá
• Reino Unido
• Alemanha
• México

Mercados fora desses países caem em is-weekend, que captura a maior parte do efeito semelhante a feriado.

Para adicionar um país, insira linhas em holiday_calendar com código do país, data e nome do feriado. O pipeline de features passa a usar na próxima execução horária.

Modal (engine de inferência)

Os modelos LightGBM treinados ficam na Modal, uma plataforma de runtime Python. O treino noturno:

1. Puxa todas as linhas de demand_features dos últimos 90 dias.
2. Treina três regressores — um por horizonte (1h, 4h, 24h).
3. Serializa como artefatos forecast-{subaccount}-h{horizon}.txt.
4. Grava um manifesto com versões de modelo e MAPE por subaccount.

A inferência é exposta como um endpoint web /predict que o cron de inferência do Next.js chama via POST.

Quando a Modal cai

A biblioteca forecasting.ts cai para um regressor de gradient boosting puro TypeScript que treina em processo a cada inferência. É mais lento (subaccounts com mais de 5.000 linhas de feature levam mais de um segundo) e menos preciso, mas o pipeline continua rodando. A ausência da Modal é registrada em log, mas não fica visível para o cliente.

Frescor dos features

Cada camada do pipeline grava um carimbo de tempo de frescor:

• weather_observations.fetched_at — quando a Tomorrow.io foi consultada pela última vez
• demand_features.feature_built_at — quando a linha de features foi montada
• demand_forecasts.created_at — quando o modelo escreveu a previsão
• model_runs.completed_at — quando o último treino terminou

Se qualquer um deles estiver desatualizado por mais de 90 minutos, o painel mostra o banner de previsão desatualizada (veja Mapa de previsão de demanda).

Auditando uma previsão

Para ver o que alimentou uma determinada previsão para um hex × hora:

SELECT * FROM demand_features
WHERE subaccount_id = '<uuid>'
  AND h3_index = <bigint>
  AND bucket_start = '<timestamp>';

Em seguida, junte com weather_observations e o feature de eventos para a mesma chave. A linha também traz um model_version que casa com demand_forecasts.model_version, permitindo rastrear exatamente qual artefato treinado produziu a previsão.

Relacionado

• Mapa de previsão de demanda — como os dados são renderizados.
• Solução de problemas — o que fazer quando uma fonte está degradada.