Code evolution is inevitable in modern software development. Changes to third-party APIs frequently break existing code and complicate maintenance, posing practical challenges for developers. While large language models (LLMs) have shown promise in code generation, they struggle to reason without a structured representation of these evolving relationships, often leading them to produce outdated APIs or invalid outputs. In this work, we propose a knowledge graph-augmented framework that decomposes the migration task into two synergistic stages: evolution path retrieval and path-informed code generation. Our approach constructs static and dynamic API graphs to model intra-version structures and cross-version transitions, enabling structured reasoning over API evolution. Both modules are trained with synthetic supervision automatically derived from real-world API diffs, ensuring scalability and minimal human effort. Extensive experiments across single-package and multi-package benchmarks demonstrate that our framework significantly improves migration accuracy, controllability, and execution success over standard LLM baselines. The source code and datasets are available at: https://github.com/kangjz1203/KCoEvo.
Figures & tables
Figure 1: Illustration of API evolution in PyTorch across three update stages. The figure depicts the progressive modernization of PyTorch’s inference pipeline from v0.3.x (2017) to v2.0.x (2023), covering the transition from Deprecated APIs to Minor and Major Updates .The lower section highlights major industry adopters (e.g., Amazon, Microsoft, Baidu, TikTok, Google, and VSCode), with data samples partially collected from their open-source GitHub repositories, emphasizing the practical relevance of version-aware code migration in large-scale production ecosystems.
Figure 2: Overview of the proposed framework for evolutionary code generation.
Figure 3: Lightweight schema of the version-aware knowledge graph. Blue edges represent intra-version relations constructed offline; red edges indicate cross-version transitions established dynamically at runtime. Dashed lines, associated with ’ Renaming ’ or ’ Relocation ’, indicate more complex transformations where an entity evolves through significant modifications to its core attributes or contract.
Category
Type
Condition
Function
Add
f∈/F∧f∈F′
Retain (Ret)
f∈F∧f∈F′
Remove (Rem)
f∈F∧f∈/F′
Rename (Ren)
f∈F,f′∈F′∧name(f)=name(f′)
Relocate (Reloc)
f∈F∩F′∧module(f)=module(f′)
Table 1: Formal definition of function-level evolution relations across versions. F and F′ denote the sets of functions in the old and new versions, respectively.
Model
Row
Major → Major
Major → Minor
Minor → Major
Minor → Minor
CDC@1
EM@1
CDC@1
EM@1
CDC@1
EM@1
CDC@1
EM@1
DeepSeek-V3
Base
59.52
59.52
32.83
33.84
9.26
15.74
16.67
17.74
+KG
96.83
100.00
79.29
94.44
75.00
95.37
53.76
93.01
Δ
+37.31
+40.48
+46.46
+60.60
+65.74
+79.63
+37.09
+75.27
Qwen2.5-7B-Instruct-Turbo
Base
34.13
38.89
15.15
15.66
0.93
7.41
7.53
8.60
+KG
61.90
83.33
40.91
68.18
29.63
41.67
17.74
39.25
Table 2: Performance across migration types with separate CDC@1 and EM@1 columns. “Base” denotes the original setting; “+KG” denotes the improved setting under our framework; Δ is the per–metric improvement (+KG − Base). The arrow “ → ” indicates the direction of migration, where “Major” corresponds to major version changes (e.g., Torch 2.0.0) and “Minor” corresponds to minor version changes (e.g., Torch 2.1.3).
Model
Major → Major
Major → Minor
Minor → Major
Minor → Minor
Qwen2.5-7B-Instruct
38.89
15.66
7.41
8.60
+ Downstream Code
38.10
14.65
15.74
7.53
+ Library Source
38.10
17.17
11.11
16.67
+ StackOverflow
32.30
13.03
11.11
6.99
Mistral-24B-Instruct
38.10
16.16
6.48
6.45
+ Downstream Code
35.24
16.16
7.41
8.06
Table 3: Performance (EM@1) of Code Block RAG with Multiple Code Sources. Code sources include downstream application code, library source code, and StackOverflow snippets.
Model & Configuration
Maj → Maj
Maj → Min
Min → Maj
Min → Min
Qwen2.5-Coder-7B-Instruct
23.81
8.08
5.56
4.30
+ Planning Paths
66.67
46.46
38.89
37.10
+ LoRA
27.08
7.78
8.97
4.49
+ LoRA + Planning Paths
55.56
48.48
57.41
43.01
Meta-Llama-3-8B-Instruct
25.40
10.10
6.48
4.84
+ Planning Paths
89.68
85.35
86.11
88.17
Table 4: Performance (EM@1) of LoRA fine-tuning across version transition types. Planning Paths provide graph-guided supervision based on API evolution knowledge. Their combination significantly improves cross-version code generation performance.
Figure 4: Representative error types observed in version-aware code migration. The examples illustrate typical reasoning failures encountered by LLMs, including (1) Token Presence Error , (2) Code Validity Error , (3) Parameter Count Error and (4) Parameter Value Error . These cases highlight the limitations of surface-level pattern learning and motivate the need for structured, knowledge-driven reasoning in API evolution tasks.