hm-llm-guardrails

/hm-llm-guardrails — Patterns LLM-app (v2)

Você está agora em modo LLM guardrails. Seu trabalho e validar que app que integra LLM (Claude, GPT, Gemini, Llama via API) tem todos os guardrails de produção em pe. Não esta otimizado pra cobrir um caso de uso. Cobre TODOS os patterns recorrentes.

Princípio central

LLMs sao componentes não-deterministicos com custo variavel e latencia variavel, em provedores externos. Tratar como qualquer outra dependência externa: rate limit, retry, fallback, timeout, dedupe, observabilidade. Sem guardrails, você não tem produto — tem demo.

Quando usar

• Antes de shippar feature LLM pra produção
• Quando custo de API explode sem explicacao
• Quando user reclama de "respostas demoram demais", "trava no meio", "respondeu coisa errada"
• Quando adicionar tool calling, agentes, ou chat persistente
• Apos integrar provider novo (multi-provider routing)

Patterns obrigatorios

1. Sliding window de chat history

Problema: chat history sem limite cresce sem limite. Conversa de 50+ turns estoura context window (200k tokens em Sonnet 4.6 / 1M com beta header) ou explode custo.

Pattern:

// SQL/ORM: últimas N messages, ordem cronologica preservada
const recent = await db
  .select()
  .from(messages)
  .where(eq(messages.threadId, id))
  .orderBy(desc(messages.createdAt))
  .limit(CHAT_HISTORY_LIMIT) // tipicamente 30
const history = recent.reverse()

Limite típico: 30 turns (15 user/assistant pares). Suficiente pra contexto recente, longe do limite de tokens.

Avancado: Sliding window + summary das mensagens antigas (compactacao). Soma das duas no prompt = janela infinita efetiva. Custa 1 LLM call extra periodicamente pra gerar summary.

2. Lazy client factory (sem singleton stale)

Problema: SDK client (Anthropic, OpenAI) instanciado no module-load com getApiKey(). Se user trocar key em runtime (settings page), continua usando a antiga até restart.

Pattern:

let cachedClient: { key: string; client: Anthropic } | null = null

export class ApiKeyMissingError extends Error {}

export function getAnthropic(): Anthropic {
  const key = getApiKey()
  if (!key) throw new ApiKeyMissingError()
  if (cachedClient && cachedClient.key === key) return cachedClient.client
  cachedClient = { key, client: new Anthropic({ apiKey: key, timeout: 90_000, maxRetries: 1 }) }
  return cachedClient.client
}