build-small-hackathon/lulluna

🌙 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

🏅 Badge Claims

✨ How to Use

1. 1.Fill in the form on the left: child's name, age, interests, value/theme, cultural tradition, and length.
2. 2.Click ✨ Weave tonight's story — the story appears in ~10 s.
3. 3.Click 🎙️ Narrate to hear it read aloud in a warm voice.
4. 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](https://huggingface.co/build-small-hackathon)