README.md

---
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](https://huggingface.co/openbmb/MiniCPM5-1B-GGUF) (OpenBMB) | **1.0 B** | llama.cpp (GGUF Q4_K_M) |
| Voice narration | [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) (hexgrad) | **82 M** | PyTorch |
| Illustration | [SD Turbo](https://huggingface.co/stabilityai/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 →](https://huggingface.co/blog/lulluna-build-small) |

---

## ✨ 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

```bash
# 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)*