AI Code Debugger Agent

An intelligent Python-based code debugging agent that analyzes, debugs, and fixes code issues with a Senior Developer persona. Supports multiple free AI providers including Ollama (local) and Hugging Face (free tier).

🆓 FREE TO USE! No API Keys Required!

This project now supports multiple free AI providers:

• Ollama (Recommended) - 100% free, runs locally, no limits, no API keys needed!
• Hugging Face - Free tier available
• OpenAI - Optional paid option

👉 See docs/FREE_SETUP_GUIDE.md for complete free setup instructions!

📚 All documentation is in the docs/ folder!

Features

• 🔍 Intelligent Code Analysis: Identifies bugs, errors, and potential issues
• 🛠️ Automatic Fixes: Provides corrected code with explanations
• 👨‍💻 Senior Developer Persona: Expert-level debugging with mentoring approach
• 📊 Code Quality Analysis: Comprehensive code review capabilities
• 🎯 Root Cause Analysis: Explains why issues occur and how to fix them
• 🆓 Multiple Free Providers: Works with Ollama, Hugging Face, or OpenAI

Project Structure

.
├── agent.py              # Main agent logic
├── prompts.py            # AI instructions and persona definitions
├── test_code.py          # Broken code examples for testing
├── quick_debug.py        # Quick debugging tool
├── debug_my_file.py      # Example: Debug your own files
├── example_usage.py       # Usage examples
├── test_setup.py         # Setup verification tool
├── requirements.txt       # Python dependencies
├── docs/                  # 📚 All documentation and guides
│   ├── README.md         # Documentation index
│   ├── BEGINNER_GUIDE.md  # Complete beginner's guide
│   ├── FREE_SETUP_GUIDE.md # Free setup instructions
│   ├── NEXT_STEPS.md      # What to do after setup
│   └── TEST_WITH_YOUR_CODE.md # How to debug your code
└── README.md             # This file

Quick Start (FREE with Ollama)

1. Install dependencies:

   pip install -r requirements.txt

2. Install Ollama (completely free, no API key needed):

   • Download from: https://ollama.com
   • Install it
   • Run: ollama pull llama3.2
   • That's it! No API keys needed!

3. Run the debugger:

   python agent.py

👉 For detailed free setup instructions, see docs/FREE_SETUP_GUIDE.md

📚 All guides: See docs/README.md for complete documentation index

Alternative: Hugging Face (Free Tier)

If you prefer Hugging Face:

1. Get free API key at: https://huggingface.co/settings/tokens
2. Create .env file with: HUGGINGFACE_API_KEY=your_key
3. Change provider="huggingface" in agent.py main() function

Usage

Basic Usage

Run the agent to debug the test code:

python agent.py

Programmatic Usage

from agent import CodeDebuggerAgent

# Initialize with Ollama (free, local)
agent = CodeDebuggerAgent(provider="ollama", model="llama3.2")

# Or use Hugging Face (free tier)
# agent = CodeDebuggerAgent(provider="huggingface")

# Or use OpenAI (paid)
# agent = CodeDebuggerAgent(provider="openai", model="gpt-4")

# Debug code
result = agent.debug_code(code_string, error_message="Optional error message")

# Analyze code quality
quality_analysis = agent.analyze_code_quality(code_string)

Configuration

• Provider: Choose "ollama" (free), "huggingface" (free tier), or "openai" (paid)
• Model:
  • Ollama: "llama3.2", "codellama", "mistral" (all free)
  • Hugging Face: Various free models
  • OpenAI: "gpt-4", "gpt-3.5-turbo" (paid)
• Temperature: Set to 0.3 for consistent debugging results

Example Output

The agent provides:

• Analysis: Comprehensive analysis of code issues
• Issues Found: Numbered list of bugs and problems
• Fixed Code: Corrected code with improvements
• Explanation: Detailed explanations of fixes and best practices

Requirements

• Python 3.8+
• Free Option: Ollama (no API key needed!) - See docs/FREE_SETUP_GUIDE.md
• Alternative: Hugging Face free API key OR OpenAI paid API key
• See requirements.txt for dependencies

Documentation

📚 All guides and documentation are in the docs/ folder:

• Documentation Index - Start here to find what you need
• Beginner's Guide - Complete guide for beginners
• Free Setup Guide - Set up for free (no API keys!)
• Next Steps - Advanced usage and features
• Testing with Your Own Code - Practical examples

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

• 🐛 Report bugs
• 💡 Suggest new features
• 🔧 Submit pull requests
• 📚 Improve documentation

License

MIT License - see LICENSE file for details.

Author

Created as a portfolio project demonstrating:

• AI/LLM integration
• Python development
• Code analysis and debugging
• Multi-provider architecture
• Comprehensive documentation