Skip to content
घोषणाएँ9 मिनट में पढ़ें

Potato 2.3: Agentic Annotation, Solo Mode और Best-Worst Scaling

Potato 2.3.0 में human-LLM labeling के लिए Solo Mode, agent trace annotation, Best-Worst Scaling, SSO और OAuth login, Parquet export और 15 demo projects जोड़े गए हैं।

Potato Team

ध्यान दें: यह पोस्ट Potato 2.3 का वह रूप बताती है जो मार्च 2026 में रिलीज़ के वक़्त था। नीचे दी गई कई config keys बाद के संस्करणों में बदल दी गईं या हटाकर दूसरी keys से बदली गईं, और मौजूदा सिंटैक्स दस्तावेज़ में है। इन blocks को किसी मौजूदा Potato पर चल रहे project में कॉपी न करें।

Potato 2.3.0 में Solo Mode जोड़ा गया है, जो human-LLM labeling का एक workflow है और दस documented phases से होकर चलता है। इसके साथ ग्यारह registered trace converters वाला agent trace annotation, तीन scoring methods वाला Best-Worst Scaling, Google, GitHub और generic OIDC providers के लिए SSO और OAuth login, Parquet export और 15 demo projects भी आए हैं। Release notes में 2.2.0 के बाद से 50 या उससे ज़्यादा commits दर्ज हैं, और 8 modules में 12 security vulnerabilities के fixes भी।

यह release उस बदलाव के बाद आई है जो लोगों के annotate करने की चीज़ों में हुआ है। जो researchers दो साल पहले sentiment और named entities label कर रहे थे, वे अब multi-step agent traces की बारीकी से जाँच कर रहे हैं, model outputs की बड़े पैमाने पर तुलना कर रहे हैं, और ऐसे tasks के लिए datasets बना रहे हैं जो Potato का schema set डिज़ाइन होते समय मौजूद ही नहीं थे। Solo Mode और agent trace का काम, दोनों इसी बदलाव को ध्यान में रखकर बनाए गए हैं।

Upgrade करना

bash
pip install --upgrade potato-annotation==2.3.0

Parquet export के लिए PyArrow 12.0.0 या उससे नया संस्करण चाहिए, जिसे अलग से install करना होता है:

bash
pip install "pyarrow>=12.0.0"

Agent trace annotation

एक agent run tool calls, reasoning steps और intermediate outputs का एक क्रम होता है, और उसे plain text में समतल कर देने से वह संरचना खो जाती है जो evaluator को देखनी होती है। इसलिए Potato 2.3 traces को display system के ज़रिए render करता है, ताकि trace एक conversation की तरह दिखे और ratings अलग-अलग turns से जुड़ी हों।

Display को instance_display में घोषित किया जाता है, और हर turn के rating schemes उस field के नीचे nested होते हैं जिसमें conversation है:

yaml
instance_display:
  layout:
    direction: vertical
    gap: 16px
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: conversation
      type: dialogue
      label: "Agent Trace"
      span_target: true
      display_options:
        show_turn_numbers: true
        alternating_shading: true

2.3 में agent से जुड़ा काम दो display types संभालते हैं। dialogue display किसी trace को turns के रूप में render करता है और उन पर span annotation की सुविधा देता है, और interactive_chat उन conversations के लिए है जिनमें annotator बाद में पढ़ने के बजाय ख़ुद हिस्सा लेता है। span_target: true सेट करने से ही annotators किसी turn के भीतर का कोई अंश highlight कर पाते हैं, और hallucinations और बिना आधार वाले दावे इसी तरह उसी जगह mark होते हैं जहाँ वे आते हैं।

दूसरे frameworks के traces converter के ज़रिए आते हैं, जो इस release में ग्यारह formats register करता है: openai, anthropic, swebench, otel, mcp, multi_agent, langchain, langfuse, react, webarena और atif।

bash
python -m potato.trace_converter -i traces.json -f react -o data/traces.jsonl

Solo Mode

कई annotators के साथ labeling के लिए लोगों को hire करना, train करना और उनके काम का तालमेल बिठाना पड़ता है, और कई research projects में annotation interface से ज़्यादा यही logistics रुकावट बनती है। Solo Mode इसकी जगह एक domain expert को एक LLM के साथ जोड़ता है। Human label करता है, LLM सुझाव देता है, हर correction वापस prompt में जाता है, और जैसे-जैसे दोनों एक-दूसरे के करीब आते हैं, human queue का बड़ा हिस्सा LLM को सौंपता जाता है।

