se3labs 0.0.0a0__tar.gz

se3labs-0.0.0a0/.gitignore

@@ -0,0 +1,92 @@
+# Data
+*.rrd
+
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Linker files
+*.ilk
+
+# Debugger Files
+*.pdb
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+*.so.*
+
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+# Build directories
+build/
+Build/
+build-*/
+
+# CMake generated files
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+Makefile
+install_manifest.txt
+compile_commands.json
+
+# Temporary files
+*.tmp
+*.log
+*.bak
+*.swp
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# vcpkg
+vcpkg_installed/
+
+# debug information files
+*.dwo
+
+# test output & cache
+Testing/
+.cache/
+
+# Documentation site (doc/public, Docusaurus)
+doc/public/node_modules/
+doc/public/build/
+doc/public/.docusaurus/
+doc/public/.cache-loader/
+
+# Customer package build output (sdk/)
+sdk/dist/
+sdk/build/

se3labs-0.0.0a0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: se3labs
+Version: 0.0.0a0
+Summary: SE3 Labs client library: evaluate your robot policy on an SE3 Labs station without shipping model code.
+Project-URL: Documentation, https://se3labs.github.io/YAM-Station/
+Project-URL: Source, https://github.com/se3labs/YAM-Station
+Author: SE3 Labs
+License-Expression: Apache-2.0
+Keywords: grpc,policy-evaluation,robotics
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: grpcio>=1.75
+Requires-Dist: protobuf>=6
+Description-Content-Type: text/markdown
+
+# se3labs
+
+Client library for evaluating a robot policy on an SE3 Labs station. Your
+model runs on your machine; the station streams observations to it over one
+gRPC stream, executes the actions it returns under the station's safety
+layer, and records everything. Nothing here touches hardware: the only
+dependencies are `grpcio` and `protobuf`.
+
+```bash
+pip install se3labs
+```
+
+Run a reference policy against the job id your SE3 Labs contact gives you,
+and poll the job's progress:
+
+```bash
+se3labs eval run    --job job_… --address relay.example.com:7443 --policy hold
+se3labs eval status --job job_… --address relay.example.com:7443
+```
+
+Wrap your own model:
+
+```python
+from se3labs.eval.policy import client
+from se3labs.eval.policy.proto import policy_session_pb2 as pb
+
+
+class MyPolicy:
+    def manifest(self) -> pb.ClientManifest:
+        return client.default_manifest(model="my-model", version="1", max_horizon=8)
+
+    def reset(self, reset: pb.Reset) -> None:
+        pass
+
+    def act(self, observe: pb.Observe) -> list[pb.Action]:
+        targets = {a.name: (list(a.joint_pos_rad), None) for a in observe.observation.arms}
+        return [client.joint_action(targets) for _ in range(8)]
+
+
+client.serve_policy("job_…", "relay.example.com:7443", MyPolicy())
+```
+
+Or, with that class saved in `my_policy.py`, without writing the last line:
+
+```bash
+se3labs eval run --job job_… --address relay.example.com:7443 --policy my_policy:MyPolicy
+```
+
+Full documentation: https://se3labs.github.io/YAM-Station/
+
+Protocol version: `se3labs.eval.policy.PROTOCOL_VERSION`. A release that
+changes it cannot talk to a station expecting the old one.

se3labs-0.0.0a0/README.md

@@ -0,0 +1,52 @@
+# se3labs
+
+Client library for evaluating a robot policy on an SE3 Labs station. Your
+model runs on your machine; the station streams observations to it over one
+gRPC stream, executes the actions it returns under the station's safety
+layer, and records everything. Nothing here touches hardware: the only
+dependencies are `grpcio` and `protobuf`.
+
+```bash
+pip install se3labs
+```
+
+Run a reference policy against the job id your SE3 Labs contact gives you,
+and poll the job's progress:
+
+```bash
+se3labs eval run    --job job_… --address relay.example.com:7443 --policy hold
+se3labs eval status --job job_… --address relay.example.com:7443
+```
+
+Wrap your own model:
+
+```python
+from se3labs.eval.policy import client
+from se3labs.eval.policy.proto import policy_session_pb2 as pb
+
+
+class MyPolicy:
+    def manifest(self) -> pb.ClientManifest:
+        return client.default_manifest(model="my-model", version="1", max_horizon=8)
+
+    def reset(self, reset: pb.Reset) -> None:
+        pass
+
+    def act(self, observe: pb.Observe) -> list[pb.Action]:
+        targets = {a.name: (list(a.joint_pos_rad), None) for a in observe.observation.arms}
+        return [client.joint_action(targets) for _ in range(8)]
+
+
+client.serve_policy("job_…", "relay.example.com:7443", MyPolicy())
+```
+
+Or, with that class saved in `my_policy.py`, without writing the last line:
+
+```bash
+se3labs eval run --job job_… --address relay.example.com:7443 --policy my_policy:MyPolicy
+```
+
+Full documentation: https://se3labs.github.io/YAM-Station/
+
+Protocol version: `se3labs.eval.policy.PROTOCOL_VERSION`. A release that
+changes it cannot talk to a station expecting the old one.

