RPG: A Repository Planning Graph for Unified and Scalable Codebase Generation
The paper introduces RPG, a structured Repository Planning Graph that replaces ambiguous natural language planning with explicit blueprints, enabling the ZeroRepo framework to generate significantly larger, more coherent, and higher-quality software repositories with improved test accuracy compared to existing baselines.
Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer
Imagine you ask a brilliant but slightly chaotic architect to build a massive, bustling city from scratch based on a single sentence: "Build a city for machine learning."
If you just give that instruction to a standard AI (like the ones we use today), it might start building a house, then realize it needs a road, then build a bridge, then forget where the water pipes go. It's like trying to build a skyscraper by stacking bricks one by one without a blueprint. The result is often a messy pile of code that doesn't quite work together.
This paper introduces RPG (Repository Planning Graph) and ZeroRepo, a new way to help AI build entire software "cities" (repositories) that are huge, organized, and actually work.
Here is the breakdown using simple analogies:
1. The Problem: The "Word Salad" Approach
Current AI coding tools are great at writing a single paragraph (a function) or a single page (a file). But when asked to write a whole book (a software repository), they tend to get lost.
- The Issue: They rely on "natural language" (words) to plan. Words are fuzzy. If you say "build a library," the AI might forget that books need shelves, shelves need floors, and floors need foundations.
- The Result: The AI builds a few rooms, gets confused about how they connect, and stops. It creates small, fragmented projects that are often broken.
2. The Solution: The "Blueprint" (RPG)
The authors created something called the Repository Planning Graph (RPG). Think of this not as a list of words, but as a living, interactive blueprint.
- Nodes are Rooms: Instead of just writing "we need a kitchen," the RPG creates a specific node for the kitchen, another for the bedroom, and another for the plumbing.
- Edges are Pipes and Wires: The RPG draws lines between these nodes. It knows that the Water Pump (Node A) must connect to the Kitchen Sink (Node B) before the Faucet (Node C) can work.
- Why it matters: This removes the guesswork. The AI doesn't have to "remember" how things connect; the graph tells it exactly what to build and in what order.
3. The Builder: ZeroRepo
ZeroRepo is the construction crew that uses this blueprint. It works in three distinct phases:
- Phase 1: The Proposal (The "What"):
Imagine a master planner looking at a giant catalog of every possible feature in the world (like "data loading," "clustering," "visualization"). The planner picks the ones needed for this specific city and arranges them into a rough map. - Phase 2: The Implementation (The "How"):
Now, the planner zooms in. They turn the "Kitchen" node into a specific list of files:sink.py,stove.py,fridge.py. They draw the pipes (data flows) showing how water moves from the main line to the sink. This creates the full RPG. - Phase 3: The Construction (The "Build"):
The AI starts building. But it doesn't just write code; it follows the blueprint's order.- It builds the foundation first.
- It builds the walls.
- Crucially: After building every room, it immediately runs a "safety inspection" (tests). If the sink leaks, it fixes it before moving to the next room. This ensures the whole city doesn't collapse later.
4. The Results: A City vs. A Shack
The researchers tested this against other top AI coders (like Claude Code) using a benchmark called RepoCraft (a test with 6 real-world projects like data tools and web frameworks).
- Size: The AI using RPG built code 3.9 times larger than the best competitor. It didn't just build a shack; it built a skyscraper.
- Quality: It passed 81.5% of the functional tests, compared to the competitor's 54%.
- Scalability: As the project got bigger, the RPG method kept getting better (linear growth), while the others got confused and stopped adding features.
5. The "GPS" Analogy for Finding Bugs
One of the hardest parts of coding is finding a bug in a massive codebase.
- Without RPG: It's like looking for a specific lost sock in a giant, messy laundry pile. You have to dig through everything.
- With RPG: It's like having a GPS. The AI knows exactly which "room" (file) and which "shelf" (function) the sock is in because the map told it where everything belongs. This made the AI 30–50% faster at fixing errors.
Summary
This paper is about teaching AI to stop "winging it" with words and start "planning" with structure. By giving the AI a structured map (RPG) instead of a vague list of instructions, they enabled it to build massive, complex software systems that are coherent, tested, and ready for the real world.
It's the difference between asking a child to "draw a city" (which results in scribbles) and giving an architect a CAD drawing with every pipe and wire mapped out (which results in a functional metropolis).
Drowning in papers in your field?
Get daily digests of the most novel papers matching your research keywords — with technical summaries, in your language.