abstract-client 0.2.2__tar.gz → 0.3.0__tar.gz

{abstract_client-0.2.2 → abstract_client-0.3.0}/NOTICE

@@ -1,9 +1,9 @@
-abstract-client (Abstract's robot API from Python, import name atoms)
+abstract-client (Abstract's robot API from Python, import name abstract)
 Copyright 2026 Abstract
 
 Licensed under the Apache License, Version 2.0 (LICENSE).
 
-The harness (atoms.AtomsClient) reproduces the calls of dreamlabs-client's DreamClient (policy,
+The harness (abstract.RobotClient) reproduces the calls of dreamlabs-client's DreamClient (policy,
 set_observation, get_action, reset_episode, refill_due, close, last_timing), and its frame
 window, refill pacing and slow-network warning are ported from dreamlabs-client
 (https://github.com/dreamlabs-co/dreamlabs), first through the TypeScript harness

abstract_client-0.2.2/README.md → abstract_client-0.3.0/PKG-INFO

@@ -1,4 +1,29 @@
-# abstract-client
+Metadata-Version: 2.5
+Name: abstract-client
+Version: 0.3.0
+Summary: Abstract's robot API from Python: action chunks from served robot models, sync and asyncio.
+Project-URL: Homepage, https://abstract.inc
+Project-URL: Documentation, https://docs.abstract.inc
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx2<3,>=2.12
+Provides-Extra: quic
+Requires-Dist: aioquic<2,>=1.3; extra == 'quic'
+Description-Content-Type: text/markdown
+
+# abstract.client
 
 Abstract's robot API from Python. A `Client` holds your key and its connections and is safe to
 share between threads; each `Policy` is one episode of one served robot model doing one task, one
@@ -8,12 +33,12 @@ action chunk per `predict()`.
 uv add abstract-client
 ```
 
-### Quickstart (0.2.2)
+### Quickstart (0.3.0)
 
 ```python
 import abstract
 
-checkpoint = "nvidia/dreamzero"
+checkpoint = "allenai/molmoact2"
 embodiment = "yam"
 client = abstract.client(ABSTRACT_API_KEY, checkpoint, embodiment)
 
@@ -28,24 +53,27 @@ holds `prompt` (the task) and `state` (measured alongside the frames). The YAM c
 state fields are shown below. The returned `Chunk` contains targets, never hardware motion;
 reset ends the model's episode without repositioning the robot.
 
-`abstract.client()` checks the account's unmetered model catalogue before configuring an
-`AtomsClient`. The checkpoint must be available and its `robot` must match `embodiment`.
-It does not adapt models to other robots. Omit `api_key` to use the environment or saved
+`abstract.client()` checks the account's unmetered model catalogue before configuring a
+`RobotClient`. The checkpoint must be available and its `robot` must match `embodiment`.
+An optional URDF layer converts poses to another arm's joint geometry; it does not establish
+policy transfer. Omit `api_key` to use the environment or saved
 CLI credentials; connection options such as `base_url` and `timeout` pass through to the
-existing client. Context managers and the existing `atoms` interface remain supported.
+existing client. Context managers and the lower-level `abstract.Client` interface remain supported.
 
-Release order: publish the matching 0.2.2 SDK before deploying the new landing snippet and
-quickstart; older wheels do not provide `import abstract`.
+The `abstract.client(...)` factory has existed since 0.2.2. Version 0.3.0 moves the full SDK
+into `abstract`, including the lower-level clients and policy types. Publish that version before
+advertising the renamed advanced interfaces. `import atoms`, the 0.2 name, still resolves in 0.3
+with a `DeprecationWarning`: its top-level names only, `AtomsClient` being `abstract.RobotClient`.
 
 This is all a robot with its own stack needs. The `abstract` command and the robot station are
-`abstract-robots`, built on it, and `abstract-atoms` installs both (`apps/atoms`).
+in `abstract-atoms`, built on it (`apps/atoms`).
 
 ```python
-import atoms
+import abstract
 
-client = atoms.Client()  # the key: api_key=, else ABSTRACT_API_KEY, else `abstract login`'s file
+client = abstract.Client()  # the key: api_key=, else ABSTRACT_API_KEY, else `abstract login`'s file
 
-with client.connect("nvidia/dreamzero", "fold the towel") as policy:
+with client.connect("allenai/molmoact2", "fold the towel") as policy:
     frames = {"overhead": top_jpeg, "wrist_l": left_jpeg, "wrist_r": right_jpeg}
     while not done:
         state = {
@@ -58,15 +86,16 @@ with client.connect("nvidia/dreamzero", "fold the towel") as policy:
         }
         chunk = policy.predict(frames, state)
         # Row k is a pose for t + k * chunk.dt; your arm's inverse kinematics turns each into
-        # joint angles. chunk.elapsed_rows were already due when the answer arrived.
-        for left, right in zip(chunk.left[chunk.elapsed_rows :], chunk.right[chunk.elapsed_rows :]):
+        # joint angles. The arm held still while predict() ran, so every row runs; a loop that
+        # keeps the arm moving meanwhile skips the rows it ran, as the RobotClient loop below.
+        for left, right in zip(chunk.left, chunk.right):
             robot.command(left, right)
         # The next call sends policy.frames_needed JPEGs per camera, oldest first.
         frames = latest_frames(policy.frames_needed)
 # Leaving the block ends the episode now; the server would after 60 s idle.
 ```
 
-A stateful model (DreamZero) takes the video since its last observation: after the first call,
+A stateful model takes the video since its last observation: after the first call,
 send `policy.frames_needed` frames per camera.
 
 ### Native robot checkpoints
@@ -79,57 +108,63 @@ is enabled on the account. These native contracts are separate from the YAM exam
 | Model                             | Observation                                                                                                                                                                                                    | Returned commands                                                                                                                                      |
 | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `verne/v0.5`                      | The YAM example's poses and cameras, one frame per camera and then four; not trained on the YAM                                                                                                                | 18 pose rows per arm at 30 Hz                                                                                                                          |
+| `runway/praxis-1` | The YAM example's poses and cameras at 16:10, one frame per camera and then 21: one at the end of each row just run. Capture them yourself and call `policy.predict()`; `RobotClient`'s window also counts the pause between chunks. | 21 pose rows per arm at 15 Hz |
 | `xiaomi/xiaomi-robotics-1`        | RoboDojo ARX X5 world-frame poses, normalized grippers (0 closed, 1 open), and `left_joint_position` / `right_joint_position` with six measured radians each. Cameras retain `overhead`, `wrist_l`, `wrist_r`. | `chunk.left` / `chunk.right`: 30 end-effector targets at 25 Hz, in the same RoboDojo world frame.                                                      |
 | `black-forest-labs/flux-3-action` | DROID Franka `joint_position` (seven radians), `gripper_position` (one closed fraction: 0 open, 1 closed), and cameras `exterior_image_0_left`, `exterior_image_1_left`, `wrist_image_left`.                   | `chunk.joints`: 32 rows of seven absolute joint targets plus gripper at 15 Hz; `chunk.action_space == "joint_position"`. `left` and `right` are empty. |
 
 Use `chunk.row_count` for either command format. `elapsed_rows`, sync/async policies, retries
-and the `AtomsClient` observation window work with both. Policies sharing one observation
-window must use the same state and camera contract. The YAM station does not drive these robots.
+and the `RobotClient` observation window work with both. Policies sharing one observation
+window must use the same state and camera contract. The bimanual station does not drive these native contracts.
 
-### `atoms.AtomsClient`: Dream Labs' DreamClient on this API
+### `abstract.RobotClient`: Dream Labs' DreamClient on this API
 
-`atoms.AtomsClient` keeps that window for you and paces the requests, with the calls of Dream Labs'
+`abstract.RobotClient` keeps that window for you and paces the requests, with the calls of Dream Labs'
 `DreamClient` (Apache-2.0; see `NOTICE`): bind the key, choose the model, push every camera tick,
 pull a chunk when it says so.
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
 
-robot = atoms.AtomsClient()  # the key, as atoms.Client finds it
-robot.policy({"model": "nvidia/dreamzero"})
+robot = abstract.RobotClient()  # the key, as abstract.Client finds it
+robot.policy({"model": "allenai/molmoact2"})
 with robot, ThreadPoolExecutor(1) as worker:  # the request runs while the robot moves
     chunk, row, pending = None, 0, None
+    ran = ran_at_ask = 0  # rows the robot has run, and how many when the request went out
     while not done:
         frames = {"video.overhead": top, "video.wrist_l": left, "video.wrist_r": right}
         robot.set_observation(frames, {"prompt": "fold the towel", "state": read_state()})
         rows_left = len(chunk.left) - row if chunk else 0
         if pending is None and robot.refill_due(row, rows_left):
-            pending = worker.submit(robot.get_action)
+            pending, ran_at_ask = worker.submit(robot.get_action), ran
         if pending is not None and pending.done():
             chunk, pending = pending.result(), None
-            row = chunk.elapsed_rows
+            # Skip the rows the robot ran while this chunk was computed (at most those already
+            # due, chunk.elapsed_rows). A robot that held still meanwhile starts at row 0.
+            row = min(chunk.elapsed_rows, ran - ran_at_ask)
         if chunk and row < len(chunk.left):
             robot.command(chunk.left[row], chunk.right[row])
-            row += 1
+            row, ran = row + 1, ran + 1
         wait_for_next_tick()
 ```
 
 #### Several models on one robot
 
-DreamClient runs one model. `AtomsClient` runs as many as you open on the same camera ticks, each
-with its own episode, frames (DreamZero takes four per camera, MolmoAct2 one), pacing and timing.
+DreamClient runs one model. `RobotClient` runs as many as you open on the same camera ticks, each
+with its own episode, frames (a stateful model takes several per camera, MolmoAct2 one), pacing and timing.
 One drives the arms; the others answer the same observations, to compare them.
 
 ```python
-robot.policies({"dz": {"model": "nvidia/dreamzero"}, "molmo": {"model": "allenai/molmoact2"}})
+robot.policies(
+    {"molmo": {"model": "allenai/molmoact2"}, "pi": {"model": "physical-intelligence/pi0.5"}}
+)
 robot.set_observation(frames, observation)  # one tick, every model
 answers = robot.get_actions()  # every model at once: {name: Chunk, or the error it raised}
-drive = robot["dz"]  # one model: get_action(), refill_due(), last, mode, last_timing
+drive = robot["molmo"]  # one model: get_action(), refill_due(), last, mode, last_timing
 ```
 
-| DreamClient                                                                         | atoms.AtomsClient                                                                                                                   |
+| DreamClient                                                                         | abstract.RobotClient                                                                                                                   |
 | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `DreamClient(api_key)`                                                              | `AtomsClient(api_key)`, or `AtomsClient(client=...)`                                                                                |
+| `DreamClient(api_key)`                                                              | `RobotClient(api_key)`, or `RobotClient(client=...)`                                                                                |
 | `get_models()`                                                                      | `get_models()`: served models and your fine-tunes, with their rates                                                                 |
 | `policy({"checkpoint": ...})`                                                       | `policy({"model": ...})`; `execution_horizon`, `action_hz`, `sync_above_ms`, `timeout_ms` as in DreamClient                         |
 | `set_observation(frames, observation, timestamp=)`                                  | the same: `video.<camera>` frames, `prompt` and `state` (a dict or `state.<name>` keys)                                             |
@@ -137,13 +172,35 @@ drive = robot["dz"]  # one model: get_action(), refill_due(), last, mode, last_t
 | `reset_episode()`, `refill_due()`, `close()`                                        | the same                                                                                                                            |
 | `mode`, `execution_horizon`, `action_hz`, `last_timing`, `checkpoint`, `session_id` | the same, `model` for `checkpoint`                                                                                                  |
 | `obs_window`, `obs_fps`                                                             | none: each answer says how many frames the next observation carries                                                                 |
-| `DreamSlowNetworkWarning`                                                           | `atoms.SlowNetworkWarning`                                                                                                          |
+| `DreamSlowNetworkWarning`                                                           | `abstract.SlowNetworkWarning`                                                                                                          |
 | one model per client                                                                | `policies({name: config})`, `get_actions()`, `robot[name]`                                                                          |
 
-Not here yet: DreamClient's seam smoothing (`commanded`), datasets and fine-tuning. Embodiments,
-`ik` and Live View have no counterpart on this API.
+### Optional URDF FK and IK (0.3.0)
+
+The solver is not in this package: install `abstract-atoms[ik]` after release, or
+`uv pip install -e ./apps/atoms/client -e './apps/atoms[ik]'` from this checkout. Configure each physical arm's URDF, joint order, grasp point and frames:
+
+```python
+from abstract_robots.ik import RobotIK
+
+ik = RobotIK.from_file("robot.json")
+client = abstract.client(checkpoint="allenai/molmoact2", embodiment="yam", ik=ik)
+client.set_joint_observation(frames, measured_joints, grippers, prompt="fold the towel")
+chunk = client.get_action()
+# Measure again after inference; solving is local and commands no hardware. The arm held still
+# during this call; one that kept moving passes start= the rows it ran (at most elapsed_rows).
+joints = client.to_joints(chunk, current_measured_joints)
+```
+
+See [the configuration and driver guide](../robots/IK.md) for full examples, limits, geometry checks and
+validation scope. Different arm geometries/joint counts are supported locally. Model embodiment
+checks remain; correct IK does not prove policy transfer. The Python station uses the same solver
+through `--ik robot.json`, with `observe_joints()` / `command_joints()` drivers.
+
+DreamClient's seam smoothing (`commanded`) is not implemented. Dataset and fine-tuning commands
+and the station's Live View remain in `abstract-atoms`.
 
-`atoms.AsyncClient` is native asyncio with the same arguments, rules and calls
+`abstract.AsyncClient` is native asyncio with the same arguments, rules and calls
 (`await policy.predict(...)`). Cancelling a call cancels its request, but the server may already
 be running it, so the next `predict()` asks for that answer first, as after a lost connection.
 
@@ -159,10 +216,41 @@ import httpx2
 
 tls = ssl.create_default_context(cafile="lab-ca.pem")
 tls.load_cert_chain("robot.pem", "robot.key")
-client = atoms.Client(http_client=httpx2.Client(verify=tls, proxy="http://proxy.lab:3128"))
+client = abstract.Client(http_client=httpx2.Client(verify=tls, proxy="http://proxy.lab:3128"))
 ```
 
-`connect(model, task, scaling={"seed": 7})` (or `scaling` in an `AtomsClient` config) sends the
+### Transports
+
+`transport` chooses how the calls travel. `"http"` is the default and what everything above
+describes. `"quic"` sends the same calls to the same routes over HTTP/3, on one QUIC connection
+that every policy on the client shares; it is opt-in and needs the `quic` extra:
+
+```sh
+uv add 'abstract-client[quic]'
+```
+
+```python
+client = abstract.Client(transport="quic")  # or ABSTRACT_TRANSPORT=quic; every client takes it
+```
+
+The API sees the same request either way, so chunks are billed the same and a call that gets no
+answer is sent again under the same rules. What differs is the network's side:
+
+- QUIC needs outbound UDP to the API on port 443. Where a network blocks it, calls fail with
+  `APIConnectionError` or `APITimeoutError`; nothing switches to `"http"` on its own.
+- No proxy can carry it. On a machine set to use one (`HTTPS_PROXY`, `ALL_PROXY` or the system's)
+  the client raises `ConfigError` rather than go around the proxy, and `http_client=` cannot be
+  combined with it.
+- TLS is checked against certifi's CA bundle, not the operating system's trust store: a CA your
+  IT installed is not trusted, and there is no setting for a private CA or a client certificate.
+- A connection that hears nothing for 20 s is closed and the next call opens another. While a
+  call waits for its answer the client pings every 5 s, so a model's cold start does not end it.
+
+It runs aioquic's QUIC stack as it comes, with no tuning, and has not been measured against
+`"http"`: choose it to compare the two on your own network, not on a promise that it is faster.
+`client.transport` says which one a client uses.
+
+`connect(model, task, scaling={"seed": 7})` (or `scaling` in a `RobotClient` config) sends the
 API's `scaling` with every observation, so a seedable model replays its noise; the engine's reports
 (`scaling`, `cache`, `context`) come back in `chunk.raw`.
 
@@ -171,12 +259,16 @@ bytes and `observation_id`, so the server answers it from its record and never b
 Refusals the server marks retryable are sent again after its `Retry-After`, up to `max_retries`;
 `timeout` bounds a whole call, resends included, and `connect_timeout` opening a connection.
 
-Every error is an `atoms.AbstractError`. A refusal is an `atoms.APIStatusError` subclass named
+Every error is an `abstract.AbstractError`. A refusal is an `abstract.APIStatusError` subclass named
 for its status (`AuthenticationError`, `PaymentRequiredError`, `RateLimitError`, ...) with the
 server's `code`, `retryable`, `retry_after` and `request_id`; a refused or answered
 `get_action` also carries its reply's `trace_id`, which a replay keeps. `APIConnectionError` and
-`APITimeoutError` mean no answer came: the next `predict()` asks for it first. The `atoms`
+`APITimeoutError` mean no answer came: the next `predict()` asks for it first. The `abstract.client`
 logger reports resends; it never logs the key.
 
-Python 3.10 or later; its one dependency is `httpx2`. Tests: `pytest apps/atoms` (the contract
+Python 3.10 or later; its one dependency is `httpx2` (`aioquic` with the `quic` extra). Tests: `pytest apps/atoms` (the contract
 tests need Bun and the engine's packages: `uv run --project apps/engine pytest apps/atoms`).
+
+Version 0.3 replaces `import atoms` with `import abstract`; the buffered harness is
+`abstract.RobotClient` (previously `AtomsClient`). `abstract.client(...)` is the recommended
+entry point. The Python station uses this same implementation; there is no separate YAM runner.

abstract_client-0.2.2/PKG-INFO → abstract_client-0.3.0/README.md

@@ -1,15 +1,4 @@
-Metadata-Version: 2.5
-Name: abstract-client
-Version: 0.2.2
-Summary: Abstract's robot API from Python: action chunks from served robot models, sync and asyncio.
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Requires-Python: >=3.10
-Requires-Dist: httpx2<3,>=2.12
-Description-Content-Type: text/markdown
-
-# abstract-client
+# abstract.client
 
 Abstract's robot API from Python. A `Client` holds your key and its connections and is safe to
 share between threads; each `Policy` is one episode of one served robot model doing one task, one
@@ -19,12 +8,12 @@ action chunk per `predict()`.
 uv add abstract-client
 ```
 
-### Quickstart (0.2.2)
+### Quickstart (0.3.0)
 
 ```python
 import abstract
 
-checkpoint = "nvidia/dreamzero"
+checkpoint = "allenai/molmoact2"
 embodiment = "yam"
 client = abstract.client(ABSTRACT_API_KEY, checkpoint, embodiment)
 
@@ -39,24 +28,27 @@ holds `prompt` (the task) and `state` (measured alongside the frames). The YAM c
 state fields are shown below. The returned `Chunk` contains targets, never hardware motion;
 reset ends the model's episode without repositioning the robot.
 
-`abstract.client()` checks the account's unmetered model catalogue before configuring an
-`AtomsClient`. The checkpoint must be available and its `robot` must match `embodiment`.
-It does not adapt models to other robots. Omit `api_key` to use the environment or saved
+`abstract.client()` checks the account's unmetered model catalogue before configuring a
+`RobotClient`. The checkpoint must be available and its `robot` must match `embodiment`.
+An optional URDF layer converts poses to another arm's joint geometry; it does not establish
+policy transfer. Omit `api_key` to use the environment or saved
 CLI credentials; connection options such as `base_url` and `timeout` pass through to the
-existing client. Context managers and the existing `atoms` interface remain supported.
+existing client. Context managers and the lower-level `abstract.Client` interface remain supported.
 
-Release order: publish the matching 0.2.2 SDK before deploying the new landing snippet and
-quickstart; older wheels do not provide `import abstract`.
+The `abstract.client(...)` factory has existed since 0.2.2. Version 0.3.0 moves the full SDK
+into `abstract`, including the lower-level clients and policy types. Publish that version before
+advertising the renamed advanced interfaces. `import atoms`, the 0.2 name, still resolves in 0.3
+with a `DeprecationWarning`: its top-level names only, `AtomsClient` being `abstract.RobotClient`.
 
 This is all a robot with its own stack needs. The `abstract` command and the robot station are
-`abstract-robots`, built on it, and `abstract-atoms` installs both (`apps/atoms`).
+in `abstract-atoms`, built on it (`apps/atoms`).
 
 ```python
-import atoms
+import abstract
 
-client = atoms.Client()  # the key: api_key=, else ABSTRACT_API_KEY, else `abstract login`'s file
+client = abstract.Client()  # the key: api_key=, else ABSTRACT_API_KEY, else `abstract login`'s file
 
-with client.connect("nvidia/dreamzero", "fold the towel") as policy:
+with client.connect("allenai/molmoact2", "fold the towel") as policy:
     frames = {"overhead": top_jpeg, "wrist_l": left_jpeg, "wrist_r": right_jpeg}
     while not done:
         state = {
@@ -69,15 +61,16 @@ with client.connect("nvidia/dreamzero", "fold the towel") as policy:
         }
         chunk = policy.predict(frames, state)
         # Row k is a pose for t + k * chunk.dt; your arm's inverse kinematics turns each into
-        # joint angles. chunk.elapsed_rows were already due when the answer arrived.
-        for left, right in zip(chunk.left[chunk.elapsed_rows :], chunk.right[chunk.elapsed_rows :]):
+        # joint angles. The arm held still while predict() ran, so every row runs; a loop that
+        # keeps the arm moving meanwhile skips the rows it ran, as the RobotClient loop below.
+        for left, right in zip(chunk.left, chunk.right):
             robot.command(left, right)
         # The next call sends policy.frames_needed JPEGs per camera, oldest first.
         frames = latest_frames(policy.frames_needed)
 # Leaving the block ends the episode now; the server would after 60 s idle.
 ```
 
-A stateful model (DreamZero) takes the video since its last observation: after the first call,
+A stateful model takes the video since its last observation: after the first call,
 send `policy.frames_needed` frames per camera.
 
 ### Native robot checkpoints
@@ -90,57 +83,63 @@ is enabled on the account. These native contracts are separate from the YAM exam
 | Model                             | Observation                                                                                                                                                                                                    | Returned commands                                                                                                                                      |
 | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `verne/v0.5`                      | The YAM example's poses and cameras, one frame per camera and then four; not trained on the YAM                                                                                                                | 18 pose rows per arm at 30 Hz                                                                                                                          |
+| `runway/praxis-1` | The YAM example's poses and cameras at 16:10, one frame per camera and then 21: one at the end of each row just run. Capture them yourself and call `policy.predict()`; `RobotClient`'s window also counts the pause between chunks. | 21 pose rows per arm at 15 Hz |
 | `xiaomi/xiaomi-robotics-1`        | RoboDojo ARX X5 world-frame poses, normalized grippers (0 closed, 1 open), and `left_joint_position` / `right_joint_position` with six measured radians each. Cameras retain `overhead`, `wrist_l`, `wrist_r`. | `chunk.left` / `chunk.right`: 30 end-effector targets at 25 Hz, in the same RoboDojo world frame.                                                      |
 | `black-forest-labs/flux-3-action` | DROID Franka `joint_position` (seven radians), `gripper_position` (one closed fraction: 0 open, 1 closed), and cameras `exterior_image_0_left`, `exterior_image_1_left`, `wrist_image_left`.                   | `chunk.joints`: 32 rows of seven absolute joint targets plus gripper at 15 Hz; `chunk.action_space == "joint_position"`. `left` and `right` are empty. |
 
 Use `chunk.row_count` for either command format. `elapsed_rows`, sync/async policies, retries
-and the `AtomsClient` observation window work with both. Policies sharing one observation
-window must use the same state and camera contract. The YAM station does not drive these robots.
+and the `RobotClient` observation window work with both. Policies sharing one observation
+window must use the same state and camera contract. The bimanual station does not drive these native contracts.
 
-### `atoms.AtomsClient`: Dream Labs' DreamClient on this API
+### `abstract.RobotClient`: Dream Labs' DreamClient on this API
 
-`atoms.AtomsClient` keeps that window for you and paces the requests, with the calls of Dream Labs'
+`abstract.RobotClient` keeps that window for you and paces the requests, with the calls of Dream Labs'
 `DreamClient` (Apache-2.0; see `NOTICE`): bind the key, choose the model, push every camera tick,
 pull a chunk when it says so.
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
 
-robot = atoms.AtomsClient()  # the key, as atoms.Client finds it
-robot.policy({"model": "nvidia/dreamzero"})
+robot = abstract.RobotClient()  # the key, as abstract.Client finds it
+robot.policy({"model": "allenai/molmoact2"})
 with robot, ThreadPoolExecutor(1) as worker:  # the request runs while the robot moves
     chunk, row, pending = None, 0, None
+    ran = ran_at_ask = 0  # rows the robot has run, and how many when the request went out
     while not done:
         frames = {"video.overhead": top, "video.wrist_l": left, "video.wrist_r": right}
         robot.set_observation(frames, {"prompt": "fold the towel", "state": read_state()})
         rows_left = len(chunk.left) - row if chunk else 0
         if pending is None and robot.refill_due(row, rows_left):
-            pending = worker.submit(robot.get_action)
+            pending, ran_at_ask = worker.submit(robot.get_action), ran
         if pending is not None and pending.done():
             chunk, pending = pending.result(), None
-            row = chunk.elapsed_rows
+            # Skip the rows the robot ran while this chunk was computed (at most those already
+            # due, chunk.elapsed_rows). A robot that held still meanwhile starts at row 0.
+            row = min(chunk.elapsed_rows, ran - ran_at_ask)
         if chunk and row < len(chunk.left):
             robot.command(chunk.left[row], chunk.right[row])
-            row += 1
+            row, ran = row + 1, ran + 1
         wait_for_next_tick()
 ```
 
 #### Several models on one robot
 
-DreamClient runs one model. `AtomsClient` runs as many as you open on the same camera ticks, each
-with its own episode, frames (DreamZero takes four per camera, MolmoAct2 one), pacing and timing.
+DreamClient runs one model. `RobotClient` runs as many as you open on the same camera ticks, each
+with its own episode, frames (a stateful model takes several per camera, MolmoAct2 one), pacing and timing.
 One drives the arms; the others answer the same observations, to compare them.
 
 ```python
-robot.policies({"dz": {"model": "nvidia/dreamzero"}, "molmo": {"model": "allenai/molmoact2"}})
+robot.policies(
+    {"molmo": {"model": "allenai/molmoact2"}, "pi": {"model": "physical-intelligence/pi0.5"}}
+)
 robot.set_observation(frames, observation)  # one tick, every model
 answers = robot.get_actions()  # every model at once: {name: Chunk, or the error it raised}
-drive = robot["dz"]  # one model: get_action(), refill_due(), last, mode, last_timing
+drive = robot["molmo"]  # one model: get_action(), refill_due(), last, mode, last_timing
 ```
 
-| DreamClient                                                                         | atoms.AtomsClient                                                                                                                   |
+| DreamClient                                                                         | abstract.RobotClient                                                                                                                   |
 | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `DreamClient(api_key)`                                                              | `AtomsClient(api_key)`, or `AtomsClient(client=...)`                                                                                |
+| `DreamClient(api_key)`                                                              | `RobotClient(api_key)`, or `RobotClient(client=...)`                                                                                |
 | `get_models()`                                                                      | `get_models()`: served models and your fine-tunes, with their rates                                                                 |
 | `policy({"checkpoint": ...})`                                                       | `policy({"model": ...})`; `execution_horizon`, `action_hz`, `sync_above_ms`, `timeout_ms` as in DreamClient                         |
 | `set_observation(frames, observation, timestamp=)`                                  | the same: `video.<camera>` frames, `prompt` and `state` (a dict or `state.<name>` keys)                                             |
@@ -148,13 +147,35 @@ drive = robot["dz"]  # one model: get_action(), refill_due(), last, mode, last_t
 | `reset_episode()`, `refill_due()`, `close()`                                        | the same                                                                                                                            |
 | `mode`, `execution_horizon`, `action_hz`, `last_timing`, `checkpoint`, `session_id` | the same, `model` for `checkpoint`                                                                                                  |
 | `obs_window`, `obs_fps`                                                             | none: each answer says how many frames the next observation carries                                                                 |
-| `DreamSlowNetworkWarning`                                                           | `atoms.SlowNetworkWarning`                                                                                                          |
+| `DreamSlowNetworkWarning`                                                           | `abstract.SlowNetworkWarning`                                                                                                          |
 | one model per client                                                                | `policies({name: config})`, `get_actions()`, `robot[name]`                                                                          |
 
-Not here yet: DreamClient's seam smoothing (`commanded`), datasets and fine-tuning. Embodiments,
-`ik` and Live View have no counterpart on this API.
+### Optional URDF FK and IK (0.3.0)
+
+The solver is not in this package: install `abstract-atoms[ik]` after release, or
+`uv pip install -e ./apps/atoms/client -e './apps/atoms[ik]'` from this checkout. Configure each physical arm's URDF, joint order, grasp point and frames:
+
+```python
+from abstract_robots.ik import RobotIK
+
+ik = RobotIK.from_file("robot.json")
+client = abstract.client(checkpoint="allenai/molmoact2", embodiment="yam", ik=ik)
+client.set_joint_observation(frames, measured_joints, grippers, prompt="fold the towel")
+chunk = client.get_action()
+# Measure again after inference; solving is local and commands no hardware. The arm held still
+# during this call; one that kept moving passes start= the rows it ran (at most elapsed_rows).
+joints = client.to_joints(chunk, current_measured_joints)
+```
+
+See [the configuration and driver guide](../robots/IK.md) for full examples, limits, geometry checks and
+validation scope. Different arm geometries/joint counts are supported locally. Model embodiment
+checks remain; correct IK does not prove policy transfer. The Python station uses the same solver
+through `--ik robot.json`, with `observe_joints()` / `command_joints()` drivers.
+
+DreamClient's seam smoothing (`commanded`) is not implemented. Dataset and fine-tuning commands
+and the station's Live View remain in `abstract-atoms`.
 
-`atoms.AsyncClient` is native asyncio with the same arguments, rules and calls
+`abstract.AsyncClient` is native asyncio with the same arguments, rules and calls
 (`await policy.predict(...)`). Cancelling a call cancels its request, but the server may already
 be running it, so the next `predict()` asks for that answer first, as after a lost connection.
 
@@ -170,10 +191,41 @@ import httpx2
 
 tls = ssl.create_default_context(cafile="lab-ca.pem")
 tls.load_cert_chain("robot.pem", "robot.key")
-client = atoms.Client(http_client=httpx2.Client(verify=tls, proxy="http://proxy.lab:3128"))
+client = abstract.Client(http_client=httpx2.Client(verify=tls, proxy="http://proxy.lab:3128"))
 ```
 
-`connect(model, task, scaling={"seed": 7})` (or `scaling` in an `AtomsClient` config) sends the
+### Transports
+
+`transport` chooses how the calls travel. `"http"` is the default and what everything above
+describes. `"quic"` sends the same calls to the same routes over HTTP/3, on one QUIC connection
+that every policy on the client shares; it is opt-in and needs the `quic` extra:
+
+```sh
+uv add 'abstract-client[quic]'
+```
+
+```python
+client = abstract.Client(transport="quic")  # or ABSTRACT_TRANSPORT=quic; every client takes it
+```
+
+The API sees the same request either way, so chunks are billed the same and a call that gets no
+answer is sent again under the same rules. What differs is the network's side:
+
+- QUIC needs outbound UDP to the API on port 443. Where a network blocks it, calls fail with
+  `APIConnectionError` or `APITimeoutError`; nothing switches to `"http"` on its own.
+- No proxy can carry it. On a machine set to use one (`HTTPS_PROXY`, `ALL_PROXY` or the system's)
+  the client raises `ConfigError` rather than go around the proxy, and `http_client=` cannot be
+  combined with it.
+- TLS is checked against certifi's CA bundle, not the operating system's trust store: a CA your
+  IT installed is not trusted, and there is no setting for a private CA or a client certificate.
+- A connection that hears nothing for 20 s is closed and the next call opens another. While a
+  call waits for its answer the client pings every 5 s, so a model's cold start does not end it.
+
+It runs aioquic's QUIC stack as it comes, with no tuning, and has not been measured against
+`"http"`: choose it to compare the two on your own network, not on a promise that it is faster.
+`client.transport` says which one a client uses.
+
+`connect(model, task, scaling={"seed": 7})` (or `scaling` in a `RobotClient` config) sends the
 API's `scaling` with every observation, so a seedable model replays its noise; the engine's reports
 (`scaling`, `cache`, `context`) come back in `chunk.raw`.
 
@@ -182,12 +234,16 @@ bytes and `observation_id`, so the server answers it from its record and never b
 Refusals the server marks retryable are sent again after its `Retry-After`, up to `max_retries`;
 `timeout` bounds a whole call, resends included, and `connect_timeout` opening a connection.
 
-Every error is an `atoms.AbstractError`. A refusal is an `atoms.APIStatusError` subclass named
+Every error is an `abstract.AbstractError`. A refusal is an `abstract.APIStatusError` subclass named
 for its status (`AuthenticationError`, `PaymentRequiredError`, `RateLimitError`, ...) with the
 server's `code`, `retryable`, `retry_after` and `request_id`; a refused or answered
 `get_action` also carries its reply's `trace_id`, which a replay keeps. `APIConnectionError` and
-`APITimeoutError` mean no answer came: the next `predict()` asks for it first. The `atoms`
+`APITimeoutError` mean no answer came: the next `predict()` asks for it first. The `abstract.client`
 logger reports resends; it never logs the key.
 
-Python 3.10 or later; its one dependency is `httpx2`. Tests: `pytest apps/atoms` (the contract
+Python 3.10 or later; its one dependency is `httpx2` (`aioquic` with the `quic` extra). Tests: `pytest apps/atoms` (the contract
 tests need Bun and the engine's packages: `uv run --project apps/engine pytest apps/atoms`).
+
+Version 0.3 replaces `import atoms` with `import abstract`; the buffered harness is
+`abstract.RobotClient` (previously `AtomsClient`). `abstract.client(...)` is the recommended
+entry point. The Python station uses this same implementation; there is no separate YAM runner.

abstract_client-0.3.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "abstract-client"
+# The one place this wheel's version is written: `abstract.__version__` reads it from the
+# installed wheel. Raise it here to release this wheel; abstract-atoms accepts any 0.3.
+version = "0.3.0"
+description = "Abstract's robot API from Python: action chunks from served robot models, sync and asyncio."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+# Pydantic's maintained HTTPX; 2.15 and later need Python 3.11, so 3.10 resolves to 2.14.
+dependencies = ["httpx2>=2.12,<3"]
+
+[project.optional-dependencies]
+# `transport="quic"`: the same calls over HTTP/3. aioquic 1.4 and later need Python 3.11, so 3.10
+# resolves to 1.3.
+quic = ["aioquic>=1.3,<2"]
+
+[project.urls]
+Homepage = "https://abstract.inc"
+Documentation = "https://docs.abstract.inc"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/abstract", "src/atoms"]  # atoms: the 0.2 import name, deprecated