se3labs-0.0.0a0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "se3labs"
+# PEP 440 spelling of 0.0.0-alpha. Bump on every release; PyPI never
+# accepts the same version twice.
+version = "0.0.0a0"
+description = "SE3 Labs client library: evaluate your robot policy on an SE3 Labs station without shipping model code."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "SE3 Labs" }]
+keywords = ["robotics", "policy-evaluation", "grpc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "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",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# The generated *_pb2 modules check the protobuf runtime at import and
+# refuse one older than the protoc they came from; the floor tracks what
+# tool/gen_proto.sh was last run with.
+dependencies = [
+    "grpcio>=1.75",
+    "protobuf>=6",
+]
+
+[project.scripts]
+se3labs = "se3labs.cli:main"
+
+[project.urls]
+Documentation = "https://se3labs.github.io/YAM-Station/"
+Source = "https://github.com/se3labs/YAM-Station"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/se3labs"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/se3labs", "README.md", "pyproject.toml"]

se3labs-0.0.0a0/src/se3labs/__init__.py

@@ -0,0 +1,10 @@
+"""SE3 Labs customer-facing packages. Hardware-free: nothing here imports a
+robot driver. ``se3labs.eval.policy`` is the client for evaluating a policy
+on an SE3 Labs station."""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("se3labs")
+except PackageNotFoundError:  # source tree without an install
+    __version__ = "0+unknown"

