Deploy production-ready AI Concept Explainer with GPT-4.1-mini

.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+venv/
+env/
+ENV/
+adk_venv/
+.venv/
+
+# Environment files
+.env
+*.env
+api_keys.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*.code-workspace
+
+# Git
+.git/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Gradio
+.gradio/
+flagged/
+
+# Test files
+test_*.py
+test_docker.sh
+
+# Docker (not needed in HF Spaces)
+Dockerfile
+docker-compose.yml
+.dockerignore

README.md

@@ -8,192 +8,106 @@ sdk_version: "5.47.2"
 app_file: app.py
 pinned: false
 license: mit
-short_description: AI-powered concept explainer
+short_description: AI-powered concept explainer with adaptive complexity
 ---
 
 # 🧠 AI Concept Explainer
 
-An intelligent Gradio app that explains any concept at different complexity levels using OpenAI's GPT models. Get personalized explanations tailored to your understanding level and preferred language.
+An intelligent Gradio app that explains any concept at different complexity levels using OpenAI's GPT-4o-mini. Get personalized explanations tailored to your understanding level and preferred language.
 
 ## 🎯 Features
 
 - **Adaptive Complexity**: 5 levels from "like I'm 5" to expert-level explanations
 - **Multi-language Support**: English, Russian, German, Spanish, French, Italian
-- **Streaming Responses**: Real-time explanation generation
-- **Quick Examples**: Pre-loaded sample questions for instant testing
-- **Modern UI**: Clean, responsive interface with gradient styling
+- **Real-time Streaming**: Live explanation generation with streaming responses
+- **Modern UI**: Clean, responsive interface with dark/light mode support
 - **Error Handling**: Graceful API error management
 
-## 🚀 Quick Start
+## 🚀 Setup
 
-### Prerequisites
-- Python 3.7+
-- OpenAI API key
-- Gradio library
+### Hugging Face Spaces
 
-### Installation & Setup
+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!
 
-1. **Navigate to the project directory**:
-```bash
-cd gradio_concept_explainer
-```
+### Local Development
 
-2. **Activate the virtual environment**:
 ```bash
-source ../adk_venv/bin/activate
-```
+# Clone and navigate to the project
+cd Explainer_docker
 
-3. **Install dependencies**:
-```bash
-pip install gradio openai python-dotenv
+# 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
 ```
 
-4. **Set up your OpenAI API key**:
+Visit `http://127.0.0.1:7860` in your browser.
+
+**To stop**: Press `Ctrl+C` in the terminal, then deactivate the virtual environment:
 ```bash
-# Create or edit api_keys.env file
-echo "OPENAI_API_KEY=your_api_key_here" > ../api_keys.env
+deactivate
 ```
 
-5. **Run the application**:
+### Docker Deployment
+
 ```bash
-python app.py
-```
+# Create .env file with your API key
+echo "OPENAI_API_KEY=your_key_here" > .env
+
+# Build and run
+docker-compose up --build
 
