ai-dbug 0.1.0
AI-powered Python debugger that explains errors in plain English with practical fixes
License: MIT
Requires Python: >=3.7
Keywords: debugging, errors, ai, developer-tools, traceback, error-handling, python-debugger, error-explanation, beginner-friendly

# 🐛 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

| Platform                  | Emojis | Colors | Status     |
| ------------------------- | ------ | ------ | ---------- |
| 🪟 Windows Terminal       | ✅     | ✅     | ✅ Perfect |
| 🪟 Windows CMD/PowerShell | ASCII  | ✅     | ✅ Good    |
| 🖥️ VS Code                | ✅     | ✅     | ✅ Perfect |
| 🍎 macOS Terminal         | ✅     | ✅     | ✅ Perfect |
| 🐧 Linux Terminal         | ✅     | ✅     | ✅ Perfect |
| 💻 PyCharm                | ✅     | ✅     | ✅ Perfect |
| 📓 Jupyter                | ✅     | ✅     | ✅ Perfect |

## 📦 Installation

```bash
pip install ai-dbug
```

For colored output (recommended):

```bash
pip install ai-dbug[color]
```

For all features:

```bash
pip install ai-dbug[full]
```

## 🚀 Quick Start

### Basic Usage

```python
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

```python
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

```python
from ai_dbug import debug_context

# Only debug specific code blocks
with debug_context():
    result = 10 / 0  # ZeroDivisionError with explanation
```

### Method 3: Multiple Errors

```python
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

```python
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+)

<details>
<summary><b>Type Errors</b> (10+ variations)</summary>

- Adding incompatible types
- NoneType errors
- Calling non-callable objects
- Type conversion issues
- Subscriptable type errors
- And more...

</details>

<details>
<summary><b>Value Errors</b> (7+ variations)</summary>

- Invalid int/float conversions
- Unpacking errors
- Math domain errors
- Empty ranges
- Substring not found
- And more...

</details>

<details>
<summary><b>Key/Attribute Errors</b> (5+ variations)</summary>

- Missing dictionary keys
- Undefined attributes
- Module attribute errors
- NoneType attribute access
- And more...

</details>

<details>
<summary><b>Index Errors</b></summary>

- List index out of range
- String index out of range
- Tuple index out of range

</details>

<details>
<summary><b>Import Errors</b> (4+ variations)</summary>

- ModuleNotFoundError
- ImportError
- Cannot import name
- No module named

</details>

<details>
<summary><b>Name Errors</b></summary>

- Undefined variables
- Global name errors
- UnboundLocalError

</details>

<details>
<summary><b>Indentation Errors</b></summary>

- Inconsistent indentation
- Expected indented block
- Tab/space mixing

</details>

<details>
<summary><b>Syntax Errors</b> (6+ variations)</summary>

- Invalid syntax
- EOF while parsing
- Invalid characters
- Keyword argument issues
- And more...

</details>

<details>
<summary><b>File Errors</b> (5+ variations)</summary>

- FileNotFoundError
- PermissionError
- IsADirectoryError
- Unicode encoding errors
- And more...

</details>

<details>
<summary><b>Math Errors</b></summary>

- ZeroDivisionError
- OverflowError
- FloatingPointError

</details>

<details>
<summary><b>Async/Await Errors</b> (4+ variations)</summary>

- Event loop issues
- Coroutine errors
- await outside async
- And more...

</details>

<details>
<summary><b>Other Common Errors</b></summary>

- RecursionError
- AssertionError
- MemoryError
- OSError
- ConnectionError
- TimeoutError
- KeyboardInterrupt
- JSON/Database errors
- Pandas errors
- Threading errors
- And many more...

</details>

## ⚙️ Configuration

### Hide Original Traceback

```python
import ai_dbug

# Show only AI-DBUG output (cleaner!)
ai_dbug.enable_ai_debugging(
    use_color=True,
    show_original_traceback=False  # Default
)
```

### Disable Colors

```python
# Maximum compatibility mode
ai_dbug.enable_ai_debugging(use_color=False)
```

### Temporarily Disable

```python
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

```bash
# 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:**

```python
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](https://github.com/jithubaiju55/ai-dbug/issues)

### Improve Documentation

Documentation improvements are always welcome!

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by the need for beginner-friendly error messages
- Built with love for the Python community
- Uses [rich](https://github.com/Textualize/rich) for beautiful output
- Uses [colorama](https://github.com/tartley/colorama) for Windows colors

## 📞 Support & Community

- 🐛 **Bug Reports:** [GitHub Issues](https://github.com/jithubaiju55/ai-dbug/issues)
- 📧 **Email:** ithubaiju124@gmail.com
- 🌟 **Star us:** If AI-DBUG helped you, give us a star!

## 🗺️ Roadmap

- [x] Cross-platform compatibility (Windows, macOS, Linux)
- [x] 70+ error types with explanations
- [x] IDE compatibility (VS Code, PyCharm, Jupyter)
- [x] 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:

```bibtex
@software{ai_dbug,
  title = {AI-DBUG: AI-Powered Python Debugger},
  author = {AI-DBUG Contributors},
  year = {2024},
  url = {https://github.com/jithubaiju55/ai-dbug}
}
```

---

<div align="center">

[GitHub](https://github.com/jithubaiju55/ai-dbug)

⭐ Star us on GitHub — it motivates us a lot!

</div>