Camada modeling

Papel da camada

domain.modeling governa como um modelo é definido, evoluído e ativado para uso em produção. Essa camada é responsável por evitar decisões de promoção inconsistentes.

Objetos de especificação

ModelName

• normaliza para slug;
• rejeita vazio.

WindowSpec

• lookback_periods > 0;
• min_history_periods > 0;
• min_history_periods <= lookback_periods.

LagSpec

• lista de lags obrigatória;
• todos positivos;
• sem duplicidade.

HorizonSpec

• periods > 0;
• step > 0;
• define granularidade alvo da previsão.

MetricSpec, EvaluatorSpec, StrategySpec

• nomes/chaves normalizados;
• parâmetros copiados defensivamente;
• StrategySpec exige chave e família de biblioteca válidas.

Objetos de estado

ModelVersion

Representa snapshot congelado da definição do modelo usado para rastrear qual configuração abasteceu um treino.

ModelInstance

Representa materialização treinada do modelo para uma série específica.

Campos críticos de governança:

• model_version (qual ModelVersion originou o treino);
• status (DRAFT, ACTIVE, DEPRECATED);
• artifact_uri;
• mlflow_run_id;
• metric_snapshot;
• trained_at.

Regras importantes:

• instância ativa exige artifact_uri;
• versão da instância deve ser positiva;
• métricas devem ser numéricas finitas.

Aggregate root: ModelDefinition

ModelDefinition concentra:

• escopo (organization_id, target_selector);
• estratégia de previsão (horizon, janela, lags);
• política de avaliação (avaliadores, métrica primária, thresholds);
• ciclo de vida de versões e instâncias.

Regras de negócio detalhadas

Regra	Onde é aplicada	Motivo de negócio
Precisa existir ao menos um avaliador	__post_init__ de ModelDefinition	Sem avaliador não há base objetiva de comparação.
Precisa existir ao menos uma estratégia	__post_init__ de ModelDefinition	Sem estratégia não há candidato para treino/inferência.
Métrica primária deve existir entre avaliadores	_validate_primary_metric	Evita promoção baseada em métrica não calculada.
Thresholds só podem referenciar métricas existentes	_validate_promotion_thresholds	Evita política inconsistente de promoção.
Chaves de estratégia sem duplicidade	_validate_strategy_specs	Evita ambiguidades de resolução de estratégia.
Apenas uma instância ativa por série	add_instance e active_instance_for_series	Evita disputa de verdade operacional na inferência.
Instância deve pertencer à mesma organização do modelo	add_instance	Impede contaminação entre tenants.

Ciclo de vida de governança

1. Definir modelo (ModelDefinition).
2. Congelar a configuração corrente em ModelVersion (ensure_current_version).
3. Registrar instâncias treinadas por série (add_instance) vinculadas a essa versão.
4. Promover instância campeã (promote_instance).
5. Consultar ativa e anterior para inferência e fallback.

Política de horizonte em runtime

Método: resolve_horizon(override).

Regras:

• override só pode alterar periods;
• grain e step devem permanecer iguais ao modelo.

Motivo:

• permite ajuste de tamanho de previsão sem quebrar semântica temporal da série.

Sinais de configuração inválida

• avaliador não registrado (available_evaluator_keys);
• estratégia desconhecida na criação de instância;
• tentativa de reaproveitar versão existente na mesma série;
• promoção de versão inexistente.

Contrato de saída da camada

Ao fim da camada de modelagem, o sistema sabe:

• qual definição de modelo é válida;
• quais versões e instâncias existem;
• qual instância está autorizada para inferência em cada série.