| --- |
| title: AI Code Maintainability Scoring Engine |
| emoji: 🚀 |
| colorFrom: blue |
| colorTo: indigo |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| # AI Code Maintainability Scoring & Refactoring Engine |
|
|
| 🚀 **Live Demo:** [ai-code-maintainability.hmuhammadusman.com](https://ai-code-maintainability.hmuhammadusman.com) |
|
|
| ## Overview |
| The **AI Code Maintainability Scoring Engine** is a modular, machine-learning-based system designed to evaluate the structural quality of Python code and autonomously refactor it. Rather than relying on rigid rule-based linters (like PyLint or Flake8), this engine uses a supervised learning approach (Random Forest) to predict maintainability risks dynamically based on pure structural signals, and then utilizes Deep Learning (CodeT5) to actively improve the code. |
|
|
| This repository contains the completely unified Engine: |
| - **Phase 1 (The Evaluator)**: The Core Scoring Engine. It evaluates code and assigns a risk score (0–100), a risk category, and surfaces top structural risk factors. |
| - **Phase 2 (The Refactorer)**: The Autonomous Refactoring Agent. It generates, validates, and selects better candidates for structurally risky code to iteratively improve the risk score. |
|
|
| ## System Architecture |
|
|
| The engine is built on a strictly modular architecture. |
|
|
| ### Evaluator (Phase 1) |
| 1. **AST Analyzer (`ast_analyzer.py`)**: Parses Python Abstract Syntax Trees (AST) to extract 11 core structural metrics. |
| 2. **ML Risk Model (`model_trainer.py`)**: Uses a Random Forest classifier for stateless inference of risk scores. |
| 3. **Explanation Engine (`explanation_engine.py`)**: Converts raw feature importances into plain-English explanations. |
| 4. **Scoring API (`scoring_api.py`)**: The central access point exposing the master `evaluate()` backend function. |
|
|
| ### Refactorer (Phase 2) |
| 1. **Candidate Generator (`phase2/candidate_generator.py`)**: Uses a localized Deep Learning model (`CodeT5`) to generate multiple refactored versions of the code. |
| 2. **Code Validator (`phase2/validation.py`)**: Ensures that generated candidates compile and do not contain syntax errors. |
| 3. **Candidate Selector (`phase2/selector.py`)**: Uses the `Scoring API` to rank candidates and selects the one that provides the best improvement in the maintainability risk score. |
| 4. **Iterative Optimizer (`phase2/optimization.py`)**: Manages the iterative loops to continuously refine the code until a target score is reached. |
| |
| ## Extracted Structural Features |
| The Evaluator rates maintainability using the following exact signals: |
| - Maximum Nesting Depth (*Strongest Indicator*) |
| - Cyclomatic Complexity Approximation |
| - Average Function Length and Total Line Count |
| - Branching Density (`if`/`elif`) |
| - Loop Density (`for`/`while`) |
| - Error Handling Density (`try`/`except`) |
| - Number of Functions and Return Points |
| - Global Variable Declarations |
| - Recursion Detection |
| |
| ## Quick Start |
| |
| ### Installation |
| Ensure you have Python 3.8+ installed. Install the required dependencies: |
| ```bash |
| pip install scikit-learn xgboost numpy transformers torch |
| ``` |
| |
| ### Usage |
| To analyze and refactor a Python file automatically, you can use the unified `main.py` entry point: |
| |
| ```bash |
| python main.py path/to/your/messy_code.py |
| ``` |
| This will: |
| 1. Provide the initial maintainability score. |
| 2. Interactively use Deep Learning to refactor the code. |
| 3. Output the cleaned code and the final score improvement. |
| |
