v2.5

.gitignore

@@ -4,42 +4,55 @@ __pycache__/
 *$py.class
 *.so
 .Python
-*.egg-info/
-dist/
-build/
-
-# Virtual environments
-.venv/
+env/
 venv/
 ENV/
-
-# Audio files (generated)
-audio/*.mp3
-audio/*.wav
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Audio files
+audio/
+*.mp3
+*.wav
+*.mp4
+*.part
 
 # Logs
-logs/*.log
+logs/
+*.log
 
 # User data
 user_data.json
 user_memory.json
+music_cache/
 
 # IDE
 .vscode/
 .idea/
 *.swp
 *.swo
+*~
 
 # OS
 .DS_Store
 Thumbs.db
 
-# Temporary files
-*.part
-*.tmp
-
-# ChromaDB
-chroma_db/
+# Environment
+.env
+.env.local
 
-# Music cache
-music_cache/
+# Gradio
+flagged/

DEPLOY_HF.md

@@ -0,0 +1,79 @@
+# Deploying to HuggingFace Spaces
+
+## Step-by-Step Guide
+
+### 1. Create a New Space
+
+1. Go to [HuggingFace Spaces](https://huggingface.co/spaces)
+2. Click "Create new Space"
+3. Fill in:
+   - **Space name**: `ai-radio` (or your preferred name)
+   - **SDK**: Select **Gradio**
+   - **Hardware**: CPU (or GPU if available)
+   - **Visibility**: Public or Private
+
+### 2. Configure Secrets
+
+After creating the Space, go to **Settings → Secrets** and add:
+
+| Secret Name | Value | Required |
+|------------|-------|----------|
+| `ELEVENLABS_API_KEY` | Your ElevenLabs API key | ✅ Yes |
+| `NEBIUS_API_KEY` | Your Nebius API key | ✅ Yes |
+| `LLAMAINDEX_API_KEY` | Your LlamaIndex API key | ⚠️ Optional |
+| `OPENAI_API_KEY` | Your OpenAI API key (for embeddings fallback) | ⚠️ Optional |
+
+### 3. Push Your Code
+
+You can either:
+
+**Option A: Git Push**
+```bash
+git remote add hf https://huggingface.co/spaces/<your-username>/<space-name>
+git push hf main
+```
+
+**Option B: Upload via Web UI**
+- Go to your Space page
+- Click "Files and versions"
+- Upload all files from your local `ai_radio` directory
+
+### 4. Required Files
+
+Make sure these files are in your Space repository:
+
+- ✅ `app.py` - Entry point (already created)
+- ✅ `requirements.txt` - Dependencies
+- ✅ `README.md` - Space description
+- ✅ `src/` - Source code directory
+- ✅ `.gitignore` - Git ignore rules
+
+### 5. Verify Deployment
+
+1. Check the **Logs** tab in your Space
+2. Wait for the build to complete
+3. The app should be available at: `https://huggingface.co/spaces/<your-username>/<space-name>`
+
+## Troubleshooting
+
+### Build Fails
+- Check that `requirements.txt` has all dependencies
+- Verify Python version compatibility (3.9+)
+- Check logs for specific error messages
+
+### App Doesn't Start
+- Verify all required secrets are set
+- Check that `app.py` is at the root level
+- Ensure port is set to 7860 (HF Spaces default)
+
+### API Errors
+- Double-check that API keys are correctly set as secrets
+- Verify API keys are valid and have sufficient credits/quota
+
+## Notes
+
+- The app uses port 7860 by default on HF Spaces (configured in `app.py`)
+- Audio files are stored temporarily in `audio/` directory
+- User data persists in `user_memory.json` and `user_data.json`
+- Logs are available in the Space's Logs tab
+

README.md

@@ -112,11 +112,33 @@ This app fulfills all requirements for **Track 2: MCP in Action**:
 
 ## 🚀 Getting Started
 
+### Option 1: Deploy to HuggingFace Spaces (Recommended) 🚀
+
+**Quick Deploy:**
+
+1. **Create a new Space** on [HuggingFace Spaces](https://huggingface.co/spaces)
+   - SDK: **Gradio**
+   - Hardware: **CPU** (or GPU if available)
+
+2. **Configure Secrets** (Settings → Secrets):
+   - `ELEVENLABS_API_KEY` - Your ElevenLabs API key
+   - `NEBIUS_API_KEY` - Your Nebius API key (for GPT-OSS-120B)
+   - `LLAMAINDEX_API_KEY` - Optional, for LlamaIndex embeddings
+   - `OPENAI_API_KEY` - Optional, for OpenAI embeddings fallback
+
+3. **Push your code** to the Space repository
+
+4. **Access your Space** at `https://huggingface.co/spaces/<username>/<space-name>`
+
+📖 **Detailed deployment guide**: See [DEPLOY_HF.md](DEPLOY_HF.md)
+
+### Option 2: Local Installation
+
 ### Prerequisites
 
 - Python 3.9+
 - Nebius API key (for GPT-OSS-120B LLM)
-- ElevenLabs API key (provided)
+- ElevenLabs API key
 
 ### Installation
 
@@ -131,9 +153,11 @@ cd ai_radio
 pip install -r requirements.txt
 ```
 
-3. Set up your Nebius API key in `config.py`:
-```python
-nebius_api_key: str = "your-nebius-api-key-here"
+3. Set up environment variables or edit `src/config.py`:
+```bash
+export ELEVENLABS_API_KEY="your-key-here"
+export NEBIUS_API_KEY="your-key-here"
+export LLAMAINDEX_API_KEY="your-key-here"
 ```
 
 4. Run the app:
@@ -141,11 +165,7 @@ nebius_api_key: str = "your-nebius-api-key-here"
 python run.py
 ```
 
-Or from the src directory:
-```bash
-cd src
-python app.py
-```
+The app will be available at `http://localhost:7871`
 
 5. Open your browser to `http://localhost:7871`
 

README_HF_SPACES.md

@@ -0,0 +1,50 @@
+# AI Radio - HuggingFace Spaces Deployment
+
+This is the deployment guide for hosting AI Radio on HuggingFace Spaces.
+
+## 🚀 Quick Start
+
+1. **Create a new Space** on HuggingFace Spaces
+   - Choose "Gradio" as the SDK
+   - Set the hardware to "CPU" (or "GPU" if available)
+
+2. **Configure Secrets** in your Space settings:
+   Go to Settings → Secrets and add the following:
+   - `ELEVENLABS_API_KEY` - Your ElevenLabs API key
+   - `NEBIUS_API_KEY` - Your Nebius API key (for GPT-OSS-120B)
+   - `LLAMAINDEX_API_KEY` - Your LlamaIndex API key (optional, for embeddings)
+   - `OPENAI_API_KEY` - Optional, for OpenAI embeddings fallback
+
+3. **Push your code** to the Space repository
+
+## 📁 File Structure
+
+The Space expects:
+- `app.py` - Entry point (already created)
+- `requirements.txt` - Python dependencies (already exists)
+- `src/` - Source code directory
+- `README.md` - This file (will be displayed on Space)
+
+## 🔧 Configuration
+
+API keys are loaded from environment variables (set as Secrets in HF Spaces):
+- `ELEVENLABS_API_KEY` - Required for text-to-speech
+- `NEBIUS_API_KEY` - Required for LLM (GPT-OSS-120B)
+- `LLAMAINDEX_API_KEY` - Optional, for LlamaIndex embeddings
+- `OPENAI_API_KEY` - Optional, for OpenAI embeddings fallback
+
+## 📝 Notes
+
+- The app will run on port 7860 (HF Spaces default)
+- Audio files are stored in `audio/` directory
+- User data is stored in `user_memory.json` and `user_data.json`
+- Logs are stored in `logs/` directory
+
+## 🐛 Troubleshooting
+
+If the app doesn't start:
+1. Check that all required secrets are set
+2. Check the logs in the Space
+3. Ensure `requirements.txt` has all dependencies
+4. Verify that `app.py` is at the root level
+

SECRETS_SETUP.md

@@ -0,0 +1,57 @@
+# 🔐 Настройка Secrets для HuggingFace Spaces
+
+## Необходимые Secrets
+
+Перейдите в **Settings → Secrets** вашего Space и добавьте следующие секреты:
+
+### Обязательные Secrets:
+
+1. **`ELEVENLABS_API_KEY`**
+   - Значение: Ваш API ключ от ElevenLabs
+   - Использование: Текст-в-речь (TTS)
+   - Где получить: https://elevenlabs.io/
+
+2. **`NEBIUS_API_KEY`**
+   - Значение: Ваш API ключ от Nebius
+   - Использование: LLM (GPT-OSS-120B) для генерации контента
+   - Где получить: https://nebius.com/
+
+### Опциональные Secrets:
+
+3. **`LLAMAINDEX_API_KEY`**
+   - Значение: Ваш API ключ от LlamaIndex
+   - Использование: Embeddings для RAG системы (если не используется локальный)
+   - Где получить: https://llamaindex.ai/
+   - Примечание: Если не указан, используется локальный sentence-transformers
+
+4. **`OPENAI_API_KEY`**
+   - Значение: Ваш API ключ от OpenAI
+   - Использование: Fallback для embeddings (если LlamaIndex недоступен)
+   - Где получить: https://platform.openai.com/
+   - Примечание: Опционально, используется только как fallback
+
+## Как добавить Secrets в HF Spaces:
+
+1. Откройте ваш Space: https://huggingface.co/spaces/MCP-1st-Birthday/AI-RADIO
+2. Перейдите в **Settings** (вкладка справа)
+3. Прокрутите до раздела **Secrets**
+4. Нажмите **"New secret"**
+5. Введите имя секрета (например, `ELEVENLABS_API_KEY`)
+6. Введите значение секрета
+7. Нажмите **"Add secret"**
+8. Повторите для всех необходимых секретов
+
+## Проверка:
+
+После добавления всех секретов:
+1. Перейдите во вкладку **Logs**
+2. Дождитесь перезапуска Space
+3. Проверьте логи на наличие предупреждений о недостающих ключах
+
+## Важно:
+
+- ✅ Все API ключи теперь читаются ТОЛЬКО из переменных окружения
+- ✅ Никакие ключи не хранятся в коде
+- ✅ Код безопасен для публичного репозитория
+- ⚠️ Убедитесь, что все необходимые секреты добавлены перед запуском
+

app.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""Entry point for HuggingFace Spaces deployment"""
+import sys
+import os
+
+# Add src directory to Python path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))
+
+# Import and run the app
+from app import demo
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,  # HF Spaces default port
+        share=False
+    )
+

docs/ARCHITECTURE.md

@@ -1,424 +0,0 @@
-# 🏗️ AI Radio - Architecture Documentation
-
-## System Overview
-
-AI Radio is built with a modular, agent-based architecture that demonstrates autonomous behavior, tool use via MCP servers, and intelligent personalization through RAG.
-
-## 📐 Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Gradio UI Layer                       │
-│  (Radio Player, Preferences, Stats, Controls)                │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-┌──────────────────────▼──────────────────────────────────────┐
-│                     Radio Agent                              │
-│  (Autonomous Planning, Reasoning, Execution)                 │
-│                                                              │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │  Agent Core                                          │   │
-│  │  • plan_radio_show()  - Planning                    │   │
-│  │  • execute_segment()   - Execution                  │   │
-│  │  • _generate_*()       - Reasoning                  │   │
-│  └─────────────────────────────────────────────────────┘   │
-└──────┬──────────────┬──────────────┬──────────────┬─────────┘
-       │              │              │              │
-       │              │              │              │
-┌──────▼──────┐ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
-│   Music     │ │   News    │ │  Podcast  │ │    RAG    │
-│ MCP Server  │ │MCP Server │ │MCP Server │ │  System   │
-│             │ │           │ │           │ │           │
-│ • search_   │ │ • fetch_  │ │ • get_    │ │• store_   │
-│   music     │ │   news    │ │   podcasts│ │  prefs    │
-│ • get_      │ │ • get_    │ │ • get_    │ │• get_     │
-│   playlist  │ │   personl │ │   personl │ │  recom    │
-└─────────────┘ └───────────┘ └───────────┘ └─────┬─────┘
-                                                   │
-                                            ┌──────▼──────┐
-                                            │ LlamaIndex  │
-                                            │Vector Store │
-                                            └─────────────┘
-       │                    │
-┌──────▼──────┐      ┌──────▼──────┐
-│   Gemini    │      │ ElevenLabs  │
-│    LLM      │      │    TTS      │
-│             │      │             │
-│ • Content   │      │ • Voice     │
-│   Gen       │      │   Gen       │
-│ • Host      │      │ • Speech    │
-│   Scripts   │      │   Synth     │
-└─────────────┘      └─────────────┘
-```
-
-## 🧩 Component Details
-
-### 1. **Gradio UI Layer**
-
-**File**: `app.py`
-
-**Responsibilities**:
-- User interface for radio player
-- Preference collection
-- Statistics display
-- Playback controls
-
-**Key Features**:
-- Responsive design with custom CSS
-- Real-time updates
-- Audio player integration
-- Multi-tab layout
-
-### 2. **Radio Agent (Autonomous Agent)**
-
-**File**: `radio_agent.py`
-
-**Responsibilities**:
-- **Planning**: Create personalized radio show plans
-- **Reasoning**: Make intelligent content decisions
-- **Execution**: Generate and deliver content
-- **Learning**: Store listening history
-
-**Agent Behaviors**:
-
-#### Planning
-```python
-plan_radio_show(user_preferences, duration_minutes)
-├── Load user preferences from RAG
-├── Calculate segment distribution
-├── Generate segment plan
-│   ├── Music segments (50%)
-│   ├── News segments (20%)
-│   ├── Podcast segments (20%)
-│   └── Story segments (10%)
-├── Shuffle for variety
-└── Return structured plan
-```
-
-#### Reasoning
-- Analyzes user mood and preferences
-- Selects appropriate content from MCP servers
-- Generates contextual commentary
-- Adapts to user feedback (via RAG)
-
-#### Execution
-- Executes each segment in sequence
-- Calls MCP servers for content
-- Generates TTS for host commentary
-- Logs to RAG system for learning
-
-### 3. **MCP Servers (Tool Layer)**
-
-MCP (Model Context Protocol) servers provide structured, modular tools for the agent.
-
-#### Music MCP Server
-**File**: `mcp_servers/music_server.py`
-
-**Tools**:
-- `search_music(genre, mood, limit)`: Find music tracks
-- `get_personalized_playlist(user_preferences)`: Generate playlists
-
-**Features**:
-- Multi-genre support
-- Mood-based filtering
-- Demo tracks (expandable to real APIs)
-
-#### News MCP Server
-**File**: `mcp_servers/news_server.py`
-
-**Tools**:
-- `fetch_news(category, limit)`: Fetch latest news
-- `get_personalized_news(user_preferences)`: Curate news
-
-**Features**:
-- RSS feed integration
-- Multiple categories
-- Real-time updates
-- Fallback demo content
-
-#### Podcast MCP Server
-**File**: `mcp_servers/podcast_server.py`
-
-**Tools**:
-- `get_trending_podcasts(category, limit)`: Find podcasts
-- `get_personalized_podcasts(user_preferences)`: Recommend podcasts
-
-**Features**:
-- Category-based search
-- Ratings and metadata
-- Demo content (expandable)
-
-### 4. **RAG System**
-
-**File**: `rag_system.py`
-
-**Powered by**: LlamaIndex + Gemini Embeddings
-
-**Responsibilities**:
-- Store user preferences
-- Track listening history
-- Generate recommendations
-- Provide context to agent
-
-**Data Storage**:
-```json
-{
-  "type": "preferences",
-  "timestamp": "2025-11-27T...",
-  "data": {
-    "name": "User",
-    "favorite_genres": ["pop", "rock"],
-    "interests": ["technology"],
-    "mood": "happy"
-  }
-}
-```
-
-**Vector Store**:
-- Uses Gemini embeddings
-- Semantic search over user data
-- Persistent storage in JSON
-
-### 5. **TTS Service**
-
-**File**: `tts_service.py`
-
-**Powered by**: ElevenLabs
-
-**Responsibilities**:
-- Convert text to natural speech
-- Support multiple voices
-- Generate high-quality audio
-- Save audio files
-
-**Features**:
-- Streaming support
-- Voice selection
-- Error handling
-- File management
-
-### 6. **Configuration**
-
-**File**: `config.py`
-
-**Contains**:
-- API keys (with environment variable support)
-- Radio station settings
-- Segment ratios
-- Voice configuration
-
-## 🔄 Data Flow
-
-### 1. User Sets Preferences
-```
-User Input → Gradio UI → save_preferences()
-                              ↓
-                         RAG System
-                              ↓
-                    Store in Vector Index
-```
-
-### 2. Starting Radio
-```
-Start Button → start_radio_stream()
-                    ↓
-              RadioAgent.plan_radio_show()
-                    ↓
-        ┌───────────┴───────────┐
-        ↓                       ↓
-   Query RAG           Use MCP Servers
-        ↓                       ↓
-   Get Preferences      Get Content
-        ↓                       ↓
-        └───────────┬───────────┘
-                    ↓
-            Generate Show Plan
-                    ↓
-             Return Segments
-```
-
-### 3. Playing Segment
-```
-play_next_segment()
-        ↓
-execute_segment()
-        ↓
-   ┌────┴────┐
-   ↓         ↓
-Generate  Call MCP
-  Text    Server
-   ↓         ↓
-   └────┬────┘
-        ↓
-   TTS Service
-        ↓
-   Audio File
-        ↓
-  Gradio Audio Player
-        ↓
-   User Hears
-```
-
-### 4. Learning Loop
-```
-User Listens → execute_segment()
-                      ↓
-           Store in RAG (history)
-                      ↓
-              Update Preferences
-                      ↓
-         Future Recommendations Improve
-```
-
-## 🎯 Autonomous Agent Behavior
-
-The RadioAgent demonstrates three key autonomous behaviors:
-
-### 1. **Planning**
-- Analyzes user preferences and context
-- Creates a balanced, engaging show structure
-- Considers segment variety and flow
-- Adapts to show duration
-
-### 2. **Reasoning**
-- Uses LLM to generate contextual content
-- Makes intelligent content selections
-- Balances user preferences with variety
-- Generates natural host commentary
-
-### 3. **Execution**
-- Calls appropriate MCP tools
-- Generates TTS for speech
-- Manages playback flow
-- Logs for future learning
-
-## 🔧 MCP Tool Integration
-
-All MCP servers follow a consistent pattern:
-
-```python
-class MCPServer:
-    def __init__(self):
-        self.name = "server_name"
-        self.description = "Server description"
-    
-    def tool_function(self, params):
-        """Tool implementation"""
-        return results
-    
-    def get_tools_definition(self):
-        """Return MCP tool schema"""
-        return [
-            {
-                "name": "tool_name",
-                "description": "What it does",
-                "parameters": { ... }
-            }
-        ]
-```
-
-This standardization allows:
-- Easy tool discovery
-- Consistent invocation
-- Simple extension
-- Clear documentation
-
-## 💡 Context Engineering
-
-The agent uses context engineering to:
-
-1. **Personalize Content**:
-   - Passes user preferences to all LLM calls
-   - Includes mood and interests in prompts
-   - Maintains conversation continuity
-
-2. **Generate Natural Speech**:
-   - Creates prompts that mimic radio DJ style
-   - Ensures appropriate tone and energy
-   - Keeps content concise for audio
-
-3. **Adapt to User**:
-   - Uses RAG to retrieve relevant history
-   - Considers past feedback
-   - Improves over time
-
-## 🚀 Scalability Considerations
-
-### Current Design
-- Demo content for quick deployment
-- In-memory vector store
-- Local file storage
-
-### Production Ready
-- Replace demo content with real APIs:
-  - Spotify/Apple Music API
-  - NewsAPI.org
-  - iTunes Podcast API
-- Use persistent vector store (Pinecone, Weaviate)
-- Cloud storage for audio files
-- Distributed architecture
-
-## 📊 Performance
-
-### Efficiency Features
-- **Lazy Loading**: TTS only generates when needed
-- **Caching**: Store generated audio
-- **Streaming**: Stream audio for large files
-- **Batching**: Process segments in batches
-
-### Cost Optimization
-- **Conditional Generation**: Only generate TTS for host segments
-- **Reuse Content**: Cache common segments
-- **Efficient Prompts**: Minimize LLM token usage
-- **Smart Planning**: Balance content types
-
-## 🔐 Security
-
-- API keys stored in config (can use env vars)
-- No user data sent to external services (except APIs)
-- Local storage of preferences
-- Sandboxed execution
-
-## 🧪 Testing Strategy
-
-### Unit Tests
-- Test each MCP server independently
-- Test RAG storage and retrieval
-- Test TTS generation
-- Test agent planning logic
-
-### Integration Tests
-- Test full show generation
-- Test UI interactions
-- Test audio playback
-- Test preference persistence
-
-### User Acceptance
-- Test with real users
-- Gather feedback on content quality
-- Measure engagement
-- Iterate on improvements
-
-## 📈 Future Enhancements
-
-1. **Multi-language Support**: TTS in multiple languages
-2. **Live Streaming**: Real-time audio streaming
-3. **Social Features**: Share shows with friends
-4. **Advanced Personalization**: Deep learning recommendations
-5. **Voice Commands**: Control radio with voice
-6. **Mobile App**: Native mobile experience
-7. **Offline Mode**: Download shows for offline listening
-8. **Community Content**: User-generated segments
-
-## 🎓 Learning Resources
-
-- [MCP Documentation](https://modelcontextprotocol.io/)
-- [Gradio Docs](https://www.gradio.app/docs)
-- [LlamaIndex Guide](https://docs.llamaindex.ai/)
-- [Gemini API](https://ai.google.dev/)
-- [ElevenLabs API](https://elevenlabs.io/docs)
-
----
-
-Built with ❤️ for the MCP 1st Birthday Competition
-

docs/DEPLOYMENT.md

@@ -1,381 +0,0 @@
-# 🚀 AI Radio - Deployment Guide
-
-Complete guide for deploying AI Radio to HuggingFace Spaces for the MCP Competition.
-
-## 📋 Pre-Deployment Checklist
-
-Before deploying, ensure you have:
-- ✅ All source files in the `ai_radio` folder
-- ✅ Google Gemini API key
-- ✅ HuggingFace account (free)
-- ✅ Tested the app locally
-
-## 🌐 HuggingFace Spaces Deployment
-
-### Method 1: Web Upload (Easiest)
-
-#### Step 1: Create Space
-
-1. Go to https://huggingface.co/spaces
-2. Click "Create new Space"
-3. Fill in details:
-   - **Owner**: Your username
-   - **Space name**: `ai-radio` (or your choice)
-   - **License**: MIT
-   - **Select SDK**: Gradio
-   - **SDK version**: 4.44.0
-   - **Space hardware**: CPU basic (free tier)
-   - **Visibility**: Public
-4. Click "Create Space"
-
-#### Step 2: Prepare Files
-
-Ensure your folder has these files:
-```
-ai_radio/
-├── app.py                 # Main application
-├── config.py              # Configuration
-├── requirements.txt       # Dependencies
-├── README.md             # Project documentation
-├── radio_agent.py        # AI Agent
-├── rag_system.py         # RAG system
-├── tts_service.py        # Text-to-speech
-├── demo_assets.py        # Demo data
-├── mcp_servers/
-│   ├── __init__.py
-│   ├── music_server.py
-│   ├── news_server.py
-│   └── podcast_server.py
-├── .gitignore
-├── LICENSE
-├── QUICKSTART.md
-├── SETUP_GUIDE.md
-└── ARCHITECTURE.md
-```
-
-#### Step 3: Upload Files
-
-1. In your new Space, click "Files" tab
-2. Click "Add file" → "Upload files"
-3. Drag and drop ALL files from the list above
-4. Or upload folder by folder:
-   - First, upload root files
-   - Then create `mcp_servers` folder and upload its contents
-5. Add commit message: "Initial deployment of AI Radio"
-6. Click "Commit changes to main"
-
-#### Step 4: Configure Secrets
-
-1. Go to "Settings" tab in your Space
-2. Scroll to "Repository secrets"
-3. Click "New secret"
-4. Add your Gemini API key:
-   - **Name**: `GOOGLE_API_KEY`
-   - **Value**: Your actual Gemini API key
-   - Click "Add"
-
-#### Step 5: Wait for Build
-
-1. Go to "App" tab
-2. HuggingFace will automatically:
-   - Install dependencies from `requirements.txt`
-   - Build the container
-   - Start the app
-3. Wait 3-5 minutes
-4. Your app will be live!
-
-#### Step 6: Test Deployment
-
-1. Once running, test the app:
-   - Set preferences
-   - Start radio
-   - Check if audio plays
-   - Verify all tabs work
-2. If errors, check the "Logs" section
-
-### Method 2: Git Push (Advanced)
-
-#### Prerequisites
-```bash
-# Install git-lfs
-brew install git-lfs  # macOS
-# or
-apt-get install git-lfs  # Linux
-
-git lfs install
-```
-
-#### Steps
-
-1. **Clone your Space**:
-```bash
-git clone https://huggingface.co/spaces/YOUR_USERNAME/ai-radio
-cd ai-radio
-```
-
-2. **Copy files**:
-```bash
-# Copy all files from your local project
-cp -r ~/Desktop/ai_radio/* .
-```
-
-3. **Configure git** (if not already done):
-```bash
-git config user.email "your.email@example.com"
-git config user.name "Your Name"
-```
-
-4. **Commit and push**:
-```bash
-git add .
-git commit -m "Initial deployment of AI Radio for MCP Competition"
-git push
-```
-
-5. **Set secrets** via web interface (see Method 1, Step 4)
-
-## 🏷️ Competition Tagging
-
-Your `README.md` already includes the correct tags for the competition:
-
-```yaml
-tags:
-  - mcp
-  - mcp-in-action-track-consumer
-  - hackathon
-```
-
-This ensures your submission is properly categorized!
-
-## 🔍 Verification
-
-After deployment, verify:
-
-### ✅ App Functionality
-- [ ] App loads without errors
-- [ ] Can save preferences
-- [ ] Radio starts and plays
-- [ ] Audio generates (TTS works)
-- [ ] Stats page shows data
-- [ ] All tabs are accessible
-
-### ✅ MCP Features
-- [ ] Music server provides tracks
-- [ ] News server fetches updates
-- [ ] Podcast server gives recommendations
-- [ ] Agent plans shows autonomously
-- [ ] RAG system stores preferences
-
-### ✅ Competition Requirements
-- [ ] Tagged with `mcp-in-action-track-consumer`
-- [ ] README explains MCP usage
-- [ ] Demonstrates autonomous behavior
-- [ ] Uses MCP servers as tools
-- [ ] Gradio interface works
-- [ ] RAG system functional
-
-## 🐛 Common Deployment Issues
-
-### Issue 1: Dependencies Not Installing
-
-**Error**: `ModuleNotFoundError`
-
-**Solution**:
-- Ensure `requirements.txt` is in root directory
-- Check package names are correct
-- Try specifying versions more loosely:
-  ```
-  gradio>=4.44.0
-  google-generativeai>=0.8.0
-  ```
-
-### Issue 2: Secrets Not Loading
-
-**Error**: `API key not found`
-
-**Solution**:
-- Verify secret name is exactly `GOOGLE_API_KEY`
-- Check secret is added to the Space (not repository)
-- Restart the Space after adding secrets
-
-### Issue 3: Audio Not Playing
-
-**Error**: No audio output
-
-**Solutions**:
-- Check ElevenLabs API key in `config.py`
-- Verify TTS service initializes correctly
-- Check logs for ElevenLabs errors
-- Test with demo mode (without TTS)
-
-### Issue 4: Out of Memory
-
-**Error**: Container crashes
-
-**Solution**:
-- Upgrade to better hardware tier (Settings → Hardware)
-- Optimize memory usage:
-  - Reduce batch sizes
-  - Clear old audio files
-  - Use streaming instead of loading all at once
-
-### Issue 5: Slow Performance
-
-**Symptoms**: App is sluggish
-
-**Solutions**:
-- Upgrade Space hardware
-- Implement caching for frequently used content
-- Reduce number of segments
-- Optimize LLM prompts
-
-## 📊 Monitoring Your Space
-
-### View Logs
-1. Go to your Space
-2. Click on the running app area
-3. Look for "View Logs" or similar
-4. Monitor for errors
-
-### Check Usage
-1. Settings → Usage
-2. Monitor:
-   - API calls
-   - Memory usage
-   - CPU usage
-   - Storage
-
-### Analytics
-1. Settings → Analytics
-2. See:
-   - Number of visitors
-   - Session duration
-   - Popular features
-
-## 🔄 Updating Your Space
-
-### Quick Updates
-1. Go to Files tab
-2. Click on file to edit
-3. Make changes
-4. Commit
-5. Space rebuilds automatically
-
-### Batch Updates
-1. Use git method to push multiple changes
-2. Or upload files again via web interface
-
-## 🎯 Competition Submission
-
-### Final Steps
-
-1. **Verify README**:
-   - Has competition tags
-   - Explains MCP integration
-   - Includes demo instructions
-   - Lists all features
-
-2. **Test thoroughly**:
-   - Try all features
-   - Check error handling
-   - Verify user experience
-
-3. **Document**:
-   - Clear setup instructions
-   - Architecture explanation
-   - MCP server details
-
-4. **Share**:
-   - Get the Space URL
-   - Submit to competition
-   - Share on social media!
-
-### Submission Checklist
-
-- [ ] Space is public
-- [ ] App runs without errors
-- [ ] README has correct tags
-- [ ] All MCP features demonstrated
-- [ ] RAG system working
-- [ ] UI is polished
-- [ ] Documentation complete
-
-## 🎨 Polish Your Space
-
-### Custom Thumbnail
-1. Create a 1200x400px image
-2. Upload as `thumbnail.png`
-3. It will show in Space preview
-
-### Better Description
-Edit README to add:
-- Demo GIF/video
-- Feature highlights
-- Screenshots
-- Competition hashtags
-
-### Social Media
-Share your Space:
-```
-🎵 Just built AI Radio for #MCP1stBirthday! 
-
-Personalized radio with:
-🤖 Autonomous AI agent
-🎶 Smart music selection
-📰 Custom news
-🎙️ Podcast recommendations
-
-Try it: https://huggingface.co/spaces/YOUR_USERNAME/ai-radio
-
-#MCP #AI #Gradio #HuggingFace
-```
-
-## 📈 Optimization Tips
-
-### For Free Tier
-- Use CPU efficiently
-- Cache generated content
-- Limit concurrent users
-- Optimize model calls
-
-### For Better UX
-- Add loading indicators
-- Show progress bars
-- Provide helpful error messages
-- Add tooltips and hints
-
-### For Demo
-- Preload sample data
-- Have demo preferences ready
-- Show example outputs
-- Guide first-time users
-
-## 🏆 Making Your Submission Stand Out
-
-1. **Demo Video**: Record a quick demo showing features
-2. **Clear Documentation**: Make README super clear
-3. **Polish UI**: Beautiful, intuitive interface
-4. **Smooth Experience**: Test thoroughly, fix bugs
-5. **Showcase MCP**: Clearly demonstrate MCP integration
-6. **Highlight RAG**: Show how personalization works
-7. **Agent Behavior**: Explain autonomous planning/reasoning
-
-## 🎉 Launch!
-
-Once everything is ready:
-
-1. ✅ Test one final time
-2. ✅ Check all documentation
-3. ✅ Verify tags are correct
-4. ✅ Share your Space URL
-5. ✅ Submit to competition
-6. 🎊 Celebrate!
-
-Your AI Radio is now live and ready for the MCP Competition!
-
----
-
-**Good luck with your submission!** 🍀
-
-Made with ❤️ for MCP 1st Birthday Competition
-

docs/GET_GEMINI_KEY.md

@@ -1,178 +0,0 @@
-# 🔑 How to Get Your Gemini API Key
-
-## Why You Need It
-
-AI Radio uses Google's Gemini LLM to:
-- Generate radio host commentary
-- Create news scripts
-- Write stories and fun facts
-- Power the autonomous agent's reasoning
-
-**This is the ONLY key you need to add yourself!**
-
-## 📝 Step-by-Step Guide
-
-### Step 1: Go to Google AI Studio
-
-Open your browser and go to:
-```
-https://makersuite.google.com/app/apikey
-```
-
-Or Google search for: "Google AI Studio API key"
-
-### Step 2: Sign In
-
-- Sign in with your Google account
-- Any Google account works (Gmail, workspace, etc.)
-- It's completely FREE!
-
-### Step 3: Create API Key
-
-1. Click the **"Create API Key"** button
-2. Choose **"Create API key in new project"** (recommended)
-3. Wait a few seconds for it to generate
-4. Your API key will appear - it looks like:
-   ```
-   AIzaSyA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q
-   ```
-
-### Step 4: Copy Your Key
-
-1. Click the **copy icon** next to your key
-2. Or manually select and copy the entire key
-3. **Keep it safe!** Don't share publicly
-
-### Step 5: Add to Config
-
-Open `config.py` in your editor and find this line:
-
-```python
-google_api_key: str = ""
-```
-
-Replace it with:
-
-```python
-google_api_key: str = "AIzaSyA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q"
-```
-
-(Use your actual key, not the example above!)
-
-### Step 6: Save and Test
-
-1. Save the `config.py` file
-2. Run the test script:
-   ```bash
-   python test_app.py
-   ```
-3. If you see "✅ Google API key present" - you're good to go!
-
-## Alternative: Environment Variable
-
-Instead of editing `config.py`, you can set an environment variable:
-
-### macOS/Linux:
-```bash
-export GOOGLE_API_KEY="your-key-here"
-python app.py
-```
-
-### Windows (PowerShell):
-```powershell
-$env:GOOGLE_API_KEY="your-key-here"
-python app.py
-```
-
-### Windows (CMD):
-```cmd
-set GOOGLE_API_KEY=your-key-here
-python app.py
-```
-
-## 🔒 Security Tips
-
-1. **Never commit API keys to git**
-   - They're in `.gitignore` for safety
-   - Config file with key won't be pushed
-
-2. **Don't share publicly**
-   - Don't post in forums, Discord, etc.
-   - Don't include in screenshots
-
-3. **Regenerate if exposed**
-   - If you accidentally share it, regenerate in AI Studio
-   - Old key will stop working
-
-4. **Monitor usage**
-   - Check Google AI Studio for usage stats
-   - Free tier is generous (lots of requests)
-
-## 🎁 Free Tier
-
-Gemini API free tier includes:
-- **60 requests per minute**
-- **1,500 requests per day**
-- Plenty for personal use and demos!
-
-No credit card required for free tier.
-
-## ❓ Troubleshooting
-
-### "API key not valid"
-- Make sure you copied the entire key
-- Check for extra spaces before/after
-- Verify it's the Gemini API key, not other Google API
-
-### "Quota exceeded"
-- You've hit the free tier limit
-- Wait for the quota to reset (daily)
-- Or upgrade to paid tier in AI Studio
-
-### "API not enabled"
-- Go to Google Cloud Console
-- Enable "Generative Language API"
-- Try again
-
-### Still having issues?
-- Try creating a new API key
-- Check Google AI Studio status page
-- Make sure your Google account is active
-
-## 🌐 For HuggingFace Deployment
-
-When deploying to HuggingFace Spaces:
-
-1. **Don't include key in code**
-2. Go to Space Settings → Secrets
-3. Add secret:
-   - Name: `GOOGLE_API_KEY`
-   - Value: Your Gemini API key
-4. App will load it automatically
-
-## ✅ Verification
-
-Your key is working if:
-- ✅ Test script passes
-- ✅ Radio generates commentary
-- ✅ News scripts are created
-- ✅ Stories are generated
-- ✅ No "API key" errors in logs
-
-## 🎉 You're All Set!
-
-Once you have your Gemini API key:
-1. ✅ Add it to `config.py` or environment variable
-2. ✅ Run `python test_app.py` to verify
-3. ✅ Start the app with `python app.py`
-4. 🎵 Enjoy your AI Radio!
-
----
-
-**Quick Links:**
-- [Google AI Studio](https://makersuite.google.com/app/apikey)
-- [Gemini API Docs](https://ai.google.dev/tutorials)
-- [Pricing Info](https://ai.google.dev/pricing)
-
-Need help? Check SETUP_GUIDE.md for more details!
-

docs/INSTALL_FFMPEG.md

@@ -1,52 +0,0 @@
-# 🎵 Installing FFmpeg for Music Playback
-
-FFmpeg is required to download and convert YouTube audio for playback in the app.
-
-## macOS Installation
-
-```bash
-brew install ffmpeg
-```
-
-## Linux Installation
-
-```bash
-# Ubuntu/Debian
-sudo apt-get update
-sudo apt-get install ffmpeg
-
-# Fedora/CentOS
-sudo dnf install ffmpeg
-
-# Arch Linux
-sudo pacman -S ffmpeg
-```
-
-## Windows Installation
-
-1. Download from: https://ffmpeg.org/download.html
-2. Extract to a folder (e.g., `C:\ffmpeg`)
-3. Add to PATH:
-   - System Properties → Environment Variables
-   - Add `C:\ffmpeg\bin` to Path
-
-## Verify Installation
-
-```bash
-ffmpeg -version
-```
-
-You should see version information if installed correctly.
-
-## Alternative: Use YouTube Links
-
-If you can't install ffmpeg, the app will still work! It will:
-- Show track information
-- Provide YouTube links to listen
-- All other features work normally
-- Music just won't play directly in the app
-
-## Note
-
-FFmpeg is only needed for downloading YouTube audio. All other features (host speech, news, podcasts, stories) work without it!
-

docs/INSTALL_VOICE_INPUT.md

@@ -1,82 +0,0 @@
-# 🎤 Voice Input Installation Guide
-
-The voice input feature requires `pyaudio`, which needs the PortAudio library to be installed first.
-
-## macOS Installation
-
-1. **Install PortAudio using Homebrew:**
-   ```bash
-   brew install portaudio
-   ```
-
-2. **Install pyaudio:**
-   ```bash
-   pip install pyaudio
-   ```
-
-## Linux Installation
-
-1. **Install PortAudio development libraries:**
-   ```bash
-   sudo apt-get update
-   sudo apt-get install portaudio19-dev python3-pyaudio
-   ```
-
-   Or for other distributions:
-   ```bash
-   # Fedora/CentOS
-   sudo dnf install portaudio-devel
-   
-   # Arch Linux
-   sudo pacman -S portaudio
-   ```
-
-2. **Install pyaudio:**
-   ```bash
-   pip install pyaudio
-   ```
-
-## Windows Installation
-
-1. **Download and install PortAudio:**
-   - Download from: http://files.portaudio.com/download.html
-   - Or use pre-built wheels:
-   ```bash
-   pip install pipwin
-   pipwin install pyaudio
-   ```
-
-## Alternative: Use Text Input
-
-If you can't install pyaudio, you can still use the app! The voice input feature will be disabled, but you can:
-- Type your song requests in the preferences
-- Use the regular radio controls
-- All other features work without voice input
-
-## Verify Installation
-
-After installing, test with:
-```bash
-python -c "import speech_recognition as sr; print('✅ Speech recognition ready!')"
-python -c "import pyaudio; print('✅ PyAudio ready!')"
-```
-
-## Troubleshooting
-
-**Error: "portaudio.h not found"**
-- Make sure PortAudio is installed before pyaudio
-- On macOS, use Homebrew: `brew install portaudio`
-
-**Error: "No module named 'pyaudio'"**
-- Install pyaudio: `pip install pyaudio`
-- Make sure PortAudio is installed first
-
-**Microphone not detected**
-- Check microphone permissions in system settings
-- On macOS: System Settings → Privacy & Security → Microphone
-- Make sure your app has microphone access
-
-## Note
-
-Voice input is **optional**. The app works perfectly without it - you just won't be able to request songs by voice. All other features (radio, music, news, etc.) work normally.
-

docs/PROJECT_OVERVIEW.txt

@@ -1,356 +0,0 @@
-================================================================================
-                    🎵 AI RADIO - PROJECT COMPLETE! 🎵
-================================================================================
-
-Congratulations! Your personalized AI Radio Station is ready for the 
-MCP 1st Birthday Competition!
-
-================================================================================
-                           📦 WHAT YOU HAVE
-================================================================================
-
-A complete, production-ready AI Radio application featuring:
-
-✅ Autonomous AI Agent (planning, reasoning, execution)
-✅ 3 MCP Servers (music, news, podcasts) 
-✅ RAG System (LlamaIndex) for personalization
-✅ Beautiful Gradio UI (radio station theme)
-✅ ElevenLabs TTS (natural voice)
-✅ Google Gemini LLM (content generation)
-✅ Comprehensive documentation
-✅ Test suite
-✅ HuggingFace deployment ready
-
-================================================================================
-                          📁 PROJECT STRUCTURE
-================================================================================
-
-ai_radio/
-├── 🚀 MAIN APPLICATION
-│   ├── app.py                    # Main Gradio app (run this!)
-│   ├── config.py                 # Configuration (ADD YOUR GEMINI KEY!)
-│   ├── radio_agent.py            # Autonomous AI agent
-│   ├── rag_system.py             # RAG system with LlamaIndex
-│   ├── tts_service.py            # ElevenLabs TTS integration
-│   └── demo_assets.py            # Sample data
-│
-├── 🔧 MCP SERVERS (Tools)
-│   ├── mcp_servers/
-│   │   ├── __init__.py
-│   │   ├── music_server.py       # Music search & playlists
-│   │   ├── news_server.py        # News fetching & curation
-│   │   └── podcast_server.py     # Podcast recommendations
-│
-├── 📚 DOCUMENTATION
-│   ├── START_HERE.md             # 👈 READ THIS FIRST!
-│   ├── README.md                 # Full project documentation
-│   ├── QUICKSTART.md             # 5-minute setup guide
-│   ├── GET_GEMINI_KEY.md         # How to get Gemini API key
-│   ├── SETUP_GUIDE.md            # Detailed setup instructions
-│   ├── ARCHITECTURE.md           # Technical architecture
-│   ├── DEPLOYMENT.md             # HuggingFace deployment
-│   └── PROJECT_SUMMARY.md        # Complete overview
-│
-├── 🧪 TESTING & CONFIG
-│   ├── test_app.py               # Test suite (run before deploying!)
-│   ├── requirements.txt          # Python dependencies
-│   ├── .gitignore                # Git ignore rules
-│   └── LICENSE                   # MIT License
-│
-└── 📄 THIS FILE
-    └── PROJECT_OVERVIEW.txt      # You are here!
-
-================================================================================
-                        🚀 GETTING STARTED (3 STEPS!)
-================================================================================
-
-STEP 1: Get Gemini API Key (2 minutes)
----------------------------------------
-1. Go to: https://makersuite.google.com/app/apikey
-2. Sign in with Google (FREE!)
-3. Click "Create API Key"
-4. Copy the key
-
-📖 See GET_GEMINI_KEY.md for detailed instructions
-
-STEP 2: Add Your Key (30 seconds)
-----------------------------------
-Open config.py and find:
-    google_api_key: str = ""
-
-Replace with:
-    google_api_key: str = "your-gemini-key-here"
-
-STEP 3: Install & Run (3 minutes)
-----------------------------------
-    cd ~/Desktop/ai_radio
-    pip install -r requirements.txt
-    python test_app.py
-    python app.py
-
-Open browser: http://localhost:7860
-
-🎉 That's it! You're running!
-
-================================================================================
-                        🎮 USING YOUR AI RADIO
-================================================================================
-
-1. SET PREFERENCES
-   - Go to "Your Preferences" tab
-   - Enter name, genres, interests, mood
-   - Click "Save Preferences"
-
-2. START RADIO
-   - Go to "Radio Player" tab
-   - Click "▶️ Start Radio"
-   - Listen to your personalized show!
-
-3. CONTROLS
-   - ⏭️ Next Segment - Skip to next
-   - ⏹️ Stop - Pause radio
-
-4. VIEW STATS
-   - "Your Stats" tab shows listening history
-   - RAG system learns from this!
-
-================================================================================
-                    🏆 MCP COMPETITION REQUIREMENTS
-================================================================================
-
-TRACK: MCP in Action - Consumer Applications
-TAG: mcp-in-action-track-consumer
-
-REQUIREMENTS MET:
-✅ Autonomous Agent Behavior
-   • Planning: Creates balanced show plans
-   • Reasoning: LLM-powered content decisions
-   • Execution: Generates and delivers content
-
-✅ MCP Servers as Tools
-   • MusicMCPServer - Music search & playlists
-   • NewsMCPServer - News fetching & curation
-   • PodcastMCPServer - Podcast recommendations
-
-✅ Gradio Application
-   • Beautiful radio station UI
-   • Real-time controls
-   • Multi-tab interface
-   • Responsive design
-
-✅ Advanced Features (BONUS!)
-   • RAG System - LlamaIndex personalization
-   • Context Engineering - Mood-aware content
-   • Learning System - Improves over time
-
-================================================================================
-                      🌐 DEPLOYING TO HUGGINGFACE
-================================================================================
-
-QUICK DEPLOY (5 minutes):
-
-1. Go to: https://huggingface.co/spaces
-2. Click "New Space"
-   - Name: ai-radio
-   - SDK: Gradio
-   - Visibility: Public
-3. Upload all files from ai_radio/ folder
-4. Settings → Secrets → Add:
-   - Name: GOOGLE_API_KEY
-   - Value: Your Gemini key
-5. Wait for build (3-5 minutes)
-6. Done! Share the link!
-
-📖 See DEPLOYMENT.md for detailed instructions
-
-================================================================================
-                          🛠️ TECHNOLOGY STACK
-================================================================================
-
-Frontend:       Gradio 4.44.0
-LLM:            Google Gemini Pro
-TTS:            ElevenLabs
-RAG:            LlamaIndex + Gemini Embeddings
-Protocol:       MCP (Model Context Protocol)
-News:           RSS Feeds (BBC, NYT, etc.)
-Language:       Python 3.9+
-
-API Keys Included (Ready to Use):
-  ✅ ElevenLabs: Already in config
-  ✅ LlamaIndex: Already in config
-  ⚠️  Gemini: YOU NEED TO ADD THIS!
-
-================================================================================
-                         ✅ PRE-SUBMISSION CHECKLIST
-================================================================================
-
-Before submitting to the competition:
-
-[ ] Gemini API key added to config.py
-[ ] Ran python test_app.py - all tests pass
-[ ] Tested locally - app runs without errors
-[ ] Can save preferences
-[ ] Radio starts and plays segments
-[ ] Audio generates (TTS works)
-[ ] All MCP servers working
-[ ] RAG system stores data
-[ ] Deployed to HuggingFace Spaces
-[ ] README.md has competition tags
-[ ] Tested deployed version
-[ ] Shared Space URL
-
-================================================================================
-                           📊 PROJECT STATISTICS
-================================================================================
-
-Lines of Code:    ~2,500+
-Python Files:     11 source files
-MCP Servers:      3 specialized tools
-Features:         10+ major features
-Documentation:    8 comprehensive guides
-Tests:            7 component tests
-Dependencies:     15 Python packages
-Ready to Deploy:  ✅ YES!
-
-================================================================================
-                          🎨 CUSTOMIZATION OPTIONS
-================================================================================
-
-Change Voice (config.py):
-    elevenlabs_voice_id: str = "ErXwobaYiN019PkySvjV"  # Antoni
-
-Adjust Music/News Ratio (config.py):
-    music_ratio: float = 0.7    # More music
-    news_ratio: float = 0.1     # Less news
-
-Station Name (config.py):
-    station_name: str = "My Cool Radio 🎶"
-
-UI Colors (app.py):
-    Edit custom_css variable to change gradients
-
-================================================================================
-                            🆘 TROUBLESHOOTING
-================================================================================
-
-PROBLEM: "API key not valid"
-SOLUTION: Check you copied entire key from Google AI Studio
-          See GET_GEMINI_KEY.md
-
-PROBLEM: "Module not found"
-SOLUTION: pip install -r requirements.txt --force-reinstall
-
-PROBLEM: "No audio playing"
-SOLUTION: ElevenLabs key is already in config.py
-          Check internet connection
-
-PROBLEM: Tests failing
-SOLUTION: Ensure all dependencies installed
-          Check Gemini API key is set correctly
-
-PROBLEM: Deployment issues
-SOLUTION: See DEPLOYMENT.md troubleshooting section
-
-================================================================================
-                          📚 DOCUMENTATION GUIDE
-================================================================================
-
-WHERE TO START:
-  👉 START_HERE.md - Begin here!
-
-QUICK SETUP:
-  👉 QUICKSTART.md - Fast setup (5 min)
-  👉 GET_GEMINI_KEY.md - Get your API key
-
-DETAILED GUIDES:
-  👉 SETUP_GUIDE.md - Complete setup
-  👉 DEPLOYMENT.md - Deploy to HuggingFace
-
-TECHNICAL DETAILS:
-  👉 ARCHITECTURE.md - How it works
-  👉 PROJECT_SUMMARY.md - Complete overview
-
-MAIN DOCS:
-  👉 README.md - Project documentation
-
-================================================================================
-                             🎯 NEXT STEPS
-================================================================================
-
-RIGHT NOW:
-  1. Read START_HERE.md
-  2. Get Gemini API key (see GET_GEMINI_KEY.md)
-  3. Add key to config.py
-  4. Run: python test_app.py
-  5. Run: python app.py
-  6. Test in browser: http://localhost:7860
-
-TODAY:
-  7. Try all features
-  8. Set preferences
-  9. Listen to personalized radio
-  10. Check stats page
-
-TOMORROW:
-  11. Deploy to HuggingFace (see DEPLOYMENT.md)
-  12. Test deployed version
-  13. Submit to MCP Competition
-  14. Share with friends!
-
-================================================================================
-                           🎉 YOU'RE ALL SET!
-================================================================================
-
-Everything is ready to go! Your AI Radio is:
-
-  ✅ Fully implemented
-  ✅ Thoroughly documented
-  ✅ Competition ready
-  ✅ Deploy ready
-  ✅ Production quality
-
-Just add your Gemini API key and you're ready to launch!
-
-Commands to run:
-  cd ~/Desktop/ai_radio
-  python test_app.py      # Test everything
-  python app.py           # Start radio!
-
-Good luck with the MCP Competition! 🍀
-
-================================================================================
-                            📧 QUICK REFERENCE
-================================================================================
-
-PROJECT NAME:    AI Radio
-COMPETITION:     MCP 1st Birthday
-TRACK:           MCP in Action - Consumer
-TAG:             mcp-in-action-track-consumer
-LICENSE:         MIT
-LOCATION:        ~/Desktop/ai_radio/
-
-KEY COMMANDS:
-  Test:    python test_app.py
-  Run:     python app.py
-  Install: pip install -r requirements.txt
-
-KEY FILES:
-  Main App:     app.py
-  Config:       config.py (ADD GEMINI KEY HERE!)
-  Agent:        radio_agent.py
-  RAG:          rag_system.py
-  Test:         test_app.py
-
-IMPORTANT LINKS:
-  Gemini Key:   https://makersuite.google.com/app/apikey
-  HF Spaces:    https://huggingface.co/spaces
-  Gemini Docs:  https://ai.google.dev/
-
-================================================================================
-
-Made with ❤️ for MCP 1st Birthday Competition
-
-🎵 Enjoy your personalized AI Radio! 🎵
-
-================================================================================
-

docs/PROJECT_SUMMARY.md

@@ -1,315 +0,0 @@
-# 🎵 AI Radio - Project Summary
-
-## 📦 What We Built
-
-**AI Radio** is a complete, production-ready personalized radio station application built for the MCP 1st Birthday Competition. It demonstrates autonomous AI agent behavior, MCP server integration, RAG-based personalization, and a beautiful Gradio interface.
-
-## ✨ Key Features
-
-### 🤖 Autonomous AI Agent
-The `RadioAgent` demonstrates three core autonomous behaviors:
-
-1. **Planning** - Analyzes user preferences and creates balanced show plans
-2. **Reasoning** - Makes intelligent content selections using LLM
-3. **Execution** - Generates and delivers personalized content
-
-### 🛠️ MCP Servers (Tools)
-Three specialized MCP servers provide modular functionality:
-
-- **MusicMCPServer** - Music search and playlist generation
-- **NewsMCPServer** - Real-time news fetching and curation  
-- **PodcastMCPServer** - Podcast discovery and recommendations
-
-### 💾 RAG System
-Powered by LlamaIndex:
-- Stores user preferences and listening history
-- Provides context-aware recommendations
-- Learns and improves over time
-- Semantic search over user data
-
-### 🎨 Beautiful Gradio UI
-Modern radio station interface with:
-- Gradient color schemes
-- Real-time playback controls
-- Multiple themed tabs
-- Responsive design
-- Audio player integration
-
-### 🔊 Voice Generation
-ElevenLabs TTS integration:
-- Natural-sounding AI radio host
-- High-quality voice synthesis
-- Multiple voice options
-- Streaming support
-
-### 🧠 Advanced LLM Integration
-Google Gemini powers:
-- Dynamic host commentary
-- News script generation
-- Story creation
-- Personalized introductions
-- Context-aware responses
-
-## 📁 Project Structure
-
-```
-ai_radio/
-├── app.py                 # Main Gradio application
-├── config.py              # Configuration and API keys
-├── radio_agent.py         # Autonomous AI agent
-├── rag_system.py          # RAG system with LlamaIndex
-├── tts_service.py         # ElevenLabs TTS integration
-├── demo_assets.py         # Sample data and demos
-├── requirements.txt       # Python dependencies
-├── mcp_servers/          # MCP Server implementations
-│   ├── __init__.py
-│   ├── music_server.py   # Music search and playlists
-│   ├── news_server.py    # News fetching
-│   └── podcast_server.py # Podcast recommendations
-├── README.md             # Main documentation
-├── QUICKSTART.md         # 5-minute setup guide
-├── SETUP_GUIDE.md        # Detailed setup instructions
-├── ARCHITECTURE.md       # Technical architecture
-├── DEPLOYMENT.md         # HuggingFace deployment guide
-├── .gitignore            # Git ignore rules
-└── LICENSE               # MIT License
-```
-
-## 🏆 Competition Requirements Met
-
-### ✅ Track 2: MCP in Action
-
-| Requirement | Implementation | Status |
-|------------|----------------|--------|
-| Autonomous Agent Behavior | RadioAgent with planning, reasoning, execution | ✅ Complete |
-| MCP Servers as Tools | 3 specialized MCP servers | ✅ Complete |
-| Gradio App | Beautiful radio station UI | ✅ Complete |
-| Advanced Features (Bonus) | RAG system + Context Engineering | ✅ Complete |
-
-### 🎯 Autonomous Behaviors Demonstrated
-
-1. **Planning**:
-   - Analyzes user preferences
-   - Creates balanced show structure
-   - Optimizes segment distribution
-   - Considers variety and flow
-
-2. **Reasoning**:
-   - Uses RAG for context-aware decisions
-   - Generates appropriate commentary
-   - Selects relevant content
-   - Adapts to user mood
-
-3. **Execution**:
-   - Calls MCP tools as needed
-   - Generates TTS dynamically
-   - Manages playback flow
-   - Logs for learning
-
-## 🔧 Technology Stack
-
-| Component | Technology | Purpose |
-|-----------|-----------|---------|
-| UI Framework | Gradio 4.44.0 | Interactive web interface |
-| LLM | Google Gemini Pro | Content generation & reasoning |
-| TTS | ElevenLabs | Voice synthesis |
-| RAG | LlamaIndex | Personalization & learning |
-| Embeddings | Gemini Embeddings | Vector search |
-| News | RSS Feeds | Real-time news |
-| Protocol | MCP | Structured tools |
-
-## 🎮 User Experience Flow
-
-1. **Onboarding**:
-   ```
-   User opens app → Sets preferences → Saves to RAG
-   ```
-
-2. **Planning**:
-   ```
-   User clicks Start → Agent queries RAG → Plans show → Returns segments
-   ```
-
-3. **Playback**:
-   ```
-   Play segment → Call MCP server → Generate TTS → Play audio
-   ```
-
-4. **Learning**:
-   ```
-   User listens → Log to RAG → Update preferences → Better recommendations
-   ```
-
-## 📊 Performance Characteristics
-
-### Efficiency
-- **Low latency**: Segments generate in 2-5 seconds
-- **Streaming**: Audio streams for faster playback
-- **Caching**: Reuses generated content when possible
-- **Cost-effective**: Optimized API calls
-
-### Scalability
-- **Modular design**: Easy to add new MCP servers
-- **Stateless segments**: Each segment independent
-- **Efficient storage**: JSON-based persistence
-- **API optimized**: Minimal token usage
-
-## 🎨 UI Highlights
-
-### Radio Player Tab
-- Prominent play controls
-- Now playing display
-- Progress indicator
-- Audio player with auto-play
-- Segment information display
-
-### Preferences Tab
-- Intuitive form layout
-- Multi-select dropdowns
-- Instant save feedback
-- Visual confirmation
-
-### Stats Tab
-- Listening history
-- Usage statistics
-- RAG-powered insights
-- One-click refresh
-
-### About Tab
-- Feature overview
-- Technology stack
-- Competition info
-- Usage instructions
-
-## 🔒 Security & Privacy
-
-- ✅ API keys in config (can use env vars)
-- ✅ Local data storage
-- ✅ No unnecessary data collection
-- ✅ User data stays on device
-- ✅ Secure API communication
-
-## 📈 Future Enhancements
-
-### Possible Extensions
-1. Real music API integration (Spotify, Apple Music)
-2. Live streaming capabilities
-3. Social sharing features
-4. Mobile app version
-5. Offline mode
-6. Voice commands
-7. Multi-language support
-8. Advanced analytics
-
-## 📚 Documentation
-
-| Document | Purpose | Audience |
-|----------|---------|----------|
-| README.md | Project overview | All users |
-| QUICKSTART.md | 5-minute setup | New users |
-| SETUP_GUIDE.md | Detailed setup | All users |
-| ARCHITECTURE.md | Technical details | Developers |
-| DEPLOYMENT.md | HuggingFace deploy | Deployers |
-| PROJECT_SUMMARY.md | This file | Everyone |
-
-## 🎯 What Makes This Special
-
-### Innovation
-- **Personalized Radio**: First AI-powered personal radio station
-- **Autonomous Agent**: Fully self-managing show planning
-- **RAG Integration**: Learning system that improves over time
-- **MCP Protocol**: Demonstrates proper tool integration
-
-### Quality
-- **Professional UI**: Beautiful, polished interface
-- **Comprehensive Docs**: Extensive documentation
-- **Error Handling**: Graceful fallbacks
-- **User Experience**: Intuitive, smooth interactions
-
-### Completeness
-- **Full Stack**: End-to-end implementation
-- **Production Ready**: Can be deployed immediately
-- **Well Tested**: Robust error handling
-- **Documented**: Every component explained
-
-## 🚀 Quick Start
-
-```bash
-# 1. Install dependencies
-pip install -r requirements.txt
-
-# 2. Add Gemini API key to config.py
-# Edit config.py: google_api_key = "your-key"
-
-# 3. Run
-python app.py
-
-# 4. Open browser
-# http://localhost:7860
-```
-
-## 📊 Project Stats
-
-- **Files**: 15 source files
-- **Lines of Code**: ~2,500+
-- **MCP Servers**: 3 specialized tools
-- **Documentation Pages**: 6 comprehensive guides
-- **Features**: 10+ major features
-- **Dependencies**: 15 Python packages
-- **Development Time**: Optimized for quality
-
-## 🎉 Success Criteria
-
-All checkboxes verified:
-
-- ✅ Autonomous agent with planning, reasoning, execution
-- ✅ MCP servers implemented as tools
-- ✅ Gradio app with beautiful UI
-- ✅ RAG system for personalization
-- ✅ Context engineering demonstrated
-- ✅ Production-ready code
-- ✅ Comprehensive documentation
-- ✅ Easy deployment process
-- ✅ Tagged for competition
-- ✅ Ready to submit!
-
-## 🏅 Competition Highlights
-
-### Why This Wins
-
-1. **Complete Implementation**: Every requirement exceeded
-2. **Beautiful UX**: Professional, polished interface
-3. **Real Utility**: Actually useful application
-4. **Technical Excellence**: Clean, modular architecture
-5. **Great Documentation**: Easy to understand and deploy
-6. **MCP Showcase**: Perfect demonstration of protocol
-7. **RAG Integration**: Advanced personalization
-8. **Production Ready**: Deploy immediately
-
-## 📧 Next Steps
-
-1. ✅ Add your Gemini API key to `config.py`
-2. ✅ Test locally with `python app.py`
-3. ✅ Deploy to HuggingFace Spaces
-4. ✅ Submit to MCP Competition
-5. 🎉 Share with the world!
-
-## 🙏 Acknowledgments
-
-- **MCP Team** - For the amazing protocol
-- **Google** - For Gemini API
-- **ElevenLabs** - For TTS technology
-- **LlamaIndex** - For RAG capabilities
-- **Gradio** - For beautiful UI framework
-- **You** - For building this!
-
----
-
-## 🎵 Enjoy Your AI Radio! 🎵
-
-**Track**: MCP in Action - Consumer Applications  
-**Tag**: `mcp-in-action-track-consumer`  
-**Status**: ✅ Ready for Competition
-
-Made with ❤️ for MCP 1st Birthday Competition
-

docs/QUICKSTART.md

@@ -1,155 +0,0 @@
-# ⚡ AI Radio - Quick Start Guide
-
-Get your AI Radio up and running in 5 minutes!
-
-## 🎯 What You Need
-
-1. **Gemini API Key** - [Get it here](https://makersuite.google.com/app/apikey) (FREE)
-2. Python 3.9+ installed
-3. That's it! ElevenLabs and LlamaIndex keys are already included
-
-## 🚀 3-Step Setup
-
-### Step 1: Install Dependencies (2 minutes)
-
-```bash
-cd ~/Desktop/ai_radio
-pip install -r requirements.txt
-```
-
-### Step 2: Add Your Gemini Key (30 seconds)
-
-Open `config.py` and add your key:
-
-```python
-google_api_key: str = "paste-your-gemini-key-here"
-```
-
-Or set environment variable:
-```bash
-export GOOGLE_API_KEY="your-key-here"
-```
-
-### Step 3: Run! (10 seconds)
-
-```bash
-python app.py
-```
-
-Open: http://localhost:7860
-
-## 🎵 First Use (1 minute)
-
-1. Go to **"Your Preferences"** tab
-2. Enter your name: `Your Name`
-3. Pick genres: `pop`, `rock`
-4. Pick interests: `technology`, `world`
-5. Click **"Save Preferences"**
-6. Go to **"Radio Player"** tab
-7. Click **"▶️ Start Radio"**
-8. Enjoy! 🎉
-
-## ✅ What You Get
-
-- 🎵 **Personalized Music** from your favorite genres
-- 📰 **Latest News** on topics you care about
-- 🎙️ **Podcast Recommendations** matching your interests
-- 📖 **AI-Generated Stories** and fun facts
-- 🤖 **AI Radio Host** with natural voice
-- 💾 **Smart Learning** - gets better over time
-
-## 🎮 Controls
-
-| Button | Action |
-|--------|--------|
-| ▶️ Start Radio | Begin your show |
-| ⏭️ Next Segment | Skip to next |
-| ⏹️ Stop | Pause playback |
-
-## 📱 How It Works
-
-```
-You → Set Preferences → AI Plans Show → Generates Content → Plays Audio
-                             ↓
-                    Learns from your listening
-                             ↓
-                    Better recommendations next time!
-```
-
-## 🔧 Troubleshooting
-
-**Can't hear audio?**
-- Check that ElevenLabs key is in `config.py`
-- Verify internet connection
-
-**Errors with Gemini?**
-- Double-check your API key
-- Make sure it's from Google AI Studio
-
-**News not loading?**
-- This is OK! Demo news will play instead
-
-## 🌟 Pro Tips
-
-1. **Try different moods** - Changes the music and tone
-2. **Mix genres** - Get more variety in your show
-3. **Check stats** - See what you've listened to
-4. **Let it run** - Each segment is unique!
-
-## 📊 Example Show
-
-A typical 30-minute show includes:
-- **Intro** (1 min) - Personal greeting
-- **Music** (15 min) - 5 tracks from your favorite genres
-- **News** (6 min) - Latest updates on your interests
-- **Podcasts** (6 min) - 3 podcast recommendations
-- **Stories** (3 min) - Interesting facts and tales
-- **Outro** (1 min) - Friendly goodbye
-
-## 🚀 Deploy to HuggingFace (5 minutes)
-
-1. Go to [HuggingFace Spaces](https://huggingface.co/spaces)
-2. Click "New Space"
-3. Choose Gradio SDK
-4. Upload all files
-5. Add `GOOGLE_API_KEY` in Settings → Secrets
-6. Done! Share the link
-
-## 🎨 Customize
-
-### Change the Voice
-```python
-# config.py
-elevenlabs_voice_id: str = "ErXwobaYiN019PkySvjV"  # Antoni
-```
-
-### More Music, Less News
-```python
-# config.py
-music_ratio: float = 0.7  # 70% music
-news_ratio: float = 0.1   # 10% news
-```
-
-### Different Station Name
-```python
-# config.py
-station_name: str = "My Cool Radio 🎶"
-```
-
-## 🆘 Need Help?
-
-1. Read [SETUP_GUIDE.md](SETUP_GUIDE.md) for detailed instructions
-2. Check [ARCHITECTURE.md](ARCHITECTURE.md) for technical details
-3. Review error messages carefully
-4. Ensure all API keys are set correctly
-
-## 🎉 You're Ready!
-
-That's it! You now have your own personalized AI radio station.
-
-**Enjoy the show!** 🎵📻🎶
-
----
-
-Made with ❤️ for MCP 1st Birthday Competition
-

docs/SETUP_GUIDE.md

@@ -1,378 +0,0 @@
-# 🚀 AI Radio - Complete Setup Guide
-
-This guide will walk you through setting up AI Radio on your local machine or deploying it to HuggingFace Spaces.
-
-## 📋 Prerequisites
-
-- Python 3.9 or higher
-- pip (Python package manager)
-- Google Gemini API key
-- (Optional) Git for version control
-
-## 🔑 Getting API Keys
-
-### 1. Google Gemini API Key (Required)
-
-1. Go to [Google AI Studio](https://makersuite.google.com/app/apikey)
-2. Sign in with your Google account
-3. Click "Create API Key"
-4. Copy your API key
-5. Keep it safe - you'll need it later
-
-### 2. ElevenLabs API Key (Already Provided)
-
-The ElevenLabs API key is already included in the configuration:
-```
-sk_2dde999f3cedf21dff7ba4671ce27f292e48ea37d30c5e4a
-```
-
-### 3. LlamaIndex API Key (Already Provided)
-
-The LlamaIndex API key is already included:
-```
-llx-WRsj0iehk2ZlSlNIenOLyyhO9X1yFT4CmJXpl0qk6hapFi01
-```
-
-## 💻 Local Installation
-
-### Step 1: Clone the Repository
-
-```bash
-# Navigate to your desired directory
-cd ~/Desktop
-
-# If you have the ai_radio folder already
-cd ai_radio
-
-# Otherwise, create it
-mkdir ai_radio
-cd ai_radio
-```
-
-### Step 2: Create Virtual Environment (Recommended)
-
-```bash
-# Create virtual environment
-python -m venv venv
-
-# Activate it
-# On macOS/Linux:
-source venv/bin/activate
-
-# On Windows:
-venv\Scripts\activate
-```
-
-### Step 3: Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-This will install:
-- gradio
-- google-generativeai
-- elevenlabs
-- llama-index
-- feedparser
-- and other dependencies
-
-### Step 4: Configure API Keys
-
-Edit the `config.py` file and add your Gemini API key:
-
-```python
-# Open config.py in your favorite editor
-nano config.py  # or vim, code, etc.
-
-# Find this line:
-google_api_key: str = ""
-
-# Replace with your actual key:
-google_api_key: str = "your-gemini-api-key-here"
-```
-
-Or set it as an environment variable:
-
-```bash
-export GOOGLE_API_KEY="your-gemini-api-key-here"
-```
-
-### Step 5: Run the App
-
-```bash
-python app.py
-```
-
-You should see output like:
-```
-Running on local URL:  http://0.0.0.0:7860
-
-To create a public link, set `share=True` in `launch()`.
-```
-
-### Step 6: Open in Browser
-
-Open your browser and navigate to:
-```
-http://localhost:7860
-```
-
-You should see the AI Radio interface!
-
-## 🎮 First-Time Usage
-
-### 1. Set Your Preferences
-
-1. Click on the **"Your Preferences"** tab
-2. Fill in:
-   - Your name (e.g., "Alex")
-   - Current mood (e.g., "happy")
-   - Favorite music genres (e.g., "pop", "rock")
-   - News interests (e.g., "technology", "world")
-   - Podcast interests (e.g., "technology")
-3. Click **"Save Preferences"**
-
-You should see: ✅ Preferences saved!
-
-### 2. Start Your Radio
-
-1. Go to the **"Radio Player"** tab
-2. Click **"▶️ Start Radio"**
-3. Wait a moment for the agent to plan your show
-4. Listen to your personalized radio!
-
-### 3. Control Playback
-
-- **⏭️ Next Segment**: Skip to next segment
-- **⏹️ Stop**: Pause the radio
-
-### 4. View Your Stats
-
-1. Go to the **"Your Stats"** tab
-2. Click **"🔄 Refresh Stats"**
-3. See your listening history!
-
-## 🌐 Deploying to HuggingFace Spaces
-
-### Option 1: Using the Web Interface
-
-1. **Create Account**
-   - Go to [HuggingFace](https://huggingface.co)
-   - Sign up or log in
-
-2. **Create New Space**
-   - Click your profile → "New Space"
-   - Space name: `ai-radio`
-   - License: MIT
-   - Select SDK: **Gradio**
-   - Visibility: Public
-   - Click "Create Space"
-
-3. **Upload Files**
-   - Click "Files" tab
-   - Click "Add file" → "Upload files"
-   - Upload all files:
-     - `app.py`
-     - `config.py`
-     - `requirements.txt`
-     - `radio_agent.py`
-     - `rag_system.py`
-     - `tts_service.py`
-     - `mcp_servers/` folder (all files)
-     - `README.md`
-   - Commit changes
-
-4. **Set Secrets**
-   - Go to "Settings" tab
-   - Click "New secret"
-   - Name: `GOOGLE_API_KEY`
-   - Value: Your Gemini API key
-   - Click "Add"
-
-5. **Wait for Build**
-   - HuggingFace will automatically build your space
-   - Wait 2-3 minutes
-   - Your app will be live!
-
-### Option 2: Using Git (Advanced)
-
-```bash
-# Install git-lfs
-git lfs install
-
-# Clone your space
-git clone https://huggingface.co/spaces/YOUR_USERNAME/ai-radio
-cd ai-radio
-
-# Copy all files
-cp -r ~/Desktop/ai_radio/* .
-
-# Add, commit, push
-git add .
-git commit -m "Initial commit of AI Radio"
-git push
-```
-
-## 🔧 Troubleshooting
-
-### Issue: "ElevenLabs client not initialized"
-
-**Solution**: Check that the ElevenLabs API key is correctly set in `config.py`
-
-### Issue: "Error generating speech"
-
-**Solutions**:
-1. Verify ElevenLabs API key is valid
-2. Check internet connection
-3. Check API rate limits
-
-### Issue: "Error fetching news"
-
-**Solution**: This is normal! The app will fall back to demo news. For real news:
-1. Ensure internet connection
-2. Some RSS feeds may be blocked - this is okay
-
-### Issue: Gemini API errors
-
-**Solutions**:
-1. Verify your API key is correct
-2. Check you haven't exceeded quota
-3. Make sure the key has Gemini API access enabled
-
-### Issue: "Module not found"
-
-**Solution**: Reinstall dependencies:
-```bash
-pip install -r requirements.txt --force-reinstall
-```
-
-### Issue: Port 7860 already in use
-
-**Solution**: Kill the existing process or use a different port:
-```bash
-# Find process
-lsof -i :7860
-
-# Kill it
-kill -9 <PID>
-
-# Or change port in app.py:
-demo.launch(server_port=7861)
-```
-
-## 📱 Testing the App
-
-### Test Checklist
-
-- [ ] Set preferences successfully
-- [ ] Start radio and hear intro
-- [ ] Music segment plays with commentary
-- [ ] News segment delivers news
-- [ ] Podcast segment gives recommendations
-- [ ] Story segment tells interesting story
-- [ ] Next button skips segments
-- [ ] Stop button pauses radio
-- [ ] Stats page shows listening history
-- [ ] Preferences persist between sessions
-
-## 🎨 Customization
-
-### Change Voice
-
-Edit `config.py`:
-```python
-elevenlabs_voice_id: str = "ErXwobaYiN019PkySvjV"  # Antoni voice
-```
-
-Available voices:
-- `21m00Tcm4TlvDq8ikWAM` - Rachel (Default)
-- `ErXwobaYiN019PkySvjV` - Antoni
-- `MF3mGyEYCl7XYWbV9V6O` - Elli
-
-### Change Segment Ratios
-
-Edit `config.py`:
-```python
-music_ratio: float = 0.6  # 60% music (default 50%)
-news_ratio: float = 0.2   # 20% news
-podcast_ratio: float = 0.1  # 10% podcasts (default 20%)
-story_ratio: float = 0.1   # 10% stories
-```
-
-### Add Real Music API
-
-Edit `mcp_servers/music_server.py`:
-```python
-def search_free_music(self, genre: str, mood: str, limit: int):
-    # Add your API integration here
-    # Example: Spotify, Apple Music, YouTube Music
-    pass
-```
-
-### Customize UI Colors
-
-Edit `app.py` CSS:
-```python
-custom_css = """
-#radio-header {
-    background: linear-gradient(135deg, #your-color 0%, #your-color2 100%);
-}
-"""
-```
-
-## 📊 Performance Tips
-
-### Reduce Cost
-
-1. **Use shorter segments**: Modify `duration_minutes` in planning
-2. **Cache audio**: Reuse generated TTS
-3. **Batch requests**: Generate multiple segments at once
-
-### Improve Speed
-
-1. **Preload content**: Fetch news/music in advance
-2. **Parallel generation**: Generate TTS while planning next segment
-3. **Optimize prompts**: Use shorter, more efficient prompts
-
-## 🔒 Security Best Practices
-
-1. **Never commit API keys** to public repos
-2. **Use environment variables** for sensitive data
-3. **Rotate keys regularly**
-4. **Monitor API usage** to detect abuse
-5. **Use secrets** in HuggingFace Spaces
-
-## 📚 Additional Resources
-
-- [Gradio Documentation](https://www.gradio.app/docs)
-- [Gemini API Guide](https://ai.google.dev/tutorials)
-- [ElevenLabs API Docs](https://elevenlabs.io/docs)
-- [LlamaIndex Tutorials](https://docs.llamaindex.ai/)
-- [HuggingFace Spaces Guide](https://huggingface.co/docs/hub/spaces)
-
-## 🆘 Getting Help
-
-If you encounter issues:
-
-1. Check the troubleshooting section above
-2. Review error messages carefully
-3. Check API quotas and limits
-4. Verify all dependencies are installed
-5. Try running in a fresh virtual environment
-
-## 🎉 Success!
-
-Once everything is working, you should have:
-- ✅ A running AI Radio station
-- ✅ Personalized content based on your preferences
-- ✅ Smooth playback with TTS
-- ✅ A beautiful Gradio interface
-- ✅ RAG-powered recommendations
-
-Enjoy your personalized AI Radio! 🎵
-
----
-
-Need help? Check the ARCHITECTURE.md for technical details!
-

docs/START_HERE.md

@@ -1,306 +0,0 @@
-# 🎵 AI Radio - START HERE! 🎵
-
-Welcome to your AI Radio project! This guide will get you up and running in minutes.
-
-## 🎯 What You Have
-
-A complete, production-ready **personalized AI radio station** for the MCP 1st Birthday Competition!
-
-**Features:**
-- 🤖 Autonomous AI agent (planning, reasoning, execution)
-- 🎵 Personalized music from your favorite genres
-- 📰 Real-time news on topics you care about
-- 🎙️ Podcast recommendations
-- 📖 AI-generated stories
-- 🔊 Natural voice with ElevenLabs TTS
-- 💾 RAG system that learns your preferences
-- 🎨 Beautiful Gradio UI
-
-## ⚡ Quick Start (5 Minutes)
-
-### 1️⃣ Get Your Gemini API Key (2 minutes)
-
-This is the ONLY thing you need to do!
-
-1. Go to: https://makersuite.google.com/app/apikey
-2. Sign in with Google (it's FREE!)
-3. Click "Create API Key"
-4. Copy your key
-
-📖 **Detailed guide**: See `GET_GEMINI_KEY.md`
-
-### 2️⃣ Add Your Key (30 seconds)
-
-Open `config.py` and find this line:
-
-```python
-google_api_key: str = ""
-```
-
-Replace with your key:
-
-```python
-google_api_key: str = "your-gemini-key-here"
-```
-
-### 3️⃣ Install Dependencies (2 minutes)
-
-```bash
-cd ~/Desktop/ai_radio
-pip install -r requirements.txt
-```
-
-### 4️⃣ Test Everything (1 minute)
-
-```bash
-python test_app.py
-```
-
-You should see: "🎉 All tests passed!"
-
-### 5️⃣ Run! (10 seconds)
-
-```bash
-python app.py
-```
-
-Open in browser: http://localhost:7860
-
-## 🎮 Using AI Radio
-
-### First Time Setup
-
-1. Go to **"Your Preferences"** tab
-2. Enter your details:
-   - Name (e.g., "Alex")
-   - Mood (e.g., "happy")
-   - Favorite genres (e.g., pop, rock)
-   - News interests (e.g., technology, world)
-   - Podcast interests (e.g., technology)
-3. Click **"Save Preferences"**
-
-### Start Listening
-
-1. Go to **"Radio Player"** tab
-2. Click **"▶️ Start Radio"**
-3. Enjoy your personalized show!
-4. Use **⏭️ Next** to skip segments
-5. Use **⏹️ Stop** to pause
-
-### View Your Stats
-
-1. Go to **"Your Stats"** tab
-2. See your listening history
-3. The RAG system learns from this!
-
-## 📁 Project Files
-
-Here's what you have:
-
-| File | What It Does |
-|------|-------------|
-| `app.py` | Main Gradio app (run this!) |
-| `radio_agent.py` | Autonomous AI agent |
-| `rag_system.py` | Learning/personalization |
-| `tts_service.py` | Voice generation |
-| `mcp_servers/` | MCP tools (music, news, podcasts) |
-| `config.py` | Configuration (add your key here!) |
-| `test_app.py` | Test all components |
-
-**Documentation:**
-- `README.md` - Full project documentation
-- `QUICKSTART.md` - Fast setup guide
-- `SETUP_GUIDE.md` - Detailed instructions
-- `GET_GEMINI_KEY.md` - How to get API key
-- `ARCHITECTURE.md` - Technical details
-- `DEPLOYMENT.md` - Deploy to HuggingFace
-- `PROJECT_SUMMARY.md` - Complete overview
-
-## 🚀 Deploy to HuggingFace (5 Minutes)
-
-### Quick Deploy
-
-1. Go to: https://huggingface.co/spaces
-2. Create new Space (Gradio SDK)
-3. Upload all files
-4. Add `GOOGLE_API_KEY` in Settings → Secrets
-5. Wait for build
-6. Done! 🎉
-
-📖 **Detailed guide**: See `DEPLOYMENT.md`
-
-## ✅ Verification Checklist
-
-Before submitting to the competition:
-
-- [ ] Gemini API key added to config
-- [ ] `python test_app.py` passes all tests
-- [ ] App runs locally without errors
-- [ ] Can save preferences
-- [ ] Radio starts and plays
-- [ ] Audio generates (TTS works)
-- [ ] All MCP servers working
-- [ ] RAG system stores data
-- [ ] Deployed to HuggingFace Spaces
-- [ ] README has competition tags
-
-## 🏆 Competition Info
-
-**Track**: MCP in Action - Consumer Applications  
-**Tag**: `mcp-in-action-track-consumer`
-
-**Requirements Met:**
-- ✅ Autonomous agent (planning, reasoning, execution)
-- ✅ MCP servers as tools (3 specialized servers)
-- ✅ Gradio app (beautiful UI)
-- ✅ Advanced features (RAG + Context Engineering)
-
-## 📚 Need Help?
-
-### Common Issues
-
-**"API key not valid"**
-- Check you copied the entire key from Google AI Studio
-- See `GET_GEMINI_KEY.md`
-
-**"Module not found"**
-- Run: `pip install -r requirements.txt`
-
-**"No audio playing"**
-- Check ElevenLabs key in config.py
-- Key is already included!
-
-**Tests failing?**
-- Make sure all dependencies installed
-- Check Gemini API key is set
-
-### Where to Look
-
-| Problem | Solution |
-|---------|----------|
-| Setup issues | `SETUP_GUIDE.md` |
-| API key help | `GET_GEMINI_KEY.md` |
-| Deployment | `DEPLOYMENT.md` |
-| How it works | `ARCHITECTURE.md` |
-| Quick fixes | This file! |
-
-## 🎨 Customization
-
-### Change the Voice
-
-Edit `config.py`:
-```python
-elevenlabs_voice_id: str = "ErXwobaYiN019PkySvjV"  # Antoni
-```
-
-### More Music, Less News
-
-Edit `config.py`:
-```python
-music_ratio: float = 0.7   # 70% music
-news_ratio: float = 0.1    # 10% news
-```
-
-### Station Name
-
-Edit `config.py`:
-```python
-station_name: str = "My Cool Radio 🎶"
-```
-
-## 🌟 Pro Tips
-
-1. **Try different moods** - Affects music and commentary tone
-2. **Mix multiple genres** - More variety in your show
-3. **Let it run** - Each segment is unique!
-4. **Check stats regularly** - See the RAG system learning
-5. **Deploy to HF** - Share with friends!
-
-## 📊 What Happens When You Run
-
-```
-1. You set preferences
-   ↓
-2. RAG system stores them
-   ↓
-3. Agent plans personalized show
-   ↓
-4. MCP servers fetch content
-   ↓
-5. Gemini generates commentary
-   ↓
-6. ElevenLabs creates voice
-   ↓
-7. You hear amazing radio!
-   ↓
-8. System learns for next time
-```
-
-## 🎉 You're Ready!
-
-Everything is set up and ready to go. Just:
-
-1. ✅ Add your Gemini API key to `config.py`
-2. ✅ Run `python test_app.py`
-3. ✅ Start with `python app.py`
-4. 🎵 Enjoy!
-
-## 🚢 Next Steps
-
-### Today
-- [ ] Get Gemini API key
-- [ ] Test locally
-- [ ] Try all features
-
-### Tomorrow
-- [ ] Deploy to HuggingFace
-- [ ] Share with friends
-- [ ] Submit to competition
-
-### Optional
-- [ ] Customize UI colors
-- [ ] Add more genres
-- [ ] Tweak segment ratios
-- [ ] Create demo video
-
-## 🙏 Thank You!
-
-Thank you for building AI Radio! This project demonstrates:
-- Autonomous AI agents
-- MCP protocol integration
-- RAG-based personalization
-- Beautiful UX design
-
-**Good luck with the MCP Competition!** 🍀
-
----
-
-## 🆘 Still Stuck?
-
-If you're having issues:
-
-1. Read the error message carefully
-2. Check `SETUP_GUIDE.md` troubleshooting section
-3. Run `python test_app.py` to diagnose
-4. Verify all API keys are set
-5. Make sure dependencies are installed
-
-## 🎵 Let's Go!
-
-You're all set to create amazing personalized radio experiences!
-
-**Run this now:**
-```bash
-python test_app.py
-python app.py
-```
-
-**Open:** http://localhost:7860
-
-**Enjoy your AI Radio!** 🎉🎵📻
-
----
-
-Made with ❤️ for MCP 1st Birthday Competition  
-Track: MCP in Action - Consumer Applications
-

src/app.py

@@ -1961,10 +1961,13 @@ Your passphrase: **{passphrase}**
     """)
 
 # Launch the app
+# Note: For HuggingFace Spaces, use app.py at root level instead
 if __name__ == "__main__":
+    import os
+    port = int(os.getenv("PORT", 7871))
     demo.launch(
         server_name="0.0.0.0",
-        server_port=7871,
+        server_port=port,
         share=False
     )
 

src/config.py

@@ -5,17 +5,13 @@ from pydantic import BaseModel
 class RadioConfig(BaseModel):
     """Configuration for the radio app"""
     
-    # API Keys
-    elevenlabs_api_key: str = "sk_d0a3622fe5acdf6c747236728ef193a3726c29bc943519d5"
-    llamaindex_api_key: str = "llx-WRsj0iehk2ZlSlNIenOLyyhO9X1yFT4CmJXpl0qk6hapFi01"
-    nebius_api_key: str = "v1.CmQKHHN0YXRpY2tleS1lMDB0eTkxeTdwY3lxNDk5OWcSIXNlcnZpY2VhY2NvdW50LWUwMGowemtmZWpqc2E3ZHF3aDIMCKb4oskGENS9j8MBOgwIpfu6lAcQgOqAhwNAAloDZTAw.AAAAAAAAAAGEI_L5sJCQ7XR93nSzvXCPO-J3-gHjqPiRqrvkrMLeDtd-70zGWB1-c8yovnX-q7yEc1dHOnA2L8FUa3Le6X8D"
+    # API Keys - MUST be set via environment variables (secrets in HF Spaces)
+    # These defaults are empty strings - will fail if not set via env vars
+    elevenlabs_api_key: str = ""
+    llamaindex_api_key: str = ""
+    nebius_api_key: str = ""
+    
     # Nebius OpenAI-compatible endpoint and model
-    # See example usage:
-    # client = OpenAI(
-    #     base_url="https://api.tokenfactory.nebius.com/v1/",
-    #     api_key=os.environ.get("NEBIUS_API_KEY")
-    # )
-    # model="openai/gpt-oss-120b"
     nebius_api_base: str = "https://api.tokenfactory.nebius.com/v1/"  # Nebius OpenAI-compatible endpoint
     nebius_model: str = "openai/gpt-oss-120b"  # GPT-OSS-120B model name from Nebius
     
@@ -33,16 +29,20 @@ class RadioConfig(BaseModel):
     story_ratio: float = 0.1
 
 def get_config() -> RadioConfig:
-    """Get configuration with environment variable overrides"""
+    """Get configuration from environment variables (secrets in HF Spaces)"""
     config = RadioConfig()
     
-    # Override with environment variables if available
-    if api_key := os.getenv("ELEVENLABS_API_KEY"):
-        config.elevenlabs_api_key = api_key
-    if api_key := os.getenv("LLAMAINDEX_API_KEY"):
-        config.llamaindex_api_key = api_key
-    if api_key := os.getenv("NEBIUS_API_KEY"):
-        config.nebius_api_key = api_key
+    # Read API keys from environment variables (required for HF Spaces)
+    # These should be set as Secrets in HuggingFace Spaces Settings
+    config.elevenlabs_api_key = os.getenv("ELEVENLABS_API_KEY", "")
+    config.llamaindex_api_key = os.getenv("LLAMAINDEX_API_KEY", "")
+    config.nebius_api_key = os.getenv("NEBIUS_API_KEY", "")
+    
+    # Validate that required keys are set
+    if not config.elevenlabs_api_key:
+        print("⚠️ Warning: ELEVENLABS_API_KEY not set. TTS will not work.")
+    if not config.nebius_api_key:
+        print("⚠️ Warning: NEBIUS_API_KEY not set. LLM will not work.")
     
     return config