README.md

metadata

title: Lulluna - Bedtime Story Weaver
emoji: 🌙
colorFrom: purple
colorTo: indigo
sdk: docker
app_port: 7860
pinned: true
license: apache-2.0
tags:
  - gradio
  - llama-cpp
  - text-generation
  - text-to-speech
  - image-generation
  - children
  - storytelling
  - small-models
  - build-small-hackathon
  - minicpm
  - kokoro
  - sd-turbo

🌙 Lulluna — Bedtime Story Weaver

HuggingFace Build Small Hackathon 2026 · Track: Backyard AI

Lulluna solves a nightly challenge for busy parents: "What story do I read tonight?"

In about 10 seconds it weaves a personalized bedtime story tailored to your child's age, name, and interests — drawing from rich traditions like Aesop, Panchatantra, Norse mythology, and African folktales — with a gentle value quietly threaded in and a soft closing line that helps little ones drift off to sleep.

Every story can be narrated aloud in a warm voice and illustrated with a watercolour storybook image — all on-device, with no API keys and no data leaving the machine.

---

🤖 AI Stack — 100% Local, ~1.96 B Parameters Total

Component	Model	Params	Runtime
Story generation	MiniCPM5-1B (OpenBMB)	1.0 B	llama.cpp (GGUF Q4_K_M)
Voice narration	Kokoro-82M (hexgrad)	82 M	PyTorch
Illustration	SD Turbo (Stability AI)	~860 M	Diffusers (4-step)
Total		~1.96 B	All models ≤ 32 B ✓

---

🏅 Badge Claims

Badge	How
🦙 Llama Champion	Story engine uses llama.cpp with GGUF Q4_K_M quantization
🔌 Off the Grid	Zero cloud API calls — all three models run entirely on-device
📓 Field Notes	Read the build log →

---

✨ How to Use

1. Fill in the form on the left: child's name, age, interests, value/theme, cultural tradition, and length.
2. Click ✨ Weave tonight's story — the story appears in ~10 s.
3. Click 🎙️ Narrate to hear it read aloud in a warm voice.
4. Click 🎨 Illustrate to generate a watercolour storybook cover (takes ~30 s).

Traditions available

Aesop · Panchatantra · Jataka · Japanese · African · Norse · Native American · Sufi · Celtic · Arabian · Chinese · Grimm

Values available

Kindness · Courage · Love · Honesty · Patience · Generosity · Friendship · Perseverance · Wisdom · Humility

---

🔌 REST API (companion frontend)

The Space exposes three endpoints for the companion React app:

POST /api/generate
  Request:  {"data": [age, value, tradition, length, name, interests]}
  Response: {"data": [{"title": "...", "emoji": "...", "body": "..."}]}

POST /api/narrate
  Request:  {"data": ["full story text"]}
  Response: {"data": ["{\"audio\": \"<base64 wav>\", \"mime\": \"audio/wav\"}"]}

POST /api/illustrate
  Request:  {"data": ["title", "body"]}
  Response: {"data": ["{\"image\": \"<base64 png>\", \"mime\": \"image/png\"}"]}

---

🛠️ Local Setup

# 1. Clone and enter the backend directory
git clone https://huggingface.co/spaces/YOUR_USERNAME/lulluna
cd lulluna

# 2. Create a venv (Python 3.10+)
python -m venv .venv && source .venv/bin/activate

# 3. Install deps — Metal on Apple Silicon, CUDA on NVIDIA
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python --no-binary llama-cpp-python
pip install -r requirements.txt

# 4. Download the story model (~800 MB, one-time)
python download_model.py

# 5. Launch
python app.py          # → http://localhost:7860

HF Spaces GPU note: Set the Space env var CMAKE_ARGS="-DGGML_CUDA=on" so llama-cpp-python is compiled with CUDA on first boot.

---

📁 Repository Structure

app.py              ← Gradio UI + REST API endpoints
engine.py           ← StoryEngine: loads MiniCPM5-1B via llama-cpp-python
prompts.py          ← System-prompt builder (age / value / tradition)
narrate.py          ← Kokoro-82M TTS (reads stdin → base64 WAV JSON on stdout)
illustrate.py       ← SD Turbo image gen (reads JSON prompt → base64 PNG JSON)
download_model.py   ← One-time model downloader from HF Hub
requirements.txt    ← All Python dependencies (single environment)
packages.txt        ← System packages for HF Spaces (espeak-ng, ffmpeg)

---

Built with ❤️ for the HuggingFace Build Small Hackathon 2026