xerror

Name	xerror JSON
Version	1.0.0 JSON
	download
home_page	https://github.com/xerror/xerror
Summary	A smart CLI tool to analyze error logs from multiple languages and return AI-generated explanations and fix suggestions
upload_time	2025-07-26 08:13:13
maintainer	None
docs_url	None
author	Avishek Devnath
requires_python	>=3.10
license	None
keywords	error debugging ai cli python traceback exception
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 🧪 Error Explainer

**Author:** Avishek Devnath  
**Email:** avishekdevnath@gmail.com

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/badge/PyPI-xerror-blue.svg)](https://pypi.org/project/xerror/)
[![Downloads](https://img.shields.io/pypi/dm/xerror)](https://pypi.org/project/xerror/)
[![Version](https://img.shields.io/pypi/v/xerror)](https://pypi.org/project/xerror/)
[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/xerror/xerror)
[![Maintenance](https://img.shields.io/badge/maintained-yes-green.svg)](https://github.com/xerror/xerror/graphs/commit-activity)

**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](mailto:avishekdevnath@gmail.com)**

## ✨ 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:**
```bash
pip install xerror
```

**For Developers:**
```bash
# 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](https://makersuite.google.com/app/apikey)
2. Set the environment variable:

```bash
export GOOGLE_API_KEY=your-api-key-here
```

Or create a `.env` file in your project directory:

```env
GOOGLE_API_KEY=your-api-key-here
```

### Basic Usage

```bash
# 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

| Language | Error Detection | AI Explanation | Rule-Based | Examples | Status |
|----------|----------------|----------------|------------|----------|--------|
| Python | ✅ | ✅ | ✅ | NameError, TypeError, ImportError | 🟢 Production Ready |
| JavaScript | ✅ | ✅ | ✅ | TypeError, ReferenceError, SyntaxError | 🟢 Production Ready |
| TypeScript | ✅ | ✅ | ✅ | TS2322, TS2339, TS2307 | 🟢 Production Ready |
| C++ | ✅ | ✅ | ✅ | Compilation errors, runtime errors | 🟢 Production Ready |
| Java | ✅ | ✅ | ✅ | NullPointerException, ClassNotFoundException | 🟢 Production Ready |

## 📖 Usage Examples

### 1. Multi-Language Error Analysis

```bash
# 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

```bash
# 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

```bash
# 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

```python
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
```python
# 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
```javascript
// 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
```typescript
// 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
```cpp
// 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
```java
// 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

| Function | Description | Returns | Example |
|----------|-------------|---------|---------|
| `explain_error(error_text)` | Full AI-powered error explanation | Dict with explanation, confidence, method | `explain_error("NameError: name 'x' is not defined")` |
| `quick_explain(error_text)` | Fast rule-based explanation | String explanation | `quick_explain("TypeError: can only concatenate str (not 'int') to str")` |
| `detect_language(error_text)` | Detect programming language | Language enum | `detect_language("TypeError: Cannot read property 'length' of undefined")` |
| `parse_error(error_text)` | Parse error details | ErrorInfo object | `parse_error("TS2322: Type 'string' is not assignable to type 'number'")` |
| `get_supported_languages()` | Get list of supported languages | List of Language enums | `get_supported_languages()` |

### Context Managers

| Context Manager | Description | Example |
|----------------|-------------|---------|
| `auto_explain_exceptions()` | Automatically explain any exceptions | `with auto_explain_exceptions(): ...` |
| `watch_process(command)` | Monitor a running process for errors | `with watch_process("python script.py"): ...` |

### Decorators

| Decorator | Description | Example |
|-----------|-------------|---------|
| `explain_function_errors()` | Automatically explain errors in decorated function | `@explain_function_errors()` |

**See [API Documentation](API_DOCUMENTATION.md) for complete API reference.**

## 🧪 Testing

### Running Tests

```bash
# 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

| Component | Test Files | Coverage | Status |
|-----------|------------|----------|--------|
| Core Language Detection | `test_multi_language.py` | ✅ 100% | 🟢 Complete |
| Python API | `test_api_proper.py` | ✅ 100% | 🟢 Complete |
| Real-time Monitoring | `test_watcher.py` | ✅ 100% | 🟢 Complete |
| Multi-Model Support | `test_multi_model.py` | ✅ 100% | 🟢 Complete |
| Error Parsing | `test_parser.py` | ✅ 100% | 🟢 Complete |
| Rule-Based Explainer | `test_rule_based.py` | ✅ 100% | 🟢 Complete |

### Test Examples

```bash
# 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

| Feature | AI Mode | Offline Mode |
|---------|---------|--------------|
| API Key Required | ✅ Yes | ❌ No |
| Internet Connection | ✅ Yes | ❌ No |
| Response Time | 2-5 seconds | Instant |
| Explanation Quality | High (contextual) | Good (rule-based) |
| Coverage | All errors | Common errors |
| Cost | API usage | Free |
| Best For | Complex/unique errors | Common errors, offline use |

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

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

### Multi-Model Support

| Model | Provider | Status | Features | Cost |
|-------|----------|--------|----------|------|
| Gemini 1.5 Flash | Google | ✅ Active | Fast, cost-effective | Low |
| Gemini 1.5 Pro | Google | ⚠️ Limited | Higher quality, slower | Medium |
| OpenAI GPT-4 | OpenAI | 🔧 Optional | High quality, paid | High |
| Ollama Local | Local | 🔧 Optional | Offline, customizable | Free |

### Custom Configuration

```bash
# 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

```bash
# 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

| Issue | Solution | Status |
|-------|----------|--------|
| **API Key Error** | Set `GOOGLE_API_KEY` environment variable | ✅ Fixed |
| **Language Not Detected** | Use `--offline` mode or check error format | ✅ Fixed |
| **Slow Response** | Use offline mode or check internet connection | ✅ Fixed |
| **Import Error** | Install with `pip install xerror` | ✅ Fixed |
| **Permission Denied** | Check file permissions or use `--offline` | ✅ Fixed |

### Error Messages

```bash
# 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

| Format | Extension | Description | Example |
|--------|-----------|-------------|---------|
| Log files | `.log` | Standard log files | `error.log` |
| Text files | `.txt` | Plain text files | `error.txt` |
| Python files | `.py` | Python source files | `script.py` |
| Error files | `.error` | Dedicated error files | `error.error` |
| Any text | `*` | Any text-based file | `output` |

## 🏗️ 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

| Feature | Status | Priority | ETA | Description |
|---------|--------|----------|-----|-------------|
| VSCode Extension | 🔧 In Progress | High | Q4 2024 | IDE integration with real-time error detection |
| GitHub Actions CI | 🔧 In Progress | Medium | Q4 2024 | Automated testing and deployment |
| Desktop Notifications | 📋 Planned | Medium | Q1 2025 | Get notified of critical errors |
| More Languages (Go, Rust) | 📋 Planned | Low | Q2 2025 | Extended language support |
| Web Interface | 📋 Planned | Low | Q3 2025 | Browser-based error analysis |
| Mobile App | 📋 Planned | Low | Q4 2025 | iOS/Android error analysis |

## 🛠️ Development

### Local Development Setup

```bash
# 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

```bash
# 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

| Component | Version | Required | Notes |
|-----------|---------|----------|-------|
| Python | 3.10+ | ✅ Yes | Core requirement |
| Google Gemini API | Latest | ⚠️ For AI mode | Free tier available |
| Internet Connection | - | ⚠️ For AI mode | Not needed for offline mode |
| Click | 8.1.0+ | ✅ Yes | CLI framework |
| Rich | 13.0.0+ | ✅ Yes | Terminal formatting |

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Areas

| Area | Description | Priority | Status |
|------|-------------|----------|--------|
| Language Support | Add new programming languages | High | 🔧 In Progress |
| Error Patterns | Improve error detection patterns | High | 🔧 In Progress |
| AI Models | Add support for new AI providers | Medium | 📋 Planned |
| Performance | Optimize parsing and analysis speed | Medium | 📋 Planned |
| Documentation | Improve docs and examples | Low | ✅ Complete |

### How to Contribute

1. **Report Bugs**: Use [GitHub Issues](https://github.com/xerror/xerror/issues)
2. **Request Features**: Use [GitHub Discussions](https://github.com/xerror/xerror/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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Google Gemini](https://ai.google.dev/) for providing the AI capabilities
- [Click](https://click.palletsprojects.com/) for the CLI framework
- [Rich](https://rich.readthedocs.io/) for beautiful terminal output
- [Python Community](https://www.python.org/community/) for inspiration
- All contributors and users who provided feedback

## 👨‍💻 Author

**Avishek Devnath**
- 📧 Email: [avishekdevnath@gmail.com](mailto:avishekdevnath@gmail.com)
- 🌐 GitHub: [@avishekdevnath](https://github.com/avishekdevnath)
- 💼 LinkedIn: [Avishek Devnath](https://linkedin.com/in/avishekdevnath)

## 📞 Support

| Channel | Link | Response Time | Best For |
|---------|------|---------------|----------|
| 📧 Email | [avishekdevnath@gmail.com](mailto:avishekdevnath@gmail.com) | 24-48 hours | Personal support, feature requests |
| 🐛 Issues | [GitHub Issues](https://github.com/xerror/xerror/issues) | 1-3 days | Bug reports, technical issues |
| 📖 Documentation | [GitHub Wiki](https://github.com/xerror/xerror/wiki) | Instant | How-to guides, tutorials |
| 💬 Discussions | [GitHub Discussions](https://github.com/xerror/xerror/discussions) | 1-2 days | General questions, community help |

---

**Made with ❤️ by [Avishek Devnath](mailto:avishekdevnath@gmail.com) for developers everywhere** 

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/xerror/xerror",
    "name": "xerror",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "error, debugging, ai, cli, python, traceback, exception",
    "author": "Avishek Devnath",
    "author_email": "avishekdevnath@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/5a/31/afa046295aed1ef1555d804416b7d228ceef954018b98c841cbdd977cec9/xerror-1.0.0.tar.gz",
    "platform": null,
    "description": "# \ud83e\uddea Error Explainer\r\n\r\n**Author:** Avishek Devnath  \r\n**Email:** avishekdevnath@gmail.com\r\n\r\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![PyPI](https://img.shields.io/badge/PyPI-xerror-blue.svg)](https://pypi.org/project/xerror/)\r\n[![Downloads](https://img.shields.io/pypi/dm/xerror)](https://pypi.org/project/xerror/)\r\n[![Version](https://img.shields.io/pypi/v/xerror)](https://pypi.org/project/xerror/)\r\n[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/xerror/xerror)\r\n[![Maintenance](https://img.shields.io/badge/maintained-yes-green.svg)](https://github.com/xerror/xerror/graphs/commit-activity)\r\n\r\n**AI-powered error analysis and explanation tool for multiple programming languages.**\r\n\r\nExplain 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.\r\n\r\n> **Built with \u2764\ufe0f by [Avishek Devnath](mailto:avishekdevnath@gmail.com)**\r\n\r\n## \u2728 Features\r\n\r\n- \ud83e\udd16 **AI-Powered Explanations**: Uses Google Gemini 1.5 Flash for intelligent error analysis\r\n- \ud83d\udd0d **Offline Rule-Based Analysis**: Works without AI - instant explanations for common errors\r\n- \ud83c\udf10 **Multi-Language Support**: Python, JavaScript, TypeScript, C++, Java\r\n- \ud83d\udcc1 **Multiple Input Methods**: Read from files, stdin, or paste interactively\r\n- \ud83d\udcbe **Save & Search**: Store explanations and search through your error history\r\n- \ud83c\udfa8 **Rich Output**: Beautiful terminal formatting with progress indicators\r\n- \ud83d\udd0d **Smart Parsing**: Intelligent traceback and error detection across languages\r\n- \ud83d\udcca **Markdown Export**: Export explanations in markdown format\r\n- \u26a1 **Fast & Lightweight**: Quick analysis with minimal dependencies\r\n- \ud83c\udf10 **Works Offline**: No internet connection required for rule-based mode\r\n- \ud83d\udd04 **Real-time Monitoring**: Watch running processes for live error detection\r\n- \ud83d\udc0d **Python API**: Programmatic access for integration with your tools\r\n- \ud83d\udd27 **Multi-Model Support**: Switch between different AI providers\r\n- \ud83c\udfaf **Language Auto-Detection**: Automatically identifies programming language from error logs\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n**For Users:**\r\n```bash\r\npip install xerror\r\n```\r\n\r\n**For Developers:**\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/xerror/xerror.git\r\ncd xerror\r\n\r\n# Install in development mode\r\npip install -e .\r\n```\r\n\r\n### Setup API Key\r\n\r\n1. Get your Google Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey)\r\n2. Set the environment variable:\r\n\r\n```bash\r\nexport GOOGLE_API_KEY=your-api-key-here\r\n```\r\n\r\nOr create a `.env` file in your project directory:\r\n\r\n```env\r\nGOOGLE_API_KEY=your-api-key-here\r\n```\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n# Explain error from file (AI mode - requires API key)\r\nxerror error.log\r\n\r\n# Explain error offline (no API key required)\r\nxerror error.log --offline\r\n\r\n# Paste error interactively\r\nxerror --paste\r\n\r\n# Paste error offline\r\nxerror --paste --offline\r\n\r\n# Pipe error from stdin\r\nxerror < error.log\r\n\r\n# Save explanation to history\r\nxerror error.log --save\r\n\r\n# Output in markdown format\r\nxerror error.log --markdown\r\n```\r\n\r\n## \ud83c\udf10 Supported Languages\r\n\r\n| Language | Error Detection | AI Explanation | Rule-Based | Examples | Status |\r\n|----------|----------------|----------------|------------|----------|--------|\r\n| Python | \u2705 | \u2705 | \u2705 | NameError, TypeError, ImportError | \ud83d\udfe2 Production Ready |\r\n| JavaScript | \u2705 | \u2705 | \u2705 | TypeError, ReferenceError, SyntaxError | \ud83d\udfe2 Production Ready |\r\n| TypeScript | \u2705 | \u2705 | \u2705 | TS2322, TS2339, TS2307 | \ud83d\udfe2 Production Ready |\r\n| C++ | \u2705 | \u2705 | \u2705 | Compilation errors, runtime errors | \ud83d\udfe2 Production Ready |\r\n| Java | \u2705 | \u2705 | \u2705 | NullPointerException, ClassNotFoundException | \ud83d\udfe2 Production Ready |\r\n\r\n## \ud83d\udcd6 Usage Examples\r\n\r\n### 1. Multi-Language Error Analysis\r\n\r\n```bash\r\n# Python error\r\nxerror python_error.log\r\n\r\n# JavaScript error\r\nxerror javascript_error.log\r\n\r\n# TypeScript error\r\nxerror typescript_error.log\r\n\r\n# C++ error\r\nxerror cpp_error.log\r\n\r\n# Java error\r\nxerror java_error.log\r\n```\r\n\r\n### 2. Language Detection\r\n\r\n```bash\r\n# Auto-detect language from error\r\nxerror detect \"NameError: name 'x' is not defined\"\r\nxerror detect \"TypeError: Cannot read property 'length' of undefined\"\r\nxerror detect \"TS2322: Type 'string' is not assignable to type 'number'\"\r\nxerror detect \"error: 'cout' was not declared in this scope\"\r\nxerror detect \"Exception in thread \\\"main\\\" java.lang.NullPointerException\"\r\n```\r\n\r\n### 3. Real-time Process Monitoring\r\n\r\n```bash\r\n# Watch a running process for errors\r\nxerror watch \"python my_script.py\"\r\n\r\n# Watch with custom command\r\nxerror watch \"npm start\"\r\n\r\n# Watch in background mode\r\nxerror watch \"python long_running_script.py\" --background\r\n```\r\n\r\n### 4. Python API Examples\r\n\r\n```python\r\nimport xerror\r\n\r\n# Basic error explanation\r\nresult = xerror.explain_error(\"NameError: name 'x' is not defined\")\r\nprint(result['explanation'])\r\n\r\n# Language detection\r\nlanguage = xerror.detect_language(\"TypeError: Cannot read property 'length' of undefined\")\r\nprint(f\"Detected language: {language}\")\r\n\r\n# Parse error details\r\nerror_info = xerror.parse_error(\"TS2322: Type 'string' is not assignable to type 'number'\")\r\nprint(f\"Error type: {error_info.error_type}\")\r\nprint(f\"Language: {error_info.language}\")\r\n\r\n# Quick explanation (rule-based only)\r\nexplanation = xerror.quick_explain(\"TypeError: can only concatenate str (not 'int') to str\")\r\nprint(explanation)\r\n\r\n# Automatic error handling\r\nwith xerror.auto_explain_exceptions():\r\n    undefined_variable  # This will be automatically explained\r\n\r\n# Function decorator\r\n@xerror.explain_function_errors()\r\ndef my_function():\r\n    return undefined_variable\r\n```\r\n\r\n### 5. Error Examples by Language\r\n\r\n#### Python Errors\r\n```python\r\n# NameError\r\nNameError: name 'x' is not defined\r\n\r\n# TypeError\r\nTypeError: can only concatenate str (not 'int') to str\r\n\r\n# ImportError\r\nImportError: No module named 'requests'\r\n\r\n# IndentationError\r\nIndentationError: expected an indented block\r\n\r\n# AttributeError\r\nAttributeError: 'list' object has no attribute 'append'\r\n\r\n# ValueError\r\nValueError: invalid literal for int() with base 10: 'abc'\r\n```\r\n\r\n#### JavaScript Errors\r\n```javascript\r\n// TypeError\r\nTypeError: Cannot read property 'length' of undefined\r\n\r\n// ReferenceError\r\nReferenceError: x is not defined\r\n\r\n// SyntaxError\r\nSyntaxError: Unexpected token '{'\r\n\r\n// RangeError\r\nRangeError: Maximum call stack size exceeded\r\n\r\n// URIError\r\nURIError: URI malformed\r\n```\r\n\r\n#### TypeScript Errors\r\n```typescript\r\n// TS2322: Type assignment error\r\nTS2322: Type 'string' is not assignable to type 'number'\r\n\r\n// TS2339: Property does not exist\r\nTS2339: Property 'length' does not exist on type 'number'\r\n\r\n// TS2307: Module not found\r\nTS2307: Cannot find module './Component'\r\n\r\n// TS2345: Argument type mismatch\r\nTS2345: Argument of type 'string' is not assignable to parameter of type 'number'\r\n\r\n// TS2531: Object is possibly null\r\nTS2531: Object is possibly 'null'\r\n```\r\n\r\n#### C++ Errors\r\n```cpp\r\n// Compilation error\r\nerror: 'cout' was not declared in this scope\r\n\r\n// Syntax error\r\nerror: expected ';' before '}' token\r\n\r\n// Missing include\r\nerror: 'vector' was not declared in this scope\r\n\r\n// Linker error\r\nundefined reference to 'main'\r\n\r\n// Runtime error\r\nSegmentation fault (core dumped)\r\n```\r\n\r\n#### Java Errors\r\n```java\r\n// NullPointerException\r\nException in thread \"main\" java.lang.NullPointerException\r\n\r\n// Compilation error\r\nerror: cannot find symbol: variable x\r\n\r\n// Class not found\r\njava.lang.ClassNotFoundException: com.example.MyClass\r\n\r\n// ArrayIndexOutOfBoundsException\r\njava.lang.ArrayIndexOutOfBoundsException: Index 5 out of bounds for length 3\r\n\r\n// NumberFormatException\r\njava.lang.NumberFormatException: For input string: \"abc\"\r\n```\r\n\r\n## \ud83d\udc0d Python API Reference\r\n\r\n### Core Functions\r\n\r\n| Function | Description | Returns | Example |\r\n|----------|-------------|---------|---------|\r\n| `explain_error(error_text)` | Full AI-powered error explanation | Dict with explanation, confidence, method | `explain_error(\"NameError: name 'x' is not defined\")` |\r\n| `quick_explain(error_text)` | Fast rule-based explanation | String explanation | `quick_explain(\"TypeError: can only concatenate str (not 'int') to str\")` |\r\n| `detect_language(error_text)` | Detect programming language | Language enum | `detect_language(\"TypeError: Cannot read property 'length' of undefined\")` |\r\n| `parse_error(error_text)` | Parse error details | ErrorInfo object | `parse_error(\"TS2322: Type 'string' is not assignable to type 'number'\")` |\r\n| `get_supported_languages()` | Get list of supported languages | List of Language enums | `get_supported_languages()` |\r\n\r\n### Context Managers\r\n\r\n| Context Manager | Description | Example |\r\n|----------------|-------------|---------|\r\n| `auto_explain_exceptions()` | Automatically explain any exceptions | `with auto_explain_exceptions(): ...` |\r\n| `watch_process(command)` | Monitor a running process for errors | `with watch_process(\"python script.py\"): ...` |\r\n\r\n### Decorators\r\n\r\n| Decorator | Description | Example |\r\n|-----------|-------------|---------|\r\n| `explain_function_errors()` | Automatically explain errors in decorated function | `@explain_function_errors()` |\r\n\r\n**See [API Documentation](API_DOCUMENTATION.md) for complete API reference.**\r\n\r\n## \ud83e\uddea Testing\r\n\r\n### Running Tests\r\n\r\n```bash\r\n# Run all tests\r\npython -m pytest\r\n\r\n# Run specific test categories\r\npython -m pytest test_multi_language.py\r\npython -m pytest test_api_proper.py\r\npython -m pytest test_watcher.py\r\npython -m pytest test_multi_model.py\r\n\r\n# Run with coverage\r\npython -m pytest --cov=xerror\r\n\r\n# Run with verbose output\r\npython -m pytest -v\r\n\r\n# Run tests in parallel\r\npython -m pytest -n auto\r\n```\r\n\r\n### Test Coverage\r\n\r\n| Component | Test Files | Coverage | Status |\r\n|-----------|------------|----------|--------|\r\n| Core Language Detection | `test_multi_language.py` | \u2705 100% | \ud83d\udfe2 Complete |\r\n| Python API | `test_api_proper.py` | \u2705 100% | \ud83d\udfe2 Complete |\r\n| Real-time Monitoring | `test_watcher.py` | \u2705 100% | \ud83d\udfe2 Complete |\r\n| Multi-Model Support | `test_multi_model.py` | \u2705 100% | \ud83d\udfe2 Complete |\r\n| Error Parsing | `test_parser.py` | \u2705 100% | \ud83d\udfe2 Complete |\r\n| Rule-Based Explainer | `test_rule_based.py` | \u2705 100% | \ud83d\udfe2 Complete |\r\n\r\n### Test Examples\r\n\r\n```bash\r\n# Test language detection\r\npython test_multi_language.py\r\n\r\n# Test API functionality\r\npython test_api_proper.py\r\n\r\n# Test watcher functionality\r\npython test_watcher.py\r\n\r\n# Test multi-model support\r\npython test_multi_model.py\r\n```\r\n\r\n## \ud83d\udd27 Advanced Usage\r\n\r\n### AI Mode vs Offline Mode\r\n\r\n| Feature | AI Mode | Offline Mode |\r\n|---------|---------|--------------|\r\n| API Key Required | \u2705 Yes | \u274c No |\r\n| Internet Connection | \u2705 Yes | \u274c No |\r\n| Response Time | 2-5 seconds | Instant |\r\n| Explanation Quality | High (contextual) | Good (rule-based) |\r\n| Coverage | All errors | Common errors |\r\n| Cost | API usage | Free |\r\n| Best For | Complex/unique errors | Common errors, offline use |\r\n\r\n```bash\r\n# AI mode (requires API key)\r\nxerror error.log\r\n\r\n# Offline mode (no API key needed)\r\nxerror error.log --offline\r\n```\r\n\r\n### Multi-Model Support\r\n\r\n| Model | Provider | Status | Features | Cost |\r\n|-------|----------|--------|----------|------|\r\n| Gemini 1.5 Flash | Google | \u2705 Active | Fast, cost-effective | Low |\r\n| Gemini 1.5 Pro | Google | \u26a0\ufe0f Limited | Higher quality, slower | Medium |\r\n| OpenAI GPT-4 | OpenAI | \ud83d\udd27 Optional | High quality, paid | High |\r\n| Ollama Local | Local | \ud83d\udd27 Optional | Offline, customizable | Free |\r\n\r\n### Custom Configuration\r\n\r\n```bash\r\n# Use custom API key for this session\r\nxerror error.log --api-key your-custom-key\r\n\r\n# Use different AI model\r\nxerror error.log --model gemini-1.5-pro\r\n\r\n# Set custom log directory\r\nexport ERROR_EXPLAINER_LOG_DIR=/custom/path\r\nxerror error.log --save\r\n\r\n# Set default model\r\nexport DEFAULT_MODEL=gemini-1.5-flash\r\n```\r\n\r\n### Search with Filters\r\n\r\n```bash\r\n# Search by error type\r\nxerror search \"NameError\"\r\n\r\n# Search by language\r\nxerror search \"python\"\r\n\r\n# Search by keyword\r\nxerror search \"undefined\"\r\n\r\n# Search by filename\r\nxerror search \"views.py\"\r\n\r\n# Limit search results\r\nxerror search \"error\" --limit 5\r\n\r\n# Search with date range\r\nxerror search \"error\" --since \"2024-01-01\" --until \"2024-12-31\"\r\n```\r\n\r\n## \ud83d\udea8 Troubleshooting\r\n\r\n### Common Issues\r\n\r\n| Issue | Solution | Status |\r\n|-------|----------|--------|\r\n| **API Key Error** | Set `GOOGLE_API_KEY` environment variable | \u2705 Fixed |\r\n| **Language Not Detected** | Use `--offline` mode or check error format | \u2705 Fixed |\r\n| **Slow Response** | Use offline mode or check internet connection | \u2705 Fixed |\r\n| **Import Error** | Install with `pip install xerror` | \u2705 Fixed |\r\n| **Permission Denied** | Check file permissions or use `--offline` | \u2705 Fixed |\r\n\r\n### Error Messages\r\n\r\n```bash\r\n# If you see: \"No API key found\"\r\nexport GOOGLE_API_KEY=your-api-key-here\r\n\r\n# If you see: \"Language not detected\"\r\nxerror error.log --offline\r\n\r\n# If you see: \"Import error\"\r\npip install --upgrade xerror\r\n\r\n# If you see: \"Permission denied\"\r\nchmod +r error.log\r\n```\r\n\r\n### Performance Tips\r\n\r\n- Use `--offline` mode for faster responses\r\n- Save explanations with `--save` to avoid re-analyzing\r\n- Use specific error messages rather than full logs\r\n- Set up your API key in `.env` file for convenience\r\n\r\n## \ud83d\udcc1 Supported File Formats\r\n\r\n| Format | Extension | Description | Example |\r\n|--------|-----------|-------------|---------|\r\n| Log files | `.log` | Standard log files | `error.log` |\r\n| Text files | `.txt` | Plain text files | `error.txt` |\r\n| Python files | `.py` | Python source files | `script.py` |\r\n| Error files | `.error` | Dedicated error files | `error.error` |\r\n| Any text | `*` | Any text-based file | `output` |\r\n\r\n## \ud83c\udfd7\ufe0f Project Structure\r\n\r\n```\r\nxerror/\r\n\u251c\u2500\u2500 xerror/\r\n\u2502   \u251c\u2500\u2500 __init__.py              # Package initialization\r\n\u2502   \u251c\u2500\u2500 cli.py                   # Command line interface\r\n\u2502   \u251c\u2500\u2500 config.py                # Configuration management\r\n\u2502   \u251c\u2500\u2500 explainer.py             # AI explanation engine\r\n\u2502   \u251c\u2500\u2500 parser.py                # Error parsing logic\r\n\u2502   \u251c\u2500\u2500 rule_based_explainer.py  # Offline rule-based analysis\r\n\u2502   \u251c\u2500\u2500 api.py                   # Python API functions\r\n\u2502   \u251c\u2500\u2500 watcher.py               # Real-time process monitoring\r\n\u2502   \u251c\u2500\u2500 models.py                # Multi-model support\r\n\u2502   \u251c\u2500\u2500 language_parsers.py      # Multi-language parsing\r\n\u2502   \u2514\u2500\u2500 utils.py                 # Utility functions\r\n\u251c\u2500\u2500 examples/\r\n\u2502   \u251c\u2500\u2500 error_sample.log         # Python error example\r\n\u2502   \u251c\u2500\u2500 javascript_error.log     # JavaScript error example\r\n\u2502   \u251c\u2500\u2500 typescript_error.log     # TypeScript error example\r\n\u2502   \u251c\u2500\u2500 cpp_error.log            # C++ error example\r\n\u2502   \u251c\u2500\u2500 java_error.log           # Java error example\r\n\u2502   \u2514\u2500\u2500 api_usage_examples.py    # API usage examples\r\n\u251c\u2500\u2500 setup.py                     # Package setup\r\n\u251c\u2500\u2500 requirements.txt             # Dependencies\r\n\u251c\u2500\u2500 env.example                  # Environment template\r\n\u251c\u2500\u2500 README.md                    # This file\r\n\u2514\u2500\u2500 API_DOCUMENTATION.md         # API documentation\r\n```\r\n\r\n## \ud83d\udd2e Roadmap\r\n\r\n| Feature | Status | Priority | ETA | Description |\r\n|---------|--------|----------|-----|-------------|\r\n| VSCode Extension | \ud83d\udd27 In Progress | High | Q4 2024 | IDE integration with real-time error detection |\r\n| GitHub Actions CI | \ud83d\udd27 In Progress | Medium | Q4 2024 | Automated testing and deployment |\r\n| Desktop Notifications | \ud83d\udccb Planned | Medium | Q1 2025 | Get notified of critical errors |\r\n| More Languages (Go, Rust) | \ud83d\udccb Planned | Low | Q2 2025 | Extended language support |\r\n| Web Interface | \ud83d\udccb Planned | Low | Q3 2025 | Browser-based error analysis |\r\n| Mobile App | \ud83d\udccb Planned | Low | Q4 2025 | iOS/Android error analysis |\r\n\r\n## \ud83d\udee0\ufe0f Development\r\n\r\n### Local Development Setup\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/xerror/xerror.git\r\ncd xerror\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# Install development dependencies\r\npip install -r requirements.txt\r\n\r\n# Set up environment\r\ncp env.example .env\r\n# Edit .env with your API keys\r\n```\r\n\r\n### Development Commands\r\n\r\n```bash\r\n# Run tests\r\npython -m pytest\r\n\r\n# Run linting\r\nflake8 xerror/\r\n\r\n# Format code\r\nblack xerror/\r\n\r\n# Type checking\r\nmypy xerror/\r\n\r\n# Build package\r\npython setup.py sdist bdist_wheel\r\n\r\n# Install from local build\r\npip install dist/xerror-0.1.0.tar.gz\r\n\r\n# Run security checks\r\nbandit -r xerror/\r\n```\r\n\r\n### Contributing Guidelines\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Make your changes\r\n4. Add tests for new functionality\r\n5. Run tests: `python -m pytest`\r\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n7. Push to the branch (`git push origin feature/amazing-feature`)\r\n8. Open a Pull Request\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n| Component | Version | Required | Notes |\r\n|-----------|---------|----------|-------|\r\n| Python | 3.10+ | \u2705 Yes | Core requirement |\r\n| Google Gemini API | Latest | \u26a0\ufe0f For AI mode | Free tier available |\r\n| Internet Connection | - | \u26a0\ufe0f For AI mode | Not needed for offline mode |\r\n| Click | 8.1.0+ | \u2705 Yes | CLI framework |\r\n| Rich | 13.0.0+ | \u2705 Yes | Terminal formatting |\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\r\n\r\n### Development Areas\r\n\r\n| Area | Description | Priority | Status |\r\n|------|-------------|----------|--------|\r\n| Language Support | Add new programming languages | High | \ud83d\udd27 In Progress |\r\n| Error Patterns | Improve error detection patterns | High | \ud83d\udd27 In Progress |\r\n| AI Models | Add support for new AI providers | Medium | \ud83d\udccb Planned |\r\n| Performance | Optimize parsing and analysis speed | Medium | \ud83d\udccb Planned |\r\n| Documentation | Improve docs and examples | Low | \u2705 Complete |\r\n\r\n### How to Contribute\r\n\r\n1. **Report Bugs**: Use [GitHub Issues](https://github.com/xerror/xerror/issues)\r\n2. **Request Features**: Use [GitHub Discussions](https://github.com/xerror/xerror/discussions)\r\n3. **Submit Code**: Follow the contributing guidelines above\r\n4. **Improve Docs**: Submit PRs for documentation improvements\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- [Google Gemini](https://ai.google.dev/) for providing the AI capabilities\r\n- [Click](https://click.palletsprojects.com/) for the CLI framework\r\n- [Rich](https://rich.readthedocs.io/) for beautiful terminal output\r\n- [Python Community](https://www.python.org/community/) for inspiration\r\n- All contributors and users who provided feedback\r\n\r\n## \ud83d\udc68\u200d\ud83d\udcbb Author\r\n\r\n**Avishek Devnath**\r\n- \ud83d\udce7 Email: [avishekdevnath@gmail.com](mailto:avishekdevnath@gmail.com)\r\n- \ud83c\udf10 GitHub: [@avishekdevnath](https://github.com/avishekdevnath)\r\n- \ud83d\udcbc LinkedIn: [Avishek Devnath](https://linkedin.com/in/avishekdevnath)\r\n\r\n## \ud83d\udcde Support\r\n\r\n| Channel | Link | Response Time | Best For |\r\n|---------|------|---------------|----------|\r\n| \ud83d\udce7 Email | [avishekdevnath@gmail.com](mailto:avishekdevnath@gmail.com) | 24-48 hours | Personal support, feature requests |\r\n| \ud83d\udc1b Issues | [GitHub Issues](https://github.com/xerror/xerror/issues) | 1-3 days | Bug reports, technical issues |\r\n| \ud83d\udcd6 Documentation | [GitHub Wiki](https://github.com/xerror/xerror/wiki) | Instant | How-to guides, tutorials |\r\n| \ud83d\udcac Discussions | [GitHub Discussions](https://github.com/xerror/xerror/discussions) | 1-2 days | General questions, community help |\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f by [Avishek Devnath](mailto:avishekdevnath@gmail.com) for developers everywhere** \r\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A smart CLI tool to analyze error logs from multiple languages and return AI-generated explanations and fix suggestions",
    "version": "1.0.0",
    "project_urls": {
        "Bug Reports": "https://github.com/xerror/xerror/issues",
        "Documentation": "https://github.com/xerror/xerror#readme",
        "Homepage": "https://github.com/xerror/xerror",
        "Source": "https://github.com/xerror/xerror"
    },
    "split_keywords": [
        "error",
        " debugging",
        " ai",
        " cli",
        " python",
        " traceback",
        " exception"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a18edbdbd268b6f078a2bda04f0b1fc3d75447e4e340cf23b274e4f0574a4bf4",
                "md5": "3f2c34dc40913f7854c179f0c6c3775a",
                "sha256": "abc65a37fb2624ef4dc679167fb101292cfaa0899b285c3b1393dc2e8c3d35f6"
            },
            "downloads": -1,
            "filename": "xerror-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3f2c34dc40913f7854c179f0c6c3775a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 38636,
            "upload_time": "2025-07-26T08:13:12",
            "upload_time_iso_8601": "2025-07-26T08:13:12.218008Z",
            "url": "https://files.pythonhosted.org/packages/a1/8e/dbdbd268b6f078a2bda04f0b1fc3d75447e4e340cf23b274e4f0574a4bf4/xerror-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5a31afa046295aed1ef1555d804416b7d228ceef954018b98c841cbdd977cec9",
                "md5": "1d9c323ea3024040fad369e8756c1d7d",
                "sha256": "357b0de72bf175a38bf48cfea4738a7bd2d83ba449350d633bc64e64e8e05834"
            },
            "downloads": -1,
            "filename": "xerror-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "1d9c323ea3024040fad369e8756c1d7d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 40680,
            "upload_time": "2025-07-26T08:13:13",
            "upload_time_iso_8601": "2025-07-26T08:13:13.622394Z",
            "url": "https://files.pythonhosted.org/packages/5a/31/afa046295aed1ef1555d804416b7d228ceef954018b98c841cbdd977cec9/xerror-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-26 08:13:13",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "xerror",
    "github_project": "xerror",
    "github_not_found": true,
    "lcname": "xerror"
}