servo-client 0.2.0__tar.gz

servo_client-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include servo_client_build_backend.py
+graft src
+global-exclude __pycache__
+global-exclude *.py[cod]

servo_client-0.2.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: servo-client
+Version: 0.2.0
+Summary: Python SDK for Servo's hosted robot model API
+Project-URL: Documentation, https://servo.mintlify.site/
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx[http2]
+Requires-Dist: msgpack>=1.0.5
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2
+Requires-Dist: protobuf<7,>=6.33.6
+Requires-Dist: websockets>=13
+Provides-Extra: livekit
+Requires-Dist: livekit==1.1.14; extra == "livekit"
+
+# servo-client
+
+The public Python SDK and customer CLI for Servo robot policies, world models, datasets, jobs, and
+deployments.
+
+## Install
+
+```bash
+pip install 'servo-client>=0.2,<0.3'
+```
+
+Servo releases two architecture-specific Linux wheels containing the native Quinn action-session
+binary, one portable wheel, and a source distribution. Native clients prefer a validated QUIC
+route; WSS and H2 binary remain ordered pre-inference fallbacks. Portable installations use the
+advertised non-native routes. Every route carries the same ActionSession v4 Protobuf frames.
+
+LiveKit is an explicit optional transport:
+
+```bash
+pip install 'servo-client[livekit]>=0.2,<0.3'
+```
+
+## Configure the control plane
+
+Servo has no compiled-in hosted URL. Set the origin supplied by your Servo administrator so an old
+package cannot silently send credentials or robot traffic to a retired deployment:
+
+```bash
+export SERVO_BASE_URL='https://<your-servo-control-plane>'
+```
+
+The client also accepts `base_url=` explicitly. The argument takes precedence over the environment.
+
+## Sign in
+
+The distribution installs the customer-safe `servo` CLI:
+
+```bash
+servo login
+servo whoami
+servo key create --label laptop
+servo deployment list
+```
+
+Serving, benchmarking, profiling, and platform-operator commands belong to the private
+`servo-platform` distribution and are not installed by `servo-client`.
+
+## Quickstart
+
+```python
+import os
+
+import servo
+from servo import templates
+
+sv = servo.Servo(
+    base_url=os.environ["SERVO_BASE_URL"],
+    api_key=os.environ["SERVO_API_KEY"],
+)
+
+robot = sv.robots.register(templates.so101())
+observation = templates.sample_observation(robot)
+model = sv.models.get("smolvla")
+
+report = model.inspect(robot)
+if not report.compatible:
+    raise RuntimeError(report.issues)
+
+prediction = model.policy(robot, instruction="pick up the cube").act(observation)
+print(prediction.actions[0])
+```
+
+## Action sessions
+
+`sv.session(policy)` negotiates the transports advertised by the selected deployment. Once an
+inference request could have executed, Servo never replays it over another route.
+
+LiveKit requires both deployment and session opt-in:
+
+```python
+provider = servo.ServingProvider(os.environ["SERVO_SERVE_PROVIDER"])
+deployment = model.deploy(
+    robot,
+    serve_provider=provider,
+    action_session_channels=("livekit", "wss"),
+)
+policy = deployment.policy(robot, instruction="pick up the cube")
+
+with sv.session(
+    policy,
+    action_session=servo.ActionSessionOptions(channels=("livekit",)),
+) as session:
+    prediction = session.act(observation)
+```
+
+## Public boundary
+
+Application compatibility is promised for documented imports from `servo` and these client
+namespaces:
+
+- Stable: `robots`, `adapters`, `models`, `datasets`/`data`, `deployments`, `jobs`, `licenses`, and
+  `secrets`.
+- Advanced: direct endpoint helpers (`servo.connect`, `servo.attach`, `EndpointGrant`) and
+  `sv.self_hosted`.
+
+The distribution also carries dependency-light support packages:
+
+- Extension contracts: `servo_action_session`, `servo_data`, and `servo_observation`.
+- Implementation dependencies: `servo_contracts` and `servo_telemetry`.
+
+Importability of an implementation package is not a customer compatibility promise. The client
+wheel excludes product-only profiler integration and does not contain `servo_platform`,
+`servo_runtimes`, FastAPI routes, database models, provider launchers, provider credentials, or
+private endpoint URLs.
+
+## Failure and retry policy
+
+The client does not automatically replay mutations or robot actions. Transport and server failures
+are returned as typed Servo errors so applications can choose a recovery policy appropriate to the
+operation. Idempotent reads may be retried by application code. Configure `timeout=` on
+`servo.Servo`; long-running synchronous jobs can require a larger read timeout than catalog calls.
+
+## Requirements
+
+- Python 3.12+
+- A Servo control-plane URL
+- An organization API key for authenticated operations
+
+Full documentation: <https://servo.mintlify.site/>

