Prédiction du coût en jetons

PRECC fournit un oracle de prédiction du coût en jetons pour que les plans multi-étapes se budgétisent en jetons, et non en temps réel. Enregistrez une prédiction avant chaque étape, notez la valeur réelle une fois le travail terminé, et le jeu de données entraîne un prédicteur intégré qui s’améliore au fil du temps.

Enregistrer une prédiction

Fournissez une description sur une ligne de l’étape planifiée. PRECC la catégorise (feat / fix / test / refactor / measurement / doc / chore / unknown), estime un nombre de jetons et affiche un id que vous utiliserez pour boucler la boucle.

$ 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>

Enregistrer la valeur réelle

Une fois l’étape terminée, récupérez le nombre réel de jetons depuis le pied de session ou la télémétrie et renvoyez-le via l’id.

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

Entraîner trained-v1

Une fois que vous avez au moins dix prédictions fermées, ajustez la régression ridge trained-v1 sur log10(actual) en fonction de log10(longueur de la description) plus une variable indicatrice de catégorie one-hot. L’ajustement est en forme close (Cholesky sur les équations normales avec ridge λ=1) et s’exécute en millisecondes.

$ 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

Après l’entraînement, chaque nouvel appel à precc predict utilise trained-v1 automatiquement jusqu’à ce que vous supprimiez ou remplaciez le fichier modèle. Les anciennes prédictions conservent leur model_version d’origine, afin que vous puissiez comparer les prédicteurs dans le temps.

Inspecter la précision du prédicteur

precc predict --eval rapporte l’erreur absolue moyenne en pourcentage (MAPE) globalement et par catégorie, calculée uniquement sur les prédictions fermées (lignes avec à la fois des valeurs prédites et réelles).

$ 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%
  ...

Lister les prédictions récentes

precc predict --list affiche les lignes récentes par ordre chronologique inverse. Les lignes ouvertes (sans valeur réelle) sont prêtes à être fermées.

$ 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...

Pourquoi des jetons et non du temps réel

Les estimations de temps ne sont pas mesurables a posteriori et ne se composent pas d’une machine ou d’une session à l’autre. Les nombres de jetons sont déterministes, comparables et font croître un jeu de données étiqueté qui améliore le prédicteur à chaque boucle fermée. L’intérêt même de l’oracle est de transformer l’estimation d’un jeu de devinettes en une mesure.

Où résident les données

Toutes les données de prédiction sont stockées localement sur votre machine. Rien n’est téléversé.

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