Koder Value-to-Intelligence Quotient (KVIQ)

Abstract

Esta especificação define o método quantitativo padronizado para cálculo e aplicação do KVIQ (Koder Value-to-Intelligence Quotient). O KVIQ é a métrica reguladora utilizada no ecossistema da Koder Stack para avaliar a eficiência de custo-benefício de modelos de inteligência artificial aplicados à engenharia de software e desenvolvimento de sistemas complexos.

O objetivo primário do KVIQ é permitir que agentes de codificação autônomos (como o Antigravity CLI) e equipes de engenharia tomem decisões dinâmicas e fundamentadas sobre qual modelo de IA empregar para cada classe de tarefa (pesquisa, escrita de código, refatoração global, etc.), balanceando custos operacionais de chamadas de API contra poder lógico e capacidade de contexto.

1. Filosofia de Design

• Ponderação Realista de Contexto: Modelos com grandes janelas de contexto (como a linha Gemini) oferecem um benefício desproporcional na análise de monorepos inteiros, eliminando a fragmentação do código. O KVIQ premia essa capacidade de forma logarítmica.
• Aferição baseada em SWE-bench Pro: Rejeita-se o uso de benchmarks puramente acadêmicos (como HumanEval). O KVIQ ancora o benefício lógico no SWE-bench Pro, que reflete a capacidade de resolução de bugs de produção reais em bases de código legadas.
• Normalização de Custos de Entrada/Saída: Em fluxos de trabalho agentivos, o tráfego de entrada (contexto do repositório) é massivamente maior que o de saída (o código gerado). O KVIQ pondera essa assimetria na proporção realista de 80/20.
• Suporte a Modelos Locais e Subscrições: Para fins de comparação justa, modelos locais de pesos abertos (open-weights) e assinaturas flat-rate de consumo ilimitado recebem custos efetivos equivalentes aproximados baseados em amortização de infraestrutura.

2. A Fórmula Matemática

O KVIQ de um modelo de inteligência artificial é calculado pela relação entre o seu Benefício Ponderado ($B$) e o seu Custo Efetivo de Tokens ($C_{final}$), escalado por um fator de legibilidade ($k = 2$):

$$\text{KVIQ} = \frac{B}{C_{final}} \times 2$$

2.1 Benefício de Engenharia ($B$)

O benefício lógico ponderado é calculado multiplicando-se a taxa de sucesso no SWE-bench Pro ($S$, expressa como percentual de 0 a 100) pelo fator de eficiência de contexto ($X$, medido em milhares de tokens):

$$B = S \times \left(1 + \omega \times \log_{10}\left(\frac{X}{100}\right)\right)$$

Onde:

• $S \in [0, 100]$: Percentual de sucesso no benchmark SWE-bench Pro (ou estimativa oficial de paridade).
• $X \ge 100$: Tamanho máximo da janela de contexto aceita pelo modelo, expressa em milhares de tokens (ex: 200 para 200K, 2000 para 2M).
• $\omega = 0.20$: Peso de amortização do ganho de contexto. A escala logarítmica garante retornos decrescentes de utilidade marginal para janelas extremamente extensas.

Nota: Para $X < 100$, assume-se o valor base de $100$ no denominador para evitar penalidades artificiais a modelos especialistas de baixo contexto.

2.2 Custo Final de Tokens ($C_{final}$)

O custo por milhão de tokens é normalizado para refletir a proporção média de consumo de agentes de codificação (estimada em $80%$ de leitura e $20%$ de escrita):

$$C_{eff} = 0.8 \times C_{input} + 0.2 \times C_{output}$$

Onde:

• $C_{input}$: Preço de API por 1 milhão de tokens de entrada (em USD).
• $C_{output}$: Preço de API por 1 milhão de tokens de saída (em USD).

Para modelar o custo de hardware e evitar indeterminações matemáticas por custo nulo ($0.00$), aplica-se a seguinte taxonomia de custos baselines e regularização:

