===================================================
Motores de Entrega de Mensagem (Streaming e Direto)
===================================================

O ecossistema disponibiliza quatro formas de interação com a IA. Enquanto as três primeiras utilizam *Server-Sent Events* (SSE) para respostas em tempo real, a quarta é um canal direto de disparo para o WhatsApp.

.. list-table:: Matriz de Escolha de Motor
   :header-rows: 1
   :widths: 25 20 45 10

   * - Endpoint
     - Tipo
     - Caso de Uso Principal
     - Fluxo
   * - ``/token_streaming``
     - SSE
     - Interfaces de Chat Web/Mobile (UX fluida).
     - Stream
   * - ``/sentence_streaming``
     - SSE
     - Integrações com Voz (TTS) ou leitura assistida.
     - Stream
   * - ``/block_streaming``
     - SSE
     - **WhatsApp Web** e integrações via Dashboards.
     - Stream
   * - ``/send_prompt_wpp``
     - POST
     - **Envio Direto/Notificação (MIA).**
     - Síncrono

---

Especificação de Saída (EventSource)
====================================

Para os endpoints de **Streaming** (SSE), os dados são entregues linha a linha no formato ``data: {"tipo": "...", "data": "..."}``.

.. list-table:: Tipos de Dados Suportados
   :header-rows: 1
   :widths: 20 20 60

   * - Tipo (tipo)
     - Conteúdo (data)
     - Comportamento no Front-end
   * - ``msg``
     - String
     - Texto para exibição (tokens, sentenças ou blocos).
   * - ``dynamic_chart``
     - JSON Spec
     - Renderizar gráfico interativo (Plotly/ECharts).
   * - ``image``
     - Base64 (PNG)
     - Exibir imagem estática ou gráfico convertido.
   * - ``pdf`` / ``vcard``
     - Base64
     - Disponibilizar para download ou visualização.

---

Detalhamento dos Motores de Streaming
=====================================

1. Token Streaming
------------------
Entrega o conteúdo de forma granular (palavra por palavra). Ideal para reduzir a latência percebida em aplicações web.

* **Rota**: ``POST /token_streaming``

2. Sentence Streaming
---------------------
Agrupa os tokens em frases completas antes do disparo. O servidor aguarda uma pontuação final (``.``, ``!``, ``?``).

* **Rota**: ``POST /sentence_streaming``
* **Destaque**: Evita que sistemas de Voz (TTS) narrem palavras cortadas.

3. Block Streaming (WhatsApp Web Ready)
---------------------------------------
Atua como um *Middleware* de canal. Projetado para suportar as limitações de interfaces de mensagens e dashboards de terceiros.

* **Markdown Adaptativo**: Converte automaticamente negritos (``**text**`` para ``*text*``).
* **Fallback de Gráficos**: Converte ``dynamic_chart`` em ``image`` (PNG) automaticamente.
* **Agrupamento**: Aguarda a conclusão de blocos lógicos para evitar "picotar" a mensagem.

---

Envio Direto: WhatsApp (MIA)
============================

O endpoint ``/send_prompt_wpp`` é uma função síncrona especializada. Ele processa a solicitação e realiza o envio imediato para o destinatário final sem manter conexão aberta com o cliente.

* **Rota**: ``POST /send_prompt_wpp``

Regras de Processamento:
------------------------
1. **Sanitização**: O campo ``phone`` é limpo de caracteres especiais, mantendo apenas dígitos.
2. **Injeção de Contexto**: O telefone é inserido no ``payload``, vinculando a IA ao contato. Isso garante a integridade de histórico de usuário.
3. **Gateway**: A resposta é enviada diretamente ao serviço de mensageria configurado.

.. important::
   Diferente dos streamings, este endpoint retorna apenas um **preview** de 100 caracteres. A entrega integral ocorre no número de telefone do usuário.

---

Configurações Globais (Payload e Telefone)
==========================================

Uso do Payload (Menthor vs Geral)
---------------------------------
O campo ``payload`` é universal. No ecossistema Menthor, ele aceita a chave ``id_context``:

* **Com id_context**: A IA consulta especificamente aquela base de dados.
* **Sem id_context**: Utiliza o contexto padrão ou o último ativo para o usuário.

Normalização de Telefone (Phone)
--------------------------------
O campo ``phone`` é sanitizado em todos os endpoints. Aceita o padrão E.164 (``+55...``) ou variações brasileiras (DDD + número), realizando a correção internamente.

Manutenção de Conexão (Ping)
----------------------------
.. note::
   Os endpoints SSE utilizam ``ping=10``. O servidor envia um sinal a cada 10 segundos para evitar que a conexão seja encerrada por *timeouts* de rede.

Exemplo de Requisição (cURL)
----------------------------
.. code-block:: bash

   curl -X POST http://localhost:8000/send_prompt_wpp \
        -H "Content-Type: application/json" \
        -d '{
          "user_prompt": "Envie relatorio de vendas do mês de fevereiro",
          "phone": "44993221991",
          "email": "admin@empresa.com"
        }'