se3labs-0.0.0a0/src/se3labs/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m se3labs`` is the ``se3labs`` command."""
+
+import sys
+
+from se3labs.cli import main
+
+sys.exit(main())

se3labs-0.0.0a0/src/se3labs/cli.py

@@ -0,0 +1,156 @@
+"""``se3labs``: the command line of the customer package.
+
+    se3labs eval run    --job JOB --address HOST:PORT [--policy hold|random|module:Attr]
+    se3labs eval status --job JOB --address HOST:PORT
+    se3labs --version
+
+Plain argparse so the package keeps its two runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import sys
+from collections.abc import Sequence
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _version() -> str:
+    try:
+        return version("se3labs")
+    except PackageNotFoundError:  # running from a source tree without an install
+        return "0+unknown"
+
+
+def _parse_image(spec: str) -> tuple[str, int, int]:
+    """``cam_chest:640x480`` → ("cam_chest", 640, 480); size defaults to 640x480."""
+    camera, _, size = spec.partition(":")
+    if not camera:
+        raise argparse.ArgumentTypeError(f"image spec needs a camera name: {spec!r}")
+    w, _, h = size.partition("x")
+    try:
+        return camera, int(w or 640), int(h or 480)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"image size must be WxH, got {size!r}") from None
+
+
+def load_policy(spec: str, *, horizon: int, images: Sequence[tuple[str, int, int]]):
+    """A policy object from its spec: a reference name, or ``module:Attr``
+    naming a class (instantiated with no arguments) or an instance."""
+    from se3labs.eval.policy import reference
+
+    if spec == "hold":
+        return reference.HoldStill(horizon=horizon, images=images)
+    if spec == "random":
+        return reference.RandomWalk(horizon=horizon)
+    module_name, sep, attr = spec.partition(":")
+    if not sep or not module_name or not attr:
+        raise SystemExit(f"--policy must be 'hold', 'random', or 'module:Attr'; got {spec!r}")
+    sys.path.insert(0, "")  # the working directory, as `python -m` would
+    try:
+        obj = getattr(importlib.import_module(module_name), attr)
+    except (ImportError, AttributeError) as exc:
+        raise SystemExit(f"cannot load policy {spec!r}: {exc}") from None
+    return obj() if isinstance(obj, type) else obj
+
+
+def cmd_eval_run(args: argparse.Namespace) -> int:
+    from se3labs.eval.policy import client
+
+    policy = load_policy(args.policy, horizon=args.horizon, images=args.image)
+    try:
+        report = client.serve_policy(args.job, args.address, policy, secure=args.secure)
+    except client.SessionRejected as exc:
+        print(f"rejected: {exc}", file=sys.stderr)
+        return 2
+    print(f"session closed: {report.close_reason or 'stream ended'}; {report.episodes} resets, {report.steps} steps")
+    if report.errors:
+        print("policy errors:", *report.errors[:5], sep="\n  ", file=sys.stderr)
+        return 1
+    return 0
+
+
+def cmd_eval_status(args: argparse.Namespace) -> int:
+    import grpc
+
+    from se3labs.eval.policy.proto import job_status_pb2, job_status_pb2_grpc
+
+    channel = (
+        grpc.secure_channel(args.address, grpc.ssl_channel_credentials())
+        if args.secure
+        else grpc.insecure_channel(args.address)
+    )
+    with channel:
+        try:
+            status = job_status_pb2_grpc.JobStatusStub(channel).Get(
+                job_status_pb2.StatusRequest(job_id=args.job), timeout=args.timeout
+            )
+        except grpc.RpcError as exc:
+            print(f"{exc.code().name}: {exc.details()}", file=sys.stderr)
+            return 2
+    if args.json:
+        print(json.dumps({
+            "job_id": status.job_id,
+            "state": status.state,
+            "episode_index": status.episode_index,
+            "episodes_total": status.episodes_total,
+            "outcomes": dict(status.outcomes),
+            "updated_unix_ms": status.updated_unix_ms,
+            "message": status.message,
+        }))
+    else:
+        outcomes = ", ".join(f"{k}={v}" for k, v in sorted(status.outcomes.items())) or "none yet"
+        print(f"{status.job_id}: {status.state}  episode {status.episode_index}/{status.episodes_total}  {outcomes}")
+        if status.message:
+            print(f"  {status.message}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="se3labs", description="SE3 Labs command line.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_version()}")
+    groups = parser.add_subparsers(dest="group", required=True, metavar="<group>")
+
+    ev = groups.add_parser("eval", help="policy evaluation on an SE3 Labs station")
+    cmds = ev.add_subparsers(dest="command", required=True, metavar="<command>")
+
+    def connection(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--job", required=True, help="job id from SE3 Labs")
+        p.add_argument("--address", required=True, help="relay or station host:port")
+        p.add_argument("--secure", action="store_true", help="TLS to the address")
+
+    run = cmds.add_parser("run", help="connect a policy to a job and run every episode")
+    connection(run)
+    run.add_argument(
+        "--policy",
+        default="hold",
+        help="'hold' or 'random' (reference policies), or module:Attr naming your policy class or instance (default: hold)",
+    )
+    run.add_argument("--horizon", type=int, default=4, help="actions per chunk for the reference policies (default: 4)")
+    run.add_argument(
+        "--image",
+        action="append",
+        default=[],
+        type=_parse_image,
+        metavar="CAMERA[:WxH]",
+        help="request a camera stream, e.g. cam_chest:640x480; repeatable",
+    )
+    run.set_defaults(func=cmd_eval_run)
+
+    status = cmds.add_parser("status", help="poll a job's progress from the relay")
+    connection(status)
+    status.add_argument("--timeout", type=float, default=10.0, help="seconds to wait for the relay (default: 10)")
+    status.add_argument("--json", action="store_true", help="print the status as one JSON object")
+    status.set_defaults(func=cmd_eval_status)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

se3labs-0.0.0a0/src/se3labs/eval/__init__.py

@@ -0,0 +1 @@
+"""Policy evaluation on an SE3 Labs station, seen from the customer's side."""

se3labs-0.0.0a0/src/se3labs/eval/policy/__init__.py

@@ -0,0 +1,9 @@
+"""The customer-facing policy protocol and, later, the client SDK.
+
+Importable without hardware dependencies: nothing under this package may
+import the driver, i2rt or MuJoCo. The wire contract lives in
+:mod:`se3labs.eval.policy.proto`; see doc/01-remote-policy-evaluation.md §6.
+"""
+
+#: Bumped on any wire change a client could not ignore. Sent in ``Hello``.
+PROTOCOL_VERSION = 1

se3labs-0.0.0a0/src/se3labs/eval/policy/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m se3labs.eval.policy …`` is an alias of ``se3labs eval run …``."""
+
+import sys
+
+from se3labs.cli import main
+
+sys.exit(main(["eval", "run", *sys.argv[1:]]))

se3labs-0.0.0a0/src/se3labs/eval/policy/client.py

@@ -0,0 +1,170 @@
+"""The customer-side client: wrap a policy object and speak the stream.
+
+    from se3labs.eval.policy import client, reference
+    client.serve_policy("job_…", "relay.example.com:7443", reference.HoldStill())
+
+A :class:`Policy` answers three things: its manifest (what it wants and
+can do), a reset per episode, and actions per observation. The client
+handles the handshake, echoes every identifier, and returns a report when
+the station closes the session. It needs only ``grpcio`` and ``protobuf``.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+import grpc
+
+from se3labs.eval.policy import PROTOCOL_VERSION
+from se3labs.eval.policy.proto import policy_session_pb2 as pb
+from se3labs.eval.policy.proto import policy_session_pb2_grpc as rpc
+
+
+@runtime_checkable
+class Policy(Protocol):
+    def manifest(self) -> pb.ClientManifest: ...
+
+    def reset(self, reset: pb.Reset) -> None: ...
+
+    def act(self, observe: pb.Observe) -> Sequence[pb.Action]:
+        """1 to ``negotiated.max_horizon`` actions at the negotiated dt."""
+        ...
+
+
+class SessionRejected(RuntimeError):
+    def __init__(self, reject: pb.Reject) -> None:
+        super().__init__(f"{pb.RejectCode.Name(reject.code)}: {reject.message}")
+        self.reject = reject
+
+
+@dataclass
+class SessionReport:
+    welcome: pb.Welcome | None = None
+    episodes: int = 0
+    steps: int = 0
+    close_reason: str = ""
+    errors: list[str] = field(default_factory=list)
+
+
+def joint_action(targets: Mapping[str, tuple[Sequence[float], float | None]]) -> pb.Action:
+    """One time step: arm name → (joint positions in rad, gripper or None)."""
+    action = pb.Action()
+    for arm, (joints, gripper) in targets.items():
+        jp = pb.JointPositionAction(arm=arm, joint_pos_rad=list(joints))
+        if gripper is not None:
+            jp.gripper_pos = gripper
+        action.arms.add(joint_position=jp)
+    return action
+
+
+def default_manifest(
+    *,
+    model: str = "reference",
+    version: str = "0",
+    images: Sequence[tuple[str, int, int]] = (),
+    max_horizon: int = 8,
+    stateful: bool = False,
+) -> pb.ClientManifest:
+    manifest = pb.ClientManifest(
+        model=pb.ModelIdentity(name=model, version=version),
+        action_schemas=[pb.ACTION_SCHEMA_JOINT_POSITION_V1],
+        max_horizon=max_horizon,
+        stateful=stateful,
+    )
+    for camera, w, h in images:
+        manifest.observation.images.append(
+            pb.ImageRequest(camera=camera, max_width=w, max_height=h, encoding=pb.IMAGE_ENCODING_JPEG)
+        )
+    return manifest
+
+
+class _Outbox:
+    """Client→server messages as the iterator gRPC consumes."""
+
+    def __init__(self) -> None:
+        self._q: queue.Queue[pb.ClientMsg | None] = queue.Queue()
+
+    def put(self, msg: pb.ClientMsg) -> None:
+        self._q.put(msg)
+
+    def close(self) -> None:
+        self._q.put(None)
+
+    def __iter__(self) -> Iterator[pb.ClientMsg]:
+        return iter(self._q.get, None)
+
+
+def run_session(
+    stream: Iterator[pb.ServerMsg],
+    outbox: _Outbox,
+    job_id: str,
+    policy: Policy,
+) -> SessionReport:
+    """Drive one session over an already-open stream. Split from the
+    transport so the relay and runner tests can exercise it in-process."""
+    report = SessionReport()
+    outbox.put(pb.ClientMsg(hello=pb.Hello(job_id=job_id, protocol_version=PROTOCOL_VERSION, manifest=policy.manifest())))
+    try:
+        for msg in stream:
+            kind = msg.WhichOneof("msg")
+            if kind == "welcome":
+                report.welcome = msg.welcome
+            elif kind == "reject":
+                raise SessionRejected(msg.reject)
+            elif kind == "reset":
+                policy.reset(msg.reset)
+                report.episodes += 1
+                outbox.put(pb.ClientMsg(reset_ack=pb.ResetAck(episode_id=msg.reset.episode_id)))
+            elif kind == "observe":
+                o = msg.observe
+                try:
+                    actions = list(policy.act(o))
+                except Exception as exc:  # noqa: BLE001 - a policy bug is reported, not fatal
+                    report.errors.append(f"step {o.step_id}: {exc!r}")
+                    actions = []
+                chunk = pb.Chunk(episode_id=o.episode_id, step_id=o.step_id, request_id=o.request_id, actions=actions)
+                outbox.put(pb.ClientMsg(chunk=chunk))
+                report.steps += 1
+            elif kind == "close":
+                report.close_reason = msg.close.reason
+                break
+    finally:
+        outbox.close()
+    return report
+
+
+def serve_policy(
+    job_id: str,
+    address: str,
+    policy: Policy,
+    *,
+    secure: bool = False,
+    timeout_s: float | None = None,
+) -> SessionReport:
+    """Connect to ``address`` (the relay, or a station directly), run the
+    whole session for ``job_id``, and return the report."""
+    channel = grpc.secure_channel(address, grpc.ssl_channel_credentials()) if secure else grpc.insecure_channel(address)
+    try:
+        grpc.channel_ready_future(channel).result(timeout=timeout_s or 30.0)
+        stub = rpc.PolicySessionStub(channel)
+        outbox = _Outbox()
+        stream = stub.Run(iter(outbox), timeout=timeout_s)
+        return run_session(stream, outbox, job_id, policy)
+    finally:
+        channel.close()
+
+
+def serve_policy_in_thread(job_id: str, address: str, policy: Policy) -> tuple[threading.Thread, list[SessionReport]]:
+    """Test helper: the session on a thread, its report appended when done."""
+    reports: list[SessionReport] = []
+
+    def run() -> None:
+        reports.append(serve_policy(job_id, address, policy))
+
+    t = threading.Thread(target=run, name=f"policy-{job_id}", daemon=True)
+    t.start()
+    return t, reports

se3labs-0.0.0a0/src/se3labs/eval/policy/proto/__init__.py

@@ -0,0 +1,3 @@
+"""Generated protocol code. ``policy_session.proto`` is the source; the
+``*_pb2*`` modules are produced by ``tool/gen_proto.sh`` and checked in so a
+client install needs no compiler."""

se3labs-0.0.0a0/src/se3labs/eval/policy/proto/job_status.proto

@@ -0,0 +1,31 @@
+// Job progress, as a customer may poll it from the relay. The station
+// pushes one Status per state change; the relay caches the latest.
+//
+// Regenerate the Python after editing: tool/gen_proto.sh (in the station
+// repo). Design: doc/01-remote-policy-evaluation.md §9.
+
+syntax = "proto3";
+
+package se3labs.eval.policy.v1;
+
+service JobStatus {
+  // The latest status the station reported for a job id.
+  rpc Get(StatusRequest) returns (Status);
+}
+
+message StatusRequest {
+  string job_id = 1;
+}
+
+message Status {
+  string job_id = 1;
+  // CREATED, WAITING_POLICY, PREFLIGHT, RUNNING, PAUSED, FINALIZING,
+  // SUCCEEDED, FAILED, CANCELLED.
+  string state = 2;
+  uint32 episode_index = 3;
+  uint32 episodes_total = 4;
+  // Count per outcome: success, failure, indeterminate, invalidated.
+  map<string, uint32> outcomes = 5;
+  int64 updated_unix_ms = 6;
+  string message = 7;
+}