README.md

🎭 Explainor

Learn anything through the voice of your favorite characters!

Tags: mcp-in-action-track-creative

---

🌟 What is Explainor?

Explainor is an AI agent that takes any topic you want to learn about and explains it through the voice of fun characters! Choose from 6 unique personas:

Persona	Style
👶 5-Year-Old	Simple words, excited, curious questions
👨‍🍳 Gordon Ramsay	Intense, food metaphors, "It's RAW!"
🏴‍☠️ Pirate	"Arrr!", treasure metaphors, swashbuckling
🎭 Shakespeare	Dramatic, old English, theatrical
🏄 Surfer Dude	"Brooo", chill vibes, wave metaphors
🧙 Yoda	Inverted syntax, wise, Force references

🎬 Demo

[Demo Video Placeholder]

🛠️ How It Works

1. Enter a topic - Anything from "Quantum Computing" to "How do volcanoes work?"
2. Choose a persona - Pick your favorite character
3. Choose your audience - Who are you explaining to?
4. Watch the magic - The AI agent:
   • 🔍 Researches your topic using web search
   • 📋 Extracts key facts from sources
   • 🎭 Transforms the explanation into the character's voice
   • 🔊 Reads it aloud with a matching voice!

👤 Who's Listening?

Make the explanation even more tailored by choosing your audience:

Audience	Effect
👤 Just me	Standard explanation
👵 My confused grandmother	Extra simple, patient
🤖 A skeptical robot	Logical, evidence-based
👽 An alien visiting Earth	Explain Earth concepts
🧟 A zombie	Very short, simple words
🦊 A very smart fox	Clever, quick
👔 A stressed CEO	Bottom-line focused
🎮 A distracted gamer	Keep it engaging

🔌 MCP Server Integration

This app is a real MCP server! When running, it exposes its functionality as tools that other AI agents can call via the Model Context Protocol.

MCP Endpoint: http://localhost:7860/gradio_api/mcp/

This means:

• Other AI agents can use Explainor as a tool
• Enables agent-to-agent communication
• Part of the growing MCP ecosystem

🚀 Tech Stack

• MCP: Model Context Protocol - App exposes itself as an MCP server
• LLM: Nebius AI - Llama 3.3 70B for intelligent explanations
• TTS: ElevenLabs - Realistic voice synthesis with character-matched voices
• Web Search: DuckDuckGo API for topic research
• Frontend: Gradio with MCP integration
• Deployment: Modal - Serverless infrastructure

💻 Local Development

Prerequisites

• Python 3.11+
• Nebius API key
• ElevenLabs API key

Setup

# Clone the repository
git clone https://huggingface.co/spaces/MCP-1st-Birthday/explainor

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys

# Run locally
python app.py

Environment Variables

NEBIUS_API_KEY=your_nebius_api_key_here
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

🌐 Deployment

Modal Deployment

# Set up Modal secrets
modal secret create nebius-api-key NEBIUS_API_KEY=your_key
modal secret create elevenlabs-api-key ELEVENLABS_API_KEY=your_key

# Deploy
modal deploy modal_app.py

Hugging Face Spaces

This app is designed to run on Hugging Face Spaces with the Gradio SDK.

📁 Project Structure

explainor/
├── app.py              # Main Gradio application
├── modal_app.py        # Modal deployment config
├── requirements.txt    # Python dependencies
├── src/
│   ├── __init__.py
│   ├── personas.py     # Persona definitions & voice mappings
│   ├── agent.py        # Agent logic & web search
│   └── tts.py          # ElevenLabs integration
└── README.md

🏆 Hackathon Submission

• Event: MCP's 1st Birthday Hackathon
• Track: MCP in Action (Track 2)
• Category: Creative
• Team: kaiser-data
• Sponsor Integration: ElevenLabs for text-to-speech

📝 License

MIT License - Feel free to use and modify!

---

Made with ❤️ for MCP's 1st Birthday Hackathon