Propósito

Papel da forecast-engine no produto

A forecast-engine é a camada de inteligência que transforma histórico de demanda em decisões de previsão utilizáveis pela plataforma. Em termos de criticidade, ela não é apenas uma biblioteca: é um componente de negócio que influencia disponibilidade de previsão, confiança dos usuários e qualidade de decisão operacional.

O que a engine precisa garantir

1. Integridade de estado: dados e transições inválidas devem falhar cedo.
2. Confiabilidade de inferência: falha do modelo ativo não pode derrubar o ciclo sem tentativa de fallback.
3. Rastreabilidade: execução, métricas, artefatos e versão usada precisam ser auditáveis.
4. Evolução segura: novas estratégias e infraestrutura sem quebra de regra de domínio.

Escopo funcional (o que está dentro)

A engine cobre:

• domínio de demanda (DemandSeries, DemandObservation);
• domínio de modelagem (ModelDefinition, ModelInstance, promoção);
• domínio de previsão (ForecastRun, pontos, intervalos e degradação);
• casos de uso de treino/promoção e previsão/fallback;
• contratos e adapters para integração (msgspec, Polars/Parquet, MLflow).

Limites explícitos (o que está fora)

Não é responsabilidade deste pacote:

• implementar algoritmos específicos de ML no core;
• definir persistência concreta de repositórios;
• publicar API HTTP/GraphQL.

Essas responsabilidades entram por ports, preservando isolamento do domínio.

Resumo de fronteira

Categoria	Dentro da engine	Fora da engine
Regra de negócio	invariantes, entidades, estados e transições	política de negócio de outros serviços
Orquestração	treino/promoção e inferência/fallback	APIs públicas HTTP/GraphQL
Infraestrutura	abstrações por ports	implementação concreta de banco, fila e orquestrador externo
Integração	contratos e mapeamentos	governança dos consumidores externos

Decisões de design que refletem essa criticidade

• Domínio primeiro: regras de negócio em domain/*.
• Orquestração controlada: fluxos críticos em application/engine/use_cases.py.
• Boundary adapters: integração sem contaminar o núcleo com I/O.
• Contratos estritos: serialização previsível e rejeição de payloads inválidos.

Resultado esperado para o produto

• previsões mais resilientes em produção;
• governança real de versões de modelo;
• menor risco de regressão ao evoluir estratégias e integrações.