Metadata-Version: 2.4
Name: world-model-harness
Version: 0.1.0
Summary: Run agents, build world models from traces, and optimize agent harnesses.
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.39
Requires-Dist: boto3>=1.34
Requires-Dist: click>=8.2
Requires-Dist: environment-capture
Requires-Dist: fastapi>=0.110
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>=13.7
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.29
Provides-Extra: connectors
Requires-Dist: mcp>=1.27; extra == 'connectors'
Provides-Extra: dev
Requires-Dist: e2b>=2.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: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: seaborn>=0.13; extra == 'dev'
Requires-Dist: ty>=0.0.1a1; extra == 'dev'
Provides-Extra: e2b
Requires-Dist: e2b>=2.0; extra == 'e2b'
Provides-Extra: otel
Requires-Dist: opentelemetry-proto>=1.24; extra == 'otel'
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 Harness

`wmh` 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-harness/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 WMH, choose the model provider for the built-in runtime agent, and start a local run:

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

Build a named world model from collected traces:

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

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

```bash
wmh optimize 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
wmh login
```

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

```bash
wmh 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-harness[e2b]"
export E2B_API_KEY=...
wmh optimize my-agent my-environment --tasks tasks.jsonl --backend e2b
```

## Use a world model as an API

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

model_dir = WorldModelStore(".wmh").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 `wmh login`, the same `wmh 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
wmh login
wmh run <world-model-or-agent-id>
wmh run <agent-id> -u . --task "fix the failing tests"
```

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

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

## Runtime agents and optimizers in E2B sandboxes

WMH 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
wmh optimize my-agent my-environment --tasks tasks.jsonl --backend e2b
wmh 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

`wmh` 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 wmh config telemetry disable
```

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