servo_client-0.2.0/README.md

@@ -0,0 +1,129 @@
+# servo-client
+
+The public Python SDK and customer CLI for Servo robot policies, world models, datasets, jobs, and
+deployments.
+
+## Install
+
+```bash
+pip install 'servo-client>=0.2,<0.3'
+```
+
+Servo releases two architecture-specific Linux wheels containing the native Quinn action-session
+binary, one portable wheel, and a source distribution. Native clients prefer a validated QUIC
+route; WSS and H2 binary remain ordered pre-inference fallbacks. Portable installations use the
+advertised non-native routes. Every route carries the same ActionSession v4 Protobuf frames.
+
+LiveKit is an explicit optional transport:
+
+```bash
+pip install 'servo-client[livekit]>=0.2,<0.3'
+```
+
+## Configure the control plane
+
+Servo has no compiled-in hosted URL. Set the origin supplied by your Servo administrator so an old
+package cannot silently send credentials or robot traffic to a retired deployment:
+
+```bash
+export SERVO_BASE_URL='https://<your-servo-control-plane>'
+```
+
+The client also accepts `base_url=` explicitly. The argument takes precedence over the environment.
+
+## Sign in
+
+The distribution installs the customer-safe `servo` CLI:
+
+```bash
+servo login
+servo whoami
+servo key create --label laptop
+servo deployment list
+```
+
+Serving, benchmarking, profiling, and platform-operator commands belong to the private
+`servo-platform` distribution and are not installed by `servo-client`.
+
+## Quickstart
+
+```python
+import os
+
+import servo
+from servo import templates
+
+sv = servo.Servo(
+    base_url=os.environ["SERVO_BASE_URL"],
+    api_key=os.environ["SERVO_API_KEY"],
+)
+
+robot = sv.robots.register(templates.so101())
+observation = templates.sample_observation(robot)
+model = sv.models.get("smolvla")
+
+report = model.inspect(robot)
+if not report.compatible:
+    raise RuntimeError(report.issues)
+
+prediction = model.policy(robot, instruction="pick up the cube").act(observation)
+print(prediction.actions[0])
+```
+
+## Action sessions
+
+`sv.session(policy)` negotiates the transports advertised by the selected deployment. Once an
+inference request could have executed, Servo never replays it over another route.
+
+LiveKit requires both deployment and session opt-in:
+
+```python
+provider = servo.ServingProvider(os.environ["SERVO_SERVE_PROVIDER"])
+deployment = model.deploy(
+    robot,
+    serve_provider=provider,
+    action_session_channels=("livekit", "wss"),
+)
+policy = deployment.policy(robot, instruction="pick up the cube")
+
+with sv.session(
+    policy,
+    action_session=servo.ActionSessionOptions(channels=("livekit",)),
+) as session:
+    prediction = session.act(observation)
+```
+
+## Public boundary
+
+Application compatibility is promised for documented imports from `servo` and these client
+namespaces:
+
+- Stable: `robots`, `adapters`, `models`, `datasets`/`data`, `deployments`, `jobs`, `licenses`, and
+  `secrets`.
+- Advanced: direct endpoint helpers (`servo.connect`, `servo.attach`, `EndpointGrant`) and
+  `sv.self_hosted`.
+
+The distribution also carries dependency-light support packages:
+
+- Extension contracts: `servo_action_session`, `servo_data`, and `servo_observation`.
+- Implementation dependencies: `servo_contracts` and `servo_telemetry`.
+
+Importability of an implementation package is not a customer compatibility promise. The client
+wheel excludes product-only profiler integration and does not contain `servo_platform`,
+`servo_runtimes`, FastAPI routes, database models, provider launchers, provider credentials, or
+private endpoint URLs.
+
+## Failure and retry policy
+
+The client does not automatically replay mutations or robot actions. Transport and server failures
+are returned as typed Servo errors so applications can choose a recovery policy appropriate to the
+operation. Idempotent reads may be retried by application code. Configure `timeout=` on
+`servo.Servo`; long-running synchronous jobs can require a larger read timeout than catalog calls.
+
+## Requirements
+
+- Python 3.12+
+- A Servo control-plane URL
+- An organization API key for authenticated operations
+
+Full documentation: <https://servo.mintlify.site/>

