README.md

metadata

title: GODSEED
emoji: 🪐
colorFrom: purple
colorTo: yellow
sdk: gradio
app_file: app.py
pinned: false
license: mit
short_description: Wish, and a tiny god terraforms one shared planet
models:
  - nvidia/NVIDIA-Nemotron-Nano-9B-v2
  - nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF
datasets:
  - AndresCarreon/godseed-world
tags:
  - build-small-hackathon
  - track:wood
  - sponsor:nvidia
  - achievement:offgrid
  - achievement:llama
  - achievement:offbrand
  - achievement:sharing
  - achievement:fieldnotes
  - thousand-token-wood
  - off-the-grid
  - llama-champion
  - off-brand
  - field-notes
  - sharing-is-caring
  - llama-cpp
  - nemotron
  - agents
  - best-agent
  - text-generation
  - world-building

🪐 GODSEED

Nine billion parameters. One shared world.

Type a wish. A small NVIDIA Nemotron god reads it aloud — you watch the thoughts stream — then terraforms one persistent planet shared by every visitor. Mountains rise where it points. Glowgrass scatters. Moons hang. Your wish joins everyone else's, forever, on the same small world.

There is no level select and no reset button. One planet, one god, one wish at a time.

✨ The moment that sells it

You type "let a glass river cross the dark" and the god thinks in public: a streamed reading of your wish, then a chain of deliberate tool calls — and the camera glides to the exact latitude where a glowing river is being laid down, live, on a world that twenty strangers are watching with you.

🧠 How the god works

A real plan-act-observe agent loop, grammar-constrained, with a hard separation of church and state:

        your wish ("let a glass river cross the dark")
            │
            ▼
   ┌─ THE MIND · Nemotron ──────────────────────────────────┐
   │  1. READS the wish aloud (streamed token-by-token)     │
   │  2. PLANS: one JSON tool call per turn, max 7 turns    │
   │     {"thought":"…","call":{"tool":"place_water",…}}    │
   └──────────────┬──────────────────────▲──────────────────┘
        tool call │                      │ observation
                  ▼                      │ "ok: river laid (12,40)"
   ┌─ THE ENGINE · deterministic ────────┴──────────────────┐
   │  validates → clamps → seeds → appends a Feature        │
   │  owns ALL world state; the model owns none of it       │
   └──────────────┬─────────────────────────────────────────┘
                  │ world_delta (SSE broadcast)
                  ▼
   ┌─ THE PLANET · Three.js, client-side ───────────────────┐
   │  a pure function of the ordered feature list:          │
   │  terrain rises, flora scatters, weather turns          │
   └────────────────────────────────────────────────────────┘

The model never computes geometry and never owns state — it interprets, narrates, and picks from a DSL of exactly 11 tools (raise_terrain, lower_terrain, spawn_flora, place_structure, place_water, set_weather, set_sky, inscribe_wish, spawn_life, build_district, place_road). The deterministic engine clamps every number, seeds every feature, and feeds terse observations back into the loop. Wishes pass layered moderation before a single tool runs. Latency is liturgy: the god grants one wish at a time, and you see your place in line.

Because every feature carries its seed, the planet is fully deterministic: the landing page renders the entire world client-side from JSON with zero GPU, and any moment in its history can be replayed exactly.

📜 The Genesis Log

Every granted wish is archived in the Genesis Log (/book): the wish, the god's reading, every thought and tool call, and a one-line epitaph. Click any entry and the world reconstructs itself to that epoch, then replays that wish's deltas with the recorded thoughts streaming — a deterministic séance, shareable by URL. The full agent traces (JSONL) are published to a public dataset after every wish.

⚙️ Model config

Config	Model	Params	Runtime
Live	NVIDIA-Nemotron-Nano-9B-v2	9B (hybrid Mamba-2)	transformers + ZeroGPU
Low-power	NVIDIA-Nemotron-3-Nano-4B-GGUF (Q4_K_M, ~2.5 GB)	4B	llama.cpp in-process, free CPU tier

One model runs in the app at a time, selected by GODSEED_BACKEND (mock | llamacpp | zerogpu) — comfortably under the 32B hackathon cap. On the llama.cpp backend the tool-call loop is GBNF grammar-constrained, so a 4B model emits valid JSON every turn. Inference is always in-process — no cloud LLM APIs.

🏆 Built for Build Small — Thousand Token Wood

A world that is genuinely impossible without AI: the model doesn't power a feature, it is the god — every reading, every plan, every epitaph. Deterministic code is only guardrails, geometry, and archive.

• Off the Grid — no cloud inference APIs: every token is generated in-process on the Space. The only network traffic is the Hugging Face Hub itself (model weights at boot, and the public trace dataset appended after each granted wish).
• Llama Champion — the identical app runs end-to-end on llama.cpp: GODSEED_BACKEND=llamacpp loads the 4B GGUF (Q4_K_M) with native GBNF-constrained tool calls. The llama-cpp-python runtime ships in this Space's requirements.
• Off-Brand — a fully custom WebGL frontend on gr.Server; gradio powers the API endpoints (the browser-invoked granting rite), not the visible UI.
• Field Notes — build log: FIELD_NOTES.md.
• Sharing is Caring — live agent traces published to a public dataset: AndresCarreon/godseed-world.

📦 Submission links

• Demo video: coming before the deadline — link will land here.
• Social post: coming before the deadline — link will land here.
• Agent traces dataset: AndresCarreon/godseed-world — every granted wish's full plan-act-observe trace, appended live.

▶️ Run it locally

uv venv -p 3.12 .venv && uv pip install -r requirements.txt
GODSEED_BACKEND=mock PORT=7860 .venv/bin/python app.py   # open http://localhost:7860

GODSEED_BACKEND=llamacpp downloads the 4B GGUF from the Hub on first run (GODSEED_GGUF overrides the path). Optional env: GODSEED_DATASET + HF_TOKEN (trace publishing & persistence across restarts), GODSEED_SECRET (stable visitor identity).

🙏 Credits

• LLM: NVIDIA Nemotron Nano family (open weights), via transformers / llama.cpp.
• Rendering: three.js (MIT), vendored.
• Type: Cormorant Garamond (SIL OFL) via Google Fonts.

Speak, and it will be made.