Decomposição de variação

Selo

• Motor: Determinístico (sem LLM)
• Maturidade: Preview
• Medição: Verificável por teste

1. O que faz

Pega a variação de uma métrica entre o período atual e o anterior (o mesmo par que o Δ% dos KPIs usa) e a decompõe por dimensão: quanto cada categoria, filial, canal ou produto contribuiu para o número subir ou cair — incluindo os segmentos que apareceram e os que saíram entre um período e outro. A soma das contribuições fecha com a variação total; o que não fecha aparece como resíduo explícito, nunca é escondido.

2. Determinístico ou LLM?

Determinístico. É aritmética (soma compensada para não perder centavos em cifras grandes, divisão segura, desempate alfabético). Nenhum modelo de linguagem decide o que contribuiu. Quando a narrativa de insights ou de relatório usar esta evidência, o LLM recebe a conta pronta e só redige — ele não calcula.

3. Dados enviados e egress

Nenhum. O cálculo roda no servidor do produto sobre o snapshot do painel. Se a evidência for depois narrada por uma capacidade com LLM, valem as regras de egress daquela capacidade (privacidade, egress e orçamento).

4. Privacidade e retenção

Opera sobre o snapshot já filtrado por RLS do painel — quem não vê uma filial no visual também não a vê na decomposição. Trabalha com dimensões categóricas e métricas numéricas; texto nunca vira métrica. Não grava nada além do que o snapshot já guarda.

5. Tokens, custo e orçamento

Não se aplica: custo zero, não consome o orçamento de IA.

6. Como ligar, quem pode usar e como desligar

Nesta versão, não há botão na interface. O motor está implementado e provado por testes, mas a superfície do produto — "explique a variação" dentro dos insights do painel e da narrativa do relatório — ainda está em construção. Não há nada para ligar ou desligar; quando a superfície chegar, seguirá o kill switch e os papéis da capacidade que a exibir.

7. Recusas

• Sem período anterior (primeiro snapshot): não há variação a decompor; a capacidade não inventa uma base.
• Base zero: a variação percentual sai vazia e sinalizada, nunca Infinity nem NaN; a contribuição absoluta continua válida.
• Valores não numéricos na métrica contam zero nos dois períodos — a regra é simétrica, então o fechamento não quebra.

8. Limitações e ausência de causalidade

Contribuição não é causa. Dizer que "a filial SP respondeu por 60% da queda" é aritmética sobre o dado; não diz por que SP caiu. A decomposição não detecta sazonalidade, não compara com meta e não cruza dimensões (uma dimensão por vez). Para métricas que são razões (ticket médio = receita ÷ pedidos) existe uma decomposição própria, porque somar contribuições de uma razão como se fossem valores absolutos daria conta errada.

9. Como validar

• Conjunto de testes de referência: fechamento Σ contribuições == Δ total dentro de uma tolerância explícita, testado em estilo property-based (muitas entradas aleatórias com semente fixa); segmentos novos e que saíram; base zero; determinismo (mesma entrada → mesma saída, byte a byte).
• Quando a superfície estiver disponível: some manualmente as contribuições listadas e compare com o Δ do KPI do painel — precisa bater, e o resíduo informado precisa ser o que falta.

Estado & evidência: Preview; motor GA-candidato na matriz de capacidades (fechamento matemático provado); exposição na interface pendente.