Koder Value-to-Intelligence Quotient (KVIQ)

draft

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:

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](file:/
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.
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:

Faixa KVIQ	Classificação	Descrição Operacional
≥ 150	Imbatível (Local)	Eficiência máxima absoluta de custo marginal, ideal para execuções locais de alto volume sem exposição de dados.
80 – 149	Excelente (Cloud)	Modelos comerciais altamente otimizados ou com excelente balanço de custo por API. Recomendados como default.
30 – 79	Muito Bom / Muito Alto	Modelos com forte inteligência ou contexto imenso, ideais para pipelines estruturais onde o custo é secundário.
20 – 29	Bom	Modelos auxiliares, robustos para tarefas de apoio como geração de documentação e testes isolados.
0 – 19	Moderado (Alto Custo)	Modelos de altíssimo custo operacional. Indicados apenas para problemas de depuração crítica onde todas as outras abordagens falharam.

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)

Orquestração Dinâmica: Sub-agentes especializados em varredura e busca devem priorizar modelos com melhor KVIQ ponderado por contexto.
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.
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. * specsnamingtaxonomy.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.