-6. **Open your browser** and navigate to:
+# Access at http://localhost:7860
 ```
-http://127.0.0.1:7860
+
+**To stop**: Press `Ctrl+C`, then:
+```bash
+docker-compose down
 ```
 
 ## 🎮 How to Use
 
-1. **Enter your question** in the text box or click a quick example
+1. **Enter your question** or click a quick example
 2. **Select complexity level** (1-5) using the slider
 3. **Choose your language** from the dropdown
-4. **Click "Explain Concept"** to generate your personalized explanation
+4. **Click "Explain Concept"** to generate your explanation
 
 ### Complexity Levels
-- **Level 1**: Like I'm 5 years old - simple words and analogies
-- **Level 2**: Like I'm 10 years old - basic concepts with examples
-- **Level 3**: High school level - intermediate with some technical terms
-- **Level 4**: College level - advanced concepts with detailed explanations
-- **Level 5**: Expert level - professional depth with technical precision
-
-## 📋 Example Questions
 
-- "Why is the sky blue?"
-- "How does the internet work?"
-- "What is artificial intelligence?"
-- "Explain quantum computing"
-- "How do vaccines work?"
+- **Level 1**: Like I'm 5 - simple words and analogies
+- **Level 2**: Like I'm 10 - basic concepts with examples
+- **Level 3**: High school - intermediate with technical terms
+- **Level 4**: College - advanced concepts with details
+- **Level 5**: Expert - professional depth and precision
 
-## 🔧 Technical Details
+## 🔧 Technical Stack
 
-### Architecture
 - **Framework**: Gradio 5.47.2
-- **AI Model**: OpenAI GPT-4.1
-- **Language**: Python 3.7+
+- **AI Model**: OpenAI GPT-4o-mini
+- **Language**: Python 3.11+
 - **Streaming**: Real-time response generation
-- **Port**: localhost:7860
-
-### Key Functions
-
-#### `explain_concept(question, level, language)`
-Generates streaming explanations using OpenAI API.
-- **Parameters**: 
-  - `question` (str): Concept to explain
-  - `level` (int): Complexity level (1-5)
-  - `language` (str): Output language
-- **Returns**: Streaming explanation chunks
-- **Error Handling**: Graceful API error management
-
-### Environment Support
-- **Local Development**: Auto-opens browser, localhost only
-- **Hugging Face Spaces**: Production-ready configuration
-- **Signal Handling**: Graceful shutdown for development
-
-## 🎨 Interface Design
-
-- **Modern Theme**: Soft gradient styling
-- **Responsive Layout**: Works on all screen sizes
-- **Interactive Elements**: Sliders, dropdowns, example buttons
-- **Real-time Streaming**: Live explanation generation
-- **Accessible Design**: Clear labels and error messages
 
-## 🛠️ Customization
+## 🔒 Security
 
-### Adding New Languages
-```python
-LANGUAGES = ["English", "Russian", "German", "Spanish", "French", "Italian", "YourLanguage"]
-```
-
-### Modifying Complexity Levels
-```python
-EXPLANATION_LEVELS = {
-    1: "your custom level 1 description",
-    2: "your custom level 2 description",
-    # ... add more levels
-}
-```
-
-### Changing the AI Model
-```python
-stream = client.chat.completions.create(
-    model="gpt-3.5-turbo",  # Change model here
-    # ... rest of parameters
-)
-```
-
-## 🔒 Security & Privacy
-
-- **API Key Protection**: Environment variable storage
-- **Local Execution**: No data persistence
-- **Secure Requests**: HTTPS API calls to OpenAI
-- **No Data Storage**: Explanations not saved locally
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-1. **"OPENAI_API_KEY not found"**:
-```bash
-# Set your API key in api_keys.env
-echo "OPENAI_API_KEY=your_key_here" > ../api_keys.env
-```
-
-2. **"Module not found" errors**:
-```bash
-pip install gradio openai python-dotenv
-```
-
-3. **Port already in use**:
-```python
-# Change port in app.py
-server_port=7861
-```
-
-4. **API rate limits**:
-- Check your OpenAI usage limits
-- Consider upgrading your OpenAI plan
-
-## 📈 Future Enhancements
-
-- **Voice Output**: Text-to-speech for explanations
-- **Visual Diagrams**: Generate concept illustrations
-- **Explanation History**: Save and revisit past explanations
-- **Custom Prompts**: User-defined explanation styles
-- **Export Options**: Save explanations as PDF/Word
-- **Collaborative Features**: Share explanations with others
+- 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
 
-This project is part of the LLM and Agentic AI Bootcamp Materials.
-
-## 👥 Contributing
-
-This AI Concept Explainer is designed as a learning example. Feel free to:
-- Fork and modify for personal use
-- Use as a starting point for similar projects
-- Suggest improvements or additional features
+MIT License - Part of the LLM and Agentic AI Bootcamp Materials.
 
 ---
 

app.py

@@ -13,11 +13,14 @@ from openai import OpenAI
 from dotenv import load_dotenv
 
 # Load environment variables
-try:
-    load_dotenv('api_keys.env')
-except:
-    pass
-
+# For local development, try loading from .env files
+# For Hugging Face Spaces and Docker, env vars are set directly
+if not os.getenv("SPACE_ID"):  # Not in HF Spaces
+    try:
+        load_dotenv('.env')  # Try local .env first
+    except:
+        pass
+    
 # Initialize OpenAI client
 openai_api_key = os.getenv("OPENAI_API_KEY")
 if not openai_api_key:
@@ -97,18 +100,9 @@ def explain_concept(question, level, language):
         if "connection" in error_msg or "timeout" in error_msg or "ssl" in error_msg:
             yield f"""❌ **Connection Error**: Unable to reach OpenAI API.
 
-**On Hugging Face Spaces:**
-1. Verify `OPENAI_API_KEY` is set in **Settings → Repository secrets**
-2. Restart the Space after adding the secret
-3. Check the Logs tab for detailed error messages
-
 **Error details**: `{error_type}: {str(e)[:200]}`"""
         elif "api key" in error_msg or "authentication" in error_msg or "401" in error_msg:
-            yield """❌ **Authentication Error**: Invalid or missing API key.
-
-**Fix**: Go to **Settings → Repository secrets** and add:
-- Name: `OPENAI_API_KEY`
-- Value: Your OpenAI API key (starts with `sk-`)"""
+            yield """❌ **Authentication Error**: Invalid or missing API key."""
         elif "rate limit" in error_msg or "429" in error_msg:
             yield "❌ **Rate Limit**: Too many requests. Please wait a moment and try again."
         elif "model" in error_msg or "404" in error_msg:

requirements.txt

@@ -1,11 +1,5 @@
-# Python 3.12.11
-# Local versions:
-# gradio==5.46.0
-# openai==1.107.3
-# python-dotenv==1.1.1
-# httpx==0.27.0
-
-gradio
-openai
-python-dotenv
-httpx
+# Python 3.11+
+# Pinned versions for Docker reproducibility
+gradio==5.47.2
+openai==1.107.3
+python-dotenv==1.1.1