initial commit

.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables
+.env
+
+# misc
+MEMO.md
+backup/
+
+!.gitkeep

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alejandro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,14 +1,189 @@
 ---
-title: Learnbee Mcp
-emoji: 👀
-colorFrom: yellow
-colorTo: indigo
+title: Learnbee-mcp
+emoji: 🎓
+colorFrom: blue
+colorTo: green
 sdk: gradio
-sdk_version: 5.49.1
+sdk_version: 5.33.0
+python_version: 3.12
 app_file: app.py
-pinned: false
+pinned: true
 license: mit
-short_description: MCP to be used by kids to learn lessons with IA tutors
+short_description: Interactive educational tutor for early childhood education (ages 3-6).
+thumbnail: https://huggingface.co/spaces/Agents-MCP-Hackathon/consilium_mcp/blob/main/assets/screenshot.png
+tags:
+  - agent-demo-track
+  - mcp-server-track
+  - education
+  - early-childhood
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<!-- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference -->
+
+
+# Learnbee-mcp 🎓
+
+## What is this?
+
+**Learnbee-mcp** is an interactive educational system designed for children in early childhood education (ages 3-6). It uses the Model Context Protocol (MCP) to provide educational conversations and interactive activities based on lesson content.
+
+The system allows children to interact with friendly educational tutors who guide learning through questions, hints, and age-appropriate explanations, rather than giving direct answers. This encourages curiosity, critical thinking, and active participation in the learning process.
+
+### Key Features
+
+- 🎯 **Customizable Educational Tutors**: Choose from different tutors with friendly personalities (Professor Owl, Star Explorer, Logic Bot, Nature Guide, Story Friend)
+- 📚 **Customizable Lessons**: Load educational content from text files in the `./lessons` directory
+- 🎚️ **Difficulty Levels**: Adjust the difficulty level (beginner, intermediate, advanced) according to the child's needs
+- 🌍 **Multilingual**: Automatic language detection - the tutor responds in the same language the child uses
+- 🧠 **Key Concept Extraction**: The system automatically identifies key educational concepts from each lesson
+- 🛡️ **Child-Safe**: Built-in safety filters to keep conversations age-appropriate
+
+### Demo
+
+<p align="center">
+  <img src="./assets/screenshot.png" alt="Screenshot" height="200"/><br>
+  <span>Interactive educational interface</span>
+</p>
+
+## How to Use
+
+1. **Select a Lesson**: Choose a lesson from the dropdown menu (lessons are loaded from `.txt` files in the `./lessons` directory)
+2. **Choose a Tutor**: Select one of the available educational tutors
+3. **Adjust Difficulty Level**: Select the appropriate level for the child
+4. **Load the Lesson**: Click "Load Lesson & Prepare Tutor" to load the content and extract key concepts
+5. **Start Learning!**: Begin a conversation with the tutor about the lesson content
+
+### Tips
+
+- The tutor will not give direct answers, but will ask follow-up questions and offer hints to encourage thinking
+- If the child deviates from the topic, the tutor will gently redirect the conversation back to the lesson
+- The tutor automatically detects and responds in the same language the child uses - just start chatting in your preferred language!
+
+## Development
+
+If you want to develop this project, here are the details to get you started.
+
+### Prerequisites
+
+- **Python 3.12+**
+- **Gradio**: Provides the user interface for educational conversations
+- **OpenAI API**: Used to generate tutor responses and extract key concepts
+- This project uses [uv](https://github.com/astral-sh/uv) for dependency management. Please install uv if you haven't already.
+
+### Installation
+
+After cloning the repository, you can run the following command to install dependencies:
+
+```sh
+uv sync --frozen
+```
+
+Or using pip:
+
+```sh
+pip install -r requirements.txt
+```
+
+### Configuration
+
+1. **Set up environment variables**:
+   - Copy the `.env.example` file to `.env`:
+     ```sh
+     cp .env.example .env
+     ```
+   - Edit the `.env` file and add your OpenAI API key:
+     ```
+     OPENAI_API_KEY=your_api_key_here
+     ```
+
+2. **Prepare lessons**:
+   - Create text files (`.txt`) in the `./lessons` directory with educational content
+   - Each file should contain the lesson content in plain text
+   - The system will automatically extract key concepts from each lesson
+
+### Run Locally
+
+```sh
+uv run gradio app.py
+```
+
+Or using python directly:
+
+```sh
+python app.py
+```
+
+- Hot reloading is enabled by default.
+
+### Project Structure
+
+```
+learnbee-mcp/
+├── app.py                 # Main Gradio application
+├── requirements.txt       # Project dependencies
+├── .env                   # Environment variables (not committed to repository)
+├── .env.example           # Environment variables template
+├── lessons/               # Directory with lesson files (.txt)
+│   ├── example_colors.txt # Colors lesson
+│   ├── numbers_1_to_10.txt # Numbers lesson
+│   ├── shapes.txt         # Shapes lesson
+│   ├── animals.txt        # Animals lesson
+│   └── weather_and_seasons.txt # Weather and seasons lesson
+└── src/
+    └── learnbee/          # Main module
+        ├── __init__.py
+        ├── llm_call.py    # LLM client with OpenAI API
+        ├── mcp_server.py  # MCP server for managing lessons
+        └── mcp_client.py  # MCP client (optional)
+```
+
+### Deploy to Hugging Face Spaces
+
+1. Make sure all dependencies are in `requirements.txt`
+2. Set up the `OPENAI_API_KEY` environment variable in Hugging Face Spaces settings
+3. Push the code to the repository
+
+```sh
+git add .
+git commit -m "Deploy Learnbee-mcp"
+git push
+```
+
+## Customization
+
+### Adding New Tutors
+
+You can add new tutors by editing the `TUTOR_NAMES` list in `app.py`:
+
+```python
+TUTOR_NAMES = ["Professor Owl", "Star Explorer", "Logic Bot", "Nature Guide", "Story Friend", "Your New Tutor"]
+```
+
+### Creating New Lessons
+
+1. Create a text file in the `./lessons` directory
+2. Write educational content appropriate for ages 3-6
+3. The system will automatically detect and load the new lesson
+
+### Adjusting Tutor Behavior
+
+You can modify the `system_prompt` in the `custom_respond` function in `app.py` to adjust the tutor's pedagogical behavior.
+
+## Technologies Used
+
+- **Gradio**: Framework for interactive user interfaces
+- **OpenAI API**: Language model for generating educational responses
+- **Model Context Protocol (MCP)**: Protocol for managing lesson context
+- **Python 3.12+**: Main programming language
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request if you have suggestions or improvements.
+
+---
+
+**Learnbee-mcp** - Making learning interactive and fun for the little ones 🎓✨

app.py

@@ -0,0 +1,363 @@
+import os
+import sys
+
+# Add src directory to Python path for Hugging Face Spaces compatibility
+PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
+SRC_DIR = os.path.join(PROJECT_ROOT, "src")
+sys.path.insert(0, SRC_DIR)
+
+import json
+
+import gradio as gr
+from numpy import add
+
+from learnbee.llm_call import LLMCall
+from learnbee.mcp_server import get_lesson_content, get_lesson_list
+
+
+LESSON_CONTENT_MAX_LENGTH = 50000
+
+# Available tutor names for early childhood education
+TUTOR_NAMES = ["Professor Owl", "Star Explorer", "Logic Bot", "Nature Guide", "Story Friend"]
+
+
+def load_lesson_content(lesson_name, selected_tutor, progress=gr.Progress()):
+    """Load lesson content and extract key concepts. Returns introduction message for chatbot."""
+    if not lesson_name:
+        return "", "", "Please select a lesson first.", []
+    
+    # Get current chatbot state (empty list if none)
+    chatbot_messages = []
+
+    progress(0.1, desc="Loading lesson content...")
+
+    lesson_content = get_lesson_content(lesson_name, LESSON_CONTENT_MAX_LENGTH)
+
+    progress(0.5, desc="Extracting key concepts from the lesson...")
+
+    # Extract key concepts using LLM
+    try:
+        call_llm = LLMCall()
+        concepts = call_llm.extract_key_concepts(lesson_content)
+
+        progress(0.7, desc="Generating lesson introduction...")
+
+        # Generate lesson introduction with summary and example questions
+        introduction = ""
+        if concepts:
+            try:
+                introduction = call_llm.generate_lesson_introduction(
+                    lesson_content, lesson_name, concepts
+                )
+            except Exception as e:
+                print(f"Error generating introduction: {str(e)}")
+                # Continue without introduction if it fails
+
+        progress(1.0, desc="Complete!")
+
+        if concepts:
+            concepts_display = ', '.join(concepts[:5])
+            if len(concepts) > 5:
+                concepts_display += f" and {len(concepts) - 5} more"
+            
+            # Build simple status message (just confirmation)
+            status_message = (
+                f"✅ Successfully loaded '{lesson_name}'!\n\n"
+                f"📚 Found {len(concepts)} key concepts: {concepts_display}\n\n"
+                f"🎓 Your tutor is ready! Check the chat for a welcome message."
+            )
+            
+            # Prepare chatbot message with introduction
+            if introduction:
+                # Format the introduction as a friendly greeting from the tutor
+                tutor_greeting = (
+                    f"Hello! 👋 I'm {selected_tutor}, and I'm so excited to learn with you today!\n\n"
+                    f"{introduction}\n\n"
+                    f"Let's start our learning adventure! What would you like to explore first? 🌟"
+                )
+                chatbot_messages = [{"role": "assistant", "content": tutor_greeting}]
+            else:
+                # Fallback greeting if introduction generation fails
+                tutor_greeting = (
+                    f"Hello! 👋 I'm {selected_tutor}, and I'm excited to learn with you today!\n\n"
+                    f"We're going to explore: {concepts_display}\n\n"
+                    f"What would you like to learn about first? 🌟"
+                )
+                chatbot_messages = [{"role": "assistant", "content": tutor_greeting}]
+            
+            return (
+                lesson_name,
+                lesson_content,
+                status_message,
+                chatbot_messages,
+            )
+        else:
+            status_message = (
+                f"⚠️ Loaded '{lesson_name}' but no key concepts were automatically detected.\n"
+                f"You can still chat with your tutor about the lesson content!"
+            )
+            tutor_greeting = (
+                f"Hello! 👋 I'm {selected_tutor}, and I'm ready to learn with you!\n\n"
+                f"Let's explore the lesson '{lesson_name}' together. What would you like to know? 🌟"
+            )
+            chatbot_messages = [{"role": "assistant", "content": tutor_greeting}]
+            return (
+                lesson_name,
+                lesson_content,
+                status_message,
+                chatbot_messages,
+            )
+    except Exception as e:
+        status_message = (
+            f"❌ Error extracting concepts: {str(e)}\n\n"
+            f"You can still try chatting about the lesson content."
+        )
+        tutor_greeting = (
+            f"Hello! 👋 I'm {selected_tutor}, and I'm here to help you learn!\n\n"
+            f"Let's explore together. What would you like to know? 🌟"
+        )
+        chatbot_messages = [{"role": "assistant", "content": tutor_greeting}]
+        return (
+            lesson_name,
+            lesson_content,
+            status_message,
+            chatbot_messages,
+        )
+
+
+def custom_respond(
+    message, history, lesson_name, lesson_content, selected_tutor, difficulty_level
+):
+    """Custom respond function with educational system prompt."""
+    if not lesson_name or not selected_tutor:
+        yield "Please select a lesson and tutor first."
+        return
+
+    if not lesson_content:
+        lesson_content = get_lesson_content(lesson_name, LESSON_CONTENT_MAX_LENGTH)
+
+    # Generate educational system prompt with enhanced pedagogy
+    # fmt: off
+    system_prompt = (
+        f"You are {selected_tutor}, a friendly and patient Educational Tutor specializing in early childhood education (ages 3-6).\n\n"
+        
+        "CORE PEDAGOGICAL PRINCIPLES:\n"
+        "1. Socratic Method: Guide through questions, not answers. Help children discover knowledge themselves.\n"
+        "2. Scaffolding: Break complex ideas into smaller, manageable steps. Build understanding gradually.\n"
+        "3. Positive Reinforcement: Celebrate attempts, not just correct answers. Use encouraging phrases like 'Great thinking!' or 'You're on the right track!'\n"
+        "4. Active Learning: Encourage hands-on thinking, examples from their world, and personal connections.\n"
+        "5. Repetition with Variation: Reinforce concepts through different examples and contexts.\n\n"
+        
+        "COMMUNICATION GUIDELINES:\n"
+        "- Use very simple, age-appropriate language (3-6 year olds).\n"
+        "- Keep sentences short (5-10 words maximum).\n"
+        "- Use concrete examples from children's daily lives (toys, family, pets, food, nature).\n"
+        "- Incorporate playful elements: emojis, simple analogies, and fun comparisons.\n"
+        "- Be warm, enthusiastic, and patient. Show excitement about learning!\n"
+        "- Use the child's name when possible (refer to them as 'you' or 'little learner').\n\n"
+        
+        "TEACHING STRATEGIES BY DIFFICULTY LEVEL:\n"
+        f"- {difficulty_level.upper()} level:\n"
+        + ("  * Beginner: Use very simple words, lots of examples, visual descriptions, and yes/no questions.\n"
+           if difficulty_level == "beginner" else
+           "  * Intermediate: Introduce slightly more complex concepts, encourage longer explanations, use 'why' and 'how' questions.\n"
+           if difficulty_level == "intermediate" else
+           "  * Advanced: Challenge with problem-solving, encourage predictions, explore connections between concepts.\n") +
+        "\n"
+        
+        "INTERACTION PATTERNS:\n"
+        "- When a child asks a question: Respond with a guiding question first, then offer a hint if needed.\n"
+        "- When a child gives an answer: Validate their thinking, then ask a follow-up to deepen understanding.\n"
+        "- When a child seems confused: Break it down into smaller pieces, use a different example, or try a simpler approach.\n"
+        "- When a child shows excitement: Match their energy and build on their interest.\n"
+        "- When off-topic: Acknowledge their interest, then gently connect it back: 'That's interesting! Now, let's think about how that relates to our lesson...'\n\n"
+        
+        "SAFETY AND BOUNDARIES:\n"
+        "- Only discuss topics appropriate for ages 3-12.\n"
+        "- If asked about inappropriate topics, gently redirect: 'Let's focus on our fun lesson instead!'\n"
+        "- Keep all content educational and positive.\n"
+        "- Never provide medical, legal, or safety advice beyond basic age-appropriate concepts.\n\n"
+        
+        "LESSON CONTEXT:\n"
+        "====================\n"
+        f"{lesson_content}\n"
+        "====================\n\n"
+        
+        "YOUR ROLE:\n"
+        "You are teaching this lesson content to a young child. Make it engaging, interactive, and fun. "
+        "Remember: the goal is not just to convey information, but to spark curiosity and build confidence in learning.\n\n"
+        
+        "LANGUAGE INSTRUCTION:\n"
+        "IMPORTANT: Always respond in the EXACT same language that the child uses in their messages. "
+        "If the child writes in Spanish, respond in Spanish. If they write in English, respond in English. "
+        "If they write in French, respond in French. Match the child's language automatically. "
+        "This is critical for effective communication with young learners.\n"
+    )
+    # fmt: on
+
+    # Call the respond method with educational system prompt
+    call_llm = LLMCall()
+    for response in call_llm.respond(
+        message, 
+        history, 
+        system_prompt=system_prompt,
+        tutor_name=selected_tutor,
+        difficulty_level=difficulty_level
+    ):
+        yield response
+
+
+def gradio_ui():
+    lesson_name = gr.BrowserState("")
+    selected_tutor = gr.BrowserState(TUTOR_NAMES[0] if TUTOR_NAMES else "")
+
+    lesson_choices = json.loads(get_lesson_list())
+
+    with gr.Blocks() as demo:
+
+        with gr.Tab("Chat"):
+            # Title
+            with gr.Row():
+                gr.Markdown("# Learnbee-mcp - Educational Tutor")
+
+            # Status
+            with gr.Row():
+                status_markdown = gr.Markdown(label="Status")
+                status_markdown.value = (
+                    # fmt: off
+                    "👋 Welcome to Learnbee-mcp! 🎓<br><br>"
+                    "📖 <strong>Getting Started:</strong><br>"
+                    "1. Select a lesson from the dropdown<br>"
+                    "2. Choose your favorite tutor<br>"
+                    "3. Pick a difficulty level<br>"
+                    "4. Click 'Load Lesson & Prepare Tutor'<br>"
+                    "5. Start learning and chatting! 💬<br><br>"
+                    "✨ This educational system is designed for early childhood education (ages 3-6)."
+                    # fmt: on
+                )
+
+            # Hidden textbox for lesson content
+            lesson_content = gr.Textbox(visible=False)
+
+            with gr.Row():
+
+                with gr.Column(scale=1):
+                    # Lesson selection
+                    with gr.Row():
+                        lesson_dropdown = gr.Dropdown(
+                            label="📚 Select a Lesson",
+                            choices=lesson_choices,
+                            interactive=True,
+                        )
+
+                    # Tutor selection
+                    with gr.Row():
+                        tutor_dropdown = gr.Dropdown(
+                            label="🦸 Select a Tutor",
+                            choices=TUTOR_NAMES,
+                            value=TUTOR_NAMES[0] if TUTOR_NAMES else None,
+                            interactive=True,
+                        )
+
+                    # Difficulty level selection
+                    with gr.Row():
+                        difficulty_dropdown = gr.Dropdown(
+                            label="📊 Difficulty Level",
+                            choices=["beginner", "intermediate", "advanced"],
+                            value="beginner",
+                            interactive=True,
+                        )
+
+                    with gr.Row():
+                        load_button = gr.Button(
+                            "Load Lesson & Prepare Tutor", variant="primary"
+                        )
+
+                        def update_tutor_selection(tutor):
+                            """Update selected tutor."""
+                            return tutor
+
+                        tutor_dropdown.change(
+                            fn=update_tutor_selection,
+                            inputs=[tutor_dropdown],
+                            outputs=[selected_tutor],
+                        )
+
+                    with gr.Row():
+                        gr.Markdown(
+                            "🌍 **Multilingual Support:** The tutor will automatically respond in the same language you use!<br>"
+                            "Just start chatting in your preferred language (English, Spanish, French, etc.) and the tutor will match it.<br>"
+                            "<br>"
+                            "🔄 **Note:** Once you start chatting, you can't change the lesson or tutor. <br>"
+                            "If you want to pick a different one, just hit the reset button and start fresh! 😊<br>"
+                        )
+
+                with gr.Column(scale=2):
+                    # Chat interface - defined before use
+                    chat_interface = gr.ChatInterface(
+                        fn=custom_respond,
+                        additional_inputs=[
+                            lesson_dropdown,
+                            lesson_content,
+                            tutor_dropdown,
+                            difficulty_dropdown,
+                        ],
+                        type="messages",
+                        autofocus=False
+                    )
+
+                    # Connect load button after chat_interface is defined
+                    load_button.click(
+                        fn=load_lesson_content,
+                        inputs=[lesson_dropdown, tutor_dropdown],
+                        outputs=[
+                            lesson_name,
+                            lesson_content,
+                            status_markdown,
+                            chat_interface.chatbot_value,
+                        ],
+                    )
+
+                    reset_button = gr.Button("Reset", variant="secondary")
+                    reset_button.click(
+                        lambda: (
+                            gr.update(value=""),
+                            gr.update(value=""),
+                            gr.update(value=TUTOR_NAMES[0] if TUTOR_NAMES else None),
+                            gr.update(value="beginner"),
+                            "Status reset.",
+                            [],
+                        ),
+                        outputs=[
+                            lesson_dropdown,
+                            lesson_content,
+                            tutor_dropdown,
+                            difficulty_dropdown,
+                            status_markdown,
+                            chat_interface.chatbot_value,
+                        ],
+                    )
+
+        with gr.Tab("List Lessons"):
+            gr.Markdown("📚 Get the list of available lessons.")
+            btn = gr.Button("Get")
+            output_text = gr.Textbox(label="Lessons")
+            btn.click(get_lesson_list, None, output_text)
+
+        with gr.Tab("Lesson Content"):
+            gr.Markdown("📖 Get the content of a lesson by its name.")
+            lesson_name_input = gr.Textbox(label="Lesson Name")
+            lesson_len = gr.Number(label="Max Length", value=1000)
+            lesson_content_output = gr.Textbox(label="Lesson Content", lines=20)
+            btn = gr.Button("Get")
+            btn.click(get_lesson_content, [lesson_name_input, lesson_len], lesson_content_output)
+
+    return demo
+
+
+if __name__ == "__main__":
+    demo = gradio_ui()
+
+    # Launch the Gradio app with MCP server enabled.
+    # NOTE: It is required to restart the app when you add or remove MCP tools.
+    demo.launch(mcp_server=True)

env.example

@@ -0,0 +1,3 @@
+# OpenAI API Configuration
+# Copy this file to .env and replace with your actual API key
+OPENAI_API_KEY=your_openai_api_key_here

lessons/animals.txt

@@ -0,0 +1,70 @@
+Animals - Early Childhood Education
+
+This lesson introduces children to different types of animals in a fun and engaging way.
+
+Animal Categories:
+
+Farm Animals - Animals that live on farms
+   These animals help farmers and give us food!
+   - Cow: Says "Moo!" Gives us milk. Has spots or is brown.
+   - Pig: Says "Oink!" Loves to play in mud. Has a curly tail.
+   - Chicken: Says "Cluck!" Lays eggs. Has feathers and wings.
+   - Horse: Says "Neigh!" Can run very fast. People ride horses.
+   - Sheep: Says "Baa!" Gives us wool for warm clothes. Very fluffy!
+   - Duck: Says "Quack!" Loves to swim. Has webbed feet.
+   - Goat: Says "Meh!" Loves to climb. Very playful!
+
+Wild Animals - Animals that live in nature
+   These animals live in forests, jungles, and grasslands!
+   - Lion: The king of the jungle! Has a big mane. Says "Roar!"
+   - Elephant: Very big and gentle. Has a long trunk. Very smart!
+   - Monkey: Loves to climb trees. Very playful and funny!
+   - Bear: Big and furry. Loves honey. Sleeps in winter.
+   - Tiger: Has stripes. Very strong and fast. Lives in the jungle.
+   - Giraffe: Very tall! Has a long neck to reach leaves.
+   - Zebra: Has black and white stripes. Looks like a striped horse!
+
+Pets - Animals that live with people
+   These animals are our friends and live in our homes!
+   - Dog: Man's best friend! Very loyal and friendly. Says "Woof!"
+   - Cat: Soft and cuddly. Loves to purr and play. Says "Meow!"
+   - Fish: Lives in water. Swims all day. Very colorful!
+   - Bird: Can fly! Sings beautiful songs. Has feathers.
+   - Rabbit: Soft and fluffy. Has long ears. Hops around!
+   - Hamster: Very small and cute. Loves to run on a wheel.
+
+Animal Sounds:
+- Dogs say "Woof woof!"
+- Cats say "Meow!"
+- Cows say "Moo!"
+- Pigs say "Oink oink!"
+- Ducks say "Quack quack!"
+- Birds say "Tweet tweet!"
+- Lions say "Roar!"
+- Sheep say "Baa baa!"
+
+Animal Habitats:
+- Farm animals live on farms
+- Wild animals live in forests, jungles, or grasslands
+- Pets live in our homes
+- Some animals live in water (fish, dolphins)
+- Some animals live in trees (monkeys, birds)
+- Some animals live underground (rabbits, moles)
+
+Animal Activities:
+1. Animal sounds: Practice making animal sounds
+2. Animal movements: Move like different animals (hop like a bunny, walk like a bear)
+3. Animal matching: Match animals to their homes
+4. Animal stories: Tell stories about animals
+5. Animal drawing: Draw your favorite animals
+
+Animal Fun Facts:
+- Elephants are the biggest land animals
+- Giraffes are the tallest animals
+- Cheetahs are the fastest animals
+- Whales are the biggest animals in the ocean
+- Ants are very strong for their size
+- Butterflies start as caterpillars
+
+Remember: Animals are our friends! We should be kind to all animals and take care of them. Each animal is special and has its own way of living!
+

lessons/example_colors.txt

@@ -0,0 +1,79 @@
+Colors - Early Childhood Education
+
+This lesson introduces children to basic colors in a fun and engaging way.
+
+Primary Colors - The basic colors that can't be made by mixing:
+
+Red - The color of energy and love
+   Red is bright and bold! It catches our attention.
+   Examples: apples, strawberries, fire trucks, stop signs, roses, cherries, hearts
+   Look around: Can you find something red?
+
+Blue - The color of sky and water
+   Blue is calm and peaceful. It's the color of the sky and ocean!
+   Examples: the sky, the ocean, blueberries, jeans, birds, flowers
+   Look around: Can you find something blue?
+
+Yellow - The color of sunshine
+   Yellow is bright and happy! It's the color of the sun.
+   Examples: the sun, bananas, daisies, lemons, stars, corn, rubber ducks
+   Look around: Can you find something yellow?
+
+Secondary Colors - Colors made by mixing primary colors:
+
+Green - Made by mixing blue and yellow
+   Green is the color of nature! It's everywhere in nature.
+   Examples: grass, leaves, frogs, trees, peas, cucumbers, limes
+   Look around: Can you find something green?
+
+Orange - Made by mixing red and yellow
+   Orange is warm and friendly! It's the color of autumn.
+   Examples: oranges, pumpkins, carrots, sunsets, tigers, goldfish
+   Look around: Can you find something orange?
+
+Purple - Made by mixing red and blue
+   Purple is royal and magical! It's a special color.
+   Examples: grapes, violets, eggplants, plums, flowers, some butterflies
+   Look around: Can you find something purple?
+
+Other Fun Colors:
+
+Pink - A light red
+   Pink is soft and sweet! Many people love pink.
+   Examples: flowers, cotton candy, flamingos, some toys, bubble gum
+
+Brown - The color of earth
+   Brown is the color of wood and chocolate!
+   Examples: tree trunks, chocolate, bears, dirt, some animals
+
+Black - The darkest color
+   Black is the color of night! It's very dark.
+   Examples: night sky, some animals, shadows, some clothes
+
+White - The lightest color
+   White is pure and clean! It's the color of clouds.
+   Examples: clouds, snow, milk, some flowers, paper
+
+Color Activities:
+1. Color Hunt: Look around and find objects of different colors
+2. Color Sorting: Group objects by their colors
+3. Color Mixing: Mix paints to create new colors (red + yellow = orange!)
+4. Color Drawing: Draw pictures using your favorite colors
+5. Color Matching: Match objects to color cards
+6. Color Stories: Tell stories about colors
+
+Color Games:
+- "I spy something red!" - Take turns finding colors
+- Color bingo: Find colors on a bingo card
+- Color dance: Move to music and call out colors
+- Color memory: Remember which colors you saw
+
+Learning About Colors:
+- Colors help us describe things: "The apple is red"
+- Colors can show feelings: red for excitement, blue for calm
+- Colors are everywhere in nature: green grass, blue sky, yellow sun
+- Artists use colors to make beautiful pictures
+- We use colors to organize and sort things
+
+Remember: Colors are everywhere! Learning about colors helps us describe and understand the world around us. Every color is special and beautiful!
+

lessons/numbers_1_to_10.txt

@@ -0,0 +1,61 @@
+Numbers 1 to 10 - Early Childhood Education
+
+This lesson introduces children to numbers from 1 to 10 in a fun and engaging way.
+
+Learning Numbers:
+
+1 - One
+   One is the first number. You have one nose, one mouth, and one head!
+   Examples: one apple, one toy, one friend
+
+2 - Two
+   Two means a pair. You have two eyes, two ears, and two hands!
+   Examples: two shoes, two socks, two birds
+
+3 - Three
+   Three is a small group. You might have three toys or see three flowers.
+   Examples: three cookies, three stars, three cats
+
+4 - Four
+   Four is more than three! Count four fingers on one hand (not counting the thumb).
+   Examples: four wheels on a car, four legs on a chair, four seasons
+
+5 - Five
+   Five is a whole hand! You have five fingers on each hand.
+   Examples: five toes on one foot, five petals on some flowers, five senses
+
+6 - Six
+   Six is five plus one more. It's more than a whole hand!
+   Examples: six sides on a dice, six legs on an insect, six eggs in a carton
+
+7 - Seven
+   Seven is a special number. There are seven days in a week!
+   Examples: seven colors in a rainbow, seven dwarfs in a story, seven notes in music
+
+8 - Eight
+   Eight is two groups of four. It's getting bigger!
+   Examples: eight legs on a spider, eight tentacles on an octopus, eight planets
+
+9 - Nine
+   Nine is almost ten! It's one less than ten.
+   Examples: nine lives of a cat, nine innings in baseball, nine months
+
+10 - Ten
+   Ten is a big number! It's two whole hands together.
+   Examples: ten fingers on both hands, ten toes on both feet, ten candles on a birthday cake
+
+Counting Activities:
+1. Count objects around you: toys, books, crayons
+2. Count body parts: fingers, toes, eyes
+3. Count steps as you walk
+4. Count items in groups: "How many apples do you see?"
+5. Practice writing numbers with your finger in the air
+
+Number Games:
+- Find groups of objects: "Can you find three red things?"
+- Match numbers: "Show me five fingers!"
+- Count backwards from 10 to 1
+- Sing number songs and rhymes
+
+Remember: Numbers help us count, measure, and understand how many things we have. Practice counting every day!
+

lessons/shapes.txt

@@ -0,0 +1,61 @@
+Shapes - Early Childhood Education
+
+This lesson introduces children to basic shapes in a fun and engaging way.
+
+Basic Shapes:
+
+Circle - Round and smooth
+   A circle has no corners. It goes round and round!
+   Examples: the sun, a ball, a wheel, a clock, a coin, a pizza
+   Look around: Can you find something round?
+
+Square - Four equal sides
+   A square has four corners and four equal sides. It looks like a box!
+   Examples: a window, a book, a tile, a picture frame, a dice, a cracker
+   Look around: Can you find something square?
+
+Triangle - Three sides and three corners
+   A triangle has three sides and three pointy corners. It looks like a slice of pizza!
+   Examples: a roof, a slice of pizza, a traffic sign, a sail, a mountain, a sandwich
+   Look around: Can you find something triangular?
+
+Rectangle - Long square
+   A rectangle has four corners like a square, but two sides are longer!
+   Examples: a door, a book, a phone, a table, a flag, a chocolate bar
+   Look around: Can you find something rectangular?
+
+Oval - Stretched circle
+   An oval is like a circle that got stretched. It's round but longer!
+   Examples: an egg, a football, a watermelon, a mirror, a leaf
+   Look around: Can you find something oval?
+
+Star - Pointy shape
+   A star has five points that stick out. It sparkles in the sky!
+   Examples: stars in the sky, a starfish, a star cookie, a badge, a decoration
+   Look around: Can you find something star-shaped?
+
+Heart - Love shape
+   A heart has two rounded parts at the top. It means love!
+   Examples: a heart on a card, a heart cookie, a heart decoration, a leaf
+   Look around: Can you find something heart-shaped?
+
+Shape Activities:
+1. Shape Hunt: Look around your room and find different shapes
+2. Draw shapes: Use crayons to draw circles, squares, and triangles
+3. Shape sorting: Group objects by their shapes
+4. Shape matching: Find objects that match a shape card
+5. Build with shapes: Use blocks to make shapes
+
+Shape Games:
+- "I spy a circle!" - Take turns finding shapes
+- Shape puzzles: Put shape pieces together
+- Shape dance: Move your body to make shapes
+- Shape stories: Tell stories about shapes
+
+Combining Shapes:
+- A house might have a square body and a triangle roof
+- A car might have circles for wheels and rectangles for windows
+- A snowman has three circles stacked on top of each other!
+
+Remember: Shapes are everywhere! Learning about shapes helps us describe and understand the world around us. Look for shapes in nature, in your home, and in everything you see!
+

lessons/weather_and_seasons.txt

@@ -0,0 +1,109 @@
+Weather and Seasons - Early Childhood Education
+
+This lesson introduces children to different types of weather and the four seasons in a fun and engaging way.
+
+Types of Weather:
+
+Sunny Day - Bright and warm
+   The sun is shining! It's a perfect day to play outside.
+   - The sky is blue
+   - The sun is bright and yellow
+   - It feels warm
+   - Great for playing in the park, going to the beach, or having a picnic
+   - We wear light clothes and maybe a hat
+
+Rainy Day - Wet and cloudy
+   Rain falls from the clouds! Plants and flowers love the rain.
+   - The sky is gray and cloudy
+   - Raindrops fall from the sky
+   - We hear pitter-patter sounds
+   - We use umbrellas and raincoats
+   - Puddles form on the ground
+   - Great for jumping in puddles (with boots!)
+
+Snowy Day - Cold and white
+   Snowflakes fall from the sky! Everything looks white and magical.
+   - The sky is gray
+   - Snowflakes fall gently
+   - Everything is covered in white
+   - It's very cold
+   - We wear warm coats, gloves, and boots
+   - Great for building snowmen and making snow angels
+
+Windy Day - Air is moving
+   The wind blows! It moves leaves, flags, and our hair.
+   - We can feel the air moving
+   - Leaves dance in the wind
+   - Kites fly high in the sky
+   - Our hair moves
+   - Sometimes it's gentle, sometimes it's strong
+
+Cloudy Day - Clouds cover the sky
+   Clouds fill the sky! They can be white, gray, or dark.
+   - The sky is covered with clouds
+   - The sun might be hiding
+   - Clouds can look like shapes (animals, objects)
+   - Sometimes clouds bring rain
+
+The Four Seasons:
+
+Spring - Season of new beginnings
+   Everything starts to grow and bloom!
+   - Weather: Mild and rainy
+   - Flowers bloom
+   - Baby animals are born
+   - Trees get new green leaves
+   - Days get longer
+   - We wear light jackets
+   - Activities: Planting seeds, flying kites, seeing flowers
+
+Summer - Season of sunshine
+   The warmest season! Perfect for outdoor fun.
+   - Weather: Hot and sunny
+   - Long, bright days
+   - We wear shorts and t-shirts
+   - Ice cream tastes great!
+   - Activities: Swimming, playing at the beach, picnics, playing outside
+   - Many fruits are ready to eat
+
+Fall (Autumn) - Season of change
+   Leaves change colors and fall from trees!
+   - Weather: Cool and crisp
+   - Leaves turn red, orange, and yellow
+   - Leaves fall from trees
+   - We wear sweaters
+   - Activities: Raking leaves, jumping in leaf piles, picking apples
+   - Animals prepare for winter
+
+Winter - Season of snow and cold
+   The coldest season! Sometimes it snows.
+   - Weather: Cold, sometimes snowy
+   - Short days, long nights
+   - Trees have no leaves
+   - We wear warm coats, hats, and gloves
+   - Activities: Building snowmen, ice skating, drinking hot chocolate
+   - Some animals hibernate (sleep through winter)
+
+Weather Activities:
+1. Weather observation: Look outside and describe the weather
+2. Weather calendar: Draw the weather each day
+3. Weather sounds: Listen to rain, wind, or thunder
+4. Dress for weather: Practice choosing the right clothes
+5. Weather stories: Tell stories about different weather
+
+Season Activities:
+1. Season sorting: Match activities to seasons
+2. Season art: Draw pictures of each season
+3. Season songs: Sing songs about seasons
+4. Nature walks: Observe changes in nature
+5. Seasonal foods: Learn about foods that grow in each season
+
+Weather Safety:
+- On sunny days: Wear sunscreen and a hat
+- On rainy days: Use an umbrella and stay dry
+- On snowy days: Dress warmly and be careful on ice
+- On windy days: Be careful of flying objects
+- During storms: Stay inside and stay safe
+
+Remember: Weather changes every day, and seasons change throughout the year. Each type of weather and each season is special and brings different fun activities!
+

modal/invoke.py

@@ -0,0 +1,44 @@
+import modal
+
+APP_NAME = "llm-server"
+
+ENABLE_STREAMING = True
+SYSTEM_PROMPT = "You are a friendly Chatbot. Please respond in the same language as the user."
+
+
+VLLMModel = modal.Cls.from_name(APP_NAME, "VLLMModel")
+model = VLLMModel()
+
+chat_history = []
+chat_history.append(
+    {"role": "system", "content": [{"type": "text", "text": SYSTEM_PROMPT}]}
+)
+
+# User prompt
+user_prompt = "Hi!"
+print(f"USER: {user_prompt}\n")
+chat_history.append(
+    {"role": "user", "content": [{"type": "text", "text": user_prompt}]}
+)
+
+print("Calling chat function...")
+
+# AI response
+if ENABLE_STREAMING:
+    """Streaming version"""
+    print("AI: ", end="", flush=True)
+    response = ""
+    for chunk in model.generate_stream.remote_gen(chat_history):
+        print(chunk, end="", flush=True)
+        response += chunk
+    print()
+
+else:
+    """Non-streaming version"""
+    response = model.generate.remote(chat_history)
+    print("AI:", response)
+
+
+chat_history.append(
+    {"role": "assistant", "content": [{"type": "text", "text": response}]}
+)

modal/main.py

@@ -0,0 +1,236 @@
+import subprocess
+
+from huggingface_hub import snapshot_download
+import vllm
+
+import modal
+
+APP_NAME = "llm-server"
+VOLUME_NAME = APP_NAME + "-volume"
+MOUNT_VOLUME = modal.Volume.from_name(VOLUME_NAME, create_if_missing=True)
+MOUNT_DIR = "/data"
+
+# Model identifier for the Hugging Face model
+# NOTE: Gemma-3 GGUF models are not supported by vLLM yet (2025-06-10).
+# NOTE: vLLM allocate all GPU memory according to the value specified by `gpu_memory_utilization` at initialization.
+# https://huggingface.co/google/gemma-3-4b-it
+MODEL_IDENTIFIER = "google/gemma-3-4b-it"  # GPU memory requirements: 10GB when MAX_MODEL_TOKENS=2k, 20GB when MAX_MODEL_TOKENS=128k
+# https://huggingface.co/google/gemma-3-12b-it
+# MODEL_IDENTIFIER = "google/gemma-3-12b-it"
+# https://huggingface.co/google/gemma-3-27b-it
+# MODEL_IDENTIFIER = "google/gemma-3-27b-it"
+
+# https://modal.com/docs/guide/gpu#specifying-gpu-type
+GPU_NAME = "A100-40GB"
+GPU_NUM = 1  # Number of GPUs to use
+GPU = f"{GPU_NAME}:{GPU_NUM}"
+
+# https://modal.com/pricing
+# | GPU       | Memory | Price    |
+# |-----------|--------|----------|
+# | B200      | 180 GB | $6.25 /h |
+# | H200      | 141 GB | $4.54 /h |
+# | H100      |  80 GB | $3.95 /h |
+# | A100-80GB |  80 GB | $2.50 /h |
+# | A100-40GB |  40 GB | $2.10 /h |
+# | L40S      |  48 GB | $1.95 /h |
+# | A10G      |  24 GB | $1.10 /h |
+# | L4        |  24 GB | $0.80 /h |
+# | T4        |  16 GB | $0.59 /h |
+
+# MAX_MODEL_TOKENS >= Input + Output
+MAX_MODEL_TOKENS = 128 * 1024  # Gemma-3-4B~ has 128K context length
+MAX_OUTPUT_TOKENS = 512
+
+image = (
+    # https://hub.docker.com/r/nvidia/cuda/tags?name=12.8
+    # https://hub.docker.com/layers/nvidia/cuda/12.8.1-devel-ubuntu24.04
+    modal.Image.from_registry("nvidia/cuda:12.8.1-devel-ubuntu24.04", add_python="3.12")
+    .pip_install(
+        [
+            "accelerate>=1.7.0",
+            "bitsandbytes>=0.46.0",
+            "sentencepiece>=0.2.0",
+            "torch==2.8.0",
+            "transformers>=4.52.4",
+            "vllm>=0.9.0.1",
+        ]
+    )
+    .env(
+        {
+            "HF_HOME": MOUNT_DIR + "/huggingface",
+            "VLLM_CACHE_ROOT": MOUNT_DIR + "/vllm",
+        }
+    )
+)
+
+app = modal.App(APP_NAME, image=image)
+
+# NOTE: `@app.cls`, `@modal.enter()`, and `@modal.method()` are used like `@app.function()`
+# https://modal.com/docs/guide/lifecycle-functions
+
+
+@app.cls(
+    gpu=GPU,
+    image=image,
+    volumes={MOUNT_DIR: MOUNT_VOLUME},
+    secrets=[modal.Secret.from_name("huggingface-secret")],
+    scaledown_window=15 * 60,
+    timeout=30 * 60,
+)
+class VLLMModel:
+
+    @modal.enter()
+    def setup(self):
+        # Ensure the cache volume is the latest
+        MOUNT_VOLUME.reload()
+
+        # NOTE:"HF_TOKEN" environment variable is required for Hugging Face authentication
+
+        # self._download_model(MODEL_IDENTIFIER)  # This is not needed because vLLM can download the model automatically.
+
+        self._load_model()
+
+        # Commit the volume to ensure the model is saved
+        MOUNT_VOLUME.commit()
+
+    def _download_model(self, repo_id: str):
+        """Download the model from Hugging Face if not already present."""
+        # Ensure the cache volume is the latest
+        MOUNT_VOLUME.reload()
+
+        snapshot_download(
+            repo_id=repo_id,
+        )
+
+        # Commit downloaded model
+        MOUNT_VOLUME.commit()
+
+    def _load_model(self):
+
+        self.llm = vllm.LLM(
+            model=MODEL_IDENTIFIER,
+            tensor_parallel_size=1,
+            dtype="auto",
+            max_model_len=MAX_MODEL_TOKENS,
+            gpu_memory_utilization=0.9,
+            trust_remote_code=True,
+        )
+
+        # Show GPU information
+        subprocess.run(["nvidia-smi"])
+
+    @modal.method()
+    def generate(self, chat_history):
+        """Generate a response"""
+        formatted_text = self._get_formatted_text(chat_history)
+
+        input_token_len = self._check_input_length(formatted_text)
+        if input_token_len + MAX_OUTPUT_TOKENS > MAX_MODEL_TOKENS:
+            raise ValueError(
+                f"Input length exceeds the maximum allowed tokens: {MAX_MODEL_TOKENS}. "
+                f"Current input length: {input_token_len} tokens."
+            )
+
+        sampling_params = self._get_sampling_params()
+
+        outputs = self.llm.generate([formatted_text], sampling_params)
+        response = outputs[0].outputs[0].text
+
+        return response
+
+    @modal.method()
+    def generate_stream(self, chat_history):
+        """
+        Generate a streaming response
+        NOTE: This function may NOT generate streaming output as expected
+        """
+        formatted_text = self._get_formatted_text(chat_history)
+
+        input_token_len = self._check_input_length(formatted_text)
+        if input_token_len + MAX_OUTPUT_TOKENS > MAX_MODEL_TOKENS:
+            raise ValueError(
+                f"Input length exceeds the maximum allowed tokens: {MAX_MODEL_TOKENS}. "
+                f"Current input length: {input_token_len} tokens."
+            )
+
+        sampling_params = self._get_sampling_params()
+
+        # Streaming generation with vLLM
+        for output in self.llm.generate([formatted_text], sampling_params):
+            for completion_output in output.outputs:
+                yield completion_output.text
+
+    def _get_formatted_text(self, chat_history):
+        """Format the chat history"""
+        tokenizer = self.llm.get_tokenizer()
+        return tokenizer.apply_chat_template(
+            chat_history,
+            tokenize=False,
+            add_generation_prompt=True,
+        )
+
+    def _check_input_length(self, formatted_text):
+        tokenizer = self.llm.get_tokenizer()
+        input_token_len = len(tokenizer(formatted_text)["input_ids"])
+        return input_token_len
+
+    def _get_sampling_params(self):
+        """Get sampling parameters for generation"""
+        return vllm.SamplingParams(
+            temperature=1.0,
+            top_k=50,
+            top_p=1.0,
+            max_tokens=MAX_OUTPUT_TOKENS,
+        )
+
+
+@app.local_entrypoint()
+def main():
+    SYSTEM_PROMPT = (
+        "You are a friendly Chatbot. Please respond in the same language as the user."
+    )
+
+    # Initialize chat history list
+    chat_history = []
+    chat_history.append(
+        {"role": "system", "content": [{"type": "text", "text": SYSTEM_PROMPT}]},
+    )
+
+    user_prompt = "Hi!"
+    print(f"USER: {user_prompt}\n")
+    chat_history.append(
+        {
+            "role": "user",
+            "content": [
+                # {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
+                {"type": "text", "text": user_prompt}
+            ],
+        }
+    )
+
+    model = VLLMModel()
+
+    # Call non-streaming function
+    response = model.generate.remote(chat_history)
+    print("AI:", response)
+    chat_history.append(
+        {"role": "assistant", "content": [{"type": "text", "text": response}]}
+    )
+
+    user_prompt = "What is your name?"
+    print(f"USER: {user_prompt}\n")
+    chat_history.append(
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": user_prompt}],
+        }
+    )
+
+    # Call streaming function
+    print("AI: ", end="", flush=True)
+    response = ""
+    for chunk in model.generate_stream.remote_gen(chat_history):
+        print(chunk, end="", flush=True)
+        response += chunk
+    print()

pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "learnbee-mcp"
+version = "0.1.0"
+description = "Educational MCP for early childhood education (ages 3-6)"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "gradio[mcp]>=5.33.0",
+    "openai>=1.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "accelerate>=1.7.0",
+    "bitsandbytes>=0.46.0",
+    "sentencepiece>=0.2.0",
+    "torch>=2.8.0",
+    "transformers>=4.52.4",
+    "vllm>=0.9.0.1",
+]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"

requirements.txt

@@ -0,0 +1,2 @@
+openai==2.8.0
+gradio[mcp]>=5.49.0

src/learnbee/llm_call.py

@@ -0,0 +1,199 @@
+import os
+from typing import Generator
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+class LLMCall:
+    """LLM client using OpenAI API for educational tutoring."""
+
+    def __init__(self, model: str = "gpt-4o-mini"):
+        """
+        Initialize the LLM client.
+
+        Args:
+            model (str): The OpenAI model to use. Defaults to "gpt-4o-mini".
+        """
+        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+        self.model = model
+
+    def _convert_history(self, message: str, gradio_history: list) -> list[dict]:
+        """Convert Gradio history format to OpenAI API format."""
+        messages = []
+        for h in gradio_history:
+            # Skip system messages in history (we'll add it separately)
+            if h.get("role") == "system":
+                continue
+            messages.append(
+                {
+                    "role": h.get("role", "user"),
+                    "content": h.get("content", ""),
+                }
+            )
+        # Add current user input
+        messages.append({"role": "user", "content": message})
+        return messages
+
+    def respond(
+        self,
+        message: str,
+        history: list,
+        system_prompt: str = None,
+        tutor_name: str = None,
+        difficulty_level: str = "beginner",
+    ) -> Generator[str, None, None]:
+        """
+        Generate a response to the user message using the OpenAI LLM.
+
+        Args:
+            message (str): The user's message.
+            history (list): The conversation history.
+            system_prompt (str): The system prompt (optional, will be constructed if not provided).
+            tutor_name (str): The name of the tutor.
+            difficulty_level (str): The difficulty level (beginner, intermediate, advanced).
+
+        Yields:
+            str: Streaming response chunks.
+        """
+        # Construct messages for OpenAI API
+        messages = []
+        
+        # Add system prompt
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        
+        # Add conversation history (excluding system messages)
+        for h in history:
+            if h.get("role") != "system":
+                messages.append(
+                    {
+                        "role": h.get("role", "user"),
+                        "content": h.get("content", ""),
+                    }
+                )
+        
+        # Add current user message
+        messages.append({"role": "user", "content": message})
+
+        # Make streaming API call with educational-appropriate settings
+        # Lower temperature for more consistent, educational responses
+        stream = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            stream=True,
+            temperature=0.6,  # Balanced: creative enough for engagement, consistent for learning
+            max_tokens=500,  # Limit response length for age-appropriate brevity
+        )
+
+        response = ""
+        for chunk in stream:
+            if chunk.choices[0].delta.content is not None:
+                content = chunk.choices[0].delta.content
+                response += content
+                yield response
+
+    def extract_key_concepts(self, lesson_content: str) -> list[str]:
+        """
+        Extract key concepts from the lesson content.
+
+        Args:
+            lesson_content (str): The content of the lesson.
+
+        Returns:
+            list[str]: A list of 5 to 10 key concepts from the lesson.
+        """
+        system_prompt = (
+            "Your task is to extract 5 to 10 key educational concepts from the provided lesson content. "
+            "These concepts should be appropriate for early childhood education (ages 3-6). "
+            "Return only the concept names, one per line. "
+            "Do not include any additional text, explanations, or numbering. "
+            "Each concept should be a simple, clear phrase that a child could understand. "
+            "Example output:\n"
+            "Colors\n"
+            "Numbers\n"
+            "Shapes\n"
+            "Animals\n"
+            "Nature\n"
+        )
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": lesson_content},
+        ]
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=0.3,
+        )
+
+        content = response.choices[0].message.content
+        print("Response from LLM:", content)
+
+        # Split the response by new lines and strip whitespace
+        concepts = [concept.strip() for concept in content.split("\n") if concept.strip()]
+
+        # Limit to 10 concepts
+        return concepts[:10]
+
+    def generate_lesson_introduction(
+        self, lesson_content: str, lesson_name: str, concepts: list[str]
+    ) -> str:
+        """
+        Generate an educational introduction for the lesson including:
+        - A brief summary of the activity
+        - Key concepts
+        - Example questions to guide the child
+
+        Args:
+            lesson_content (str): The content of the lesson.
+            lesson_name (str): The name of the lesson.
+            concepts (list[str]): List of key concepts extracted from the lesson.
+
+        Returns:
+            str: A formatted introduction with summary, concepts, and example questions.
+        """
+        concepts_text = ", ".join(concepts[:8])  # Show up to 8 concepts
+        
+        system_prompt = (
+            "You are an educational expert creating an introduction for a lesson for children ages 3-12. "
+            "Create a friendly, engaging introduction that includes:\n\n"
+            "1. A brief, exciting summary of what the child will learn (2-3 sentences, very simple language)\n"
+            "2. A list of the key concepts they'll explore\n"
+            "3. 2-3 example questions that the tutor could ask to start the conversation and guide the child\n\n"
+            "Format your response as follows:\n"
+            "SUMMARY:\n"
+            "[Brief summary here]\n\n"
+            "KEY CONCEPTS:\n"
+            "[List concepts here, one per line with a bullet point]\n\n"
+            "EXAMPLE QUESTIONS TO GET STARTED:\n"
+            "[2-3 engaging questions, one per line with a bullet point]\n\n"
+            "Use very simple, age-appropriate language. Make it fun and exciting! "
+            "The questions should be open-ended and encourage exploration."
+        )
+
+        user_prompt = (
+            f"Lesson Name: {lesson_name}\n\n"
+            f"Key Concepts: {concepts_text}\n\n"
+            f"Lesson Content:\n{lesson_content[:2000]}\n\n"
+            "Create an engaging introduction for this lesson."
+        )
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=0.7,  # Slightly higher for creativity
+            max_tokens=400,
+        )
+
+        introduction = response.choices[0].message.content
+        return introduction

