DaLIC x LocAgent Experimental Suite

This repository is not a direct mirror of the original LocAgent project. Instead, it is an experimental suite built by extending LocAgent, designed to study and validate how the supplemental context provided by DaLIC affects code localization performance.

In short:

• LocAgent is the foundation, providing code indexing, graph traversal, retrieval tools, localization workflows, and evaluation utilities.
• DaLIC is the extension layer, injecting additional dynamic-analysis-based context into the LocAgent localization pipeline.
• This repository integrates both into a reproducible experimental environment for batch comparisons and result analysis.

Repository Positioning

If we view this repository as a system, the relationship can be summarized as:

LocAgent (base code localization framework)
    +
DaLIC (dynamic context enhancement)
    =
This repository (an extended suite for experiment reproduction and analysis)

This repository preserves the main LocAgent workflow while adding:

• unique artifacts generated by DaLIC
• an optional unique dependency tree
• batch scripts for multiple experimental configurations
• post-processing scripts for statistical analysis and result export
• organized experimental output directories

Relationship Between DaLIC and LocAgent

What LocAgent Does

LocAgent is the original code localization framework. It is responsible for:

• building or loading graph indexes and BM25 indexes
• providing search, entity localization, and graph traversal tools
• allowing an LLM agent to iteratively search for relevant candidate locations in a repository
• producing file-level, module-level, and function-level localization results

In this repository, these capabilities are mainly reflected in:

• auto_search_main.py
• dependency_graph/
• repo_index/
• plugins/location_tools/
• evaluation/

What DaLIC Does

In this repository, DaLIC does not replace LocAgent. Instead, it acts as an enhancement module. It obtains supplemental evidence related to the target functionality through dynamic tracing, then passes that evidence to LocAgent for use during localization.

At the moment, DaLIC mainly provides two kinds of context in this repository:

• unique_artifacts.txt Generated through a differential dynamic analysis process similar to Software Reconnaissance, keeping only the traces that appear when the target feature is enabled but not when it is disabled.
• unique_dep_tree_edgelist.txt Derived from the unique artifacts, capturing data dependency relationships to further connect the artifacts to one another.

How They Are Connected

The key integration pattern in this repository is: LocAgent remains responsible for search and localization, while DaLIC supplies supplemental context inside the prompt.

The main integration points are:

• auto_search_main.py In the main localization pipeline, this file decides whether to append DaLIC context to the user task description based on --use_dalic and --use_data_deps.
• DaLIC/prompt_generator.py Builds the supplemental prompt by reading unique_artifacts.txt and, optionally, unique_dep_tree_edgelist.txt from DaLIC/vt_results/<instance_id>/.
• DaLIC/run_dalic.py Runs batched experiments under multiple configurations to compare the baseline, DaLIC-enhanced variants, data dependency variants, and graph-enabled/graph-disabled settings.

So, more precisely, DaLIC in this repository should be understood as:

• an experimental enhancement built on top of LocAgent
• a context injection layer for code localization
• an extension used for ablation studies and experimental comparison

Experimental Configurations

DaLIC/run_dalic.py defines several core experiment settings:

• original The original LocAgent baseline, with graph tools enabled and no DaLIC context.
• original_without_graph The original LocAgent baseline, but without graph traversal.
• with_dalic LocAgent enhanced with DaLIC unique artifacts.
• with_dalic_without_graph DaLIC unique artifacts enabled, but graph tools disabled.
• with_dalic_data_deps DaLIC unique artifacts plus the unique dependency tree.
• with_dalic_data_deps_without_graph unique artifacts + data dependencies, with graph tools disabled.

These configurations reflect the main purpose of this repository: to systematically evaluate the gains brought by DaLIC-based context enhancement on top of the LocAgent baseline.

Directory Structure

