README.md

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

<!-- ↑ Space card config. app.py runs as a Gradio Server (gr.Server): it serves
     the WebGL world at /, the Genesis Log at /book, the JSON/SSE API under /api,
     and the gradio API endpoint that runs the granting rite under /gradio_api. -->

# 🪐 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](https://huggingface.co/nvidia/NVIDIA-Nemotron-Nano-9B-v2) | 9B (hybrid Mamba-2) | transformers + ZeroGPU |
| **Low-power** | [NVIDIA-Nemotron-3-Nano-4B-GGUF](https://huggingface.co/nvidia/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](./FIELD_NOTES.md).
- **Sharing is Caring** — live agent traces published to a public dataset:
  [AndresCarreon/godseed-world](https://huggingface.co/datasets/AndresCarreon/godseed-world).

## 📦 Submission links

<!-- TODO(fill-at-deploy): replace all three placeholders before the deadline. -->

- **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](https://huggingface.co/datasets/AndresCarreon/godseed-world)
  — every granted wish's full plan-act-observe trace, appended live.

## ▶️ Run it locally

```bash
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](https://threejs.org) (MIT), vendored.
- **Type:** Cormorant Garamond (SIL OFL) via Google Fonts.

*Speak, and it will be made.*