awp-python 0.1.0a3__tar.gz → 0.1.0a4__tar.gz

{awp_python-0.1.0a3 → awp_python-0.1.0a4}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.0a4
+
+Targets specification revision `0.1-draft.9`.
+
+- The reference world moves to its own package, [awp-sim](https://github.com/Hyperduality/awp-sim), and awp-python is the agent SDK alone.
+- `awp-sim demo` becomes `awp-demo` (`awp.demo`). It reads `$AWP_URL` and `$AWP_TOKEN` when its flags are absent.
+- Tests run against a scripted world over WebSockets instead of awp-sim, and CI runs awp-conformance against `awp-demo` in both time models.
+
 ## 0.1.0a3
 
 Targets specification revision `0.1-draft.9`.

awp_python-0.1.0a4/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: awp-python
+Version: 0.1.0a4
+Summary: Agent World Protocol agent SDK for Python.
+Project-URL: Specification, https://www.agentworldprotocol.com
+Project-URL: Source, https://github.com/Hyperduality/awp-python
+Author: Hyperduality
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# awp-python
+
+The Python agent SDK for the [Agent World Protocol](https://www.agentworldprotocol.com). `ClientConnection` is the agent side of AWP as a sans-IO state machine, and `awp.aio.AsyncClient` drives it over a WebSocket.
+
+It targets specification revision **`0.1-draft.9`**, pinned as the `spec/` submodule. This is an alpha, so the API will change along with the draft. The reference world, [awp-sim](https://github.com/Hyperduality/awp-sim), is a separate package built on this one.
+
+## Status
+
+![AWP: Core Agent, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_Agent%2C_conformant_0.1--draft.9-555)
+
+In both time models, the demo agent built on the client is **Core Agent: AWP-conformant against 0.1-draft.9**. [awp-conformance](https://github.com/Hyperduality/awp-conformance) reports no failure and nothing untested, and [`conformance/`](conformance/README.md) holds the reports and the evidence for their manual rows. CI runs the suite against the demo agent on every change.
+
+| Implemented | Not implemented |
+|---|---|
+| Lockstep and streaming sessions; `world.tick` advances that wait for every per-tick channel | Multi-bind (`embodiments`) |
+| Inline and `ws` stream bindings; binary frame codec (every spec vector) | Other stream bindings (`webrtc`, `webtransport`, `shm`, `grpc`) |
+| Action lifecycle checked against the spec's transition table; idempotent resubmission | |
+| Heartbeats, clock synchronization, receiver reports, resumption with replay and acknowledgement | |
+| Canonical schema validation in receiver and sender forms | |
+| Task, approval and standing approvals, transfer, reset, snapshots, and command channels | |
+
+## Install
+
+```bash
+pip install --pre awp-python
+```
+
+Requires Python 3.11+.
+
+## Using the client
+
+With asyncio:
+
+```python
+from awp import ClientConnection
+from awp.aio import AsyncClient
+
+conn = ClientConnection({"name": "my-agent", "version": "0.1.0", "vendor": "me"}, ["proprio/json"])
+async with AsyncClient(conn, "ws://127.0.0.1:8710") as client:
+    await client.initialize()
+    await client.open_session("streaming", embodiment="arm_01", subscribe=["proprio"])
+    await client.wait_for(lambda e: "proprio" in client.latest)
+    record = await client.submit(
+        "move_to_pose",
+        {"pose": {"frame": "base", "p_m": [0.3, 0.2, 0.5], "q": [0, 0, 0, 1]}},
+        basis=client.latest["proprio"].frame,  # the observation this intent rests on
+        valid_for_ms=200,
+    )
+    print((await client.wait_terminal(record.action_id)).state)
+    await client.close_session()
+```
+
+Without asyncio, feed `ClientConnection` the decoded messages and send whatever it queues:
+
+```python
+events = conn.receive(message)  # typed events: ActionUpdated, FrameReceived, ...
+for out in conn.outgoing():  # messages to send, in order
+    transport.send(json.dumps(out))
+```
+
+The connection:
+
+- tracks the action lifecycle against the spec's transition table;
+- deduplicates replayed statuses;
+- keeps the clock offset from heartbeats;
+- reports any violation by the world as a `ProtocolViolation` event.
+
+## The demo agent
+
+`awp-demo` is a scripted agent for awp-sim's arm. It moves, cancels a move, and triggers an envelope refusal. It rides out a lost connection by resuming the session, or by opening a new one if the world no longer holds it.
+
+```bash
+pip install --pre awp-sim
+awp-sim serve &                      # streaming world on ws://127.0.0.1:8710
+awp-demo                             # or --url, --token ($AWP_URL, $AWP_TOKEN)
+```
+
+## Layout
+
+```
+src/awp/            client protocol layer (sans-IO), asyncio adapter, frame codec, schemas, demo agent
+src/awp/_spec/      schemas and lifecycle table bundled from spec/ (scripts/sync_spec.py)
+tests/              unit tests, and a scripted world that serves over WebSockets
+conformance/        conformance reports, the manifests they were run against, and evidence
+spec/               agent-world-protocol, pinned at spec-v0.1-draft.9
+```
+
+## Development
+
+```bash
+git clone --recurse-submodules https://github.com/Hyperduality/awp-python
+cd awp-python
+uv sync
+uv run ruff check && uv run ruff format --check
+uv run mypy
+uv run pytest --cov
+uv run python scripts/sync_spec.py --check
+```
+
+To move to a new draft revision:
+
+1. Check out its tag in `spec/`.
+2. Run `scripts/sync_spec.py`.
+3. Update `SPEC_REVISION` in `src/awp/__init__.py`.
+4. Fix whatever the tests report.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

awp_python-0.1.0a4/README.md

@@ -0,0 +1,109 @@
+# awp-python
+
+The Python agent SDK for the [Agent World Protocol](https://www.agentworldprotocol.com). `ClientConnection` is the agent side of AWP as a sans-IO state machine, and `awp.aio.AsyncClient` drives it over a WebSocket.
+
+It targets specification revision **`0.1-draft.9`**, pinned as the `spec/` submodule. This is an alpha, so the API will change along with the draft. The reference world, [awp-sim](https://github.com/Hyperduality/awp-sim), is a separate package built on this one.
+
+## Status
+
+![AWP: Core Agent, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_Agent%2C_conformant_0.1--draft.9-555)
+
+In both time models, the demo agent built on the client is **Core Agent: AWP-conformant against 0.1-draft.9**. [awp-conformance](https://github.com/Hyperduality/awp-conformance) reports no failure and nothing untested, and [`conformance/`](conformance/README.md) holds the reports and the evidence for their manual rows. CI runs the suite against the demo agent on every change.
+
+| Implemented | Not implemented |
+|---|---|
+| Lockstep and streaming sessions; `world.tick` advances that wait for every per-tick channel | Multi-bind (`embodiments`) |
+| Inline and `ws` stream bindings; binary frame codec (every spec vector) | Other stream bindings (`webrtc`, `webtransport`, `shm`, `grpc`) |
+| Action lifecycle checked against the spec's transition table; idempotent resubmission | |
+| Heartbeats, clock synchronization, receiver reports, resumption with replay and acknowledgement | |
+| Canonical schema validation in receiver and sender forms | |
+| Task, approval and standing approvals, transfer, reset, snapshots, and command channels | |
+
+## Install
+
+```bash
+pip install --pre awp-python
+```
+
+Requires Python 3.11+.
+
+## Using the client
+
+With asyncio:
+
+```python
+from awp import ClientConnection
+from awp.aio import AsyncClient
+
+conn = ClientConnection({"name": "my-agent", "version": "0.1.0", "vendor": "me"}, ["proprio/json"])
+async with AsyncClient(conn, "ws://127.0.0.1:8710") as client:
+    await client.initialize()
+    await client.open_session("streaming", embodiment="arm_01", subscribe=["proprio"])
+    await client.wait_for(lambda e: "proprio" in client.latest)
+    record = await client.submit(
+        "move_to_pose",
+        {"pose": {"frame": "base", "p_m": [0.3, 0.2, 0.5], "q": [0, 0, 0, 1]}},
+        basis=client.latest["proprio"].frame,  # the observation this intent rests on
+        valid_for_ms=200,
+    )
+    print((await client.wait_terminal(record.action_id)).state)
+    await client.close_session()
+```
+
+Without asyncio, feed `ClientConnection` the decoded messages and send whatever it queues:
+
+```python
+events = conn.receive(message)  # typed events: ActionUpdated, FrameReceived, ...
+for out in conn.outgoing():  # messages to send, in order
+    transport.send(json.dumps(out))
+```
+
+The connection:
+
+- tracks the action lifecycle against the spec's transition table;
+- deduplicates replayed statuses;
+- keeps the clock offset from heartbeats;
+- reports any violation by the world as a `ProtocolViolation` event.
+
+## The demo agent
+
+`awp-demo` is a scripted agent for awp-sim's arm. It moves, cancels a move, and triggers an envelope refusal. It rides out a lost connection by resuming the session, or by opening a new one if the world no longer holds it.
+
+```bash
+pip install --pre awp-sim
+awp-sim serve &                      # streaming world on ws://127.0.0.1:8710
+awp-demo                             # or --url, --token ($AWP_URL, $AWP_TOKEN)
+```
+
+## Layout
+
+```
+src/awp/            client protocol layer (sans-IO), asyncio adapter, frame codec, schemas, demo agent
+src/awp/_spec/      schemas and lifecycle table bundled from spec/ (scripts/sync_spec.py)
+tests/              unit tests, and a scripted world that serves over WebSockets
+conformance/        conformance reports, the manifests they were run against, and evidence
+spec/               agent-world-protocol, pinned at spec-v0.1-draft.9
+```
+
+## Development
+
+```bash
+git clone --recurse-submodules https://github.com/Hyperduality/awp-python
+cd awp-python
+uv sync
+uv run ruff check && uv run ruff format --check
+uv run mypy
+uv run pytest --cov
+uv run python scripts/sync_spec.py --check
+```
+
+To move to a new draft revision:
+
+1. Check out its tag in `spec/`.
+2. Run `scripts/sync_spec.py`.
+3. Update `SPEC_REVISION` in `src/awp/__init__.py`.
+4. Fix whatever the tests report.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

awp_python-0.1.0a4/conformance/README.md

@@ -0,0 +1,53 @@
+# Conformance
+
+![AWP: Core Agent, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_Agent%2C_conformant_0.1--draft.9-555)
+
+| Class | Configuration | Claim | Report |
+|---|---|---|---|
+| Core Agent | `awp-demo`, [`manifest-lockstep.json`](manifest-lockstep.json) | Core Agent (lockstep): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`core-agent-lockstep.json`](core-agent-lockstep.json) |
+| Core Agent | `awp-demo`, [`manifest-streaming.json`](manifest-streaming.json) | Core Agent (streaming): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`core-agent-streaming.json`](core-agent-streaming.json) |
+
+The reports come from awp-conformance 0.1.0a3 run against awp-python 0.1.0a4. Neither has a failure or anything untested. The evidence for their `manual` rows is below (AWP-CNF-005).
+
+## Reproduce
+
+The suite serves each manifest from its harness world and runs the demo agent against it. The manifests are awp-sim's (`awp-sim manifest --mode lockstep`, `--mode streaming`). [`frames.json`](frames.json) gives the harness one sample payload per channel.
+
+```bash
+pip install --pre awp-python awp-conformance
+awp-conformance agent --manifest conformance/manifest-lockstep.json --frames conformance/frames.json \
+  --mode lockstep --out report/ -- awp-demo --url '{url}' --token '{token}'
+```
+
+For streaming, use `manifest-streaming.json` with `--mode streaming`. CI runs both on every change. The tests cited below run in CI too:
+
+```bash
+uv run pytest tests/test_frames.py tests/test_evidence.py
+```
+
+## Manual evidence
+
+### AWP-DAT-001, AWP-DAT-009: loss accounting at the receiver (lockstep)
+
+In streaming, the suite reads the agent's loss accounting from its `obs.report`. Lockstep sessions send no `obs.report`, so these rows are `manual` there.
+
+- `test_the_receiver_counts_seq_gaps_as_loss_but_not_the_gap_before_a_resync` (`tests/test_evidence.py`) runs in each time model:
+  - on one channel, frames that skip two `seq` values count two missing frames in `ClientConnection.delivery()`;
+  - on another, a resync frame after a gap of five counts none.
+- The client holds no delta state. Each frame reaches the application whole, with its `keyframe` and `resync` flags.
+
+### AWP-DAT-008: frame test vectors
+
+`test_vectors` (`tests/test_frames.py`) runs `awp.frames` over every vector in `schemas/test-vectors/frames.json` of the `spec/` submodule, which is pinned at `spec-v0.1-draft.9`:
+
+- the 10 valid vectors decode to their listed fields;
+- the 7 marked `expect_error` are rejected with their listed error.
+
+`test_roundtrip_without_vendor` re-encodes the 8 valid vectors that have no unknown extension or reserved bits, and each matches byte for byte.
+
+### AWP-VER-009: the draft revision is named
+
+- The [README](../README.md) and the [Python SDK page](https://www.agentworldprotocol.com/sdks/python) name `0.1-draft.9`.
+- `awp.SPEC_REVISION` is `"0.1-draft.9"`.
+- The `spec/` submodule is pinned at the tag `spec-v0.1-draft.9`.
+- Each report records `"specification": "0.1-draft.9"`, and its claim names the revision.

{awp_python-0.1.0a3 → awp_python-0.1.0a4}/conformance/core-agent-lockstep.json

@@ -4,9 +4,9 @@
     "version": "0.1.0a3"
   },
   "specification": "0.1-draft.9",
-  "target": "/Users/archivec/Documents/Code/Hyperduality/awp-conformance/.venv/bin/awp-sim demo --url {url} --token {token}",
+  "target": "awp-demo --url {url} --token {token}",
   "side": "agent",
-  "generated": "2026-09-25T19:40:36Z",
+  "generated": "2026-09-25T21:46:19Z",
   "claim": {
     "status": "conformant",
     "wording": "Core Agent (lockstep): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3)",
@@ -138,7 +138,7 @@
       "id": "AWP-AGT-006",
       "level": "MUST",
       "outcome": "pass",
-      "detail": "23 check(s): lockstep/baseline, lockstep/integer-range, lockstep/malformed-frame, lockstep/reconnect, lockstep/restarted-world, lockstep/silent-world"
+      "detail": "23 check(s): lockstep/baseline, lockstep/malformed-frame, lockstep/reconnect, lockstep/restarted-world, lockstep/silent-world"
     },
     {
       "id": "AWP-AGT-007",
@@ -1206,7 +1206,7 @@
       "id": "AWP-TIM-003",
       "level": "MUST",
       "outcome": "pass",
-      "detail": "8 check(s): lockstep/baseline, lockstep/malformed-frame, lockstep/reconnect, lockstep/restarted-world"
+      "detail": "5 check(s): lockstep/baseline, lockstep/malformed-frame, lockstep/reconnect, lockstep/restarted-world"
     },
     {
       "id": "AWP-TIM-004",

{awp_python-0.1.0a3 → awp_python-0.1.0a4}/conformance/core-agent-streaming.json

@@ -4,9 +4,9 @@
     "version": "0.1.0a3"
   },
   "specification": "0.1-draft.9",
-  "target": "/Users/archivec/Documents/Code/Hyperduality/awp-conformance/.venv/bin/awp-sim demo --url {url} --token {token}",
+  "target": "awp-demo --url {url} --token {token}",
   "side": "agent",
-  "generated": "2026-09-25T19:40:57Z",
+  "generated": "2026-09-25T21:46:39Z",
   "claim": {
     "status": "conformant",
     "wording": "Core Agent (streaming): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3)",

awp_python-0.1.0a4/conformance/frames.json

@@ -0,0 +1,4 @@
+{
+  "proprio": { "p_m": [0, 0, 0.4], "v_mps": [0, 0, 0] },
+  "arm_state": { "phase": "idle", "target_m": null, "action_id": null }
+}

awp_python-0.1.0a4/conformance/manifest-lockstep.json

@@ -0,0 +1,157 @@
+{
+  "protocol_version": "0.1",
+  "world": {
+    "name": "awp-sim",
+    "version": "0.1.0a4",
+    "vendor": "hyperduality"
+  },
+  "time_models": [
+    "lockstep"
+  ],
+  "capabilities": {},
+  "initial_states": [
+    "home"
+  ],
+  "embodiments": [
+    {
+      "id": "arm_01",
+      "kind": "manipulator",
+      "action_types": [
+        "move_to_pose",
+        "stop"
+      ],
+      "channels": [
+        "proprio",
+        "arm_state"
+      ]
+    }
+  ],
+  "observation_channels": [
+    {
+      "id": "proprio",
+      "modality": "proprio/json",
+      "rate_hz": null,
+      "loss_class": "latest-wins",
+      "stale_after_ms": 50,
+      "schema": {
+        "fields": [
+          "p_m",
+          "v_mps"
+        ],
+        "frame": "base"
+      }
+    },
+    {
+      "id": "arm_state",
+      "modality": "text/event+json",
+      "rate_hz": null,
+      "loss_class": "reliable",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": {
+            "enum": [
+              "idle",
+              "moving",
+              "stopping",
+              "servo"
+            ]
+          },
+          "target_m": {
+            "type": [
+              "array",
+              "null"
+            ]
+          },
+          "action_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "phase",
+          "target_m",
+          "action_id"
+        ]
+      }
+    }
+  ],
+  "action_schemas": [
+    {
+      "type": "move_to_pose",
+      "params_schema": {
+        "$ref": "#/$defs/move_to_pose_params"
+      },
+      "duration": "extended",
+      "preemption": [
+        "replace",
+        "queue",
+        "reject"
+      ],
+      "concurrency_group": "arm_motion",
+      "max_queue": 4,
+      "max_abort_ms": 1500,
+      "max_duration_ms": 10000,
+      "description": "Move the end effector in a straight line to a position."
+    },
+    {
+      "type": "stop",
+      "params_schema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "duration": "instant",
+      "preemption": "replace",
+      "concurrency_group": "arm_motion",
+      "description": "Decelerate to rest; replaces any motion."
+    }
+  ],
+  "safety_policy": {
+    "envelopes": [
+      {
+        "embodiment": "arm_01",
+        "spatial": {
+          "frame": "base",
+          "aabb_m": [
+            [
+              -0.5,
+              -0.5,
+              0.0
+            ],
+            [
+              0.5,
+              0.5,
+              0.8
+            ]
+          ]
+        },
+        "max_velocity_mps": 0.5,
+        "max_action_rate_hz": 20.0,
+        "enforcement": "command_check",
+        "on_violation": "reject"
+      }
+    ]
+  },
+  "$defs": {
+    "move_to_pose_params": {
+      "type": "object",
+      "properties": {
+        "pose": {
+          "$ref": "https://agentworldprotocol.com/schemas/v0.1/common.schema.json#/$defs/pose"
+        },
+        "max_velocity_mps": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      },
+      "required": [
+        "pose"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "tick_policy": "on_tick",
+  "tick_authority": "any_session"
+}

awp_python-0.1.0a4/conformance/manifest-streaming.json

@@ -0,0 +1,160 @@
+{
+  "protocol_version": "0.1",
+  "world": {
+    "name": "awp-sim",
+    "version": "0.1.0a4",
+    "vendor": "hyperduality"
+  },
+  "time_models": [
+    "streaming"
+  ],
+  "capabilities": {},
+  "initial_states": [
+    "home"
+  ],
+  "embodiments": [
+    {
+      "id": "arm_01",
+      "kind": "manipulator",
+      "action_types": [
+        "move_to_pose",
+        "stop"
+      ],
+      "channels": [
+        "proprio",
+        "arm_state"
+      ]
+    }
+  ],
+  "observation_channels": [
+    {
+      "id": "proprio",
+      "modality": "proprio/json",
+      "rate_hz": 100.0,
+      "loss_class": "latest-wins",
+      "stale_after_ms": 50,
+      "schema": {
+        "fields": [
+          "p_m",
+          "v_mps"
+        ],
+        "frame": "base"
+      }
+    },
+    {
+      "id": "arm_state",
+      "modality": "text/event+json",
+      "rate_hz": 10.0,
+      "loss_class": "reliable",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": {
+            "enum": [
+              "idle",
+              "moving",
+              "stopping",
+              "servo"
+            ]
+          },
+          "target_m": {
+            "type": [
+              "array",
+              "null"
+            ]
+          },
+          "action_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "phase",
+          "target_m",
+          "action_id"
+        ]
+      }
+    }
+  ],
+  "action_schemas": [
+    {
+      "type": "move_to_pose",
+      "params_schema": {
+        "$ref": "#/$defs/move_to_pose_params"
+      },
+      "duration": "extended",
+      "preemption": [
+        "replace",
+        "queue",
+        "reject"
+      ],
+      "concurrency_group": "arm_motion",
+      "max_queue": 4,
+      "max_abort_ms": 1500,
+      "max_duration_ms": 10000,
+      "description": "Move the end effector in a straight line to a position."
+    },
+    {
+      "type": "stop",
+      "params_schema": {
+        "type": "object",
+        "additionalProperties": false
+      },
+      "duration": "instant",
+      "preemption": "replace",
+      "concurrency_group": "arm_motion",
+      "description": "Decelerate to rest; replaces any motion."
+    }
+  ],
+  "safety_policy": {
+    "envelopes": [
+      {
+        "embodiment": "arm_01",
+        "spatial": {
+          "frame": "base",
+          "aabb_m": [
+            [
+              -0.5,
+              -0.5,
+              0.0
+            ],
+            [
+              0.5,
+              0.5,
+              0.8
+            ]
+          ]
+        },
+        "max_velocity_mps": 0.5,
+        "max_action_rate_hz": 20.0,
+        "enforcement": "command_check",
+        "on_violation": "reject"
+      }
+    ],
+    "safe_state": {
+      "behavior": "safe_stop",
+      "watchdog_ms": 2000
+    },
+    "max_basis_age_ms": 500
+  },
+  "$defs": {
+    "move_to_pose_params": {
+      "type": "object",
+      "properties": {
+        "pose": {
+          "$ref": "https://agentworldprotocol.com/schemas/v0.1/common.schema.json#/$defs/pose"
+        },
+        "max_velocity_mps": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      },
+      "required": [
+        "pose"
+      ],
+      "additionalProperties": false
+    }
+  }
+}