लेबलिंग इंजन CLI, REST API, MCP टूल और SDK

लेबलिंग इंजन को potato label, /api/engine/v1 REST रूट, पाँच इंजन MCP टूल या Python Study क्लास से चलाइए, सब एक ही engine.sqlite फ़ाइल के ज़रिए।

एनोटेशन सर्वर, कमांड लाइन, REST API, MCP टूल और Python SDK, सभी उसी लेबलिंग इंजन को टास्क डायरेक्टरी की उसी engine.sqlite फ़ाइल के ज़रिए चलाते हैं। आप कमांड लाइन से अध्ययन शुरू कर सकते हैं, सर्वर से लोगों को अनुरोध परोस सकते हैं, और किसी नोटबुक से प्रमाणित कर सकते हैं।

एक समय में केवल एक प्रोसेस किसी अध्ययन को चलाता है। चल रहे सर्वर का प्लानर अध्ययन का राइटर लॉक रखता है, और जब तक वह लॉक उसके पास है, potato label run, potato label certify और Study.run() चलने से मना कर देते हैं और यह बता देते हैं। ऐसे में सर्वर के ज़रिए प्रमाणित करें, POST /api/engine/v1/certify या एडमिन पेज से। लॉक इसलिए है कि दो ड्राइवर दो कैलिब्रेशन नमूने चुनेंगे और एक-दूसरे के लेबलों पर प्रमाणित करेंगे। लॉक रखने वाला प्रोसेस बाहर निकलते ही लॉक छोड़ देता है। उसी मशीन पर बंद कर दिए गए धारक का लॉक तुरंत ले लिया जाता है, और किसी दूसरी मशीन वाले का, दो मिनट तक हार्टबीट न मिलने के बाद। केवल पढ़ने वाली कमांड (status, certificate, calls, export) किसी भी समय काम करती हैं।

कमांड लाइन

हर इंजन कमांड अध्ययन की कॉन्फ़िग फ़ाइल लेती है:

bash

potato label <command> <config.yaml> [options]

नौ कमांड पहली मॉडल कॉल से लेकर एक्सपोर्ट किए गए डेटासेट तक पूरे अध्ययन को कवर करती हैं:

