StoryForge

🎙️ Talk to create. ✨ Watch it come alive.

A real-time, voice-driven storybook generator powered by Google Gemini.
Speak your ideas. Get illustrated pages. Download your book.

---

🎯 What is StoryForge?

StoryForge lets anyone — especially kids — talk their stories into existence. You speak to Quill, a friendly AI creative companion, who listens to your ideas, asks follow-up questions, and generates a fully illustrated storybook page by page.

"I want a brave little fox who finds a magical forest…"

Quill responds, asks about the fox's name, what the forest looks like, and then — boom — a watercolor-illustrated page appears on screen with narration.

✨ Key Features

🎙️ Voice-First Storytelling Talk naturally with Quill via the Gemini Live API. No typing required — just speak your ideas and watch them become pages. 🎨 AI Illustrations Every page gets a unique illustration generated by Imagen 3, locked to your chosen visual style (watercolor, line art, retro pixel, etc.). 📖 One-Click PDF Export Download your completed storybook as a beautifully formatted PDF with illustrations, page numbers, and a title page.

🛡️ Child-Safe by Design Built-in content safety checks ensure all generated text and images are appropriate for the selected age group (5-8, 9-12, 13-17). 🔊 Story Narration Each page is narrated aloud by a warm storybook narrator voice (separate from Quill's conversational voice), powered by Gemini TTS. ⚡ Real-Time Pipeline Text, illustration, and narration generate in parallel — pages appear in seconds, not minutes.

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     Frontend (React)                    │
│              Voice Input  ←→  Story Display             │
└────────────────────┬────────────────────────────────────┘
                     │ WebSocket + REST APIs
┌────────────────────▼────────────────────────────────────┐
│                   FastAPI Backend                        │
│                                                         │
│  ┌──────────────┐    ┌──────────────┐   ┌────────────┐ │
│  │  Gemini Live  │───▶│ Orchestrator │──▶│   State    │ │
│  │  (Quill 🦉)  │    │  (Pipeline)  │   │  Manager   │ │
│  └──────────────┘    └──────┬───────┘   └────────────┘ │
│                             │                           │
│              ┌──────────────┼──────────────┐            │
│              ▼              ▼              ▼            │
│     ┌──────────────┐ ┌───────────┐ ┌────────────┐      │
│     │ Story Writer  │ │  Imagen   │ │ Narration  │      │
│     │ (Gemini 2.5)  │ │  (Art 🎨) │ │  (TTS 🔊)  │      │
│     └──────────────┘ └───────────┘ └────────────┘      │
└─────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Node.js 20+
• Python 3.11+
• A Google AI API key
• A Firebase Project (for Authentication, Firestore, and Storage)

Setup

# Clone the repo
git clone https://github.com/Ker102/StoryForge.git
cd StoryForge

# Install frontend dependencies
cd client
npm install

# Install backend dependencies
cd ../backend
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

# Configure environment
cp .env.example .env.storyforge
# Edit .env.storyforge and add your API keys + Firebase config

# Run the stack
# Terminal 1 (Backend)
uvicorn app.main:app --reload --port 8000

# Terminal 2 (Frontend)
cd ../client
npm run dev

📁 Project Structure

StoryForge/
├── client/                  # React + Vite frontend
│   ├── src/
│   │   ├── components/      # UI components (StoryReader, loading screens)
│   │   ├── hooks/           # custom audio processing, WebSocket hooks
│   │   └── lib/             # Firebase init
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI app + static routing
│   │   ├── models/              # StoryState, Page, Character
│   │   ├── services/            # Pipeline coordinators & agents
│   │   │   ├── orchestrator.py  # Page generation pipeline
│   │   │   ├── live_session.py  # Gemini Live API (Quill)
│   │   │   ├── story_writer.py  # Gemini 2.5 Flash text gen
│   │   │   ├── firestore_service.py # Firebase Persistence
│   │   │   └── export_service.py    # PDF generation
│   │   ├── routes/
│   │   │   ├── ws.py            # Real-time WebSockets
│   │   │   └── api.py           # REST endpoints
│   ├── pyproject.toml
│   └── ruff.toml

🤖 AI Models Used

Role	Model	Purpose
🦉 Creative Companion	gemini-2.5-flash	System instructed with FunctionTools to intercept story triggers and converse using Live WebSockets
⚡ Story Writer	gemini-2.5-flash	Structured story text generation following user prompts
🎨 Illustrator	imagen-3.0-generate-002	Page illustrations
🔊 Narrator	gemini-2.5-flash-tts-preview	Story narration audio

🛡️ Security & Dependability

• CodeQL scanning on every PR and weekly
• Dependabot for automated dependency updates
• pip-audit for Python dependency vulnerability scanning
• Ruff with bandit security rules enforced in CI
• Firebase Auth securing REST API endpoints via token verification
• See SECURITY.md for vulnerability reporting

🗺️ Roadmap

• Backend scaffold with FastAPI
• AI service integration (Live, Writer, Imagen, TTS)
• WebSocket real-time communication
• CI/CD pipeline + security scanning
• Modern React/Vite Frontend
• Google Login + Firebase Persistence
• Cloud Run Serverless Deployment
• Multi-language story support
• Collaborative storytelling (multiplayer)

📄 License

MIT — see LICENSE for details.

---

Built with ❤️ for the Gemini Live Hackathon