---
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](YOUR_YOUTUBE_LINK_HERE)

## 🌐 Social Media
[📱 Project Announcement on X/LinkedIn](YOUR_SOCIAL_MEDIA_POST_HERE)

---

**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.

```mermaid
graph LR
    %% Nodes with Icons
    User([fa:fa-user User / Child])
    
    subgraph Frontend_HF [Hugging Face Spaces]
        Gradio[fa:fa-desktop Gradio UI]
    end
    
    subgraph Brain_Blaxel [Blaxel Cloud]
        Agent[fa:fa-robot Blaxel Agent]
        MCP[fa:fa-server MCP Server Host]
    end
    
    subgraph Text_Inference [Text Intelligence]
        LLM_Story[fa:fa-book Story: Gemini 2.5 Pro]
        LLM_Questions[fa:fa-bolt Questions: Hyperbolic]
    end
    
    subgraph Muscle_Modal [Modal.com]
        Flux[fa:fa-image Image: Flux.1-schnell]
    end

    subgraph Audio_API [Audio Services]
        TTS[fa:fa-headphones OpenAI Nova]
    end

    %% Data Flow
    User -- "1. Ask" --> Gradio
    Gradio -- "2. Request" --> Agent
    
    Agent -- "3. Story" --> LLM_Story
    LLM_Story -.-> Agent
    
    %% Parallel Execution Flows
    Agent -- "Task A" --> Flux
    Flux -.-> Agent
    
    Agent -- "Task B" --> MCP
    MCP -- "TTS" --> TTS
    TTS -.-> MCP
    MCP -.-> Agent

    Agent -- "Task C" --> LLM_Questions
    LLM_Questions -.-> Agent
    
    Agent -- "Stream" --> Gradio
    Gradio -- "Show" --> User

    %% Styling
    classDef user fill:#fff,stroke:#333,stroke-width:2px,color:#000;
    classDef frontend fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000;
    classDef blaxel fill:#e3f2fd,stroke:#2196f3,stroke-width:2px,color:#000;
    classDef ai fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000;
    classDef modal fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
    classDef audio fill:#fbe9e7,stroke:#ff5722,stroke-width:2px,color:#000;
    linkStyle default stroke:#000000

    class User user;
    class Gradio frontend;
    class Agent,MCP blaxel;
    class LLM_Story,LLM_Questions ai;
    class Flux modal;
    class TTS audio;
```

### 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)

```mermaid
sequenceDiagram
    participant User
    participant Gradio as app.py<br/>(Gradio UI)
    participant Agent as main.py<br/>(Blaxel Agent)
    participant Gemini as Google Gemini<br/>(Storyteller)
    participant Hyperbolic as Hyperbolic API<br/>(Questions)
    participant Flux as Modal Flux<br/>(Image Gen)
    participant MCP as server.py<br/>(MCP Server)
    participant OpenAI as OpenAI API<br/>(TTS)

    Note over User, Gradio: 1. Input
    User->>Gradio: "Why do birds fly?" (Age: 5)
    
    Note over Gradio, Agent: 2. Orchestration Request
    Gradio->>Agent: POST /generate (SSE Stream)

    Note over Agent, Gemini: 3. Story Generation
    Agent->>Gemini: generate_content(prompt)
    Gemini-->>Agent: { "story": "Birds have wings...", "image_prompt": "Bird flying..." }
    Agent->>Gradio: Stream Story Text

    Note over Agent, Flux: 4. PARALLEL EXECUTION START
    
    par Task A: Image Generation
        Agent->>Flux: generate_image.remote(prompt)
        Flux-->>Agent: Image Bytes (PNG)
        Agent->>Gradio: Stream Image (Base64)
    and Task B: Audio Generation (via MCP)
        Agent->>MCP: call_tool("narrate_text", text)
        MCP->>OpenAI: audio.speech.create(text)
        OpenAI-->>MCP: Audio Bytes (MP3)
        MCP-->>Agent: Audio Base64
        Agent->>Gradio: Stream Audio (Base64)
    and Task C: Related Questions
        Agent->>Hyperbolic: chat.completions.create(context_summary)
        Hyperbolic-->>Agent: ["Question 1?", "Question 2?"]
        Agent->>Gradio: Stream Related Questions
    end

    Note over Agent, Gradio: 5. Completion
    Agent->>Gradio: Event: "completed"
    Gradio->>User: Render Full Multimedia Story
```

### 🧠 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.*