servo_client-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "servo_client_build_backend"
+backend-path = ["."]
+
+[project]
+name = "servo-client"
+version = "0.2.0"
+description = "Python SDK for Servo's hosted robot model API"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "cryptography>=42",
+    "httpx[http2]",
+    "msgpack>=1.0.5",
+    "numpy>=1.26",
+    "pydantic>=2",
+    "protobuf>=6.33.6,<7",
+    "websockets>=13",
+]
+
+[project.optional-dependencies]
+livekit = ["livekit==1.1.14"]
+
+[project.scripts]
+servo = "servo.cli:main"
+
+[project.urls]
+Documentation = "https://servo.mintlify.site/"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = [
+    "servo",
+    "servo.*",
+    "servo_action_session",
+    "servo_action_session.*",
+    "servo_contracts",
+    "servo_contracts.*",
+    "servo_data",
+    "servo_data.*",
+    "servo_observation",
+    "servo_observation.*",
+    "servo_telemetry",
+    "servo_telemetry.*",
+]
+exclude = ["servo_platform*"]
+
+# The native QUIC data plane is the default transport, so the compiled artifact
+# ships with the client rather than being something the user has to locate or
+# build. Wheels carrying it are platform-specific by construction.
+[tool.setuptools.package-data]
+servo = ["_native/servo-action-session-quic"]

servo_client-0.2.0/servo_client_build_backend.py

