Model-MOO

Model-MOO is a persistent, MOO-style world inhabited and built by a local language model. Every run begins in a single empty room called The Void. The model receives a small collection of validated world-building tools and no assigned theme or objective, then decides what to explore and create.

The project asks a small question: if a local model is given an empty world of its own, what will it make?

Unedited dashboard capture from a real qwen3:1.7b run. The model recovered from a malformed action, created and explored the Hall of Echoes, returned to the Void, and continued inferring.

What it includes

• A persistent SQLite world containing rooms, exits, objects, verbs, memories, model identity, actions, and model-turn activity.
• Solo and collaborative modes. In collaborative mode, a human can enter the same world as a visible second participant.
• Validated tools for exploration, building, inventory, object properties, reusable verbs, memory, and a model-authored character sheet.
• A live dashboard showing the current room, emitted model thinking, inference status, action history, statistics, and a grid-based map of connected rooms.
• Trial-and-error behavior that records failed actions and gives the model another turn instead of treating ordinary mistakes as a reason to stop.
• A source-independent Linux desktop workspace that can package the Python application, a private Ollama runtime, and the selected model workflow as a Tauri AppImage.

See the architecture overview for how these pieces fit together.

Requirements

• Python 3.11 or newer
• Ollama running locally
• A tool-capable Ollama model

The supplied profiles use qwen3:1.7b, which is small enough for modest local hardware:

ollama pull qwen3:1.7b

Quick start

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
model-moo launch --port 8000

Open http://127.0.0.1:8000, then choose Start new run beside a supplied setup:

• default.yaml gives the model a solo world.
• collaborative.yaml enables human player controls alongside the model.

The launcher creates a new run directory, starts the model loop and dashboard, and opens that run's page. Separate launcher runs receive fresh random seeds; Repeat seed reproduces a setup's configured seed.

Press Ctrl+C in the launcher terminal to stop the processes it owns. Completed and interrupted runs remain available from the launcher.

Run without the launcher

Start a headless run directly from a profile:

model-moo run --config config/profiles/default.yaml

Serve a saved run later:

model-moo serve --run runs/<run-id> --port 8001

Each run stores its SQLite database and manifest under runs/<run-id>/. Run data is local and gitignored.

Configuration

A minimal profile is a YAML mapping:

model: qwen3:1.7b
seed: 42
max_actions: 500
max_runtime_seconds: 3600
mode: solo

Additional settings control private memory size, verb complexity, repetition recovery sensitivity, Ollama request and turn timeouts, the local Ollama endpoint, and collaborative player naming. The supplied profiles in config/profiles/ show the complete supported form.

Runs normally continue until max_actions. Failed world actions remain part of the action budget and are returned to the model as observations. Tool-free responses and transient Ollama errors receive bounded retries; overall runtime and inference deadlines prevent an infinite run.

Testing

The deterministic suite does not require Ollama or a browser:

python -m pip install -e '.[test]'
python -m pytest

Browser and live-model checks are opt-in. See TESTING.md for the short test matrix.

Linux desktop build

The isolated desktop workspace builds a Linux x86_64 Tauri AppImage with a frozen Python sidecar and a private, checksum-verified Ollama runtime. Runtime downloads and generated AppImages are not committed to the source repository.

Project layout

config/profiles/                         Example solo and collaborative setups
desktop/                                Tauri desktop source and build tooling
documentation/public-documentation/     Public architecture and media
src/model_moo/                          Agent, world engine, launcher, and UI
tests/                                  Deterministic and opt-in validation
runs/                                   Generated local worlds (gitignored)

Practical limitations

Model-MOO intentionally targets a small local model. On CPU-only or low-power hardware, inference can be slow, and qwen3:1.7b may repeat ideas, misuse a tool schema, or need several attempts to complete a plan. The system preserves those attempts rather than hiding them; observing how the model adapts is part of the project.

The application is local-first and intended as a portfolio experiment, not a hosted multi-user service.

License

Model-MOO is free software licensed under the GNU General Public License version 3 only. Bundled and downloaded components retain their own licenses; see THIRD_PARTY_NOTICES.md.