---
title: Curiosity Storybook
emoji: 🦁
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 6.0.0
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - building-mcp-track-creative
  - mcp-in-action-track-creative
---

# 🦁 Curiosity Storybook

> **MCP's 1st Birthday Hackathon Submission**  
> Tracks: Building MCP (Track 1) + MCP in Action (Track 2)

## 📹 Demo Video
[🎥 Watch Demo on YouTube](https://youtu.be/22J-rUAjF9Y)

## 🌐 Social Media
[📱 Project Announcement on LinkedIn](https://www.linkedin.com/posts/activity-7401015401532530688-pm6S)

## 👥 Team
- **Silvestre-PO** - [Hugging Face Profile](https://huggingface.co/Silvestre-PO)

---

**An AI-powered interactive storybook that answers children's "Why?" questions with multimedia explanations.**

[![Blaxel](https://img.shields.io/badge/Agent-Blaxel-purple)](https://blaxel.ai)
[![Blaxel](https://img.shields.io/badge/MCP-Blaxel-purple)](https://blaxel.ai)
[![Modal](https://img.shields.io/badge/Compute-Modal-green)](https://modal.com)
[![Gemini](https://img.shields.io/badge/LLM-Gemini%202.5%20Pro-blue)](https://deepmind.google/technologies/gemini/)
[![Hyperbolic](https://img.shields.io/badge/LLM-Llama%203.3-orange)](https://hyperbolic.xyz)
[![Flux](https://img.shields.io/badge/Image-Flux.1-red)](https://blackforestlabs.ai/)
[![OpenAI](https://img.shields.io/badge/Audio-OpenAI%20TTS-green)](https://openai.com)
[![Gradio](https://img.shields.io/badge/Frontend-Gradio-orange)](https://gradio.app)

---

## 🎯 What is it?

Curiosity Storybook is a magical educational tool designed for children aged 3-12. Instead of a boring search result, it turns any "Why?" question into a **personalized storybook page** generated in real-time.

It answers questions like *"Why is the sky blue?"* or *"How do airplanes fly?"* with:
1.  📖 **A Story:** An age-appropriate, engaging explanation generated by **Google Gemini 2.5 Pro**.
2.  🎨 **An Illustration:** A beautiful, Pixar-style image generated by **Flux.1-schnell** on **Modal** GPUs.
3.  🔊 **Narration:** A warm voice reading the story aloud using **OpenAI TTS** via a **Blaxel MCP Server**.

## 🗣️ Sample Questions

Try asking these to see the magic happen:
- *"Why is the sky blue?"* (Classic physics)
- *"How do airplanes fly?"* (Engineering)
- *"Why do leaves change color in autumn?"* (Biology)
- *"Where does the sun go at night?"* (Astronomy)
- *"How do fish breathe underwater?"* (Marine biology)

## 🚀 Features

-   **🌍 Multilingual:** Ask in English, Spanish, French, etc., and it responds in the same language!
-   **⚡ Real-time Hybrid Streaming:** Uses parallel execution to generate text, image, and audio simultaneously, reducing latency by 50%.
-   **👶 Age-Adaptive:** Adjusts the complexity of the story based on the child's age (3-12).
-   **🔊 Auto-Narration:** Automatically reads the story for younger children who can't read yet.
-   **🧠 Advanced Context Engineering:** Implements **Compaction** (summarization) and **Relevance Detection** to maintain a coherent conversation without context rot, following [Anthropic's best practices](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
-   **🔒 Production-Ready Security:** Bearer token authentication, rate limiting (per-session + global), and built-in content safety filters.

## 🏗️ Architecture

This project was built for the **MCP's 1st Birthday Hackathon** (Celebrating 1 Year of MCP).

It demonstrates a **Hybrid Architecture**:
-   **Frontend:** Gradio 6 (hosted here on Hugging Face Spaces).
-   **Agent Orchestrator:** [Blaxel](https://blaxel.ai) Agent running **Gemini 2.5 Pro**.
-   **Tooling (MCP):** A Blaxel **Model Context Protocol (MCP)** server providing TTS capabilities.
-   **Heavy Compute:** [Modal](https://modal.com) running **Flux.1-schnell** on A100 GPUs for image generation.

![Architecture Diagram](./assets/architecture.png)

### How it works:
1.  **User** asks a question in the Gradio UI.
2.  **Blaxel Agent** receives the request and prompts **Gemini**.
3.  **Gemini** generates the story text and an image prompt.
4.  **Agent Orchestrator** launches **3 parallel tasks** for maximum performance:
    -   **Task A:** Calls **Modal** to generate the image (Flux.1).
    -   **Task B:** Calls **MCP Server** to generate the audio narration.
    -   **Task C:** Calls **Hyperbolic (Llama 3.3)** to generate related questions instantly using **Compacted Context**.
5.  **Agent** streams all components back to the UI using Server-Sent Events (SSE) as they become available.

### ⚙️ Workflow (Under the Hood)

![Workflow Diagram](./assets/workflow.png)

### 🧠 Context Engineering (Bonus)

We implemented a custom `ConversationContext` class that applies **Context Engineering** principles:

1.  **Compaction:** Instead of feeding raw logs, we generate high-fidelity summaries of the conversation history. This allows **Hyperbolic** to understand the context without consuming excessive tokens.
2.  **Just-in-Time Relevance:** The agent analyzes the user's intent to decide whether to inject previous context (follow-up) or start fresh (new topic), preventing "Context Rot".
3.  **Parallel Contexts:** We maintain separate context windows for the Storyteller (Gemini) and the Question Generator (Hyperbolic), optimizing each for their specific role.

<!--[📄 Read our full Context Engineering Analysis](docs/context_engineering_analysis.md) -->

## 🛠️ Technologies Used

-   **Blaxel:** For hosting the Agent and the MCP Server.
-   **Modal:** For serverless GPU inference (Flux.1).
-   **Google Gemini:** For reasoning and creative writing (Story).
-   **Hyperbolic (Llama 3.3):** For ultra-fast related questions generation.
-   **OpenAI TTS:** For high-quality audio narration.
-   **Gradio:** For the kid-friendly user interface.
-   **FastAPI:** For the backend agent logic.

## 🔧 MCP Server Tools

Our custom MCP Server (`curiosity-tools`) exposes 2 tools via the Model Context Protocol:

### 1. `narrate_text` ✅ **Actively Used**
```python
def narrate_text(text: str, voice: str = "nova") -> str
```
- **Purpose:** Generate audio narration using OpenAI TTS
- **Input:** Story text + voice selection
- **Output:** Base64-encoded MP3 audio
- **Usage:** Called by the agent for every story generation

### 2. `generate_illustration` 📦 **Available**
```python
def generate_illustration(prompt: str) -> str
```
- **Purpose:** Generate illustrations using Modal Flux.1
- **Input:** Image description prompt
- **Output:** Base64-encoded PNG image
- **Note:** Available but bypassed in production (agent calls Modal directly for performance)

**Why the hybrid approach?**
- Audio generation is fast (~2s) → Safe to use via MCP
- Image generation can take 3-5 min on cold start → Direct Modal call prevents gateway timeouts

## 🏆 Hackathon Tracks

This project targets:
-   **Track 1: Building MCP:** We built a custom MCP server on Blaxel with 2 production-ready tools.
-   **Track 2: MCP in Action:** We used the MCP server as a tool within a larger agentic workflow to build a consumer education app.


## 🚀 Phase 2: Roadmap & Future Enhancements

### 📚 Content & Features
- **Interactive Quizzes:** Generate comprehension questions after each story
- **Story Collections:** Save favorite stories into personalized "books"
- **Parent Dashboard:** Track learning progress and topics explored
- **Collaborative Mode:** Multiple children can ask follow-up questions together
- **Video Narration:** Animated characters reading the story (Luma AI / Runway)

### 🎨 UI/UX Enhancements
- **Kid-Friendly Design:**
  - Animated mascot guide (friendly lion character)
  - Colorful theme switcher (Rainbow, Ocean, Forest, Space)
  - Larger fonts and touch-friendly buttons for tablets
  - Celebration animations when stories complete (confetti, stars)
- **Reading Experience:**
  - Page-flip animation for story transitions
  - Highlight text as audio plays (karaoke mode)
  - Adjustable reading speed and voice selection
  - Dark mode for bedtime reading
- **Engagement Features:**
  - Progress badges ("Curious Explorer", "Question Master")
  - Story streak counter (days in a row)
  - Share stories as beautiful PDFs or social cards
  - Print-friendly storybook format

### ⚡ Performance Optimizations
- **Smart Caching:** Cache frequently asked questions (Redis)
- **Predictive Pre-generation:** Start generating related questions while streaming the story
- **Edge Deployment:** Deploy MCP Server closer to users (Cloudflare Workers)
- **Model Quantization:** Use Flux.1-schnell quantized version for 2x faster image generation
- **Streaming Audio:** Stream TTS chunks instead of waiting for full audio

### 🧠 AI Enhancements
- **Multi-Agent Storytelling:** Orchestrate specialized agents with distinct roles:
  - **Writer Agent:** Crafts the narrative structure and plot
  - **Educator Agent:** Ensures scientific accuracy and age-appropriateness
  - **Illustrator Agent:** Designs visual concepts and composition
  - **Editor Agent:** Reviews coherence and educational value
  - **Coordinator Agent:** Manages workflow and quality control
- **Multi-modal Understanding:** Accept voice questions (Whisper API)
- **Visual Learning:** Generate diagrams for complex concepts (Mermaid/D2)
- **Adaptive Difficulty:** Fine-tune story complexity based on child's responses
- **Fact-Checking Layer:** Verify scientific accuracy with retrieval-augmented generation (RAG)
- **Emotion Detection:** Adjust tone based on child's engagement level

### 🌍 Accessibility & Scale
- **Offline Mode:** Download stories for offline reading
- **Text-to-Sign Language:** Generate sign language videos (SignAll API)
- **Dyslexia-Friendly Mode:** OpenDyslexic font + adjustable spacing
- **Multi-platform:** Native iOS/Android apps (React Native)
- **Classroom Edition:** Teacher tools for group learning

### 🔒 Safety & Compliance (Future)
- **Enhanced Content Filtering:** Multi-layer content moderation beyond Gemini's built-in filters
- **COPPA Compliance:** Privacy controls for children under 13
- **Parental Controls:** Approve topics, set time limits, review history
- **Audit Logs:** Comprehensive tracking of all AI-generated content

## 📝 License

This project is licensed under the Apache License 2.0. 

---

*Created with ❤️ by Silvestre-PO for the MCP's 1st Birthday.*