Skip to content
forecast-engine

domain.forecasting

Papel na engine

domain.forecasting modela o ciclo de execução de previsão como uma máquina de estados explícita. Isso garante que o produto preserve rastreabilidade e degradação controlada diante de falhas.

Módulo: domain.forecasting.model

ForecastPointValue

Campos:

  • value: Decimal
  • uom: UomCode
  • period_start: PeriodStart

Invariante:

  • value >= 0.

PredictionInterval

Campos:

  • lower: Decimal
  • upper: Decimal
  • confidence: Decimal

Invariantes:

  • lower <= upper
  • confidence em (0, 1)

ForecastPoint

Campos:

  • period_start: PeriodStart
  • value: ForecastPointValue
  • interval: PredictionInterval | None

Invariante:

  • period_start do ponto deve ser igual ao period_start de value.

ForecastRunStatus

  • REQUESTED
  • RUNNING
  • COMPLETED
  • FAILED

ForecastRun

Campos principais:

  • identificação: id, organization_id, model_definition_id
  • contexto do modelo: model_version, series_key, horizon_spec
  • unidade esperada: expected_uom
  • estado: status, points, failure_reason
  • metadata de execução: executed_model_version, fallback_from_version, degraded

Validações de inicialização:

  • id e model_definition_id não nulos;
  • model_version > 0;
  • series_key.organization_id igual a organization_id;
  • series_key.grain igual a horizon_spec.grain.

Propriedade

  • points -> tuple[ForecastPoint, ...]

Métodos de ciclo de vida

start() -> None

Permite transição para RUNNING a partir de REQUESTED ou RUNNING.

fail(reason: str) -> None

Marca run como FAILED com motivo não vazio.

set_executed_model_version(version: int) -> None

Define versão realmente executada. Se igual à model_version, limpa metadata de fallback degradado.

mark_degraded_fallback(fallback_from_version, executed_model_version) -> None

Marca execução degradada com fallback.

Regras:

  • ambas versões > 0;
  • versões devem ser diferentes.

record_point(point: ForecastPoint) -> None

Adiciona ponto e valida:

  • status não finalizado;
  • UOM do ponto igual a expected_uom;
  • sequência temporal monotônica com step do horizonte;
  • total de pontos não excede horizon_spec.periods.

set_points(points: list[ForecastPoint]) -> None

Substitui todos os pontos com validação equivalente a record_point.

complete(points: list[ForecastPoint] | None = None) -> None

Finaliza run como COMPLETED se:

  • não estiver FAILED;
  • houver exatamente horizon_spec.periods pontos;
  • executed_model_version estiver preenchido;
  • sequência de pontos e UOM forem válidas.

Metadata de fallback

Validação interna:

  • degraded=True exige fallback_from_version e executed_model_version;
  • degraded=False proíbe fallback_from_version.