PaperlayerView exact revision on arXiv

Source-linked AI summary

Closing the Loop: Universal Repository Representation with RPG-Encoder

Jane Luo, Chengyu Yin, Xin Zhang, Qingtao Li, Steven Liu, Yiming Huang, Jie Wu, Hao Liu, Yangyu Huang, Yu Kang, Fangkai Yang, Ying Xin, Scarlett Li

arXiv:2602.02084v2cs.CLcs.SE

TL;DR

Repository agents struggle because API documentation and dependency graphs provide fragmented semantic or structural views, despite comprehension and generation forming inverse paths in one reasoning cycle. RPG-Encoder unifies these views by encoding code into an evolving RPG and exposing it for structure-aware reasoning. It achieves state-of-the-art localization and high-fidelity reconstruction, including 93.7% Acc@5 on SWE-bench Verified and 98.5% coverage on RepoCraft.

  • Problem

    Existing repository approaches use fragmented representations, while repository comprehension and generation require a unified connection between semantic intent and structural dependencies.

  • Method

    RPG-Encoder generalizes RPG into a bidirectional representation that encodes code with semantic features and dependencies, evolves incrementally, and supports structure-aware reasoning.

  • Results

    93.7% Acc@5 on SWE-bench Verified and 98.5% reconstruction coverage on RepoCraft are reported alongside state-of-the-art repository understanding and high-fidelity reconstruction.

  • Takeaways & Limitations

    RPG-Encoder establishes RPG as a unified representation that bidirectionally links architectural intent with structural implementation.

Abstract

from arXiv · show

Current repository agents encounter a reasoning disconnect due to fragmented representations, as existing methods rely on isolated API documentation or dependency graphs that lack semantic depth. We consider repository comprehension and generation to be inverse processes within a unified cycle: generation expands intent into implementation, while comprehension compresses implementation back into intent. To address this, we propose RPG-Encoder, a framework that generalizes the Repository Planning Graph (RPG) from a static generative blueprint into a unified, high-fidelity representation. RPG-Encoder closes the reasoning loop through three mechanisms: (1) Encoding raw code into the RPG that combines lifted semantic features with code dependencies; (2) Evolving the topology incrementally to decouple maintenance costs from repository scale, reducing overhead by 95.7%; and (3) Operating as a unified interface for structure-aware navigation. In evaluations, RPG-Encoder establishes state-of-the-art localization performance on SWE-bench Verified with 93.7% Acc@5 and exceeds the best baseline by over 10% in localization accuracy on SWE-bench Live Lite. These results highlight our superior fine-grained precision in complex codebases. Furthermore, it achieves 98.5% reconstruction coverage on RepoCraft, confirming RPG's high-fidelity capacity to mirror the original codebase and closing the loop between intent and implementation.

1. Introduction

RPG-Encoder addresses fragmented repository representations by unifying semantic intent and structural dependencies within a bidirectional reasoning cycle. It encodes, incrementally evolves, and operates on RPG while achieving strong localization and reconstruction results.

  • Existing API documentation captures semantic intent but lacks global navigability, whereas dependency graphs expose structure with limited semantic information.
  • RPG unifies documentation-like semantic density with dependency-graph topological rigor to support both generation and comprehension.
  • RPG-Encoder converts code into an interpretable RPG whose nodes combine functional descriptions with metadata and whose edges encode hierarchy and dependencies.
  • Incremental evolution updates RPG from commit diffs, while Operation provides structure-aware traversal between high-level intent and low-level execution logic.
  • 93.7% Acc@5 on SWE-bench Verified and 98.5% reconstruction coverage on RepoCraft demonstrate RPG-Encoder’s navigational utility and representational fidelity.
  • RPG generalizes the Repository Planning Graph into a unified representation that closes the loop between repository comprehension and generation.

2. Related Work

Related work advances repository generation toward architectural coherence and repository understanding toward active, structure-aware exploration. These directions include multi-agent workflows, reconstruction systems, dependency-guided navigation, and long-context semantic methods.

  • Repository generation has progressed from localized file completion toward systemic workflows emphasizing architectural coherence.
  • Multi-agent frameworks and paper-to-code systems use role-based abstraction to manage repository complexity.
  • Commit0 introduces library-level reconstruction from near-zero implementations, while terminal-based agents support iterative repository construction.
  • Repository understanding has shifted from passive retrieval toward active, structure-aware exploration.
  • Graph-guided navigation, explicit dependency schemas, knowledge graphs, and long-context summarization target search-space reduction and global semantic grasp.

3. Method

