| title | Aether Garden | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| emoji | 🌙 | |||||||||||||
| colorFrom | gray | |||||||||||||
| colorTo | purple | |||||||||||||
| sdk | gradio | |||||||||||||
| sdk_version | 5.50.0 | |||||||||||||
| app_file | app.py | |||||||||||||
| pinned | true | |||||||||||||
| license | mit | |||||||||||||
| tags |
|
- Live Space: build-small-hackathon/aether-garden
- Track focus: Thousand Token Wood
- Core model (this branch): MiniCPM3-4B via Modal
- Agent behavior: autonomous hourly simulation tick with memory updates
- Persistent state: SQLite + HF Dataset backup/restore
Most AI demos generate a thing and forget it. You type a prompt, get a character sheet, close the tab — and the output dies with the session. There is no world, no history, no consequence. Judges asked for something different: AI as the product, not a wrapper around a static response.
Aether Garden is the opposite. When you open it, 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. You add 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.
A visitor opens an ancient leather-bound grimoire. Instead of navigating dashboard tabs, they turn pages through six spreads: The Realm, Explore the Realm, Book of Ages, Souls of the Garden, Bonds and Alliances, and Summoning. Each page is tied to the same persistent world state. Summoning something new triggers a full AI pipeline:
Visitor description (5–200 words)
|
MiniCPM 3-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 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. Remove inference and the Realm is just a database of text — the AI is load-bearing by definition.
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
On demo day, the target state is 7+ simulated days of history, 20+ Book entries, and at least 3 formed relationships — all generated by the model, not hand-written.
Live Space: huggingface.co/spaces/build-small-hackathon/aether-garden
Local:
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–7× to build simulation history
python app.py # → http://localhost:78601. 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. The world grows whether you are watching or not.
Prerequisites: Python 3.11+, Modal account (for production AI), Hugging Face account (for 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 inference URL → MODAL_INFERENCE_URL in .env, set USE_MOCK_AI=false
# Manual simulation tick (demo prep)
python run_tick.pyFull deployment details: DEPLOYMENT.md.
Structured AI output. Entity generation, interactions, and world events all require valid JSON. This branch runs MiniCPM 3-4B by default for tiny-model impact and low latency while staying 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 does not 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 simulation logic and prompts.
Every hour, 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
5. Lifecycle transitions (dormant, legendary, wisdom, dream fragments)
6. Write all entries to the Book of Ages
7. Increment world day + push DB snapshot to HF Dataset
Estimated cost over 10 days: ~$68 of $250 Modal credits, including demo-day GPU warm-keeping.
| Requirement | Status | Evidence |
|---|---|---|
| REQ-02: each model under 32B | Met | MiniCPM3-4B for text generation; SDXL-Turbo for portraits |
| REQ-05: Gradio app in HF Space | Met | Space uses Gradio with app entrypoint app.py |
| REQ-06: Zero GPU app limit | Met | Single Space app |
| README tags + write-up | Met | YAML frontmatter tags and complete technical write-up |
Variant switching is environment-driven (no code changes required):
- MiniCPM variant: MODEL_FAMILY=minicpm and MODEL_ID=openbmb/MiniCPM3-4B
- Nemotron variant: MODEL_FAMILY=nemotron and MODEL_ID=nvidia/Llama-3.1-Nemotron-Nano-8B-v1
| Prize | Current Position |
|---|---|
| Best MiniCPM Build | Directly targeted in this branch |
| Best Use of Modal | Modal inference + scheduled simulation runtime |
| Best Use of Codex | Codex-attributed commits on variant branch |
| Off Brand | Heavy custom UI + non-default Gradio experience |
| Best Agent | Autonomous multi-step simulation loop |
| Tiny Titan | MiniCPM3-4B model size aligns with criteria |
| Document | Contents |
|---|---|
| DETAILS.md | Full build specification — lore, schema, prompts, UX, 10-day plan |
| DEPLOYMENT.md | Modal + HF Space setup, secrets, budget, demo prep |
| assets/README.md | Free graphics resources and suggested asset files |
| .env.example | Environment variables reference |
.
├── 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)
| Prize track | Why this qualifies |
|---|---|
| Thousand Token Wood | AI is the simulation engine — not a static generator |
| Best Agent | Hourly autonomous tick: reasoning + action without user input |
| Off-Brand Award | Custom SVG map + full mystical CSS theme via Gradio |
| Best Demo | World already alive for days when judges open it |
| Modal Award | Inference + scheduled jobs on Modal A10G |
Badge targets: Off-Brand (built-in), Tiny Titan (MiniCPM 3-4B), Sharing is Caring (agent traces), Field Notes (HF blog post).