Workflow दस documented phases से होकर चलता है: setup, prompt review, edge case synthesis, edge case labeling, prompt validation, parallel annotation, disagreement resolution, periodic review, autonomous labeling और final validation। हर project हर phase से नहीं गुज़रता।

yaml
solo_mode:
  enabled: true
 
  labeling_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
      max_tokens: 256
      temperature: 0.1
 
  revision_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
 
  uncertainty:
    strategy: "direct_confidence"
 
  thresholds:
    end_human_annotation_agreement: 0.90
    minimum_validation_sample: 20
    confidence_low: 0.5
    periodic_review_interval: 50
 
  instance_selection:
    low_confidence_weight: 0.4
    diversity_weight: 0.3
    random_weight: 0.2
    disagreement_weight: 0.1
 
  state_dir: "solo_state"

instance_selection के चार weights तय करते हैं कि कौन से items पर human का ध्यान देना ज़रूरी है। Low confidence को 0.4 और diversity को 0.3 weight देने से human का ज़्यादातर समय उन instances पर जाता है जिन पर model अनिश्चित है, और साथ ही बाकी distribution की इतनी coverage बनी रहती है कि कोई systematic error पकड़ में आ सके। Random sampling पर 0.2 का weight ही end_human_annotation_agreement में agreement के अनुमान को सार्थक बनाता है, क्योंकि सिर्फ़ कठिन instances पर निकाली गई agreement rate वह rate नहीं है जो आपको पूरे corpus पर मिलती है।

Solo Mode के साथ 85 integration और end-to-end tests, एक developer guide, और examples/advanced/solo-mode/ और examples/advanced/simple-solo-mode/ में दो example projects आते हैं। Simple वाले से शुरू करें, जो local Ollama model पर चलता है और जिसे API key की ज़रूरत नहीं होती, ताकि आप पहले यह परखें कि workflow आपके task के लिए सही है या नहीं, न कि यह कि model अपनी लागत के लायक है या नहीं।

Best-Worst Scaling

Best-Worst Scaling annotator को items का एक tuple दिखाता है, आमतौर पर चार items का, और एक criterion के आधार पर सिर्फ़ सबसे अच्छा और सबसे खराब चुनने को कहता है। इन दो चुनावों से pairwise comparisons का एक set निकलता है, और कई overlapping tuples से मिले scores एक वास्तविक scale पर आते हैं, ऐसे judgments से जो rating देने से जल्दी हो जाते हैं।

yaml
annotation_schemes:
  - annotation_type: bws
    name: sentiment_bws
    description: "Sentiment Intensity"
    best_description: "Which sentence expresses the MOST positive sentiment?"
    worst_description: "Which sentence expresses the LEAST positive sentiment?"
    tuple_size: 4
    sequential_key_binding: true

इकट्ठा किए गए tuples पर तीन scoring methods चलते हैं। counting पारदर्शी baseline है, (best_count - worst_count) / appearances के हिसाब से, इसे किसी अतिरिक्त dependency की ज़रूरत नहीं और यह deterministic है। bradley_terry एक pairwise comparison model fit करता है और log-scale strength parameters देता है। plackett_luce एक पूरा ranking model fit करता है। Model पर आधारित दोनों methods के लिए pip install choix चाहिए।

bash
python -m potato.bws_scoring --config config.yaml --method bradley_terry

Scores output directory में bws_scores.tsv में लिखे जाते हैं, जिसमें हर item का score, rank, best और worst counts और appearances होते हैं। Admin dashboard में एक BWS Scoring tab है जो एक button से यही गणना चलाता है और नतीजे एक table में दिखाता है।

SSO और OAuth

जिस deployment तक annotators internet पर पहुँचते हैं, उसे असली accounts चाहिए, और 2.3 में OAuth 2.0 और OpenID Connect जोड़े गए हैं ताकि वे अपनी पहले से मौजूद identity इस्तेमाल कर सकें। Google, GitHub और कोई भी generic OIDC provider supported है, और access को email domain या GitHub organization के आधार पर सीमित किया जा सकता है।

