🧪 Error Explainer

Author: Avishek Devnath
Email: avishekdevnath@gmail.com

AI-powered error analysis and explanation tool for multiple programming languages.

Explain error logs from Python, JavaScript, TypeScript, C++, and Java using Google's Gemini AI directly from your terminal. Get instant, intelligent explanations and fix suggestions for any programming error.

Built with ❤️ by Avishek Devnath

✨ Features

• 🤖 AI-Powered Explanations: Uses Google Gemini 1.5 Flash for intelligent error analysis
• 🔍 Offline Rule-Based Analysis: Works without AI - instant explanations for common errors
• 🌐 Multi-Language Support: Python, JavaScript, TypeScript, C++, Java
• 📁 Multiple Input Methods: Read from files, stdin, or paste interactively
• 💾 Save & Search: Store explanations and search through your error history
• 🎨 Rich Output: Beautiful terminal formatting with progress indicators
• 🔍 Smart Parsing: Intelligent traceback and error detection across languages
• 📊 Markdown Export: Export explanations in markdown format
• ⚡ Fast & Lightweight: Quick analysis with minimal dependencies
• 🌐 Works Offline: No internet connection required for rule-based mode
• 🔄 Real-time Monitoring: Watch running processes for live error detection
• 🐍 Python API: Programmatic access for integration with your tools
• 🔧 Multi-Model Support: Switch between different AI providers
• 🎯 Language Auto-Detection: Automatically identifies programming language from error logs

🚀 Quick Start

Installation

For Users:

pip install xerror

For Developers:

# Clone the repository
git clone https://github.com/xerror/xerror.git
cd xerror

# Install in development mode
pip install -e .

Setup API Key

1. Get your Google Gemini API key from Google AI Studio
2. Set the environment variable:

export GOOGLE_API_KEY=your-api-key-here

Or create a .env file in your project directory:

GOOGLE_API_KEY=your-api-key-here

Basic Usage

# Explain error from file (AI mode - requires API key)
xerror error.log

# Explain error offline (no API key required)
xerror error.log --offline

# Paste error interactively
xerror --paste

# Paste error offline
xerror --paste --offline

# Pipe error from stdin
xerror < error.log

# Save explanation to history
xerror error.log --save

# Output in markdown format
xerror error.log --markdown

🌐 Supported Languages

📖 Usage Examples

1. Multi-Language Error Analysis

# Python error
xerror python_error.log

# JavaScript error
xerror javascript_error.log

# TypeScript error
xerror typescript_error.log

# C++ error
xerror cpp_error.log

# Java error
xerror java_error.log

2. Language Detection

# Auto-detect language from error
xerror detect "NameError: name 'x' is not defined"
xerror detect "TypeError: Cannot read property 'length' of undefined"
xerror detect "TS2322: Type 'string' is not assignable to type 'number'"
xerror detect "error: 'cout' was not declared in this scope"
xerror detect "Exception in thread \"main\" java.lang.NullPointerException"

3. Real-time Process Monitoring

# Watch a running process for errors
xerror watch "python my_script.py"

# Watch with custom command
xerror watch "npm start"

# Watch in background mode
xerror watch "python long_running_script.py" --background

4. Python API Examples

import xerror

# Basic error explanation
result = xerror.explain_error("NameError: name 'x' is not defined")
print(result['explanation'])

# Language detection
language = xerror.detect_language("TypeError: Cannot read property 'length' of undefined")
print(f"Detected language: {language}")

# Parse error details
error_info = xerror.parse_error("TS2322: Type 'string' is not assignable to type 'number'")
print(f"Error type: {error_info.error_type}")
print(f"Language: {error_info.language}")

# Quick explanation (rule-based only)
explanation = xerror.quick_explain("TypeError: can only concatenate str (not 'int') to str")
print(explanation)

# Automatic error handling
with xerror.auto_explain_exceptions():
    undefined_variable  # This will be automatically explained

# Function decorator
@xerror.explain_function_errors()
def my_function():
    return undefined_variable

5. Error Examples by Language

Python Errors

# NameError
NameError: name 'x' is not defined

# TypeError
TypeError: can only concatenate str (not 'int') to str

# ImportError
ImportError: No module named 'requests'

# IndentationError
IndentationError: expected an indented block

# AttributeError
AttributeError: 'list' object has no attribute 'append'

# ValueError
ValueError: invalid literal for int() with base 10: 'abc'

JavaScript Errors

// TypeError
TypeError: Cannot read property 'length' of undefined

// ReferenceError
ReferenceError: x is not defined

// SyntaxError
SyntaxError: Unexpected token '{'

// RangeError
RangeError: Maximum call stack size exceeded

// URIError
URIError: URI malformed

TypeScript Errors

// TS2322: Type assignment error
TS2322: Type 'string' is not assignable to type 'number'

// TS2339: Property does not exist
TS2339: Property 'length' does not exist on type 'number'

// TS2307: Module not found
TS2307: Cannot find module './Component'

// TS2345: Argument type mismatch
TS2345: Argument of type 'string' is not assignable to parameter of type 'number'

// TS2531: Object is possibly null
TS2531: Object is possibly 'null'

C++ Errors

