Previsão de custo em tokens

O PRECC inclui um oráculo de previsão de custo em tokens para que planos com várias etapas possam ser orçados em tokens, e não em tempo de relógio. Registre uma previsão antes de cada etapa, anote o valor real após o término do trabalho, e o conjunto de dados treina um preditor integrado que melhora com o tempo.

Registrar uma previsão

Passe uma descrição de uma linha do passo planejado. O PRECC o categoriza (feat / fix / test / refactor / measurement / doc / chore / unknown), estima a contagem de tokens e imprime um id que você usará para fechar o ciclo.

$ precc predict "Implement read-deltas with mtime check"
id=42 category=feat predicted=5680 tokens (confidence=0.50, model=trained-v1)
Record actual when done: precc predict --record 42 <actual_tokens>

Registrar o valor real

Após o passo ser concluído, consulte a contagem real de tokens no rodapé da sessão ou na telemetria e devolva-a pelo id.

$ precc predict --record 42 6300
Recorded actual=6300 tokens for prediction id=42.

Treinar trained-v1

Quando tiver pelo menos dez previsões fechadas, ajuste a regressão ridge trained-v1 sobre log10(actual) em função de log10(comprimento da descrição) mais uma variável indicadora de categoria one-hot. O ajuste é em forma fechada (Cholesky nas equações normais com ridge λ=1) e executa em milissegundos.

$ precc predict --train
Trained trained-v1 on 22 closed predictions (λ=1).
  Model file : ~/.local/share/precc/predict_model.json
  Confidence : 0.50
  Intercept  :  +1.0016
  log_desc   :  +1.2339
  Categories :
    unknown       +0.4811
    doc           +0.4474
    measurement   +0.3422
    test          +0.1071
    refactor      +0.0326
    feat          +0.0071
    fix           -0.1096
    chore         -0.3063

Após o treinamento, toda nova chamada precc predict usa trained-v1 automaticamente até que você remova ou substitua o arquivo do modelo. As previsões antigas mantêm sua model_version original para que você possa comparar os preditores ao longo do tempo.

Inspecionar a precisão do preditor

precc predict --eval informa o erro percentual absoluto médio (MAPE) geral e por categoria, calculado apenas sobre previsões fechadas (linhas com valores tanto previstos quanto reais).

$ precc predict --eval
Predictions logged   : 30
With actuals (closed): 22
Mean predicted       :     1483 tokens
Mean actual          :    47238 tokens
MAPE (statistical)   :     76.4%

By category:
  category        n   predicted      actual    MAPE
  feat            6        4605        5250   26.2%
  unknown         4        1597       30526   52.6%
  test            4         924       38900   56.4%
  ...

Listar previsões recentes

precc predict --list mostra linhas recentes em ordem cronológica inversa. Linhas abertas (sem valor real) estão prontas para serem fechadas.

$ precc predict --list --limit 5
id    ts                   category       predicted     actual  conf description
30    2026-05-09 09:40:51  feat                5348          -  0.50 Run the synthetic-fleet pilot...
29    2026-05-09 08:56:48  test                1050          -  0.60 Train predictor: trained-v1...
28    2026-05-09 07:44:18  test                 915     150000  0.60 Implement minimal task-12...

Por que tokens, e não tempo de relógio

Estimativas de tempo são inmensuráveis a posteriori e não se compõem entre máquinas ou sessões. As contagens de tokens são determinísticas, comparáveis e fazem crescer um conjunto de dados rotulado que melhora o preditor a cada ciclo fechado. O propósito do oráculo é converter a estimativa de um jogo de adivinhação em uma medição.

Onde os dados residem

Todos os dados de previsão são armazenados localmente na sua máquina. Nada é enviado.

~/.local/share/precc/
├── metrics.db                — predictions table (oracle DB)
└── predict_model.json        — trained-v1 coefficients (after `--train`)