🚀 Code Quality Intelligence Agent (MVP)

An AI-powered agent that analyzes multi-language codebases, identifies quality issues, and produces actionable reports with explanations, fix suggestions, prioritization, hotspots, and interactive Q&A over the codebase.

🎯 Features • ⚡ Quick Start • 🔧 Setup • 📖 Usage • 🤖 AI Integration • 🚀 Deployment • 🤝 Contributing

🎥 Explanation Video

📺 Project Demo & Walkthrough

📹 Complete Project Explanation & Demo Video

🎬 Video Quality & Features:

✅ HD Quality: 1080p recording for clear visibility
✅ Screen Recording: Full desktop capture with annotations
✅ Audio Commentary: Clear explanations throughout
✅ Code Highlighting: Syntax highlighting for better understanding
✅ Interactive Elements: Live demonstrations of all features
✅ Multiple Scenarios: Different repository types analyzed

📱 Access Options:

🎥 YouTube: Watch on YouTube
📺 Live Link of project: [Live Link Access](scoming soon ...)
📱 Mobile Friendly: Optimized for mobile viewing
⏯️ Playback Controls: Pause, rewind, and speed control

💡 Video Highlights:

"See how the Code Quality Intelligence Agent transforms complex codebases into actionable insights with AI-powered analysis, interactive visualizations, and intelligent recommendations."

🧑‍💻 CLI: Watch live CLI demo
🔍 Real-time Analysis: Watch live code analysis in action
📊 Interactive Dashboards: Explore dynamic visualizations
🤖 AI Conversations: Experience natural language Q&A
🚀 One-Click Deployment: See effortless setup process
📈 Comprehensive Reports: Generate detailed quality reports

📚 Architecture

🏗️ System Architecture

graph TB
    A[User Interface] --> B[CLI/Web]
    B --> C[Analysis Engine]
    C --> D[Language Analyzers]
    C --> E[Quality Metrics]
    C --> F[Dependency Graph]
    C --> G[AI Integration]
    
    D --> H[Python Analyzers]
    D --> I[JS/TS Analyzers]
    
    E --> J[Hotspot Detection]
    E --> K[Issue Prioritization]
    
    F --> L[Network Analysis]
    F --> M[Hierarchy Building]
    
    G --> N[DeepSeek API]
    G --> O[Local LLM]
    G --> P[Hugging Face]
    
    C --> Q[Visualization Engine]
    Q --> R[Plotly Charts]
    Q --> S[Interactive Graphs]
    
    C --> T[Report Generation]
    T --> U[Markdown]
    T --> V[SARIF]
    T --> W[CSV]

🎯 Features

🔍 Multi-Language Analysis

Python: Ruff, Bandit, Radon analysis
JavaScript/TypeScript: ESLint with security plugins
Smart Detection: Automatic language detection and appropriate tooling

🤖 AI-Powered Intelligence

DeepSeek Integration: Remote AI for advanced analysis
Local LLM Fallback: Offline AI using Hugging Face models
Smart Severity Scoring: AI-enhanced issue prioritization
Conversational Q&A: Natural language codebase exploration

📊 Advanced Visualizations

Interactive Charts: Plotly-powered dashboards
Dependency Graphs: Network analysis and hierarchy visualization
Hotspot Analysis: Code complexity and churn heatmaps
Trend Analysis: Quality metrics over time

⚡ Performance Optimized

Incremental Caching: Smart file change detection
Parallel Processing: Multi-threaded analysis
Sampling Tiers: Efficient large repository handling
Fast Mode: Optimized for 1000+ file repositories

🛠️ Developer Experience

Modern Web UI: Streamlit with glassmorphism design
CLI Interface: Command-line tool for CI/CD integration
Autofix Capabilities: Safe automated code improvements
Export Options: Markdown, SARIF, CSV reports

⚡ Quick Start

🐍 Prerequisites

Python 3.11 or higher
Git (for repository analysis)
4GB+ RAM (for AI features)

📦 Installation