// Compilation error
error: 'cout' was not declared in this scope

// Syntax error
error: expected ';' before '}' token

// Missing include
error: 'vector' was not declared in this scope

// Linker error
undefined reference to 'main'

// Runtime error
Segmentation fault (core dumped)

Java Errors

// NullPointerException
Exception in thread "main" java.lang.NullPointerException

// Compilation error
error: cannot find symbol: variable x

// Class not found
java.lang.ClassNotFoundException: com.example.MyClass

// ArrayIndexOutOfBoundsException
java.lang.ArrayIndexOutOfBoundsException: Index 5 out of bounds for length 3

// NumberFormatException
java.lang.NumberFormatException: For input string: "abc"

🐍 Python API Reference

Core Functions

Context Managers

Decorators

See API Documentation for complete API reference.

🧪 Testing

Running Tests

# Run all tests
python -m pytest

# Run specific test categories
python -m pytest test_multi_language.py
python -m pytest test_api_proper.py
python -m pytest test_watcher.py
python -m pytest test_multi_model.py

# Run with coverage
python -m pytest --cov=xerror

# Run with verbose output
python -m pytest -v

# Run tests in parallel
python -m pytest -n auto

Test Coverage

Test Examples

# Test language detection
python test_multi_language.py

# Test API functionality
python test_api_proper.py

# Test watcher functionality
python test_watcher.py

# Test multi-model support
python test_multi_model.py

🔧 Advanced Usage

AI Mode vs Offline Mode

# AI mode (requires API key)
xerror error.log

# Offline mode (no API key needed)
xerror error.log --offline

Multi-Model Support

Custom Configuration

# Use custom API key for this session
xerror error.log --api-key your-custom-key

# Use different AI model
xerror error.log --model gemini-1.5-pro

# Set custom log directory
export ERROR_EXPLAINER_LOG_DIR=/custom/path
xerror error.log --save

# Set default model
export DEFAULT_MODEL=gemini-1.5-flash

Search with Filters

# Search by error type
xerror search "NameError"

# Search by language
xerror search "python"

# Search by keyword
xerror search "undefined"

# Search by filename
xerror search "views.py"

# Limit search results
xerror search "error" --limit 5

# Search with date range
xerror search "error" --since "2024-01-01" --until "2024-12-31"

🚨 Troubleshooting

Common Issues

Error Messages

# If you see: "No API key found"
export GOOGLE_API_KEY=your-api-key-here

# If you see: "Language not detected"
xerror error.log --offline

# If you see: "Import error"
pip install --upgrade xerror

# If you see: "Permission denied"
chmod +r error.log

Performance Tips

• Use --offline mode for faster responses
• Save explanations with --save to avoid re-analyzing
• Use specific error messages rather than full logs
• Set up your API key in .env file for convenience

📁 Supported File Formats

🏗️ Project Structure

xerror/
├── xerror/
│   ├── __init__.py              # Package initialization
│   ├── cli.py                   # Command line interface
│   ├── config.py                # Configuration management
│   ├── explainer.py             # AI explanation engine
│   ├── parser.py                # Error parsing logic
│   ├── rule_based_explainer.py  # Offline rule-based analysis
│   ├── api.py                   # Python API functions
│   ├── watcher.py               # Real-time process monitoring
│   ├── models.py                # Multi-model support
│   ├── language_parsers.py      # Multi-language parsing
│   └── utils.py                 # Utility functions
├── examples/
│   ├── error_sample.log         # Python error example
│   ├── javascript_error.log     # JavaScript error example
│   ├── typescript_error.log     # TypeScript error example
│   ├── cpp_error.log            # C++ error example
│   ├── java_error.log           # Java error example
│   └── api_usage_examples.py    # API usage examples
├── setup.py                     # Package setup
├── requirements.txt             # Dependencies
├── env.example                  # Environment template
├── README.md                    # This file
└── API_DOCUMENTATION.md         # API documentation

🔮 Roadmap

🛠️ Development

Local Development Setup

# Clone the repository
git clone https://github.com/xerror/xerror.git
cd xerror

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements.txt

# Set up environment
cp env.example .env
# Edit .env with your API keys

Development Commands

# Run tests
python -m pytest

# Run linting
flake8 xerror/

# Format code
black xerror/

# Type checking
mypy xerror/

# Build package
python setup.py sdist bdist_wheel

# Install from local build
pip install dist/xerror-0.1.0.tar.gz

# Run security checks
bandit -r xerror/

Contributing Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run tests: python -m pytest
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📋 Requirements

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Areas

How to Contribute

1. Report Bugs: Use GitHub Issues
2. Request Features: Use GitHub Discussions
3. Submit Code: Follow the contributing guidelines above
4. Improve Docs: Submit PRs for documentation improvements

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Google Gemini for providing the AI capabilities
• Click for the CLI framework
• Rich for beautiful terminal output
• Python Community for inspiration
• All contributors and users who provided feedback

👨‍💻 Author

Avishek Devnath

• 📧 Email: avishekdevnath@gmail.com
• 🌐 GitHub: @avishekdevnath
• 💼 LinkedIn: Avishek Devnath

📞 Support

Made with ❤️ by Avishek Devnath for developers everywhere