پیش‌بینی هزینه توکن

PRECC یک پیشگوی پیش‌بینی هزینه توکن دارد تا برنامه‌های چندمرحله‌ای بتوانند بر حسب توکن بودجه‌بندی شوند، نه زمان دیواری. پیش از هر مرحله یک پیش‌بینی ثبت کنید، پس از پایان کار مقدار واقعی را وارد کنید، و مجموعه داده یک پیش‌بین داخلی را آموزش می‌دهد که با گذر زمان بهبود می‌یابد.

ثبت یک پیش‌بینی

یک توصیف یک‌خطی از مرحله برنامه‌ریزی‌شده وارد کنید. PRECC آن را دسته‌بندی می‌کند (feat / fix / test / refactor / measurement / doc / chore / unknown)، تعداد توکن را تخمین می‌زند و یک id چاپ می‌کند که برای بستن حلقه استفاده خواهید کرد.

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

ثبت مقدار واقعی

پس از پایان مرحله، تعداد واقعی توکن را از فوتر جلسه یا تله‌متری بیابید و از طریق id آن را بازگردانید.

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

آموزش trained-v1

به محض اینکه دست‌کم ده پیش‌بینی بسته‌شده دارید، رگرسیون ridge با نام trained-v1 را روی log10(actual) در برابر log10(طول توصیف) به اضافه یک متغیر مجازی one-hot برای دسته برازش کنید. برازش به‌صورت بسته است (Cholesky روی معادلات نرمال با ridge λ=1) و در چند میلی‌ثانیه اجرا می‌شود.

$ 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

پس از آموزش، هر فراخوانی جدید precc predict به‌طور خودکار از trained-v1 استفاده می‌کند تا زمانی که فایل مدل را حذف یا جایگزین کنید. پیش‌بینی‌های قدیمی model_version اصلی خود را حفظ می‌کنند تا بتوانید پیش‌بین‌ها را در طول زمان مقایسه کنید.

بررسی دقت پیش‌بین

precc predict --eval میانگین خطای درصدی مطلق (MAPE) را در کل و به تفکیک هر دسته گزارش می‌دهد و فقط روی پیش‌بینی‌های بسته‌شده (سطرهایی که هم مقدار پیش‌بینی‌شده و هم مقدار واقعی دارند) محاسبه می‌شود.

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

فهرست پیش‌بینی‌های اخیر

precc predict --list سطرهای اخیر را به ترتیب زمانی معکوس نمایش می‌دهد. سطرهای باز (بدون مقدار واقعی) آماده بسته‌شدن هستند.

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

چرا توکن، نه زمان دیواری

تخمین‌های زمانی پس از وقوع قابل اندازه‌گیری نیستند و بین ماشین‌ها یا جلسات قابل ترکیب نیستند. شمارش توکن قطعی و قابل مقایسه است و مجموعه داده برچسب‌خورده‌ای را گسترش می‌دهد که با هر حلقه بسته‌شده، پیش‌بین را بهبود می‌بخشد. هدف اصلی این پیشگو این است که تخمین را از یک بازی حدس به یک اندازه‌گیری تبدیل کند.

محل ذخیره داده‌ها

تمام داده‌های پیش‌بینی به‌صورت محلی روی دستگاه شما ذخیره می‌شوند. هیچ چیزی آپلود نمی‌شود.

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