RPG-Encoder extracts a hierarchical dual-view graph from code, maintains it incrementally, and exposes it as a unified substrate for semantic and dependency-aware agent reasoning. The design links functional intent to executable structure while limiting routine update costs.

  • Overview: RPG-Encoder comprises Encoding for RPG extraction, Evolution for incremental maintenance, and Operation as a unified reasoning substrate.
  • RPG Encoding: RPG models repositories as a hierarchical dual-view graph with high-level architectural nodes and low-level implementation nodes.
  • RPG Encoding: Each node pairs a semantic feature with structural metadata, while functional and dependency edges encode hierarchy and logical interactions.
  • RPG Encoding: Semantic lifting extracts behavioral signatures from functions and classes, summarizes file functionality, and establishes functional edges between levels.
  • RPG Encoding: Hierarchical aggregation recovers latent functional topology from implementation units and organizes nodes around abstract functional centroids.
  • RPG Encoding: Artifact grounding propagates metadata and maps abstract functional features to concrete directory and code artifacts.
  • RPG Evolution: Routine updates parse commit diffs and edit only affected graph regions, reserving global reconstruction for major refactoring.
  • RPG Operation: The unified representation supports SearchNode, FetchNode, and ExploreRPG for retrieval, source inspection, and cross-view traversal.

4. Experiments Setup

The experiments evaluate RPG as both a navigational substrate for repository localization and a structurally complete representation for reconstruction. They use SWE-bench benchmarks, RepoCraft, established baselines, standard metrics, and controlled model configurations.

  • Evaluation Tasks: The evaluation measures repository understanding through navigation and localization, and repository reconstruction through fidelity and losslessness.
  • Repository Understanding: SWE-bench Verified provides 500 human-validated examples from 12 repositories, while SWE-bench-Live Lite provides 300 recent issues across 70 repositories.
  • Repository Understanding: Localization baselines include hierarchical text narrowing, explicit dependency graphs, static-code search, and dynamic execution signals with agentic planning.
  • Metrics: Acc@k tests whether the ground-truth target appears among the top-k predictions, while Precision and Recall quantify set overlap.
  • Repository Reconstruction: RepoCraft reconstruction compares Official API Documentation with RPG as representation sources for rebuilding target repositories with ground-truth functionality.
  • Repository Reconstruction: ZeroRepo-RPG uses the extracted RPG as its exclusive knowledge source and scheduler, processing nodes in topological order.
  • Metrics: Reconstruction reports Coverage, Accuracy, and code statistics measuring functional categories, test outcomes, structural similarity, and recovered code volume.
  • Implementation: RPG extraction uses GPT-4o, reconstruction uses GPT-5-mini and GPT-4.1, and evaluation follows bounded or completion-based stopping conditions.

5. Main Result

RPG-Encoder improves fine-grained repository understanding and reconstructs repository structure with high fidelity. Its gains span localization accuracy, coverage, pass rate, and reconstructed code scale.

  • 87.8% Acc@5 on SWE-bench Live function-level localization exceeds CoSIL by 11.6 points.On SWE-bench Verified, RPG-Encoder with Claude-4.5 achieves 93.7% Acc@5 at function level, surpassing OrcaLoca by 14.4 points.
  • 98.5% Coverage and an 86.0% Pass Rate on RepoCraft exceed the documentation-based baseline by over 33 points.The evaluation uses GPT-5-mini for repository reconstruction.
  • 550k reconstructed tokens approach the scale of the human-written gold project, whereas the baseline captures only 17% of the original volume.The comparison concerns repository reconstruction in RepoCraft.

6. Ablation Study

Ablations show that semantic features, dependencies, and hierarchical metadata each contribute to RPG-Encoder’s localization and reconstruction performance. Removing these components reduces semantic alignment, structural retrieval, repository granularity, or code correctness.

  • Experimental Setup: Progressive node-metadata removal in RepoCraft and structural-metadata removal in SWE-bench Live isolate representational fidelity and navigational efficacy.These are the two ablation settings used to separate semantic and topological contributions.
  • Semantics and Topology are Mutually Reinforcing: 50.5% to 43.1% Function-level Acc@1 on GPT-4o follows removal of semantic features.The ablation identifies semantic features as essential for aligning natural-language intent with concrete implementations.
  • Semantics and Topology are Mutually Reinforcing: Removing dependency edges significantly degrades File-level retrieval by disrupting execution tracing.Dependencies establish structural connectivity, while the Full RPG outperforms all ablated variants.
  • Hierarchical Constraints Ensure Structural Fidelity: 157 files instead of 256 and approximately 200,000 fewer tokens result when file and function metadata are removed.Without explicit topological boundaries, distinct modules tend to merge and repository granularity is lost.
  • Hierarchical Constraints Ensure Structural Fidelity: 74.1% Pass Rate instead of 82.8% follows removal of function metadata.The result shows that detailed structural signals are important for code correctness.

