कोडिंग एजेंट एनोटेशन की घोषणा: Claude Code, Aider और SWE-Agent ट्रेस का मूल्यांकन

कोडिंग एजेंट एनोटेशन क्यों मायने रखता है

Claude Code, Aider और SWE-Agent जैसे कोडिंग एजेंट तेज़ी से अच्छे हुए हैं, और अब लोगों को सचमुच उनके काम को परखना पड़ रहा है। एक अकेला रन एक बिखरी हुई ट्रैजेक्टरी होता है: कोड संपादन, टर्मिनल कमांड, फ़ाइल रीड और तर्क-चरण एक के बाद एक पिरोए हुए। बेहतर एजेंट प्रशिक्षित करने के लिए आपको इन रन पर मानवीय फ़ीडबैक चाहिए, और ज़्यादातर टीमों के पास जो एनोटेशन टूल थे वे इस तरह के डेटा के लिए कभी बने ही नहीं थे।

सादा टेक्स्ट एनोटेशन इंटरफ़ेस न unified diff रेंडर कर सकता है, न टर्मिनल आउटपुट को फ़ॉर्मैट कर सकता है, न एजेंट ट्रेस की नेस्टेड संरचना संभाल सकता है। इसलिए लैब अपने ख़ुद के मूल्यांकन UI लिखने लगती हैं, वही काम बार-बार दोहराती हैं, और आख़िर में ऐसे डेटासेट बनते हैं जो एक-दूसरे से मेल ही नहीं खाते।

Potato अब कोडिंग एजेंट एनोटेशन सीधे संभालता है, ट्रेस के लिए बने रेंडरिंग कंपोनेंट, इस तरह के मूल्यांकन के लिए एनोटेशन योजनाएँ, और ऐसे निर्यात के साथ जो सीधे प्रशिक्षण में जाते हैं। पूरे फ़ीचर संदर्भ के लिए कोडिंग एजेंट एनोटेशन दस्तावेज़ और व्यापक एजेंट मूल्यांकन गाइड देखें।

CodingTraceDisplay: एक ट्रेस व्यूअर

एनोटेशन का ज़्यादातर अनुभव CodingTraceDisplay कंपोनेंट से होकर गुज़रता है। यह एजेंट की ट्रैजेक्टरी के हर चरण को उस चरण के प्रकार के हिसाब से उपयुक्त विज़ुअलाइज़ेशन से रेंडर करता है।

Potato में कोडिंग एजेंट एनोटेशन इंटरफ़ेस ऐसा दिखता है:

CodingTraceDisplay कोड diff, टर्मिनल आउटपुट और फ़ाइल रीड को सही फ़ॉर्मैटिंग के साथ रेंडर करता है

Unified Diff दृश्य

कोड संपादन unified diff के रूप में रेंडर होते हैं, जिनमें हटाई गई और जोड़ी गई पंक्तियों के लिए लाल/हरी हाइलाइटिंग होती है। diff दृश्य में पंक्ति संख्याएँ, फ़ाइल पथ के हेडर और बदलावों के आसपास की संदर्भ पंक्तियाँ शामिल हैं। यह GitHub pull request के उसी जाने-पहचाने अनुभव जैसा है जिससे ज़्यादातर डेवलपर पहले से वाक़िफ़ हैं।

# The diff rendering is automatic when your trace data includes tool_use
# steps with file edit operations. No special config is needed.
coding_agent:
  display:
    diff_style: "unified"         # "unified" or "split" side-by-side
    context_lines: 3              # Lines of context around changes
    syntax_highlighting: true     # Language-aware highlighting
    collapse_large_diffs: true    # Auto-collapse diffs > 100 lines
    large_diff_threshold: 100

गहरे टर्मिनल ब्लॉक

Bash कमांड और उनके आउटपुट गहरे रंग के टर्मिनल ब्लॉक में रेंडर होते हैं, मोनोस्पेस फ़ॉन्ट, सही ANSI रंग समर्थन, और लंबे नतीजों के लिए स्क्रॉल होने वाले आउटपुट के साथ। टर्मिनल ब्लॉक चलाया गया कमांड, वर्किंग डायरेक्टरी और exit code दिखाते हैं।

coding_agent:
  display:
    terminal_theme: "dark"        # "dark" or "light"
    max_terminal_height: 400      # pixels, scrollable beyond this
    show_exit_codes: true
    show_working_directory: true
    ansi_colors: true             # Render ANSI escape sequences

पंक्ति-संख्या वाले कोड ब्लॉक

