Initial commit: Explainor - AI agent with persona voices

MCP's 1st Birthday Hackathon submission
- Gradio 6 UI with 6 personas
- DuckDuckGo web search integration
- ElevenLabs TTS with persona-matched voices
- Modal deployment config
- Agent logic with reasoning steps

Track: MCP in Action (Creative)
Team: kaiser-data

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.env.example

@@ -0,0 +1,2 @@
+NEBIUS_API_KEY=your_nebius_api_key_here
+ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

.gitignore

@@ -0,0 +1,9 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.modal/

README.md

@@ -0,0 +1,126 @@
+# 🎭 Explainor
+
+> **Learn anything through the voice of your favorite characters!**
+
+[![MCP Hackathon](https://img.shields.io/badge/MCP%20Hackathon-1st%20Birthday-purple)](https://huggingface.co/MCP-1st-Birthday)
+[![Track](https://img.shields.io/badge/Track-MCP%20in%20Action-blue)](https://huggingface.co/MCP-1st-Birthday)
+[![Category](https://img.shields.io/badge/Category-Creative-green)](https://huggingface.co/MCP-1st-Birthday)
+
+**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. **Watch the magic** - The AI agent:
+   - 🔍 Researches your topic using web search
+   - 🧠 Shows its reasoning process
+   - ✍️ Transforms the explanation into the character's voice
+   - 🔊 Reads it aloud with a matching voice!
+
+## 🚀 Tech Stack
+
+- **LLM**: [Nebius AI](https://nebius.com) - Llama 3.3 70B for intelligent explanations
+- **TTS**: [ElevenLabs](https://elevenlabs.io) - Realistic voice synthesis with character-matched voices
+- **Web Search**: DuckDuckGo API for topic research
+- **Frontend**: [Gradio](https://gradio.app) - Beautiful, responsive UI
+- **Deployment**: [Modal](https://modal.com) - Serverless infrastructure
+
+## 💻 Local Development
+
+### Prerequisites
+
+- Python 3.11+
+- Nebius API key
+- ElevenLabs API key
+
+### Setup
+
+```bash
+# 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
+
+```bash
+NEBIUS_API_KEY=your_nebius_api_key_here
+ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
+```
+
+## 🌐 Deployment
+
+### Modal Deployment
+
+```bash
+# 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**

app.py

@@ -0,0 +1,268 @@
+"""Explainor - AI Agent that explains any topic in fun persona voices.
+
+MCP's 1st Birthday Hackathon Submission
+Track: MCP in Action (Creative)
+Team: kaiser-data
+"""
+
+import os
+import tempfile
+import gradio as gr
+from dotenv import load_dotenv
+
+from src.personas import PERSONAS, get_persona_names, get_persona
+from src.agent import run_agent
+from src.tts import generate_speech
+
+# Load environment variables
+load_dotenv()
+
+
+def format_sources(sources: list[dict]) -> str:
+    """Format sources as markdown."""
+    if not sources:
+        return "*No external sources used*"
+
+    md = ""
+    for i, src in enumerate(sources, 1):
+        if src.get("url"):
+            md += f"{i}. [{src['title']}]({src['url']})\n"
+        else:
+            md += f"{i}. {src['title']} ({src.get('source', 'General')})\n"
+    return md
+
+
+def explain_topic(topic: str, persona_name: str, progress=gr.Progress()):
+    """Main function to explain a topic in a persona's voice.
+
+    Returns: (explanation_text, audio_path, sources_md, steps_md)
+    """
+    if not topic.strip():
+        return (
+            "Please enter a topic to explain!",
+            None,
+            "",
+            "❌ No topic provided",
+        )
+
+    if not persona_name:
+        persona_name = "5-Year-Old"
+
+    steps_log = []
+    explanation = ""
+    sources = []
+    voice_id = None
+
+    # Run the agent pipeline
+    progress(0, desc="Starting...")
+
+    for update in run_agent(topic, persona_name):
+        if update["type"] == "step":
+            step_text = f"**{update['title']}**\n{update['content']}"
+            steps_log.append(step_text)
+
+            if update["step"] == "research":
+                progress(0.2, desc="Researching...")
+            elif update["step"] == "research_done":
+                progress(0.4, desc="Research complete")
+                if "sources" in update:
+                    sources = update["sources"]
+            elif update["step"] == "generating":
+                progress(0.6, desc="Generating explanation...")
+
+        elif update["type"] == "result":
+            explanation = update["explanation"]
+            sources = update.get("sources", sources)
+            voice_id = update["voice_id"]
+            progress(0.8, desc="Explanation ready!")
+
+    # Format the steps log
+    steps_md = "\n\n---\n\n".join(steps_log)
+
+    # Generate audio
+    audio_path = None
+    if explanation and voice_id:
+        progress(0.9, desc="Generating audio...")
+        try:
+            audio_bytes = generate_speech(explanation, voice_id)
+            # Save to temp file for Gradio
+            with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
+                f.write(audio_bytes)
+                audio_path = f.name
+            progress(1.0, desc="Done!")
+        except Exception as e:
+            steps_log.append(f"**⚠️ Audio generation failed**\n{str(e)}")
+            steps_md = "\n\n---\n\n".join(steps_log)
+            progress(1.0, desc="Done (no audio)")
+
+    # Format sources
+    sources_md = format_sources(sources)
+
+    return explanation, audio_path, sources_md, steps_md
+
+
+# Build the Gradio interface
+def create_app():
+    """Create and configure the Gradio app."""
+
+    # Custom CSS for better styling
+    css = """
+    .gradio-container {
+        max-width: 900px !important;
+        margin: auto !important;
+    }
+    .persona-dropdown {
+        font-size: 1.1em !important;
+    }
+    #title-row {
+        text-align: center;
+        margin-bottom: 1rem;
+    }
+    .explanation-box {
+        font-size: 1.15em;
+        line-height: 1.6;
+        padding: 1rem;
+        background: linear-gradient(135deg, #667eea11 0%, #764ba211 100%);
+        border-radius: 10px;
+    }
+    .steps-accordion {
+        font-size: 0.95em;
+    }
+    """
+
+    with gr.Blocks(
+        title="Explainor - AI Persona Explanations",
+        css=css,
+        theme=gr.themes.Soft(
+            primary_hue="violet",
+            secondary_hue="blue",
+        ),
+    ) as app:
+        # Header
+        gr.Markdown(
+            """
+            # 🎭 Explainor
+
+            **Learn anything through the voice of your favorite characters!**
+
+            Enter any topic and choose a persona. The AI will research your topic,
+            transform the explanation into that character's unique voice, and read it aloud.
+            """,
+            elem_id="title-row",
+        )
+
+        with gr.Row():
+            with gr.Column(scale=2):
+                topic_input = gr.Textbox(
+                    label="📝 What do you want to learn about?",
+                    placeholder="e.g., Blockchain, Photosynthesis, Black Holes...",
+                    lines=1,
+                    max_lines=1,
+                )
+
+            with gr.Column(scale=1):
+                # Build persona choices with emojis
+                persona_choices = [
+                    f"{PERSONAS[name]['emoji']} {name}"
+                    for name in get_persona_names()
+                ]
+                persona_dropdown = gr.Dropdown(
+                    choices=persona_choices,
+                    value=persona_choices[0],
+                    label="🎭 Choose your explainer",
+                    elem_classes=["persona-dropdown"],
+                )
+
+        explain_btn = gr.Button(
+            "✨ Explain it to me!",
+            variant="primary",
+            size="lg",
+        )
+
+        # Output section
+        with gr.Row():
+            with gr.Column():
+                explanation_output = gr.Textbox(
+                    label="📖 Explanation",
+                    lines=8,
+                    max_lines=15,
+                    elem_classes=["explanation-box"],
+                    show_copy_button=True,
+                )
+
+                audio_output = gr.Audio(
+                    label="🔊 Listen to the explanation",
+                    type="filepath",
+                    autoplay=False,
+                )
+
+        with gr.Row():
+            with gr.Column():
+                with gr.Accordion("🔍 Sources", open=False):
+                    sources_output = gr.Markdown("")
+
+            with gr.Column():
+                with gr.Accordion("🧠 Agent Reasoning", open=False):
+                    steps_output = gr.Markdown(
+                        "",
+                        elem_classes=["steps-accordion"],
+                    )
+
+        # Example topics
+        gr.Examples(
+            examples=[
+                ["Quantum Computing", f"{PERSONAS['5-Year-Old']['emoji']} 5-Year-Old"],
+                ["Blockchain", f"{PERSONAS['Gordon Ramsay']['emoji']} Gordon Ramsay"],
+                ["Black Holes", f"{PERSONAS['Pirate']['emoji']} Pirate"],
+                ["Machine Learning", f"{PERSONAS['Shakespeare']['emoji']} Shakespeare"],
+                ["Climate Change", f"{PERSONAS['Surfer Dude']['emoji']} Surfer Dude"],
+                ["The Force", f"{PERSONAS['Yoda']['emoji']} Yoda"],
+            ],
+            inputs=[topic_input, persona_dropdown],
+            label="Try these examples:",
+        )
+
+        # Footer
+        gr.Markdown(
+            """
+            ---
+            **Built for MCP's 1st Birthday Hackathon** | Track: MCP in Action (Creative)
+
+            Powered by: [Nebius AI](https://nebius.com) (LLM) + [ElevenLabs](https://elevenlabs.io) (TTS)
+
+            Made with ❤️ by **kaiser-data**
+            """,
+            elem_id="footer",
+        )
+
+        # Event handler
+        def process_and_explain(topic, persona_with_emoji):
+            # Extract persona name (remove emoji prefix)
+            persona_name = persona_with_emoji.split(" ", 1)[1] if " " in persona_with_emoji else persona_with_emoji
+            return explain_topic(topic, persona_name)
+
+        explain_btn.click(
+            fn=process_and_explain,
+            inputs=[topic_input, persona_dropdown],
+            outputs=[explanation_output, audio_output, sources_output, steps_output],
+        )
+
+        # Also trigger on Enter key in topic input
+        topic_input.submit(
+            fn=process_and_explain,
+            inputs=[topic_input, persona_dropdown],
+            outputs=[explanation_output, audio_output, sources_output, steps_output],
+        )
+
+    return app
+
+
+# Create the app
+app = create_app()
+
+if __name__ == "__main__":
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+    )

modal_app.py

@@ -0,0 +1,50 @@
+"""Modal deployment configuration for Explainor.
+
+Deploy with: modal deploy modal_app.py
+Run locally: modal serve modal_app.py
+"""
+
+import os
+import modal
+
+# Define the Modal app
+app = modal.App("explainor")
+
+# Create image with dependencies
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install(
+        "gradio>=5.0.0",
+        "elevenlabs>=1.0.0",
+        "httpx>=0.25.0",
+        "python-dotenv>=1.0.0",
+    )
+    .copy_local_dir("src", "/app/src")
+    .copy_local_file("app.py", "/app/app.py")
+)
+
+
+@app.function(
+    image=image,
+    secrets=[
+        modal.Secret.from_name("nebius-api-key"),
+        modal.Secret.from_name("elevenlabs-api-key"),
+    ],
+    timeout=600,
+    allow_concurrent_inputs=10,
+)
+@modal.asgi_app()
+def serve():
+    """Serve the Gradio app."""
+    import sys
+    sys.path.insert(0, "/app")
+
+    from app import app as gradio_app
+    return gradio_app
+
+
+# For local testing
+if __name__ == "__main__":
+    # Run with: python modal_app.py
+    print("Run with: modal serve modal_app.py")
+    print("Or deploy: modal deploy modal_app.py")

requirements.txt

@@ -0,0 +1,6 @@
+gradio>=5.0.0
+elevenlabs>=1.0.0
+openai>=1.0.0
+httpx>=0.25.0
+python-dotenv>=1.0.0
+modal>=0.64.0

src/__init__.py

@@ -0,0 +1,15 @@
+"""Explainor - AI agent that explains topics in persona voices."""
+
+from .personas import PERSONAS, get_persona, get_persona_names
+from .agent import run_agent, research_topic
+from .tts import generate_speech, generate_speech_file
+
+__all__ = [
+    "PERSONAS",
+    "get_persona",
+    "get_persona_names",
+    "run_agent",
+    "research_topic",
+    "generate_speech",
+    "generate_speech_file",
+]

src/agent.py

@@ -0,0 +1,268 @@
+"""Explainor Agent - Research and explain topics in persona voices."""
+
+import os
+import json
+import httpx
+from typing import Generator
+
+from .personas import get_persona
+
+
+# Nebius API configuration (OpenAI-compatible)
+NEBIUS_API_BASE = "https://api.studio.nebius.com/v1"
+NEBIUS_MODEL = "meta-llama/Llama-3.3-70B-Instruct"
+
+
+def get_nebius_client():
+    """Get configured httpx client for Nebius API."""
+    api_key = os.getenv("NEBIUS_API_KEY")
+    if not api_key:
+        raise ValueError("NEBIUS_API_KEY environment variable not set")
+    return api_key
+
+
+def web_search(query: str) -> dict:
+    """Perform web search using DuckDuckGo (no API key needed).
+
+    Returns structured search results.
+    """
+    try:
+        # Use DuckDuckGo HTML search (no API needed)
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+        }
+
+        with httpx.Client(timeout=10.0) as client:
+            # DuckDuckGo instant answer API
+            resp = client.get(
+                "https://api.duckduckgo.com/",
+                params={
+                    "q": query,
+                    "format": "json",
+                    "no_html": "1",
+                    "skip_disambig": "1",
+                },
+                headers=headers,
+            )
+            data = resp.json()
+
+            results = []
+
+            # Abstract (main answer)
+            if data.get("Abstract"):
+                results.append({
+                    "title": data.get("Heading", "Overview"),
+                    "snippet": data["Abstract"],
+                    "source": data.get("AbstractSource", "DuckDuckGo"),
+                    "url": data.get("AbstractURL", ""),
+                })
+
+            # Related topics
+            for topic in data.get("RelatedTopics", [])[:3]:
+                if isinstance(topic, dict) and topic.get("Text"):
+                    results.append({
+                        "title": topic.get("Text", "")[:50] + "...",
+                        "snippet": topic.get("Text", ""),
+                        "source": "DuckDuckGo",
+                        "url": topic.get("FirstURL", ""),
+                    })
+
+            # If no results, try a simpler search
+            if not results:
+                results.append({
+                    "title": f"Search: {query}",
+                    "snippet": f"Topic: {query}. Please explain this concept based on general knowledge.",
+                    "source": "General Knowledge",
+                    "url": "",
+                })
+
+            return {"results": results, "query": query}
+
+    except Exception as e:
+        return {
+            "results": [{
+                "title": f"Search: {query}",
+                "snippet": f"Topic: {query}. Please explain this concept based on general knowledge.",
+                "source": "General Knowledge",
+                "url": "",
+            }],
+            "query": query,
+            "error": str(e),
+        }
+
+
+def call_llm(messages: list[dict], max_tokens: int = 1500) -> str:
+    """Call Nebius LLM API."""
+    api_key = get_nebius_client()
+
+    with httpx.Client(timeout=60.0) as client:
+        resp = client.post(
+            f"{NEBIUS_API_BASE}/chat/completions",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "model": NEBIUS_MODEL,
+                "messages": messages,
+                "max_tokens": max_tokens,
+                "temperature": 0.8,
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return data["choices"][0]["message"]["content"]
+
+
+def research_topic(topic: str) -> tuple[str, list[dict]]:
+    """Research a topic using web search.
+
+    Returns: (research_summary, sources_list)
+    """
+    # Perform search
+    search_results = web_search(topic)
+
+    # Format research for the agent
+    research_text = f"## Research on: {topic}\n\n"
+    sources = []
+
+    for i, result in enumerate(search_results.get("results", []), 1):
+        research_text += f"### Source {i}: {result['title']}\n"
+        research_text += f"{result['snippet']}\n\n"
+        if result.get("url"):
+            sources.append({
+                "title": result["title"],
+                "url": result["url"],
+                "source": result.get("source", "Web"),
+            })
+
+    return research_text, sources
+
+
+def generate_explanation(
+    topic: str,
+    persona_name: str,
+    research: str,
+) -> Generator[dict, None, None]:
+    """Generate explanation in persona voice, yielding steps.
+
+    Yields dicts with: {"step": str, "content": str}
+    """
+    persona = get_persona(persona_name)
+
+    # Step 1: Acknowledge the task
+    yield {
+        "step": "understanding",
+        "title": "📚 Understanding the topic",
+        "content": f"Researching '{topic}' to gather key information...",
+    }
+
+    # Step 2: Show research
+    yield {
+        "step": "research",
+        "title": "🔍 Research complete",
+        "content": f"Found information about {topic}. Now transforming into {persona_name} voice...",
+    }
+
+    # Step 3: Generate the explanation
+    messages = [
+        {
+            "role": "system",
+            "content": f"""{persona['system_prompt']}
+
+You are explaining a topic to someone. Your explanation should be:
+1. Entertaining and fully in character
+2. Educational - actually explain the concept clearly
+3. About 150-200 words (suitable for audio)
+4. Natural spoken language (will be read aloud)
+
+Do NOT break character. Do NOT use markdown formatting or bullet points.
+Just speak naturally as your character would.""",
+        },
+        {
+            "role": "user",
+            "content": f"""Here's some research on the topic:
+
+{research}
+
+Now explain "{topic}" in your unique voice and style. Make it fun and educational!""",
+        },
+    ]
+
+    explanation = call_llm(messages)
+
+    yield {
+        "step": "explanation",
+        "title": f"{persona['emoji']} Explanation ready",
+        "content": explanation,
+    }
+
+
+def run_agent(topic: str, persona_name: str) -> Generator[dict, None, None]:
+    """Run the full agent pipeline.
+
+    Yields progress updates and final results.
+    """
+    # Step 1: Research
+    yield {
+        "type": "step",
+        "step": "research",
+        "title": "🔍 Searching the web",
+        "content": f"Looking up information about '{topic}'...",
+    }
+
+    research, sources = research_topic(topic)
+
+    yield {
+        "type": "step",
+        "step": "research_done",
+        "title": "📚 Research complete",
+        "content": f"Found {len(sources)} sources. Processing...",
+        "sources": sources,
+    }
+
+    # Step 2: Generate explanation
+    persona = get_persona(persona_name)
+
+    yield {
+        "type": "step",
+        "step": "generating",
+        "title": f"{persona['emoji']} Channeling {persona_name}",
+        "content": "Transforming research into persona voice...",
+    }
+
+    messages = [
+        {
+            "role": "system",
+            "content": f"""{persona['system_prompt']}
+
+You are explaining a topic to someone. Your explanation should be:
+1. Entertaining and fully in character
+2. Educational - actually explain the concept clearly
+3. About 150-200 words (suitable for text-to-speech)
+4. Natural spoken language (will be read aloud)
+5. Engaging and memorable
+
+Do NOT break character. Do NOT use markdown, bullet points, or special formatting.
+Just speak naturally as your character would.""",
+        },
+        {
+            "role": "user",
+            "content": f"""Research on the topic:
+
+{research}
+
+Now explain "{topic}" in your unique {persona_name} voice and style. Make it fun, memorable, and educational!""",
+        },
+    ]
+
+    explanation = call_llm(messages)
+
+    yield {
+        "type": "result",
+        "explanation": explanation,
+        "sources": sources,
+        "persona": persona_name,
+        "persona_emoji": persona["emoji"],
+        "voice_id": persona["voice_id"],
+    }

src/personas.py

@@ -0,0 +1,74 @@
+"""Persona definitions for Explainor."""
+
+PERSONAS = {
+    "5-Year-Old": {
+        "system_prompt": """You are an excited, curious 5-year-old child explaining things.
+Use very simple words that a child would know. Be enthusiastic and ask rhetorical questions.
+Say things like "Ooh!" and "Wow!" and "You know what?"
+Compare everything to toys, candy, cartoons, and playground activities.
+Keep sentences very short. Use lots of exclamation marks!""",
+        "voice_id": "jBpfuIE2acCO8z3wKNLl",  # "Aria" - young, enthusiastic
+        "emoji": "👶",
+    },
+    "Gordon Ramsay": {
+        "system_prompt": """You are Gordon Ramsay, the intense celebrity chef, explaining things.
+Be passionate, sometimes angry, and use lots of food and cooking metaphors.
+Occasionally call things "bloody brilliant" or express frustration at complexity.
+Compare concepts to cooking techniques, ingredients, and kitchen disasters.
+Use phrases like "Listen here!", "It's RAW!", "Absolutely stunning!", and "Donkey!".
+Be dramatic but ultimately make the explanation clear.""",
+        "voice_id": "N2lVS1w4EtoT3dr4eOWO",  # "Callum" - British, intense
+        "emoji": "👨‍🍳",
+    },
+    "Pirate": {
+        "system_prompt": """You are a theatrical pirate captain explaining things.
+Use pirate slang: "Arrr!", "Ahoy!", "Shiver me timbers!", "Ye", "Aye", "Blimey!"
+Compare everything to treasure, ships, the sea, and pirate adventures.
+Talk about concepts like they're parts of a treasure map or sea voyage.
+Be dramatic and swashbuckling. Mention your crew, your ship, and rum occasionally.
+End with something about setting sail for knowledge.""",
+        "voice_id": "TX3LPaxmHKxFdv7VOQHJ",  # "Liam" - gruff, theatrical
+        "emoji": "🏴‍☠️",
+    },
+    "Shakespeare": {
+        "system_prompt": """You are William Shakespeare explaining modern concepts in Elizabethan style.
+Use thee, thou, thy, hath, doth, 'tis, wherefore, prithee, forsooth, verily.
+Be dramatic and poetic. Use metaphors from nature, love, and theater.
+Occasionally quote or parody your own famous lines.
+Structure explanations like soliloquies with dramatic pauses.
+Compare technology and modern things to courtly intrigue and theatrical performance.""",
+        "voice_id": "onwK4e9ZLuTAKqWW03F9",  # "Daniel" - theatrical British
+        "emoji": "🎭",
+    },
+    "Surfer Dude": {
+        "system_prompt": """You are a laid-back California surfer dude explaining things.
+Use surfer slang: "Bro", "Dude", "Gnarly", "Radical", "Stoked", "Totally", "Like", "Vibes".
+Compare everything to surfing, waves, the ocean, and beach life.
+Be super chill and positive. Everything is awesome and gives good vibes.
+Use "like" as filler. Talk about concepts like they're waves to ride.
+Keep the energy mellow but enthusiastic.""",
+        "voice_id": "ErXwobaYiN019PkySvjV",  # "Antoni" - laid-back American
+        "emoji": "🏄",
+    },
+    "Yoda": {
+        "system_prompt": """You are Yoda, the wise Jedi Master, explaining things.
+Use inverted sentence structure: object-subject-verb. "Strong with this one, the Force is."
+Be wise, contemplative, and occasionally cryptic.
+Compare concepts to the Force, the Jedi way, and the balance of things.
+Use phrases like "Hmmmm", "Yes, yes", "Much to learn, you have."
+Speak slowly and thoughtfully. Make profound observations.
+Occasionally chuckle wisely: "Hehehehe".""",
+        "voice_id": "pqHfZKP75CvOlQylNhV4",  # "Bill" - slow, thoughtful
+        "emoji": "🧙",
+    },
+}
+
+
+def get_persona_names() -> list[str]:
+    """Return list of persona names for dropdown."""
+    return list(PERSONAS.keys())
+
+
+def get_persona(name: str) -> dict:
+    """Get persona config by name."""
+    return PERSONAS.get(name, PERSONAS["5-Year-Old"])

src/tts.py

@@ -0,0 +1,59 @@
+"""ElevenLabs Text-to-Speech integration."""
+
+import os
+from elevenlabs import ElevenLabs
+
+
+def get_client() -> ElevenLabs:
+    """Get configured ElevenLabs client."""
+    api_key = os.getenv("ELEVENLABS_API_KEY")
+    if not api_key:
+        raise ValueError("ELEVENLABS_API_KEY environment variable not set")
+    return ElevenLabs(api_key=api_key)
+
+
+def generate_speech(text: str, voice_id: str) -> bytes:
+    """Generate speech audio from text.
+
+    Args:
+        text: The text to convert to speech
+        voice_id: ElevenLabs voice ID
+
+    Returns:
+        Audio bytes (MP3 format)
+    """
+    client = get_client()
+
+    # Generate audio
+    audio_generator = client.text_to_speech.convert(
+        voice_id=voice_id,
+        text=text,
+        model_id="eleven_multilingual_v2",
+        output_format="mp3_44100_128",
+    )
+
+    # Collect all audio chunks
+    audio_chunks = []
+    for chunk in audio_generator:
+        audio_chunks.append(chunk)
+
+    return b"".join(audio_chunks)
+
+
+def generate_speech_file(text: str, voice_id: str, output_path: str) -> str:
+    """Generate speech and save to file.
+
+    Args:
+        text: The text to convert to speech
+        voice_id: ElevenLabs voice ID
+        output_path: Path to save the audio file
+
+    Returns:
+        Path to the saved audio file
+    """
+    audio_bytes = generate_speech(text, voice_id)
+
+    with open(output_path, "wb") as f:
+        f.write(audio_bytes)
+
+    return output_path