Verdict کے ذریعے CLI نتائج کی مقامی درجہ بندی

Verdict کیا کرتا ہے

Verdict کوڈنگ ایجنٹس، CI رنرز اور دیگر ایسے سسٹمز کے لیے semantic outcome layer کا تحقیقی پیش نظارہ ہے جو ٹولز استعمال کرتے ہیں۔ یہ کسی process کے exit code کو قطعی ثبوت سمجھنے کے بجائے command، exit code، standard output اور standard error کا مجموعی جائزہ لیتا ہے۔

ماڈل چار میں سے ایک label واپس کرتا ہے: success، failure، blocked یا unknown۔ یہ فرق مفید ہے کیونکہ کوئی command صفر code کے ساتھ ختم ہو سکتی ہے، مگر اس نے کوئی test نہ چلایا ہو، HTTP 500 response واپس کیا ہو، کسی worker کا انتظار کر رہی ہو یا نامکمل output پیدا کیا ہو۔ اسی طرح nonzero exit code کسی failed assertion کے بجائے ماحول میں موجود رکاوٹ کی نشاندہی بھی کر سکتا ہے۔

اہم: Verdict ایک advisory classifier ہے۔ یہ ثابت نہیں کرتا کہ task مکمل ہو گیا ہے یا environment میں مطلوبہ تبدیلی واقع ہو گئی ہے۔ deterministic checks اور authoritative state verification کو source of truth برقرار رکھیں۔

اہم خصوصیات

• مقامی inference: Inputs مقامی CPU پر network calls یا telemetry کے بغیر process کیے جاتے ہیں۔
• چھوٹا model: Quantized model تقریباً 197 KB کا ہے۔
• Zero-dependency runtime: Inference میں Python standard library استعمال ہوتی ہے اور package کے علاوہ tokenizer files، GPU یا Python runtime dependencies کی ضرورت نہیں ہوتی۔
• Semantic classification: Model صرف exit code پر انحصار کرنے کے بجائے command، exit code، stdout اور stderr کو مدِنظر رکھتا ہے۔
• تیز predictions: Repository کے مطابق documented Windows 11، AMD64 اور Python 3.12 benchmark environment میں median inference time 0.54 ms ہے۔
• Python اور CLI interfaces: Model کو application میں یا براہِ راست shell pipeline سے استعمال کریں۔
• Browser demonstration: Project page logs upload کیے بغیر browser میں انہی quantized weights کو چلاتا ہے۔

Verdict hashed character 3–5-grams اور word 1–3-grams کو multiclass logistic regression کے ساتھ استعمال کرتا ہے۔ اس کے inputs UTF-8 text ہوتے ہیں، جبکہ ہر output stream کو explicit head-and-tail clipping کے ذریعے 12,288 characters تک محدود کیا جاتا ہے۔

چاروں Labels کو سمجھیں

• success: Output میں مثبت ثبوت موجود ہوتا ہے کہ operation مکمل ہو گیا۔
• failure: Operation چلی اور اس نے واضح failure رپورٹ کیا۔
• blocked: Permissions، dependencies، networking، quota limits یا environment نے execution روک دی۔
• unknown: Evidence موجود نہیں، نامکمل ہے، skip کیا گیا ہے، صرف dry run تک محدود ہے یا کسی اور وجہ سے غیر حتمی ہے۔

واپس کی گئی probabilities ایک linear multiclass model سے آتی ہیں۔ انہیں safety-critical فیصلوں کے لیے calibrated confidence نہ سمجھیں۔

Verdict انسٹال کریں

Repository clone کریں، اس کی directory میں جائیں اور pip کے ذریعے package انسٹال کریں:

git clone https://github.com/Balanov/verdict.git
cd verdict
python -m pip install .

اس سے verdict_tiny Python package اور verdict command-line interface انسٹال ہوتے ہیں۔

اپنی پہلی Python Prediction چلائیں

Verdict instance بنائیں اور اسے وہی evidence دیں جسے آپ کے tool runner نے observe کیا تھا۔ یہ مثال ایک کامیاب pytest process کی نمائندگی کرتی ہے جس نے حقیقت میں کوئی test نہیں چلایا:

from verdict_tiny import Verdict

model = Verdict()
result = model.predict(
    command="pytest tests/",
    exit_code=0,
    stdout="collected 0 items\nno tests ran in 0.01s",
)
print(result)

Documented model output، zero exit code کے باوجود، اس evidence کو unknown قرار دیتا ہے:

{
  "label": "unknown",
  "confidence": 0.999981,
  "probabilities": {
    "success": 0.000019,
    "failure": 0.0,
    "blocked": 0.0,
    "unknown": 0.999981
  },
  "advisory": true
}

label منتخب outcome ہے۔ probabilities object ہر class کا score دکھاتا ہے، جبکہ advisory اس بات پر زور دیتا ہے کہ prediction authoritative proof نہیں ہے۔

Verdict کو Command Line سے استعمال کریں

آپ command output کو Verdict میں pipe کر سکتے ہیں اور اصل command اور exit code فراہم کر سکتے ہیں:

printf 'collected 0 items\nno tests ran\n' | verdict \
  --command 'pytest tests/' --exit-code 0

پہلے سے files میں محفوظ output کے لیے --stdout اور --stderr استعمال کریں:

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log

آپ کسی مخصوص location سے weights بھی load کر سکتے ہیں:

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log \
  --weights /path/to/verdict-q8.bin

Verdict کو محفوظ طریقے سے Integrate کریں

ایک عملی integration میں Verdict کو final judge کے بجائے اضافی decision signal سمجھنا چاہیے۔ Coding agent یا CI runner اس label کی مدد سے فیصلہ کر سکتا ہے کہ مزید evidence کا جائزہ لینا ہے، operation دوبارہ آزمانا ہے یا انسانی review کی درخواست کرنی ہے۔

