servo-client 0.1.0__py3-none-any.whl

servo/__init__.py

@@ -0,0 +1,126 @@
+"""Servo SDK — robot AI, made usable.
+
+The public surface is one robot policy operations API:
+- **Identity**: ``Model``, ``Checkpoint`` (which weights).
+- **Hosting**: ``HostedDeployment``, ``EdgeExport`` (where it runs; never routes).
+- **Execution**: ``Policy`` (``.act``), ``World`` (``.rollout``), ``Session`` (the control loop).
+
+Everything is reached from ``servo.Servo``. ``servo.templates`` carries embodiment helpers;
+``servo.errors`` carries the full typed error surface. Modules can be used independently or
+composed through the same policy and embodiment resources. Upstream frameworks are exposed as
+integration adapters, not as application-facing control surfaces.
+"""
+
+from servo import errors, templates  # noqa: F401
+from servo.client import Servo
+from servo.constants import (
+    ActionSpace,
+    Compute,
+    PolicyAdapter,
+    RobotType,
+)
+from servo.errors import (
+    ActionSpaceIncompatible,
+    CapabilityNotAvailable,
+    DependencyUnavailable,
+    EmbodimentUnsupported,
+    ExternalDependencyError,
+    LicenseBlocked,
+    ModelNotServable,
+    NotFound,
+    NotHydrated,
+    NotReady,
+    ObservationInvalid,
+    PaymentRequired,
+    ServoError,
+    SurfaceUnsupported,
+    Unauthorized,
+    ValidationError,
+)
+from servo.execution.chunked_loop import ChunkedRunReport, ChunkRecord
+from servo.execution.policy import Policy
+from servo.execution.session import Session
+from servo.execution.world import World
+from servo.hardware import LocalRobot as ConnectedRobot
+from servo.hardware import RobotRun
+from servo.resources.dataset import Dataset, DatasetInspection
+from servo.resources.deployment import EdgeExport, HostedDeployment
+from servo.resources.embodiment import Embodiment as Robot
+from servo.resources.hf_import import ModelImport, ModelInspection
+from servo.resources.job import EvalResult, FineTuneResult, Job, SynthDataResult
+from servo.resources.model import Checkpoint, CompatibilityReport, Model, RuntimeBinding
+from servo.resources.adapter import Adapter, RuntimeEntry
+from servo.resources.billing import BillingBalance, CheckoutSession
+from servo.resources.secret import Secret
+from servo.resources.upload import ModelUpload
+from servo.resources.usage import Grant, UsageSummary
+from servo.types import ActionPrediction, FrameRef, Observation, RolloutPrediction
+
+__all__ = [
+    # Client + helpers
+    "Servo",
+    "templates",
+    "errors",
+    "Observation",
+    "ActionSpace",
+    "Compute",
+    "PolicyAdapter",
+    "RobotType",
+    # Identity
+    "Model",
+    "Checkpoint",
+    "Robot",
+    "ConnectedRobot",
+    "Adapter",
+    "RuntimeEntry",
+    # Data + import lifecycle
+    "Dataset",
+    "DatasetInspection",
+    "ModelInspection",
+    "ModelImport",
+    # Hosting
+    "HostedDeployment",
+    "EdgeExport",
+    # Jobs + results
+    "Job",
+    "FineTuneResult",
+    "EvalResult",
+    "SynthDataResult",
+    # Execution
+    "Policy",
+    "World",
+    "Session",
+    "RobotRun",
+    "ChunkedRunReport",
+    "ChunkRecord",
+    # Predictions
+    "ActionPrediction",
+    "RolloutPrediction",
+    "FrameRef",
+    # Operational
+    "UsageSummary",
+    "Grant",
+    "CompatibilityReport",
+    "RuntimeBinding",
+    "BillingBalance",
+    "CheckoutSession",
+    "Secret",
+    "ModelUpload",
+    # Errors (also under servo.errors)
+    "NotHydrated",
+    "NotReady",
+    "ServoError",
+    "SurfaceUnsupported",
+    "CapabilityNotAvailable",
+    "LicenseBlocked",
+    "EmbodimentUnsupported",
+    "ActionSpaceIncompatible",
+    "ExternalDependencyError",
+    "DependencyUnavailable",
+    "ValidationError",
+    "NotFound",
+    "Unauthorized",
+    "ModelNotServable",
+    "ObservationInvalid",
+    "PaymentRequired",
+]