फ़ाइल पढ़ने की क्रियाएँ पंक्ति संख्याओं सहित सिंटैक्स-हाइलाइटेड कोड ब्लॉक के रूप में दिखती हैं। जब एजेंट पंक्तियों की कोई ख़ास सीमा पढ़ता है, तो सिर्फ़ वही पंक्तियाँ अपनी मूल पंक्ति संख्याओं के साथ दिखाई जाती हैं, जिससे असली फ़ाइल से मिलान करना आसान रहता है।

फ़ाइल ट्री साइडबार

एक समेटी जा सकने वाली साइडबार ट्रैजेक्टरी के दौरान छुई गई सारी फ़ाइलें ट्री संरचना में दिखाती है। हर फ़ाइल पर एक आइकन बताता है कि वह बनाई गई, बदली गई, पढ़ी गई या हटाई गई। ट्री में किसी फ़ाइल पर क्लिक करने से ट्रेस में उसके पहले ज़िक्र तक स्क्रॉल हो जाता है।

coding_agent:
  display:
    file_tree:
      enabled: true
      position: "left"            # "left" or "right"
      show_change_icons: true     # Icons for created/modified/deleted
      group_by: "directory"       # "directory" or "chronological"

समेटे जा सकने वाले आउटपुट

किसी भी प्रकार के चरण का लंबा आउटपुट समेटा जा सकता है ताकि ट्रेस पढ़ने लायक बना रहे। एनोटेटर ज़रूरत के मुताबिक़ अलग-अलग चरण खोल सकते हैं, या "Expand All" / "Collapse All" नियंत्रण इस्तेमाल कर सकते हैं। एजेंट के thinking/reasoning ब्लॉक डिफ़ॉल्ट रूप से समेटे रहते हैं पर समीक्षा के लिए उपलब्ध रहते हैं।

coding_agent:
  display:
    collapsible:
      auto_collapse_thinking: true
      auto_collapse_long_output: true
      long_output_threshold: 50   # lines
      default_expanded_types:     # These step types start expanded
        - "file_edit"
        - "bash_command"

प्रोसेस रिवॉर्ड मॉडल (PRM) योजना

प्रोसेस रिवॉर्ड मॉडल सिर्फ़ अंतिम नतीजे को आँकने के बजाय चरण-स्तर पर श्रेय बाँटते हैं। Potato दो PRM एनोटेशन मोड समर्थित करता है, जो रफ़्तार और सटीकता के अलग-अलग संतुलन के लिए बने हैं।

First-Error मोड

first-error मोड में एनोटेटर ट्रैजेक्टरी में स्क्रॉल करता है और उस पहले चरण पर क्लिक करता है जहाँ एजेंट ग़लत होता है। क्लिक किए गए चरण से पहले के सारे चरण अपने आप सही चिह्नित हो जाते हैं, और उसके बाद के सारे चरण (उस चरण समेत) अपने आप ग़लत चिह्नित हो जाते हैं। इससे एनोटेशन काफ़ी तेज़ हो जाता है, क्योंकि एनोटेटर को सिर्फ़ एक बिंदु पहचानना होता है।

annotation_schemes:
  - annotation_type: process_reward
    name: prm_first_error
    mode: "first_error"
    description: "Click the first step where the agent makes an error"

प्रति-चरण मोड

प्रति-चरण मोड में हर चरण को अपनी स्वतंत्र रेटिंग मिलती है। इससे ज़्यादा विस्तृत प्रशिक्षण डेटा बनता है पर प्रति ट्रेस समय ज़्यादा लगता है। एनोटेटर हर चरण को सही, ग़लत या आंशिक रूप से सही आँकते हैं।

annotation_schemes:
  - annotation_type: process_reward
    name: prm_per_step
    mode: "per_step"

कोड रिव्यू योजना

कोड रिव्यू इंटरफ़ेस GitHub PR जैसे एनोटेशन नियंत्रण देता है:

एनोटेटर diff की पंक्तियों पर क्लिक करके इनलाइन टिप्पणी जोड़ सकते हैं, फ़ाइलों को रेट कर सकते हैं और approve/reject फ़ैसला दे सकते हैं

कोड रिव्यू योजना GitHub PR जैसा एनोटेशन एजेंट ट्रेस पर ले आती है। एनोटेटर diff के भीतर ख़ास पंक्तियों पर इनलाइन टिप्पणी छोड़ सकते हैं, अलग-अलग फ़ाइलों को रेट कर सकते हैं, और कुल मिलाकर एक फ़ैसला दे सकते हैं।

