README.md

metadata

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

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:

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 — code generation
• Gradio — web UI framework
• Hugging Face Spaces — deployment
• 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