---

title: Aether Garden emoji: 🌙 colorFrom: gray colorTo: purple sdk: gradio sdk_version: 5.50.0 app_file: app.py pinned: true license: mit tags:

• gradio
• agents
• simulation
• three.js
• persistent-world
• hackathon
• thousand-token-wood
• track:wood
• best-agent
• off-brand
• achievement:offbrand
• achievement:fieldnotes
• achievement:sharingiscaring
• modal
• codex
• minicpm
• tiny-model
• tiny-titan
• sponsor:openbmb
• sponsor:modal
• sponsor:openai
• sponsor:codex

---

---

Submission Snapshot

---

The Idea

Most AI demos have amnesia. You type a prompt, get a character sheet, close the tab — and the output dies with the session. There's no world, no history, no consequence.

Aether Garden is the opposite. It's a persistent fantasy realm, built as a leather-bound grimoire you have to open before you're let in — no dashboard, no tab that says "Chat," you turn pages.

When you arrive, the world is already days old. Strangers have already built it. A Joke Dragon became Mayor while you were asleep. The Book of Ages remembers all of it. You summon one strange thing — "a blind cartographer who maps places that don't exist yet" — and hours later, without you watching, the simulation runs. The cartographer meets someone else's Crystal Tree. History writes itself.

Remove the model and the Realm is just a SQLite file full of vibes. The AI is load-bearing by definition — which is exactly what this track asked for.

---

What It Does

The app is a single Gradio Space styled as an illuminated manuscript. Instead of dashboard tabs, visitors turn pages through six spreads:

1. The Realm — an SVG map of eight sacred places, a live chronicle, and a "Realm Pulse" ticker
2. Explore the Realm — step into a location via a Three.js diorama window
3. Book of Ages — every arrival, meeting, world event, and milestone, in styled prose
4. Souls of the Garden — every summoned soul, with backstory, goals, fears, and an evolving memory
5. Bonds and Alliances — a 3D web of relationships the simulation forged on its own
6. Summon a New Soul — describe something strange; the Oracle gives it a name, a face, a home, and eventually enemies

The Summon Pipeline

Visitor description (5–200 words)
        |
MiniCPM3-4B on Modal (A10G)        name, appearance, backstory, goals, fears,
                                    personality, greeting, sacred location
        |
SQLite + WAL                       entity persisted; arrival logged to Book of Ages
        |
SVG world map                      entity appears as a glowing dot at their location
        |
Hourly simulation tick              1 world event + 2-4 entity interactions
(Modal scheduled job)               relationships form; memories compress; lifecycle updates
        |
HF Dataset backup                   world.db snapshot pushed after every tick

Nobody scripts the encounters. The model decides what happens between visits.

---

The Autonomous Simulation — Why It's an Agent

Every hour, whether anyone is watching, Modal runs a 7-step tick:

1. Load world state + active entities
2. Generate 1 world event (natural / social / historical / cosmic / discovery)
3. Generate 2-4 entity interactions (location-weighted, relationship-aware)
4. Update memories for all entities involved (compressed, <=150 words each)
5. Lifecycle transitions (dormant -> legendary, dream fragments, wisdom tags)
6. Write all entries to the Book of Ages
7. Increment world day + push DB snapshot to HF Dataset

This is a closed reasoning-and-action loop with no human in it: the model observes world state, decides what happens, and writes that decision back into persistent state that future reasoning depends on. That's the Best Agent case in one sentence.

A blind cartographer summoned at 2am can meet someone else's Crystal Tree at 4am. You find out when you open the Book.

Estimated cost over the build: ~$68 of $250 Modal credits, including demo-day GPU warm-keeping.

---

First-Run Experience

The world is designed to feel alive on first load:

• 8 sacred locations pre-seeded with lore — the Library of Unfinished Thoughts, the Sea of Forgotten Names, the Clock Forest, and five more
• 10+ starter entities with existing memories, relationships, and history from Day 1
• Book of Ages — every arrival, interaction, world event, and milestone in styled prose
• Autonomous simulation — runs every hour whether anyone is watching

