---
title: Bilingual Storyteller & Illustrator
emoji: 📚
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.18.0
app_file: app.py
pinned: false
---

# AI-Powered Bilingual Storyteller & Illustrator

## Overview

This application generates high-quality stories in both English and Arabic with emotional analysis and optional illustrations. It uses a robust template-based approach combined with AI models to ensure culturally appropriate, engaging, and safe content generation.

## Key Features

### 1. Reliable Bilingual Story Generation
- **English Stories**: High-quality narrative generation with emotional analysis
- **Arabic Stories**: Template-based system with culturally appropriate content
- **Automatic Language Detection**: Seamlessly handles input in either language

### 2. Multiple Creation Modes
- **Basic Story Mode**: Generate stories from simple prompts
- **Template Story Mode**: Guided creation using structured templates
- **Visual Story Mode**: Create stories with illustrated scenes

### 3. Advanced Visualization
- Generate scene sequences from stories (1-5 scenes)
- Multiple artistic styles: realistic, anime, fantasy
- Automatic prompt enhancement for better image quality

### 4. Content Safety System
- Multi-layered content filtering to prevent inappropriate material
- Language consistency verification
- Repetition detection to maintain story quality
- Graceful fallbacks to ensure reliable output

## Technical Implementation

### Story Generation Architecture

The system uses a hybrid approach to story generation:

1. **English Generation**:
   - Uses EleutherAI/gpt-neo-1.3B with optimization for storytelling
   - Enhanced with template options for consistency

2. **Arabic Generation**:
   - Template-based system with curated high-quality narratives
   - Dynamic template selection based on prompt analysis
   - Parameter extraction to customize stories
   - Multiple fallback mechanisms to ensure appropriate content

3. **Emotion Analysis**:
   - English: distilbert-based sentiment analysis
   - Arabic: CAMeL-Lab/bert-base-arabic-sentiment when available
   - Cross-lingual sentiment analysis for comprehensive coverage

4. **Translation Capabilities**:
   - Arabic-to-English: Helsinki-NLP/opus-mt-ar-en
   - English-to-Arabic: Helsinki-NLP/opus-mt-en-ar (when available)
   - Used for cross-lingual operations and image generation

### Visual Generation

The application uses Stable Diffusion (runwayml/stable-diffusion-v1-5) for image generation with:

- Efficient GPU resource management
- Scene extraction from story content
- Style-specific prompt enhancement
- Comprehensive error handling

## Usage Instructions

### Basic Story Generation
1. Enter a prompt in English or Arabic
2. Select your desired output language
3. Click "Generate Story"
4. Review your story with emotional analysis

### Template Story Creation
1. Choose a template type (Adventure, Friendship, Fantasy)
2. Fill in the template parameters or use defaults
3. Select output language
4. Generate your customized story

### Visual Storytelling
1. Enter your story prompt
2. Choose output language
3. Select the number of scenes (1-5)
4. Pick your preferred artistic style
5. Generate a story with matching illustrations

## Template System

The application includes a sophisticated template system with:

- **Adventure Templates**: Exploration and discovery narratives
- **Friendship Templates**: Stories about connections and relationships
- **Fantasy Templates**: Tales of magic and extraordinary powers

Each template category includes multiple variations in both languages, ensuring fresh and engaging content each time. The system automatically:

1. Analyzes user prompts for keywords
2. Selects the most appropriate template type
3. Extracts parameters from the prompt when possible
4. Uses default parameters when needed
5. Customizes the selected template for a personalized story

## Safety Features

The application prioritizes content safety through:

1. **Content Filtering**: Detection of inappropriate terms or patterns
2. **Language Consistency**: Verification of output language integrity
3. **Quality Control**: Detection of repetitive or nonsensical content
4. **Fallback Mechanisms**: Multiple layers of backup generation options

## Technical Requirements

- Python 3.8+
- CUDA-capable GPU recommended for image generation
- Dependencies listed in requirements.txt

## Future Enhancements

- Enhanced Arabic image prompt understanding
- Voice narration for stories
- Interactive branching narratives
- Additional language support
- Expanded template library

## License & Acknowledgements

- [Hugging Face Transformers](https://github.com/huggingface/transformers)
- [Diffusers](https://github.com/huggingface/diffusers)
- [CAMeL-Lab](https://huggingface.co/CAMeL-Lab)
- [Gradio](https://github.com/gradio-app/gradio)
- [Helsinki-NLP](https://huggingface.co/Helsinki-NLP)

## Contact

For questions or support, please open an issue in the repository.