application.engine

Papel na engine

application.engine é a orquestração operacional do módulo de inteligência. Ele conecta regras de domínio às integrações externas por meio de ports, mantendo o core desacoplado.

Módulo: application.engine.contracts

Tipos

• FeatureFrame = Any
• params em requests usam ParamsMap do domínio de modelagem (dict[str, JSONValue]).

Requests/Results

TrainRequest

Campos:

• organization_id
• model_definition_id
• series_key
• horizon_spec
• feature_frame
• params: ParamsMap

TrainResult

Campos:

• metrics: dict[str, float]
• artifact_uri: str | None
• artifact_payload: bytes | None
• tags: dict[str, str]

Pelo menos um entre artifact_uri e artifact_payload deve existir para persistência do candidato.

BatchTrainItem

Campos:

• series_key
• feature_frame

BatchTrainRequest

Campos:

• organization_id
• model_definition_id
• horizon_spec
• items: tuple[BatchTrainItem, ...]
• params: ParamsMap

Regras:

• items não pode ser vazio;
• series_key deve ser único dentro do batch.

BatchTrainSeriesResult

Campos:

• series_key
• metrics: dict[str, float]
• artifact_uri: str | None
• artifact_payload: bytes | None
• tags: dict[str, str]
• error: str | None

BatchTrainResult

Campos:

• series_results: tuple[BatchTrainSeriesResult, ...]
• shared_artifact_uri: str | None
• shared_artifact_payload: bytes | None
• tags: dict[str, str]

Regras:

• series_results não pode ser vazio;
• séries bem-sucedidas precisam resolver para artefato próprio ou compartilhado;
• falhas por série permanecem explícitas e não devem ser promovidas.

PredictRequest

Campos:

• organization_id
• model_definition_id
• series_key
• horizon_spec
• feature_frame
• artifact_uri
• params: ParamsMap

PredictResult

Campos:

• forecast_frame
• metrics
• tags

EvaluationResult

Campos:

• strategy_key
• metrics

Módulo: application.engine.ports

Protocolos (ports):

• ModelStrategy
  • train(request) -> TrainResult
  • predict(request) -> PredictResult
• BatchTrainingStrategy
  • train_batch(request) -> BatchTrainResult
• StrategyRegistryPort
  • resolve(strategy_key) -> ModelStrategy
• ExperimentTrackerPort
• start_run(...) -> str
• start_batch_run(...) -> str
• log_params(...)
• log_tags(...)
• log_metrics(...)
• log_artifact(...)
• end_run(...)
• ArtifactStorePort
  • store_artifact(...) -> str
  • store_batch_artifact(...) -> str
• ModelRegistryPort
  • register_model_version(...) -> RegisteredModelVersion
  • promote_model_version(...)
  • deprecate_model_version(...)
  • resolve_serving_target(...) -> ServingTarget
• ForecastObservabilityPort
  • record_forecast(telemetry)
• RunQueuePort
  • enqueue_training(...)
  • enqueue_forecast(...)
• ModelingRepositoryPort
  • get_model_definition(...)
  • save_model_definition(...)
  • save_promotion_audit_record(...)
  • list_promotion_audit_records(...)
• ForecastingRepositoryPort
  • save_forecast_run(...)
• DemandReadRepositoryPort
  • list_series(...)

Módulo: application.engine.registry

InMemoryStrategyRegistry

Implementação simples em memória de StrategyRegistryPort.

Métodos:

• register(strategy_key, strategy)
• resolve(strategy_key)

Comportamentos:

• normaliza chave da estratégia para slug;
• rejeita registro duplicado;
• falha para chave desconhecida.

Módulo: application.engine.policy

passes_thresholds(instance, thresholds, primary_metric) -> bool

Valida se candidato atende limites de promoção.

select_champion(candidates, primary_metric, thresholds) -> ModelInstance | None

Seleciona campeão entre candidatos viáveis.

• direção MIN: menor valor da métrica primária;
• direção MAX: maior valor da métrica primária.

Módulo: application.engine.use_cases

Comandos e resultados

• TrainCandidatesAndPromoteChampionCommand(model_definition_id)
• ActivateModelInstanceCommand(model_definition_id, series_key, version, actor_id, reason, metric_snapshot, serving_alias)
• ActivationResult(series_key, promoted_version, strategy_key, metrics, registered_model_name, registered_model_version, serving_alias, audit_id)
• PromotionResult(series_key, promoted_version, strategy_key, metrics)
• RunForecastWithFallbackCommand(run, series)

train_candidates_and_promote_champion(...) -> list[PromotionResult]

Orquestra treino de candidatos por estratégia e promoção de campeão por série.

Pontos-chave:

• captura o ModelVersion corrente antes de gerar candidatos;
• resolve params de treino a partir do snapshot congelado dessa versão;
• lê StrategySpec.training_mode (series por default, batch via opt-in);
• mantém o fluxo legado para estratégias single-series;
• usa train_batch(...) apenas para estratégias batch-capable;
• aceita resultado misto em lote e só cria instâncias para séries bem-sucedidas;
• preserva promoção, ativação e versionamento por SeriesKey;
• vincula cada ModelInstance criada ao model_version usado no treino;
• permite compartilhar artifact_uri e mlflow_run_id entre instâncias do mesmo lote.
• quando model_registry é fornecido, persiste candidatos antes da promoção e delega a ativação para activate_model_instance(...).

activate_model_instance(...) -> ActivationResult

Promove explicitamente uma instância já treinada para um alvo servível.

Pontos-chave:

• cria PromotionAuditRecord em estado PENDING;
• registra versão concreta no registry quando necessário;
• grava metadados de registry na ModelInstance;
• promove a instância no agregado de domínio;
• sincroniza o alias operacional (champion por default);
• persiste auditoria em COMPLETED ou FAILED.

run_forecast_with_fallback(...) -> ForecastRun

Orquestra previsão com tentativa primária e fallback para versão anterior.

Pontos-chave:

• falha sem instância ativa;
• resolve params de predição a partir do model_version armazenado na instância;
• marca execução degradada quando fallback é usado;
• sempre persiste run no repositório de forecasting.
• pode emitir ForecastTelemetry via ForecastObservabilityPort sem acoplar observabilidade ao domínio.