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.

Matriz de Escolha de Motor
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": "..."}.

Tipos de Dados Suportados
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:

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

Importante

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)

Nota

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)

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"
     }'