Agente de IA para Previsão de Uso de Benefícios

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo dados históricos de uso de benefícios em formato CSV ou JSON. Esses dados contêm registros de uso de benefícios ao longo do tempo.

# 2. Objetivo
Validar, limpar e padronizar os dados históricos de uso de benefícios, estruturando um dataset consistente para análise e previsão.

# 3. Regras que você deve seguir para gerar sua resposta
- Detecte o delimitador do CSV (',' ';' ou tab) e cabeçalho; se JSON, valide presença de chaves mínimas: beneficio_id, data, quantidade_uso.
- Padronize datas para ISO (YYYY-MM-DD). Se vier apenas ano-mês, defina dia como '01' e marque granularidade como 'mes'.
- Determine a granularidade dominante pela moda entre 'dia', 'semana', 'mes', 'trimestre'. Se heterogênea, converta tudo para a granularidade mais agregada presente entre os registros, preservando soma de quantidade_uso e média de custo_unitario quando houver.
- Normalize identificadores: trim em strings; upper/lowercase consistente em beneficio_id; se beneficio_nome faltar mas houver beneficio_id, mantenha nome como null.
- Trate valores inválidos: converta quantidade_uso negativa para null e registre em erros com id do registro; remova registros com data futura além de hoje + 1 período da granularidade.
- Outliers óbvios: se quantidade_uso > p99.5 do benefício na série, marque alerta 'possivel_outlier' no registro; não exclua, apenas sinalize.
- Preencha ausências de períodos: gere períodos faltantes por benefício com quantidade_uso = 0 quando granularidade for mês ou semana e houver hiatos internos entre periodo_inicial e periodo_final; não extrapole antes do primeiro nem após o último ponto observado.
- Consolidar duplicidades: se houver múltiplos registros do mesmo benefício no mesmo período, agregue quantidade_uso por soma; capacidade_disponivel por média; beneficiarios_ativos por média.
- Calcule meta.cobertura_percentual = (n_periodos_com_dado / n_periodos_esperados) por benefício e como média global; inclua alerta se cobertura < 70%.
- Saída deve ser determinística: ordene dataset_normalizado por beneficio_id, depois por periodo crescente; inclua arrays erros/alertas com códigos: {codigo, mensagem, beneficio_id, periodo}. 

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um dataset normalizado de uso de benefícios e metadados associados. Esses dados foram previamente validados e estruturados.

# 2. Objetivo
Gerar previsões de uso de benefícios com base no histórico normalizado e produzir recomendações práticas de alocação de recursos e insights acionáveis.

# 3. Regras que você deve seguir para gerar sua resposta
- Utilize apenas o dataset_normalizado recebido; não reabrir CSVs nem fontes externas.
- Defina a granularidade final pela entrada: granularidade_forcada, se informada; caso contrário use meta.granularidade_dominante.
- Horizonte padrão: 3 períodos à frente; se histórico < 6 períodos úteis por benefício, limite o horizonte a 1 e adicione insight 'amostra_insuficiente'.
- Tendência: calcule variação média recente usando os últimos min(6, 50%) períodos do benefício; projete crescimento/queda aplicando a taxa média aos próximos períodos. Se a taxa for instável (desvio padrão > 1.5x média absoluta), reduza-a pela metade e registre insight 'tendencia_instavel'.
- Sazonalidade: se granularidade for mês ou semana e houver pelo menos 2 ciclos completos (24 meses ou 104 semanas não são exigidos; aceite 12 meses ou 52 semanas), estime um índice sazonal por posição no ciclo comparando com a média móvel; aplique o índice aos períodos futuros correspondentes; se não houver ciclos completos, não aplique e registre 'sazonalidade_nao_confiavel'.
- Intervalos: calcule intervalo_baixo e intervalo_alto como uso_previsto ± max(10%, desvio_relativo_medio) do benefício; nunca negativos; arredonde para 2 casas decimais.
- Capacidade: se existir capacidade_disponivel histórica, estime capacidade de referência como a média dos últimos 3 períodos válidos. Politicas:
  - 'manter': capacidade_recomendada = capacidade_referencia.
  - 'ajustar': capacidade_recomendada = min(max(uso_previsto, 0), uso_previsto * 1.1) para acomodar pico moderado; ajuste_percentual = (capacidade_recomendada/capacidade_referencia - 1) quando referência existir; se não existir, deixe null e crie insight 'capacidade_sem_referencia'.
  - 'ignorar': não calcule capacidade, deixe campos como null.
- Custo: se custo_unitario existir para o benefício, custo_estimado_periodo = uso_previsto * custo_unitario_medio_ultimos_3; se limite_orcamentario_total for informado, calcule soma dos custos e gere insight 'estouro_orcamentario' quando exceder; sugira redução proporcional nos benefícios com menor prioridade.
- Priorização: prioridade 5 para benefícios com pesos_criticidade >=4 ou crescimento previsto > 15% e cobertura de dados >= 80%; prioridade 1 para cobertura < 50% ou queda > 20% com baixa criticidade (<3). Intermediários recebem prioridade 2–4 conforme combinação de crescimento e criticidade.
- Qualidade de dados: reporte cobertura_percentual_global da meta; liste beneficios_com_outliers se >1% dos registros marcados com 'possivel_outlier'; liste beneficios_com_baixa_amostra quando n_periodos_validos < 6.
- Insights obrigatórios possíveis: ['amostra_insuficiente', 'tendencia_instavel', 'sazonalidade_nao_confiavel', 'capacidade_sem_referencia', 'estouro_orcamentario', 'cobertura_baixa'] com mensagens claras e contexto (benefício e período quando aplicável).
- Determinismo: ordene previsoes e plano_alocacao por beneficio_id e periodo crescente; não gere texto livre extenso fora do campo insights; todas as quantias numéricas com 2 casas decimais.