By demo day the Realm has 7+ simulated days of history, 20+ Book entries, and multiple formed relationships — all generated by the model, not hand-written.

---

Try It

Live Space: huggingface.co/spaces/build-small-hackathon/aether-garden

Watch first: Demo video

Local setup:

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # USE_MOCK_AI=true works without Modal
python seed_world.py          # 10 starter entities + sample history
python run_tick.py            # run 3-7x to build simulation history
python app.py                 # -> http://localhost:7860

1. Open the Tome cover, then use page turns or the ribbon table of contents.
2. In The Realm spread, inspect the map and live chronicle.
3. In Explore the Realm, choose a place and step into the diorama window.
4. In Summon a New Soul, create something strange and wait for the Oracle.
5. Check the map and Souls spread. Your creation is now part of the world.
6. Run python run_tick.py. Refresh. New interactions and events appear in the Book.

Step 6 is the key test: the simulation runs without user input, history accumulates, and the world grows whether you are watching or not.

---

Build From Source

Prerequisites: Python 3.11+, a Modal account (for production AI), and a Hugging Face account (for the Space + dataset backup).

# Local development (mock AI - no GPU needed)
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python seed_world.py
python app.py

# Production AI via Modal
pip install modal
modal token new
MODEL_FAMILY=minicpm MODEL_ID=openbmb/MiniCPM3-4B TRUST_REMOTE_CODE=true modal deploy modal_app.py
# Copy the inference URL -> MODAL_INFERENCE_URL in .env, set USE_MOCK_AI=false

# Manual simulation tick (demo prep)
python run_tick.py

---

Technical Notes

Structured AI output. Entity generation, interactions, and world events all require valid JSON. This branch runs MiniCPM3-4B by default — a deliberate tiny-model choice for fast latency and a smaller footprint, while staying comfortably under the 32B cap. Failed parses trigger an automatic retry at lower temperature.

World coherence at scale. Each entity carries a compressed memory_summary (max 150 words) updated after significant events — not a raw log. Interactions are scoped by location. The 8 sacred locations act as narrative containers so the world doesn't sprawl into contradiction.

Persistence across restarts. HF Spaces are ephemeral. The SQLite database is backed up to a private HF Dataset repo after every simulation tick. On startup, the app pulls world.db if the local copy is missing.

Rate limiting. One entity creation per session per 10 minutes. The Realm is collaborative, not a spam funnel. Reading, exploring, and viewing are unlimited.

Entity lifecycle. Active entities participate in simulation. After 7 days without interaction → Dormant. After 30 days dormant → Legendary. Dormant entities in the Valley of Sleeping Giants generate dream fragments for the Book of Ages. Entities at the Hollow Mountain for 14+ days earn a wisdom tag.

Simulation fairness. The Ember Crossroads has 3× interaction probability — it is the crossroads of everything. The Clock Forest ages entities 1.5× faster. The Sea of Forgotten Names grants a secret second name. Location special properties are enforced in both simulation logic and prompts.

Variant switching is environment-driven, no code changes required:

• MiniCPM variant: MODEL_FAMILY=minicpm, MODEL_ID=openbmb/MiniCPM3-4B
• Nemotron variant: MODEL_FAMILY=nemotron, MODEL_ID=nvidia/Llama-3.1-Nemotron-Nano-8B-v1

---

Submission Compliance

---

Prize Mapping

---

Project Layout

.
├── app.py                 Gradio frontend — map, Book of Ages, entity summoning
├── modal_app.py           MiniCPM/Nemotron/Qwen inference + hourly simulation (deploy to Modal)
├── seed_world.py          Pre-populate 10 entities, history, relationships
├── run_tick.py            Manual simulation tick for testing and demo prep
├── world/                 SQLite schema, entities, locations, Book of Ages, relationships
├── ai/                    Prompt templates, entity generation, Modal client, mock fallback
├── simulation/            7-step autonomous tick, lifecycle transitions
├── ui/                    SVG world map, Sacred Places gallery, entity cards, image asset registry, mystical CSS
├── persistence/           HF Dataset backup and restore
├── assets/                Banner, textures, icons (banner.png included)
└── data/                  Local SQLite database (gitignored)

---