| title | AI Code Explainer | ||||||
|---|---|---|---|---|---|---|---|
| emoji | 🧠 | ||||||
| colorFrom | blue | ||||||
| colorTo | purple | ||||||
| sdk | streamlit | ||||||
| sdk_version | 1.40.0 | ||||||
| app_file | src/streamlit_app.py | ||||||
| pinned | false | ||||||
| license | mit | ||||||
| tags |
|
||||||
| short_description | AI-powered code analysis, explanation, and visualization |
Analyze, understand, and improve your code with AI
A production-ready tool that uses AI to explain code, analyze complexity, detect security issues, generate documentation, and visualize code flow.
- High-Level Summary: Understand what code does at a glance
- Line-by-Line Walkthrough: Step-by-step explanation of each line
- ELI5 Mode: Simple explanations with real-world analogies
- Audience Levels: Beginner, Intermediate, Expert
- Complexity Analysis: Time & Space complexity (Big O notation)
- Security Scan: Detect common vulnerabilities (SQL injection, hardcoded keys, etc.)
- Best Practices Review: PEP8 compliance, naming conventions, code smells
- Flowchart Generation: Visual representation of code logic
- Dependency Graphs: See which functions call which
- Mermaid Diagrams: Interactive, copy-ready diagrams
- Refactoring Suggestions: Improve readability, performance, or maintainability
- Before/After Comparison: Side-by-side view of changes
- Docstring Generation: Auto-generate documentation in multiple styles
- Ask Questions: "Why did you use a while loop here?"
- Context-Aware: Remembers the conversation history
- Deep Understanding: Get detailed answers about specific code sections
- Python 3.10+
- Groq API Key (free tier available)
# Clone the repository
git clone https://github.com/your-repo/ai-code-explainer.git
cd ai-code-explainer
# Create virtual environment with uv
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
uv pip install -e .
# Copy environment template and add your API key
cp .env.example .env
# Edit .env and add your GROQ_API_KEY
# Run the application
streamlit run src/streamlit_app.py# Clone the repository
git clone https://github.com/your-repo/ai-code-explainer.git
cd ai-code-explainer
# Copy environment template
cp .env.example .env
# Edit .env and add your GROQ_API_KEY
# Run with Docker Compose (Direct Mode - Default)
docker-compose up --build
# Access at http://localhost:7860- Fork this repository
- Create a new Space on Hugging Face
- Select "Docker" as the SDK
- Add your
GROQ_API_KEYas a secret in Space settings - Push to your Space repository
This project follows a "Direct-First" Hybrid Architecture:
┌─────────────────────────────────────────────────────────────┐
│ AI Code Explainer │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────────────┐ │
│ │ Streamlit │ │ Backend │ │
│ │ Frontend │ │ │ │
│ │ │ Direct │ ┌─────────────────┐ │ │
│ │ components.py │─────────│─►│ services.py │ │ │
│ │ │ Import │ │ (Business Logic)│ │ │
│ │ streamlit_app │ │ └─────────────────┘ │ │
│ │ .py │ │ │ │ │
│ │ │ OR │ ▼ │ │
│ │ │ │ ┌─────────────────┐ │ │
│ │ │ HTTP │ │ api.py │ │ │
│ │ │─────────│─►│ (FastAPI) │ │ │
│ │ │ (--mode │ └─────────────────┘ │ │
│ │ │ api) │ │ │
│ └─────────────────┘ └─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
| Mode | Description | Use Case |
|---|---|---|
| Direct Mode (Default) | Frontend imports backend services directly | HF Spaces, local dev |
| API Mode | Frontend calls FastAPI endpoints via HTTP | Microservices, scaling |
ai-code-explainer/
├── .env.example # Environment template
├── Dockerfile # Streamlit container (HF Spaces)
├── Dockerfile.api # FastAPI container (API mode)
├── docker-compose.yml # Multi-container orchestration
├── pyproject.toml # uv/pip project configuration
├── requirements.txt # pip-compatible dependencies
├── README.md # This file
└── src/
├── __init__.py
├── streamlit_app.py # Main entry point
├── frontend/
│ ├── __init__.py
│ └── components.py # Reusable UI components
└── backend/
├── __init__.py
├── config.py # Centralized configuration
├── services.py # Business logic (AI interactions)
└── api.py # FastAPI endpoints
| Variable | Required | Default | Description |
|---|---|---|---|
GROQ_API_KEY |
✅ Yes | - | Your Groq API key |
GROQ_BASE_URL |
No | https://api.groq.com |
API base URL (no /openai/v1) |
GROQ_MODEL_NAME |
No | llama-3.3-70b-versatile |
AI model to use |
MAX_CODE_LINES |
No | 500 |
Max lines to analyze |
| Model | Speed | Quality | Best For |
|---|---|---|---|
llama-3.3-70b-versatile |
⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Complex code, detailed explanations |
llama-3.1-8b-instant |
⭐⭐⭐⭐⭐ | ⭐⭐⭐ | Quick analysis, simple code |
llama-3.1-70b-versatile |
⭐⭐⭐ | ⭐⭐⭐⭐ | Alternative to 3.3 |
mixtral-8x7b-32768 |
⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Large files (32K context) |
gemma2-9b-it |
⭐⭐⭐⭐ | ⭐⭐⭐ | Efficient, balanced |
- Understand complex algorithms with ELI5 explanations
- Learn from flowchart visualizations
- Get analogies that make concepts click
- Document legacy code with auto-generated docstrings
- Review code for best practices
- Refactor for better readability
- Analyze time/space complexity of solutions
- Get optimization suggestions
- Understand algorithmic patterns
- Detect common vulnerabilities
- Find hardcoded secrets
- Review for injection risks
For microservices architecture or when you need to scale the backend separately:
# Start both API and Streamlit in API mode
docker-compose --profile api-mode up --build
# Or manually:
# Terminal 1: Start FastAPI
uvicorn src.backend.api:app --host 0.0.0.0 --port 8000
# Terminal 2: Start Streamlit in API mode
streamlit run src/streamlit_app.py -- --mode api --api-url http://localhost:8000| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Health check |
/models |
GET | List available models |
/explain |
POST | Generate code explanation |
/analyze-complexity |
POST | Analyze time/space complexity |
/check-security |
POST | Security vulnerability scan |
/review-practices |
POST | Best practices review |
/generate-docstring |
POST | Generate documentation |
/generate-flowchart |
POST | Generate Mermaid flowchart |
/refactor |
POST | Suggest refactoring |
/chat |
POST | Interactive Q&A |
API documentation available at /docs when running in API mode.
- ✅ No Code Execution: This tool only analyzes code, never runs it
- ✅ No Storage: Code is sent to Groq's API but not stored permanently
- ✅ Input Limits: Configurable limits on code size to prevent abuse
- ✅ API Key Protection: Keys stored securely, never exposed in UI
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Groq for blazing-fast LLM inference
- Streamlit for the amazing web framework
- FastAPI for the robust API framework
- Hugging Face for hosting and deployment
Built with ❤️ using Streamlit and Groq AI
GitHub • Demo • Get API Key