@@ -0,0 +1,356 @@
+"""Build the public client from the monorepo's canonical Python sources.
+
+The public distribution is a strict projection of selected packages in the repository-level
+``src`` tree.  A PEP 517 source distribution must be self-contained, so pointing setuptools at
+``../../src`` produces an sdist whose paths escape the archive and whose wheel cannot be rebuilt.
+This backend stages only the public packages into the conventional local ``src`` layout before
+delegating to setuptools.  The generated sdist therefore contains its complete, immutable build
+input and can be built independently of the Servo repository.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import shutil
+import tempfile
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from setuptools import build_meta as _setuptools
+
+
+_PROJECT_ROOT = Path(__file__).resolve().parent
+
+
+def _contract_value(name: str) -> tuple[str, ...]:
+    """Read a tuple from the data-only SDK contract without importing ``servo``."""
+
+    candidates = (
+        _PROJECT_ROOT / "src" / "servo" / "public_api.py",
+        (_PROJECT_ROOT / ".." / ".." / "src" / "servo" / "public_api.py").resolve(),
+    )
+    contract_path = next((path for path in candidates if path.is_file()), None)
+    if contract_path is None:
+        raise RuntimeError("servo-client build could not locate src/servo/public_api.py")
+    tree = ast.parse(contract_path.read_text(encoding="utf-8"), filename=str(contract_path))
+    values: dict[str, tuple[str, ...]] = {}
+
+    def evaluate(node: ast.expr) -> tuple[str, ...] | None:
+        if isinstance(node, ast.Name):
+            return values.get(node.id)
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+            left = evaluate(node.left)
+            right = evaluate(node.right)
+            return left + right if left is not None and right is not None else None
+        try:
+            value = ast.literal_eval(node)
+        except (ValueError, TypeError):
+            return None
+        if isinstance(value, tuple) and all(isinstance(item, str) for item in value):
+            return value
+        return None
+
+    for node in tree.body:
+        if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+            continue
+        target = node.targets[0]
+        if not isinstance(target, ast.Name):
+            continue
+        value = evaluate(node.value)
+        if value is not None:
+            values[target.id] = value
+    try:
+        return values[name]
+    except KeyError as exc:
+        raise RuntimeError(f"servo-client public contract does not define {name}") from exc
+
+
+_PUBLIC_PACKAGES = _contract_value("DISTRIBUTION_PACKAGES")
+_CLIENT_EXCLUDED_PATHS = {
+    Path(*module.split(".")).with_suffix(".py")
+    for module in _contract_value("CLIENT_EXCLUDED_MODULES")
+}
+_STAGE_EXCLUDES = {
+    ".git",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "src",
+}
+_PUBLIC_BUILD_ARTIFACT_SUFFIXES = {".dylib", ".pyd", ".so"}
+_BENCHMARK_ONLY_SOURCES = {
+    "flatbuffers_cython.c",
+    "flatbuffers_cython.pyx",
+}
+_PLATFORM_TAG_ENV_VAR = "SERVO_CLIENT_WHEEL_PLATFORM_TAG"
+_RELEASE_PLATFORM_TAGS = {
+    "manylinux_2_28_aarch64",
+    "manylinux_2_28_x86_64",
+}
+
+
+def _canonical_source_root() -> Path:
+    local_source = _PROJECT_ROOT / "src"
+    repository_source = (_PROJECT_ROOT / ".." / ".." / "src").resolve()
+    for candidate in (local_source, repository_source):
+        if all((candidate / package).is_dir() for package in _PUBLIC_PACKAGES):
+            return candidate
+    raise RuntimeError(
+        "servo-client build requires all configured public source packages: "
+        + ", ".join(_PUBLIC_PACKAGES)
+    )
+
+
+def _ignore_stage_entry(path: Path) -> bool:
+    return (
+        path.name in _STAGE_EXCLUDES
+        or path.name.endswith(".egg-info")
+        or path.suffix in {".pyc", ".pyo"}
+    )
+
+
+def _ignore_public_source_entry(path: Path, *, source_root: Path) -> bool:
+    """Exclude local/benchmark build products from the public SDK projection.
+
+    The canonical source tree is also the output directory for optional native builds. Copying it
+    wholesale can otherwise put a developer's architecture-specific extension into a supposedly
+    portable wheel. The FlatBuffers Cython source is benchmark-only and is not a product codec.
+    The one native executable that is part of the product is suffixless and remains included.
+    """
+    return (
+        _ignore_stage_entry(path)
+        or path.relative_to(source_root) in _CLIENT_EXCLUDED_PATHS
+        or path.suffix in _PUBLIC_BUILD_ARTIFACT_SUFFIXES
+        or path.name in _BENCHMARK_ONLY_SOURCES
+    )
+
+
+def _copy_project(stage: Path) -> None:
+    stage.mkdir(parents=True)
+    for source in _PROJECT_ROOT.iterdir():
+        if _ignore_stage_entry(source):
+            continue
+        destination = stage / source.name
+        if source.is_dir():
+            shutil.copytree(
+                source,
+                destination,
+                ignore=lambda _directory, names: [
+                    name for name in names if _ignore_stage_entry(Path(name))
+                ],
+            )
+        else:
+            shutil.copy2(source, destination)
+
+    canonical_source = _canonical_source_root()
+    staged_source = stage / "src"
+    staged_source.mkdir()
+    for package in _PUBLIC_PACKAGES:
+        shutil.copytree(
+            canonical_source / package,
+            staged_source / package,
+            ignore=lambda directory, names: [
+                name
+                for name in names
+                if _ignore_public_source_entry(
+                    Path(directory) / name,
+                    source_root=canonical_source,
+                )
+            ],
+        )
+
+
+def _native_artifact(stage: Path) -> Path:
+    return stage / "src" / "servo" / "_native" / "servo-action-session-quic"
+
+
+def _exclude_native_artifact(stage: Path) -> None:
+    """Keep the host architecture's executable out of source distributions."""
+    artifact = _native_artifact(stage)
+    if artifact.is_file():
+        artifact.unlink()
+
+
+def _configure_platform_wheel(stage: Path) -> None:
+    """Make a wheel carrying the native data plane fail on another architecture."""
+    if not _native_artifact(stage).is_file():
+        return
+    platform_override = os.environ.get(_PLATFORM_TAG_ENV_VAR)
+    if platform_override is not None and platform_override not in _RELEASE_PLATFORM_TAGS:
+        raise RuntimeError(
+            f"{_PLATFORM_TAG_ENV_VAR} must name a governed release platform, "
+            f"got {platform_override!r}"
+        )
+    (stage / "setup.py").write_text(
+        f"""from setuptools import Distribution, setup
+from wheel.bdist_wheel import bdist_wheel
+
+
+PLATFORM_OVERRIDE = {platform_override!r}
+
+
+class PlatformDistribution(Distribution):
+    def has_ext_modules(self):
+        return True
+
+
+class PlatformWheel(bdist_wheel):
+    def finalize_options(self):
+        super().finalize_options()
+        self.root_is_pure = False
+
+    def get_tag(self):
+        _python, _abi, platform = super().get_tag()
+        return "py3", "none", PLATFORM_OVERRIDE or platform
+
+
+setup(distclass=PlatformDistribution, cmdclass={{"bdist_wheel": PlatformWheel}})
+""",
+        encoding="utf-8",
+    )
+
+
+def _configure_editable_project(stage: Path) -> None:
+    """Force setuptools' selective finder while retaining canonical source paths.
+
+    A single ``{"": "src"}`` mapping makes setuptools emit a plain ``.pth`` entry.  Besides
+    pointing at the temporary staging tree, that would expose every repository package.  Explicit
+    top-level mappings make setuptools emit its selective meta-path finder, and the finder resolves
+    directly to the canonical source directories after the build staging tree is removed.
+    """
+
+    canonical_source = _canonical_source_root()
+    mappings = ", ".join(
+        f'"{package}" = "{Path(os.path.relpath(canonical_source / package, stage)).as_posix()}"'
+        for package in _PUBLIC_PACKAGES
+    )
+    pyproject_path = stage / "pyproject.toml"
+    pyproject = pyproject_path.read_text(encoding="utf-8")
+    original = 'package-dir = {"" = "src"}'
+    replacement = f"package-dir = {{{mappings}}}"
+    if pyproject.count(original) != 1:
+        raise RuntimeError("servo-client editable build could not locate package-dir declaration")
+    pyproject_path.write_text(pyproject.replace(original, replacement), encoding="utf-8")
+
+
+@contextmanager
+def _staged_project(
+    *,
+    editable: bool = False,
+    include_native: bool = True,
+    platform_wheel: bool = False,
+) -> Iterator[None]:
+    previous_directory = Path.cwd()
+    with tempfile.TemporaryDirectory(prefix="servo-client-build-") as temporary_directory:
+        # Resolve macOS' /var -> /private/var symlink before deriving editable
+        # package paths. A lexical relative path calculated across that symlink
+        # otherwise resolves under /private/Users after setuptools changes cwd.
+        stage = Path(temporary_directory).resolve() / "servo-client"
+        _copy_project(stage)
+        if not include_native:
+            _exclude_native_artifact(stage)
+        if platform_wheel:
+            _configure_platform_wheel(stage)
+        if editable:
+            _configure_editable_project(stage)
+        os.chdir(stage)
+        try:
+            yield
+        finally:
+            os.chdir(previous_directory)
+
+
+def _absolute_directory(path: str) -> str:
+    return str(Path(path).resolve())
+
+
+def get_requires_for_build_wheel(
+    config_settings: Mapping[str, Any] | None = None,
+) -> list[str]:
+    with _staged_project(platform_wheel=True):
+        return _setuptools.get_requires_for_build_wheel(config_settings)
+
+
+def get_requires_for_build_sdist(
+    config_settings: Mapping[str, Any] | None = None,
+) -> list[str]:
+    with _staged_project(include_native=False):
+        return _setuptools.get_requires_for_build_sdist(config_settings)
+
+
+def get_requires_for_build_editable(
+    config_settings: Mapping[str, Any] | None = None,
+) -> list[str]:
+    with _staged_project(editable=True):
+        return _setuptools.get_requires_for_build_editable(config_settings)
+
+
+def prepare_metadata_for_build_wheel(
+    metadata_directory: str,
+    config_settings: Mapping[str, Any] | None = None,
+) -> str:
+    metadata_directory = _absolute_directory(metadata_directory)
+    with _staged_project(platform_wheel=True):
+        return _setuptools.prepare_metadata_for_build_wheel(
+            metadata_directory,
+            config_settings,
+        )
+
+
+def prepare_metadata_for_build_editable(
+    metadata_directory: str,
+    config_settings: Mapping[str, Any] | None = None,
+) -> str:
+    metadata_directory = _absolute_directory(metadata_directory)
+    with _staged_project(editable=True):
+        return _setuptools.prepare_metadata_for_build_editable(
+            metadata_directory,
+            config_settings,
+        )
+
+
+def build_wheel(
+    wheel_directory: str,
+    config_settings: Mapping[str, Any] | None = None,
+    metadata_directory: str | None = None,
+) -> str:
+    wheel_directory = _absolute_directory(wheel_directory)
+    if metadata_directory is not None:
+        metadata_directory = _absolute_directory(metadata_directory)
+    with _staged_project(platform_wheel=True):
+        return _setuptools.build_wheel(
+            wheel_directory,
+            config_settings,
+            metadata_directory,
+        )
+
+
+def build_editable(
+    wheel_directory: str,
+    config_settings: Mapping[str, Any] | None = None,
+    metadata_directory: str | None = None,
+) -> str:
+    wheel_directory = _absolute_directory(wheel_directory)
+    if metadata_directory is not None:
+        metadata_directory = _absolute_directory(metadata_directory)
+    with _staged_project(editable=True):
+        return _setuptools.build_editable(
+            wheel_directory,
+            config_settings,
+            metadata_directory,
+        )
+
+
+def build_sdist(
+    sdist_directory: str,
+    config_settings: Mapping[str, Any] | None = None,
+) -> str:
+    sdist_directory = _absolute_directory(sdist_directory)
+    with _staged_project(include_native=False):
+        return _setuptools.build_sdist(sdist_directory, config_settings)

servo_client-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+