AI Debugging Assistant

Automatically detects, explains, and fixes bugs in source code using a LangGraph pipeline powered by Groq LLMs. Supports a Streamlit web UI and a command-line interface.

Group Members

Hnin Ei San 65011303, Thet Htet San 66011271

---

Architecture

The system is built as a directed LangGraph state machine. Each node is a discrete step in the debugging pipeline. The graph routes between nodes based on runtime outcomes.

read_source
    └── static_analysis
            └── check_cache
                    └── run_program
                            ├── (error)   ──► analyze_bug ──► generate_fix ──► apply_fix ──► run_program
                            ├── (fixed)   ──► gen_run_tests
                            │                     ├── (pass) ──► finalize ──► END
                            │                     └── (fail) ──► analyze_bug
                            └── (max iter) ──► mark_failed ──► END

Nodes

Node	File	Description
read_source	debugger_agent.py	Reads the source file and detects language from extension
static_analysis	debugger_agent.py	Runs language-appropriate linters (ruff, mypy, eslint, go vet, etc.)
check_cache	debugger_agent.py	Looks up the error fingerprint in the SQLite fix cache
run_program	debugger_agent.py	Executes the file and captures stderr
analyze_bug	debugger_agent.py	Sends error + code to Groq LLM for root-cause explanation
generate_fix	debugger_agent.py	Generates 3 candidate fixes, scores each, picks the best
apply_fix	debugger_agent.py	Writes the fix to disk; backs up original on first iteration
gen_run_tests	debugger_agent.py	Generates and runs a test file; re-routes to analyze if tests fail
finalize	debugger_agent.py	Ends the graph
mark_failed	debugger_agent.py	Records failure when max iterations are reached

Module Overview

Code Debug Buddy/
├── app.py                  # Streamlit web UI
├── main.py                 # CLI entry point
├── src/
│   ├── debugger_agent.py   # LangGraph pipeline and state definition
│   ├── language_support.py # Runner, linter, and test command dispatch
│   ├── confidence_scoring.py # Candidate fix generation and scoring
│   ├── fix_cache.py        # SQLite-backed fix cache
│   └── explain_panel.py    # Streamlit Q&A chat panel logic
├── examples/
│   └── buggy_example.py    # Sample buggy file for testing
└── requirements.txt

State

The entire pipeline communicates through a single DebugState TypedDict defined in debugger_agent.py. Key fields:

Field	Type	Description
file_path	str	Path to the file being debugged
lang	str	File extension (.py, .js, etc.)
source_code	str	Current source content
error_output	str	Captured stderr from last run
explanation	str	LLM root-cause explanation
fixed_code	str	Best candidate fix
unified_diff	str	Diff between original and fix
status	str	running, fixed, test_failed, failed
iteration	int	Current loop count
cache_hit	bool	Whether fix came from cache
confidence_scores	list[int]	Scores for each generated candidate

Confidence Scoring

confidence_scoring.py generates 3 candidate fixes per iteration using varied prompt seeds, writes each to a temporary file, runs it, and scores it:

• +30 if the file runs without error
• +40 if generated tests pass
• +20 if the diff is small (fewer changed lines)
• +10 if Python syntax is valid

The highest-scoring candidate is selected as the fix.

src/fix_cache.py maintains a local SQLite database (~/.ai_debugger_cache.db). Each error is fingerprinted by MD5 hashing the first 300 characters of stderr. On a cache hit, the LLM call is skipped entirely.

---

Setup

1. Install dependencies

pip install -r requirements.txt

2. Create a .env file in the project root with your Groq API key:

GROQ_API_KEY=your_key_here

Get a free key at console.groq.com.

---

Usage

Streamlit UI

streamlit run app.py

Command line

python main.py examples/buggy_example.py
python main.py myfile.py --max-iter 3 --report report.json

Python API

from src.debugger_agent import debug_file

result = debug_file("myfile.py", max_iterations=5)
print(result["status"])      # "fixed" or "failed"
print(result["explanation"]) # LLM root-cause explanation
print(result["fixed_code"])  # Corrected source

---

Supported Languages

Extension	Runner	Linters
.py	python	ruff, mypy
.js	node	eslint
.ts	ts-node	eslint
.go	go run	go vet, staticcheck
.rs	rustc	rustfmt