sidekick-sdk 0.1.0__py3-none-any.whl

sidekick_sdk/__init__.py

@@ -0,0 +1,641 @@
+"""Sidekick Python client.
+
+    from sidekick_sdk import Sidekick
+
+    sk = Sidekick(api_key="sk-sidekick-...")
+
+    # Roll the world forward
+    out = sk.predict(
+        model="sidekick/auto:manipulation",
+        observations=[sk.observation(image_url=url)],
+        instruction="pick up the red block",
+        horizon=16,
+    )
+
+    # Ask what to do next
+    act = sk.act(
+        model="sidekick/auto:vla",
+        observations=[sk.observation(image_url=url)],
+        instruction="put the spoon on the towel",
+        action_space="ee_delta_6d_grip",
+    )
+    robot.execute(act.action.steps)
+
+Designed for a control loop: the synchronous client keeps one pooled
+connection, `stream_predict` yields frames as they arrive, and every response
+carries `route` so you can see which model and provider actually served you.
+"""
+from __future__ import annotations
+
+import base64
+import collections
+import json
+import os
+import pathlib
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Iterator
+
+import httpx
+
+__all__ = ["Sidekick", "SidekickError", "UnsafeResponse", "ActionStream",
+           "Prediction", "Action", "Grounding", "Evaluation"]
+
+__version__ = "0.1.0"
+
+# Where the service actually is. This used to read
+# "https://api.sidekickrobotics.com", a host that is neither the right domain
+# nor a subdomain that resolves, so `Sidekick(api_key=...)` with no base_url
+# failed for every developer who took the default. Overridable by environment so
+# a customer pointing at a private deployment does not have to pass it at every
+# construction site.
+DEFAULT_BASE_URL = os.environ.get(
+    "SIDEKICK_ORIGIN", "https://www.sidekickrobotics.ai/api")
+
+
+class SidekickError(RuntimeError):
+    def __init__(self, status: int, body: Any) -> None:
+        detail = body
+        if isinstance(body, dict):
+            detail = body.get("detail", body)
+            if isinstance(detail, dict):
+                detail = detail.get("error", detail)
+        self.status = status
+        self.body = detail
+        msg = detail.get("message") if isinstance(detail, dict) else str(detail)
+        self.code = detail.get("code") if isinstance(detail, dict) else None
+        super().__init__(f"[{status}] {msg}")
+
+
+@dataclass
+class Prediction:
+    id: str
+    model: str
+    frames: list[dict]
+    route: dict
+    usage: dict
+    latents_url: str | None = None
+
+    def save_frames(self, directory: str | pathlib.Path, prefix: str = "frame") -> list[pathlib.Path]:
+        """Write base64 frames to disk. Frames returned as URLs are skipped."""
+        d = pathlib.Path(directory)
+        d.mkdir(parents=True, exist_ok=True)
+        out = []
+        for i, f in enumerate(self.frames):
+            if not f.get("b64"):
+                continue
+            p = d / f"{prefix}_{i:04d}.png"
+            p.write_bytes(base64.b64decode(f["b64"]))
+            out.append(p)
+        return out
+
+
+@dataclass
+class Action:
+    id: str
+    model: str
+    action: dict
+    route: dict
+    usage: dict
+    confidence: float | None = None
+    predicted_frames: list[dict] | None = None
+
+    @property
+    def steps(self) -> list[list[float]]:
+        return self.action["steps"]
+
+    @property
+    def space(self) -> str:
+        return self.action["space"]
+
+
+@dataclass
+class Grounding:
+    """Where things are, in image coordinates.
+
+    Deliberately not an Action. `points` and `boxes` are normalised 0 to 1 in
+    image space, and a caller that feeds them to an actuator is commanding
+    pixels as joint targets. Convert through your own camera model first.
+    """
+
+    id: str
+    model: str
+    route: dict
+    usage: dict
+    points: list[dict]
+    boxes: list[dict]
+    raw: str | None = None
+
+    def labels(self) -> list[str]:
+        seen = {p.get("label") for p in self.points} | {b.get("label") for b in self.boxes}
+        return sorted(x for x in seen if x)
+
+
+@dataclass
+class Evaluation:
+    id: str
+    model: str
+    status: str
+    scenario: str
+    results: dict | None
+    usage: dict
+    error: str | None = None
+
+
+class Sidekick:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 120.0,
+        max_retries: int = 2,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers={"authorization": f"Bearer {api_key}", "content-type": "application/json"},
+            transport=httpx.HTTPTransport(retries=max_retries),
+        )
+
+    # ------------------------------------------------------------------
+    @staticmethod
+    def observation(
+        *,
+        image_url: str | None = None,
+        image_b64: str | None = None,
+        image_path: str | pathlib.Path | None = None,
+        camera: str = "primary",
+        cameras: dict[str, str] | None = None,
+        depth_url: str | None = None,
+        proprio: list[float] | None = None,
+        tactile: list[float] | None = None,
+        intrinsics: list[float] | None = None,
+    ) -> dict:
+        """Build one observation from a URL, raw base64, a local path, or a rig.
+
+        `cameras` is the multi-view form: a mapping of camera name to URL, local
+        path or base64. It exists because the single-camera helper was a trap for
+        exactly the checkpoints most people reach for. pi0.5 on ALOHA wants four
+        named views, and a policy trained with a wrist camera second produces
+        confident nonsense if the streams are swapped, with nothing in the
+        response to say so. Names must match what the checkpoint declares.
+
+            obs = sk.observation(
+                cameras={"cam_high": "frames/high.jpg",
+                         "cam_low": "frames/low.jpg",
+                         "cam_left_wrist": "frames/lw.jpg",
+                         "cam_right_wrist": "frames/rw.jpg"},
+                proprio=joint_positions)
+        """
+        if cameras:
+            if image_url or image_b64 or image_path:
+                raise ValueError("pass `cameras` or a single image, not both")
+            obs = {"frames": [dict({"camera": name}, **_frame_source(v))
+                              for name, v in cameras.items()]}
+            if proprio is not None:
+                obs["proprio"] = proprio
+            if tactile is not None:
+                obs["tactile"] = tactile
+            return obs
+        if image_path is not None:
+            image_b64 = base64.b64encode(pathlib.Path(image_path).read_bytes()).decode()
+        if bool(image_url) == bool(image_b64):
+            raise ValueError("provide exactly one of image_url, image_b64, "
+                             "image_path or cameras")
+        obs: dict[str, Any] = {
+            "frames": [{"camera": camera, "url": image_url, "b64": image_b64,
+                        "intrinsics": intrinsics}]
+        }
+        if depth_url:
+            obs["depth"] = [{"camera": camera, "url": depth_url}]
+        if proprio is not None:
+            obs["proprio"] = proprio
+        if tactile is not None:
+            obs["tactile"] = tactile
+        return obs
+
+    # ------------------------------------------------------------------
+    def _post(self, path: str, payload: dict) -> dict:
+        r = self._client.post(f"{self.base_url}{path}", json=payload)
+        if r.status_code >= 400:
+            raise SidekickError(r.status_code, _safe_json(r))
+        return r.json()
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        r = self._client.get(f"{self.base_url}{path}", params=params)
+        if r.status_code >= 400:
+            raise SidekickError(r.status_code, _safe_json(r))
+        return r.json()
+
+    # ------------------------------------------------------------------
+    def predict(
+        self,
+        *,
+        model: str,
+        observations: list[dict],
+        actions: dict | None = None,
+        instruction: str | None = None,
+        horizon: int = 16,
+        fps: int = 10,
+        resolution: str | None = None,
+        models: list[str] | None = None,
+        preference: str | None = None,
+        provider: dict | None = None,
+        seed: int | None = None,
+        return_latents: bool = False,
+        **kwargs: Any,
+    ) -> Prediction:
+        body = _clean({
+            "model": model, "models": models, "observations": observations,
+            "actions": actions, "instruction": instruction, "horizon": horizon,
+            "fps": fps, "resolution": resolution, "provider": provider or {},
+            "preference": preference, "seed": seed, "return_latents": return_latents, **kwargs,
+        })
+        d = self._post("/v1/predict", body)
+        return Prediction(id=d["id"], model=d["model"], frames=d["frames"],
+                          route=d["route"], usage=d["usage"], latents_url=d.get("latents_url"))
+
+    def stream_predict(self, **kwargs: Any) -> Iterator[tuple[str, dict]]:
+        """Yield (event, payload) as the model generates. Events: route, frame,
+        done, error, end."""
+        body = _clean({"horizon": 16, "fps": 10, "provider": {}, **kwargs})
+        with self._client.stream("POST", f"{self.base_url}/v1/predict/stream", json=body) as r:
+            if r.status_code >= 400:
+                r.read()
+                raise SidekickError(r.status_code, _safe_json(r))
+            event = None
+            for line in r.iter_lines():
+                if line.startswith("event: "):
+                    event = line[7:].strip()
+                elif line.startswith("data: ") and event:
+                    yield event, json.loads(line[6:])
+                    if event == "end":
+                        return
+
+    def act(
+        self,
+        *,
+        model: str,
+        observations: list[dict],
+        instruction: str | None = None,
+        action_space: str = "ee_delta_6d_grip",
+        horizon: int = 16,
+        goal_image: dict | None = None,
+        models: list[str] | None = None,
+        preference: str | None = None,
+        provider: dict | None = None,
+        temperature: float | None = None,
+        return_prediction: bool = False,
+        **kwargs: Any,
+    ) -> Action:
+        body = _clean({
+            "model": model, "models": models, "observations": observations,
+            "instruction": instruction, "action_space": action_space,
+            "horizon": horizon, "goal_image": goal_image, "provider": provider or {},
+            "preference": preference,
+            "temperature": temperature, "return_prediction": return_prediction, **kwargs,
+        })
+        d = self._post("/v1/act", body)
+        return Action(id=d["id"], model=d["model"], action=d["action"], route=d["route"],
+                      usage=d["usage"], confidence=d.get("confidence"),
+                      predicted_frames=d.get("predicted_frames"))
+
+    def ground(
+        self,
+        *,
+        observations: list[dict],
+        instruction: str | None = None,
+        model: str = "sidekick/ground",
+        max_images: int = 3,
+        max_tokens: int = 1024,
+        provider: dict | None = None,
+        **kwargs: Any,
+    ) -> Grounding:
+        """Ask where things are. Points and boxes, never actions.
+
+            g = sk.ground(observations=[sk.observation(image_path="scene.jpg")],
+                          instruction="point at every graspable object")
+        """
+        d = self._post("/v1/ground", _clean({
+            "model": model, "observations": observations, "instruction": instruction,
+            "max_images": max_images, "max_tokens": max_tokens,
+            "provider": provider or {}, **kwargs,
+        }))
+        return Grounding(id=d["id"], model=d["model"], route=d["route"],
+                         usage=d["usage"], points=d.get("points", []),
+                         boxes=d.get("boxes", []), raw=d.get("raw"))
+
+    def evaluate(self, *, model: str, policy_endpoint: str, scenario: str,
+                 episodes: int = 25, metrics: list[str] | None = None,
+                 **kwargs: Any) -> Evaluation:
+        d = self._post("/v1/evaluate", _clean({
+            "model": model, "policy_endpoint": policy_endpoint, "scenario": scenario,
+            "episodes": episodes, "metrics": metrics, **kwargs,
+        }))
+        return _to_eval(d)
+
+    def evaluation(self, job_id: str) -> Evaluation:
+        return _to_eval(self._get(f"/v1/evaluate/{job_id}"))
+
+    def wait_for_evaluation(self, job_id: str, *, poll_s: float = 2.0,
+                            timeout_s: float = 3600) -> Evaluation:
+        import time
+
+        deadline = time.time() + timeout_s
+        while time.time() < deadline:
+            job = self.evaluation(job_id)
+            if job.status in {"succeeded", "failed", "cancelled"}:
+                return job
+            time.sleep(poll_s)
+        raise TimeoutError(f"evaluation {job_id} did not finish in {timeout_s}s")
+
+    # ------------------------------------------------------------------
+    def models(self, **filters: Any) -> list[dict]:
+        return self._get("/v1/models", _clean(filters))["data"]
+
+    def model(self, model_id: str) -> dict:
+        return self._get(f"/v1/models/{model_id}")
+
+    def providers(self) -> list[dict]:
+        return self._get("/v1/providers")["data"]
+
+    def routes(self) -> list[dict]:
+        return self._get("/v1/routes")["data"]
+
+    def taxonomy(self) -> dict:
+        """Every value the catalog filters accept, with counts. Call this instead
+        of hard-coding domain / family / action-space strings."""
+        return self._get("/v1/taxonomy")
+
+    def scenarios(self, *, target: str | None = None,
+                  runnable: bool | None = None) -> list[dict]:
+        """The benchmark registry: valid values for `evaluate(scenario=...)`."""
+        return self._get("/v1/scenarios", _clean({"target": target, "runnable": runnable}))["data"]
+
+    def literature(self, *, kind: str | None = None) -> list[dict]:
+        """Surveys, position papers, theory. Catalogued, never servable."""
+        return self._get("/v1/literature", _clean({"kind": kind}))["data"]
+
+    def action_space_dims(self, space: str) -> int | None:
+        """How many numbers one step in this action space carries."""
+        for row in self.taxonomy()["action_spaces"]:
+            if row["id"] == space:
+                return row["dims"]
+        return None
+
+    def preview_route(self, *, model: str, horizon: int = 16,
+                      provider: dict | None = None, contract: str = "predict") -> list[dict]:
+        """Dry-run the router. Free, no inference happens."""
+        body = {"model": model, "horizon": horizon, "provider": provider or {},
+                "observations": [{"frames": [{"url": "https://example.invalid/probe.png"}]}]}
+        r = self._client.post(f"{self.base_url}/v1/routes/preview",
+                              params={"contract": contract}, json=body)
+        if r.status_code >= 400:
+            raise SidekickError(r.status_code, _safe_json(r))
+        return r.json()["plan"]
+
+    def usage(self, limit: int = 50) -> dict:
+        return self._get("/v1/usage", {"limit": limit})
+
+    def key(self) -> dict:
+        return self._get("/v1/key")
+
+    def stream_actions(self, **kwargs: Any) -> "ActionStream":
+        """A buffered action stream for a control loop. See ActionStream."""
+        return ActionStream(self, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Sidekick":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+def _clean(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _safe_json(r: httpx.Response) -> Any:
+    try:
+        return r.json()
+    except ValueError:
+        return r.text
+
+
+def _to_eval(d: dict) -> Evaluation:
+    return Evaluation(id=d["id"], model=d["model"], status=d["status"],
+                      scenario=d["scenario"], results=d.get("results"),
+                      usage=d.get("usage", {}), error=d.get("error"))
+
+
+def _frame_source(value: str) -> dict:
+    """Turn a URL, a local path or raw base64 into a frame body.
+
+    Guessing is the point: a caller assembling a four-camera rig should not have
+    to say which of three encodings each entry is, and getting it wrong is a
+    400 rather than a type error.
+    """
+    if value.startswith(("http://", "https://")):
+        return {"url": value}
+    p = pathlib.Path(value)
+    if p.exists():
+        return {"b64": base64.b64encode(p.read_bytes()).decode()}
+    return {"b64": value}
+
+
+class UnsafeResponse(RuntimeError):
+    """A response that must not reach an actuator.
+
+    Separate from SidekickError on purpose. A SidekickError means the call did
+    not succeed and you should retry or fail. This means the call succeeded and
+    the answer is wrong for this robot, which is the more dangerous case because
+    nothing about the response looks broken.
+    """
+
+
+class ActionStream:
+    """A local action buffer kept full from a remote policy.
+
+    The integration problem this solves: **you cannot call a cloud API once per
+    actuation.** A control loop runs at 30 to 200 Hz, a round trip is tens of
+    milliseconds before the GPU starts, and a policy answers in several hundred.
+    Ask for one action per tick and the robot stands still.
+
+    So `/v1/act` returns a chunk of N future actions plus the `dt_ms` they were
+    planned for, and this class executes that chunk from a local buffer while
+    fetching the next one on a background thread. Two threads, and the split is
+    the whole design:
+
+        your control thread   real-time, reads the buffer, never blocks
+        the policy thread     does the HTTP, refills the buffer, may be slow
+
+    Usage:
+
+        stream = sk.stream_actions(
+            model="sidekick/auto:manipulation",
+            instruction="fold the towel",
+            action_space="joint_pos_14", dof=14,
+            observe=lambda: sk.observation(cameras=rig.capture(),
+                                           proprio=robot.joints()),
+        )
+        stream.warm_up()          # while the arm is still braked
+        with stream:
+            while running:
+                step = stream.next_action()
+                if step is None:
+                    robot.hold()  # policy fell behind; decelerate, never repeat
+                else:
+                    robot.set_joint_positions(step)
+                time.sleep(stream.dt_s)
+
+    `next_action()` returns None as a real answer, not an error. It means the
+    buffer is dry or stale and the correct response is to decelerate. A client
+    that repeats its last command instead is a client that keeps driving on a
+    world that has moved on.
+    """
+
+    # Refetch when remaining runway drops below this multiple of measured
+    # latency. Expressed in time rather than steps because the step form is
+    # wrong in a way that looks right: "refill at 5 steps left" is 330 ms of
+    # runway against a 684 ms fetch, so the buffer empties for a third of every
+    # cycle and the arm stutters.
+    REFILL_LEAD = 1.5
+    MAX_CHUNK_AGE_S = 2.0
+
+    def __init__(self, client: "Sidekick", *, model: str, observe,
+                 instruction: str | None = None,
+                 action_space: str = "ee_delta_6d_grip", dof: int | None = None,
+                 horizon: int = 16, preference: str = "fastest",
+                 provider: dict | None = None):
+        self.sk = client
+        self.model = model
+        self.observe = observe
+        self.instruction = instruction
+        self.action_space = action_space
+        self.dof = dof
+        self.horizon = horizon
+        self.preference = preference
+        self.provider = provider or {"allow_simulated": False}
+
+        self._buffer: "collections.deque[list[float]]" = collections.deque()
+        self._lock = threading.Lock()
+        self._chunk_at = 0.0
+        self._dt_ms = 100
+        # Seeded pessimistically: an optimistic first estimate is a stall on the
+        # first cycle, before any measurement exists to correct it.
+        self._fetch_s = 1.0
+        self._stop = threading.Event()
+        self._need = threading.Event()
+        self._thread: threading.Thread | None = None
+        self.calls = 0
+        self.failures = 0
+        self.spend_usd = 0.0
+        self.last_error: str | None = None
+
+    # -- safety ----------------------------------------------------------
+    def check(self, act: "Action") -> None:
+        """Every way a response can be well-formed and still wrong for this robot."""
+        if act.route.get("simulated"):
+            raise UnsafeResponse("route.simulated is true: placeholder output, no GPU ran")
+        if act.space != self.action_space:
+            raise UnsafeResponse(
+                f"got action space {act.space!r}, this robot is {self.action_space!r}")
+        if self.dof is not None:
+            for i, step in enumerate(act.steps):
+                if len(step) != self.dof:
+                    raise UnsafeResponse(
+                        f"step {i} has {len(step)} values, this robot has {self.dof} joints")
+
+    # -- the policy thread -----------------------------------------------
+    def _fetch(self) -> None:
+        started = time.monotonic()
+        act = self.sk.act(
+            model=self.model, observations=[self.observe()],
+            instruction=self.instruction, action_space=self.action_space,
+            horizon=self.horizon, preference=self.preference, provider=self.provider,
+        )
+        self.check(act)
+        elapsed = time.monotonic() - started
+        with self._lock:
+            # Append rather than replace: the steps still queued were planned
+            # from a real observation, and discarding them opens exactly the gap
+            # this class exists to close.
+            self._buffer.extend(act.steps)
+            self._chunk_at = time.monotonic()
+            self._dt_ms = act.action.get("dt_ms", self._dt_ms)
+            self._fetch_s = 0.7 * self._fetch_s + 0.3 * elapsed
+            self.calls += 1
+            self.spend_usd += act.usage.get("cost_usd", 0.0)
+        self.last_error = None
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            if not self._need.wait(timeout=0.1):
+                continue
+            self._need.clear()
+            try:
+                self._fetch()
+            except Exception as exc:  # noqa: BLE001
+                # Never clear the buffer on failure. What is left is still valid
+                # for a few hundred milliseconds, which is enough for the control
+                # thread to notice and decelerate rather than fault.
+                self.failures += 1
+                self.last_error = f"{type(exc).__name__}: {exc}"
+
+    # -- the control thread ----------------------------------------------
+    def warm_up(self, timeout_s: float = 180.0) -> None:
+        """Fetch one chunk before the robot is enabled.
+
+        A cold serverless container loads several GB of weights. That belongs
+        here, with the arm braked, not on the first tick of a live loop.
+        """
+        deadline = time.monotonic() + timeout_s
+        while time.monotonic() < deadline:
+            try:
+                self._fetch()
+                return
+            except Exception as exc:  # noqa: BLE001
+                self.last_error = f"{type(exc).__name__}: {exc}"
+                time.sleep(2.0)
+        raise TimeoutError(f"policy did not warm in {timeout_s:g}s: {self.last_error}")
+
+    def start(self) -> "ActionStream":
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        return self
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=2.0)
+
+    def __enter__(self) -> "ActionStream":
+        return self.start()
+
+    def __exit__(self, *exc: Any) -> None:
+        self.stop()
+
+    @property
+    def dt_s(self) -> float:
+        return self._dt_ms / 1000.0
+
+    def next_action(self) -> list[float] | None:
+        """One step, or None if the buffer is dry or stale. Never blocks."""
+        with self._lock:
+            if not self._buffer:
+                self._need.set()
+                return None
+            if time.monotonic() - self._chunk_at > self.MAX_CHUNK_AGE_S:
+                self._buffer.clear()
+                self._need.set()
+                return None
+            step = self._buffer.popleft()
+            runway_s = len(self._buffer) * self._dt_ms / 1000.0
+            if runway_s <= self._fetch_s * self.REFILL_LEAD:
+                self._need.set()
+            return step