7. Analysis

RPG-Encoder improves repository-navigation efficiency and maintains representation fidelity through incremental evolution. Its interface also structures agent exploration from global topology to localized implementation.

  • Reasoning Efficiency: 4.63 efficiency is achieved by RPG-Encoder on GPT-4.1, with fewer steps and lower expenditure across tested backbones.On GPT-5, it reaches 4.15 efficiency at a cost of $0.22.
  • Structural Evolvability: 95.7% reduction in maintenance tokens is achieved by incremental updates, using 633K tokens instead of more than 14.7M for full reconstruction.The strategy isolates semantic deltas and confines heavy computation to one-time initialization.
  • Fidelity Under Evolution: 81.9% Acc@5 is achieved by incremental RPG maintenance on SWE-bench Live for GPT-4.1, compared with 80.3% for full reconstruction.Full reconstruction retains an approximately 2% advantage in Precision and Recall, while the two strategies maintain statistical parity overall.
  • Structured Exploration: Agents exhibit a universal “Search-then-Zoom” pattern, traversing topology broadly before narrowing to fine-grained source retrieval.The pattern is more pronounced for stronger reasoners, including Claude-4.5.
  • Failure Analysis: RPG-Encoder reduces Search & Exploration failures through dual-path access that combines broad semantic retrieval with hierarchy-guided dependency traversal.The same navigation design also reduces redundant search and keeps reasoning grounded in the correct implementation units.

8. Conclusion

RPG-Encoder transforms RPG into a unified repository representation that links semantic intent with implementation structure. Its construction pipeline extracts normalized semantic features from code and supports machine-consumable outputs.

  • Conclusion: RPG-Encoder transforms the Repository Planning Graph into a unified representation linking architectural intent and structural implementation.The framework is presented as both a navigational map for localization and a blueprint for reconstruction.
  • Construction: The construction stage converts raw repositories into a hierarchically organized feature space with mappings from abstract functional nodes to directory scopes.It includes semantic lifting, latent architecture recovery, and grounded artifact mapping.
  • Semantic Lifting: Semantic lifting analyzes code entities as repository-wide semantic units rather than isolated files, preserving consistent granularity across file boundaries.Batched processing analyzes every semantic unit exactly once under controlled token budgets.
  • Semantic Feature Representation: Each entity receives concise, lowercase, implementation-agnostic verb–object features that describe purpose through atomic single-responsibility phrases.Normalization supplies stable semantic anchors for later grouping and hierarchical encoding.
  • Output Validation: The semantic-parsing prompt requires complete function coverage and returns a JSON mapping from each function name to its semantic features.Post-processing validates schema compliance, normalizes feature lists, and retries malformed outputs with minimal format correction.

A.1.2. Latent Architecture Recovery for Hierarchical Encoding

Latent architecture recovery organizes semantic features into a three-level hierarchy and grounds abstract nodes in compact directory scopes. The resulting tree supports high-signal routing, traversal, and scalable synchronization.

  • Domain Discovery: The recovery process reorganizes flat semantic features into an interpretable hierarchy because ungrouped features are difficult to navigate and directory grouping can miss logical roles.It begins by discovering high-level functional areas as architectural centroids.
  • Hierarchical Construction: Each feature group is assigned to a three-level path consisting of functional area, category, and subcategory labels focused on intent.The first level must use a provided functional area, while later levels express broader purpose and precise specialization.
  • Tree Usage: The resulting feature tree provides high-signal search scopes and semantically coherent routing and traversal boundaries.It balances top-level abstraction with fine-grained specialization to keep tool-based navigation tractable.
  • Artifact Grounding: File Coverage C(v) collects parent directories of all leaf files beneath node v, while π̂(v) seeks a compact representation preserving module boundaries.Trie-based branching analysis retains branching or terminating path nodes to avoid collapsing unrelated modules into overly general roots.
  • Operation and Scalability: Incremental evolution scales with the magnitude of repository changes rather than repository size because each atomic operation affects only a bounded hierarchy region.The RPG also exposes SearchNode, FetchNode, and ExploreRPG for intent discovery, precise context retrieval, and structural traversal.

B.1.1. Experiment Setup

