orchestral-client 0.1.0__tar.gz

orchestral_client-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: orchestral-client
+Version: 0.1.0
+Summary: Orchestral Labs — Real-time robotics & VLA model platform
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: httpx>=0.27
+Requires-Dist: msgpack>=1.0.5
+Requires-Dist: cryptography>=42.0
+Requires-Dist: PyJWT>=2.8
+Requires-Dist: omegaconf>=2.3.0
+Requires-Dist: aioquic>=1.2.0
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: av>=12.0
+Requires-Dist: pillow>=10.0
+Provides-Extra: cloud
+Requires-Dist: boto3>=1.34; extra == "cloud"
+Provides-Extra: exp
+Requires-Dist: wandb>=0.18; extra == "exp"
+Provides-Extra: benchmark
+Requires-Dist: boto3>=1.34; extra == "benchmark"
+Requires-Dist: wandb>=0.18; extra == "benchmark"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: tach>=0.35; extra == "dev"
+Requires-Dist: boto3>=1.34; extra == "dev"
+Requires-Dist: wandb>=0.18; extra == "dev"
+
+# Orchestral Quickstart
+
+Install the client, sign in, enroll a robot, choose a model from the Models section in the sidebar, and predict an action chunk.
+
+## 1. Install and sign in
+
+Create an environment and install the client:
+
+```text your computer
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install orchestral-client
+```
+
+Sign in and confirm the active account:
+
+```bash your computer
+orc login
+orc whoami
+```
+
+## 2. Enroll the robot
+
+Install the client on the robot computer:
+
+```text robot computer
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install orchestral-client
+```
+
+Request enrollment from the robot computer. No user login is needed there. This command prints a short-lived code and waits while an organization administrator approves it:
+
+```bash robot computer
+orc agent install --name robot-1
+```
+
+From an organization administrator's signed-in computer, replace `CODE` with the code printed by the waiting command and approve it:
+
+```bash your computer
+orc robot approve CODE
+```
+
+The waiting command finishes on the robot computer and saves its robot-scoped credential for predictions.
+
+Check that the robot is enrolled:
+
+```bash your computer
+orc robot list
+```
+
+## 3. Choose and deploy a model
+
+This walkthrough uses Pi 0.5. Inspect its checkpoint, import it, then deploy the imported model to the enrolled robot. Keep the `mdl_...` ID printed by import and the `dep_...` ID printed by deploy. Import waits for target preparation to finish before returning. To return while preparation continues, pass `--no-wait`; check progress with `orc model status MODEL_ID` or wait later with `orc model wait MODEL_ID`. For private or gated checkpoints, [connect your Hugging Face account](https://api.orchestrallabs.ai/account/huggingface) first and accept the model's access terms on Hugging Face.
+
+```text your computer
+orc model inspect hf://npow/pi05-yam-red-cap-full-7500
+orc model import hf://npow/pi05-yam-red-cap-full-7500
+MODEL_ID=mdl_123456789abc
+orc model deploy "$MODEL_ID" --robot robot-1 --wait
+```
+
+Replace the example `mdl_...` value with the ID returned by import. Pi 0.5 expects `middle`, `left`, and `right` as RGB `uint8` frames of shape `(224, 224, 3)`, plus `state` as `float32` with shape `(7,)`; it returns `actions` with shape `(15, 7)`. See the [Pi 0.5 model guide](/models/pi05) for the full contract and an SDK example.
+
+The downloaded prediction script reads the deployed model's input contract and creates Pi 0.5's three `(224, 224, 3)` RGB camera frames and `(7,)` state without requiring you to rename or reshape them.
+
+## 4. Predict an action chunk
+
+On the robot computer, download `quickstart_predict.py` and run it with the deployment ID printed by the Pi 0.5 deploy command. It generates sample Pi 0.5 inputs with state values normalized to `[-1, 1]`.
+
+```text robot computer
+wget -O quickstart_predict.py https://api.orchestrallabs.ai/quickstart_predict.py
+DEPLOYMENT_ID=dep_123456789abc
+python quickstart_predict.py "$DEPLOYMENT_ID"
+```
+
+Set `DEPLOYMENT_ID` to the `dep_...` ID printed by the deploy command. The script reads the deployment's input contract and sends generated sample frames and state, so it can confirm prediction works before you connect `inputs` to your robot's cameras and state. Connect the script's `inputs` to those live sources for robot operation.
+
+When OTLP is configured, the script prints the Tempo trace ID, whether Grafana returned the trace, and the p50 latency breakdown for encoding, wire time, decoding, queueing, inference, and total round trip.
+
+## 5. Stop the deployment
+
+When finished, stop the deployment from your computer. Set `DEPLOYMENT_ID` to the ID from step 3:
+
+```text your computer
+DEPLOYMENT_ID=dep_123456789abc
+orc deployment stop "$DEPLOYMENT_ID"
+```

orchestral_client-0.1.0/docs/quickstart.md

@@ -0,0 +1,88 @@
+# Orchestral Quickstart
+
+Install the client, sign in, enroll a robot, choose a model from the Models section in the sidebar, and predict an action chunk.
+
+## 1. Install and sign in
+
+Create an environment and install the client:
+
+```text your computer
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install orchestral-client
+```
+
+Sign in and confirm the active account:
+
+```bash your computer
+orc login
+orc whoami
+```
+
+## 2. Enroll the robot
+
+Install the client on the robot computer:
+
+```text robot computer
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install orchestral-client
+```
+
+Request enrollment from the robot computer. No user login is needed there. This command prints a short-lived code and waits while an organization administrator approves it:
+
+```bash robot computer
+orc agent install --name robot-1
+```
+
+From an organization administrator's signed-in computer, replace `CODE` with the code printed by the waiting command and approve it:
+
+```bash your computer
+orc robot approve CODE
+```
+
+The waiting command finishes on the robot computer and saves its robot-scoped credential for predictions.
+
+Check that the robot is enrolled:
+
+```bash your computer
+orc robot list
+```
+
+## 3. Choose and deploy a model
+
+This walkthrough uses Pi 0.5. Inspect its checkpoint, import it, then deploy the imported model to the enrolled robot. Keep the `mdl_...` ID printed by import and the `dep_...` ID printed by deploy. Import waits for target preparation to finish before returning. To return while preparation continues, pass `--no-wait`; check progress with `orc model status MODEL_ID` or wait later with `orc model wait MODEL_ID`. For private or gated checkpoints, [connect your Hugging Face account](https://api.orchestrallabs.ai/account/huggingface) first and accept the model's access terms on Hugging Face.
+
+```text your computer
+orc model inspect hf://npow/pi05-yam-red-cap-full-7500
+orc model import hf://npow/pi05-yam-red-cap-full-7500
+MODEL_ID=mdl_123456789abc
+orc model deploy "$MODEL_ID" --robot robot-1 --wait
+```
+
+Replace the example `mdl_...` value with the ID returned by import. Pi 0.5 expects `middle`, `left`, and `right` as RGB `uint8` frames of shape `(224, 224, 3)`, plus `state` as `float32` with shape `(7,)`; it returns `actions` with shape `(15, 7)`. See the [Pi 0.5 model guide](/models/pi05) for the full contract and an SDK example.
+
+The downloaded prediction script reads the deployed model's input contract and creates Pi 0.5's three `(224, 224, 3)` RGB camera frames and `(7,)` state without requiring you to rename or reshape them.
+
+## 4. Predict an action chunk
+
+On the robot computer, download `quickstart_predict.py` and run it with the deployment ID printed by the Pi 0.5 deploy command. It generates sample Pi 0.5 inputs with state values normalized to `[-1, 1]`.
+
+```text robot computer
+wget -O quickstart_predict.py https://api.orchestrallabs.ai/quickstart_predict.py
+DEPLOYMENT_ID=dep_123456789abc
+python quickstart_predict.py "$DEPLOYMENT_ID"
+```
+
+Set `DEPLOYMENT_ID` to the `dep_...` ID printed by the deploy command. The script reads the deployment's input contract and sends generated sample frames and state, so it can confirm prediction works before you connect `inputs` to your robot's cameras and state. Connect the script's `inputs` to those live sources for robot operation.
+
+When OTLP is configured, the script prints the Tempo trace ID, whether Grafana returned the trace, and the p50 latency breakdown for encoding, wire time, decoding, queueing, inference, and total round trip.
+
+## 5. Stop the deployment
+
+When finished, stop the deployment from your computer. Set `DEPLOYMENT_ID` to the ID from step 3:
+
+```text your computer
+DEPLOYMENT_ID=dep_123456789abc
+orc deployment stop "$DEPLOYMENT_ID"
+```

orchestral_client-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orchestral-client"
+version = "0.1.0"
+description = "Orchestral Labs — Real-time robotics & VLA model platform"
+readme = "docs/quickstart.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.26",
+    "httpx>=0.27",
+    "msgpack>=1.0.5",
+    "cryptography>=42.0",
+    "PyJWT>=2.8",
+    "omegaconf>=2.3.0",
+    "aioquic>=1.2.0",
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+    # Session.predict() defaults to H.264 for camera inputs.
+    "av>=12.0",
+    "pillow>=10.0",
+]
+
+[project.optional-dependencies]
+cloud = ["boto3>=1.34"]
+exp = ["wandb>=0.18"]
+benchmark = ["boto3>=1.34", "wandb>=0.18"]
+dev = ["pytest>=8.0,<9", "ruff>=0.6", "tach>=0.35", "boto3>=1.34", "wandb>=0.18"]
+
+[project.scripts]
+orc = "orchestral.ops.cli:main"
+orchestral = "orchestral.ops.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["orchestral*"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+orchestral = [
+    "entrypoint.sh",
+    "client/_native/TAILSCALE-LICENSE.txt",
+    "client/_native/*/tailscaled",
+    "client/_native/*/tailscale",
+    "client/_native/*/orchestral-action-session-quic",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "e2e: end-to-end journey or live infrastructure test; run on demand",
+    "gcp_e2e: opt-in real GCP/GKE quickstart and prediction test",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

orchestral_client-0.1.0/setup.cfg

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

orchestral_client-0.1.0/setup.py

@@ -0,0 +1,65 @@
+"""Setuptools wheel tags for platform-specific native client payloads."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, "src")
+
+from setuptools import Distribution, setup
+from wheel.bdist_wheel import bdist_wheel
+
+
+class NativeClientDistribution(Distribution):
+    def has_ext_modules(self) -> bool:
+        return True
+
+
+class NativeClientWheel(bdist_wheel):
+    def finalize_options(self) -> None:
+        super().finalize_options()
+        tag = os.environ.get("ORC_WHEEL_PLATFORM_TAG")
+        if not tag:
+            # Setuptools asks bdist_wheel for metadata while preparing editable installs.
+            # Keep that path lightweight; enforce the platform payload when a wheel is run.
+            return
+        target = {
+            "manylinux_2_28_x86_64": "linux_amd64",
+            "manylinux_2_28_aarch64": "linux_arm64",
+            "macosx_13_0_arm64": "macos_arm64",
+        }.get(tag)
+        if target is None:
+            raise RuntimeError(f"unsupported orchestral-client wheel platform tag {tag!r}")
+        native_directory = Path("src/orchestral/client/_native") / target
+        required = (
+            "tailscaled",
+            "tailscale",
+            "orchestral-action-session-quic",
+        )
+        missing = [name for name in required if not (native_directory / name).is_file()]
+        if missing:
+            raise RuntimeError(
+                f"platform wheel payload is incomplete in {native_directory}: {', '.join(missing)}"
+            )
+        self.root_is_pure = False
+        self.plat_name = tag
+        self.plat_name_supplied = True
+
+    def get_tag(self) -> tuple[str, str, str]:
+        tag = os.environ.get("ORC_WHEEL_PLATFORM_TAG")
+        if tag is None:
+            return super().get_tag()
+        return "py3", "none", tag
+
+    def run(self) -> None:
+        if not os.environ.get("ORC_WHEEL_PLATFORM_TAG"):
+            raise RuntimeError(
+                "set ORC_WHEEL_PLATFORM_TAG and run `make client-native-binaries` "
+                "before building an orchestral-client wheel"
+            )
+        super().run()
+
+
+setup(distclass=NativeClientDistribution, cmdclass={"bdist_wheel": NativeClientWheel})

orchestral_client-0.1.0/src/orchestral/__init__.py

@@ -0,0 +1,108 @@
+"""Orchestral Labs — Real-time robotics & VLA platform.
+
+Lazy top-level exports keep `import orchestral` under 5ms.
+Domain packages:
+  - `orchestral.core`:      Contracts, plugin registry, and wire protocol (`contracts`, `registry`, `wire`)
+  - `orchestral.runtime`:   Worker data-plane runtime, CAS hydration & custom kernels (`serve`, `cas`, `kernels`)
+  - `orchestral.control`:   Cloud control plane, placement engine, auth/RBAC, state store & telemetry
+  - `orchestral.plugins`:   Hardware accelerators, profiles, solvers, providers, models & simulators
+  - `orchestral.client`:    Customer Python SDK (`sdk`)
+  - `orchestral.ops`:       Operator CLI, model onboarding, benchmarks & closed-loop evaluation
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ConnectGrant",
+    "Deployment",
+    "IOSpec",
+    "Orchestral",
+    "PluginKind",
+    "SensorModality",
+    "SensorSpec",
+    "Session",
+    "StepTimings",
+    "client",
+    "connect",
+    "control",
+    "core",
+    "deploy",
+    "model",
+    "offers",
+    "ops",
+    "plugins",
+    "register",
+    "runtime",
+    "session",
+    "simulator",
+    "usage",
+    "wire",
+]
+
+if TYPE_CHECKING:
+    from orchestral import client, control, core, ops, plugins, runtime
+    from orchestral.client.sdk import (
+        Deployment,
+        Orchestral,
+        Session,
+        connect,
+        deploy,
+        offers,
+        session,
+        usage,
+    )
+    from orchestral.core import wire
+    from orchestral.core.contracts import (
+        IOSpec,
+        PluginKind,
+        SensorModality,
+        SensorSpec,
+        StepTimings,
+    )
+    from orchestral.core.grants import ConnectGrant
+    from orchestral.core.registry import model, register, simulator
+
+
+def __getattr__(name: str) -> Any:
+    if name in {"core", "runtime", "control", "plugins", "client", "ops"}:
+        import importlib
+
+        return importlib.import_module(f"orchestral.{name}")
+    if name == "wire":
+        from orchestral.core import wire
+
+        return wire
+    if name in {"register", "model", "simulator"}:
+        from orchestral.core import registry
+
+        return getattr(registry, name)
+    if name in {"PluginKind", "SensorModality", "SensorSpec"}:
+        from orchestral.core import contracts
+
+        return getattr(contracts, name)
+    if name == "ConnectGrant":
+        from orchestral.core.grants import ConnectGrant
+
+        return ConnectGrant
+    if name in {"IOSpec", "StepTimings"}:
+        from orchestral.core import contracts
+
+        return getattr(contracts, name)
+    if name in {
+        "Orchestral",
+        "Deployment",
+        "Session",
+        "connect",
+        "deploy",
+        "session",
+        "offers",
+        "usage",
+    }:
+        from orchestral.client import sdk
+
+        return getattr(sdk, name)
+    raise AttributeError(f"module 'orchestral' has no attribute {name!r}")