annotation_schemes:
  - annotation_type: code_review
    name: agent_review
    comment_categories:
      enabled: true
      categories:                 # Optional categorization for comments
        - "Bug"
        - "Style"
        - "Logic Error"
        - "Unnecessary Change"
        - "Missing Error Handling"
    file_rating_dimensions:
      enabled: true
      scale: [1, 2, 3, 4, 5]
      labels: ["Poor", "Below Average", "Acceptable", "Good", "Excellent"]
    verdict_options:
      enabled: true
      options:
        - value: "approve"
          text: "Approve"
          description: "Changes are correct and complete"
        - value: "request_changes"
          text: "Request Changes"
          description: "Changes need fixes before merging"
        - value: "comment"
          text: "Comment"
          description: "General feedback, no strong opinion"

ट्रेस कन्वर्टर: किसी भी एजेंट से आयात

Potato में तीन सबसे लोकप्रिय कोडिंग एजेंट फ़ॉर्मैट के लिए पहले से कन्वर्टर मौजूद हैं। ये कन्वर्टर हर फ़ॉर्मैट को Potato के आंतरिक संरचित ट्रेस प्रतिनिधित्व में ढाल देते हैं।

Claude Code (Anthropic Messages API)

Claude Code ट्रेस Anthropic Messages API फ़ॉर्मैट इस्तेमाल करते हैं, जिसमें tool_use और tool_result कंटेंट ब्लॉक होते हैं। कन्वर्टर टूल कॉल से फ़ाइल संपादन, bash कमांड और फ़ाइल रीड निकालता है और असिस्टेंट का तर्क-पाठ बनाए रखता है।

# Convert Claude Code traces to Potato format
potato convert-traces \
  --format claude_code \
  --input ./claude_traces/ \
  --output ./potato_data/traces.jsonl

Aider (एडिट ब्लॉक वाला मार्कडाउन चैट)

Aider मार्कडाउन में फ़ॉर्मैट किए चैट लॉग बनाता है, जिनमें SEARCH/REPLACE एडिट ब्लॉक होते हैं। कन्वर्टर इन ब्लॉक को पढ़कर फ़ाइल संपादन दोबारा खड़ा करता है और फ़ेंस्ड कोड ब्लॉक से शेल कमांड निकालता है।

# Convert Aider chat logs
potato convert-traces \
  --format aider \
  --input ./aider_logs/ \
  --output ./potato_data/traces.jsonl

SWE-Agent (Thought/Action/Observation)

SWE-Agent thought/action/observation लूप फ़ॉर्मैट इस्तेमाल करता है। कन्वर्टर क्रियाओं को उपयुक्त चरण प्रकारों (edit, bash, read) से जोड़ता है और एजेंट के chain-of-thought तर्क को समेटे जा सकने वाले thinking ब्लॉक के रूप में बनाए रखता है।

# Convert SWE-Agent trajectories
potato convert-traces \
  --format swe_agent \
  --input ./swe_agent_trajectories/ \
  --output ./potato_data/traces.jsonl

अपने आप पहचान

अगर आपके पास कई एजेंट से ट्रेस हैं, तो Potato हर फ़ाइल की संरचना देखकर फ़ॉर्मैट ख़ुद पहचान सकता है:

# Auto-detect format for mixed trace directories
potato convert-traces \
  --format auto \
  --input ./mixed_traces/ \
  --output ./potato_data/traces.jsonl

प्रशिक्षण पाइपलाइन के लिए निर्यात

एनोटेट किए गए ट्रेस मॉडल प्रशिक्षण के लिए तैयार फ़ॉर्मैट में निर्यात किए जा सकते हैं।

PRM फ़ॉर्मैट

प्रोसेस रिवॉर्ड मॉडल प्रशिक्षित करने के लिए चरण-स्तरीय रिवॉर्ड लेबल:

# Exported PRM format (one line per trace)
{
  "trace_id": "trace_001",
  "steps": [
    {"step_idx": 0, "content": "Read file src/main.py", "label": "correct"},
    {"step_idx": 1, "content": "Edit src/main.py: fix import", "label": "correct"},
    {"step_idx": 2, "content": "Run tests", "label": "correct"},
    {"step_idx": 3, "content": "Edit src/utils.py: wrong fix", "label": "incorrect"},
    {"step_idx": 4, "content": "Run tests again", "label": "incorrect"}
  ],
  "first_error_step": 3
}

DPO/RLHF प्रेफ़रेंस जोड़े

