pyoworld 0.3.0

Build, optimize, and deploy verified symbolic world models.

OpenWorld

The PyTorch for code world models: describe a world, let an LLM write and verify its dynamics as plain Python, and deploy it in one line — no training, no GPU, no dataset.

Source-free, it's the first perfect ARC-AGI-3 result → 25/25 games · 183/183 levels · human-efficient, beats prior SOTA. Every solve is a verified, serveable world model the agent built by acting — the map is the model.

⭐ Star the repo if this is useful · 📄 Cite the work

TL;DR — A world model in OpenWorld is a small spec: symbolic state + declared actions + verified code dynamics + an optional perception boundary. An LLM can write and verify that code for you; the result is deterministic, inspectable, and needs 0 training data. Then openworld serve turns any spec into a FastAPI inference server with a live, animated React Flow view.

Who's it for? Agent & RL researchers who need an auditable simulator instead of a black box · LLM builders who want a world model as a verifier / planner · anyone tired of learned dynamics that hallucinate and compound error.

Prototype a world model in minutes, not months. The same World object you sketch in a notebook serializes to a portable spec, renders to a model card, composes into bigger worlds, and deploys as an inference server — one zero-dependency core, no training loop.

---

⚡ The 30-second mental model

Every world serializes to a lossless JSON spec and renders to a stunning, self-contained SVG model card (a HuggingFace-style card — but the artifact is a runnable world). Composition is closed: worlds nest into worlds, coupled by bridges and rolled up by aggregators.

_{A generated model card — one self-contained SVG per world: state graph · schema · verified dynamics · rollout · metrics · declared rules. Just render_card(world).}

---

🎮 Watch it solve ARC-AGI-3 — source-free, beats prior SOTA

Each loop is a verified, source-free solution to an ARC-AGI-3 game: the agent discovered the rules by acting (no game code), built and verified its own predict(frame, action) world model, reasoned the win condition, and replayed the winning move sequence. Every solve round-trips to a serveable OpenWorld World — the map is the model. Below: all 25 public games, each completed source-free by Claude Fable 5.

The recipe — how every solve above is made

