feat: Final polish for hackathon submission

- Add horizontal badges to frontend UI
- Update README with MCP tools, Phase 2 roadmap, and license
- Fix architecture diagrams (LR layout, contrast, syntax)
- Add footer with hackathon credits

README.md

@@ -29,10 +29,13 @@ tags:
 **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)
 
 ---
 
@@ -45,17 +48,27 @@ It answers questions like *"Why is the sky blue?"* or *"How do airplanes fly?"*
 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:** The agent maintains conversation history and uses it to suggest relevant follow-up questions, creating a continuous learning journey.
+-   **🧠 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 **Hugging Face & MCP Hackathon** (Celebrating 1 Year of Agents).
+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).
@@ -63,6 +76,72 @@ It demonstrates a **Hybrid Architecture**:
 -   **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**.
@@ -70,9 +149,66 @@ It demonstrates a **Hybrid Architecture**:
 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.
+    -   **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.
@@ -83,12 +219,103 @@ It demonstrates a **Hybrid Architecture**:
 -   **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 for audio generation.
+-   **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.*
+

app.py

@@ -81,7 +81,7 @@ async def generate_storybook(question, age, session_id, progress=gr.Progress()):
     current_image = None
     current_audio = None
     related_questions = []  # Context Engineering
-    status_msg = "🚀 Starting..."
+    status_msg = "🚀 **Starting your magical story...**"
     
     # Progress tracking
     progress(0, desc="Starting...")
@@ -233,11 +233,81 @@ label {
 }
 """
 
+''' with gr.Blocks(title="🦁 Curiosity Storybook") as demo:
+    gr.Markdown("""
+# 🦁 Curiosity Storybook
+
+[![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)
+
+### Ask me anything! I'll remember our conversation and suggest related questions. 📚✨💭
+*Works in any language! Each conversation builds on previous questions.*
+""")  '''
+
+# --- 1. Definición del Contenido y Estilos CSS ---
+
+# A. CSS para Adaptabilidad: Permite el salto de línea (wrap)
+COMPRESSION_CSS_ADAPTABLE = """
+<style>
+/* Clase para permitir que los elementos se envuelvan (wrap) naturalmente */
+.compact-badges-adaptable {
+    padding: 0;
+    margin: 0;
+}
+
+/* Estilo para los enlaces (los badges) */
+.compact-badges-adaptable a {
+    /* Es crucial que sean inline-block para que se alineen horizontalmente */
+    display: inline-block !important; 
+    /* Margen entre badges: 4px horizontal, 5px vertical (para separar las filas) */
+    margin: 0px 4px 5px 0px !important; 
+    padding: 0;
+    vertical-align: middle;
+}
+</style>
+"""
+
+# B. Badges Convertidos a HTML Puro para garantizar la visualización
+# Nota: La sintaxis es <a href="URL_DESTINO"><img src="URL_IMAGEN" alt="Texto" style="height: 20px;"></a>
+BADGES_HTML_PURO = """
+<a href="https://blaxel.ai"><img src="https://img.shields.io/badge/Agent-Blaxel-purple" alt="Blaxel Agent" style="height: 20px;"/></a>
+<a href="https://blaxel.ai"><img src="https://img.shields.io/badge/MCP-Blaxel-purple" alt="Blaxel MCP" style="height: 20px;"/></a>
+<a href="https://modal.com"><img src="https://img.shields.io/badge/Compute-Modal-green" alt="Modal Compute" style="height: 20px;"/></a>
+<a href="https://deepmind.google/technologies/gemini/"><img src="https://img.shields.io/badge/LLM-Gemini%202.5%20Pro-blue" alt="Gemini LLM" style="height: 20px;"/></a>
+<a href="https://hyperbolic.xyz"><img src="https://img.shields.io/badge/LLM-Llama%203.3-orange" alt="Llama LLM" style="height: 20px;"/></a>
+<a href="https://blackforestlabs.ai/"><img src="https://img.shields.io/badge/Image-Flux.1-red" alt="Flux Image" style="height: 20px;"/></a>
+<a href="https://openai.com"><img src="https://img.shields.io/badge/Audio-OpenAI%20TTS-green" alt="OpenAI Audio" style="height: 20px;"/></a>
+<a href="https://gradio.app"><img src="https://img.shields.io/badge/Frontend-Gradio-orange" alt="Gradio Frontend" style="height: 20px;"/></a>
+"""
+
+# C. Ensamblamos el contenido final que inyectaremos en gr.HTML
+FULL_HTML_ADAPTABLE = f"""
+{COMPRESSION_CSS_ADAPTABLE}
+<div class="compact-badges-adaptable">
+    {BADGES_HTML_PURO} 
+</div>
+"""
+
+# --- 2. Estructura Principal de Gradio ---
+
 with gr.Blocks(title="🦁 Curiosity Storybook") as demo:
-    gr.Markdown("# 🦁 Curiosity Storybook 🚀")
-    gr.Markdown("### Ask me anything! I'll remember our conversation and suggest related questions. 📚✨💭")
-    gr.Markdown("*Works in any language! Each conversation builds on previous questions.*")
+    gr.Markdown("""
+# 🦁 Curiosity Storybook
+""")
+    
+    # Inyectamos el CSS y el contenido de los badges
+    gr.HTML(FULL_HTML_ADAPTABLE)
+
+    gr.Markdown("""
+---
+### Ask me anything! I'll remember our conversation and suggest related questions. 📚✨💭
+*Works in any language! Each conversation builds on previous questions.*
+""")
+
     
+
+
+
+
     # Session state (invisible to user, persistent across interactions)
     session_state = gr.State(lambda: str(uuid.uuid4()))
     
@@ -245,7 +315,7 @@ with gr.Blocks(title="🦁 Curiosity Storybook") as demo:
         with gr.Column(scale=1):
             question_input = gr.Textbox(
                 label="❓ What are you curious about?", 
-                placeholder="Why is the sky blue?\n¿Por qué brillan las estrellas?\nPourquoi les chats ronronnent?",
+                placeholder="e.g., Why is the sky blue? 🌤️\n¿Por qué brillan las estrellas? ⭐\nPourquoi les chats ronronnent? 🐱",
                 lines=3,
                 max_lines=5
             )
@@ -266,7 +336,7 @@ with gr.Blocks(title="🦁 Curiosity Storybook") as demo:
             )
             
             submit_btn = gr.Button("✨ Tell me a story! ✨", variant="primary", size="lg")
-            status_output = gr.Markdown("🌟 Ready to explore! Ask me anything...")
+            status_output = gr.Markdown("🌟 **Ready to explore!** Ask me anything...")
             
         with gr.Column(scale=2):
             story_output = gr.Markdown(label="📖 Your Story")
@@ -291,6 +361,15 @@ with gr.Blocks(title="🦁 Curiosity Storybook") as demo:
         inputs=[question_input, age_slider],
         label="💡 Try these questions:"
     )
+    
+    # Footer with credits
+    gr.Markdown("""
+---
+### 🏆 Built for MCP's 1st Birthday Hackathon
+
+
+*Featuring Context Engineering with Compaction & Relevance Detection*
+""")
 
     # Event: Submit button click
     submit_btn.click(