Modelos Custo Beneficio

Modelos custo-benefício — candidatos para Eval

Use para encontrar candidatos OpenRouter conforme requisitos técnicos. Esta skill não escolhe modelo de produção e não executa o runner: devolve até cinco candidatos e o contrato obrigatório para a suíte de Eval do repositório.

Contrato de descoberta

Todo candidato deve cumprir simultaneamente:

1. versão mais recente da família (heurística created do OpenRouter);
2. não gratuito;
3. reasoning controlável via reasoning.supported_efforts ou reasoning.supports_max_tokens;
4. endpoint com throughput_last_30m.p75 >= 60 t/s; na ausência de p75, p50/median/avg é fallback. Dado ausente reprova;
5. endpoint com latency_last_30m.p50 < 120_000ms (2 min) e latency_last_30m.p99 < 180_000ms (3 min). Ambos são gates hard obrigatórios; dado ausente, inválido ou no limite reprova;
6. inputs, structured outputs, contexto e teto de custo solicitados;
7. suporte a tools, pois o gate de Tool Calls é obrigatório inclusive para runtime textual.
8. índice de inteligência estritamente maior que 35 por padrão, vindo de GET /api/v1/benchmarks?source=artificial-analysis&task_type=intelligence; usa match exato antes de fallback restrito a sufixo de data. Índices ausentes, inválidos, não finitos ou ambíguos reprovam.

O benchmark de inteligência é um filtro hard aplicado antes de --candidate-limit; não há associação fuzzy por nome e não há fallback para uma fonte que não possa ser verificada.

Roteamento

--no-tool-calls define o slug de runtime; ele não dispensa o gate obrigatório de Tool Calls, que deve testar o mesmo modelo com :exacto.

Entrada

eval_language é obrigatório e deve representar o idioma nativo da aplicação, por exemplo pt-BR. Aceite texto livre convertido para flags ou --requirements-json.

Procedimento obrigatório

1. Defina OPENROUTER_API_KEY no ambiente antes de executar. A skill não acessa vaults, 1Password nem imprime a credencial:

   python scripts/openrouter_model_recommender.py \
     --eval-language pt-BR --limit 5 --min-throughput 60 --min-intelligence 35 \
     --input text,image --tool-calls --structured-outputs --min-context 128000
   

2. Se houver menos de dois candidatos, pare; não relaxe requisitos nem invente candidatos.

3. Pré-flight da suíte: procure casos executáveis para os quatro gates abaixo. Se algum não existir, crie-o no framework de Eval já adotado pelo repositório antes de testar candidatos. Sem cobertura nos quatro, pare: nenhum modelo pode ser aprovado.

   Gate obrigatório	Critério mínimo
   Idioma nativo (eval_language)	prompts, entradas, respostas esperadas e critérios no idioma real da aplicação; não substitua o corpus por tradução automática.
   Markdown	respostas com a estrutura exigida (títulos/listas/tabelas/fences aplicáveis) e validação determinística de sintaxe, inclusive fences não fechados.
   Tool Calls	chamada controlada do mesmo modelo via :exacto; valide escolha da ferramenta, schema e argumentos, resultado e recuperação/abstenção para ferramenta inválida/indisponível.
   Antialucinação	casos grounded e sem resposta; afirmações devem vir da evidência; sem evidência, deve declarar incerteza, pedir contexto ou recusar. Reprove fatos, citações, resultados de tool ou detalhes inventados.
   Ganho vs. mercado	compare cada candidato no mesmo corpus contra ≥3 baselines atuais, com IDs/versões/providers pinados e de provedores distintos; inclua o modelo de produção atual, se houver. Registre Δ pass_rate global e por gate (pontos percentuais), custo, latência e throughput.

4. Execute cada candidato com reasoning.initial válido (xhigh, high, medium, low ou minimal; para max_tokens, use o mapa local equivalente). None, vazio ou valor fora desse enum não é esforço válido e desqualifica a combinação. Uma combinação modelo + variante + reasoning só passa se cada gate e a taxa global atingirem pass_rate >= 95%, ou o limiar explicitamente configurado pela suíte. Gate ausente ou falho desqualifica o candidato.

   Prioridade de execução: dispare em paralelo todas as combinações independentes de modelo + variante + reasoning (candidatos e baselines) para economizar tempo. Cada worker usa o mesmo snapshot de corpus/prompts/tools e grava resultado imutável separado. Limite a concorrência por provider conforme rate limits, orçamento e capacidade do runner; retries seguem a mesma política para todos. Só agregue métricas e decida principal/fallback após todos os jobs terminarem; não paralelize etapas dependentes nem compartilhe arquivos mutáveis.

5. Reduza o reasoning por sobrevivente: xhigh → high → medium → low → minimal, ignorando níveis não suportados. Ao falhar, retenha o menor nível anterior aprovado.

6. Somente com pelo menos dois modelos distintos aprovados nos quatro gates, o Eval escolhe principal e fallback: menor custo total observado → menor latência → maior throughput. Aplique runtime manualmente.

7. Revalide em até 30 dias, e quando mudarem idioma, contrato Markdown, ferramentas, corpus/grounding, modelo, provider, preço, reasoning ou suíte.

Saída

Entregue apenas:

• até cinco candidatos com endpoint, reasoning inicial, throughput e índice de inteligência;
• metadados da fonte do benchmark (source, task_type, as_of, version) e diagnósticos no JSON;
• o guia de Eval acima.

Não anuncie vencedor antes dos quatro gates aprovados e não altere runtime.