ai-dbug

🐛 AI-DBUG

An AI-powered Python debugger that explains errors in plain English with suggested fixes.

Stop wasting time deciphering cryptic error messages! AI-DBUG translates Python errors into clear, understandable explanations with practical solutions.

✨ Features

• 🎯 Automatic Error Capture - Hooks into Python's exception system
• 💡 Plain English Explanations - No more cryptic error messages
• 🔧 Practical Fix Suggestions - Step-by-step solutions for 70+ error types
• 🎨 Beautiful Output - Colored, formatted error messages
• 🌍 Cross-Platform - Works on Windows, macOS, and Linux
• 🖥️ IDE Compatible - VS Code, PyCharm, Jupyter, and all terminals
• 📚 Extensive Knowledge Base - Covers almost all Python error types
• 🔌 One-Line Setup - Get started in seconds

🌐 Platform Support

📦 Installation

pip install ai-dbug

For colored output (recommended):

pip install ai-dbug[color]

For all features:

pip install ai-dbug[full]

🚀 Quick Start

Basic Usage

import ai_dbug

# Enable AI debugging - that's it!
ai_dbug.enable_ai_debugging()

# Your code here
result = 5 + "10"  # TypeError with helpful explanation!

Output Example

======================================================================
                          🐛 AI-DBUG: Error Analysis
======================================================================

❌ Error
TypeError: can only concatenate str (not "int") to str

📍 Location
File: example.py, Line: 7, Function: <module>
Code: result = 5 + "10"

💡 What Happened?
You're trying to perform an operation between incompatible types
(e.g., adding a number and a string).

🔧 How to Fix
Convert one type to match the other. For example:
str(number) + string or int(string) + number.

📝 Example
age = 25
print('Age: ' + str(age))  # Convert int to str
# or
result = int('10') + 5     # Convert str to int

📖 Usage Examples

Method 1: Global Debugging

import ai_dbug

ai_dbug.enable_ai_debugging()

# All errors in your script will be explained
data = {'name': 'Alice'}
print(data['age'])  # KeyError with AI explanation

Method 2: Context Manager

from ai_dbug import debug_context

# Only debug specific code blocks
with debug_context():
    result = 10 / 0  # ZeroDivisionError with explanation

Method 3: Multiple Errors

from ai_dbug import debug_multiple

# Catch and explain multiple errors without stopping
with debug_multiple() as handler:
    with handler:
        x = 5 + "10"  # Error 1

    with handler:
        data['missing']  # Error 2

    with handler:
        10 / 0  # Error 3

# Output: "3 errors caught and explained"

Method 4: Manual Analysis

from ai_dbug import ErrorAnalyzer, ErrorFormatter
import sys

analyzer = ErrorAnalyzer()
formatter = ErrorFormatter()

try:
    problematic_code()
except Exception:
    exc_type, exc_value, exc_tb = sys.exc_info()
    analysis = analyzer.analyze_exception(exc_type, exc_value, exc_tb)
    formatter.format_error(analysis)

📚 Supported Error Types (70+)

Type Errors (10+ variations)

• Adding incompatible types
• NoneType errors
• Calling non-callable objects
• Type conversion issues
• Subscriptable type errors
• And more...

Value Errors (7+ variations)

• Invalid int/float conversions
• Unpacking errors
• Math domain errors
• Empty ranges
• Substring not found
• And more...

Key/Attribute Errors (5+ variations)

• Missing dictionary keys
• Undefined attributes
• Module attribute errors
• NoneType attribute access
• And more...

Index Errors

• List index out of range
• String index out of range
• Tuple index out of range

Import Errors (4+ variations)

• ModuleNotFoundError
• ImportError
• Cannot import name
• No module named

Name Errors

• Undefined variables
• Global name errors
• UnboundLocalError

Indentation Errors

• Inconsistent indentation
• Expected indented block
• Tab/space mixing

Syntax Errors (6+ variations)

• Invalid syntax
• EOF while parsing
• Invalid characters
• Keyword argument issues
• And more...

File Errors (5+ variations)

• FileNotFoundError
• PermissionError
• IsADirectoryError
• Unicode encoding errors
• And more...

Math Errors

• ZeroDivisionError
• OverflowError
• FloatingPointError

Async/Await Errors (4+ variations)

• Event loop issues
• Coroutine errors
• await outside async
• And more...

Other Common Errors

• RecursionError
• AssertionError
• MemoryError
• OSError
• ConnectionError
• TimeoutError
• KeyboardInterrupt
• JSON/Database errors
• Pandas errors
• Threading errors
• And many more...

⚙️ Configuration

Hide Original Traceback

import ai_dbug

# Show only AI-DBUG output (cleaner!)
ai_dbug.enable_ai_debugging(
    use_color=True,
    show_original_traceback=False  # Default
)

Disable Colors

# Maximum compatibility mode
ai_dbug.enable_ai_debugging(use_color=False)

Temporarily Disable

import ai_dbug

ai_dbug.enable_ai_debugging()
# ... your code ...
ai_dbug.disable_ai_debugging()

🎨 Output Formats

AI-DBUG automatically adapts to your environment:

Modern Terminals

• Windows Terminal, macOS, Linux
• Beautiful panels with emojis: 🐛 ❌ 💡 🔧 📝 📍
• Full color support

Legacy Consoles

• Windows CMD, PowerShell 5
• ASCII fallback: [!] [X] [@] [?] [+] [~]
• Color support maintained

Plain Text Mode

• No colors, pure ASCII
• Maximum compatibility

🧪 Running Tests

# Install with dev dependencies
pip install ai-dbug[dev]

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=ai_dbug --cov-report=html

# View coverage report
open htmlcov/index.html

