कोडिंग एजेंट एनोटेशन

diff रेंडरिंग, टर्मिनल आउटपुट और फ़ाइल ट्री नेविगेशन के साथ कोडिंग एजेंट ट्रेस का एनोटेशन करें। Claude Code, Aider, SWE-Agent और दूसरे कोडिंग सहायकों से आयात करें।

v2.4.0 में नया

कोडिंग एजेंट -- Claude Code, Aider, SWE-Agent, OpenHands और दूसरे -- ऐसे ट्रेस बनाते हैं जो सामान्य एजेंट ट्रेस से अलग होते हैं। उनमें कोड diff, टर्मिनल आउटपुट, फ़ाइल रीड, डायरेक्टरी ट्रैवर्सल और टेस्ट नतीजे होते हैं। ऐसे ट्रेस की समीक्षा के लिए ख़ास रेंडरिंग चाहिए, जो कोड बदलावों की संरचना समझे और उन्हें सॉफ़्टवेयर इंजीनियरों के जाने-पहचाने फ़ॉर्मैट में दिखाए।

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

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

अपने प्रोजेक्ट कॉन्फ़िग में कोडिंग ट्रेस डिस्प्ले चालू करें:

yaml

instance_display:
  fields:
    - key: structured_turns
      type: coding_trace
      label: "Agent session"
      display_options:
        # Diff rendering
        diff_view: unified          # "unified" or "side_by_side"
 
        # Terminal output
        terminal_theme: dark        # "dark" or "light"
 
        # Long output
        collapse_long_outputs: true
        max_output_lines: 50        # collapse after this many lines
 
        # Step chrome
        show_file_tree: true
        show_step_numbers: true
        show_tool_badges: true
        show_reasoning: true
        compact: false

डिस्प्ले की सुविधाएँ

Unified Diff दृश्य

संपादन ऑपरेशन unified diff के रूप में रेंडर होते हैं, लाल/हरी हाइलाइटिंग के साथ। हटाई गई पंक्तियाँ लाल पृष्ठभूमि और - उपसर्ग के साथ दिखती हैं; जोड़ी गई पंक्तियाँ हरी पृष्ठभूमि और + उपसर्ग के साथ। संदर्भ पंक्तियाँ तटस्थ धूसर रंग में दिखती हैं। हर diff ब्लॉक के ऊपर एक हेडर बार में फ़ाइल पथ और पंक्ति रेंज दिखती है।

diff_style: side_by_side सेट करने पर पुराना और नया संस्करण साथ-साथ कॉलम में दिखते हैं, जिससे जटिल संपादनों में बदलाव देखना आसान हो जाता है।

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

Bash और शेल कमांड मोनोस्पेस फ़ॉन्ट में गहरे टर्मिनल ब्लॉक के रूप में रेंडर होते हैं। कमांड ख़ुद $ prompt उपसर्ग के साथ दिखता है, और उसके नीचे आउटपुट। एग्ज़िट कोड एक छोटे बैज में दिखते हैं (0 के लिए हरा, ग़ैर-शून्य के लिए लाल)। लंबे आउटपुट अपने आप समिट जाते हैं और उनके साथ "Show N more lines" वाला विस्तारक आता है।

पंक्ति संख्या सहित फ़ाइल रीड

जब एजेंट कोई फ़ाइल पढ़ता है, तो सामग्री पंक्ति संख्याओं के साथ एक हल्के कोड ब्लॉक में दिखती है। आंशिक रीड पंक्ति रेंज दिखाते हैं (जैसे "lines 42-87 of 312")। सिंटैक्स हाइलाइटिंग फ़ाइल एक्सटेंशन के आधार पर लगती है।

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

फ़ाइल ट्री साइडबार में वे सारी फ़ाइलें दिखती हैं जिन्हें एजेंट ने ट्रेस के दौरान छुआ। फ़ाइलें डायरेक्टरी के हिसाब से समूहबद्ध और वर्णक्रम में क्रमित होती हैं। हर फ़ाइल पर एक आइकॉन बताता है कि उस पर क्या ऑपरेशन हुए:

संपादित फ़ाइलों के लिए पेंसिल आइकॉन
सिर्फ़ पढ़ी गई फ़ाइलों के लिए आँख आइकॉन
नई बनी फ़ाइलों के लिए प्लस आइकॉन
हटाई गई फ़ाइलों के लिए कूड़ेदान आइकॉन
चलाई गई स्क्रिप्ट के लिए टर्मिनल आइकॉन