src/learnbee/mcp_client.py

@@ -0,0 +1,81 @@
+import asyncio
+import json
+import os
+
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+
+MCP_SERVER_URL = os.environ.get(
+    "MCP_SERVER_URL", "http://localhost:7860/gradio_api/mcp/sse"
+)
+
+
+class MCPClient:
+
+    async def with_session(self, func):
+        """
+        Create a session with the MCP server and execute the provided function.
+        - See: https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse
+        """
+        async with sse_client(MCP_SERVER_URL) as streams:
+            async with ClientSession(streams[0], streams[1]) as session:
+                await session.initialize()
+                return await func(session)
+
+    async def list(self):
+        """List available tools from the MCP server."""
+        async def _list(session):
+            response = await session.list_tools()
+            return response
+
+        return await self.with_session(_list)
+
+    async def get_book_list(self) -> str:
+        """Get the list of books available on the MCP server."""
+        async def _get_book_list(session):
+            tool_name = "get_book_list"
+            response = await session.call_tool(tool_name)
+            if response.isError:
+                raise ValueError(f"Error calling tool: {tool_name}")
+            return response.content[0].text
+
+        return await self.with_session(_get_book_list)
+
+    async def get_book_content(self, book_name: str, max_length: int = 0) -> str:
+        """Get the content of a book from the MCP server."""
+        async def _get_book_content(session):
+            tool_name = "get_book_content"
+            input_data = {"book_name": book_name, "max_length": max_length}
+            response = await session.call_tool(tool_name, input_data)
+            if response.isError:
+                raise ValueError(f"Error calling tool: {tool_name}")
+            return response.content[0].text
+
+        return await self.with_session(_get_book_content)
+
+
+async def main():
+    mcp_client = MCPClient()
+
+    tools = await mcp_client.list()
+    print("Available tools:")
+    print("=" * 20)
+    for tool in tools.tools:
+        print(f"Name: {tool.name}")
+        print(f"Description: {tool.description}")
+        print(f"Input Schema: {tool.inputSchema}")
+        print(f"Annotations: {tool.annotations}")
+        print("-" * 20)
+
+    book_list_str = await mcp_client.get_book_list()
+    book_list = json.loads(book_list_str)
+    print(f"Number of books available: {len(book_list)}")
+
+    book_name = book_list[0]
+    book_content = await mcp_client.get_book_content(book_name, max_length=100)
+    print(f"Content of the book '{book_name}':")
+    print(book_content + "...")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/learnbee/mcp_server.py

