domain.modeling

Papel na engine

domain.modeling controla a governança de modelos da plataforma: quais estratégias são válidas, quais versões existem e qual instância está ativa em cada série.

Módulo: domain.modeling.model

Tipos auxiliares

• type JSONScalar = str | int | float | bool | None
• type JSONValue = JSONScalar | list[JSONValue] | dict[str, JSONValue]
• type ParamsMap = dict[str, JSONValue]
• DEFAULT_EVALUATOR_REGISTRY_KEYS = {"mae", "rmse", "mape", "smape", "wape"}

Estruturas de especificação

ModelName

• Campo: value: str
• Normaliza para slug (baseline xgboost -> baseline-xgboost)
• Falha se vazio.

WindowSpec

Campos:

• lookback_periods: int
• min_history_periods: int

Regras:

• ambos > 0;
• min_history_periods <= lookback_periods.

LagSpec

Campo:

• lags: tuple[int, ...]

Regras:

• não pode ser vazio;
• todos os lags > 0;
• lags devem ser únicos.

HorizonSpec

Campos:

• periods: int
• grain: TimeGrain
• step: int = 1

Regras:

• periods > 0
• step > 0

MetricDirection

• MIN
• MAX

StrategyTrainingMode

• SERIES
• BATCH

MetricSpec

Campos:

• name: str
• direction: MetricDirection
• params: ParamsMap = {}

Comportamento:

• normaliza name para lowercase;
• copia defensiva profunda de params.

EvaluatorSpec

Campos:

• registry_key: str
• params: ParamsMap = {}

Comportamento:

• normaliza registry_key para lowercase;
• copia defensiva profunda de params.

StrategySpec

Campos:

• strategy_key: str
• library_family: str
• params_schema: ParamsMap = {}
• enabled: bool = True

Comportamento:

• normaliza strategy_key e library_family como slug;
• trata library_family como seletor de família de engine (nixtla-statsforecast, nixtla-mlforecast, etc.);
• copia defensiva profunda de params_schema;
• expõe training_mode com default series.

Convenção recomendada de params_schema:

• model.name
• model.hyperparams
• features.date_features
• features.static_features
• features.known_future_features
• intervals.levels
• execution.training_mode

execution.training_mode aceita:

• series
• batch

Versionamento e instâncias

ModelVersionStatus

• DRAFT, ACTIVE, DEPRECATED

ModelVersion

Campos:

• version: int
• status: ModelVersionStatus
• params_snapshot: ParamsMap
• created_at: datetime

Regra:

• version > 0.
• params_snapshot preserva árvores JSON-like aninhadas.
• no fluxo padrão da engine, params_snapshot guarda o snapshot congelado do ModelDefinition usado para treino.

ModelInstanceStatus

• DRAFT, ACTIVE, DEPRECATED

ModelInstance

Campos principais:

• model_definition_id: UUID
• series_key: SeriesKey
• model_version: int
• version: int
• strategy_key: str
• status: ModelInstanceStatus
• artifact_uri: str | None
• mlflow_run_id: str | None
• metric_snapshot: dict[str, float]
• trained_at: datetime | None

Regras centrais:

• model_definition_id não nulo;
• model_version > 0;
• version > 0;
• strategy_key normalizado e não vazio;
• status=ACTIVE exige artifact_uri;
• métricas são normalizadas para float finito;
• status não-DRAFT preenche trained_at se ausente.

Observação:

• instâncias treinadas em batch podem compartilhar artifact_uri e mlflow_run_id, sem alterar a regra de uma instância ACTIVE por série.
• model_version aponta para o snapshot congelado usado no treino e é a base para reconstituir params em inferência.

Método:

• set_status(status) com validação de artefato para ACTIVE.

Agregado principal: ModelDefinition

Campos principais:

• identidade: id, organization_id, name
• escopo: target_selector
• configuração: horizon_spec, window_spec, lag_spec
• avaliação: evaluator_specs, primary_metric, promotion_thresholds
• estratégias: strategy_specs
• policy: allowed_target_grains, available_evaluator_keys
• estado: versions, instances, created_at

Validações de inicialização:

• id não nulo;
• target_selector não vazio;
• ao menos um avaliador e uma estratégia;
• horizon_spec.grain permitido por policy;
• primary_metric presente entre avaliadores;
• thresholds referenciam métricas existentes;
• strategy keys sem duplicidade;
• ao menos uma estratégia habilitada.

Propriedades

• versions -> tuple[ModelVersion, ...]
• instances -> tuple[ModelInstance, ...]

Métodos de versão

• add_version(params_snapshot, status=DRAFT, created_at=None, force_version=None)
• update_version_status(version, status)
• latest_version()
• ensure_current_version()
• strategy_params_for_version(model_version, strategy_key)

Métodos de instância

• enabled_strategy_specs()
• add_instance(...)
• promote_instance(series_key, version)
• active_instance_for_series(series_key)
• latest_instance_for_series(series_key)
• previous_instance_for_series(series_key, version)
• instances_for_series(series_key)

Regras relevantes de instância:

• series_key.organization_id deve coincidir com organization_id do modelo;
• estratégia deve existir em strategy_specs;
• versão de instância deve ser única por série;
• apenas uma instância ACTIVE por série.

Método de horizonte

• resolve_horizon(override: HorizonSpec | None)

Restrições de override:

• mesmo grain do horizonte do modelo;
• mesmo step do horizonte do modelo;
• periods pode variar.