yaml
authentication:
  method: "oauth"
  providers:
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
  user_identity_field: "email"
 
secret_key: ${POTATO_SECRET_KEY}

यह block अपने config में जोड़ें। इसके साथ दो ज़रूरतें आती हैं। OAuth को HTTPS deployment चाहिए, जिसमें development के लिए localhost को छूट है, और उसे एक स्थिर secret_key चाहिए, क्योंकि हर restart पर बदलने वाली signing key उन sessions को अमान्य कर देती है जो login पहले ही जारी कर चुका है। अपने provider के पास redirect URI को https://your-domain.com/auth/callback/google के रूप में register करें, और उसमें provider का नाम बदल दें।

Parquet export

Annotation data तेज़ी से ऐसे analytics tools में पहुँच रहा है जो columnar format चाहते हैं, इसलिए 2.3 export registry में Parquet जोड़ता है। एक export अधिकतम तीन tables बनाता है: annotations.parquet, जिसमें हर instance और annotator के लिए एक row है, spans.parquet, जिसमें हर span annotation के लिए एक row है, और items.parquet, जिसमें source data है।

bash
python -m potato.export -c config.yaml -f parquet -o ./export/

Options project में configure करने के बजाय command line पर दिए जाते हैं, और compression codec snappy (default), gzip, zstd, lz4 या none में से एक होता है:

bash
python -m potato.export -c config.yaml -f parquet -o ./export/ \
    --option compression=gzip --option include_items=false

Tables instance key पर join होती हैं, हालाँकि column का नाम उनमें अलग है: annotations.parquet और spans.parquet में instance_id है, जबकि items.parquet में item_id है। इसी वजह से export को DuckDB से, पहले pandas में कुछ load किए बिना, इस्तेमाल किया जा सकता है:

python
import duckdb
duckdb.sql("""
  SELECT i.item_id, a.user_id, a.*
  FROM './export/annotations.parquet' a
  JOIN './export/items.parquet' i ON a.instance_id = i.item_id
""")

annotations.parquet में हर instance और annotator के लिए एक row है, और हर annotation scheme अपने अलग column में समतल होता है, इसलिए select करने के लिए कोई generic value column नहीं है। जो scheme एक साथ कई answers store करता है, वह <scheme>.<part> नाम वाले dotted sub-columns में फैल जाता है।

Security fixes

यह release 8 modules में 12 security vulnerabilities ठीक करती है, साथ ही 25 files में XSS, robustness और data integrity की समस्याएँ, और एक span-delete cascade भी, जो dictionary की values के बजाय keys पर iterate करता था और link records पीछे छोड़ देता था। एक dependency audit ने Python और JavaScript dependencies को मौजूदा versions तक पहुँचाया।

दूसरे fixes में से दो ऐसे हैं जो आपके पहले से इकट्ठा किए गए data को बदल सकते थे। has_free_response boolean crash (issue #111) और all-phases navigation loop, दोनों का असर इस पर था कि annotations इच्छित तरीके से record हुए या नहीं, और dynamic multirate quote handling का असर इस पर था कि वे values कैसे लिखी गईं। अगर आपने 2.2 पर free-response options या multirate schemes के साथ कोई study चलाई है, तो output को final मानने से पहले उसे जाँच लें।

Demo projects

इस release में demo/ के अंतर्गत 15 demo projects हैं, जिन्हें उसी क्रम में क्रमांकित किया गया है जिसमें वे एक-दूसरे पर आधारित हैं, 01-sentiment-admin से 15-agentic-chat तक। ये spans, custom moderation layouts, image classification, audio emotion, video, multimodal items, adjudication, sliders, bounding boxes, dependency trees, tiered ELAN annotation और agentic chat को कवर करते हैं। हर demo directory में एक config.yaml और उसका data/ होता है, और पूरा suite एक ही script साझा करता है जो media पर आधारित demos के लिए ज़रूरी media बनाती है।

bash
# From the repository root: generates the demo data, then starts all 15 servers
bash demo/launch.sh

ऊपर बताए गए हर fix सहित पूरे changelog के लिए repository में v2.3.0 release notes देखें। Issues GitHub पर दर्ज करें या GitHub Discussions में thread शुरू करें।