# Clone the repository
git clone https://github.com/Blacksujit/Code-Quality-Intelligent_Agent
cd code-quality-agent

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
python -m pip install -e .

# Install optional AI dependencies
python -m pip install transformers torch

🚀 Run Web Interface

# Launch the modern web interface
streamlit run src/cq_agent/web/app.py

# Or use the demo script
python demo_ui.py

🌐 Open your browser to: http://localhost:8501

🔧 Setup

📁 Project Structure

code-quality-agent/
├── 📁 src/cq_agent/
│   ├── 📁 analyzers/          # Code analysis engines
│   ├── 📁 ai/                 # AI integration modules
│   ├── 📁 cli/                # Command-line interface
│   ├── 📁 graph/              # Dependency analysis
│   ├── 📁 metrics/            # Quality metrics
│   ├── 📁 qa/                 # Q&A and search
│   ├── 📁 reporting/          # Report generation
│   ├── 📁 visualizations/     # Chart and graph creation
│   └── 📁 web/                # Streamlit web interface
├── 📁 assignment-docs/        # Project documentation
├── 📄 pyproject.toml          # Dependencies and metadata
└── 📄 README.md              # This file

🔑 Environment Configuration

Create a .env file in the project root:

# AI Configuration (Optional)
DEEPSEEK_API_KEY=your_deepseek_api_key_here
HF_TOKEN=your_huggingface_token_here
HUGGINGFACEHUB_API_TOKEN=your_hf_inference_token_here

# Performance Settings
MAX_FILES=1000
WORKER_THREADS=4

📦 Dependencies

Core Dependencies

# Essential packages (auto-installed)
pip install streamlit pandas plotly numpy
pip install gitpython pathlib typing-extensions

AI Dependencies (Optional)

# For local LLM support
pip install transformers torch

# For enhanced semantic search
pip install faiss-cpu sentence-transformers

# For advanced AI agents
pip install langchain langchain-community

Analysis Tools

# Python analysis (auto-installed)
pip install ruff bandit radon

# JavaScript/TypeScript analysis (optional)
npm install -g eslint

📖 Usage

🎨 Web Interface

The Streamlit web interface provides a modern, interactive experience:

🔧 Analysis Configuration

Repository Path: Select or enter your codebase location
File Limits: Configure analysis scope (default: 1000 files)
Fast Mode: Enable for large repositories (1000+ files)
AI Backend: Choose between DeepSeek, Local LLM, or Disabled

📊 Dashboard Tabs

📈 Overview: Quality metrics and summary cards
🔍 Issues: Filterable issue list with AI enhancements
📁 File Details: Per-file analysis and code context
🔧 Autofix: Safe automated code improvements
📤 Export: Download reports in multiple formats
🌐 Dependencies: Interactive dependency graphs
🔥 Hotspots: Code complexity and churn analysis
📈 Trends: Quality metrics over time
🤖 AI Q&A: Conversational codebase exploration

🔌 CLI Commands

📊 Analysis Commands

# Basic analysis
cq-agent analyze .

# Generate reports
cq-agent analyze . --md report.md --sarif security.sarif

# Preview and apply autofixes
cq-agent analyze . --autofix-dry-run
cq-agent analyze . --autofix

# AI-enhanced analysis
cq-agent analyze . --deepseek

💬 Q&A Commands

# Interactive Q&A (extractive mode)
cq-agent qa .

# DeepSeek AI Q&A
cq-agent qa . --deepseek

# Local LLM Q&A
cq-agent qa . --local-llm

# Agentic Q&A with Hugging Face
cq-agent qa . --agent --agent-backend hf --agent-model "HuggingFaceH4/zephyr-7b-beta"

📋 Command Reference