servo/client.py

@@ -0,0 +1,236 @@
+"""Servo SDK client (006 redesign).
+
+The ``Servo`` client is the single entry point: thin uniform namespaces (``sv.models`` etc.), the
+execution factories (``sv.policy``/``sv.world``/``sv.session``), and ``sv.usage()``. Transport is
+unchanged — HTTP to a running control plane by default, or the in-process ASGI ``app=`` test client.
+
+Robot/embodiment normalization (FR-013/D8): every ``robot=`` accepts a registered robot handle,
+id, or name and is resolved to an embodiment id via ``_embodiment_id`` before any request;
+unknown/ambiguous names raise client-side.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from servo_contracts.errors import (
+    ActionSpaceIncompatible,
+    CapabilityNotAvailable,
+    DependencyUnavailable,
+    EmbodimentUnsupported,
+    ExternalDependencyError,
+    LicenseBlocked,
+    ModelNotServable,
+    NotFound,
+    ObservationInvalid,
+    PaymentRequired,
+    ServoError,
+    SurfaceUnsupported,
+    Unauthorized,
+)
+from servo.errors import NotReady, ValidationError
+from servo.namespaces.datasets import Datasets
+from servo.namespaces.adapters import Adapters
+from servo.namespaces.billing import Billing
+from servo.namespaces.deployments import Deployments
+from servo.namespaces.robots import Robots
+from servo.namespaces.jobs import Jobs
+from servo.namespaces.licenses import Licenses
+from servo.namespaces.models import Models
+from servo.namespaces.secrets import Secrets
+from servo.resources.usage import UsageSummary
+
+if TYPE_CHECKING:  # pragma: no cover
+    from servo.execution.policy import Policy
+    from servo.execution.session import Session
+    from servo.execution.world import World
+    from servo.resources.embodiment import Embodiment
+    from servo.resources.model import Checkpoint, Model
+
+_ERROR_BY_CODE = {
+    "ObservationInvalid": ObservationInvalid,
+    "ActionSpaceIncompatible": ActionSpaceIncompatible,
+    "ModelNotServable": ModelNotServable,
+    "EmbodimentUnsupported": EmbodimentUnsupported,
+    "LicenseBlocked": LicenseBlocked,
+    "SurfaceUnsupported": SurfaceUnsupported,
+    "CapabilityNotAvailable": CapabilityNotAvailable,
+    "ExternalDependencyError": ExternalDependencyError,
+    "DependencyUnavailable": DependencyUnavailable,
+    "ValidationError": ValidationError,
+    "NotFound": NotFound,
+    "NotReady": NotReady,
+    "Unauthorized": Unauthorized,
+    "PaymentRequired": PaymentRequired,
+}
+
+
+def _raise_for_error(resp: httpx.Response) -> dict[str, Any]:
+    if resp.status_code < 400:
+        return resp.json() if resp.content else {}
+    try:
+        body = resp.json()
+    except Exception:  # noqa: BLE001
+        resp.raise_for_status()
+        raise
+    code = body.get("code", "ServoError")
+    cls = _ERROR_BY_CODE.get(code, ServoError)
+    raise cls(body.get("message", "error"), detail=body.get("detail"))
+
+
+class Servo:
+    """Typed Servo client. Pass ``app=`` to drive the ASGI app in-process (hermetic tests)."""
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8000",
+        api_key: str = "dev",
+        app: Any | None = None,
+        http: Any | None = None,
+        timeout: float | None = 3600.0,
+    ):
+        self.api_key = api_key
+        headers = {"Authorization": f"Bearer {api_key}"}
+        if http is not None:
+            self._http = http
+            self._http.headers.update(headers)
+        elif app is not None:
+            from starlette.testclient import TestClient
+
+            self._http = TestClient(app)
+            self._http.headers.update(headers)
+        else:
+            # Some control-plane calls block on real GPU work (a synchronous finetune POST runs the
+            # Modal job inline and only returns when it finishes — minutes, not seconds). httpx's
+            # 5s default read-timeout would abort those mid-flight, so the SDK defaults to a generous
+            # 1h timeout. Override per-client with ``timeout=`` (``None`` disables it entirely).
+            self._http = httpx.Client(base_url=base_url, headers=headers, timeout=timeout)
+
+        # Namespaces (thin, uniform — all return typed handles).
+        self.robots = Robots(self)
+        self.adapters = Adapters(self)
+        self.models = Models(self)
+        self.datasets = Datasets(self)
+        self.data = self.datasets
+        self.deployments = Deployments(self)
+        self.jobs = Jobs(self)
+        self.licenses = Licenses(self)
+        self.billing = Billing(self)
+        self.secrets = Secrets(self)
+
+        self._embodiment_cache: dict[str, str] | None = None
+
+    # ---- execution factories ----
+    def policy(
+        self,
+        model_or_checkpoint: "Any",
+        embodiment: "Any",
+        *,
+        instruction: str | None = None,
+        deployment_id: str | None = None,
+        advisory: str | None = None,
+    ) -> "Policy":
+        """Bind a model/checkpoint + embodiment -> a :class:`Policy` (single-shot ``.act``)."""
+        from servo.execution.policy import Policy
+        from servo.resources.model import Checkpoint, Model
+
+        ref = (
+            model_or_checkpoint.id
+            if isinstance(model_or_checkpoint, (Model, Checkpoint))
+            else model_or_checkpoint
+        )
+        local_robot = embodiment if hasattr(embodiment, "run") and hasattr(embodiment, "embodiment") else None
+        emb_id = self._embodiment_id(embodiment)
+        return Policy(
+            self, ref, emb_id,
+            instruction=instruction, deployment_id=deployment_id, advisory=advisory,
+            robot=local_robot,
+        )
+
+    def world(self, model: "Any", embodiment: "Any" = None) -> "World":
+        """Bind a world model -> a :class:`World` (``.rollout``)."""
+        from servo.execution.world import World
+        from servo.resources.model import Checkpoint, Model
+
+        ref = model.id if isinstance(model, (Model, Checkpoint)) else model
+        emb_id = self._embodiment_id(embodiment) if embodiment is not None else None
+        return World(self, ref, embodiment_id=emb_id)
+
+    def session(self, policy: "Policy") -> "Session":
+        """Open the real-robot control loop for a :class:`Policy` -> a :class:`Session` (context mgr)."""
+        from servo.execution.session import Session
+
+        return Session(self, policy)
+
+    def usage(self) -> UsageSummary:
+        """Org usage telemetry summary -> a typed :class:`UsageSummary`."""
+        return UsageSummary(self._get("/v1/usage"))
+
+    # ---- embodiment normalization (FR-013 / D8) ----
+    def _embodiment_id(self, embodiment: "Any") -> str:
+        """Normalize ``Robot handle | id | name`` -> an embodiment id."""
+        from servo.resources.embodiment import Embodiment
+
+        if isinstance(embodiment, Embodiment):
+            return embodiment.id
+        local_embodiment = getattr(embodiment, "embodiment", None)
+        if isinstance(local_embodiment, Embodiment):
+            return local_embodiment.id
+        if not isinstance(embodiment, str):
+            raise ValidationError(
+                f"robot must be a Robot | id | name, got {type(embodiment).__name__}",
+                detail={"value": repr(embodiment)},
+            )
+        # An id passed directly (registered embodiment ids are emb_...) — accept as-is.
+        if embodiment.startswith("emb_"):
+            return embodiment
+        cache = self._embodiment_cache_get()
+        # id present in the cache (covers non-prefixed ids).
+        if embodiment in cache.values():
+            return embodiment
+        matches = [eid for name, eid in cache.items() if name == embodiment]
+        if len(matches) == 1:
+            return matches[0]
+        if len(matches) > 1:
+            raise ValidationError(
+                f"embodiment name '{embodiment}' is ambiguous ({len(matches)} matches)",
+                detail={"name": embodiment, "matches": matches},
+            )
+        # Unknown name: refresh once in case the cache is stale, then fail closed.
+        self._invalidate_embodiment_cache()
+        cache = self._embodiment_cache_get()
+        if embodiment in cache.values():
+            return embodiment
+        matches = [eid for name, eid in cache.items() if name == embodiment]
+        if len(matches) == 1:
+            return matches[0]
+        if len(matches) > 1:
+            raise ValidationError(
+                f"embodiment name '{embodiment}' is ambiguous ({len(matches)} matches)",
+                detail={"name": embodiment, "matches": matches},
+            )
+        raise ValidationError(
+            f"unknown robot '{embodiment}'; register it or pass a Robot handle",
+            detail={"name": embodiment},
+        )
+
+    def _embodiment_cache_get(self) -> dict[str, str]:
+        if self._embodiment_cache is None:
+            data = self._get("/v1/embodiments")["embodiments"]
+            self._embodiment_cache = {e["name"]: e["id"] for e in data}
+        return self._embodiment_cache
+
+    def _invalidate_embodiment_cache(self) -> None:
+        self._embodiment_cache = None
+
+    # ---- transport ----
+    def _get(self, path: str, params: dict | None = None) -> Any:
+        return _raise_for_error(self._http.get(path, params=params))
+
+    def _post(self, path: str, body: Any) -> Any:
+        return _raise_for_error(self._http.post(path, json=body))
+
+    def _delete(self, path: str) -> Any:
+        return _raise_for_error(self._http.delete(path))

servo/constants.py

@@ -0,0 +1,79 @@
+"""Public constants for Servo's typed SDK surface.
+
+The constants are ``str`` enums, so callers can pass them anywhere the SDK accepts a string
+while still getting autocomplete and a finite set of Servo-owned values.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class RobotType(StrEnum):
+    """Built-in robot types with Servo observation/action schemas."""
+
+    SO101 = "so101"
+    ALOHA = "aloha"
+    LIBERO = "libero"
+    DROID = "droid"
+
+
+class ActionSpace(StrEnum):
+    JOINT_POSITION = "joint_position"
+    JOINT_VELOCITY = "joint_velocity"
+    EEF_DELTA = "eef_delta"
+    EEF_ABSOLUTE = "eef_absolute"
+
+
+class PolicyAdapter(StrEnum):
+    """Servo policy integrations that inspect, validate, train, and serve checkpoints."""
+
+    OPENPI = "openpi"
+    OPENVLA = "openvla"
+    SMOLVLA = "smolvla"
+    GROOT = "gr00t"
+    MOLMOACT2 = "molmoact2"
+    STARVLA = "starvla"
+    VLA0 = "vla0"
+    HY_EMBODIED = "hy-embodied"
+    LINGBOT_VLA = "lingbot-vla"
+    X_VLA = "x-vla"
+    RDT = "rdt"
+    OCTO = "octo"
+    CUSTOM = "custom"
+
+    @classmethod
+    def native(cls) -> tuple["PolicyAdapter", ...]:
+        return (cls.OPENPI, cls.OPENVLA, cls.SMOLVLA, cls.GROOT)
+
+    @classmethod
+    def external(cls) -> tuple["PolicyAdapter", ...]:
+        return (
+            cls.MOLMOACT2,
+            cls.STARVLA,
+            cls.VLA0,
+            cls.HY_EMBODIED,
+            cls.LINGBOT_VLA,
+            cls.X_VLA,
+            cls.RDT,
+            cls.OCTO,
+            cls.CUSTOM,
+        )
+
+    @classmethod
+    def all(cls) -> tuple["PolicyAdapter", ...]:
+        return cls.native() + cls.external()
+
+
+class Compute(StrEnum):
+    """Compute substrates Servo can provision for hosted deployment."""
+
+    MODAL = "modal"
+
+
+__all__ = [
+    "ActionSpace",
+    "Compute",
+    "PolicyAdapter",
+    "RobotType",
+]