Metadata-Version: 2.4
Name: world-model-optimizer
Version: 0.2.0
Summary: Run agents, build world models from traces, and optimize agent harnesses.
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.39
Requires-Dist: boto3>=1.34
Requires-Dist: click>=8.2
Requires-Dist: environment-capture
Requires-Dist: fastapi>=0.128
Requires-Dist: gepa>=0.1.1
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: openai>=1.40
Requires-Dist: posthog>=7.0
Requires-Dist: pydantic>=2.6
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: rich>=14.1
Requires-Dist: scikit-learn>=1.4
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.16
Requires-Dist: uvicorn>=0.38
Provides-Extra: connectors
Requires-Dist: mcp>=1.27; extra == 'connectors'
Provides-Extra: dev
Requires-Dist: e2b==2.31.0; extra == 'dev'
Requires-Dist: harbor==0.20.0; extra == 'dev'
Requires-Dist: matplotlib>=3.8; extra == 'dev'
Requires-Dist: mcp>=1.27; extra == 'dev'
Requires-Dist: opentelemetry-proto>=1.24; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: seaborn>=0.13; extra == 'dev'
Requires-Dist: tinker-cookbook<0.5,>=0.4.3; extra == 'dev'
Requires-Dist: tinker<0.24,>=0.23; extra == 'dev'
Requires-Dist: ty>=0.0.1a1; extra == 'dev'
Requires-Dist: wandb>=0.17; extra == 'dev'
Provides-Extra: distill
Requires-Dist: tinker-cookbook<0.5,>=0.4.3; extra == 'distill'
Requires-Dist: tinker<0.24,>=0.23; extra == 'distill'
Requires-Dist: wandb>=0.17; extra == 'distill'
Provides-Extra: e2b
Requires-Dist: e2b==2.31.0; extra == 'e2b'
Provides-Extra: harbor
Requires-Dist: harbor==0.20.0; extra == 'harbor'
Provides-Extra: otel
Requires-Dist: opentelemetry-proto>=1.24; extra == 'otel'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Requires-Dist: pandas>=2.0; extra == 'viz'
Requires-Dist: seaborn>=0.13; extra == 'viz'
Description-Content-Type: text/markdown

# World Model Optimizer

`wmo` is an open-source project for running and building continuously improving agents. It
includes a flexible agent runtime, a world model that simulates tool calls, and an optimizer that
builds task-specific harnesses for stronger performance at lower cost.

![World model, runtime agent, and optimizer connected in a continuous improvement loop](assets/world-model-agent-loop.svg)

<p align="center">
  🌐 <a href="https://platform.experientiallabs.ai">Platform</a> |
  📚 <a href="https://github.com/experientiallabs/world-model-optimizer/tree/main/docs">Docs</a> |
  <a href="https://discord.gg/QwjJpEyHd"><img src="https://cdn.simpleicons.org/discord/5865F2" alt="" width="16" height="16"> Discord</a>
</p>

## Getting started

### Local setup

Install WMO, choose the model provider for the built-in runtime agent, and start a local run:

```bash
pip install world-model-optimizer
wmo providers set
wmo run --task "Inspect this repository and explain it"
```

Build a named world model from collected traces:

```bash
wmo build --file traces.jsonl --name my-environment
```

Then optimize an agent harness against that model and a set of tasks:

```bash
wmo optimize harness my-agent my-environment --tasks tasks.jsonl
```

### Hosted platform

Create an account at [platform.experientiallabs.ai](https://platform.experientiallabs.ai), then
authenticate the CLI:

```bash
wmo login
```

Copy an agent ID from the platform and run its current champion harness:

```bash
wmo run <agent-id>
```

### E2B backend

Hosted agents already run in platform-managed E2B sandboxes. To evaluate a local optimization in
E2B, install the extra and provide an E2B key:

```bash
pip install "world-model-optimizer[e2b]"
export E2B_API_KEY=...
wmo optimize harness my-agent my-environment --tasks tasks.jsonl --backend e2b
```

## Use a world model as an API

```python
from wmo import Action, ActionKind
from wmo.config.store import WorldModelStore
from wmo.engine.loader import load_world_model

model_dir = WorldModelStore(".wmo").resolve("airline")
wm, _provider = load_world_model(model_dir)

session = wm.new_session(task="check out the cart")
obs = wm.step(session.id, Action(kind=ActionKind.TOOL_CALL, name="add_to_cart",
                                 arguments={"sku": "A1"}))
print(obs.content)
```

Or over HTTP (same code path), namespaced by model name: `GET /world_models`, then `POST /world_models/{name}/sessions` and `POST /world_models/{name}/sessions/{id}/step`.

## Run after platform login

After `wmo login`, the same `wmo run` command can open a hosted world model or run an agent's
current champion harness in E2B. The platform manages model and sandbox credentials, so hosted
runs do not need local API keys.

```bash
wmo login
wmo run <world-model-or-agent-id>
wmo run <agent-id> -u . --task "fix the failing tests"
```

Workspace upload is opt-in with `-u`: WMO live-syncs changes and preserves concurrent local edits.
Long-running agents can detach, continue in the platform, and be messaged or reattached later.

```bash
wmo run <agent-id> -u . --detach
wmo run --send "Now run the full test suite"
wmo run --attach
wmo run --end
```

## Runtime agents and optimizers in E2B sandboxes

WMO can run the real [pi](https://github.com/earendil-works/pi) worker inside isolated
[E2B](https://e2b.dev) sandboxes while the world model supplies the environment. Optimization and
evaluation rollouts run in parallel, and model credentials stay outside the sandbox.

```bash
wmo optimize harness my-agent my-environment --tasks tasks.jsonl --backend e2b
wmo eval tasks.jsonl --mode closed-loop --harness my-agent --harness-backend e2b
```

The optimizer can change prompts, tools, policies, skills, and runtime code. Every candidate is
measured against the same simulated tasks, and only changes that pass the evaluation gates become
the new versioned champion harness.

## Development

Managed with [uv](https://docs.astral.sh/uv/); linting/formatting with [ruff](https://docs.astral.sh/ruff/); type checking with [ty](https://github.com/astral-sh/ty). Conventions live in [AGENTS.md](./AGENTS.md).

```bash
uv sync --extra dev      # env + dev tools
uv run ruff check .      # lint
uv run ruff format .     # format
uv run ty check          # type check
uv run pytest -q         # tests
```

## Usage telemetry

`wmo` uses anonymous usage telemetry to track the volume of usage.
Telemetry is strictly metadata. It never includes prompts, traces, actions, observations, file paths,
model names, provider credentials, or raw user content.

Telemetry is enabled by default. To opt out for a project:

```bash
uv run wmo config telemetry disable
```

This writes `.wmo/settings.toml`. You can re-enable it with `uv run wmo config telemetry enable`,
check the current setting with `uv run wmo config telemetry status`, or disable it for a process
with `DO_NOT_TRACK=1` or `WMO_TELEMETRY=0`.
