🐛 Code Debugger Assistant

A terminal-based AI debugging assistant built with LangChain 1.0 (LCEL), OpenAI / any LLM provider, and a Textual TUI.

It reads a source code file, detects the language, analyzes errors with an AI model, proposes fixes with full reasoning and a diff preview, and only applies changes after you explicitly approve them.

---

✨ Features

• 🔍 Auto-detects programming language from file extension (+ Pygments fallback)
• 🤖 AI analysis via a pure LCEL chain: PromptTemplate | model.with_structured_output()
• 📋 Structured output: issues list, severity badges, root-cause reasoning, confidence score
• 🔀 Diff preview before any file is touched
• ✅ Human-in-the-loop: Approve & Overwrite / Save Corrected Copy / Reject
• 💾 Automatic backup (.bak) created before overwriting
• 🔌 Multi-provider: works with LM Studio, OpenAI, Anthropic, Gemini, Groq

---

🗂 Project Structure

code-debugger-assistant/
├── app/
│   ├── main.py              # Entry point
│   ├── config.py            # Env config + extension map
│   ├── agent/
│   │   ├── schemas.py       # Pydantic v2 response models
│   │   ├── prompts.py       # ChatPromptTemplate
│   │   └── debugger_chain.py # LCEL chain wiring
│   ├── core/
│   │   ├── file_loader.py   # File validation + reading
│   │   ├── language_detector.py
│   │   ├── diff_builder.py  # difflib wrapper
│   │   └── patch_writer.py  # File overwrite / corrected copy
│   └── ui/
│       ├── debugger_app.py  # Root Textual App
│       ├── screens.py       # 5 screens
│       └── widgets.py       # IssueCard, DiffViewer, CodeViewer
├── tests/
│   ├── test_language_detector.py
│   ├── test_diff_builder.py
│   └── test_patch_writer.py
├── examples/
│   ├── buggy_python.py
│   ├── buggy_js.js
│   └── buggy_java.java
├── .env.example
└── pyproject.toml

---

🚀 Setup

1. Prerequisites

• Python 3.10+
• LM Studio for local inference (or any provider below)

2. Install

cd code-debugger-assistant
pip install -e ".[dev]"

3. Configure

Copy the example env file and edit it:

cp .env.example .env

Local (LM Studio) — default

MODEL_PROVIDER=openai
MODEL_NAME=local-model        # match the model loaded in LM Studio
BASE_URL=http://localhost:1234/v1
OPENAI_API_KEY=lm-studio      # required by langchain-openai, value ignored by LM Studio

Start LM Studio → Local Server → Load a model → Start server.

Real OpenAI

MODEL_PROVIDER=openai
MODEL_NAME=gpt-4.1
OPENAI_API_KEY=sk-...
# BASE_URL=                   # leave blank

Anthropic

MODEL_PROVIDER=anthropic
MODEL_NAME=claude-sonnet-4-5
ANTHROPIC_API_KEY=sk-ant-...

Groq

MODEL_PROVIDER=groq
MODEL_NAME=llama-3.3-70b-versatile
GROQ_API_KEY=gsk_...

---

▶️ Run

python -m app.main

Or if installed via pip:

debug-assistant

---

🎬 Demo Workflow

1. Launch the app.
2. Enter examples/buggy_python.py in the file input.
3. The app detects Python and shows the source code.
4. Click Analyze with AI — the AI finds:
   • Missing : in function definition
   • Missing second argument in function call
5. Review the diff and issue cards with severity badges.
6. Click Save Corrected Copy → buggy_python_corrected.py is created.
7. Original file is untouched.

Try the same with examples/buggy_js.js and examples/buggy_java.java.

---

🧪 Tests

pytest tests/ -v

Tests cover:

• Language detection (all extensions + Pygments fallback + unknown)
• Diff generation (additions, removals, identical code)
• Patch writing (overwrite, backup, corrected copy, error handling)

---

⌨️ Keyboard Shortcuts

Key	Action
ESC	Go back one screen
q	Quit
Enter	Submit file path input

---

🔮 Future Enhancements

• Multi-file project analysis
• Git diff integration
• Unit test generation after fix
• LangSmith tracing
• Linter integration (ruff, eslint)
• VS Code extension