Streaming em Tempo Real

O ChatCLI suporta streaming em tempo real de respostas de LLM, exibindo o texto character-by-character conforme ele e gerado pela API. Isso melhora significativamente a experiencia do usuário, eliminando a espera por respostas completas.

Interface StreamingClient

O streaming e implementado como uma interface opcional que provedores podem adotar:

type StreamingClient interface {
    LLMClient

    SendPromptStream(ctx context.Context, prompt string,
        history []models.Message, maxTokens int) (<-chan StreamChunk, error)

    SupportsStreaming() bool
}

A detecção e automatica via type assertion — provedores que implementam StreamingClient recebem streaming automaticamente:

if sc, ok := client.AsStreamingClient(c); ok {
    chunks, err := sc.SendPromptStream(ctx, prompt, history, maxTokens)
    // processa chunks em tempo real
}

Provedores que não implementam StreamingClient continuam funcionando normalmente. O ChatCLI faz fallback para SendPrompt (resposta completa) automaticamente.

StreamChunk

Cada chunk do streaming carrega:

Campo	Tipo	Descricao
`Text`	string	Texto incremental neste chunk (pode ser vazio)
`Done`	bool	`true` no chunk final
`Usage`	*UsageInfo	Dados de uso de tokens (apenas no chunk final)
`StopReason`	string	Razao da parada: `end_turn`, `max_tokens`, `tool_use`
`Error`	error	Erro durante streaming (termina o stream)

Contrato de Streaming

O canal retorna zero ou mais chunks de texto
O chunk final tem Done=true e pode incluir Usage e StopReason
Se ocorrer erro, um chunk com Error e enviado e o canal fecha
O canal fecha após o chunk final ou erro
O caller pode cancelar via contexto

Provedores com Suporte

Provedor	Streaming	Observacoes
Anthropic (API Key)	Sim	Streaming nativo via Messages API
Anthropic (OAuth)	Sim	Streaming via token OAuth
OpenAI	Sim	Streaming via Chat Completions
ZAI (Zhipu AI)	Sim	Streaming compatível com OpenAI
MiniMax	Sim	Streaming compatível com OpenAI
Moonshot (Kimi)	Sim	Streaming compatível com OpenAI
OpenRouter	Sim	Streaming via API OpenAI-compatible
Google (Gemini)	Não	Fallback para resposta completa
xAI (Grok)	Não	Fallback para resposta completa
GitHub Models	Não	Fallback para resposta completa
Ollama	Não	Fallback para resposta completa

Stream Watchdog

O Stream Watchdog monitora o stream para detectar stalls (interupcoes sem dados) e prevenir que o ChatCLI fique travado esperando indefinidamente:

Timeouts
Resultado

Timer	Duracao	Acao
Warning	45 segundos	Loga aviso de stall no log
Idle Timeout	90 segundos	Aborta stream e retorna conteúdo parcial

Ambos os timers sao resetados a cada chunk recebido. Se o provedor parar de enviar dados por 90 segundos, o watchdog interrompe o stream e retorna o texto já acumulado.

O watchdog retorna um WatchdogResult:

Campo	Descricao
`Text`	Texto acumulado até o momento
`Usage`	Dados de uso (se stream completou)
`StopReason`	Razao da parada
`WasStalled`	`true` se o watchdog disparou por timeout
`StallCount`	Numero de stalls detectados durante o stream

Configuração do Watchdog

Variável de Ambiente	Descricao	Default
`CHATCLI_STREAM_IDLE_TIMEOUT_SECONDS`	Timeout de idle em segundos	90

Em redes lentas ou com provedores que tem alta latência entre chunks, aumente o timeout para evitar interrupcoes prematuras. O padrão de 90 segundos e suficiente para a maioria dos cenarios.

Fallback para Não-Streaming

Quando o streaming não esta disponível (provedor não suporta ou erro na conexão), o ChatCLI faz fallback automático:

Tenta SendPromptStream()  → streaming em tempo real
Se não suportado → fallback para SendPrompt()
Resposta completa exibida de uma vez

A função DrainStream permite converter um stream em resposta completa quando necessário:

text, usage, stopReason, err := client.DrainStream(chunks)

Integração com TUI

No modo interativo (Bubble Tea), o streaming integra-se diretamente com o renderizador:

Cada chunk e emitido como evento via TUIEmitter
O modelo Bubble Tea atualiza a view incrementalmente
Markdown e renderizado progressivamente via Glamour
A barra de status mostra o estado do streaming em tempo real

No modo one-shot (-p), o streaming e desabilitado e DrainStream e usado para coletar a resposta completa antes de imprimir.

Próximos Passos

Recuperação de Contexto

O que acontece quando max_tokens e atingido durante streaming.

Provider Fallback

Chain de fallback entre provedores com e sem streaming.

Tool Use Nativo

Streaming com tool calls nativas.

UI de Progresso

Indicadores visuais durante streaming do agente.

​Interface StreamingClient

​StreamChunk

​Contrato de Streaming

​Provedores com Suporte

​Stream Watchdog

​Configuração do Watchdog

​Fallback para Não-Streaming

​Integração com TUI

​Próximos Passos

Recuperação de Contexto

Provider Fallback

Tool Use Nativo

UI de Progresso

Interface StreamingClient

StreamChunk

Contrato de Streaming

Provedores com Suporte

Stream Watchdog

Configuração do Watchdog

Fallback para Não-Streaming

Integração com TUI

Próximos Passos