Command	Description	Example
`analyze <path>`	Analyze code repository	`cq-agent analyze .`
`--md <file>`	Generate Markdown report	`--md report.md`
`--sarif <file>`	Generate SARIF report	`--sarif security.sarif`
`--autofix-dry-run`	Preview safe fixes	`--autofix-dry-run`
`--autofix`	Apply safe fixes	`--autofix`
`--incremental`	Use incremental cache	`--incremental`
`--no-incremental`	Disable cache	`--no-incremental`
`--deepseek`	Enable DeepSeek AI	`--deepseek`
`qa <path>`	Interactive Q&A	`cq-agent qa .`
`--local-llm`	Use local LLM	`--local-llm`
`--agent`	Use agentic Q&A	`--agent`
`--agent-backend <type>`	AI backend type	`--agent-backend hf`
`--agent-model <name>`	AI model name	`--agent-model llama3.1`

🔧 Performance Flags

# Fast mode for large repositories
cq-agent analyze . --max-files 1000

# Incremental analysis (default)
cq-agent analyze . --incremental

# Fresh analysis
cq-agent analyze . --no-incremental

# Parallel processing
cq-agent analyze . --workers 8

🤖 AI Integration

🌐 DeepSeek (Remote AI)

Best for: Production use, most capable analysis

# Set API key
export DEEPSEEK_API_KEY="your_key_here"

# Use in web interface or CLI
cq-agent analyze . --deepseek
cq-agent qa . --deepseek

Features:

✅ Advanced code understanding
✅ Smart severity re-ranking
✅ Comprehensive Q&A responses
❌ Requires API key and internet

🏠 Local LLM (Offline AI)

Best for: Development, privacy, offline work

# Install dependencies
pip install transformers torch

# Use in web interface (select "Local LLM (Fast)")
# Or CLI
cq-agent qa . --local-llm --local-model "microsoft/DialoGPT-small"

Features:

✅ No API keys required
✅ Works offline
✅ Fast for development
✅ Privacy-focused
❌ Limited model capabilities

🔄 Hugging Face Integration

Best for: Custom models, inference endpoints

# Router (OpenAI-compatible)
export HF_TOKEN="hf_..."
cq-agent qa . --agent --agent-backend hf --agent-model "HuggingFaceH4/zephyr-7b-beta:featherless-ai"

# Inference API
export HUGGINGFACEHUB_API_TOKEN="hf_..."
cq-agent qa . --agent --agent-backend hf --agent-model "HuggingFaceH4/zephyr-7b-beta"

🎯 AI Backend Selection Guide

Backend	Speed	Capability	Privacy	Cost	Best For
DeepSeek	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	💰💰	Production
Local LLM	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	💰	Development
HF Router	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	💰💰	Custom models
Extractive	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	💰	No AI needed

🎨 Web Interface

🎭 Modern Design Features

🌊 Glassmorphism Theme: Modern, translucent UI elements
📱 Responsive Layout: Works on desktop, tablet, and mobile
🎨 Interactive Charts: Plotly-powered visualizations
⚡ Real-time Updates: Live progress bars and status updates
🎯 Smart Filtering: Advanced search and filter capabilities

📊 Visualization Types

📈 Overview Dashboard

Quality score gauge
Severity distribution charts
Language breakdown
File count metrics

🌐 Dependency Analysis

Interactive network graphs
Hierarchical sunburst charts
Dependency heatmaps
Centrality analysis

🔥 Hotspot Analysis

Code complexity treemaps
Churn vs. complexity scatter plots
Language comparison radar charts
Directory-level heatmaps

📈 Trend Analysis

Quality metrics over time
Commit activity heatmaps
Lines changed charts
Issue resolution trends

📊 Visualizations

🎨 Chart Types

📊 Bar Charts

Severity distribution
Language breakdown
Issue categories
File complexity

🌐 Network Graphs

Dependency relationships
File connections
Module interactions
Import/export flows

🔥 Heatmaps

Code complexity by directory
Issue density by file
Churn patterns
Language comparison

📈 Time Series

Quality trends
Commit activity
Issue resolution
Code growth

🎯 Specialized Charts

Sunburst: Hierarchical dependency structure
Treemap: File size and complexity
Radar: Multi-dimensional language comparison
Scatter: Complexity vs. churn analysis

