README.md

metadata

title: AI Concept Explainer
emoji: 🧠
colorFrom: indigo
colorTo: gray
sdk: docker
pinned: false
license: mit
short_description: AI-powered concept explainer with adaptive complexity

🧠 AI Concept Explainer v2.0

A clean, Gradio app that explains any concept at different complexity levels using OpenAI's GPT-4.1-mini. Get personalized explanations tailored to your understanding level and preferred language, with a modern interface optimized for ease of use.

✨ Features

🎓 Core Functionality

• 5 Complexity Levels: From "like I'm 5" to expert-level explanations
• 6 Languages: English, Russian, German, Spanish, French, Italian
• Real-time Streaming: Watch explanations generate live with streaming responses
• Quick Examples: 3 pre-selected questions to get started instantly

🎨 Professional UI/UX

• Compact Design: Clean layout that fits on one screen without scrolling
• Modern Gradient Header: Beautiful purple gradient with professional styling
• Dark/Light Mode: Automatic theme detection with smooth transitions
• Responsive Layout: Optimized for desktop, tablet, and mobile (900px max-width)
• Smooth Animations: Entrance animations and hover effects throughout

🚀 Productivity Features

• 📋 Copy to Clipboard: One-click copy of any explanation
• 📖 Reading Time: Real-time reading time estimates as text streams
• ⌨️ Keyboard Shortcuts: Ctrl/Cmd+Enter to submit, Escape to clear
• 📊 Character Counter: Color-coded visual feedback (green/orange/red, 0/500 chars)
• 👍👎 Feedback: Simple helpful/not helpful reactions for continuous improvement
• 🔄 Clear Button: Quick reset to start fresh

🛡️ Code Quality & Reliability

• Type Hints: Full type annotations throughout the codebase
• Professional Logging: Structured logging system (not print statements)
• Error Handling: User-friendly error messages with collapsible technical details
• Input Validation: Character limits, language verification, and edge case handling
• Clean Architecture: Well-organized code with clear sections and documentation

🚀 Setup

Hugging Face Spaces

1. Fork or import this repository to your Hugging Face Space
2. Go to Settings → Repository secrets
3. Add secret: OPENAI_API_KEY with your OpenAI API key
4. The app will automatically deploy!

Local Development

# Clone and navigate to the project
cd Explainer_docker

# Create virtual environment (Python 3.11+)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set your API key
echo "OPENAI_API_KEY=your_api_key_here" > .env

# Run the app
python app.py

Visit http://127.0.0.1:7860 in your browser.

To stop: Press Ctrl+C in the terminal, then deactivate the virtual environment:

deactivate

Docker Deployment

# Create .env file with your API key
echo "OPENAI_API_KEY=your_key_here" > .env

# Build and run
docker-compose up --build

# Access at http://localhost:7860

To stop: Press Ctrl+C, then:

docker-compose down

🎮 How to Use

1. Click a quick example or enter your own question (up to 500 characters)
2. Adjust complexity level (1-5) using the slider to match your knowledge
3. Select your language from the dropdown (6 languages available)
4. Click "🚀 Explain Concept" or press Ctrl/Cmd + Enter (keyboard shortcut)
5. Watch the explanation stream in real-time with live reading time estimate
6. Copy to clipboard with one click for easy sharing
7. Give feedback with 👍 Helpful or 👎 Not Helpful to improve the app

📊 Complexity Levels Explained

Level	Description	Best For
1 🧒	Like I'm 5 - Simple words and analogies	Young learners, complete beginners
2 👦	Like I'm 10 - Basic concepts with examples	Elementary understanding
3 🎓	High school - Intermediate with technical terms	General audience (default)
4 🎯	College - Advanced concepts with details	Students and professionals
5 👨‍🔬	Expert - Professional depth and precision	Subject matter experts

🔧 Technical Stack

• Framework: Gradio 5.47.2 with custom theming
• AI Model: OpenAI GPT-4o-mini (optimized for quality and speed)
• Language: Python 3.11+ with type hints
• UI/UX: Custom CSS with Inter font, responsive design
• Features: Real-time streaming, session management, client-side interactivity
• Architecture: Modular code structure with proper separation of concerns

🔒 Security

• API keys stored as environment variables only
• No data persistence or storage
• Secure HTTPS API calls to OpenAI
• .env files are gitignored and never committed

📝 License

MIT License - Part of the LLM and Agentic AI Bootcamp Materials.

🎉 What's New in v2.0

✨ New Features

• ✅ Compact, professional header with beautiful gradient design
• ✅ Copy to clipboard - Share explanations with one click
• ✅ Real-time reading time - Know how long each explanation will take
• ✅ Character counter - Visual feedback with color coding (green/orange/red)
• ✅ 3 Quick examples - Get started instantly with pre-selected questions
• ✅ Keyboard shortcuts - Power user features (Ctrl/Cmd+Enter, Escape)
• ✅ User feedback system - 👍/👎 to help improve the experience
• ✅ Clear button - Quick reset to start fresh
• ✅ Enhanced error handling - Friendly messages with technical details for debugging

💻 Code Quality Improvements

• ✅ Full type hints - Complete type annotations throughout the codebase
• ✅ Professional logging - Structured logging system replacing print statements
• ✅ Modular organization - Clean code structure with clear sections
• ✅ Comprehensive documentation - Detailed docstrings for all functions
• ✅ Better error handling - Categorized errors with helpful user messages
• ✅ Input validation - Character limits, language verification, edge cases

🎨 UI/UX Enhancements

• ✅ One-screen design - Everything fits without scrolling for optimal UX
• ✅ Wider but shorter - 900px width, minimal vertical space
• ✅ Modern gradient header - Professional purple gradient (indigo to purple)
• ✅ Inter font - Modern, readable typography from Google Fonts
• ✅ Smooth animations - Entrance effects and hover transitions
• ✅ Enhanced dark mode - Automatic detection with beautiful themes
• ✅ Clean, focused layout - No sidebars, distractions, or clutter
• ✅ Responsive design - Works beautifully on desktop, tablet, and mobile

---

v2.0 • Built with ❤️ for learning • Get clear explanations for any concept! 🎯