Pular para o conteúdo principal
O ChatCLI suporta uma cadeia de failover automatico entre provedores LLM. Quando o provedor primario falha (rate limit, timeout, erro de servidor), o sistema tenta automaticamente o proximo provedor na cadeia, de forma totalmente transparente.

​
Como Funciona

A cadeia de fallback e uma lista ordenada de provedores. Cada request percorre a lista ate obter sucesso ou esgotar todas as opcoes: 
Request -> OpenAI (primario)
             | falhou (rate limit)
           Claude (secundario)
             | falhou (timeout)
           Google AI (terciario)
             | sucesso
           Resposta retornada ao usuario

​
Configuracao

# Lista ordenada de provedores (primeiro = maior prioridade)
export CHATCLI_FALLBACK_PROVIDERS="OPENAI,CLAUDEAI,GOOGLEAI,COPILOT"

# Modelo especifico por provedor (opcional)
export CHATCLI_FALLBACK_MODEL_OPENAI="gpt-4o"
export CHATCLI_FALLBACK_MODEL_CLAUDEAI="claude-sonnet-4-20250514"
export CHATCLI_FALLBACK_MODEL_GOOGLEAI="gemini-2.0-flash"
export CHATCLI_FALLBACK_MODEL_COPILOT="gpt-4o"

# Controle de retentativas e cooldown
export CHATCLI_FALLBACK_MAX_RETRIES="2"       # tentativas por provedor
export CHATCLI_FALLBACK_COOLDOWN_BASE="30s"    # cooldown base
export CHATCLI_FALLBACK_COOLDOWN_MAX="5m"      # cooldown maximo

​
Classificacao de Erros

O sistema classifica automaticamente cada falha para decidir a estrategia:
ClasseComportamentoExemplos
rate_limitAguarda backoff, depois retentaHTTP 429, “too many requests”
timeoutRetenta ate maxRetriesDeadline exceeded, connection timeout
server_errorRetenta ate maxRetriesHTTP 500, 502, 503
auth_errorNao retenta — avanca na cadeiaHTTP 401, 403, “invalid api key”
model_not_foundNao retenta — avanca na cadeiaHTTP 404, “model not found”
context_too_longNao retenta — avanca na cadeia”context length exceeded”

​
Cooldown Exponencial

Apos falhas consecutivas, o provedor entra em cooldown com backoff exponencial:
Falhas ConsecutivasCooldown
130s
260s
3120s
4240s
5+300s (max)
Erros de autenticacao recebem cooldown maximo imediato (5m). Um request bem-sucedido limpa todo o cooldown do provedor. Use ResetCooldowns() para limpar manualmente (ex: apos atualizar credenciais).

​
Monitoramento de Saude

A cadeia rastreia o estado de cada provedor em tempo real: 
health := chain.GetHealth()
for _, h := range health {
    fmt.Printf("Provider: %s, Available: %v, Fails: %d, Cooldown: %v\n",
        h.Name, h.Available, h.ConsecutiveFails, h.CooldownUntil)
}
Campos rastreados por provedor:
CampoDescricao
AvailableSe o provedor esta disponivel para requests
ConsecutiveFailsNumero de falhas consecutivas
LastErrorClassTipo da ultima falha
CooldownUntilQuando o cooldown expira
LastErrorAtTimestamp da ultima falha

​
Tool Use com Fallback

A cadeia de fallback tambem suporta SendPromptWithTools para provedores que implementam a interface ToolAwareClient. Provedores sem suporte a tool use nativo sao automaticamente ignorados na cadeia de tool calls.

​
Boas Praticas

Ordene por custo-beneficio

Coloque o provedor mais barato/rapido primeiro na cadeia.

Diversifique provedores

Misture provedores de diferentes empresas para resiliencia real.

Configure modelos por provedor

Use modelos equivalentes em capacidade para manter qualidade.

Monitore a saude

Verifique regularmente se algum provedor esta em cooldown persistente.
Cada provedor na cadeia precisa de sua propria API key configurada. Certifique-se de configurar as chaves de todos os provedores listados em CHATCLI_FALLBACK_PROVIDERS.