Metadata-Version: 2.4
Name: openral-wam
Version: 0.1.0
Summary: OpenRAL World Action Model layer — WorldModel Protocol + Rollout schema (CLAUDE.md §6.3)
License: Apache-2.0
Requires-Python: <3.13,>=3.12
Requires-Dist: openral-core
Requires-Dist: openral-observability
Requires-Dist: pydantic>=2.5
Requires-Dist: structlog>=24.1
Description-Content-Type: text/markdown

# openral-wam

OpenRAL World Action Model (WAM) layer — `WorldModel` Protocol +
`Rollout` schema + `NullWorldModel` stub.

> **Scaffold status (2026-05-18).** This package ships the **Protocol surface only**:
> `WorldModel`, `Rollout`, and a `NullWorldModel` stub for plumbing tests.
> Concrete adapters (Cosmos Predict, UnifoLM-WMA-0, IRASim) land in
> v0.3+ per CLAUDE.md §6.3. Those concrete generative WAM adapters ship as separate downstream
> packages in the private OpenRAL Pro monorepo — this public package
> stays the Protocol/contract surface.

## Layer

CLAUDE.md §6.1 Layer 5 — generative simulator used by the planning loop
for mental simulation (gating action chunks), failure anticipation, and
replanning.

## Three integration patterns (CLAUDE.md §6.3)

1. **Mental simulation (gating)** — sample N short rollouts before
   committing an action chunk. Threshold via `Rollout.confidence`.
2. **Failure anticipation** — continuous predicted-vs-observed
   discrepancy detector. The `WorldStateAggregator` and the WAM share a
   trace span; divergence raises a `FailureTrigger`.
3. **Replanning loop** — propose alternative subgoals as visual
   prompts; the reasoner re-prompts with the predicted-but-failed
   trajectory as context.

All three consume the same surface — `WorldModel.rollout(...)` →
`Rollout` — so the Protocol is sufficient for v0.2.

## Public surface

```python
from openral_wam import WorldModel, Rollout, NullWorldModel
```

- `WorldModel` — structural Protocol every WAM adapter satisfies.
- `Rollout` — Pydantic v2 schema for the predicted trajectory.
- `NullWorldModel` — identity stub returning the input state for
  `horizon` steps.

## ADRs

- Pydantic v2 preferred over `@dataclass` for schemas/configs.
- CLAUDE.md §6.3 — the canonical write-up of the three integration
  patterns; a dedicated ADR will follow when the first concrete
  adapter lands.
