Nixtla

Papel no sistema

Os adapters em src/infra/modeling/nixtla/ são a ponte entre o contrato interno da engine e as bibliotecas concretas de forecast.

No runtime:

• o ModelDefinition persiste strategy_key, library_family, params_schema, evaluation_spec, validation_policy, series_projection_recipe, feature_recipe e champion_reuse_policy;
• os jobs Airflow montam um DefaultStrategyCatalog;
• register_nixtla_strategies(...) registra o provider Nixtla no catálogo;
• o caso de uso resolve a estratégia pelo strategy_key e executa treino ou predição.

Isso mantém domínio e aplicação sem dependência direta de statsforecast, mlforecast ou scikit-learn.

Famílias suportadas

library_family	Adapter	Catálogo padrão	Modos de treino	Observações
nixtla-statsforecast	NixtlaStatsForecastStrategy	statsforecast/catalog.py	series	suporta modelos estatísticos e alguns intervalos
nixtla-mlforecast	NixtlaMLForecastStrategy	mlforecast/catalog.py	series	usa regressão sobre colunas geradas por feature_recipe

strategy_key e library_family são normalizados para slug no domínio. O lookup real acontece pelo strategy_key; o library_family serve para validar o contrato e proteger contra combinações incompatíveis.

Como a configuração é interpretada

Cada StrategySpec persiste um params_schema com esta forma:

{
  "model": {
    "name": "seasonal-naive",
    "hyperparams": {}
  },
  "intervals": {
    "levels": []
  },
  "execution": {
    "max_workers": 1
  }
}

Regras relevantes:

• model.name precisa bater com o modelo concreto esperado pelo adapter;
• execution.max_workers controla paralelismo bounded entre séries independentes;
• preparo reutilizável vive em feature_recipe; quando uma estratégia declara sua própria receita, o boundary de data-preparation aplica essa receita depois da projeção e antes do adapter Nixtla receber o frame por série;
• intervals.levels aceita inteiros entre 1 e 99;
• nixtla-mlforecast e nixtla-statsforecast treinam uma série por chamada de estratégia.

Além disso, a promoção usa as métricas expostas pela própria estratégia. A engine:

• separa treino e holdout por série usando helpers frame-native guiados por evaluation_spec;
• chama train(...) e predict(...) sobre o prefixo do holdout para validar o caminho de artefato e previsão;
• treina o candidato final com o frame completo;
• persiste no metric_snapshot as métricas retornadas por TrainResult.metrics.

Uma falha de avaliação ou treino invalida o run inteiro, sem promoção parcial, mesmo quando várias séries são executadas em paralelo.

Para o contrato completo de ModelDefinition, veja Configuração de model definition.

Tradução de dados

Os adapters Nixtla não recebem qualquer payload arbitrário. A entrada precisa ser um payload canônico por série, entregue pelo boundary de data-preparation para o control. O contrato do control é genérico e separa payload de treino de payload de forecast; o adapter aceita frames Polars vindos do boundary de data-preparation e passa Polars diretamente para as integrações Nixtla.

No caminho de treino e predição:

1. o adapter ordena por period_start.
2. a série vira um unique_id estável por organization_id + series_kind + series_id + grain.
3. period_start vira ds e quantity vira y.
4. colunas extras geradas por feature_recipe seguem como regressoras quando o adapter precisa delas.

Na volta:

• o adapter traduz ds para period_start;
• a coluna prevista vira value;
• uom é preservada a partir do frame de entrada;
• intervalos viram lower, upper e confidence quando o modelo os expõe.

Limites importantes:

• o frame precisa seguir o contrato canônico de treino;
• a série precisa ter uma única uom;
• a integração assume as colunas canônicas de demanda, não aliases locais.

nixtla-statsforecast

NixtlaStatsForecastStrategy cobre modelos estatísticos já incluídos, como seasonal-naive, auto-arima, auto-ets e outros do catálogo interno.

Semântica principal:

• implementa train(...) e predict(...);
• cada série gera seu próprio artefato e seu próprio run de treino;
• no MLflow, cada série abre um run pai com nome derivado do SeriesKey e sufixo nanoid; os runs de estratégia dessa série entram como filhos via mlflow.parentRunId;
• a promoção do campeão não usa mais métricas fitted/in-sample do catálogo;
• para famílias sazonais, season_length pode ser inferido do grain;
• alguns modelos aceitam intervalos; outros são point_only sob a integração atual.

Na prática, nixtla-statsforecast é a família mais flexível para o MVP porque não depende de pipeline de regressão.

nixtla-mlforecast

NixtlaMLForecastStrategy cobre regressões já incluídas, como ridge, random-forest, extra-trees e hist-gradient-boosting.

Semântica principal:

• recebe as colunas de feature já materializadas pelo feature_recipe;
• usa colunas extras numéricas como regressoras e colunas categóricas via OneHotEncoder;
• grava no artefato a lista de colunas usadas pelo regressor e a receita de features treinada;
• retorna metadados de relatório com colunas concretas de feature, configuração resolvida do modelo e coeficientes/importâncias quando o estimador os fornece;
• na predição, usa a porta FeatureEngineeredPredictionPort para reconstruir as features a cada passo e realimentar as previsões no histórico antes do próximo ponto;
• para modelos com componente aleatório, injeta random_state=0 se ele não vier configurado;
• calcula métricas supervisionadas sobre a matriz de treino já preparada.

Esse adapter é útil quando a série precisa de regressão sobre lags e features estáticas, sempre no contrato de treino por série.

A composição Nixtla injeta a implementação Polars dessa porta no catálogo de estratégias. Assim o mesmo caminho vale para treino local, jobs Airflow e execução de predição, sem o adapter MLForecast construir a implementação por conta própria.

Artefatos e validação

Os dois adapters serializam artefatos no mesmo formato: um zip com:

• manifest.json
• model.pkl

O manifesto registra:

• strategy_key
• resolved_config
• feature_recipe
• feature_columns nos modelos MLForecast

Na predição, o adapter valida que o manifesto bate com o strategy_key resolvido. O restante do manifesto é dado operacional do próprio caminho de predição: configuração resolvida, receita de features e colunas do regressor quando existirem. Não há camada de compatibilidade para manifestos antigos.

Isso evita aceitar artefatos de outra estratégia sem manter metadados duplicados que já existem no catálogo ou no comando de treino.

URI de artefato

Na leitura do artefato, a integração Nixtla aceita:

• file://...
• caminho local simples
• s3://bucket/key

Se o URI for s3://, o adapter depende de um cliente boto3 compatível injetado no bootstrap.

Limitações atuais

• global/panel modeling ainda não é um conceito exposto; se necessário, deve entrar como estratégia explícita própria, não como configuração de execução;
• alguns modelos statsforecast expõem apenas point forecast;
• a integração espera schema canônico de demanda, sem etapa de mapeamento flexível.

Onde estender

Para adicionar um novo modelo nessa família:

1. inclua a spec no catálogo correto;
2. mantenha o strategy_key estável;
3. registre o catálogo no bootstrap dos jobs;
4. documente o uso na página de configuração, se o contrato mudar.

Onde continuar

• Modelos ML
• Configuração de model definition
• Fluxos principais
• Airflow e jobs