Motor de Análise Cognitiva e Governança Menthor (Valgroup)

O motor de análise industrial do Menthor realiza uma interpretação técnica e semântica de detecções industriais registradas no banco de dados. O objetivo é transformar eventos brutos de telemetria em insights estruturados, combinando regras normativas industriais, análise contextual e interpretação cognitiva via LLM.

O sistema opera de forma híbrida em dois níveis de granularidade: a análise individual de detecções de falhas na linha (nível micro) e a consolidação histórica de ocorrências agrupadas (nível macro).

Esteira Micro: Análise Assíncrona de Detecção Industrial

Funcionamento do Pipeline Micro

Diferente das análises síncronas tradicionais, este endpoint utiliza processamento assíncrono em segundo plano para evitar bloqueios durante operações de alta latência envolvendo IA e persistência de dados.

Validação da Detecção: O sistema verifica imediatamente se o detection_id existe na tabela detections.
Agendamento Assíncrono: Após validação, o processamento é delegado para um worker utilizando BackgroundTasks.
Higienização e Normalização: Os dados industriais são tratados para remoção de inconsistências, normalização de defeitos e preparação contextual do payload analítico.
Enriquecimento Normativo: O pipeline adiciona regras técnicas e diretrizes industriais relacionadas aos defeitos identificados.
Análise Cognitiva via LLM: A IA interpreta a telemetria industrial, as anomalias detectadas, as observações operacionais, as regras normativas e o contexto do equipamento.
Cálculo de Score Híbrido: O sistema combina sinais quantitativos e interpretação qualitativa para gerar um score consolidado de confiabilidade.
Persistência e Integração Externa: O insight estruturado é salvo na tabela gt_vg_menthor_insights e a plataforma externa é notificada sobre sucesso ou falha do processamento.

Estrutura do Insight Gerado

O pipeline gera um diagnóstico estruturado contendo:

Fenômeno Detectado: Interpretação técnica do comportamento industrial observado.
Justificativa Técnica: Explicação baseada em telemetria, contexto operacional e regras normativas.
Ação Recomendada: Sugestão operacional ou investigativa gerada pela IA.
Score de Confiança: Indicador híbrido de confiabilidade da análise produzida.

Cálculo do Score de Confiança

O Menthor AI utiliza um modelo híbrido para reduzir dependência exclusiva da LLM e aumentar a auditabilidade do diagnóstico.

\[score\_final = (score\_telemetria \times 0.70) + (score\_llm \times 0.30)\]

Onde score_telemetria representa a avaliação quantitativa baseada em sinais industriais e consistência operacional, e score_llm representa a avaliação qualitativa produzida pela interpretação contextual da IA.

Esteira Macro: Análise Consolidada de Ocorrências (Map-Reduce)

Enquanto a esteira micro foca no sintoma instantâneo, a esteira macro executa uma compressão de contexto semântica (Map-Reduce) sobre um lote dinâmico de eventos vinculados para emitir relatórios de Causa Raiz (RCA).

Funcionamento do Pipeline Macro

Captura do Contexto Pai: O worker assíncrono utiliza o occurrence_id para extrair os registros de negócio inseridos na tabela occurrences.
Agrupamento Cronológico de Histórico: O sistema realiza um JOIN triplo na tabela relacional intermediária occurrence_detections para resgatar todas as detecções ativas vinculadas, ordenando-as estritamente pelo tempo (ORDER BY d.timestamp ASC).
Redução de Ruído por Whitelist: Apenas os campos operacionais dotados de valor analítico são repassados ao prompt do modelo de linguagem. Dados administrativos de auditoria física de tabelas são integralmente descartados da janela de contexto.
Síntese Cognitiva Semântica: O LLM correlaciona os micro-insights previamente armazenados de cada detecção individual, eliminando repetições e contradições lógicas, gerando uma conclusão coesa sobre as causas físicas operacionais.

Modularização via Dicionários de Dados

O pipeline utiliza metadados estruturados para manter o isolamento físico entre o código e o schema de banco de dados. A função geradora de prompt traduz dinamicamente o mapeamento no padrão técnico:

* [nome_do_campo]: '[valor_real_do_banco]' # [Descrição Curta do Atributo]

Se colunas livres contiverem valores nulos ou ausentes de preenchimento (como o campo de criticidade do usuário), a camada relacional injeta a palavra-chave NULL, permitindo que a inteligência identifique lacunas operacionais de preenchimento no chão de fábrica.

