Avaliação de Qualidade de Dados (Menthor DB)
============================================

O motor de auditoria do Menthor DB realiza uma análise técnica e semântica nas tabelas de banco de dados vinculadas a um contexto. O objetivo é garantir que os dados estejam íntegros e que os metadados sejam claros o suficiente para a geração precisa de consultas SQL.

Funcionamento do Diagnóstico
----------------------------

Diferente das operações de ingestão, este endpoint é **síncrono** e utiliza processamento paralelo para avaliar todas as tabelas do esquema simultaneamente.

1. **Extração de Schema**: O sistema recupera as definições de tabelas e colunas associadas ao ``id_context``.
2. **Métricas Técnicas**: Calcula scores estatísticos como completitude (*completeness*), unicidade (*uniqueness*) e aderência ao schema.
3. **Análise Qualitativa (LLM)**: A IA avalia se os nomes de tabelas e descrições de colunas são ambíguos ou se precisam de mais contexto para evitar erros de interpretação.
4. **Consolidação**: Gera um relatório único que separa sucessos de falhas técnicas.

Detalhamento das Métricas de Auditoria
--------------------------------------

O Menthor DB utiliza algoritmos estatísticos aplicados sobre uma amostra (default: 200 linhas) para extrair os seguintes indicadores:

* **Completitude (20% do peso)**:
  Calculada pela razão de células não-nulas. 
  .. math:: (1 - \frac{nulos}{total\_celulas}) \times 10

* **Unicidade (20% do peso)**:
  Avalia a taxa de duplicidade de linhas na amostra.
  .. math:: (1 - \frac{duplicados}{total\_linhas}) \times 10

* **Aderência ao Schema (30% do peso)**:
  Verifica se o tipo de dado real no banco (ex: ``int64``) corresponde ao tipo declarado no metadado (ex: ``integer``).

* **Design Semântico - LLM (30% do peso)**:
  Avaliação qualitativa que julga se a nomenclatura e descrições permitem que um humano (ou a própria IA) entenda o propósito dos dados sem ambiguidade.

Interpretando o Score de Qualidade
----------------------------------

O campo ``overall_score`` (0.0 a 10.0) reflete a confiabilidade dos dados para uso em linguagem natural.

.. list-table:: Régua de Maturidade Menthor DB
   :widths: 20 80
   :header-rows: 1

   * - Score
     - Diagnóstico e Ação
   * - **> 9.0**
     - **Dados Prontos**: Alta precisão em SQL automático e geração de insights analíticos.
   * - **6.0 a 8.9**
     - **Ajustes Necessários**: Siga as ``suggestions`` da IA para renomear colunas técnicas ou enriquecer descrições.
   * - **< 6.0**
     - **Inconsistente**: Alto risco de alucinações da IA. Os dados podem estar mal estruturados ou faltar metadados básicos.

Resiliência do Relatório
------------------------

O endpoint utiliza uma abordagem de **sucesso parcial** para garantir que uma única tabela corrompida não impeça a análise do restante do banco de dados:

* **Relatórios bem-sucedidos**: Listados em ``table_reports``.
* **Relatórios de falha**: Listados em ``failed_reports``, contendo o erro técnico específico que impediu a análise daquela tabela (ex: falha de conexão ou timeout).

.. important::
   Esta avaliação deve ser realizada sempre que houver mudanças estruturais no banco de dados (DDL) ou após o uso do endpoint ``/databases/receive_documents_db``.

Limites e Performance
---------------------

* **Rate Limiting**: O endpoint é protegido para evitar picos de custo com LLM.
* **Timeout**: Em contextos com dezenas de tabelas, o tempo de resposta pode ser maior devido ao processamento paralelo de cada diagnóstico.