orchestral_client-0.1.0/src/orchestral/client/__init__.py

@@ -0,0 +1,39 @@
+"""Customer Python SDK (`orchestral.client`)."""
+
+from __future__ import annotations
+
+from orchestral.client.sdk import (
+    Deployment,
+    InputFeature,
+    Orchestral,
+    PolicyHandle,
+    PredictionResult,
+    Session,
+    clear_credentials,
+    connect,
+    deploy,
+    get_default_cloud,
+    load_credentials,
+    offers,
+    save_credentials,
+    session,
+    usage,
+)
+
+__all__ = [
+    "Deployment",
+    "InputFeature",
+    "Orchestral",
+    "PolicyHandle",
+    "PredictionResult",
+    "Session",
+    "clear_credentials",
+    "connect",
+    "deploy",
+    "get_default_cloud",
+    "load_credentials",
+    "offers",
+    "save_credentials",
+    "session",
+    "usage",
+]

orchestral_client-0.1.0/src/orchestral/client/_native/TAILSCALE-LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2020 Tailscale Inc & contributors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

orchestral_client-0.1.0/src/orchestral/client/_native/linux_amd64/tailscaled

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: orchestral_client-0.1.0/src/orchestral/client/_native/linux_amd64/tailscaled
+size: 41151287 bytes
+sha256: f27f3746fa9a4807749bc868938949d328f8c38890ace0906966eb3f655ab240