कमांड	यह क्या करती है
`run`	कैस्केड से हर आइटम पर लेबल लगाती है, ब्लाइंड कैलिब्रेशन नमूना चुनती है, प्रमाणित करती है, समाधान करती है। `--until predicted` (डिफ़ॉल्ट) एक पास के बाद रुक जाता है, और `--until met` तब तक चलता रहता है जब तक हर कॉन्ट्रैक्ट पूरा न हो जाए या इंजन लोगों की प्रतीक्षा न करने लगे। यह `--max-items N`, `--budget-usd X` (इस रन के लिए `budgets.model_usd` की जगह लेता है), `--max-ticks N` (डिफ़ॉल्ट रूप से 20) और `--json` भी लेती है। बीच में रोका गया रन मॉडल कॉल दोहराए बिना वहीं से फिर शुरू होता है जहाँ रुका था। जब किसी स्रोत का पिछला रन विफल रहा हो या उसका दिया हर उत्तर त्रुटि रहा हो, या जब कोई स्रोत उस स्कीमा पर लेबल न लगा सके जिसका नाम कोई कॉन्ट्रैक्ट लेता है, तो यह स्रोत का नाम बताते हुए स्थिति 1 के साथ बाहर निकलती है।
`status`	आइटम, भविष्यवाणियाँ, उद्देश्य के अनुसार अनुरोध, कॉन्ट्रैक्ट, खर्च, वे आइटम जिनका अभी कोई लेबल नहीं, और हर उस स्रोत के लिए एक पंक्ति जिसमें त्रुटियाँ हों या जिसका रन विफल या रुका हुआ हो। `--json`।
`certify`	हर कॉन्ट्रैक्ट को नए cert लेबलों और नई भविष्यवाणियों पर परखती है। जब केवल dev लेबल बदले हों, तो संग्रहीत परिणाम एक टिप्पणी के साथ लौटता है, और `--retest` उस नियम को परखता है जिसे dev अब चुनता है, अगले परीक्षण-दौर पर (Looks देखें)। `--json`।
`certificate`	गुणवत्ता प्रमाणपत्र। `--format md` (डिफ़ॉल्ट), `html` या `json`, और `--out FILE`।
`export`	उत्पत्ति (provenance) सहित लेबल, प्रमाणपत्र (JSON, Markdown, HTML), एक डेटासेट कार्ड और कॉल लॉग, `--out DIR` में (डिफ़ॉल्ट रूप से `<output_annotation_dir>/labeling_engine`)।
`calls`	मॉडल-कॉल ऑडिट लॉग, JSON lines के रूप में। `--out FILE`।
`distill`	अब तक के लेबलों पर एक मॉडल प्रशिक्षित करती है और उसे कैस्केड में सबसे पहले रखती है।
`optimize`	कैस्केड के हर उपसमुच्चय को dev लेबलों पर आँकती है और वह सबसे सस्ता उपसमुच्चय बताती है जो कवरेज बनाए रखता है। जब कोई भी उपसमुच्चय कोई कवरेज नहीं बचाता, तो यह किसी की सिफ़ारिश नहीं करती। `--prompts N` किसी LLM स्तर से उसके प्रॉम्प्ट के N पुनर्कथन भी माँगता है और हर एक को dev आइटमों पर आँकता है। ये मॉडल कॉल हैं, जो लॉग होती हैं, बजट में गिनी जाती हैं और अपने अलग स्रोत संस्करणों के तहत संग्रहीत होती हैं, जबकि मौजूदा प्रॉम्प्ट को उसकी संग्रहीत भविष्यवाणियों से आँका जाता है। कैस्केड और प्रमाणपत्र नहीं बदलते।
`migrate-config`	कॉन्फ़िग की एक प्रति लिखती है जिसमें उसकी पुरानी AI कुंजियों के समकक्ष एक `labeling_engine` ब्लॉक होता है। `--out FILE`। लेबलिंग इंजन पर माइग्रेट करना देखें।

प्रगति जाँचने पर कुछ खर्च नहीं होता, क्योंकि status, certificate और एडमिन पेज संग्रहीत परिणाम पढ़ते हैं। हर नया परीक्षण, चाहे नए लेबलों पर certify से हो या certify --retest से, किसी कॉन्ट्रैक्ट के त्रुटि बजट का एक हिस्सा खर्च करता है।

एक्सपोर्ट द्वारा लिखी गई फ़ाइलें

potato label export आउटपुट डायरेक्टरी में चार तरह की फ़ाइलें लिखता है:

फ़ाइल	सामग्री
`labels.jsonl`, `labels.csv`	हर आइटम और स्कीमा के लिए एक पंक्ति, लेबल लगा हो या नहीं, जिसमें `id`, `schema`, `label`, `label_origin` (`auto`, `human`, `adjudicated`, ...), `status` (`accepted`, `threshold_legacy` के तहत `accepted_uncertified`, `pending`, `pending_recert`), `source`, `model`, `source_version`, `confidence`, `contract_version` और `request_ids` होते हैं। जिस मशीन लेबल का स्रोत स्वीकार होने के बाद बदल गया है, वह `pending_recert` दिखाता है, जब तक अगला पास उसे दोबारा प्रमाणित न कर दे।
`certificate.json`, `.md`, `.html`	प्रमाणपत्र।
`README.md`	प्रमाणपत्र से बना, Hugging Face फ़्रंट मैटर वाला एक डेटासेट कार्ड।
`model_calls.jsonl`	हर मॉडल कॉल, मॉडल, प्रॉम्प्ट और उत्तर के हैश, टोकन, लेटेंसी, लागत, कैश हिट और रिडैक्शन श्रेणियों के साथ।

