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

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

@@ -1,5 +1,23 @@
 # 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_sim`: standing approvals (AWP-APR-004), declared as `safety_policy.standing_approvals` with the approval feature; a submission within a grant is admitted without approval and its result names the grant's `approval_id`.
+- `awp`: `AsyncClient.advance` returns once every subscribed per-tick channel holds a frame of the new tick, which on a stream connection may follow the result (AWP-TIM-003). A `session.resume` answered `AWP_SESSION_UNKNOWN` closes the session and forgets its actions (AWP-SES-008). `respond_approval` takes `standing`.
+- `awp-sim demo` resumes after a lost connection, or opens a new session if the world no longer holds it.
+- `awp_sim`: an integer beyond 2^53-1 closes the session with reason `protocol_error` and the connection with code 1002 (AWP-CTL-009); a malformed frame on a stream connection closes it with code 1002 and `AWP_MALFORMED` (AWP-DAT-010); after a lockstep resumption every per-tick channel restarts with a resync keyframe at the current tick (AWP-TIM-009); after a reset the fresh frames precede the result (AWP-PRM-006).
+- `awp`: an integer beyond 2^53-1 ends the session with `session.close` and close code 1002; a malformed stream frame is dropped and its stream connection closed and re-established; frames with `resync` but not `keyframe` are malformed. While a lost stream connection is down, `AsyncClient.command` raises instead of sending inline (AWP-TRN-010). `ClientConnection.receive_frame` raises for a malformed frame, and `delivery()` reports each channel's frames and gaps.
+
 ## 0.1.0a2
 
 Targets specification revision `0.1-draft.8`.

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.