Constraints

Constraints sao como o cliente coloca uma coleira na otimizacao da Floopy. Sao declarativos — voce os define em codigo via PUT /v1/constraints ou no dashboard em /routing/constraints. Sao non-LLM — toda checagem e uma comparacao numerica ou booleana, sem chamadas extras a provedores no caminho quente. E sao auditaveis — toda mudanca e registrada com hash SHA-256 de before e after no log de auditoria.

No v2 o conjunto e de nove campos, agrupados em tres secoes: limites de qualidade, limites de custo e portoes de promocao.

Quando um candidato viola um constraint, ele e filtrado com um motivo tipado que aparece em filtered[].reason no audit row e tambem no texto de explicacao. Nao ha override silencioso.

Limitam o custo de qualidade que o router esta disposto a pagar por um candidato mais barato ou de maior confianca.

max_outcome_variance e novo no v2. Estritamente maior que zero — definir exatamente 0.0 e rejeitado com 400 out_of_range_max_outcome_variance porque e inalcancavel na pratica e quase certamente uma configuracao errada.

Limitam quanto o router pode mover em custo sem forcar validacao extra.

max_cost_drop_without_validation e novo no v2. A intuicao: um candidato que de repente parece 90 % mais barato que a baseline e mais provavel de ser uma queda de qualidade do que um almoco gratis. Definir max_cost_drop_without_validation = 0.5 significa “se a historia de economia ultrapassa 50 %, prove em shadow primeiro.”

Limitam quando o router pode promover um candidato acima do trafego baseline.

min_samples_before_promotion, max_outcome_variance, max_cost_drop_without_validation e require_shadow_before_live sao os quatro novos campos lancados no v2.

A janela de validade para require_shadow_before_live tem default de 30 dias e e configuravel por workspace — fale com o suporte para ajustar.

Quando o router rejeita um candidato por violacao de constraint, filtered[].reason no audit row carrega um motivo tipado. O enum fechado e:

A ordem em que os constraints sao avaliados e fixa — quando mais de um teria rejeitado o candidato, a auditoria mostra o primeiro que disparou. A ordem e: max_cost_increase, max_regression, confidence_threshold, min_samples_before_promotion, max_outcome_variance, max_cost_drop_without_validation, require_shadow_before_live.

{
  "max_regression": { "value": 0.02, "window": "rolling_24h" }
}

Qualquer candidato cuja queda rolante de 24 h em qualidade composta vs. baseline ultrapasse 2 pontos percentuais e filtrado com reason: "constraint_max_regression". Todo o resto e com o router.

{
  "min_samples_before_promotion": 50
}

Um candidato com n_samples < 50 e filtrado com reason: "constraint_min_samples". O painel lateral de decisao no dashboard renderiza a contagem samples de evidence para o cliente verificar o portao.

{
  "max_cost_drop_without_validation": 0.8,
  "require_shadow_before_live": true
}

Qualquer candidato cuja queda fracionaria esperada de custo vs. baseline ultrapasse 0.8 e filtrado com reason: "constraint_cost_drop_requires_validation" a menos que tenha um experimento shadow aprovado na janela de validade. Os dois constraints funcionam juntos: require_shadow_before_live exige que toda promocao passe por shadow; max_cost_drop_without_validation exige que especificamente o caminho de economia suspeita passe por shadow mesmo que o operador nao tenha ligado o portao geral.

{
  "max_outcome_variance": 0.4
}

Um candidato cuja variancia rolante de resultados ultrapasse 0.4 e filtrado com reason: "constraint_high_variance". Util em rotas onde consistencia importa mais que uma resposta perfeita ocasional.

{
  "confidence_threshold": 0.7
}

O router cai para a baseline sempre que confidence < 0.7 e emite reason: "constraint_confidence_below_threshold" para todos os outros candidatos. Veja Metodologia de Confianca para o que confidence mede.

{
  "max_regression":               { "value": 0.02, "window": "rolling_24h" },
  "max_cost_increase":            { "value": 0.10, "window": "rolling_24h" },
  "confidence_threshold":         0.7,
  "min_samples_before_promotion": 50,
  "max_outcome_variance":         0.4,
  "max_cost_drop_without_validation": 0.8,
  "require_shadow_before_live":   true
}

Constraints compoem. O router roda todo portao em todo candidato; a primeira rejeicao vence.

Todo constraint numerico passa por is_finite() — NaN, +Inf e -Inf sao rejeitados com 400 out_of_range_<field>. Os dois campos no intervalo unitario aberto a esquerda (max_outcome_variance, max_cost_drop_without_validation) sao estritamente maior que zero. min_samples_before_promotion e rejeitado fora de [1, 100_000]. O cap de body em PUT /v1/constraints e 4 KiB.

Esses limites tambem vivem como CHECK constraints na tabela organization_constraints, entao uma linha mal-configurada nao chega ao banco.

Todo PUT bem-sucedido grava uma linha em constraint_changes com o snapshot before, o snapshot after, o actor_api_key_id e o timestamp. O metadata do evento de auditoria carrega hashes SHA-256 de before e after, entao o log de auditoria nao duplica os valores brutos dos constraints.

Todos os nove campos estao apenas no plano Pro. Em planos Free a pagina /routing/constraints e renderizada ausente (nao como aba travada) e a API retorna 403 plan_required.

• GET /v1/constraints — le o conjunto atual.
• PUT /v1/constraints — escreve um novo conjunto.
• POST /v1/routing/explain — dry-run de uma requisicao candidato contra os constraints atuais.
• Explicacao de Decisao — como rejeicoes de constraint aparecem na prosa legivel.
• Metodologia de Confianca — contra o que confidence_threshold compara.