awm — a small, dependency-light world model

Docs · Source · pip install git+https://github.com/Aitherium/awpredict.git · The Aither World

The Aither World is an operating system for agents — a Linux you can hand to one, the runtimes it works in, and the tools it works with. awnix is the Linux underneath it; awpredict is one of its 67 bricks — each installs on its own, runs offline, and needs no account.

Start here: Wrap an environment you already have and ask it what happens next.

awpredict is a learned-dynamics library: encode an observation to a latent, predict the next latent given an action, score how surprised the model was, optionally plan in latent space. Two engines, a small adapter protocol, no framework lock-in.

• awpredict.core.lewm.LeWorldModel — a LeWM-style JEPA (joint-embedding predictive architecture): a two-term loss (next-latent MSE + SIGReg isotropy regularization), a CEM planner, and an optional value head (_ValueHead/_FsAdapter) for value-guided planning — trained on returns over a frozen latent, off unless you construct with a value config. This is the full engine behind an ARC-AGI-3 solving agent, not a cut-down demo of it.
• awpredict.core.mlp.MLPWorldModel — a lighter embedding-MLP transition model with a tabular cold-start fallback (tabular → hybrid → neural), for when a full JEPA is more machinery than the problem needs.
• awpredict.contracts — the two Protocols (WorldModel, EnvironmentAdapter) everything else is written against. Write an adapter for your environment; nothing in an engine has to change.
• awpredict.adapters.code_world — an example adapter mapping a codebase (landmarks + code chunks) into the engine's observation/action space. Reference implementation, not a complete environment.
• awpredict.training.online — an optional, flag-gated surprise-modulated online learning-rate controller. Off by default. See awpredict/training/PROVENANCE.md for concept provenance and license boundary — the concepts (not code) are credited to an external, restricted-license research project; this implementation is clean-room.

Every engine follows one rule: degrade loudly, never silently. A missing torch install or an unreadable checkpoint sets ok = False and returns None/[] — it never raises into a caller's turn loop and never fabricates a prediction. That property mattered more than any architecture choice; see RESULTS.md.

Install

```bash
pip install -e ".[torch]"   # torch + numpy are optional; engines degrade loudly without them

Quick use

```python
from awpredict.core.mlp import MLPWorldModel

model = MLPWorldModel()
model.observe(state, action, next_state, reward=0.0, done=False)
model.train_step()
z = model.encode(state)
pred = model.predict(z, action)
print(model.surprise(state, action, next_state))

Why this exists

The goal is to help someone bootstrap their own world model — a working engine, a planner, an optional value head, a contract to write your own adapter against, and no framework lock-in — not a stripped demo pointing at a hosted service. This is the actual core out of a larger internal agent platform (Aitherium), extracted whole rather than trimmed, plus the findings from running it against ARC-AGI-3: see RESULTS.md for the honest version, including two negative results that mattered more than any positive one.

Status

Research code. The contracts and degrade-loudly discipline are load-bearing and tested (tests/); the engines themselves are still moving. lewm.py is the same file the ARC-AGI-3 solving agent runs, value head included — see awpredict/__init__.py for what's on by default vs. opt-in.

License

MIT (see LICENSE). See awpredict/training/PROVENANCE.md for the one file with an external concept-attribution.

Aitherium open-source ecosystem

This repo is one piece of a connected set. All public, MIT/BSL-licensed:

Built by Aitherium.

The aw family

Standalone tools that share one idea: replace something you would otherwise have to trust with something you can check.

Each installs on its own, works offline, and needs no account.

awnix is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.

The Aitherium ecosystem

Every repository here is public. Each publishes an aither-manifest.json beside its page, so any surface can read every sibling's — the network is browsable from any node in it.

Built on llama.cpp · vLLM · ComfyUI · CentOS Stream · Podman · Docker · LanceDB · WireGuard · FFmpeg · Blender + Rigify · headroom · SANA · Hunyuan3D · repowise · Playwright · Chromium · Next.js · React.