जोड़ीदार तुलना के एनोटेशन के साथ मिलाने पर Potato ऐसे प्रेफ़रेंस जोड़े बनाता है जो Direct Preference Optimization या RLHF प्रशिक्षण के लिए उपयुक्त हैं:

# Exported preference pair format
{
  "prompt": "Fix the failing test in src/test_utils.py",
  "chosen": {"trace_id": "trace_001", "steps": [...]},
  "rejected": {"trace_id": "trace_002", "steps": [...]},
  "preference_strength": 0.85
}

SWE-bench के अनुकूल नतीजे

प्रकाशित बेंचमार्क से सीधी तुलना के लिए एनोटेशन को SWE-bench मूल्यांकन हार्नेस के अनुकूल फ़ॉर्मैट में निर्यात करें:

# Export to SWE-bench format
potato export \
  --format swe_bench \
  --project ./my_project/ \
  --output ./swe_bench_results.json

जल्दी शुरू करें

शून्य से चलता हुआ एनोटेशन सर्वर खड़ा करने में लगभग पाँच मिनट लगते हैं।

इंस्टॉलेशन

pip install potato-annotation[coding-agents]

अपने ट्रेस बदलें

# Convert traces from your coding agent
potato convert-traces \
  --format auto \
  --input ./my_agent_traces/ \
  --output ./data/traces.jsonl

अपना कॉन्फ़िग बनाएँ

PRM और कोड रिव्यू दोनों योजनाओं का इस्तेमाल करने वाले कोडिंग एजेंट मूल्यांकन प्रोजेक्ट का पूरा कॉन्फ़िगरेशन यह रहा:

# config.yaml
project_name: "Coding Agent Evaluation"
port: 8000
 
data:
  source: "local"
  input_path: "./data/traces.jsonl"
  data_format: "coding_trace"
 
coding_agent:
  display:
    diff_style: "unified"
    context_lines: 3
    syntax_highlighting: true
    collapse_large_diffs: true
    terminal_theme: "dark"
    max_terminal_height: 400
    show_exit_codes: true
    file_tree:
      enabled: true
      position: "left"
      show_change_icons: true
    collapsible:
      auto_collapse_thinking: true
      auto_collapse_long_output: true
 
annotation_schemes:
  - annotation_type: process_reward
    name: prm_evaluation
    mode: "first_error"
    description: "Click the first step where the agent makes a mistake"
 
  - annotation_type: code_review
    name: code_quality
    comment_categories:
      enabled: true
      categories: ["Bug", "Logic Error", "Style", "Missing Error Handling"]
    file_rating_dimensions:
      enabled: true
      scale: [1, 2, 3, 4, 5]
    verdict_options:
      enabled: true
      options:
        - value: "approve"
          text: "Approve"
        - value: "request_changes"
          text: "Request Changes"
        - value: "comment"
          text: "Comment"
 
  - annotation_type: text
    name: overall_notes
    description: "Additional Notes"
    placeholder: "Any other observations about this trace..."
output:
  path: "./output/"
  format: "jsonl"
  export_formats:
    - "prm"
    - "swe_bench"
 
quality_control:
  inter_annotator_agreement: true
  overlap_percentage: 20
  minimum_time_per_instance: 30  # seconds
 
annotators:
  - username: "annotator1"
  - username: "annotator2"

सर्वर चलाएँ

potato start config.yaml -p 8000

अपने ब्राउज़र में http://localhost:8000 खोलें, लॉग इन करें, और एनोटेशन शुरू करें। ऊपर बताई गई पूरी diff रेंडरिंग, टर्मिनल आउटपुट और प्रोसेस रिवॉर्ड एनोटेशन आपको मिल जाती है।

आगे क्या

यह पहला रिलीज़ है, और हम इसमें और भी करना चाहते हैं। सूची में हैं: और एजेंट फ़ॉर्मैट का समर्थन, कई फ़ाइलों वाले रीफ़ैक्टर के लिए बेहतर विज़ुअलाइज़ेशन, और OpenRLHF तथा TRL जैसे प्रशिक्षण फ़्रेमवर्क के साथ नज़दीकी एकीकरण।

अगर आप कोई नया ट्रेस कन्वर्टर, योजना या निर्यात फ़ॉर्मैट लिखें, तो हमें आपका योगदान पाकर ख़ुशी होगी। और अगर आपकी टीम कोडिंग एजेंट का मूल्यांकन कर रही है और कोई ऐसी चीज़ सामने आती है जो यह सेटअप कवर नहीं करता, तो हमारी GitHub रिपॉज़िटरी पर issue खोलें।