सामान्य एक्सपोर्टर (python -m potato.export और एडमिन एक्सपोर्ट) लोगों के एनोटेशन एक्सपोर्ट करते हैं, और एक्सपोर्ट फ़ॉर्मेट पेज उनकी सूची देता है। इनमें से labeling_engine फ़ॉर्मेट वही फ़ाइलें लिखता है जो potato label export लिखता है, और इंजन चालू न हो तो चलने से मना कर देता है। इंजन चालू होने पर CSV, Parquet और Hugging Face एक्सपोर्ट दो कॉलम जोड़ते हैं, जो बताते हैं कि हर एनोटेशन ने इंजन के किस अनुरोध का उत्तर दिया। engine_purpose में उद्देश्य होता है, जैसे calibration, और engine_request में उद्देश्य, चुने जाने की प्रायिकता, दृश्यता, स्प्लिट और अनुरोध id वाला JSON होता है। ब्लाइंड यादृच्छिक नमूने को सत्यापन उत्तरों से अलग करने के लिए इन कॉलमों का उपयोग करें।

REST API

इंजन के सभी रूट /api/engine/v1 के तहत हैं और JSON लौटाते हैं। X-API-Key हेडर में एडमिन कुंजी से या एडमिन सत्र से प्रमाणीकरण करें। पढ़ने के लिए एडमिन-डैशबोर्ड अनुमति चाहिए, certify और plan के लिए असाइनमेंट प्रबंधन की अनुमति, और प्रमाणपत्र के लिए एक्सपोर्ट अनुमति।

मेथड और पाथ	क्या लौटाता है
`GET /status`	आइटम, भविष्यवाणियाँ, अनुरोध, कॉल का योग, बजट, और हर स्कीमा का कैस्केड, कॉन्ट्रैक्ट और तय हुए लेबलों की गिनती
`GET /schemes/<name>/contracts`	स्कीमा पर हर कॉन्ट्रैक्ट का नवीनतम परिणाम, कैस्केड बदला हो तो `stale` चिह्नित
`GET /schemes/<name>/risk_coverage`	आखिरी स्तर के हर थ्रेशोल्ड के लिए, cert लेबलों पर, स्वीकार किया गया हिस्सा, देखी गई त्रुटि और गारंटीशुदा ऊपरी सीमा
`GET /schemes/<name>/reliability`	कैलिब्रेशन लेबलों पर, हर स्तर के विश्वसनीयता बिन, ECE और Brier स्कोर
`GET /schemes/<name>/drift`	हर selective-risk कॉन्ट्रैक्ट का ऑडिट मॉनिटर
`GET /schemes/<name>/optimize`	dev लेबलों पर आँकी गई, सस्ते कैस्केड की रिपोर्ट
`GET /requests`	उद्देश्य और स्थिति के अनुसार अनुरोधों की गिनती, और खुद अनुरोध। फ़िल्टर हैं `purpose`, `status` (पैरामीटर दोहराएँ या मानों को कॉमा से अलग करें), `schema` और `limit` (अधिकतम 1000)
`GET /calls`	कॉल लॉग, सबसे नई पहले, और स्रोत के अनुसार योग। `limit` (अधिकतम 500), `offset`
`GET /certificate`	प्रमाणपत्र। `format=json` (डिफ़ॉल्ट), `md` या `html`, और `save=1` उसे संग्रहीत भी करता है
`GET /crowd`	प्लानर की पिछली क्राउड योजना, ड्राई रन, जब तक लाइव खर्च चालू न हो
`POST /certify`	हर कॉन्ट्रैक्ट को अभी परखें। `?retest=1` (या `{"retest": true}`) ऐसे नियम को भी परखता है जिसे केवल dev लेबलों ने बदला
`POST /plan`	अभी एक प्लानर पास चलाएँ

