Name: Potato
Author: Potato

Pourquoi annoter les agents de coding

Les agents de coding comme Claude Code, Aider et SWE-Agent sont devenus bons très vite, et il faut maintenant pouvoir noter leur travail. Une seule exécution donne une trajectoire brouillonne : modifications de code, commandes de terminal, lectures de fichiers et étapes de raisonnement enchaînées. Pour entraîner un meilleur agent, il faut du retour humain sur ces exécutions, or les outils d'annotation dont disposaient la plupart des équipes n'ont jamais été conçus pour ce type de données.

Une interface d'annotation en texte brut ne sait ni afficher un diff unifié, ni mettre en forme une sortie de terminal, ni gérer la structure imbriquée d'une trace d'agent. Les laboratoires finissent donc par écrire leurs propres interfaces d'évaluation, à refaire le même travail et à produire des jeux de données qui ne se parlent pas entre eux.

Potato gère maintenant l'annotation d'agents de coding directement, avec des composants de rendu faits pour les traces, des schémas d'annotation adaptés à ce type d'évaluation et des exportations qui alimentent l'entraînement sans détour. Pour la référence complète de la fonctionnalité, voir la documentation sur l'annotation d'agents de coding et le guide d'évaluation d'agents, plus général.

CodingTraceDisplay : une visionneuse de traces

L'essentiel de l'expérience d'annotation passe par le composant CodingTraceDisplay. Il rend chaque étape de la trajectoire d'un agent avec la visualisation qui convient au type de cette étape.

Voici à quoi ressemble l'interface d'annotation d'agents de coding dans Potato :

Affichage de trace d'agent de coding montrant le rendu des diffs et l'arborescence de fichiers Le CodingTraceDisplay rend les diffs de code, la sortie du terminal et les lectures de fichiers avec une mise en forme adaptée

Vue en diff unifié

Les modifications de code sont rendues en diffs unifiés, avec surlignage rouge/vert des lignes supprimées et ajoutées. La vue affiche les numéros de ligne, les en-têtes de chemin de fichier et les lignes de contexte autour des changements. On retrouve l'expérience familière des pull requests GitHub, que la plupart des développeurs connaissent déjà.

yaml

# 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

Blocs de terminal sombres

Les commandes bash et leurs sorties sont rendues dans des blocs de terminal sombres, en police à chasse fixe, avec prise en charge des couleurs ANSI et défilement pour les résultats longs. Ces blocs affichent la commande exécutée, le répertoire de travail et le code de retour.

yaml

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

Blocs de code numérotés

Les lectures de fichiers apparaissent en blocs de code colorés avec numéros de ligne. Quand l'agent lit une plage de lignes précise, seules ces lignes sont affichées, avec leurs numéros d'origine conservés, ce qui facilite le recoupement avec le fichier réel.

Arborescence de fichiers en barre latérale

Une barre latérale repliable montre tous les fichiers touchés pendant la trajectoire, rangés en arborescence. Chaque fichier porte une icône indiquant s'il a été créé, modifié, lu ou supprimé. Un clic sur un fichier fait défiler la trace jusqu'à sa première apparition.

yaml

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"

Sorties repliables

Les sorties longues, quel que soit le type d'étape, peuvent être repliées pour garder la trace lisible. Les annotateurs déplient les étapes une par une selon leurs besoins, ou se servent des commandes « Expand All » / « Collapse All ». Les blocs de réflexion des agents sont repliés par défaut, mais restent consultables.

yaml

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"

Schéma de modèle de récompense de processus (PRM)

Les modèles de récompense de processus attribuent le crédit au niveau des étapes, au lieu de n'évaluer que le résultat final. Potato propose deux modes d'annotation PRM, pensés pour des compromis vitesse/exactitude différents.

Mode première erreur

