कोड रिव्यू एनोटेशन

v2.4.0 में नया

AI कोडिंग एजेंट के बनाए कोड बदलावों का मूल्यांकन करने के लिए बाइनरी पास/फ़ेल फ़ैसला काफ़ी नहीं है। शोधकर्ताओं और इंजीनियरिंग टीमों को कोड की गुणवत्ता कई स्तरों पर आँकनी होती है: अलग-अलग पंक्तियों में बग या शैली का उल्लंघन हो सकता है, पूरी फ़ाइल सही ढंग से बदली गई हो सकती है या ग़ैरज़रूरी हो सकती है, और बदलावों का पूरा सेट समस्या हल तो कर दे पर तकनीकी क़र्ज़ छोड़ जाए। GitHub पर pull request देखते समय मानव कोड रिव्यूअर यही कार्यप्रवाह अपनाते हैं।

Potato का कोड रिव्यू एनोटेशन मोड GitHub PR रिव्यू का अनुभव एजेंट मूल्यांकन में ले आता है। एजेंट ने जो भी फ़ाइल बदली है, एनोटेटर उसका unified diff देखते हैं। वे diff की किसी भी पंक्ति पर क्लिक करके श्रेणी टैग सहित इनलाइन टिप्पणी छोड़ सकते हैं। हर फ़ाइल को शुद्धता और गुणवत्ता की रेटिंग मिलती है। एनोटेटर आख़िरी फ़ैसला देता है: approve, request changes, या सिर्फ़ comment। यह सब संरचित एनोटेशन डेटा के रूप में दर्ज होता है, जो कोड गुणवत्ता मॉडल के प्रशिक्षण के लिए तैयार होता है।

इनलाइन टिप्पणियाँ

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

टिप्पणी श्रेणियाँ

डिफ़ॉल्ट टिप्पणी श्रेणियाँ कोड रिव्यू में मिलने वाली सबसे आम प्रतिक्रियाओं को कवर करती हैं:

कॉन्फ़िगरेशन

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Click any diff line to add an inline comment"
 
    # Categories offered on each inline comment
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question

सुझाए गए कोड बदलाव

जब allow_suggestions चालू हो, तो एनोटेटर जिस कोड ब्लॉक पर टिप्पणी कर रहे हैं उसके लिए बदलकर रखा जाने वाला कोड सुझा सकते हैं। यह GitHub के "suggestion" फ़ीचर जैसा है। सुझाव टिप्पणी के नीचे एक कोड ब्लॉक में दिखता है और उससे कोड मरम्मत मॉडल प्रशिक्षित किए जा सकते हैं।

{
  "category": "bug",
  "file": "src/parser.py",
  "line": 42,
  "text": "Off-by-one error: range should be inclusive of end"
}

फ़ाइल-स्तरीय रेटिंग

एजेंट ने जो भी फ़ाइल बदली है, उसे दो स्वतंत्र रेटिंग मिलती हैं: शुद्धता और कोड गुणवत्ता।

कॉन्फ़िगरेशन

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Rate each modified file"
 
    # One 1-5 rating per dimension, per file touched by the diff
    file_rating_dimensions:
      - correctness
      - quality

आउटपुट फ़ॉर्मैट

{
  "file_ratings": {
    "src/parser.py": {
      "correctness": 4,
      "quality": 3
    },
    "tests/test_parser.py": {
      "correctness": 5,
      "quality": 4
    },
    "src/utils.py": {
      "correctness": 2,
      "quality": 2
    }
  }
}

कुल फ़ैसला

सारी फ़ाइलें देख लेने और इनलाइन टिप्पणियाँ छोड़ देने के बाद एनोटेटर पूरे बदलाव-सेट पर एक कुल फ़ैसला देता है।

कॉन्फ़िगरेशन

annotation_schemes:
  - annotation_type: code_review
    name: review
    description: "Give an overall verdict on the code changes"
 
    verdict_options:
      - approve
      - request_changes
      - comment_only

कॉन्फ़िगरेशन संदर्भ

कोड रिव्यू एनोटेशन टास्क का पूरा कॉन्फ़िगरेशन:

annotation_task_name: "Coding Agent Code Review"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
instance_display:
  fields:
    - key: structured_turns
      type: coding_trace
      label: "Agent changes"
      display_options:
        diff_view: unified
        terminal_theme: dark
        collapse_long_outputs: true
        max_output_lines: 50
        show_file_tree: true
        show_step_numbers: true
        show_reasoning: true
 
