---
title: TinyWorld
emoji: 🏘️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "6.18.0"
app_file: app.py
pinned: false
tags:
  - hackathon
  - build-small
  - adventure-in-thousand-token-wood
  - openbmb/MiniCPM5-1B
  - nvidia/Nemotron-Mini-4B-Instruct
  - openbmb/VoxCPM2
  - cohere/cohere-transcribe-03-2026
---

# 🏘️ TinyWorld

**Throw an event. Watch the neighborhood react.**

A tiny life-sim town where AI characters react unpredictably, follow routines, and obey directed commands in their own voices. Built for the **Build Small Hackathon 2026** (Hugging Face × Gradio), targeting the **Adventure in Thousand Token Wood** track.

## Source

Public GitHub repo: [Sushruths04/tinyworld-reactive-neighborhood](https://github.com/Sushruths04/tinyworld-reactive-neighborhood)

Built with OpenAI Codex. See the commit history for Codex-attributed commits.

## How to Play

1. **Type an event** in the textbox (or click 🎲 Random Chaos for inspiration).
2. **Hit ⚡ Trigger** — watch the addressed character or whole town react on the canvas.
3. **Listen** — the most dramatic reaction auto-speaks via VoxCPM2 voice. Pick another character from the dropdown and hit 🔊 to hear them too.

## 🎬 Crisis Mode — "The Long Summer"

Beyond the open sandbox, TinyWorld has a story-driven **co-op survival** mode inspired by *Among Us*: **you are the saboteur**. Switch to **🎬 Campaign** and press **Start Campaign** to inject a linked season of escalating crises — a café fire, a heatwave blackout, a storm, a missing child, and a finale. The five residents must perceive, coordinate, and **actually resolve** each crisis before the **chaos meter** maxes out.

- **Deterministic resolution** — each crisis declares *requirements* (e.g. fire → contain it at the café, get the medic on scene, evacuate). The engine checks each resident's chosen destination and action against those requirements; the LLM only *speaks*, the engine decides whether it's solved (`crisis.py`).
- **Multi-round coordination** — unmet requirements feed back into the next round ("the fire is still spreading, no medic on scene"), so the town has to organize across rounds. You can also type directed commands ("Jay, put the fire out at the café") to rally a specific resident.
- **Story & stakes** — clear all five chapters to trigger the **finale reveal**: every disaster traced back to one source — *you*. Each chapter is graded, names an **MVP resident**, and surfaces a teaching question about *how five different minds approach the same emergency differently* (`campaign.py`).

Play it locally end-to-end with no network:

```bash
TINYWORLD_MOCK=1 python3 acceptance_check.py   # offline win + collapse playthrough
TINYWORLD_MOCK=1 python3 -m pytest -q          # full test suite incl. crisis/campaign
```

### Architecture note (portability)

The game engine is host-agnostic: `crisis.py`, `campaign.py`, `agents.py`, `decide.py`, `router.py`, `world_state.py`, and `worlds/` never import `gradio` (enforced by `tests/test_portability.py`). `app.py` is a thin Gradio adapter. This boundary is the seam that lets the same engine be wrapped by a Streamlit or FastAPI front-end later without touching the core.

## What Makes It Unpredictable

Every reaction is shaped by 4 hidden layers:
- **Mood** — each character has a secret mood that re-rolls after every event.
- **Memory** — they remember their last 3 reactions and reference them.
- **Relationships** — friendships, rivalries, and crushes color how they respond.
- **Surprise Seeds** — a random creative instruction appended to every prompt.

Trigger the same event 3 times → you get 3 completely different reactions each time.

## Models Used (all ≤ 4B params)

| Model | Params | Role | Sponsor |
|---|---|---|---|
| `nvidia/Nemotron-Mini-4B-Instruct` | 4B | Primary character dialogue model for all worlds | NVIDIA |
| `openbmb/MiniCPM5-1B` | 1B | Lightweight fallback dialogue model on Modal | OpenBMB |
| `openbmb/VoxCPM2` | 2B | Character voice synthesis (TTS) | OpenBMB |
| Whisper `base` on Modal | ~74M | Primary speech-to-text (mic input) | Modal |
| `Cohere Transcribe` | 2B | Speech-to-text fallback path | Cohere |

**Total model budget: under 10B params** (well under the 32B cap — earns the *Tiny Titan* badge).

## Built With

- [OpenAI Codex](https://openai.com/index/openai-codex/) — code generation
- [Gradio](https://gradio.app) — web UI framework
- [Hugging Face Spaces](https://huggingface.co/spaces) — deployment
- [ZeroGPU](https://huggingface.co/docs/hub/spaces-zerogpu) — in-Space GPU inference

## Sponsor Credits

- **NVIDIA** — Nemotron-Mini-4B-Instruct (character dialogue)
- **OpenBMB** — MiniCPM5-1B fallback + VoxCPM2 voice synthesis
- **Modal** — serverless LLM, voice, and Whisper transcription endpoints
- **Cohere** — Transcribe fallback path

---

*Built for Build Small Hackathon 2026 · Hugging Face × Gradio · Thousand Token Wood track*