menlo-sdk 0.1.0rc2__tar.gz

menlo_sdk-0.1.0rc2/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: lint + types + tests (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Sync (locked)
+        run: uv sync --python ${{ matrix.python }} --locked --all-groups
+
+      - name: Ruff (lint)
+        run: uv run ruff check .
+
+      - name: Ruff (format)
+        run: uv run ruff format --check .
+
+      - name: No merge-conflict markers (they pass ruff, mypy and pytest inside a docstring)
+        run: '! git grep -nE "^(<{7}|>{7})( |$)" -- .'
+
+      - name: Mypy (strict)
+        run: uv run mypy
+
+      - name: Unit tests
+        run: uv run pytest -m "not integration and not live"
+
+      - name: Package builds and ships its bindings and type information
+        run: |
+          uv build && ls -l dist/
+          python -m zipfile -l dist/*.whl | grep -E 'menlo/py.typed'
+          unzip -p dist/*.whl '*/METADATA' | grep -E '^Requires-Dist: asimov-protocol'
+
+  # The real edge connector, in-process: proves the wire, not just the fake. Clones
+  # asimov-edge at the commit the SDK is developed against; skipped only when the
+  # token is missing, and then LOUDLY.
+  integration:
+    name: real UdpConnector (asimov-edge)
+    runs-on: ubuntu-latest
+    needs: check
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      # asimov-edge is an internal repo: the workflow's own token cannot read it. Without
+      # ASIMOV_REPOS_TOKEN this job warns and skips instead of failing the PR — the unit
+      # suite already drives the wire against a fake edge; this job is the extra proof.
+      - name: Token check
+        id: tok
+        env:
+          TOKEN: ${{ secrets.ASIMOV_REPOS_TOKEN }}
+        run: |
+          if [ -n "$TOKEN" ]; then
+            git config --global url."https://x-access-token:${TOKEN}@github.com/menloresearch/".insteadOf "https://github.com/menloresearch/"
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::warning::ASIMOV_REPOS_TOKEN is not granted to this repository; skipping the real-edge integration job"
+            echo "present=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Check out asimov-edge at the pinned commit
+        if: steps.tok.outputs.present == 'true'
+        run: |
+          EDGE_REF="$(sed -nE 's/^ASIMOV_EDGE_REF=(.*)$/\1/p' tests/integration/edge.pin)"
+          git clone --depth 1 https://github.com/menloresearch/asimov-edge.git /tmp/asimov-edge
+          git -C /tmp/asimov-edge fetch --depth 1 origin "$EDGE_REF"
+          git -C /tmp/asimov-edge checkout "$EDGE_REF"
+      - name: Drop the git credential before running anything from the PR
+        if: steps.tok.outputs.present == 'true'
+        run: git config --global --unset-all url."https://x-access-token:${{ secrets.ASIMOV_REPOS_TOKEN }}@github.com/menloresearch/".insteadOf
+      - name: Sync + install the edge into the same environment
+        if: steps.tok.outputs.present == 'true'
+        run: |
+          uv sync --locked --all-groups
+          uv pip install /tmp/asimov-edge
+      - name: Integration tests
+        if: steps.tok.outputs.present == 'true'
+        env:
+          ASIMOV_EDGE_SRC: /tmp/asimov-edge/src
+        run: uv run pytest -m integration

menlo_sdk-0.1.0rc2/.github/workflows/publish.yml

@@ -0,0 +1,131 @@
+name: Publish to PyPI
+
+# Publishes the SDK on every v* tag.
+#
+# A build job proves the tag equals the package version
+# and produces sdist + wheel; a separate publish job only sees the built
+# artifacts and uploads them with PyPI trusted publishing (OIDC, no long-lived
+# token) inside the `pypi` GitHub environment, so a required reviewer can gate
+# it. workflow_dispatch builds without publishing (a packaging dry run).
+#
+# The version is dynamic (hatch reads src/menlo/__init__.py), so name and
+# version are taken from the built wheel's METADATA, which is what PyPI sees.
+#
+# Setup and the tag procedure: RELEASING.md.
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    outputs:
+      name: ${{ steps.meta.outputs.name }}
+      version: ${{ steps.meta.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          fetch-depth: 0 # the ancestry check below needs real history, not a shallow tip
+
+      # A release is a tag on main. A tag pushed on a feature branch (or on a commit
+      # that never merged) must not publish; the tag ruleset and the pypi environment
+      # gate WHO may release, this gates WHAT. Annotated tags are peeled to the commit.
+      - name: Verify the tag is on main
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          # No fetch here: the checkout above (fetch-depth 0, no persisted credentials)
+          # already brought every branch, and a fetch would need a token it does not have.
+          tag_commit="$(git rev-parse "${TAG}^{commit}")"
+          if ! git merge-base --is-ancestor "$tag_commit" origin/main; then
+            echo "::error::tag $TAG ($tag_commit) is not on main; releases are tagged on main only"
+            exit 1
+          fi
+          echo "tag $TAG is on main ($tag_commit)"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          enable-cache: false
+
+      - name: Build sdist and wheel
+        run: uv build --out-dir dist
+
+      - name: Read name and version from the wheel
+        id: meta
+        run: |
+          python - <<'PY' >> "$GITHUB_OUTPUT"
+          import glob, zipfile
+          from email.parser import HeaderParser
+          (whl,) = glob.glob("dist/*.whl")
+          z = zipfile.ZipFile(whl)
+          (meta,) = [n for n in z.namelist() if n.endswith(".dist-info/METADATA")]
+          h = HeaderParser().parsestr(z.read(meta).decode())
+          print(f"name={h['Name']}")
+          print(f"version={h['Version']}")
+          PY
+          cat "$GITHUB_OUTPUT"
+
+      # Tags are the releases; a tag that does not match what the wheel says
+      # must die here, not on PyPI.
+      - name: Verify tag matches package version
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          REF: ${{ github.ref }}
+          PKG_VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          tag_version="${REF#refs/tags/v}"
+          if [ "$tag_version" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($tag_version) does not match __version__ in src/menlo/__init__.py ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Tag and package version match: $PKG_VERSION"
+
+      # The wheel must ship the typing marker and the licence, and declare the
+      # protocol dependency — the same contract ci.yml checks.
+      - name: Check distributions
+        run: |
+          uvx twine check dist/*
+          python -m zipfile -l dist/*.whl | grep -E 'menlo/py.typed|licenses/LICENSE'
+          unzip -p dist/*.whl '*/METADATA' | grep -E '^Requires-Dist: asimov-protocol'
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: sdk-dist
+          path: dist/
+          retention-days: 1
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ needs.build.outputs.name }}
+    permissions:
+      id-token: write # mandatory for trusted publishing
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: sdk-dist
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 (twine 7: knows core metadata 2.5)

menlo_sdk-0.1.0rc2/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

menlo_sdk-0.1.0rc2/.python-version

@@ -0,0 +1 @@
+3.12

menlo_sdk-0.1.0rc2/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md — how to work in menlo-sdk
+
+Read this before changing anything. It is short on purpose.
+
+## What this is
+
+A Python SDK that drives an Asimov robot **through its edge**. It is a client of the
+edge's arbiter and safety layer, never a bypass. The import is `menlo`, one subpackage per
+robot: everything that speaks the Asimov wire lives in `menlo.asimov`; the top level holds
+`__version__` and the `menlo` console script. One `Robot`; transports implement
+`transport/base.py`. Nothing in `robot.py` may know which wire it is on.
+
+## Rules
+
+- **Verbs are the wire's verbs.** `set_velocity`, `stand`, `damp`, `stop`, `trajectory` —
+  the names the edge, the protocol and the robot's other controllers already use. Do not
+  invent synonyms.
+- **No synchronous refusal.** A command returns a `Sent`; the verdict arrives as an
+  `Outcome`. `Unknown` is never success and never refusal.
+- **State is the truth about effect.** Waits read `robot.state`, never infer from what was
+  sent. Every wait refuses to succeed on a stale stream, and a fault is reported before a
+  predicate is evaluated.
+- **Caller bugs are builtins** (`ValueError`, `KeyError`, `RuntimeError`); robot and link
+  errors subclass `MenloError` and end in `Error`.
+- **Nothing is guessed.** A field the robot does not report is `None`. A capability the
+  transport does not carry raises `UnsupportedError`. A joint table carries its provenance
+  (`robots.py`). A protocol version mismatch is `ProtocolMismatchError`, not a warning.
+- **Describe what the code does.** No roadmap, no "yet", no review history in this repo.
+  Behaviour that depends on the edge or firmware is stated as the fact it is.
+- **Tests fail without the fix.** Every behavioural change ships a test that goes red when
+  the change is reverted. The fake edge in `tests/conftest.py` speaks the real wire; if you
+  change the wire, update the fake AND run `make integration` against the real connector.
+- **Bindings are a dependency.** `asimov-protocol>=1.2.1rc1,<2` from PyPI; `menlo.asimov._proto`
+  imports it lazily. Never copy generated `_pb2` files into this repo.
+
+## Dependencies
+
+Runtime core: `protobuf` only — `pip install menlo-sdk` with no extra must drive a robot
+(the UDP lane). The media lane adds one extra, `[livekit]`, and every `livekit` import in
+the SDK is lazy and lives in `transport/_livekit_client.py`; nothing else may import it,
+and `robot.connect("udp")` must never reach it. Optional at call time, never at import time:
+numpy, Pillow and OpenCV are named in an error, never depended on.
+
+Dev: ruff, mypy (strict), pytest. Simulator for live tests:
+`menlo-studio up --container --sdk`. A LiveKit server for `make livekit`:
+`livekit-server --dev`.

menlo_sdk-0.1.0rc2/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to menlo-sdk. Pre-1.0: minor versions may change the API.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## 0.1.0rc2 — 2026-09-23
+
+### Changed
+- `asimov-protocol` is a declared dependency (`>=1.2.1rc1,<2`, from PyPI) instead of a tree
+  vendored into the wheel. One installed copy of the bindings per process; the `_vendor/`
+  directory, `scripts/vendor_protocol.sh`, `make vendor-protocol` / `check-vendor` and the
+  vendored-bindings CI job are gone.
+- The distribution is `menlo-sdk` (repository `menloresearch/menlo-sdk`), published to PyPI on
+  `v*` tags. The import is `menlo`, one subpackage per robot: the Asimov biped is
+  `menlo.asimov` (`from menlo.asimov import Robot, Mode`). The console script is `menlo`
+  (`menlo login`), the store is `~/.menlo/robots.toml` (`$MENLO_HOME`), the environment
+  variables are `MENLO_MANAGER_URL`, `MENLO_CREDENTIAL`, `MENLO_ROBOT`, `MENLO_PERSIST`, and
+  the error base class is `MenloError`. Between releases `__version__` carries the next
+  version with a `.dev0` suffix; see `RELEASING.md`.
+
+### Fixed
+- A velocity held by `set_velocity` is released when the robot itself ends the drive: a
+  fault-DAMP (critical alert while DAMPed) drops the latch so the keepalive stops re-sending
+  it, and a firmware restart (sequence counter reset) drops it and fences off a running
+  `goto` / trajectory re-send. Nothing is sent in its place; a `MOVE` at zero would ask a
+  DAMPed or booting robot to change mode.
+- `close()` from inside a state callback on the `livekit` lane no longer stalls 5 s on the
+  client's own event loop and then drops the queued zero-velocity packet and the room
+  leave; the client now leaves asynchronously and stops its loop once that is done.
+- `connect(require_state=False)`: state that arrives while the transport is still opening
+  (a LiveKit media wait) now goes through the late handshake instead of being stored raw,
+  so a protocol mismatch is raised on read rather than returning a frozen sample.
+- `connect(persist=True)`: a store that cannot be written (read-only or full `$MENLO_HOME`,
+  a name that belongs to another manager) closes the session it just opened before the
+  error propagates, instead of leaving the keepalive and the transport running.
+- `RobotStore.put` refuses to replace an entry with one for a different manager unless the
+  caller chose the name (`menlo login --name`, `persist(name=)`): a manager answering
+  another robot's room can no longer take over that robot's saved URL and credential.
+- A DEL byte (U+007F) in a room or robot name no longer produces a `robots.toml` that
+  `tomllib` rejects.
+
+### Added
+- Zero-config connect: `Robot()` with no config resolves one from `MENLO_MANAGER_URL` +
+  `MENLO_CREDENTIAL`, else from `~/.menlo/robots.toml` (`$MENLO_HOME`; `MENLO_ROBOT`
+  picks a named entry), else raises `ConnectError` naming both; `connect()` with no mode
+  takes the config's one lane. `menlo.asimov.store`: `RobotStore`, `StoredRobot`; the file is
+  0600 in a 0700 directory. `connect(persist=True)` / `MENLO_PERSIST=1` save a working URL
+  and credential after a successful connect, keyed by the serial in the robot's room.
+- The `menlo` console script: `menlo login <manager-url> [--credential]` validates a
+  credential by minting a token exactly as `connect()` does, then saves it; `menlo robots`,
+  `menlo use <name>`, `menlo logout <name>`.
+- `connect(require_state=False)`: the media lane without waiting for the firmware.
+  `robot.state`, `robot.info` and the motion verbs raise `NotConnectedError` until the robot
+  reports, then the handshake completes on its own; a late protocol mismatch is raised
+  where it is read.
+- `set_velocity(..., duration=, wait=True)` blocks until the hold has ended and its zero
+  has gone out (or another verb superseded it); `close()` during a waited hold raises
+  `NotConnectedError`. `close()` documents that it cuts an unexpired hold short.
+- `State.yaw`; `Frame.to_jpeg(quality=85) -> bytes` (Pillow, named in the `ImportError`
+  when absent; JPEG frames pass through).
+- `ManagerConfig`: the URL needs neither scheme nor port (`192.168.22.32`, `http://host`,
+  `http://host:8080`); a loopback LiveKit URL minted by the manager (`ws://localhost:7880`,
+  the robot's own view) is rewritten to the manager's host; a session with no `label` gets
+  `<host>-<6 random hex>` so two sessions on one credential never share an identity.
+  `ManagerConfig.host`, `menlo.asimov.connection.default_label()`,
+  `ConnectionConfig.from_environment()`, `ConnectionConfig.only_mode()`;
+  `LiveKitTransport.room` / `HybridTransport.room`.
+- `docs/SKILL.md`: the agent-facing reference for writing a script against the SDK.
+- `ConnectionConfig(udp=UdpConfig(...), livekit=LiveKitConfig(...) | ManagerConfig(...))`
+  describes a robot's lanes, one typed class each; `Robot(cfg)` binds without touching the
+  network; `robot.connect("udp" | "hybrid" | "livekit", timeout=, media_timeout=,
+  connect_timeout=)` attaches and returns the robot; `close()` then `connect()` again switches
+  lanes on the same `Robot`. `cfg.available_modes()` says what a config can reach; a mode
+  the config cannot carry is a `ConnectError` naming the missing slot, before any I/O.
+- `ManagerConfig(url, credential, label=)`: the SDK asks the robot's manager
+  (`POST /api/livekit/token`) for the LiveKit URL, the room and a fresh join token on every
+  connect, so a user or agent never holds a LiveKit token. `LiveKitConfig(url, room, token)`
+  is for people running their own SFU.
+- The UDP lane: `UdpTransport` (`RobotCommand` → udp/8850, `RobotState` ← udp/8851);
+  `Robot(transport)` + `open()` for any `Transport`.
+- Verbs `set_velocity(vx, vy, vyaw, duration=)`, `stop()`, `stand()`, `damp()`,
+  `trajectory(positions, kp=, kd=)`, `goto(positions, duration=, hz=, wait=)`; each returns a
+  `Sent` with the encoded command, the clamp flag and an outcome handle.
+- Outcomes `Applied | Refused(reason: Refusal) | Unknown`; `Sent.wait_outcome()`,
+  `Sent.require()`. The UDP lane carries no verdicts; every outcome there is `Unknown`.
+- Typed `State`: mode, joints by firmware name, gravity, gyro, quaternion and euler angles,
+  alerts with names and timestamps, battery (`Battery`, `BatteryProtection`), `faulted`,
+  `age_s`; `RobotInfo` with `capabilities`; `robot.has()` / `robot.require()`.
+- Waits `wait_for(Mode)`, `wait_until(pred, timeout=, stale_after=)` with typed exits
+  `WaitTimeoutError`, `StateStaleError`, `RobotFaultedError`, `CommandRefusedError`.
+- Media API `robot.camera`, `robot.microphone`, `robot.speaker` (`Frame`, `AudioChunk`)
+  through the `Transport` seam; `UnsupportedError` on a transport that does not carry them.
+- Two more lanes, both first-class: `"hybrid"` (UDP control + LiveKit media) and
+  `"livekit"` (commands and
+  state as bare `RobotCommand`/`RobotState`: reliable data packets on the `commands` topic in,
+  frames of a data track named `state` out (ordered; `State.edge_timestamp_us` is the frame's
+  `user_timestamp`, the edge's receive clock) —
+  the same protobufs the UDP lane sends, no envelope, no type tag). `HybridTransport` and
+  `LiveKitTransport` underneath; `robot.py` does not know which wire it is on.
+- LiveKit is an EXTRA (`pip install "menlo-sdk[livekit]"`): the core still depends on
+  protobuf alone, every `livekit` import is lazy inside `transport/_livekit_client.py`, and
+  `connect("udp")` never reaches it.
+- `Camera.photo(timeout=)` returns ONE fresh `Frame`; `Camera.capture_clip(seconds,
+  audio=True)` returns a `Clip` with `save_wav()` (stdlib `wave`), `frames_as_numpy()`,
+  `save_frames()` (Pillow) and `save_mp4()` (OpenCV) — the last three raise `ImportError`
+  naming the package rather than adding a dependency. LiveKit video is converted from I420
+  to `rgb8`, so `Frame.to_numpy()` works.
+- `Transport.silence_hint`: the transport, not `Robot`, says what to check when a connect
+  hears nothing on its wire.
+- No `identity` parameter on the LiveKit lanes: a participant's identity is a claim inside
+  the access token and the server ignores what a client says about it, so the SDK reads it
+  back (`transport.identity`, and `endpoint` reads `room@url as <identity>`) instead of
+  accepting an argument it could not honour.
+- Callbacks `on_state`, `on_alert`, `on_mode_change`, `on_refused`, `on_link_lost`,
+  `on_controller_change`.
+- `robot.record(path)` JSON-lines recording and `menlo.asimov.recording.load()`.
+- Capability honesty on the room lanes: `camera`/`microphone` are claimed only once the
+  matching track is actually subscribed, and dropped when the room goes; a room with no
+  video raises `UnsupportedError` instead of yielding nothing.
+- Liveness: 10 Hz hold with a generation fence and bounded `duration`; `LinkLostError`
+  after `link_timeout` seconds of silence, with a zero velocity sent; `close()` zeroes a
+  held velocity; reopen with `close()` + `open()`.
+- State-stream hygiene: samples that do not match the robot are dropped, an older datagram
+  never overwrites a newer sample (sequence compared modulo 2^32), optional `state_source`
+  allowlist.
+- Generated `asimov.io` bindings vendored at asimov-protocol v1.1.0 with `protobuf` as the
+  only runtime dependency; an installed identical `asimov-protocol` is preferred.

menlo_sdk-0.1.0rc2/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for looking. This SDK is small on purpose; changes that keep it small are welcome.
+
+- Read `AGENTS.md` first: it is the rulebook (wire verbs, no guessing, tests that fail
+  without the fix).
+- `make sync && make check` must pass: ruff, mypy `--strict`, and the unit suite, which
+  drives a fake edge over the real wire and needs no robot.
+- Every behavioural change ships a test that fails on the previous code. If you change the
+  wire, update `tests/conftest.py` and run `make integration` against the real connector.
+- Public API changes go in `CHANGELOG.md` under the unreleased version. Cutting a release
+  (version numbers, rc, tags, PyPI) is described in `RELEASING.md`.
+- Commit messages describe the change and why; the body should let a reader reconstruct
+  the reasoning without the pull request.
+- The `asimov.io` bindings come from the `asimov-protocol` package on PyPI
+  (`asimov-protocol>=1.2.1rc1,<2` in `pyproject.toml`). Move the floor when the SDK starts using
+  something a newer protocol MINOR added; the `<2` bound moves only with the wire directory.
+
+Open a pull request against `main`. A review from a maintainer is required before merge.

menlo_sdk-0.1.0rc2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Menlo Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

menlo_sdk-0.1.0rc2/Makefile

@@ -0,0 +1,33 @@
+# menlo-sdk — developer entry points. `uv` is the only tool assumed.
+.PHONY: sync lint fmt typecheck test integration live livekit check
+
+sync:            ## create/refresh .venv from uv.lock
+	uv sync --all-groups
+
+lint:            ## ruff, the way CI runs it
+	uv run ruff check . && uv run ruff format --check .
+
+fmt:             ## fix what ruff can fix
+	uv run ruff check --fix . && uv run ruff format .
+
+typecheck:
+	uv run mypy
+
+test:            ## unit tests only (no robot, no edge checkout, no livekit)
+	uv run pytest -m "not integration and not live and not livekit"
+
+integration:     ## the real asimov-edge UdpConnector in-process; needs ASIMOV_EDGE_SRC=<edge>/src
+	uv run pytest -m integration
+
+live:            ## a robot or `menlo-studio up --container --sdk`; needs MENLO_SDK_LIVE_HOST
+	uv run pytest -m live -s
+
+livekit:         ## real livekit.rtc vs `livekit-server --dev`. Needs MENLO_SDK_LIVEKIT_URL and
+                 ## TWO tokens for one room (an identity is a claim inside the JWT, so one
+                 ## token is one participant): MENLO_SDK_LIVEKIT_TOKEN (identity `sdk`) and
+                 ## MENLO_SDK_LIVEKIT_EDGE_TOKEN (identity `fake-edge`). See the test module.
+	uv run --extra livekit pytest -m livekit -s
+
+
+
+check: lint typecheck test

menlo_sdk-0.1.0rc2/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: menlo-sdk
+Version: 0.1.0rc2
+Summary: Drive an Asimov robot from Python: one Robot, pluggable transports.
+Project-URL: Homepage, https://github.com/menloresearch/menlo-sdk
+Project-URL: Documentation, https://github.com/menloresearch/menlo-sdk/blob/main/docs/REFERENCE.md
+Project-URL: Repository, https://github.com/menloresearch/menlo-sdk
+Project-URL: Issues, https://github.com/menloresearch/menlo-sdk/issues
+Project-URL: Changelog, https://github.com/menloresearch/menlo-sdk/blob/main/CHANGELOG.md
+Author: Menlo Research
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asimov,humanoid,robotics,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: asimov-protocol<2,>=1.2.1rc1
+Requires-Dist: protobuf>=5.29.3
+Provides-Extra: livekit
+Requires-Dist: livekit<2,>=1.1.4; extra == 'livekit'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://menlo.ai"><img src="https://docs.menlo.ai/menlo-logo.svg" alt="Menlo" width="160"></a>
+</p>
+
+# menlo-sdk
+
+Drive an Asimov robot from Python. One `Robot`, five verbs, waits that read the robot's own
+report, and camera, microphone and speaker on the same connection.
+
+```bash
+pip install menlo-sdk              # UDP on the LAN; Python 3.12+
+pip install "menlo-sdk[livekit]"   # + video, audio and remote connections
+```
+
+## Quickstart
+
+Once per machine, save a robot. The credential is minted on the robot
+(`asimovctl sdk-token create --role control`, or its web UI's SDK page):
+
+```bash
+menlo login http://asimov.local --credential <credential>
+```
+
+Then a script is just:
+
+```python
+from menlo.asimov import Mode, Robot
+
+with Robot().connect() as robot:  # the robot you logged in to
+    if robot.state.mode is Mode.DAMP:  # wake up: STAND is the only way out of DAMP
+        robot.stand()
+        robot.wait_for(Mode.STAND, timeout=15)
+    robot.set_velocity(vx=0.25, duration=4.0, wait=True)  # walk 0.25 m/s for 4 s, then zero
+    robot.wait_for(Mode.MOVE)  # ends in MOVE at zero velocity: standing still
+    print(robot.state.joint("L_Knee").pos, robot.state.battery)
+    print(robot.camera.photo().to_jpeg()[:4])  # needs [livekit] and Pillow
+```
+
+`Robot()` finds the robot from `MENLO_MANAGER_URL` + `MENLO_CREDENTIAL`, else from
+`~/.menlo/robots.toml` (`menlo robots`, `menlo use <name>`, `menlo logout <name>`).
+Or say where it is: `Robot(ConnectionConfig(udp=UdpConfig("asimov.local"))).connect("udp")`.
+
+## The verbs
+
+| Verb | What it does |
+|---|---|
+| `set_velocity(vx, vy, vyaw, duration=, wait=)` | walk; held at 10 Hz until superseded, `stop()`, or `duration` |
+| `stop()` | zero velocity; the robot keeps balancing in MOVE |
+| `stand()` | stiffen into the standing pose; the wake-up verb, no balance loop |
+| `damp()` | motors compliant now; a standing robot folds. The emergency verb |
+| `goto(positions, duration=)` / `trajectory(positions)` | joint targets, radians, policy off |
+
+Every verb returns a `Sent` at once. `wait_for(Mode.X)` and `wait_until(pred)` block on the
+robot's report and raise `RobotFaultedError`, `StateStaleError` or `WaitTimeoutError`
+instead of guessing. `robot.state` is the latest sample: mode, joints, IMU, alerts, battery.
+
+## Three lanes, one API
+
+| `connect(mode)` | control + state | video + audio | when |
+|---|---|---|---|
+| `"udp"` | UDP 8850 / 8851 | — | on the robot's LAN, no camera needed |
+| `"hybrid"` | UDP | LiveKit | on the LAN, with camera |
+| `"livekit"` | LiveKit | LiveKit | from anywhere the robot's manager is reachable |
+
+`ManagerConfig(url, credential)` asks the robot's manager for the room and a fresh join
+token on every connect; the SDK never holds a LiveKit secret.
+
+## Read before you let go of the robot
+
+- **A walk ends in MOVE at zero velocity, not in `stand()`.** STAND is a stiffen with no
+  balance loop; asking a free-standing biped to stiffen after walking tips it over.
+- **The SDK sends zero when your script stops.** `close()`, the end of a `with` block, a
+  lost link and a fault-DAMP all release a held velocity. The edge DAMPs on its own about
+  two seconds after the last command it heard.
+- **`damp()` folds the robot.** It is never implied by anything else.
+- Speeds are clamped client-side (0.6 m/s, 1.5 rad/s by default) and the clamp is visible
+  on `Sent.clamped`.
+
+## More
+
+- [Reference](https://github.com/menloresearch/menlo-sdk/blob/main/docs/REFERENCE.md): every
+  option, the safety model in full, the wire, errors, development.
+- [SKILL.md](https://github.com/menloresearch/menlo-sdk/blob/main/docs/SKILL.md): the
+  two-page brief for an agent writing a script against this SDK.
+- [Examples](https://github.com/menloresearch/menlo-sdk/tree/main/examples) and the
+  [changelog](https://github.com/menloresearch/menlo-sdk/blob/main/CHANGELOG.md).
+- Versions follow PEP 440; pre-releases (`0.1.0rc1`) install only with `pip install --pre`.
+  How releases are cut: [RELEASING.md](https://github.com/menloresearch/menlo-sdk/blob/main/RELEASING.md).
+
+## License
+
+MIT. The wire types come from [`asimov-protocol`](https://pypi.org/project/asimov-protocol/) (MIT).