📖 StoryWeaver — AI Interactive Storybook

An AI-powered interactive storytelling platform that generates personalized children's stories with interleaved text, AI-generated illustrations, and character narration — all powered by Google Gemini.

---

✨ Features

Feature	Description
🎨 Interleaved Output	Text and AI-generated illustrations stream together in real-time
🧠 Gemini-Powered	Uses Gemini 2.0 Flash with native multimodal output
🖼️ Imagen 3 Illustrations	Beautiful children's book-style art generated per scene
🔊 Narration	Optional text-to-speech with character voices
🎛️ Real-time Adjustments	Make the story funnier, scarier, or more magical mid-stream
📱 Responsive	Optimized for tablets (the bedtime storytelling device!)

---

🏗️ Architecture

User Input → React Frontend → WebSocket → FastAPI Backend → Gemini API
                                                ↓
                                        [Text] → Stream to client
                                        [IMAGE tag] → Imagen 3 → Cloud Storage → Client
                                        [Audio] → Cloud TTS → Client

Tech Stack

Layer	Technology
Frontend	React 18 + TypeScript + Vite
Backend	FastAPI (Python) + WebSocket
AI Model	Gemini 2.0 Flash (interleaved output)
Image Gen	Imagen 3 via GenAI SDK
Audio	Google Cloud Text-to-Speech
Storage	Cloud Storage (prod) / Local (dev)
Hosting	Cloud Run (auto-scaling)
CI/CD	Cloud Build

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• Google API Key (for Gemini & Imagen)

1. Clone & Setup Backend

cd backend
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

pip install -r requirements.txt
python main.py

The API starts at http://localhost:8080

2. Setup Frontend

cd frontend
npm install
npm run dev

The app opens at http://localhost:5173

3. Use It!

1. Pick a theme (Dragons, Space, Pirates...)
2. Name your character
3. Choose a setting
4. Click "Begin Story" and watch the magic! ✨

---

🔧 Environment Variables

Variable	Description	Default
GOOGLE_API_KEY	API key for Gemini & Imagen	required
DEMO_MODE	Run with pre-built demo story (no API key needed)	false
USE_GCS	Use Cloud Storage for assets	false
GCS_BUCKET_NAME	GCS bucket name	storyweaver-assets
FRONTEND_URL	Frontend URL for CORS	http://localhost:5173

---

🧪 Reproducible Testing Instructions

Quick Test (Demo Mode — No API Key Required)

1. Clone the repo:

   git clone https://github.com/Harsh6425/StoryWeaver.git
   cd StoryWeaver

2. Start the backend:

   cd backend
   pip install -r requirements.txt

   Create a .env file with:

   DEMO_MODE=true
   GOOGLE_API_KEY=any_placeholder
   

   Then run:

   python main.py

3. Start the frontend (in a new terminal):

   cd frontend
   npm install
   npm run dev

4. Test in browser:

   • Open http://localhost:5173
   • Select any theme (e.g., 🐉 Dragons)
   • Type a character name and setting
   • Click "📖 Begin Story"
   • ✅ A complete demo story with illustrations will stream in real-time

Full Test (With API Key)

1. Get a Google API Key
2. Set DEMO_MODE=false and GOOGLE_API_KEY=your_key in backend/.env
3. Restart the backend and generate a story — Gemini will create unique content with AI illustrations

---

☁️ Deploy to Cloud Run

Option A: Cloud Build (CI/CD)

gcloud builds submit --config infrastructure/cloudbuild.yaml

Option B: Direct Deploy

cd backend
gcloud run deploy storyweaver-api \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars USE_GCS=true \
  --set-secrets GOOGLE_API_KEY=storyweaver-api-key:latest

---

📁 Project Structure

storyweaver/
├── backend/
│   ├── main.py              # FastAPI app + WebSocket endpoint
│   ├── gemini_client.py     # Gemini interleaved output handler
│   ├── media_pipeline.py    # Imagen 3 + TTS integration
│   ├── storage.py           # Local & Cloud Storage
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.tsx           # Root layout + WebSocket orchestration
│   │   ├── components/
│   │   │   ├── StoryPlayer.tsx    # Stream renderer
│   │   │   ├── StoryControls.tsx  # Creation controls
│   │   │   └── ImageGallery.tsx   # Illustration gallery
│   │   └── index.css         # Design system
│   ├── index.html
│   └── package.json
├── infrastructure/
│   └── cloudbuild.yaml       # CI/CD pipeline
└── README.md

---

🎬 Demo

1. Start — Parent opens app, child says "I want a story about a robot who eats spaghetti!"
2. Generate — Text streams in: "Once upon a time, there was a robot named Noodle..."
3. Illustrate — AI generates a colorful image of Noodle with spaghetti circuits
4. Adapt — Hit "Make it funnier" and the story adjusts in real-time
5. Enjoy — A complete, illustrated, personalized bedtime story in minutes

---

📜 License

MIT