MazenMohamed10/Luca-PyGuide-1.0

Luca-PyGuide

Luca-PyGuide is a lightweight Python error analysis tool that predicts common Python errors and provides explanations, suggested fixes, corrected code, and learning tips.

It combines a machine-learning classifier with runtime verification and rule-based analysis to improve the reliability of its results.

Features

• Predicts common Python errors using a trained machine-learning model.

• Supports:

  • IndexError
  • NameError
  • SyntaxError

• Runtime verification of submitted Python code.

• Human-readable error explanations.

• Suggested fixes.

• Corrected code when possible.

• Educational tips.

• Handles valid Python code.

• Handles empty input.

• Simple Python package interface.

• No GUI required.

Example

from luca_pyguide import LucaPyGuide

guide = LucaPyGuide()

result = guide.analyze("""
numbers = [1, 2, 3]
print(numbers[10])
""")

print(result)

Example output:

{
    "error_type": "IndexError",
    "predicted_error": "IndexError",
    "confidence": 0.72,
    "probabilities": {
        "IndexError": 0.72,
        "NameError": 0.28
    },
    "success": True,
    "explanation": "The list 'numbers' contains 3 elements, but the code tries to access index 10, which is outside the valid range.",
    "fix": "Use an index between -3 and 2.",
    "fixed_code": "numbers = [1, 2, 3]\nprint(numbers[2])",
    "tip": "Python lists use zero-based indexing."
}

How It Works

Luca-PyGuide uses a hybrid analysis pipeline:

Python Code
     |
     v
Syntax Check
     |
     v
ML Error Prediction
     |
     v
Runtime Verification
     |
     v
Error-Specific Analyzer
     |
     v
Explanation + Fix + Corrected Code

The machine-learning model provides an initial prediction.

Runtime verification then checks whether the submitted Python code actually raises an exception.

This allows Luca-PyGuide to correct an incorrect ML prediction when the code executes successfully.

Machine Learning Model

The current model uses:

• TF-IDF Vectorization
• Logistic Regression
• scikit-learn

The model was trained to distinguish between:

IndexError
NameError

SyntaxError is handled separately through Python syntax validation.

Model Evaluation

Current evaluation results:

Accuracy: 92.11%

              precision    recall  f1-score   support

IndexError       0.90      1.00      0.95        28
NameError        1.00      0.70      0.82        10

accuracy                           0.92        38
macro avg        0.95      0.85      0.89        38
weighted avg     0.93      0.92      0.92        38

Installation

Clone the repository:

git clone <YOUR_REPOSITORY_URL>
cd Luca-PyGuide

Install the required dependencies:

pip install -r requirements.txt

Usage

from luca_pyguide import LucaPyGuide

guide = LucaPyGuide()

code = """
numbers = [1, 2, 3]
print(numbers[10])
"""

result = guide.analyze(code)

print(result)

Valid Code

Luca-PyGuide also handles code that does not contain an error.

result = guide.analyze("""
score = 100
print(score)
""")

Expected behavior:

error_type: None
success: True

Even if the ML model predicts an error, runtime verification can override that prediction when the code executes successfully.

Syntax Errors

Example:

result = guide.analyze("""
numbers = [1, 2, 3
print(numbers[0])
""")

The analyzer identifies the syntax error before attempting normal runtime analysis.

Empty Input

Empty input is handled safely:

result = guide.analyze("")

The API returns a structured response instead of crashing.

Project Structure

Luca-PyGuide/
|
├── luca_pyguide/
│   ├── __init__.py
│   └── core.py
│
├── src/
│   └── model/
│       ├── analyzer.py
│       ├── predict.py
│       └── train.py
│
├── models/
│   └── Luca-PyGuide-1.0.joblib
│
├── data/
│   └── processed/
│       └── luca_pyguide_250.json
│
├── test.py
├── requirements.txt
├── README.md
└── LICENSE

Testing

The final test suite covers:

• List IndexError
• String IndexError
• NameError
• Valid Python code
• SyntaxError
• Empty input

All seven final test cases passed successfully.

Limitations

The current version supports a limited number of Python errors:

IndexError
NameError
SyntaxError

The model is trained on a relatively small dataset, so predictions should be considered probabilistic.

Runtime verification and rule-based analysis are used to improve reliability.

Roadmap

• Dataset generation
• Dataset expansion
• Dataset validation
• ML model training
• Model evaluation
• Error prediction
• Runtime verification
• Error-specific analysis
• Python package interface
• Final test suite
• Support more Python errors
• Expand the training dataset
• Improve model accuracy
• Publish on Hugging Face
• Add automated CI tests

License

This project is licensed under the MIT License.

See the LICENSE file for details.

Author

Mazen Mohamed