Menthor DB: Banco de Dados Estruturados
=======================================

O ecossistema **Menthor DB** gerencia o ciclo de vida completo de contextos de bancos de dados, desde a ingestão e geração de metadados via IA até a auditoria de qualidade e exclusão física.

Fluxo de Processamento
----------------------

O processamento no Menthor DB é predominantemente **assíncrono**. A API responde imediatamente para garantir alta disponibilidade, enquanto as tarefas custosas ocorrem em segundo plano.

1. **Ingestão**: O cliente inicia o processo via ``/databases/create_description_db`` ou ``/databases/receive_documents_db``.
2. **Resposta Imediata**: Confirmação de entrada na fila ou persistência inicial.
3. **Processamento/Análise**: Validação de schema, análise via LLM (se necessário) e auditoria de qualidade.
4. **Notificação (Webhook)**: Ao finalizar, o sistema envia um POST para a plataforma externa:

   .. code-block:: none

      /company-contexts/partners/context/{id_context}/processed

.. important::
   O campo ``status`` na notificação pode ser ``SUCCESS`` ou ``ERROR``. Em caso de erro, o processo deve ser reiniciado manualmente. O histórico de interações é resetado automaticamente a cada nova carga para manter a consistência da IA.

Modelos de Operação
-------------------

* **Geração por IA (create_description_db)**: 
  Endpoint: ``/databases/create_description_db``
  Para tabelas sem documentação. A IA gera descrições e tipos de dados. Apresenta maior latência e consumo de tokens.
* **Sincronização Direta (receive_documents_db)**: 
  Endpoint: ``/databases/receive_documents_db``
  Para metadados já estruturados. Valida idempotência (não salva se for idêntico) e persiste o estado para uso do motor de chat.
* **Avaliação de Qualidade (evaluate-context-quality)**:
  Endpoint: ``/databases/evaluate-context-quality``
  Realiza auditoria técnica (completude/unicidade) e semântica nas tabelas de um contexto.
* **Exclusão de Contexto (delete_documents_db)**:
  Endpoints: ``/databases/delete_documents_db``
  Remove permanentemente os arquivos de metadados locais. Operação segura e idempotente (retorna sucesso mesmo se o arquivo já não existir).