Diretrizes e Restrições de Compliance Macro

Avaliação da Ação Humana: A IA confronta diretamente a contramedida registrada no campo solution pelo operador contra a evolução temporal dos alertas e emite um parecer se a manobra técnica sanou a causa raiz ou atuou como paliativo superficial.
Regra de Alçada: Se os micro-insights acumulados denunciarem falhas persistentes ou crônicas de desgaste de hardware, o modelo de linguagem é proibido de sugerir ações repetitivas de processo ao operador, ordenando de forma mandatória a abertura de uma Solicitação de Serviço (SS) para a equipe de Manutenção Especializada.
Métrica de Confiança Semântica: O campo certeza_semantica_ia segue regras matemáticas estritas de governança: * Nota entre 0.85 e 1.0: Aplicada se, independente do critério de agrupamento (temporal, por lote ou por tipo de falha), a IA conseguir mapear com clareza o nexo causal ou a cronologia dos fatos com base nos dados disponíveis. * Nota entre 0.70 e 0.84: Aplicada se houver ausência severa de micro-insights parciais no lote ou degradação de dados que impossibilite uma conclusão gerencial segura.

Interface e Roteamento HTTP (FastAPI)

POST /llm_analysis/detections

Valida uma detecção industrial registrada no banco de dados e delega o processamento analítico completo para execução assíncrona em segundo plano.

Query Parameters:

detection_id (string) – Identificador global único (UUID v4) da detecção técnica alvo.

Status Codes:

202 Accepted – Registro localizado com sucesso; o pipeline do worker em background foi inicializado.
404 Not Found – O identificador fornecido não foi localizado na tabela relacional de detecções.
500 Internal Server Error – Falha interna de comunicação com as instâncias do banco de dados MySQL na Azure.

POST /llm_analysis/occurrences

Valida uma ocorrência cadastrada e inicia o pipeline macro de consolidação e auditoria de causa raiz técnica.

Query Parameters:

occurrence_id (string) – Identificador mestre (UUID v4) do agrupamento de eventos na tabela.

Status Codes:

202 Accepted – ID validado; processamento de Map-Reduce semântico delegado às tarefas em segundo plano.
404 Not Found – Ocorrência não localizada na tabela pai do banco de dados.
500 Internal Server Error – Erro sistêmico de processamento ou falha relacional de transação.

Contratos de Resposta da API

Esquema Assíncrono de Confirmação (InsightAsyncResponse):

{
  "status": "Requisição aceita.",
  "details": {
    "message": "ID localizado com sucesso. O processamento foi iniciado em segundo plano.",
    "id": "0a2da3d1-5f96-4b06-8dfe-8ac35f7d8536"
  }
}

Interpretando os Estados do Pipeline

O endpoint retorna imediatamente após o aceite do processamento assíncrono.

Estados do Pipeline de Processamento
Status	Significado
202 Accepted	O processamento foi aceito e iniciado em segundo plano.
404 Not Found	O identificador informado (detecção ou ocorrência) não existe na base de dados.
500 Internal Server Error	Falha durante validação, infraestrutura ou execução do worker.

Resiliência e Tratamento de Falhas

O pipeline utiliza mecanismos de proteção para evitar travamentos prolongados e falhas silenciosas durante integrações com IA e serviços externos.

Timeout da LLM: Chamadas para análise cognitiva possuem timeout dedicado para evitar bloqueios indefinidos.
Timeout Global do Worker: O pipeline completo possui timeout máximo de execução de 120 segundos regido por asyncio.wait_for.
Notificação de Falhas: Qualquer erro durante o processamento gera notificação automática para a plataforma externa.
Persistência Condicional: O insight somente é salvo após validação completa da resposta estruturada da IA (Structured Outputs).

Limites e Performance

Execução Assíncrona: O endpoint não aguarda a conclusão da análise da LLM.
Rate Limiting: O endpoint é protegido no escopo counter_name="PROCESSING" para evitar picos de consumo computacional e custo com IA.
Latência Variável: O tempo total do pipeline pode variar conforme o tamanho do lote histórico, quantidade de anomalias, complexidade contextual e latência da infraestrutura de LLM do Azure OpenAI.

Importante

O retorno 202 Accepted indica apenas que o processamento foi aceito. O sucesso final do pipeline depende da execução completa do worker assíncrono.