---
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 - Technical Summary

## Core Functionality
- Generates stories in English and Arabic with emotional analysis and optional illustrations
- Uses template-based approach with AI models to ensure quality and safety

## Technical Architecture

### Story Generation

#### NLP Pipelines
- **English Text Generation Pipeline**:
  ```python
  pipeline("text-generation", model="EleutherAI/gpt-neo-1.3B", device="cpu")
  ```

- **Arabic Generation**:
  ```python
  # Uses MT5 instead of standard pipeline
  AutoTokenizer.from_pretrained("google/mt5-small")
  AutoModelForSeq2SeqLM.from_pretrained("google/mt5-small")
  ```

- **Sentiment Analysis Pipelines**:
  ```python
  # English
  pipeline("sentiment-analysis", model="distilbert-base-uncased-finetuned-sst-2-english", device="cpu")
  
  # Arabic
  pipeline("sentiment-analysis", model="CAMeL-Lab/bert-base-arabic-sentiment", device="cpu")
  ```

- **Translation Pipelines**:
  ```python
  # Arabic to English
  pipeline("translation", model="Helsinki-NLP/opus-mt-ar-en", device="cpu")
  
  # English to Arabic
  pipeline("translation", model="Helsinki-NLP/opus-mt-en-ar", device="cpu")
  ```

### Visual Generation
- **Image Generation Pipeline**:
  ```python
  pipe = StableDiffusionPipeline.from_pretrained(
      "runwayml/stable-diffusion-v1-5",
      torch_dtype=torch.float16
  )
  ```
- Efficient GPU resource management via @spaces.GPU decorator
- Scene extraction from story content

### Content Safety System
- Multi-layered content filtering
- Regex pattern detection for inappropriate content
- Repetition detection (unique word ratio < 0.4)
- Fallback mechanisms to reliable templates

## Implementation Highlights

### MultilingualStoryGenerator Class
- Central class managing generation in both languages
- Handles language detection, content safety, and sentiment analysis
- Template selection logic based on keyword matching
- Parameter extraction from prompts

### Story Templates
- Three categories: Adventure, Friendship, Fantasy
- Multiple variations in both languages
- Dynamic parameter filling

### GPU Resource Management
- @spaces.GPU decorator for efficient GPU allocation
- Pipeline moved to GPU only when needed for image generation
- Proper cleanup with torch.cuda.empty_cache() and gc.collect()

### Error Handling
- Comprehensive logging system
- Graceful degradation for missing components
- Multiple fallback mechanisms

## Technical Requirements
- Python 3.8+
- CUDA-capable GPU (for image generation)
- Key dependencies: transformers, diffusers, gradio, torch