annotation_schemes:
  # Inline comments, file ratings and the overall verdict are all one scheme
  - annotation_type: code_review
    name: review
    description: "Review the agent's code changes"
    comment_categories:
      - bug
      - logic
      - security
      - performance
      - style
      - suggestion
      - question
      - praise
    file_rating_dimensions:
      - correctness
      - quality
    verdict_options:
      - approve
      - request_changes
      - comment_only
 
  # A free-text summary is a separate scheme
  - annotation_type: text
    name: summary
    description: "Summarize your review"
    rows: 4
 
output_annotation_dir: "output/"
export_annotation_format: "jsonl"

एनोटेशन कार्यप्रवाह

कोड रिव्यू एनोटेशन टास्क करते समय एनोटेटर को क्या दिखता है और वे क्या करते हैं:

1. टास्क का ब्यौरा: ऊपर टास्क का विवरण दिखता है, जिससे पता चलता है कि एजेंट से क्या करने को कहा गया था (जैसे, "test_parser.py में विफल हो रहा टेस्ट ठीक करें")।

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

3. diff की समीक्षा: मुख्य पैनल हर फ़ाइल का unified diff दिखाता है। एनोटेटर diff में आगे बढ़ते हुए हर बदलाव पढ़ते हैं।

4. इनलाइन टिप्पणियाँ जोड़ना: किसी पंक्ति संख्या पर क्लिक करने से टिप्पणी फ़ॉर्म खुल जाता है। एनोटेटर एक श्रेणी चुनता है (bug, suggestion वग़ैरह), चाहे तो गंभीरता चुनता है, अपनी टिप्पणी लिखता है, और चाहे तो एक कोड सुझाव भी जोड़ता है।

5. फ़ाइल रेटिंग: हर फ़ाइल का diff देखने के बाद एनोटेटर उसे उसी diff के नीचे मौजूद रेटिंग विजेट से शुद्धता (1-5) और कोड गुणवत्ता (1-5) पर रेट करता है।

6. कुल फ़ैसला: सबसे नीचे एनोटेटर एक फ़ैसला चुनता है (approve, request changes, या सिर्फ़ comment) और अपनी समीक्षा का सारांश लिखता है।

7. जमा करना: एनोटेटर "Submit" पर क्लिक करके सारी इनलाइन टिप्पणियाँ, फ़ाइल रेटिंग और फ़ैसला एक ही एनोटेशन रिकॉर्ड के रूप में सहेज देता है।

डेटा फ़ॉर्मैट

एक कोड रिव्यू एनोटेशन का पूरा आउटपुट:

{
  "instance_id": "trace_042",
  "annotator": "reviewer_01",
  "verdict": "request_changes",
  "comments": [
    {
      "category": "bug",
      "file": "src/parser.py",
      "line": 42,
      "text": "This will throw IndexError when tokens list is empty"
    },
    {
      "category": "style",
      "file": "src/parser.py",
      "line": 15,
      "text": "Variable name 'x' is not descriptive"
    },
    {
      "category": "praise",
      "file": "tests/test_parser.py",
      "line": 28,
      "text": "Good edge case coverage for empty input"
    }
  ],
  "file_ratings": {
    "src/parser.py": { "correctness": 3, "quality": 2 },
    "tests/test_parser.py": { "correctness": 5, "quality": 4 }
  }
}

निर्यात

कोड रिव्यू एनोटेशन कई फ़ॉर्मैट में निर्यात किए जा सकते हैं:

python -m potato.export \
  -c config.yaml \
  -f coding_eval \
  -o results/ \
  --option types=code_review

code_review_comments फ़ॉर्मैट ख़ास तौर पर उन मॉडलों के प्रशिक्षण में काम आता है जो कोड रिव्यू टिप्पणियाँ बनाते हैं या कोड की समस्याओं की जगह और श्रेणी का अनुमान लगाते हैं।

यह भी देखें

• कोडिंग एजेंट एनोटेशन -- diff रेंडरिंग और फ़ाइल ट्री के साथ कोडिंग एजेंट ट्रेस दिखाएँ
• प्रोसेस रिवॉर्ड एनोटेशन -- PRM प्रशिक्षण के लिए प्रति-चरण रिवॉर्ड संकेत
• लाइव कोडिंग एजेंट अवलोकन -- कोडिंग एजेंट को असल समय में देखें और उनसे बातचीत करें
• एजेंटिक एनोटेशन -- सामान्य-प्रयोजन एजेंट ट्रेस एनोटेशन
• निर्यात फ़ॉर्मैट -- सभी समर्थित निर्यात फ़ॉर्मैट

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