README.md

---
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

```bash
# 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:
```bash
deactivate
```

### Docker Deployment

```bash
# 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:
```bash
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! 🎯