Constraints API

A Constraints API é como um cliente coloca uma coleira na otimização da Floopy. Dois endpoints — GET para ler o conjunto atual, PUT para substituí-lo.

A semântica é full-replace: uma chave ausente no PUT cai para o default da plataforma. Não há PATCH.

Authorization: Bearer <your-floopy-api-key>

• Permissão: read_permission para GET, write_permission para PUT.
• Apenas plano Pro.
• Estamos liberando esse endpoint por organização enquanto validamos a qualidade. Fale com o suporte caso sua organização ainda não esteja habilitada.

Lê o conjunto atual de constraints, com os defaults da plataforma exibidos ao lado.

GET https://api.floopy.ai/v1/constraints

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

Os quatro novos campos (min_samples_before_promotion, max_outcome_variance, max_cost_drop_without_validation, require_shadow_before_live) estao documentados ponta a ponta na pagina de feature de Constraints.

curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
  "https://api.floopy.ai/v1/constraints" | jq .

Substitui o conjunto de constraints. Limite do body: 4 KiB.

PUT https://api.floopy.ai/v1/constraints

{
  "max_regression":               { "value": 0.02, "window": "rolling_24h" },
  "max_cost_increase":            { "value": 0.05, "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
}

O body é deny_unknown_fields — chaves desconhecidas retornam 400 unknown_field. Semântica full-replace: qualquer chave omitida do body do PUT é definida com o default da plataforma, e não preservada. Todo campo numerico passa por is_finite() — NaN, +Inf e -Inf sao rejeitados com 400 out_of_range_<field>.

• max_regression — quando a regressão esperada de um candidato excede o cap, o candidato é filtrado com reason: "constraint_max_regression".
• max_cost_increase — quando o aumento rolante de custo esperado de um candidato excede o cap, o candidato é filtrado com reason: "constraint_max_cost_increase".
• confidence_threshold — quando o confidence do roteador está abaixo do threshold, a estratégia cai para a baseline e emite reason: "constraint_confidence_below_threshold" para todo outro candidato.
• min_samples_before_promotion — um candidato com menos amostras historicas que isso e filtrado com reason: "constraint_min_samples".
• max_outcome_variance — um candidato cuja variancia rolante de resultados ultrapassa esse cap e filtrado com reason: "constraint_high_variance".
• max_cost_drop_without_validation — um candidato cuja queda fracionaria esperada de custo vs. baseline ultrapassa esse cap e filtrado com reason: "constraint_cost_drop_requires_validation" a menos que exista um experimento shadow aprovado na janela de validade.
• require_shadow_before_live — quando true, qualquer candidato sem experimento shadow aprovado na janela de validade e filtrado com reason: "constraint_shadow_required". O cache (constraint_shadow_pass:{org}:{provider}:{model}) e DEL-ado proativamente em rollback para que um caminho de recuperacao rode quente.

Constraints compoem. O router roda todo portao em todo candidato nesta ordem fixa: max_cost_increase, max_regression, confidence_threshold, min_samples_before_promotion, max_outcome_variance, max_cost_drop_without_validation, require_shadow_before_live. A primeira rejeicao vence e e o que aparece na linha de auditoria.

Retorna o estado pós-escrita, formato idêntico ao GET.

curl -s -X PUT \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_regression":    {"value": 0.02, "window": "rolling_24h"},
    "max_cost_increase": {"value": 0.05, "window": "rolling_24h"},
    "confidence_threshold": 0.6
  }' \
  "https://api.floopy.ai/v1/constraints"

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. Os metadados do evento de auditoria carregam hashes SHA-256 de before e after, então o próprio log de auditoria não duplica os valores brutos das constraints.

• POST /v1/routing/explain — verifique uma mudança de constraint antes de aplicá-la.
• Metodologia de Confidence — contra o que confidence_threshold realmente compara.