• Modelos de Pesos Abertos (Local/Self-hosted): $C_{eff} = $0.15$ (custo elétrico e de amortização de hardware GPU empresarial estimado por milhão de tokens).
• Modelos sob Assinatura Plana (Flat-rate): $C_{eff} = $0.10$ (custo virtualizado de acesso por milhão de tokens).
• Fator de Regularização ($\epsilon = 0.20$): Adicionado ao custo efetivo para suavizar a curva de custo de modelos ultrabaratos e representar custos de setup/latência operacional: $$C_{final} = C_{eff} + 0.20$$

2.3 Evolução e Substituição de Benchmarks de Referência

Para garantir que o KVIQ não perca seu poder discriminativo ao longo do tempo (devido à saturação de acertos ou contaminação dos dados de treinamento dos modelos), o parâmetro de inteligência ($S$) deve evoluir de acordo com as seguintes diretrizes:

1. Sincronização com o Registro de Relevância: O benchmark primário de código usado para $S$ deve estar classificado como relevance: high no registro normativo meta/docs/stack/registries/ai-benchmarks.md.
2. Gatilho de Substituição: Um benchmark deve ser substituído ou rotacionado nas seguintes condições:
   • Saturação: Quando a média dos 3 modelos líderes da indústria ultrapassar $90%$ de taxa de sucesso.
   • Contaminação confirmada: Quando houver evidência de vazamento das soluções do benchmark nos datasets de treino públicos dos novos modelos.
   • Obsolescência: Quando surgir um novo benchmark que simule melhor as tarefas agentivas complexas da Koder Stack.
3. Controle de Versão do KVIQ: A alteração do benchmark de referência exige a atualização do arquivo da especificação e o incremento do seu número de versão:
   • Minor Bumps (ex: 1.0.0 → 1.1.0): Para atualizações menores de parâmetros de custos ou calibração matemática.
   • Major Bumps (ex: 1.0.0 → 2.0.0): Para a rotação completa do benchmark de referência $S$ (ex: migração futura do SWE-bench Pro para um eventual Koder-Code-Bench). Os históricos de scores deverão ser reiniciados ou re-normalizados sob a nova versão (KVIQv2).

3. Bandas de Classificação KVIQ

O resultado do cálculo do KVIQ categoriza os modelos de acordo com as seguintes faixas de eficiência de recursos:

4. Integração de Roteamento de Agentes (Use Cases)

A Koder Stack estabelece o uso do KVIQ para a tomada de decisão em pipelines de orquestração distribuída do Antigravity CLI e demais microserviços de IA:

                  [Problema de Engenharia]
                             │
            ┌────────────────┴────────────────┐
            ▼                                 ▼
   [Refatoração Crítica]             [Busca em Monorepo]
   (Exige Max Inteligência)         (Exige Contexto Amplo)
            │                                 │
            ▼                                 ▼
   Selecione o modelo de             Selecione o modelo de
   maior SWE-bench (Opus)           maior KVIQ de contexto (Gemini)

1. Orquestração Dinâmica: Sub-agentes especializados em varredura e busca devem priorizar modelos com melhor KVIQ ponderado por contexto.
2. Execução em Larga Escala (Batching): Pipelines automotivos de CI/CD e testes de regressão automatizados devem usar modelos com classificação KVIQ Excelente ou Imbatível para conter custos de infraestrutura.
3. Depuração de Falhas Complexas: Para a correção de bugs críticos com acoplamento temporal/concorrência, o agente está autorizado a realizar o downgrade temporário do KVIQ, priorizando o modelo com o maior SWE-bench Pro isolado.

References

• monorepo-RFC-009-meta-internal-split.md — Divisão de documentação normativa de metadados.
• specs/naming/taxonomy.md — Diretrizes de nomenclatura e taxonomia de projetos Koder.
• SWE-bench Pro Evaluation Suite (2026) — Benchmark de validação empírica de engenharia de software.