Monitoramento e Saúde (Health Check)
====================================

O Menthor disponibiliza uma arquitetura de monitoramento em camadas. Cada endpoint foca em uma parte específica da *stack*, permitindo um diagnóstico rápido em caso de instabilidades.



Tabela Comparativa de Diagnóstico
---------------------------------

.. list-table::
   :header-rows: 1
   :widths: 25 25 40 10

   * - Endpoint
     - Nível de Teste
     - Objetivo Principal
     - Custo
   * - ``/ping``
     - **Infraestrutura**
     - Validar se o servidor está online.
     - Não
   * - ``/credentials``
     - **Segurança**
     - Validar se o Token X-API-Key está correto.
     - Não
   * - ``/llm_health_check``
     - **Integração**
     - Validar cota e resposta da OpenAI.
     - **Sim**
   * - ``/interaction_health_check``
     - **Lógica**
     - Validar sucesso da última interação.
     - Não

---

Detalhamento dos Níveis
-----------------------

1. Camada de Infraestrutura (Ping)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

O endpoint ``/ping`` é o *Health Check* primário. Deve ser utilizado por balanceadores de carga para verificar a disponibilidade do processo.

* **Acesso**: Público (Não requer API Key).
* **Retorno**: String ``"pong"``.

2. Camada de Segurança (Credentials)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Verifica se o *handshake* de segurança entre o cliente e o Menthor está funcional.

* **Erro 401**: Indica que a ``X-API-Key`` local está incorreta ou expirou.
* **Uso sugerido**: Validar a conexão durante a inicialização (startup) da aplicação cliente.

3. Camada de Inteligência (LLM Health)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Realiza uma chamada real ao modelo (ex: ``gpt-5-nano``) para garantir que o pipeline de IA está ativo e com saldo.



.. danger::
   **Atenção ao Custo de Operação**
   
   Este endpoint realiza uma inferência real. Cada chamada **consome tokens** da conta OpenAI. Evite monitoramentos automáticos de alta frequência (ex: a cada 1 minuto) para não exaurir sua cota desnecessariamente.

4. Camada de Lógica (Interaction Health)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Monitora o estado da última conversa processada pelo sistema. 

* **Status 200 (OK)**: Indica que o fluxo "Pergunta -> Contexto -> Resposta" ocorreu sem exceções.
* **Status 500 (ERROR)**: Indica uma falha lógica (ex: erro de sintaxe SQL ou arquivo vetorial corrompido).

---

Guia de Triagem Rápida
----------------------

.. tip::
   Se o ``/ping`` retornar **200** mas o ``/interaction_health_check`` retornar **500**, o servidor está online, mas há um erro na base de dados ou na lógica do *prompt* que impede a resposta da IA.

.. note::
   Para erros no ``/llm_health_check``, verifique sempre os limites de uso (Tier) na sua conta da OpenAI Dashboard.