Treinamento e promoção

Contexto operacional

Este fluxo é o pipeline de decisão de modelo da plataforma. Ele define qual versão e estratégia passam a representar a “verdade operacional” para inferência por série.

Caso de uso

train_candidates_and_promote_champion (em application.engine.use_cases).

Entrada:

• TrainCandidatesAndPromoteChampionCommand(model_definition_id=...)

Dependências (ports):

• ModelingRepositoryPort
• DemandReadRepositoryPort
• StrategyRegistryPort
• ExperimentTrackerPort
• ArtifactStorePort
• ModelRegistryPort (opcional, quando a promoção precisa sincronizar com MLflow Registry)
• DomainToColumnarPort

Saída:

• lista de PromotionResult (uma por série promovida).

Etapas internas

1. Carrega ModelDefinition.
2. Busca séries elegíveis via target_selector.
3. Congela o ModelDefinition corrente em um ModelVersion.
4. Agrupa o treino por estratégia habilitada.
5. Para cada estratégia:
   • lê execution.training_mode em StrategySpec.params_schema;
   • modo padrão: series;
   • modo batch: exige suporte explícito via train_batch(...).
6. Executa o treino:
   • series: mantém o fluxo atual, uma TrainRequest por série;
   • batch: monta uma única BatchTrainRequest com todas as séries elegíveis da estratégia.
7. Registra parâmetros e tags no tracker:
   • series: uma run por série;
   • batch: uma run compartilhada por estratégia/lote.
8. Resolve artefatos:
   • por série (artifact_uri / artifact_payload) como antes;
   • ou compartilhados no lote (shared_artifact_uri / shared_artifact_payload).
9. Cria uma ModelInstance candidata (DRAFT) por série bem-sucedida, vinculada ao model_version congelado do passo 3.
10. Seleciona campeão por select_champion(...).
11. Persiste os candidatos DRAFT em armazenamento durável.
12. Quando ModelRegistryPort está presente:

• chama activate_model_instance(...);
• cria registro de auditoria (PromotionAuditRecord);
• registra uma versão concreta no MLflow Registry;
• sincroniza o alias operacional champion;
• persiste ModelDefinition com metadados de registry.

13. Sem registry configurado, promove campeão localmente para ACTIVE e persiste ModelDefinition.

Modos de treino

Convenção recomendada em StrategySpec.params_schema:

{
  "execution": {
    "training_mode": "series"
  }
}

Valores suportados:

• series
• batch

Compatibilidade:

• ausência de execution.training_mode preserva o comportamento legado;
• estratégias sem train_batch(...) continuam válidas em series;
• batch falha cedo se a estratégia resolvida não suportar batch training.

Lineage de configuração

Antes de iniciar o treino, a engine captura um ModelVersion com snapshot congelado da definição corrente. Isso garante que:

• todas as TrainRequest do fluxo usam params derivados desse snapshot;
• cada ModelInstance criada no treino aponta para o model_version usado;
• previsões futuras reconstituem params pela referência da instância, não pelo StrategySpec.params_schema mutável em memória.

Política de campeão

A decisão usa:

• primary_metric (e direção MIN/MAX);
• promotion_thresholds por métrica.

Regras:

• candidato fora dos thresholds é descartado;
• direção MIN: menor métrica primária vence;
• direção MAX: maior métrica primária vence.

Ativação explícita

Além do fluxo agregado de treino, a engine agora expõe o caso de uso activate_model_instance(...).

Ele existe para separar duas responsabilidades que antes ficavam acopladas:

• gerar candidatos;
• tornar uma versão servível em produção.

Entrada:

• ActivateModelInstanceCommand
  • model_definition_id
  • series_key
  • version
  • actor_id
  • reason
  • metric_snapshot
  • serving_alias (default: champion)

Saída:

• ActivationResult
  • versão promovida;
  • nome/versionamento do modelo no registry;
  • alias de serving;
  • id do registro de auditoria.

Esse fluxo é idempotente por desenho: se a instância já tiver referência de registry persistida, um retry reaproveita essa referência e força novamente o alias operacional.

Resiliência do fluxo

Se uma estratégia falhar no treino:

• o run é finalizado como FAILED no tracker;
• o erro não interrompe as outras estratégias;
• a promoção continua com os candidatos válidos.

No modo batch:

• exceção em train_batch(...) falha o lote inteiro da estratégia;
• resultado misto é aceito;
• séries com error explícito não viram ModelInstance;
• séries bem-sucedidas do mesmo lote continuam elegíveis para promoção.

Esse comportamento evita indisponibilidade de pipeline por falha pontual de estratégia.

Semântica de artefato e tracking em batch

Quando uma única execução treina várias séries:

• continua existindo uma ModelInstance por SeriesKey;
• instâncias podem compartilhar o mesmo artifact_uri;
• instâncias podem compartilhar o mesmo mlflow_run_id;
• promoção, ativação e fallback continuam estritamente por série.

Exemplo de integração de estratégia

from application.engine.contracts import TrainResult

class MinhaEstrategia:
    def train(self, request):
        return TrainResult(
            metrics={"mae": 0.64, "rmse": 0.91},
            artifact_payload=b"modelo-binario",
        )

    def predict(self, request):
        raise NotImplementedError

Exemplo batch-capable:

from application.engine.contracts import BatchTrainResult, BatchTrainSeriesResult

class MinhaEstrategiaBatch:
    def train_batch(self, request):
        return BatchTrainResult(
            series_results=tuple(
                BatchTrainSeriesResult(series_key=item.series_key, metrics={"mae": 0.64})
                for item in request.items
            ),
            shared_artifact_payload=b"modelo-painel",
            tags={"engine_family": "nixtla-statsforecast"},
        )

Checklist de produção

1. ModelDefinition possui primary_metric coerente com evaluator_specs?
2. Existe ao menos uma estratégia habilitada?
3. strategy_key do registro bate com StrategySpec.strategy_key?
4. ArtifactStorePort gera URI estável e auditável?
5. ExperimentTrackerPort registra params, métricas e artefato?
6. TrainResult.tags carrega metadados auditáveis como engine family e model name?
7. ModelRegistryPort cria uma versão concreta e sincroniza o alias champion?
8. ModelingRepositoryPort persiste PromotionAuditRecord com ator, motivo e evidência?