ट्री में किसी फ़ाइल पर क्लिक करने से मुख्य पैनल उस फ़ाइल से जुड़े पहले ऑपरेशन तक स्क्रॉल हो जाता है।

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

auto_collapse_threshold से बड़ा कोई भी आउटपुट ब्लॉक अपने आप समिट जाता है। एक सारांश पंक्ति में पहली और आख़िरी कुछ पंक्तियाँ दिखती हैं, साथ में "Show all N lines" बटन। इससे ट्रेस तब भी चलने-फिरने लायक़ रहता है जब कोई एक ऑपरेशन सैकड़ों पंक्तियों का आउटपुट बना दे।

ट्रेस कन्वर्टर

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

कन्वर्टर	स्रोत	फ़ॉर्मैट
`claude_code`	Claude Code / Anthropic API	`tool_use` ब्लॉक वाला Messages API (Read, Edit, Bash, Write टूल)
`aider`	Aider	SEARCH/REPLACE और ORIGINAL/UPDATED संपादन ब्लॉक वाले Markdown चैट लॉग
`swe_agent_trajectory`	SWE-Agent	thought/action/observation त्रिक वाली ट्रैजेक्टरी JSON फ़ाइलें
`auto`	स्वतः पहचान	ट्रेस की संरचना जाँचकर अपने आप सबसे उपयुक्त कन्वर्टर चुनता है

अपने कॉन्फ़िग में कन्वर्टर बताएँ:

bash

python -m potato.trace_converter \
  --input traces.json \
  --input-format claude_code \
  --output data/traces.jsonl

Claude Code कन्वर्टर

claude_code कन्वर्टर Anthropic Messages API से आने वाले उन ट्रेस को सँभालता है जहाँ टूल इस्तेमाल tool_use और tool_result सामग्री ब्लॉक के रूप में दर्ज होता है। यह मानक Claude Code टूल पहचानता है:

Read टूल कॉल फ़ाइल रीड डिस्प्ले बन जाते हैं
Edit टूल कॉल unified diff बन जाते हैं
Write टूल कॉल फ़ाइल निर्माण डिस्प्ले बन जाते हैं
Bash टूल कॉल टर्मिनल ब्लॉक बन जाते हैं
Glob/Grep टूल कॉल खोज परिणाम डिस्प्ले बन जाते हैं

Aider कन्वर्टर

aider कन्वर्टर Aider के markdown-आधारित चैट फ़ॉर्मैट को पार्स करता है। यह SEARCH/REPLACE ब्लॉक (और पुराना ORIGINAL/UPDATED फ़ॉर्मैट) निकालकर उन्हें unified diff में बदलता है। शेल कमांड और उनका आउटपुट bash या shell चिह्नित fenced कोड ब्लॉक से निकाले जाते हैं।

SWE-Agent ट्रैजेक्टरी कन्वर्टर

swe_agent_trajectory कन्वर्टर SWE-Agent की ट्रैजेक्टरी JSON फ़ाइलें पढ़ता है। हर ट्रैजेक्टरी प्रविष्टि में एक thought (एजेंट का तर्क), एक action (चलाया गया कमांड), और एक observation (कमांड का आउटपुट) होता है। कन्वर्टर क्रियाओं को फ़ाइल संपादन, फ़ाइल रीड, शेल कमांड और नेविगेशन ऑपरेशन में बाँटता है।

CLI इस्तेमाल

एनोटेशन सर्वर शुरू करने से पहले कच्चे ट्रेस बदल लें:

bash

# Convert Claude Code traces
python -m potato.trace_converter \
  -i traces.json \
  -f claude_code \
  -o data/converted.jsonl
 
# Convert Aider chat logs
python -m potato.trace_converter \
  -i aider_chat_history/ \
  -f aider \
  -o data/aider_converted.jsonl
 
# Convert SWE-Agent trajectories
python -m potato.trace_converter \
  -i trajectories/ \
  -f swe_agent_trajectory \
  -o data/swe_converted.jsonl
 
# Auto-detect format
python -m potato.trace_converter \
  -i mixed_traces/ \
  -f auto \
  -o data/auto_converted.jsonl

