---
title: Constellation of Hope
emoji: ✨
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.18.0
python_version: '3.12'
app_file: app.py
pinned: false
short_description: Share a wish and watch it become a star in the cosmos
env:
  GRADIO_WATCH: "false"
tags:
  - track:wood
  - achievement:offgrid
  - achievement:sharing
---

# Constellation of Hope

Share a wish and watch it become a star in a deep-space sky. A small language model transforms each wish into a poetic, wise saying that lives among the constellations — and a whispered voice will read it back to you when you click the star.

Each star in the Three.js starscape represents a hope shared by someone like you. Wishes are moderated, themed, and persisted across restarts.

## What you can do

- **Share a wish** — type a hope into the box, release it to the stars, and watch a new star appear in the sky.
- **Hear the wisdom** — click any star to open its card, then press **▶ Play wisdom** to have the saying whispered back to you.
- **Explore the constellation** — drag to orbit the camera, scroll to zoom. Nearby stars connect into small constellations of up to 5 stars each.
- **See where wishes come from** — each star is stamped with its category (Shape · Boon · Journey · Bond · Tribute) and the date it joined the sky.
- **Gentle moderation** — vulgar or harmful wishes are rewritten into a kind-hearted form before they join the sky; nonsense wishes prompt you to try again, with a soft modal explaining why.

## Models

| Role | Model | Notes |
| ---- | ----- | ----- |
| Wish moderation, theme classification, and poetic generation | [Qwen/Qwen2.5-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct) | A single Qwen call judges the wish (positive / negative / nonsense), tags its theme, and — separately — composes the one- or two-sentence saying. |
| Whispered text-to-speech | [hexgrad/Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) | Voice `af_nicole` at 0.85× speed, dampened amplitude, to feel like a hushed voice from the dark. |

Both models run on Hugging Face's ZeroGPU runtime via `@spaces.GPU` decorators, so the GPU is only allocated when a wish is submitted or wisdom is played.

## Tech stack

- **Gradio 6.18** for the UI shell, state, and component bridges.
- **Three.js 0.160** for the starscape — custom GLSL shader gives each star a fresnel rim, value-noise surface texture, and a phase-offset pulse.
- **`/data` persistent storage** for `stars.json`, so wishes survive restarts.

## Configuration

| Variable | Default | Purpose |
| -------- | ------- | ------- |
| `MODEL_ID` | `Qwen/Qwen2.5-1.5B-Instruct` | Override the language model if you want to swap. |
| `STUB_MODEL` | unset | Local-dev only — set to `1` to skip model loading and use canned sayings. Hard-disabled on Spaces. |