En mode première erreur, l'annotateur fait défiler la trajectoire et clique sur la première étape où l'agent se trompe. Toutes les étapes antérieures sont automatiquement marquées correctes, et toutes celles qui suivent (y compris l'étape cliquée) automatiquement marquées erronées. L'annotation va beaucoup plus vite, puisqu'il n'y a qu'un seul point à repérer.

yaml

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

Mode par étape

En mode par étape, chaque étape reçoit une note indépendante. Les données d'entraînement sont plus détaillées, mais chaque trace prend plus de temps. Les annotateurs notent chaque étape comme correcte, erronée ou partiellement correcte.

yaml

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

Schéma de revue de code

L'interface de revue de code offre des commandes d'annotation dans l'esprit des pull requests GitHub :

Annotation de revue de code avec commentaires en ligne sur le diff Les annotateurs peuvent cliquer sur les lignes du diff pour ajouter des commentaires en ligne, noter les fichiers et rendre un verdict d'approbation ou de rejet

Le schéma de revue de code apporte l'annotation façon pull request GitHub aux traces d'agents. Les annotateurs peuvent laisser des commentaires en ligne sur des lignes précises d'un diff, noter chaque fichier et rendre un verdict global.

yaml

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"

Convertisseurs de traces : importer depuis n'importe quel agent

Potato embarque des convertisseurs pour les trois formats d'agents de coding les plus répandus. Chacun normalise son format vers la représentation structurée interne de Potato.

Claude Code (API Messages d'Anthropic)

Les traces de Claude Code utilisent le format de l'API Messages d'Anthropic, avec des blocs de contenu tool_use et tool_result. Le convertisseur extrait des appels d'outils les modifications de fichiers, les commandes bash et les lectures de fichiers, et conserve le texte de raisonnement de l'assistant.

bash

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

Aider (chat en Markdown avec blocs d'édition)

Aider produit des journaux de conversation en Markdown, avec des blocs d'édition SEARCH/REPLACE. Le convertisseur analyse ces blocs pour reconstituer les modifications de fichiers et extrait les commandes shell des blocs de code délimités.

bash

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

SWE-Agent (pensée/action/observation)

SWE-Agent fonctionne selon une boucle pensée/action/observation. Le convertisseur associe chaque action au type d'étape qui convient (édition, bash, lecture) et conserve le raisonnement en chaîne de l'agent sous forme de blocs de réflexion repliables.

bash

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

Détection automatique

Si vos traces proviennent de plusieurs agents, Potato peut détecter le format tout seul à partir de la structure de chaque fichier :

bash

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

Exportations vers les pipelines d'entraînement

Les traces annotées s'exportent dans des formats directement exploitables pour l'entraînement de modèles.

Format PRM

Étiquettes de récompense au niveau des étapes, pour entraîner des modèles de récompense de processus :

python

# 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
}

Paires de préférence DPO/RLHF

Combinées à des annotations de comparaison par paires, elles permettent à Potato de produire des paires de préférence utilisables pour du Direct Preference Optimization ou du RLHF :

python

# 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
}

Résultats compatibles SWE-bench

Exportez les annotations dans un format compatible avec le harnais d'évaluation SWE-bench, pour comparer directement avec les résultats publiés :

bash

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

Démarrage rapide

Passer de rien à un serveur d'annotation qui tourne prend environ cinq minutes.

Installation

bash

pip install potato-annotation[coding-agents]

Convertir vos traces

bash

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

Créer votre configuration

Voici une configuration complète pour un projet d'évaluation d'agent de coding, qui utilise à la fois les schémas PRM et revue de code :

yaml

# 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"

Lancer le serveur

bash

potato start config.yaml -p 8000

Ouvrez http://localhost:8000 dans votre navigateur, connectez-vous et commencez à annoter. Vous disposez du rendu complet des diffs, de la sortie du terminal et de l'annotation de récompense de processus décrits plus haut.

La suite

C'est une première version, et il nous reste des choses à faire. Au programme : la prise en charge d'autres formats d'agents, une meilleure visualisation des refactorisations multi-fichiers et une intégration plus étroite avec des cadres d'entraînement comme OpenRLHF et TRL.

Si vous écrivez un nouveau convertisseur de traces, un schéma ou un format d'exportation, une contribution serait la bienvenue. Et si votre équipe évalue des agents de coding et tombe sur un cas que cette installation ne couvre pas, ouvrez une issue sur notre dépôt GitHub.