BRIDGE: Building Reliable Interfaces for Developer Guidance and Exploration

This repository contains the proof-of-concept implementation for the paper "BRIDGE: Building Reliable Interfaces for Developer Guidance and Exploration through Static Analysis and LLM Translation".

📖 About The Project

Traditional static analysis tools are powerful but often have a steep learning curve, requiring developers to learn a specialized query language. Conversely, while Large Language Models (LLMs) are easy to use for code-related questions, they are fundamentally unreliable for understanding the precise relationships that govern program behavior.

BRIDGE is a system designed to solve this problem by combining the strengths of both approaches. It uses an LLM's powerful natural language capabilities for one task only: translation. BRIDGE translates a developer's plain-English question into a formal query for a deterministic static analysis backend. The results are then tailored to the developer's detected expertise level.

The core insight is to leverage LLMs for what they do best (translation) while relying on symbolic tools for what they do best (analysis), resulting in a reliable and accessible code understanding tool.

---

🏗️ System Architecture

The system is built on a principle of separation of concerns and consists of five main components orchestrated by bridge_system.py:

• translator.py (Query Translation Layer): Converts a natural language query into a formal DSL command. It uses a "rules-first" approach for speed and reliability, with a fallback to a Hugging Face CodeT5 model for more complex queries.
• analyzer.py (Static Analysis Backend): Parses the source code into an Abstract Syntax Tree (AST) and builds a Data Flow Graph (DFG) using networkx. It executes the formal DSL queries to find code relationships deterministically.
• proficiency.py (Developer Proficiency Detector): Analyzes a developer's queries based on metrics like specificity and technical vocabulary to classify their expertise level as novice, intermediate, or expert.
• responder.py (Response Adaptation Layer): Takes the structured results from the analyzer and uses expertise-level templates to generate a clear, adaptive response for the user.
• demo.ipynb (Demonstration Notebook): An interactive Jupyter notebook that showcases the system's capabilities and allows for live querying.

---

🔑 Configuration

Before running the project, you need to set up your environment variables. This project uses a .env file to manage secrets like API keys.

1. Create a copy of the example environment file:

   # This file does not exist yet, you are creating it
   echo "HF_TOKEN=\"your_hugging_face_token_here\"" > .env.example
   cp .env.example .env

2. Open the newly created .env file and replace "your_hugging_face_token_here" with your actual Hugging Face access token. The .gitignore file is configured to ignore this file, so your secret will not be committed.

---

🚀 Getting Started

Follow these instructions to set up and run the project on your local machine.

1. Prerequisites

• Python 3.8+
• pip and venv

2. Installation

1. Clone the repository (if you haven't already):

   git clone [https://your-repository-url.com/BRIDGE.git](https://your-repository-url.com/BRIDGE.git)
   cd BRIDGE

2. Create a Python virtual environment:

   python -m venv .venv

3. Activate the virtual environment:

   • Windows (PowerShell):

     .\.venv\Scripts\Activate.ps1

     Note: If you get a script execution error, run this command first: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

   • macOS / Linux:

     source .venv/bin/activate

4. Install the required packages:

   pip install -r requirements.txt

3. Running the Demonstration

The primary way to interact with BRIDGE is through the demo.ipynb Jupyter Notebook.

1. Link the virtual environment to Jupyter:

   pip install ipykernel
   ipython kernel install --user --name="bridge-project"

2. Launch Jupyter Lab:

   jupyter lab

3. Open and run the notebook:

   • In Jupyter Lab, open the demo.ipynb file.
   • At the top right, ensure the kernel is set to "bridge-project".
   • Run the cells in order from top to bottom. The final cell will launch an interactive UI where you can ask your own questions or select from predefined samples.

---

💻 Usage

After running all the cells in demo.ipynb, you will see the interactive UI.

1. View the Code: The code being analyzed is shown on the left.
2. Select a Sample Query: Use the dropdown to choose from a list of examples. This will auto-populate the text box.
3. Write a Custom Query: Type your own question directly into the text area.
4. Analyze: Click the "Analyze Query" button to get a response. The output will show the translated formal query, the detected expertise level, and the final response.