POST /v1/routing/explain

O endpoint usa os mesmos planejadores de Feedback-driven e Smart Cost do live, incluindo flags de plano, switch geral, histórico real, constraints e aprovação shadow. Não despacha modelos, não grava log de request/response e não incrementa contadores de rotação/uso. O evento de audit autenticado e o orçamento do explain continuam valendo.

Request

Envie a request de chat diretamente no body JSON, com headers HTTP normais. Não há wrapper com request, locale ou headers.

curl -s https://api.floopy.ai/v1/routing/explain \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: pt" \
  -H "floopy-routing-rule: $ROUTING_RULE_ID" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Resuma este relatório."}]}'

floopy-routing-rule seleciona uma regra da organização antes da otimização. Headers reservados de identidade/internos são removidos do contexto simulado. Campos desconhecidos retornam 400 unknown_field; dados de chat inválidos retornam 400 invalid_body.

Resposta

O audit fica dentro de audit. Este exemplo ilustrativo de teste sem amostras mantém Feedback-driven como estratégia principal:

{
  "dry_run": true,
  "would_select": {"provider":"openai","model":"gpt-4o-mini"},
  "confidence": 0.0,
  "confidence_reason": "insufficient_samples",
  "firewall_decision": "pass",
  "audit": {
    "strategy_id": "feedback_driven",
    "reason": "would_dispatch",
    "phase": "auto",
    "exploration_draw": "explore_untested",
    "exploration": "explore_untested",
    "exploration_rate_effective": 0.2,
    "history_available": true,
    "winner_origin": "smart_cost_candidate",
    "winner": {"provider":"openai","model":"gpt-4o-mini"},
    "candidates": [
      {"provider":"openai","model":"gpt-4o-mini","score":0.61},
      {"provider":"openai","model":"gpt-4o","score":0.86}
    ],
    "filtered": []
  }
}

Campo	Significado
`would_select`	Primeiro par proposto; null quando bloqueado ou não resolvido.
`audit.strategy_id`	Política principal. No modo conjunto é `feedback_driven`.
`audit.smart_cost`	Participação opcional, baseline, par escolhido, complexidade e motivo efetivo.
`audit.exploration_draw`	Faixa sorteada antes de disponibilidade do pool e constraints.
`audit.exploration`	Faixa efetiva; pode virar exploit quando o pool exploratório está vazio.
`audit.history_available`	Distingue histórico vazio utilizável de consulta com erro.
`audit.winner_origin`	`approved_target` ou `smart_cost_candidate` na otimização.
`audit.candidates` / `audit.filtered`	Cadeia proposta de despacho e candidatos rejeitados.
`audit.evidence.samples_in_window`	Amostras do vencedor proposto.
`audit.evidence.recent_regressions`	Contagem: `{ "kind": "exact", "n": 0 }`, ou `{ "kind": "at_least", "n": 10 }`.
`confidence` / `confidence_reason`	Confiança do vencedor; dados insuficientes podem gerar zero.
`explanation`	Texto traduzido e ID do template.

No modo conjunto, os scores dos candidatos representam qualidade do Feedback-driven; audit.smart_cost.model_score, quando disponível, registra separadamente a utilidade de custo. audit.smart_cost.savings_estimate é zero no planejamento/explain porque o uso de tokens ainda é desconhecido. Os logs da request real preenchem esse campo após conhecer o uso, em microdólares. Bypass não dispensa constraints de qualidade, custo ou shadow.

Content-Language identifica o idioma escolhido pelo Accept-Language. O firewall segue as mesmas regras de plano/header; bloqueio retorna 200 sem vencedor proposto e com motivo de filtro do firewall.

A seleção é reproduzível internamente com a mesma seed, configuração e snapshot de evidência. Cada chamada HTTP de explain recebe novo request ID e evidência atual, portanto chamadas exploratórias podem diferir. Round-robin consulta sem avançar o contador; tráfego live concorrente pode mudar a próxima vez. Falhas de provider, retries e resultado de stream não são simulados. Agente MCP ativo retorna audit.reason: "agent_loop_not_simulated" sem inventar vencedor; envie floopy-mcp-disabled: true para inspecionar a cadeia normal.

Disponibilidade e limites

O endpoint exige kill switch da API de audit, plano elegível e permissões. O orçamento é de 30 chamadas/minuto por organização e 10 por API key; o body aceita até 64 KiB. Rejeições de plano/permissão retornam 403, kill switch retorna 404 e limites excedidos retornam 429.

Veja o fluxo de decisão, constraints e confiança.