Behind a source-free boundary (the agent's Python cannot import the engine), the same loop runs on every game — a reusable pattern for building verified world models by acting:

① Perceive pixels → a symbolic state (mask the status bar so the state space doesn't explode) · ② Explore by acting to gather (s, a, s′), with the environment as ground truth · ③ Synthesize a predict(frame, action) program — kept only if it exact-matches held-out transitions (gate 1), retrying on counterexamples · ④ Reason what raises levels_completed into a CodeObjective (the win is a procedure, not a state) · ⑤ Plan action sequences through the verified model "in imagination" · ⑥ Verify by replaying the plan on the real engine (gate 2). Each verified win banks as a serveable OpenWorld World — a Perceptor + FunctionTransition + CodeObjective you can download, re-run, and serve at openworld serve /view; unsolved games loop back and re-synthesize. (Figure 2 of the paper.)

ar25 · 8/8	bp35 · 9/9	cd82 · 6/6	cn04 · 6/6	dc22 · 6/6
ft09 · 6/6	g50t · 7/7	ka59 · 7/7	lf52 · 10/10	lp85 · 8/8
ls20 · 7/7	m0r0 · 6/6	r11l · 6/6	re86 · 8/8	s5i5 · 8/8
sb26 · 8/8	sc25 · 6/6	sk48 · 8/8	sp80 · 6/6	su15 · 9/9
tn36 · 7/7	tr87 · 6/6	tu93 · 9/9	vc33 · 7/7	wa30 · 9/9

Source-free result (audited, replay-verified): all 25/25 games · 183/183 levels — the first perfect ARC-AGI-3 result. With Claude Fable 5, every public game is completed source-free and human-efficient or better (per-game RHAE 100; per level it beats the human on 174/183 levels) — ~72% more action-efficient than the prior SOTA, beating baseline1 (15/25, 145 levels, 58.12 RHAE) on games, levels, and, decisively, efficiency. Our primary Claude Opus 4.8 arm reaches 16/25 on the identical protocol, so the perfect sweep is a model-scaling result. Frames render in the official ARC-AGI palette; the label shows the level reached. Full write-up in papers/arc-3/.

The map is the model. Every solve round-trips to a serveable OpenWorld World, rendered as an atlas model card — its discovered start → level 1 → … → win state-transition graph, verified dynamics, and reward on one page. Three of the 25 (full atlas in papers/arc-3/maps/):

arc3-su15 · 9/9

arc3-bp35 · 9/9

arc3-lf52 · 10/10

---

🧠 Why OpenWorld

_{Why code, not weights: verified dynamics are exact at every depth (no compounding error), and world-time compute lifts generalization on unseen worlds — biggest lift where models are smallest.}

• Training-free & deterministic. Dynamics are synthesized, verified code, not learned latents — no datasets, no GPUs, bit-exact rollouts, zero compounding error. (How does it solve tasks with zero data?)
• Verifiable by construction. Every candidate dynamics program passes syntax, sandboxed smoke-run, invariant, and (optional) LLM-critic gates before it is accepted. The accepted code is a plain .py you can read, diff, and unit-test.
• Portable & publishable. to_spec(world) → a complete JSON spec capturing state, rules, dynamics, perception, emit, objectives, metrics, and nested composition. render_card(...) → one self-contained SVG. to_mermaid / to_reactflow exports included.
• Composable (worlds-within-worlds). CompositeWorld nests child worlds, couples them sideways via Bridges, and rolls them up via Aggregators — recursively.
• Steerable at inference time. Objectives are declared scoring functions weighted by Dials; move along the Pareto frontier between competing values without retraining.
• Deployable in one line. openworld serve specs/ --allow-code → http://127.0.0.1:8080 with /docs, batch /predict, and a live animated React Flow view per world.
• Local-first & zero-dependency core. The library talks to Ollama through the standard library; MockLLM runs everything fully offline.

---

🧭 Three ways to use a world model — pick your path

A verified world model is a reusable artifact, and it is useful whether or not you ever fine-tune. There are three routes to spend it, plus a hybrid that combines them.

Route 1 — Use it as a tool (no training). Serve the world and call it: plan through it, query exact next-states, or use it as a verifier. Exact, auditable, zero training.

openworld serve specs/*.json --allow-code --open
#  POST /step  /rollout  /predict  /run    ·    WS /live

Pick this when you have the world at inference and want exact, auditable answers or planning.

Route 2 — Distill one world into the model (test-time training). Generate exactly-labeled trajectories from a single world and QLoRA-fine-tune on them, so that world's skill is amortized into weights (no tool needed at inference). → experiments/e80_*_ttt.py Pick this when you want one world's skill baked in for fast, tool-free inference.

Route 3 — Train across many worlds (world-time compute). Traverse a family of verified worlds and fine-tune → generalize to held-out worlds you never trained on. → experiments/e74_scaling.py, e76_world_count.py, e80_* Pick this when you want a model that generalizes across a domain, not just one task.

Hybrid (the powerful one). Use Route 1 to generate exact trajectories (plan through the tool → verified data), Route 2/3 to internalize them, and fall back to the tool for high-stakes queries. The tool bootstraps the data; training amortizes it; the tool stays the exact oracle.

	exact?	training	tool at inference	generalizes to new worlds
1 · Tool	✅ exact	none	yes	n/a (use any world)
2 · Per-world TTT	approximate	QLoRA, one world	no	within the world
3 · World-time compute	approximate	QLoRA, many worlds	no	✅ across the family
Hybrid	✅ on fallback	QLoRA	only when unsure	✅ + exact backstop

Decision line: need exactness/audit → Route 1; amortize one world → Route 2; generalize a family → Route 3; best of both → Hybrid.

📊 Empirical baselines

Verified-code dynamics vs. learned / LLM dynamics on the framework's own benchmark suite (numbers from the bundled, reproducible experiments — see experiments/).

_{Generated from experiments/results/e36_representations.json by scripts/make_readme_baselines_fig.py. Structure, not scale: verified symbolic composition needs only per-part marginals; monolithic learners need the full joint and never see it.}

Approach	Rollout exact-match	Generalization to novel combos	Training data	Determinism
OpenWorld (verified code)	1.00 → 1.00	1.00	0 samples	bit-exact
LLM next-state predictor	0.67 → 0.00 ¹	—	—	non-deterministic
Best learned baseline (boosted trees)	—	0.20 ²	thousands	seed-dependent
Monolithic MLP	—	< 0.20 ²	thousands	seed-dependent

_{¹ Per-step exact-match over a rollout (experiment E01): the LLM degrades to 0 as error compounds; verified code stays exact. ² Exact accuracy on unseen part-combinations at K=5 (E36): composition-symbolic = 1.00 with zero training data; the strongest of 9 learned families reaches ~0.20.}

Note: OpenWorld reports negative and boundary results honestly — e.g. trace induction hits an identifiability ceiling (E38) and a same-day trading world is sub-S&P on a risk-adjusted basis (E50). The value here is verified dynamics, not a universal win.

🔑 Sample efficiency: MiniGrid DoorKey vs. learned world models (E65)

On the learned models' own terrain — image-based MiniGrid DoorKey — a verified-code world model plans an 11-step optimal solution zero-shot (no training data; transition validated bit-exact against Farama MiniGrid, 600/600 steps). DreamerV3 needs 9,640 environment interactions for its first solve and ~100k to solve reliably (from 48×48 pixels, on an A100), while frozen V-JEPA-2 features decode the state well but no controller we tried could turn them into a single solve.

_{Fair-comparison caveat: DreamerV3 learns everything from raw pixels with zero priors — that generality is real. The claim is about where each species wins: when the reasoning (not the perception) is the hard part and the horizon is short, verified code is ~876× more sample-efficient. Numbers from experiments/e65_minigrid_bench.py (results JSON); figure regenerated by scripts/make_readme_doorkey_fig.py.}

---

🚀 Install

Note: Python 3.14 is recommended (faster-CPython + security/stdlib hardening; a .python-version pin selects it under pyenv), though the code runs on 3.9+. The core (import openworld) is zero-dependency; the openworld CLI + server add fastapi / uvicorn / click / rich.

pip install pyoworld             # from PyPI: core + CLI/server (imports as `openworld`)

Or from source (for the experiments, papers, and tests):

git clone https://github.com/quome-cloud/openworld.git
cd openworld
pyenv install 3.14.6 && pyenv local 3.14.6   # optional: pin the recommended Python
pip install -e .                 # core + CLI/server
pip install -e ".[dev]"          # + test tooling

Optional — for LLM-synthesized dynamics, run Ollama locally:

ollama pull qwen3-coder:30b      # or any code-capable model

---

✨ Quickstart (runs out of the box — no LLM required)

Define a world, run it deterministically, serialize it, and render its model card:

from openworld import World, Action, CodeTransition, to_spec, render_card

DYNAMICS = """
def transition(state, action):
    s = dict(state)
    if action["name"] == "heat":   s["temp"] += 1
    elif action["name"] == "cool": s["temp"] -= 1
    return s            # 'idle' (and anything else) holds — explicit & verifiable
"""

room = World(
    name="thermostat",
    description="A room with a thermostat tracking a target temperature.",
    initial_state={"temp": 18, "target": 21},
    actions=["heat", "cool", "idle"],
    rules=["'heat' raises temp by 1, 'cool' lowers it by 1, 'idle' holds."],
    transition=CodeTransition(DYNAMICS),       # verified code — not a neural net
)

print(room.transition.step(room.initial_state, Action("heat")))  # {'temp': 19, 'target': 21}
print(to_spec(room)["state_schema"])           # {'temp': 'int', 'target': 'int'}
render_card(room, "thermostat.svg")            # a self-contained SVG model card

Then deploy it with a live, animated view:

import os
from openworld import spec_to_json, to_spec
os.makedirs("specs", exist_ok=True)
open("specs/thermostat.json", "w").write(spec_to_json(to_spec(room)))

openworld serve specs/ --allow-code            # → http://127.0.0.1:8080

Open http://127.0.0.1:8080/worlds/thermostat/view, step the world, and watch the graph update.

---

🐳 Deploy with Docker

The repo ships a Dockerfile (Python 3.14, non-root, healthchecked) that runs the inference server with the bundled specs out of the box:

docker build -t openworld .
docker run --rm -p 8080:8080 openworld                       # serves the bundled specs/

Then open http://localhost:8080/ (interactive /view per world, /docs for the API). Serve your own specs by mounting a directory over /app/specs:

docker run --rm -p 8080:8080 -v "$PWD/specs:/app/specs" openworld

The image installs only the core + serve/CLI layer (FastAPI / Uvicorn / Click / Rich); override the default command to run any CLI subcommand, e.g.:

docker run --rm openworld ls /app/specs
docker run --rm -p 9000:9000 -v "$PWD/specs:/app/specs" \
  openworld serve /app/specs --host 0.0.0.0 --port 9000 --allow-code --no-open

---

🛠️ Advanced usage

Compose worlds-within-worlds (bridges + aggregators)

from openworld import CompositeWorld, Bridge, Aggregator, Action, render_card

def total_treated(children):
    return sum(c["treated"] for c in children.values())

network = CompositeWorld(
    name="hospital-network",
    children={"north": triage_world(), "south": triage_world()},    # any Worlds
    bridges=[Bridge(name="transfer", a="north", b="south",
                    transition=CodeTransition(TRANSFER_CODE))],       # sideways coupling
    aggregators=[Aggregator(name="total_treated", fn=total_treated)], # upward roll-up
    default_actions={"north": "treat_critical", "south": "treat_moderate"},
)
network.transition.step(network.initial_state, Action("tick"))       # steps both + bridge + roll-up
render_card(network, "network.svg")                                  # nested "world of worlds" card

Perception → world → emit (paste text in, get a report out)

from openworld import World, CodeTransition, CodePerceptor, to_spec

w = World(name="intake", description="ticket intake",
          initial_state={"priority": 0, "load": 0, "done": 0}, actions=["work"],
          transition=CodeTransition(WORK_CODE))

# A perceptor whose extraction is *verified code* — runs server-side with no LLM:
w.perceptors = [CodePerceptor(code=PARSE_CODE, produces=["priority", "load"],
                              schema={"priority": (int, (0, 9)), "load": (int, (0, 99))})]
w.emit = [{"modality": "report", "fields": ["priority", "load", "done"],
           "report": "priority {priority}: cleared {done}, {load} remaining"}]

spec = to_spec(w)   # perception + emit travel inside the spec, losslessly

Served, this powers the live view: paste priority: 7 / load: 4, watch it perceive → traverse the rules → emit a report, and loop.

LLM-synthesized, verified dynamics (the Code World Model loop)

from openworld import World, OllamaLLM

world = World(
    name="orchard", description="Agents share an orchard with limited apples.",
    initial_state={"apples": 10, "harvested": {"alice": 0}},
    actions=["pick", "wait"],
    rules=["'pick' moves one apple to the acting agent; none left → no-op."],
    llm=OllamaLLM(model="qwen3-coder:30b", options={"num_ctx": 8192}),
)
world.compile(invariants=[("apples never negative", lambda s: s["apples"] >= 0)])
# the LLM writes the dynamics; the verifier gates it (AST + sandbox + invariants
# + optional critic) before acceptance. The result is an editable .py artifact.

Steerable objectives & Pareto sweeps (no retraining)

from openworld import Dial, Objective, Simulation, sweep

morality = Dial("morality", value=0.0)          # λ ∈ [0, 1]
sim = Simulation(world, agents, objectives=[
    Objective("welfare",  fn=welfare,  weight=1.0),
    Objective("fairness", fn=fairness, weight=morality)])

result = sweep(sim, dial="morality", values=[0.0, 0.1, 0.5, 1.0], steps=20, episodes=3)
print(result.table())                            # totals per dial setting
frontier = result.pareto(["welfare", "fairness"])# non-dominated trade-off points

CLI: build → optimize → deploy

openworld build "a support-ticket queue you can paste into" --name intake  # Claude Code authors a spec
openworld optimize specs/intake.json --goal "clear high-priority fastest"   # tune toward a goal
openworld ls specs/                                                        # inspect a catalog
openworld card specs/intake.json --open                                    # render the SVG card
openworld serve specs/ --allow-code                                        # FastAPI @ :8080

Inference-server API (per world)

Method	Path	Purpose
GET	/worlds/{name} · /spec · /state · /actions · /metrics	introspection
GET	/card.svg · /mermaid · /reactflow · /view	visualizations
POST	/step	one forward pass: {state, action} → {next_state, changed}
POST	/predict	batch forward pass
POST	/rollout	multi-step trajectory
POST	/observe · /run	perception (gated) / full input → perceive → roll → emit
WS	/live	streamed, animated rollout

Composites, bridges, and perception are served transparently. --allow-code gates dynamics execution (a trust gate for local specs — not a sandbox against adversarial code).

---

🗺️ Repository layout

Path	What's inside
openworld/	The zero-dependency core library — state, transitions, compose, spec, card, perceive, plus the serve/cli layer (the one place third-party deps live).
recipes/	100 one-file world recipes across regulated domains.
examples/ · tutorials/ · notebooks/	Runnable learning material — small example worlds, step-by-step guides (.md + .py), and the Colab quickstart.
gallery/	Rendered world cards / atlas SVGs.
experiments/	Numbered, self-checking experiments (eNN_*.py) + results/ — the evidence behind every paper number.
papers/	The three LaTeX papers + a shared assets/, all generated by scripts/make_paper_assets.py (never hand-edited).
presentations/	The four conference decks (Beamer PDF + self-contained HTML) built from one spec.
datasets/ · bench/	Published datasets and competitor baselines (Dreamer, TD-MPC2, V-JEPA, PoE-World).
scripts/ · tests/ · docs/ · assets/	Build/utility scripts, the test suite (284 passing), design docs, and brand assets.

Root files: README.md, QUICKSTART.md, CLAUDE.md (contributor & agent notes), pyproject.toml, Dockerfile, CITATION.cff. (scratch_arc/ and .claude/ are local scratch / agent state, not part of the library.)

---

📐 Design principles

• The core is zero-dependency. import openworld and everything it pulls in uses only the standard library. The CLI/server are the one batteries-included layer.
• Honest science. Experiments are deterministic, self-checking, and report weak or negative results plainly. Paper numbers come only from scripts/make_paper_assets.py reading experiments/results/.
• Code is the contract. Accepted dynamics are auditable artifacts, not weights.

---

🔬 Reproducibility & testing

pytest -q                                  # 284 cases (228 test fns x params), deterministic & offline
python experiments/e57_world_specs.py      # e.g. world specs: 5/5 round-trip exact
python scripts/make_paper_assets.py        # regenerate every paper figure/table/number

The 62 bundled experiments are designed for reproducibility: fixed seeds, numpy baselines, and asserted claims. The accompanying paper compiles end-to-end from the same results (cd paper && tectonic main.tex).

---

📚 Citation

OpenWorld is described in three companion papers (2026 — arXiv preprints, currently under review). Cite the one(s) your work builds on.

If your work uses…	Cite
The framework itself — authoring, verifying, composing, or serving code world models (the library, the prototyping benchmark, the world zoo)	① World Computing
World-time compute — training a model on trajectories through many verified worlds to generalize to unseen worlds (incl. the diagnosis & coding world families)	② World-Time Compute
The ARC-AGI-3 source-free result — the perceptual code-world-model agent and its solve traces	③ Solving ARC-AGI-3

BibTeX — three papers

@misc{schwoebel2026worldcomputing,
  title  = {World Computing: Prototyping and Evaluating Verified Code World Models},
  author = {Schwoebel, James and Semenec, Ingrida and Rousseva, Jenia and Ortiz, Marcos
            and Overbay, Collin and Bhatt, Manish and Thorstenson, Rome and Frasch, Martin G.},
  year   = {2026},
  note   = {arXiv preprint, under review}
}

@misc{schwoebel2026worldtime,
  title  = {World-Time Compute with Verified Code World Models},
  author = {Schwoebel, James and Semenec, Ingrida and Rousseva, Jenia and Ortiz, Marcos
            and Overbay, Collin and Klaus, Christopher and Edmond, Anderson and Bhatt, Manish
            and Thorstenson, Rome and Tsai, Jessica and Frasch, Martin G.},
  year   = {2026},
  note   = {arXiv preprint, under review}
}

@misc{schwoebel2026arcagi3,
  title  = {Solving ARC-AGI-3 with Perceptual Code World Models},
  author = {Schwoebel, James and Semenec, Ingrida and Rousseva, Jenia and Ortiz, Marcos
            and Overbay, Collin and Klaus, Christopher and Bhatt, Manish and Thorstenson, Rome
            and Tsai, Jessica and Frasch, Martin G.},
  year   = {2026},
  note   = {arXiv preprint, under review}
}

Note: all three papers are under review; arXiv IDs / DOIs will be filled in here on release. Until then please cite them as preprints (above).

---

🤝 Contributing

Contributions are welcome — new world models, experiments, perceptors, or serving features.

1. Read CLAUDE.md (working conventions) and QUICKSTART.md.
2. Base every branch on main; keep the core zero-dependency; add deterministic, self-checking tests.
3. Open a PR against main with a clear description and a passing pytest.

Found a bug or have an idea? Open an issue.

---

📄 License

Released under the Apache License 2.0 — free for commercial and academic use, with an explicit patent grant.

_{Built with verified code, not vibes. ⭐ Star the repo if a readable, deployable world model is useful to you.}