🚀 Deployment

🐳 Docker Deployment

# Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .
RUN pip install -e .

EXPOSE 8501
CMD ["streamlit", "run", "src/cq_agent/web/app.py", "--server.port=8501", "--server.address=0.0.0.0"]

# Build and run
docker build -t code-quality-agent .
docker run -p 8501:8501 code-quality-agent

☁️ Cloud Deployment

🌐 Streamlit Cloud

# .streamlit/secrets.toml
DEEPSEEK_API_KEY = "your_key_here"
HF_TOKEN = "your_hf_token_here"

🪰 Fly.io

# fly.toml (already included)
fly launch
fly deploy

🐳 Railway

# railway.json
{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "streamlit run src/cq_agent/web/app.py --server.port=$PORT --server.address=0.0.0.0"
  }
}

🔧 Environment Variables

# Production environment
export DEEPSEEK_API_KEY="your_production_key"
export HF_TOKEN="your_hf_token"
export MAX_FILES="2000"
export WORKER_THREADS="8"
export STREAMLIT_SERVER_PORT="8501"
export STREAMLIT_SERVER_ADDRESS="0.0.0.0"

🚀 Quick Deployment Commands

# Make deployment script executable (Linux/Mac)
chmod +x deploy.sh

# Deploy to different platforms
./deploy.sh streamlit    # Streamlit Cloud (Free)
./deploy.sh railway      # Railway (Free tier)
./deploy.sh render       # Render (Free tier)
./deploy.sh fly          # Fly.io (Free tier)
./deploy.sh local        # Local Docker

🤝 Contributing

🚀 Getting Started

🍴 Fork the repository

📥 Clone your fork

git clone https://github.com/your-username/code-quality-agent.git
cd code-quality-agent

🌿 Create a feature branch
```
git checkout -b feature/amazing-feature
```

🔧 Set up development environment

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

🧪 Development Setup

# Install development dependencies
pip install -e ".[dev,local_llm,ai]"

# Run tests
python -m pytest tests/

# Run linting
ruff check src/
black src/

# Run type checking
mypy src/

📝 Contributing Guidelines

🎯 Areas for Contribution

🔍 New Analyzers: Add support for more languages
🤖 AI Models: Integrate additional LLM backends
📊 Visualizations: Create new chart types
🔧 CLI Features: Add new command-line options
📱 UI Improvements: Enhance the web interface
📚 Documentation: Improve guides and examples

📋 Pull Request Process

✅ Ensure tests pass
📝 Update documentation
🎨 Follow code style guidelines
📋 Provide clear description
🔗 Link related issues

🏷️ Issue Labels

🐛 bug: Something isn't working
✨ enhancement: New feature or request
📚 documentation: Documentation improvements
🎨 ui/ux: User interface improvements
🤖 ai: AI-related features
⚡ performance: Performance improvements
🔧 maintenance: Code maintenance tasks

🔧 Core Modules

Module	Purpose	Key Components
🔍 Analyzers	Code analysis engines	Python, JS/TS, AST parsing
🤖 AI	AI integration	DeepSeek, Local LLM, HF
🌐 Graph	Dependency analysis	NetworkX, centrality metrics
📊 Metrics	Quality measurement	Hotspots, complexity, churn
🎨 Visualizations	Chart generation	Plotly, interactive graphs
📝 Reporting	Output generation	Markdown, SARIF, CSV
💬 Q&A	Code search and query	TF-IDF, semantic search
🔧 Autofix	Automated fixes	Safe transformations

🔄 Data Flow

📁 Repository Ingestion: Load and parse codebase
🔍 Analysis: Run language-specific analyzers
📊 Metrics Calculation: Compute quality metrics
🌐 Graph Building: Create dependency relationships
🤖 AI Enhancement: Apply AI-powered insights
🎨 Visualization: Generate interactive charts
📝 Report Generation: Create output documents

🔧 Troubleshooting

❌ Common Issues

🐍 Python Version

# Ensure Python 3.11+
python --version