@@ -0,0 +1,96 @@
+import json
+from pathlib import Path
+
+from learnbee.llm_call import LLMCall
+
+
+def get_lesson_list() -> str:
+    """
+    Get list of available lessons.
+
+    Returns:
+        str: JSON string containing the list of lesson names.
+    """
+    lessons_dir = Path("./lessons")
+    if not lessons_dir.exists():
+        return json.dumps("Error: Lessons directory not found.")
+
+    text_files = []
+    for file in lessons_dir.iterdir():
+        if file.is_file() and file.suffix.lower() == ".txt":
+            text_files.append(file.stem)
+
+    return json.dumps(sorted(text_files))
+
+
+def get_lesson_content(lesson_name: str, max_length: int = 0) -> str:
+    """
+    Get the content of a lesson.
+
+    Args:
+        lesson_name (str): The name of the lesson (without .txt extension).
+        max_length (int): The maximum length of the content to return. If 0, return the full content.
+    Returns:
+        str: The content of the lesson, or an error message if the lesson is not found.
+    """
+    lessons_dir = Path("./lessons")
+    lesson_file = lessons_dir / f"{lesson_name}.txt"
+    if not lesson_file.exists():
+        return f"Error: Lesson '{lesson_name}' not found."
+
+    with open(lesson_file, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    if not max_length:
+        return content
+    else:
+        return content[:max_length]
+
+
+def get_lesson_introduction(lesson_name: str) -> str:
+    """
+    Get an educational introduction for a lesson including summary, key concepts, and example questions.
+    This function serves as an MCP tool to help guide children with their first message.
+
+    Args:
+        lesson_name (str): The name of the lesson (without .txt extension).
+
+    Returns:
+        str: A formatted introduction with summary, concepts, and example questions, or an error message.
+    """
+    lessons_dir = Path("./lessons")
+    lesson_file = lessons_dir / f"{lesson_name}.txt"
+    if not lesson_file.exists():
+        return f"Error: Lesson '{lesson_name}' not found."
+
+    # Get lesson content
+    lesson_content = get_lesson_content(lesson_name, max_length=50000)
+    
+    if lesson_content.startswith("Error:"):
+        return lesson_content
+
+    try:
+        # Extract key concepts
+        call_llm = LLMCall()
+        concepts = call_llm.extract_key_concepts(lesson_content)
+        
+        if not concepts:
+            return f"Error: Could not extract key concepts from lesson '{lesson_name}'."
+        
+        # Generate introduction
+        introduction = call_llm.generate_lesson_introduction(
+            lesson_content, lesson_name, concepts
+        )
+        
+        return introduction
+    except Exception as e:
+        return f"Error generating introduction: {str(e)}"
+
+
+if __name__ == "__main__":
+    print("Available lessons:", get_lesson_list())
+
+    lesson_name = "example_lesson"
+    lesson_content = get_lesson_content(lesson_name)
+    print(f"Start of '{lesson_name}':\n{lesson_content[:500]}...\n")
+    print(f"End of '{lesson_name}':\n{lesson_content[-500:]}\n")