अध्ययन के लिए इंजन बंद हो तो रूट 404 लौटाते हैं। अमान्य पैरामीटर पर वे JSON त्रुटि के साथ 400 लौटाते हैं, जैसे संख्या न होने वाला limit, अज्ञात purpose या status, या json, md और html के अलावा कोई format।

उदाहरण के लिए, यह अनुरोध पोर्ट 8000 पर चल रहे सर्वर से मौजूदा प्रमाणपत्र Markdown के रूप में लाता है:

bash

curl -H "X-API-Key: $ADMIN_API_KEY" \
  "http://localhost:8000/api/engine/v1/certificate?format=md"

MCP टूल

MCP सर्वर पाँच इंजन टूल उपलब्ध कराता है, REST रूट वाली ही अनुमतियों के साथ:

engine_status
engine_requests
engine_run, जो एक प्लानर पास चलाता है
engine_certify, जो retest लेता है
engine_certificate, json, md या html में

इंजन बंद होने पर ये टूल देना एक वैलिडेशन चेतावनी है। potato mcp connect के ज़रिए, अस्वीकृत कॉल (कोई अनुमति न होना, गलत पैरामीटर) सर्वर के संदेश के साथ टूल त्रुटि के रूप में लौटती है। टूल देने और क्लाइंट जोड़ने का तरीका MCP सर्वर दस्तावेज़ में है।

Python SDK

Study क्लास इंजन को Python से चलाती है, जैसे किसी नोटबुक में:

python

from potato.labeling_engine.sdk import Study
 
study = Study("examples/labeling-engine/text-certified-sentiment/config.yaml")
study.run()                                   # label, sample, certify, resolve
for req in study.requests(status="open")[:5]:
    study.label(req.item_id, req.schema, "positive", user="me")
study.certify()
print(study.certificate(fmt="md"))
study.export("out/")

हर मेथड किसी कमांड या रूट जैसा ही है:

मेथड	क्या करता है
`Study(config_path)`	कॉन्फ़िग और आइटम लोड करता है
`run(until="predicted", max_ticks=20)`	`potato label run` की तरह, और राइटर लॉक लेता है
`label(item_id, scheme, value, user, request_id=None)`	किसी व्यक्ति का लेबल दर्ज करता है। यह `request_id` को, या उसके न होने पर आइटम पर इस व्यक्ति के पास मौजूद किसी अनुरोध को बंद करता है, और नहीं तो लेबल को ऑर्गेनिक लेबल के रूप में रखा जाता है, जो कभी प्रमाणित नहीं करता। उसी आइटम पर उसी व्यक्ति का दूसरा लेबल उसके पहले लेबल को अपडेट करता है
`status()`	`GET /status` की तरह
`requests(status=None, purpose=None, ...)`	अनुरोधों का बहीखाता
`certify(retest=False)`	`potato label certify` की तरह
`certificate(fmt="json")`	`json`, `md` या `html`
`export(out_dir)`	`potato label export` की तरह

उदाहरण हर खुले अनुरोध पर "positive" लेबल केवल कॉल दिखाने के लिए लगाता है। Study.label से दर्ज किया गया जो लेबल किसी अनुरोध का उत्तर नहीं देता, उसे ऑर्गेनिक लेबल के रूप में रखा जाता है, और ऑर्गेनिक लेबल कभी प्रमाणित नहीं करते, इसलिए जो स्क्रिप्ट उन आइटमों पर लेबल लगाती है जिन्हें इंजन ने नहीं माँगा, वह ऐसे लेबल जोड़ती है जिन्हें कोई कॉन्ट्रैक्ट नहीं पढ़ता।

आगे पढ़ें

लेबलिंग इंजन
लेबलिंग इंजन कॉन्फ़िगरेशन
लेबलिंग इंजन कॉन्ट्रैक्ट
एडमिन डैशबोर्ड, जो इंजन के एडमिन पेज का लिंक देता है

कार्यान्वयन विवरण के लिए, स्रोत दस्तावेज़ देखें।