# If using older version, upgrade
pyenv install 3.11.0
pyenv local 3.11.0

📦 Missing Dependencies

# Reinstall package
pip uninstall cq-agent
pip install -e .

# Install optional dependencies
pip install transformers torch
pip install faiss-cpu sentence-transformers

🔑 API Key Issues

# Check environment variables
echo $DEEPSEEK_API_KEY
echo $HF_TOKEN

# Set in .env file
echo "DEEPSEEK_API_KEY=your_key" >> .env

🌐 Streamlit Issues

# Clear Streamlit cache
streamlit cache clear

# Check port availability
lsof -i :8501

# Use different port
streamlit run src/cq_agent/web/app.py --server.port 8502

🤖 AI Model Issues

# Check model availability
python -c "from transformers import pipeline; print('Models available')"

# Clear model cache
rm -rf ~/.cache/huggingface/

# Use smaller model
cq-agent qa . --agent --agent-model "microsoft/DialoGPT-small"

🆘 Getting Help

📖 Documentation: Check this README and inline docs
🐛 Issues: Search existing GitHub issues
💬 Discussions: Use GitHub Discussions for questions
📧 Contact: Create a new issue for bugs or feature requests

📄 License

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

🚀 Built with ❤️ for the developer community

•⭐ Star this repo

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.streamlit		.streamlit
MVP-images		MVP-images
assignment-docs		assignment-docs
deployement-docs		deployement-docs
docs-generated		docs-generated
sample-outputs		sample-outputs
src/cq_agent		src/cq_agent
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
demo_ui.py		demo_ui.py
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml
env.example		env.example
fly.toml		fly.toml
pyproject.toml		pyproject.toml
render.yaml		render.yaml
requirements.txt		requirements.txt
setup.py		setup.py

License

Blacksujit/Code-Quality-Intelligent_Agent

Folders and files

Latest commit

History

Repository files navigation

🚀 Code Quality Intelligence Agent (MVP)

📋 Table of Contents

🎥 Explanation Video

📺 Project Demo & Walkthrough

🎬 Video Quality & Features:

📱 Access Options:

💡 Video Highlights:

📚 Architecture

🏗️ System Architecture

🎯 Features

🔍 Multi-Language Analysis

🤖 AI-Powered Intelligence

📊 Advanced Visualizations

⚡ Performance Optimized

🛠️ Developer Experience

⚡ Quick Start

🐍 Prerequisites

📦 Installation

🚀 Run Web Interface

🔧 Setup

📁 Project Structure

🔑 Environment Configuration

📦 Dependencies

Core Dependencies

AI Dependencies (Optional)

Analysis Tools

📖 Usage

🎨 Web Interface

🔧 Analysis Configuration

📊 Dashboard Tabs

🔌 CLI Commands

📊 Analysis Commands

💬 Q&A Commands

📋 Command Reference

🔧 Performance Flags

🤖 AI Integration

🌐 DeepSeek (Remote AI)

🏠 Local LLM (Offline AI)

🔄 Hugging Face Integration

🎯 AI Backend Selection Guide

🎨 Web Interface

🎭 Modern Design Features

📊 Visualization Types

📈 Overview Dashboard

🌐 Dependency Analysis

🔥 Hotspot Analysis

📈 Trend Analysis

📊 Visualizations

🎨 Chart Types

📊 Bar Charts

🌐 Network Graphs

🔥 Heatmaps

📈 Time Series

🎯 Specialized Charts

🚀 Deployment

🐳 Docker Deployment

☁️ Cloud Deployment

🌐 Streamlit Cloud

🪰 Fly.io

🐳 Railway

🔧 Environment Variables

🚀 Quick Deployment Commands

🤝 Contributing

🚀 Getting Started

🧪 Development Setup

📝 Contributing Guidelines

🎯 Areas for Contribution

📋 Pull Request Process

🏷️ Issue Labels

🔧 Core Modules

🔄 Data Flow

🔧 Troubleshooting

❌ Common Issues

🐍 Python Version

Packages