1. اصل command چلائیں اور اس کا exit code، stdout اور stderr محفوظ رکھیں۔
2. تمام دستیاب evidence Verdict کو دیں۔
3. Predicted label اور class probabilities دونوں کا جائزہ لیں۔
4. نتیجہ خیز actions لینے سے پہلے application-specific thresholds نافذ کریں۔
5. Deterministic checks کے ذریعے completion کی تصدیق کریں، مثلاً test counts، generated files، API state یا database records۔

مثال کے طور پر، unknown result کو عموماً completion claim کے بجائے مزید investigation شروع کرنی چاہیے۔ blocked result کی صورت میں دوبارہ کوشش سے پہلے credentials، dependencies، connectivity، permissions یا quotas چیک کرنا مناسب ہو سکتا ہے۔ جب correctness اہم ہو، تب بھی success result کے لیے authoritative verification ضروری ہے۔

اعلیٰ سطحی تجاویز

مکمل عمل درآمد کا سیاق و سباق محفوظ رکھیں

جب بھی ممکن ہو، اصل کمانڈ، ایگزٹ کوڈ، stdout اور stderr فراہم کریں۔ اسٹریمز کو حذف کرنے سے وہ شواہد ختم ہو سکتے ہیں جو کسی حقیقی ناکامی کو ماحولیاتی رکاوٹ یا غیر حتمی اجرا سے ممتاز کرتے ہیں۔

ان پٹ کی کٹائی کو مدِنظر رکھیں

ہر آؤٹ پٹ اسٹریم کو head-and-tail clipping کے ذریعے 12,288 حروف تک محدود کیا جاتا ہے۔ جب لاگز بہت بڑے ہوں تو یقینی بنائیں کہ فیصلہ کن پیغامات ابتدا یا اختتام کے قریب ظاہر ہوں، یا مکمل لاگز کا ایک اضافی، متعین اسکین کریں۔

محتاط فیصلہ کن حدیں مقرر کریں

یہ احتمالات safety-critical معنوں میں کیلیبریٹ شدہ اعتماد کی نمائندگی نہیں کرتے۔ اپنے ورک فلو کے لیے موزوں حدیں استعمال کریں اور غیر یقینی یا اہم معاملات کو متعین جانچ یا انسانی جائزے کے لیے بھیجیں۔

حسبِ ضرورت یا ڈاؤن لوڈ کیے گئے وزن استعمال کریں

جاری کردہ quantized weights weights/verdict-q8.bin میں محفوظ ہیں اور Hugging Face سے بھی دستیاب ہیں۔ CLI، --weights کے ذریعے متبادل وزن کا راستہ قبول کرتی ہے۔

براؤزر ڈیمو آزمائیں

Verdict project page وہی quantized weights براؤزر میں چلاتا ہے۔ پروجیکٹ کی دستاویزات کے مطابق لاگز اپ لوڈ نہیں کیے جاتے۔

ٹریننگ اور جائزے کو دوبارہ تیار کریں

ٹریننگ اور ڈیولپمنٹ کے اضافی پیکجز انسٹال کریں، مصنوعی corpus دوبارہ بنائیں، ماڈل کو train کریں، int8 weights برآمد کریں، artifact کا جائزہ لیں، اور ٹیسٹ چلائیں:

python -m pip install -e '.[train,dev]'
python training/train.py
pytest -q

عوامی benchmark میں 48 CLI families سے 192 مصنوعی مثالیں استعمال کی گئی ہیں جو training میں شامل نہیں تھیں۔ Training میں 60 مختلف families سے 1,440 مصنوعی مثالیں استعمال کی گئی ہیں۔ رپورٹ کردہ quantized model نے 93.2% accuracy اور 93.2% macro-F1 حاصل کیا، جبکہ exit-code baseline کے لیے accuracy 47.9% اور macro-F1 31.9% تھی۔

یہ corpus مصنوعی اور انگریزی پر مبنی ہے۔ یہ پیمائشیں الگ رکھے گئے templates کا جائزہ لیتی ہیں، production agent traces پر قابلِ اعتماد کارکردگی کا نہیں، اور latency کے نتائج مختلف hardware کے لیے وعدے نہیں ہیں۔

پروجیکٹ کی حدود جانیں

Verdict جان بوجھ کر محدود دائرے میں ہے۔ یہ CLI output میں مشاہدہ کیے گئے شواہد کی درجہ بندی کرتا ہے، لیکن یہ طے نہیں کرتا کہ کوئی وسیع تر task مکمل ہوا ہے یا نہیں۔ یہ code correctness، safety یا truthfulness بھی ثابت نہیں کرتا۔

اس لیے پروجیکٹ کو raw process execution اور agent کے اگلے action کے درمیان semantic layer کے طور پر استعمال کرنا بہتر ہے۔ یہ ایسے شواہد کی شناخت کر سکتا ہے جنہیں exit code نظر انداز کر دیتا ہے، لیکن اسے tests، state inspection، validation rules اور انسانی فیصلے کا متبادل نہیں بلکہ معاون ہونا چاہیے۔

نتیجہ

Verdict، exit-code-only check کے مقابلے میں CLI نتائج کی زیادہ محتاط تشریح کے لیے ایک چھوٹا، تیز اور مقامی طریقہ فراہم کرتا ہے۔ اسے Python package کے طور پر انسٹال کریں، مکمل execution context فراہم کریں، اور follow-up actions کی رہنمائی کے لیے اس کے چار labels استعمال کریں۔ قابلِ اعتماد automation کے لیے اس کے advisory result کو ہمیشہ متعین اور مستند verification کے ساتھ ملائیں۔