The experiment evaluates repository localization under a shared protocol using multiple language-model backbones and representative baselines. Predictions are assessed at file and function granularity with canonicalized ranking metrics.

  • Evaluation Protocol: All methods use identical datasets, metrics, termination criteria, preprocessing, canonicalization, and ranking-based evaluation procedures.
  • Backbones: The study evaluates o3-mini, GPT-4o, GPT-4.1, GPT-5, DeepSeek-V3.1, and Claude-Sonnet-4.5 as language-model backbones.
  • Baselines: Comparisons include Agentless, LocAgent, CoSIL, and OrcaLoca, retaining their original algorithmic structures with minimal benchmark adaptations.
  • Granularities: Localization is evaluated at file and function levels using granularity-specific canonical strings for consistent comparison.File locations use relative paths, while function locations use fully qualified file:entity identifiers with constructor normalization.
  • Granularities: Function-level evaluation measures precise localization beyond the file boundary, while instances without function annotations are evaluated only at file level.
  • Metrics: Accuracy@k, precision, and recall are computed per instance and averaged across evaluation instances after duplicate predictions are removed.Reported Accuracy@k values use k ∈ {1, 3, 5}.

B.2.1. RepoCraft Benchmark Construction

The RepoCraft reconstruction evaluation uses structurally complex real-world Python repositories and compares unstructured official documentation with an extracted RPG prior. ZeroRepo is adapted to test whether structured traversal improves recovery, fidelity, and efficiency.

  • Benchmark: RepoCraft contains real-world Python repositories selected for popularity and structural complexity.
  • Documentation Baseline: Official API documentation is compiled from each repository’s docs/ files with Sphinx into a unified textual representation.The documentation captures official class, function, and module-hierarchy definitions.
  • Documentation Baseline: 7,320 files and over 2.5 million tokens comprise the compiled documentation across six subject repositories.
  • Reconstruction Workflows: ZeroRepo-Doc reconstructs repositories from raw documentation through agent self-planning, manual state tracking, and standard test-driven development.
  • Reconstruction Workflows: ZeroRepo-RPG injects the pre-extracted RPG as a ground-truth topological prior, shifting planning from the agent to the substrate.The workflow uses dependency-based ordering, semantically coherent batching, and context-aware execution.
  • Metrics: Reconstruction is assessed through functionality coverage, novelty, executable fidelity, and structural scale.Coverage measures recovered ground-truth functionality, novelty measures extraneous capabilities, and fidelity measures semantic correctness.
  • Results: RPG-Encoder maintains architectural integrity across repositories, achieving 100% coverage and over 96% pass rate on Django while documentation-based reconstruction can recover less than 20% of file structure in large libraries.
  • Behavioral Analysis: ExploreRPG is frequently used by high-performing models alongside keyword-based retrieval, indicating substantial use of structural navigation.

C.4. Cost Analysis

The cost analysis measures agent interaction rounds, token consumption, and monetary cost while examining tool-use failures and the efficiency trade-offs of structured exploration.

  • Cost Measurement: Average agent interaction rounds and per-instance cost are compared across models and evaluation episodes.
  • Failure Analysis: Figure 13 attributes one execution failure to COSIL selecting unrelated tools instead of investigating the core world_to_pixel issue.
  • Failure Analysis: Figure 14 attributes a SymPy lambdify search failure to insufficient coverage and overly broad query formulation.
  • Cost–Performance Trade-off: RPG-enhanced agents incur moderately higher costs than lightweight baselines because they perform more structured exploration and reasoning steps.
  • Cost–Performance Trade-off: The increased cost scales sublinearly with performance gains, and high-performing models allocate additional budget primarily to informative exploration rather than repeated failed actions.
  • Caveat: LocAgent with o3-mini can report unusually low cost after terminating in 1–2 rounds or producing an answer without tool invocation.The passage characterizes this as early termination specific to that pairing rather than efficient full-loop reasoning.

D.1. Repository Reconstruction

The reconstruction ablations remove function-level, file-level, dependency, or semantic information to isolate how hierarchical topology and graph components shape generated repository structure and efficiency.

  • Ablation Setup: The controlled ablation study uses scikit-learn from RepoCraft and GPT-5-mini to isolate hierarchical topological signals.
  • Ablation Setup: The function-level ablation removes leaf-node metadata and function-to-function edges, leaving file boundaries while requiring autonomous signature and ordering inference.
  • Structural Effects: Removing function-level guidance increases class count from 524 to 815 as the model atomizes logic into smaller class-based units.
  • Structural Effects: Removing file-level constraints reduces physical files from 250 to 154 and increases feature density from 19.77 to 33.60.The model shifts toward coarse-grained feature aggregation without directory boundaries.
  • Component Ablations: Dependency ablation removes static edges and prevents call-graph traversal, forcing navigation through physical file hierarchy alone.
  • Component Ablations: Semantic-feature ablation removes feature descriptions and functional-subordination edges, reducing intent-based search to rigid keyword matching.
  • Efficiency Effects: The full RPG-Encoder model achieves the minimum trajectory length and cost across both evaluated language models.Removing feature metadata raises GPT-4o exploration steps from 8.22 to 9.23.
Loading 2602.02084v2…