---
title: Magical Tales
emoji: 🌟
colorFrom: green
colorTo: yellow
sdk: gradio
sdk_version: 5.32.1
app_file: app.py
pinned: True
thumbnail: assets/images/wizard.png
description: |
  Magical Tales is a Gradio application that uses a range of LLMs and tools to create personalized, immersive stories for children. Customize story types, tones, and more to spark imagination and creativity!
tags: 
   - agent-demo-track
   - mcp-server-track
keywords:
  - gradio
  - Modal
  - Nebius
  - sambanova
  - mistral
  - llamaindex
  - Dia-1.6B
  - Meta musicGen
  - stories
  - children
  - mcp
  - interactive
  - pdf
  - customization
  - imagination
  - creativity
  - agent-demo-track
  - mcp-server-track
repository: agharsallah/magical-tales
---

# 🌟 Magical Tales: Where Imagination Comes Alive! 📚✨

<p align="center">
  <a href="https://huggingface.co/spaces/agharsallah/magical-tales">
    <img src="assets/images/wizard.png" alt="Magical Tales" width="200" style="max-width:100%;height:auto;">
  </a>
</p>

Welcome to Magical Tales, a Gradio application that harnesses the power of SambaNova API to craft personalized, immersive stories for children. Our app is designed to spark imagination and creativity, offering a wide array of customization options to suit various tastes and preferences:

🔹 **Story Crafting**: Choose from diverse story types (Historical, Futuristic, Fantasy), tones (Funny, Enthusiastic, Mysterious), and tailor the narrative based on the child's age, language preference, interests, and the subject of the story.
🔹 **Enhanced Context**: Optionally, upload a PDF document to provide additional context for the story, making it even more personalized and relevant.
🔹 **Interactive Experience**: Built with Gradio, our application offers an intuitive and interactive user interface, making story generation a delightful experience for both children and parents.

## Youtube Video
<p align="center">
  <a href="https://youtu.be/tGcXcd_Kj0Y">
    <img src="https://img.youtube.com/vi/tGcXcd_Kj0Y/maxresdefault.jpg" alt="Magical Tales Demo Video" width="600" style="max-width:100%;height:auto;border-radius:10px;box-shadow:0 4px 8px rgba(0,0,0,0.2);">
    <br>
    <b>✨ Watch Magical Tales in Action! ✨</b>
  </a>
</p>

## 🚀 Getting Started

### ⚙️ Configuration

You can configure the app using environment variables. For example, to set the SambaNova API key, you can use the `SAMBANOVA_API_KEY` environment variable:

   - Through the Gradio web interface in the "API Settings" section
   - By creating a `.env` file in the root directory (check `.env.example` for reference)

   When deploying to Hugging Face Spaces, set this as a Secret in the Settings tab.

See the [Gradio documentation](https://github.com/gradio-app/gradio/blob/main/guides/04_additional-features/10_environment-variables.md#_snippet_20) for more information.

### 🔧 Setup

1. **Installation**: Run the following command to install the required dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. **Running Locally**: Start the application by executing:
   ```bash
   python app.py
   ```

## 🎯 Features

- **🌎 Multi-Language Support**: Generate stories in various languages to cater to a global audience.
- **🎶 Audio Narration**: Listen to the generated stories with integrated audio narration for an immersive experience.
- **🎵 Background Music**: Enjoy background music while listening to the stories, enhancing the overall experience.
- **🎨 Image Generation**: Generate images to accompany the stories, bringing characters and scenes to life.
- **🖥️ Interactive UI**: User-friendly Gradio interface for seamless story generation.
- **📄 PDF Context Integration**: Enhance story generation with additional context from uploaded PDF documents.
- **📝 Customizable Narratives**: Tailor stories based on story type, tone, child's age, language, interests, and subject.

## 🌐 Demo

Experience the magic of our Dynamic Story Generator in action! Check out our live demo [here](https://huggingface.co/spaces/agharsallah/magical-tales).

## 🚀 Deployment

This application is optimized for Hugging Face Spaces. Simply push this repository to a Hugging Face Space and add the `SAMBANOVA_API_KEY` as a Secret in the Space settings.

## 📸 Screenshots

![App Screenshot](assets/demo/magic-story.gif)