ScottColeSW/Evo

A local, spectator-mode sandbox where LLM-driven tribes (via Ollama)
gather resources, invent their own language, and try to grow from a handful of survivors
into a founded, warring, or allying civilization — entirely on their own. You pick which
local model runs each tribe from a picker screen, hit start, and watch.
This started as a rambling voice-to-text brainstorm about factory patterns, multi-agent
adversarial games, and evolutionary civilization sims, then grew into a pitch deck framing
it as an "algorithmic survival environment" for stress-testing local models. It has since
grown well past that original pitch: a seven-era progression ladder, a five-tier Maslow
read on each tribe's condition, diplomacy that can genuinely backfire into war, conquest,
espionage, a genetics/breeding layer, and a headless benchmark harness for reproducible
model-vs-model comparison, on top of the original survival/exploration/language loop.
What's actually happening
The short version: the LLM only ever *proposes* — it picks an allowed action, a target,
private rationale, and a broadcast in its own invented language. The simulation
deterministically validates and applies that choice; the world supplies scarcity, terrain,
hazards, progression, infrastructure, diplomacy, and consequences. The UI visualizes the
result in real time.
**For the full architecture — every module's responsibility, the era ladder, the
agent-decision contract, nudges vs. mechanical enforcement, diplomacy/conflict mechanics,
persistence, and known limits — see DESIGN.md.** This README stays
deliberately short and operational; DESIGN.md is the maintained, as-built source of
truth for how the system actually works, so there's one place to keep current instead of
two documents quietly drifting apart.
Multiple simulations at once
Each websocket connection owns its own Simulation (backend/app.py), so opening a
second browser tab starts a second, fully independent world rather than replacing the
first one's run. run.py also takes --port if you'd rather run fully separate OS
processes:
Running it
Requires Ollama installed **and running** locally -- this app calls
its API at http://localhost:11434 (backend/config.py's OLLAMA_URL) both to list models
for the picker and for every tribe's turn. If Ollama isn't running, nothing crashes loudly:
the picker just shows **"(no models found)"** with a warning to pull a model, which is
misleading if the real problem is that Ollama itself isn't up yet.
Start (or confirm) the Ollama server first:
Leave that running in its own terminal/window. (On Windows/Mac, the Ollama app usually does
this automatically and keeps a tray/menu-bar icon running once you've launched it at least
once -- but it does *not* restart itself on its own after a reboot, so check for that icon,
or just run ollama serve, before assuming it's up.)
On Windows, to start it as a background process instead of dedicating a terminal window to
it, use PowerShell:
Stop it later with Get-Process ollama | Stop-Process if needed.
Confirm it's actually reachable:
Then, in a separate terminal:
Small, quantized models are the point, not an afterthought -- part of what this project
measures is exactly how (and whether) a small local model reasons under these constraints.
gemma2:2b, qwen2.5:3b, and llama3.2 are the three this project's own benchmark trials
and A/B tests actually use; any Ollama model works, but a large one mostly just runs
slower without changing what's interesting about the result.
Then open http://localhost:8765 in a browser, pick a model for each tribe, and press