🎯 Real-World Examples

Example 1: Beginner-Friendly TypeError

Before AI-DBUG:

TypeError: unsupported operand type(s) for +: 'int' and 'str'

😕 What does this mean?

With AI-DBUG:

💡 What Happened?
You're trying to add a number and text together. Python doesn't know
if you want math (5 + 10) or joining text ("5" + "10").

🔧 How to Fix
Convert both to the same type:
- For math: int("10") + 5 = 15
- For text: str(5) + "10" = "510"

😊 Clear and helpful!

Example 2: Dictionary KeyError

Before AI-DBUG:

KeyError: 'phone'

With AI-DBUG:

💡 What Happened?
You're trying to access a dictionary key 'phone' that doesn't exist.

🔧 How to Fix
1. Check if key exists first:
   if 'phone' in user_data:
       phone = user_data['phone']

2. Use .get() with a default:
   phone = user_data.get('phone', 'Not provided')

Example 3: File Operations

Before AI-DBUG:

FileNotFoundError: [Errno 2] No such file or directory: 'data.txt'

With AI-DBUG:

💡 What Happened?
Python can't find the file 'data.txt'. It's looking in:
/home/user/project/

🔧 How to Fix
1. Check the file exists:
   import os
   if os.path.exists('data.txt'):
       with open('data.txt') as f:
           content = f.read()

2. Use absolute path:
   filepath = '/full/path/to/data.txt'

3. Check current directory:
   print(os.getcwd())

🌍 Platform-Specific Notes

🪟 Windows

• Best Experience: Use Windows Terminal (free from Microsoft Store)
• VS Code: Works perfectly with both integrated terminal and Run button
• Legacy Console: Automatic ASCII fallback with colors

🍎 macOS

• Works perfectly out of the box
• Full emoji and color support
• All terminals supported

🐧 Linux

• Works on all distributions
• Full emoji and color support
• Install emoji fonts if needed: sudo apt install fonts-noto-color-emoji

🏗️ Project Structure

ai-dbug/
├── ai_dbug/
│   ├── __init__.py          # Package exports
│   ├── core.py              # Main debugger
│   ├── knowledge_base.py    # 70+ error explanations
│   ├── formatter.py         # Cross-platform output
│   └── analyzer.py          # Error analysis
├── tests/
│   ├── __init__.py
│   └── test_ai_dbug.py      # Test suite
├── README.md                # This file
├── LICENSE                  # MIT License
├── pyproject.toml           # Package config
├── setup.py                 # Setup script
└── .gitignore               # Git ignore rules

🤝 Contributing

We love contributions! Here's how you can help:

Add New Error Explanations

1. Fork the repository
2. Edit ai_dbug/knowledge_base.py
3. Add your error with explanation, fix, and example
4. Add tests in tests/test_ai_dbug.py
5. Submit a pull request

Example:

ERROR_KNOWLEDGE_BASE = {
    "YourError: pattern here": {
        "explanation": "Clear explanation in plain English",
        "fix": "Step-by-step solution",
        "example": "# Working code example\ncode_here()"
    }
}

Report Issues

Found a bug or have a suggestion? Open an issue

Improve Documentation

Documentation improvements are always welcome!

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by the need for beginner-friendly error messages
• Built with love for the Python community
• Uses rich for beautiful output
• Uses colorama for Windows colors

📞 Support & Community

• 🐛 Bug Reports: GitHub Issues
• 📧 Email: ithubaiju124@gmail.com
• 🌟 Star us: If AI-DBUG helped you, give us a star!

🗺️ Roadmap

• Cross-platform compatibility (Windows, macOS, Linux)
• 70+ error types with explanations
• IDE compatibility (VS Code, PyCharm, Jupyter)
• Multiple error catching
• VS Code extension
• PyCharm plugin
• Web dashboard for error analytics
• AI-powered custom error suggestions
• Community solution database
• Multi-language support (Spanish, French, German, etc.)
• Integration with CI/CD pipelines

🎓 Educational Use

Perfect for:

• 👨‍🎓 Teaching Python to beginners
• 📚 Coding bootcamps and courses
• 🏫 Computer science classes
• 📖 Self-learners and tutorials

📈 Statistics

• 70+ Error Types covered
• 4 Usage Modes (global, context, multiple, manual)
• 7+ Platforms supported
• 0 Configuration required
• 100% Python - no external services

💡 Why AI-DBUG?

Before AI-DBUG 😞

Traceback (most recent call last):
  File "script.py", line 42, in <module>
    process_data(items)
  File "script.py", line 15, in process_data
    return [item.upper() for item in items]
  File "script.py", line 15, in <listcomp>
    return [item.upper() for item in items]
AttributeError: 'int' object has no attribute 'upper'

Spends 30 minutes debugging...

After AI-DBUG 😊

💡 What Happened?
You're trying to use .upper() on a number (int), but .upper()
only works on text (strings).

🔧 How to Fix
Convert to string first: str(item).upper()

Or check the type:
if isinstance(item, str):
    item.upper()

📝 Example
items = [1, 2, "hello", 3]
result = [str(item).upper() for item in items]
# Output: ['1', '2', 'HELLO', '3']

Fixed in 30 seconds!

🌟 Show Your Support

If AI-DBUG made debugging easier for you:

• ⭐ Star this repository
• 🐦 Tweet about it
• 📝 Write a blog post
• 💬 Tell your friends
• 🤝 Contribute code or docs

📜 Citation

If you use AI-DBUG in research or education, please cite:

@software{ai_dbug,
  title = {AI-DBUG: AI-Powered Python Debugger},
  author = {AI-DBUG Contributors},
  year = {2024},
  url = {https://github.com/jithubaiju55/ai-dbug}
}

---