Skip to content
forecast-engine

contracts

Papel na engine

contracts define o idioma de integração da forecast-engine com o restante do produto. Como componente central, a engine depende desses contratos para evitar ambiguidades de payload e quebrar menos em evolução de versões.

Visão geral

Os contratos em src/contracts são definidos com msgspec.Struct e forbid_unknown_fields=True.

Benefícios:

  • validação rígida de payload;
  • serialização previsível;
  • fronteira estável entre serviços.

contracts.common

Tipos e enums:

  • PeriodStartContract = datetime com timezone obrigatório
  • TimeGrainContract: daily, weekly, monthly
  • UomCodeValueContract: EA, KG, L, BOX, M, M2, M3

Structs:

  • OrganizationIdContract { value: UUID }
  • ExternalKeyContract { system: str, value: str }
  • UomCodeContract { value: UomCodeValueContract }
  • DemandQuantityContract { value: str, uom: UomCodeContract }

contracts.demand

  • SeriesKeyContract
    • organization_id, sku_id, store_id, sku_key, store_key, grain
  • DemandObservationContract
    • id, period_start, quantity, source, created_at
  • DemandSeriesContract
    • id, key, observations, created_at

contracts.modeling

Enums:

  • MetricDirectionContract: min, max
  • ModelVersionStatusContract: draft, active, deprecated
  • ModelInstanceStatusContract: draft, active, deprecated

Structs de especificação:

  • ModelNameContract
  • WindowSpecContract
  • LagSpecContract
  • HorizonSpecContract
  • MetricSpecContract
  • EvaluatorSpecContract
  • StrategySpecContract

Structs de estado:

  • ModelVersionContract
  • ModelInstanceContract
  • ModelDefinitionContract

Campos operacionais relevantes:

  • ModelInstanceContract.model_version
  • ModelInstanceContract.registered_model_name
  • ModelInstanceContract.registered_model_version
  • ModelInstanceContract.serving_alias
  • ModelInstanceContract.promoted_at

contracts.forecasting

Enum:

  • ForecastRunStatusContract: requested, running, completed, failed

Structs:

  • ForecastPointValueContract
  • PredictionIntervalContract
  • ForecastPointContract
  • ForecastRunContract

contracts.operations

Enum:

  • PromotionAuditStatusContract: pending, completed, failed

Structs:

  • PromotionAuditRecordContract

API pública agregada

contracts.__init__ exporta os contratos mais usados para import direto, incluindo:

  • demanda (DemandSeriesContract, SeriesKeyContract, …)
  • modelagem (ModelDefinitionContract, StrategySpecContract, …)
  • previsão (ForecastRunContract, ForecastPointContract, …)
  • tipos comuns (OrganizationIdContract, TimeGrainContract, UomCodeContract)

Boas práticas de integração

  1. Validar payload de entrada com msgspec.json.decode(..., type=Contrato).
  2. Persistir valores monetários/quantitativos como string decimal nos contratos.
  3. Enviar sempre datetime com timezone (Z/UTC).
  4. Não enviar campos extras, pois serão rejeitados.