-i फ़्लैग एक फ़ाइल या एक डायरेक्टरी लेता है। डायरेक्टरी देने पर सारी .json और .jsonl फ़ाइलें प्रोसेस होती हैं। कन्वर्टर आउटपुट फ़ाइल में हर पंक्ति पर एक JSON ऑब्जेक्ट लिखता है।

अतिरिक्त विकल्प:

bash

# Filter by file extension
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --include "*.json"
 
# Add metadata fields from a CSV
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --metadata metadata.csv --join-key trace_id
 
# Validate output without writing
python -m potato.trace_converter \
  -i traces.json -f claude_code --validate

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

रूपांतरण के बाद, आउटपुट JSONL फ़ाइल की हर पंक्ति इस संरचना का पालन करती है:

json

{
  "id": "trace_001",
  "task_description": "Fix the failing test in test_parser.py",
  "repository": "myproject",
  "structured_turns": [
    {
      "role": "assistant",
      "content": "I'll read the parser first to see how it handles empty input.",
      "tool_calls": [
        {
          "tool": "Read",
          "input": { "file_path": "src/parser.py" },
          "output": "def parse(input_str):\n    tokens = tokenize(input_str)\n    ..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": "Empty input returns None where the test expects a ParseError.",
      "tool_calls": [
        {
          "tool": "Edit",
          "input": {
            "file_path": "src/parser.py",
            "old_string": "    if len(tokens) == 0:\n        return None",
            "new_string": "    if len(tokens) == 0:\n        raise ParseError('Empty input')"
          },
          "output": "Edited src/parser.py"
        },
        {
          "tool": "Bash",
          "input": { "command": "python -m pytest test_parser.py -v" },
          "output": "test_parser.py::test_empty_input PASSED\ntest_parser.py::test_valid_input PASSED\n\n2 passed in 0.34s"
        }
      ]
    }
  ],
  "metadata": {
    "agent": "claude_code",
    "model": "claude-sonnet-4-20250514",
    "total_tokens": 15234,
    "duration_seconds": 42
  }
}

structured_turns सरणी ऑपरेशन का सटीक क्रम बनाए रखती है। हर टर्न में एक type फ़ील्ड (file_read, edit, terminal, file_write, search, thought) और उस टाइप से जुड़ी फ़ील्ड होती हैं।

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

नीचे एक पूरा कॉन्फ़िगरेशन है, जो कोडिंग ट्रेस डिस्प्ले को कोडिंग एजेंट आउटपुट आँकने वाले एनोटेशन स्कीमा के साथ जोड़ता है:

yaml

annotation_task_name: "Coding Agent Evaluation"
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 session"
      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_tool_badges: true
        show_reasoning: true
 
annotation_schemes:
  # Did the agent complete the task?
  - annotation_type: radio
    name: task_completion
    description: "Did the agent successfully complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
      - "Made Things Worse"
 
  # Per-step correctness
  - annotation_type: trajectory_eval
    name: step_quality
    description: "Rate this step"
    steps_key: agentic_steps
    correctness_options:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Code quality rating
  - annotation_type: likert
    name: code_quality
    size: 5
    min_label: "Poor"
    max_label: "Excellent"
    description: "Rate the quality of the code changes"
    labels:
      1: "Very Poor"
      2: "Poor"
      3: "Acceptable"
      4: "Good"
      5: "Excellent"
 
  # Free-text notes
  - annotation_type: text
    name: notes
    description: "Any additional observations about the coding trace"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
export_annotation_format: "jsonl"

उदाहरण प्रोजेक्ट चलाना

Potato में कोडिंग एजेंट एनोटेशन के लिए उदाहरण प्रोजेक्ट शामिल हैं:

bash

# Clone the repository
git clone https://github.com/davidjurgens/potato.git
cd potato
 
# Run the Claude Code trace evaluation example
potato start example/coding_agent_eval/config.yaml -p 8000
 
# Run the SWE-bench evaluation example
potato start example/swe_bench_eval/config.yaml -p 8000
 
# Run the multi-agent comparison example
potato start example/coding_agent_comparison/config.yaml -p 8000

हर उदाहरण में नमूना ट्रेस, एक पूरी कॉन्फ़िगरेशन फ़ाइल, और एनोटेशन काम बताने वाला README शामिल है।

यह भी देखें

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

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