sidekick_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: sidekick-sdk
+Version: 0.1.0
+Summary: Python client for the Sidekick Robotics API: one endpoint for every robotics foundation model.
+Author: Sidekick Robotics
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://www.sidekickrobotics.ai
+Project-URL: Documentation, https://www.sidekickrobotics.ai/api
+Project-URL: Source, https://github.com/sidekickrobo/sidekick-sdk
+Project-URL: Issues, https://github.com/sidekickrobo/sidekick-sdk/issues
+Project-URL: Changelog, https://github.com/sidekickrobo/sidekick-sdk/blob/main/CHANGELOG.md
+Keywords: robotics,vla,world-model,embodied-ai,policy,inference,manipulation,control-loop
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# sidekick-sdk
+
+[![CI](https://github.com/sidekickrobo/sidekick-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/sidekickrobo/sidekick-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sidekick-sdk.svg)](https://pypi.org/project/sidekick-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/sidekick-sdk.svg)](https://pypi.org/project/sidekick-sdk/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+Python client for the [Sidekick Robotics](https://www.sidekickrobotics.ai) API:
+one endpoint for every robotics foundation model, with routing, fallback and
+per-request billing.
+
+```bash
+pip install sidekick-sdk
+```
+
+**One dependency (`httpx`).** It installs on a robot control computer, or inside
+a ROS container, without dragging a web framework along.
+
+Get an API key at [sidekickrobotics.ai/api](https://www.sidekickrobotics.ai/api).
+
+## Sixty seconds
+
+```python
+from sidekick_sdk import Sidekick
+
+sk = Sidekick(api_key="sk-sidekick-...")
+
+act = sk.act(
+    model="sidekick/auto:manipulation",   # ask for a job, not a checkpoint
+    observations=[sk.observation(image_path="frame.jpg", proprio=joints)],
+    instruction="put the spoon on the towel",
+    action_space="joint_pos_14",
+    horizon=16,
+)
+
+print(act.route["model"])      # which checkpoint actually served you
+print(act.usage["cost_usd"])   # what it cost
+robot.execute(act.steps)
+```
+
+`model` takes a router alias (`sidekick/auto:manipulation`), a concrete model
+id, or a list via `models=[...]` in the order you want them tried. Every
+response carries `route`, so you always know what answered and whether it fell
+back.
+
+## Say what you care about
+
+```python
+sk.act(..., preference="fastest")   # balanced | fastest | cheapest | reliable
+```
+
+`fastest` orders live candidates by measured latency, `cheapest` by price,
+`reliable` by success rate, `balanced` blends them. Add hard constraints
+alongside it:
+
+```python
+sk.act(..., provider={"max_latency_ms": 900, "allow_simulated": False})
+```
+
+`allow_simulated=False` is the one to set for anything with an actuator behind
+it. Without it a placeholder response is structurally indistinguishable from a
+real one.
+
+## Four contracts, on purpose
+
+| Call | Question it answers | Returns |
+| --- | --- | --- |
+| `sk.predict()` | what happens next | future frames |
+| `sk.act()` | what should I do next | an action chunk |
+| `sk.ground()` | where is the thing | boxes, masks, points |
+| `sk.evaluate()` | is this policy any good | a benchmark job |
+
+They are not interchangeable, and the router will not silently serve one where
+you asked for another.
+
+## Control loops
+
+The one thing that catches people: **you cannot call a cloud API once per
+actuation.** A control loop runs at 30 to 200 Hz and a policy answers in
+several hundred milliseconds. `/v1/act` therefore returns a *chunk* of N future
+actions plus the `dt_ms` they were planned for; the robot executes that chunk
+from a local buffer while the next one is fetched in the background.
+
+`ActionStream` is that buffer, and the timing it gets right is not obvious:
+
+```python
+stream = sk.stream_actions(
+    model="sidekick/auto:manipulation",
+    instruction="fold the towel",
+    action_space="joint_pos_14", dof=14,
+    preference="fastest",
+    observe=lambda: sk.observation(cameras=rig.capture(), proprio=robot.joints()),
+)
+
+stream.warm_up()          # cold container, arm still braked
+with stream:              # starts the background policy thread
+    while running:
+        step = stream.next_action()
+        if step is None:
+            robot.hold()  # policy fell behind; decelerate, never repeat
+        else:
+            robot.set_joint_positions(step)
+        time.sleep(stream.dt_s)
+```
+
+Three things worth knowing about it:
+
+- **`next_action()` never blocks and never raises.** All network work happens on
+  the policy thread. Your servo loop stays real-time.
+- **`None` is a real answer.** The buffer is dry or the chunk is stale. Hold or
+  decelerate. Repeating the last command indefinitely is a robot acting on a
+  world that has moved on.
+- **Refills are triggered in time, not in steps.** "Refetch when 5 steps are
+  left" sounds right and stalls: 5 steps at 66 ms is 330 ms of runway against a
+  684 ms fetch. The stream measures its own round trip and refills at 1.5x it.
+
+`stream.check()` runs three guards on every chunk before it can reach an
+actuator, raising `UnsafeResponse` on a simulated route, a mismatched action
+space, or a step whose width is not this robot's DOF.
+
+## Multi-camera rigs
+
+```python
+obs = sk.observation(
+    cameras={"cam_high": "frames/high.jpg",
+             "cam_low": "frames/low.jpg",
+             "cam_left_wrist": "frames/lw.jpg",
+             "cam_right_wrist": "frames/rw.jpg"},
+    proprio=joint_positions)
+```
+
+Values can be URLs, local paths or base64. Camera names must match what the
+checkpoint declares: a wrist view passed as the head view produces confident
+nonsense, and nothing in the response says so.
+
+## Discovery
+
+```python
+sk.routes()                       # router aliases that are live right now
+sk.models(domain="manipulation")  # the catalog
+sk.taxonomy()                     # every value the filters accept, with counts
+sk.action_space_dims("joint_pos_14")
+sk.preview_route(model="sidekick/auto:manipulation", contract="act")  # free dry run
+sk.usage()                        # your ledger
+```
+
+Call `taxonomy()` instead of hard-coding domain, family or action-space strings.
+
+## Configuration
+
+```python
+Sidekick(api_key=..., base_url=..., timeout=120.0, max_retries=2)
+```
+
+`base_url` defaults to `$SIDEKICK_ORIGIN`, then to the public gateway. Point it
+at a private deployment without touching call sites.
+
+## Errors
+
+`SidekickError` carries `.status`, `.code` and `.body`. `UnsafeResponse` is
+separate on purpose: a `SidekickError` means the call did not succeed and you
+should retry; an `UnsafeResponse` means the call succeeded and the answer is
+wrong for this robot, which is the more dangerous case because nothing about it
+looks broken.
+
+Full API reference: <https://www.sidekickrobotics.ai/api>
+
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

sidekick_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sidekick_sdk/__init__.py,sha256=3dd_BW1lUCoaE6l4pdCoSD4urTtB8fV7mkYC7VQbR-4,24588
+sidekick_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sidekick_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=iItzXBHkOU2y6V4sW16TWJTouWv07Xt1Anj1jLQOlZo,11315
+sidekick_sdk-0.1.0.dist-info/METADATA,sha256=m6WnLE9JdBYAsZ6N641JAzjsSCmYCClRVlyX4IuMtAQ,7652
+sidekick_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sidekick_sdk-0.1.0.dist-info/top_level.txt,sha256=KIcHTcBULSDubmotziXURM-zMHGQHSzs-WbAPkatXKo,13
+sidekick_sdk-0.1.0.dist-info/RECORD,,

sidekick_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sidekick_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sidekick Robotics
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

sidekick_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sidekick_sdk