.
├── auto_search_main.py          # Main LocAgent localization pipeline; DaLIC is integrated here
├── dependency_graph/            # Graph construction and traversal
├── repo_index/                  # Indexing and code structure parsing
├── plugins/location_tools/      # Tools callable by the agent
├── evaluation/                  # Localization result evaluation
├── DaLIC/
│   ├── prompt_generator.py      # Reads DaLIC context and builds prompts
│   ├── run_dalic.py             # Batch experiment entry point
│   ├── process_result.py        # Aggregates repeated experiment results
│   ├── diff_stats.py            # Statistics for differences between configurations
│   ├── result_to_excel.py       # Exports results to Excel
│   ├── vt_results/              # DaLIC dynamic context for each instance
│   └── outputs/                 # Saved experiment outputs and statistics
└── scripts/
    ├── gen_graph_index.sh
    ├── gen_bm25_index.sh
    └── run.sh

Quick Start

1. Set Up the Environment

git clone <your-fork-or-local-path>
cd LocAgent

conda create -n locagent python=3.12
conda activate locagent
pip install -r requirements.txt

2. Set Index Paths

export PYTHONPATH=$PYTHONPATH:$(pwd)
export GRAPH_INDEX_DIR=/path/to/graph_index
export BM25_INDEX_DIR=/path/to/BM25_index

If you also want a local repository cache, you can additionally set:

export LOCAL_REPO_CACHE=/path/to/repo_cache

3. Run the Original LocAgent Baseline

python auto_search_main.py \
  --dataset 'czlll/Loc-Bench_V1' \
  --split 'test' \
  --model 'azure/gpt-4o' \
  --localize \
  --merge \
  --output_folder outputs/original \
  --num_processes 10 \
  --use_function_calling \
  --simple_desc

4. Run the DaLIC-Enhanced Version

python auto_search_main.py \
  --dataset 'czlll/Loc-Bench_V1' \
  --split 'test' \
  --model 'azure/gpt-4o' \
  --localize \
  --merge \
  --output_folder outputs/with_dalic \
  --num_processes 10 \
  --use_function_calling \
  --simple_desc \
  --use_dalic

If you also want to inject data dependency information into the prompt, add:

--use_data_deps

Included Experimental Artifacts

This repository already contains a number of artifacts generated during experimentation, mainly under:

• DaLIC/vt_results/ Per-instance DaLIC intermediate results such as unique_artifacts.txt and unique_dep_tree_edgelist.txt.
• DaLIC/outputs/ Multi-run experiment outputs, aggregated JSON summaries, statistical outputs, and Excel exports.

Some especially important files include:

• DaLIC/outputs/results.xlsx
• DaLIC/outputs/diff_stats.json
• DaLIC/outputs/eval_results.txt

Result Post-Processing Scripts

Several scripts in this repository are dedicated to experiment analysis:

• DaLIC/process_result.py Aggregates repeated runs for each configuration and produces statistics by instance and localization level.
• DaLIC/diff_stats.py Computes statistical differences between experimental configurations.
• DaLIC/result_to_excel.py Exports experimental summaries to Excel for easier inspection.

Notes

• The primary purpose of this repository is to serve as an experimental suite, not as an untouched release of the original LocAgent project.
• Some experiment scripts still contain absolute paths or model endpoints from the original experiment environment, so they should be adjusted before rerunning, especially:
  • DaLIC/run_dalic.py
  • DaLIC/prebuild_bm25.py
  • evaluation/run_evaluation.ipynb
• The DaLIC functionality depends on instance-level context files under DaLIC/vt_results/; if they are missing, prompt_generator.py will raise an error directly.

Upstream References

If you want to learn more about the original LocAgent work itself, see:

• Paper: https://arxiv.org/abs/2503.09089
• Original repository: https://github.com/gersteinlab/LocAgent

If you only need the one-sentence positioning of this repository, it is:

This is a DaLIC experimental suite built by extending LocAgent, intended to evaluate the impact of dynamic context enhancement on code localization.