sequence-ai 0.1.0__py3-none-any.whl

sequence_ai/__init__.py

@@ -0,0 +1,192 @@
+"""
+sequence_ai — the Python client for the Sequences robot inference API.
+
+── In one sentence ───────────────────────────────────────────────────
+`connect()` opens one HTTP connection and hands back a `Policy`; `run()` drives a bounded
+control loop against it, keeping the connection open and the action buffer full for the life
+of the `with` block.
+
+    import sequence_ai
+
+    with sequence_ai.connect(model="pi05-droid") as policy:
+        out = policy.run(
+            observe=robot.read_observation,
+            act=robot.apply_action,
+            validate=robot.is_safe,
+            hold=robot.hold,
+            max_actions=250,
+        )
+
+── What it does for you ──────────────────────────────────────────────
+Four things, each of them work a loop written straight against the HTTP endpoints has to get
+right before it behaves properly on a robot:
+
+    keeps the connection open      184.9 ms of handshake otherwise paid on every call,
+                                   60% of a bare request  (see _transport.py)
+    refills before the buffer      a synchronous refill stops the arm once per chunk, for a
+    empties                        full round trip — 39% duty cycle on the fastest models
+                                   (see _policy.run)
+    classifies errors              `warming` with a retry_after_s is "wait 118 s"; a plain
+                                   Unavailable is "stop" — opposite instructions (see errors)
+    one driver per buffer          two loops on one handle interleave and both report
+                                   success (see Policy._driving)
+
+None of the four is guesswork. Each is a defect that existed in this client, was measured, and
+was fixed; the cited modules carry the measurements.
+
+── If your controller is not Python ──────────────────────────────────
+Everything here is a plain HTTP call to a documented, public endpoint, and it stays that way.
+There is no private control plane and nothing this package can reach that you cannot.
+
+    curl https://api.generalsequences.com/v1/act \\
+      -H "Authorization: Bearer $SEQUENCES_API_KEY" \\
+      -d '{"model":"...","observation":{...}}'
+
+Keeping that door open is deliberate: a vendor SDK that is the only supported way in gives the
+vendor a lock and excludes every team on a language it does not ship, and robots are not a
+Python-only industry — the controller is very often C++. But it is a door, not the front
+entrance. The four items above become your client's problem, and each is documented precisely
+enough to reimplement at https://generalsequences.com/docs/python/.
+
+── Safety ────────────────────────────────────────────────────────────
+An action returned by any model is model output, not a safe robot command. This library does
+not check joint limits, reachability, collisions, velocity, or anything else. Bounds
+checking, a watchdog and an e-stop belong between this library and your motors, and
+`run(validate=..., hold=...)` is where to attach them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._policy import Policy
+from ._transport import DEFAULT_BASE_URL, Transport
+from .errors import (
+    AuthError,
+    ChunkExhausted,
+    InvalidRequest,
+    OutOfCredit,
+    SequencesError,
+    Unavailable,
+)
+from .types import (
+    ActionChunk,
+    ImageFrame,
+    Model,
+    Observation,
+    Prediction,
+    Proprioception,
+    RunOutcome,
+)
+
+__all__ = [
+    "connect",
+    "models",
+    "Policy",
+    "Observation",
+    "ImageFrame",
+    "Proprioception",
+    "ActionChunk",
+    "Prediction",
+    "RunOutcome",
+    "Model",
+    "SequencesError",
+    "AuthError",
+    "OutOfCredit",
+    "InvalidRequest",
+    "Unavailable",
+    "ChunkExhausted",
+    "DEFAULT_BASE_URL",
+]
+
+__version__ = "0.1.0"
+
+# Short ids are accepted as well as full ones, because `pi05-droid` is what people actually
+# type and `accounts/sequences/models/pi05-droid` is what the API expects. Expanding it here
+# rather than making the caller remember the prefix.
+_PREFIX = "accounts/sequences/models/"
+
+
+def connect(
+    model: str,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    control_hz: float | None = None,
+    timeout_s: float = 30.0,
+) -> Policy:
+    """
+    Open a connection to one model.
+
+    model       either `pi05-droid` or the full `accounts/sequences/models/pi05-droid`
+    api_key     defaults to $SEQUENCES_API_KEY
+    base_url    defaults to $SEQUENCES_BASE_URL, then the production gateway
+    control_hz  play actions out at this rate instead of the rate the chunk declares
+    timeout_s   per-request timeout
+
+    Use it as a context manager. The connection is what makes this worth calling at all, and
+    a `Policy` that is never closed leaks a socket:
+
+        with sequence_ai.connect(model="pi05-droid") as policy:
+            ...
+
+    Nothing is sent at connect time — no session is opened on the server and nothing is
+    billed. The first request happens on the first `predict()`. This is deliberately unlike
+    a session-based API where opening the handle already costs money; here the handle is
+    purely local.
+    """
+    return Policy(
+        Transport(api_key=api_key, base_url=base_url, timeout_s=timeout_s),
+        model=_full_id(model),
+        control_hz=control_hz,
+    )
+
+
+def models(
+    *,
+    endpoint: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> list[Model]:
+    """
+    The live catalogue. `endpoint="act"` for action models, `"chat"` for vision-language.
+
+    Fetched from the server every call rather than shipped as a constant in this package: a
+    hard-coded list goes stale the moment a model is added, and a client that disagrees with
+    the server about what exists is worse than one that has to make a request to find out.
+    """
+    # No key required: the catalogue is a public endpoint, and making people sign up
+    # before they can see what is on offer is a reason to close the tab.
+    t = Transport(api_key=api_key, base_url=base_url, require_key=False)
+    try:
+        path = "/v1/models" + (f"?endpoint={endpoint}" if endpoint else "")
+        body = t.get(path)
+        return [_to_model(d) for d in body.get("data", [])]
+    finally:
+        t.close()
+
+
+def _full_id(model: str) -> str:
+    return model if "/" in model else _PREFIX + model
+
+
+def _to_model(d: dict[str, Any]) -> Model:
+    """
+    Map a catalogue row, keeping the untouched dict in `.raw`.
+
+    Only the fields a caller needs to *construct a request* are lifted into attributes; the
+    rest — pricing, licence, latency, tags — stay in `.raw`. Lifting everything would mean
+    this function has to change every time the catalogue grows a field, and forgetting to
+    update it would silently drop data the server sent.
+    """
+    return Model(
+        id=d["id"],
+        endpoint=d.get("endpoint", ""),
+        architecture=d.get("architecture", ""),
+        robot=d.get("robot"),
+        action_dim=d.get("action_dim"),
+        action_horizon=d.get("action_horizon"),
+        control_hz=d.get("control_hz"),
+        camera_views=tuple(d.get("camera_views") or ()),
+        raw=d,
+    )

sequence_ai/_config.py

@@ -0,0 +1,72 @@
+"""
+Where the API key lives when it is not in the environment.
+
+Resolution order, first hit wins:
+  1. the `api_key=` argument
+  2. $SEQUENCES_API_KEY
+  3. ~/.config/sequence-ai/credentials
+
+WHY a file at all, when an env var already works: a robot controller is usually started by
+systemd or a launch file, not from the shell that ran `export`. Telling someone to put a
+secret into a unit file is worse advice than writing it once to a mode-0600 file in their
+home directory.
+
+WHY the env var still wins over the file: CI and containers set env vars, and a stale file
+left behind on a shared machine silently overriding an explicitly-set variable is the kind
+of surprise that costs an afternoon.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+# XDG if set, otherwise the conventional location. Not ~/.sequence-ai: dotfile clutter in
+# the home directory is what XDG exists to stop.
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME")
+    return Path(base) / "sequence-ai" if base else Path.home() / ".config" / "sequence-ai"
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials"
+
+
+def load_key() -> str | None:
+    """The stored key, or None. Never raises — a missing or unreadable file just means 'no key'."""
+    p = credentials_path()
+    try:
+        for line in p.read_text().splitlines():
+            line = line.strip()
+            if line and not line.startswith("#"):
+                return line
+    except OSError:
+        return None
+    return None
+
+
+def save_key(key: str) -> Path:
+    """
+    Write the key, readable only by its owner.
+
+    chmod is applied **after** writing rather than relying on the umask: a permissive umask
+    would otherwise leave the file world-readable for the moment between creation and the
+    chmod, and on a shared machine that moment is enough.
+    """
+    d = config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = credentials_path()
+    p.write_text(key.strip() + "\n")
+    p.chmod(stat.S_IRUSR | stat.S_IWUSR)     # 0600
+    return p
+
+
+def clear_key() -> bool:
+    """Remove the stored key. Returns whether there was one."""
+    p = credentials_path()
+    try:
+        p.unlink()
+        return True
+    except OSError:
+        return False