agi-diy 0.1.0__tar.gz

agi_diy-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/

agi_diy-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: agi-diy
+Version: 0.1.0
+Summary: api.agi.diy client: lease a VLA policy, run it over the LeRobot remote-inference protocol.
+Project-URL: Homepage, https://api.agi.diy
+Project-URL: Source, https://github.com/cagataycali/api-agi-diy
+Author: agi.diy
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: lerobot
+Requires-Dist: lerobot[remote]>=0.6; extra == 'lerobot'
+Requires-Dist: numpy; extra == 'lerobot'
+Description-Content-Type: text/markdown
+
+# agi-diy
+
+Python client for [api.agi.diy](https://api.agi.diy). Lease a VLA policy, run it over the LeRobot
+remote-inference protocol (zenoh). One call = one token per action in the chunk.
+
+```
+pip install "agi-diy[lerobot]"
+agi login
+agi run act/so101 --probe
+```
+
+```python
+import agi
+
+with agi.Policy("act/so101") as session:
+    actions = session.predict(
+        {"observation.state": state, "observation.images.front": frame},
+        task="pick up the cube",
+    )  # np.ndarray [n_action_steps, dof]
+```
+
+The key comes from `AGI_API_KEY` or `~/.agi/credentials` (`AGI_API_KEY=agi_sk_live_…`).
+
+## Surface
+
+```python
+agi.Policy("act/so101")          # POST /v1/sessions → lease; raises agi.NoSlots / agi.InsufficientCredits / agi.AuthError
+session.endpoint                 # "ws/zenoh.api.agi.diy:80"
+session.deployment               # "d_…"
+session.url                      # "zenoh+ws://zenoh.api.agi.diy:80/d_…"
+session.connect()                # admitted lerobot.remote_inference.RemoteClient
+session.predict(obs, task="…")   # one chunk, np.ndarray
+session.policy()                 # strands-robots policy: arm.run(session.policy(), seconds=30)
+session.rollout_args()           # flags for lerobot-rollout
+session.close()                  # DELETE /v1/sessions/:id (also a context manager)
+agi.models(); agi.me(); agi.usage(); agi.sessions(); agi.health()
+```
+
+CLI: `agi login` · `agi models` · `agi session act/so101` · `agi run act/so101 --probe` ·
+`agi rollout act/so101 -- --robot.type=so101_follower …` · `agi usage`.
+
+`connect()`, `predict()` and `rollout` need `pip install "agi-diy[lerobot]"`. The REST part has no dependencies.
+
+Errors subclass `agi.Error` with `.error`, `.status`, `.retry_after_s`.

agi_diy-0.1.0/README.md

@@ -0,0 +1,44 @@
+# agi-diy
+
+Python client for [api.agi.diy](https://api.agi.diy). Lease a VLA policy, run it over the LeRobot
+remote-inference protocol (zenoh). One call = one token per action in the chunk.
+
+```
+pip install "agi-diy[lerobot]"
+agi login
+agi run act/so101 --probe
+```
+
+```python
+import agi
+
+with agi.Policy("act/so101") as session:
+    actions = session.predict(
+        {"observation.state": state, "observation.images.front": frame},
+        task="pick up the cube",
+    )  # np.ndarray [n_action_steps, dof]
+```
+
+The key comes from `AGI_API_KEY` or `~/.agi/credentials` (`AGI_API_KEY=agi_sk_live_…`).
+
+## Surface
+
+```python
+agi.Policy("act/so101")          # POST /v1/sessions → lease; raises agi.NoSlots / agi.InsufficientCredits / agi.AuthError
+session.endpoint                 # "ws/zenoh.api.agi.diy:80"
+session.deployment               # "d_…"
+session.url                      # "zenoh+ws://zenoh.api.agi.diy:80/d_…"
+session.connect()                # admitted lerobot.remote_inference.RemoteClient
+session.predict(obs, task="…")   # one chunk, np.ndarray
+session.policy()                 # strands-robots policy: arm.run(session.policy(), seconds=30)
+session.rollout_args()           # flags for lerobot-rollout
+session.close()                  # DELETE /v1/sessions/:id (also a context manager)
+agi.models(); agi.me(); agi.usage(); agi.sessions(); agi.health()
+```
+
+CLI: `agi login` · `agi models` · `agi session act/so101` · `agi run act/so101 --probe` ·
+`agi rollout act/so101 -- --robot.type=so101_follower …` · `agi usage`.
+
+`connect()`, `predict()` and `rollout` need `pip install "agi-diy[lerobot]"`. The REST part has no dependencies.
+
+Errors subclass `agi.Error` with `.error`, `.status`, `.retry_after_s`.

agi_diy-0.1.0/agi/__init__.py

@@ -0,0 +1,43 @@
+"""api.agi.diy — lease a VLA policy, run it over zenoh.
+
+    import agi
+    with agi.Policy("act/so101") as session:
+        actions = session.predict(observation, task="pick up the cube")
+"""
+
+from __future__ import annotations
+
+from . import _http
+from .errors import AuthError, Error, InsufficientCredits, MissingDependency, NoSlots, UnknownModel
+from .session import Policy
+
+__version__ = "0.1.0"
+__all__ = [
+    "Policy", "models", "me", "usage", "health", "sessions",
+    "Error", "AuthError", "NoSlots", "InsufficientCredits", "UnknownModel", "MissingDependency",
+]
+
+
+def models() -> list[dict]:
+    """GET /v1/models."""
+    return _http.request("GET", "/v1/models").get("models", [])
+
+
+def me() -> dict:
+    """GET /v1/me."""
+    return _http.request("GET", "/v1/me")
+
+
+def usage(since: str | None = None) -> dict:
+    """GET /v1/usage[?since=<iso>]."""
+    return _http.request("GET", "/v1/usage" + (f"?since={since}" if since else ""))
+
+
+def sessions() -> list[dict]:
+    """GET /v1/sessions."""
+    return _http.request("GET", "/v1/sessions").get("sessions", [])
+
+
+def health() -> dict:
+    """GET /v1/health (no key needed)."""
+    return _http.request("GET", "/v1/health", auth=False)

agi_diy-0.1.0/agi/_http.py

@@ -0,0 +1,78 @@
+"""Credentials + one JSON request helper. Standard library only."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from .errors import AuthError, from_response
+
+DEFAULT_URL = "https://api.agi.diy"
+CREDENTIALS = Path(os.environ.get("AGI_CREDENTIALS", "~/.agi/credentials")).expanduser()
+USER_AGENT = "agi-diy-python/0.1.0"
+
+
+def _read_credentials() -> dict[str, str]:
+    out: dict[str, str] = {}
+    try:
+        for line in CREDENTIALS.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            out[k.strip()] = v.strip().strip('"').strip("'")
+    except FileNotFoundError:
+        pass
+    return out
+
+
+def api_url() -> str:
+    return (os.environ.get("AGI_API_URL") or _read_credentials().get("AGI_API_URL") or DEFAULT_URL).rstrip("/")
+
+
+def api_key(required: bool = True) -> str | None:
+    key = os.environ.get("AGI_API_KEY") or _read_credentials().get("AGI_API_KEY")
+    if not key and required:
+        raise AuthError(
+            f"Set AGI_API_KEY or run `agi login` (writes {CREDENTIALS}); no API key found.",
+            error="unauthorized",
+            status=0,
+        )
+    return key
+
+
+def write_credentials(key: str, url: str | None = None) -> Path:
+    CREDENTIALS.parent.mkdir(parents=True, exist_ok=True)
+    lines = [f"AGI_API_KEY={key}"]
+    if url and url.rstrip("/") != DEFAULT_URL:
+        lines.append(f"AGI_API_URL={url.rstrip('/')}")
+    CREDENTIALS.write_text("\n".join(lines) + "\n")
+    CREDENTIALS.chmod(0o600)
+    return CREDENTIALS
+
+
+def request(method: str, path: str, body: dict | None = None, *, key: str | None = None, auth: bool = True, timeout: float = 15.0) -> dict:
+    url = api_url() + path
+    data = json.dumps(body).encode() if body is not None else None
+    headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+    if data is not None:
+        headers["Content-Type"] = "application/json"
+    if auth:
+        headers["Authorization"] = f"Bearer {key or api_key()}"
+    req = urllib.request.Request(url, data=data, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else {}
+    except urllib.error.HTTPError as exc:
+        raw = exc.read()
+        try:
+            parsed = json.loads(raw) if raw else None
+        except ValueError:
+            parsed = None
+        raise from_response(exc.code, parsed) from None
+    except urllib.error.URLError as exc:
+        raise from_response(0, {"error": "unreachable", "message": f"Cannot reach {url}: {exc.reason}."}) from None

agi_diy-0.1.0/agi/cli.py

@@ -0,0 +1,178 @@
+"""`agi` — login, models, run --probe, rollout. Output is plain text or JSON (--json)."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import shutil
+import sys
+import time
+
+from . import __version__, _http
+from .errors import Error
+
+
+def _die(exc: Exception, code: int = 1) -> int:
+    print(f"error: {exc}", file=sys.stderr)
+    return code
+
+
+def cmd_login(a: argparse.Namespace) -> int:
+    key = a.key or os.environ.get("AGI_API_KEY") or getpass.getpass("API key (agi_sk_live_…): ").strip()
+    if not key.startswith("agi_sk_"):
+        print("error: keys start with agi_sk_live_; create one at https://api.agi.diy/dashboard", file=sys.stderr)
+        return 2
+    if a.url:
+        os.environ["AGI_API_URL"] = a.url
+    try:
+        me = _http.request("GET", "/v1/me", key=key)
+    except Error as exc:
+        return _die(exc)
+    path = _http.write_credentials(key, a.url)
+    print(f"logged in as {me.get('login')} · credits {me.get('credits_tokens')} tokens · saved to {path}")
+    return 0
+
+
+def cmd_models(a: argparse.Namespace) -> int:
+    try:
+        models = _http.request("GET", "/v1/models").get("models", [])
+    except Error as exc:
+        return _die(exc)
+    if a.json:
+        print(json.dumps(models, indent=2))
+        return 0
+    if not models:
+        print("no models")
+        return 0
+    w = max(len(m["id"]) for m in models)
+    for m in models:
+        print(f"{m['id']:<{w}}  {m.get('state','?'):<8} slots {m.get('slots_free','?')}/{m.get('slots_total','?')}  "
+              f"horizon {m.get('action_horizon','?')}  fps {m.get('fps','?')}  {m.get('semantics','')}")
+    return 0
+
+
+def cmd_me(a: argparse.Namespace) -> int:
+    try:
+        print(json.dumps(_http.request("GET", "/v1/me"), indent=2))
+    except Error as exc:
+        return _die(exc)
+    return 0
+
+
+def cmd_usage(a: argparse.Namespace) -> int:
+    try:
+        u = _http.request("GET", "/v1/usage")
+    except Error as exc:
+        return _die(exc)
+    if a.json:
+        print(json.dumps(u, indent=2))
+        return 0
+    print(f"credits {u.get('credits_tokens')} tokens · used {u.get('tokens_used')} tokens in {u.get('calls')} calls")
+    for row in u.get("by_model", []):
+        print(f"  {row['model']:<16} {row['calls']:>6} calls {row['tokens']:>9} tokens")
+    return 0
+
+
+def cmd_session(a: argparse.Namespace) -> int:
+    from .session import Policy
+
+    try:
+        s = Policy(a.model, ttl_s=a.ttl)
+    except Error as exc:
+        return _die(exc)
+    print(json.dumps(s.lease, indent=2) if a.json else
+          f"session {s.id}\nendpoint {s.endpoint}\ndeployment {s.deployment}\nsemantics {s.semantics}\nurl {s.url}\nexpires {s.expires_at}")
+    if not a.keep:
+        s.close()
+    return 0
+
+
+def cmd_run(a: argparse.Namespace) -> int:
+    from .session import Policy
+
+    try:
+        session = Policy(a.model, ttl_s=a.ttl)
+    except Error as exc:
+        return _die(exc)
+    try:
+        print(f"session {session.id} · {session.endpoint} · {session.deployment}")
+        t0 = time.perf_counter()
+        client = session.connect(chunk_merge="append")
+        caps = client.capabilities
+        print(f"connected in {(time.perf_counter()-t0)*1000:.0f} ms · features "
+              + ", ".join(f"{f.name}{tuple(f.shape)}" for f in caps.features)
+              + f" · action {caps.action_feature.shape[0]}×{caps.execution_steps} @ {1/caps.action_interval:g} Hz")
+        if a.probe:
+            obs = session.synthetic_observation()
+            for i in range(a.n):
+                t1 = time.perf_counter()
+                actions = session.predict(obs, task=a.task)
+                dt = (time.perf_counter() - t1) * 1000
+                print(f"chunk {i+1}/{a.n}: shape {actions.shape} dtype {actions.dtype} · {dt:.0f} ms · "
+                      f"first {actions[0][:3].round(2).tolist()}…")
+        return 0
+    except Error as exc:
+        return _die(exc)
+    except Exception as exc:  # zenoh/lerobot errors already name the fix
+        return _die(exc)
+    finally:
+        session.close()
+
+
+def cmd_rollout(a: argparse.Namespace) -> int:
+    from .session import Policy
+
+    exe = shutil.which("lerobot-rollout")
+    if not exe:
+        print("error: install LeRobot with `pip install 'lerobot[remote]'`; lerobot-rollout is not on PATH.", file=sys.stderr)
+        return 2
+    try:
+        session = Policy(a.model, ttl_s=a.ttl)
+    except Error as exc:
+        return _die(exc)
+    argv = [exe, *session.rollout_args(), *a.args]
+    print("+ " + " ".join(argv), file=sys.stderr)
+    import subprocess
+
+    try:
+        return subprocess.call(argv)
+    finally:
+        session.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="agi", description="api.agi.diy — the brain over cloud.")
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("login", help="save an API key to ~/.agi/credentials")
+    s.add_argument("--key"); s.add_argument("--url", help="API base URL (default https://api.agi.diy)")
+    s.set_defaults(fn=cmd_login)
+
+    s = sub.add_parser("models", help="list models"); s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_models)
+    s = sub.add_parser("me", help="who am I"); s.set_defaults(fn=cmd_me)
+    s = sub.add_parser("usage", help="credits and usage"); s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_usage)
+
+    s = sub.add_parser("session", help="lease a slot and print endpoint + deployment")
+    s.add_argument("model"); s.add_argument("--ttl", type=int); s.add_argument("--keep", action="store_true", help="do not end it")
+    s.add_argument("--json", action="store_true"); s.set_defaults(fn=cmd_session)
+
+    s = sub.add_parser("run", help="lease, connect over zenoh, --probe sends a synthetic observation")
+    s.add_argument("model"); s.add_argument("--probe", action="store_true"); s.add_argument("-n", type=int, default=3)
+    s.add_argument("--task", default="probe"); s.add_argument("--ttl", type=int); s.set_defaults(fn=cmd_run)
+
+    s = sub.add_parser("rollout", help="lease, then exec lerobot-rollout with the remote flags filled in")
+    s.add_argument("model"); s.add_argument("--ttl", type=int)
+    s.add_argument("args", nargs=argparse.REMAINDER, help="-- <lerobot-rollout args>")
+    s.set_defaults(fn=cmd_rollout)
+
+    a = p.parse_args(argv)
+    if getattr(a, "args", None) and a.args[:1] == ["--"]:
+        a.args = a.args[1:]
+    return a.fn(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agi_diy-0.1.0/agi/errors.py

@@ -0,0 +1,56 @@
+"""Every error names the fix in one sentence."""
+
+from __future__ import annotations
+
+
+class Error(Exception):
+    """An api.agi.diy refusal. `error` is the snake_case code from the API."""
+
+    def __init__(self, message: str, *, error: str = "error", status: int = 0, retry_after_s: float | None = None):
+        super().__init__(message)
+        self.error = error
+        self.status = status
+        self.retry_after_s = retry_after_s
+
+    @property
+    def retryable(self) -> bool:
+        return self.retry_after_s is not None
+
+
+class AuthError(Error):
+    """401: no key, a revoked key, or a wrong key."""
+
+
+class NoSlots(Error):
+    """409 no_slots: every slot for the model is taken; wait `retry_after_s` and call again."""
+
+
+class InsufficientCredits(Error):
+    """402: credits are at zero."""
+
+
+class UnknownModel(Error):
+    """404 unknown_model: the id is not in `agi models`."""
+
+
+class MissingDependency(Error):
+    """A zenoh call needs the lerobot extra."""
+
+
+_BY_CODE = {
+    "unauthorized": AuthError,
+    "no_slots": NoSlots,
+    "insufficient_credits": InsufficientCredits,
+    "unknown_model": UnknownModel,
+}
+
+
+def from_response(status: int, body: dict | None) -> Error:
+    body = body or {}
+    code = str(body.get("error") or f"http_{status}")
+    message = str(body.get("message") or f"api.agi.diy answered {status}.")
+    retry = body.get("retry_after_s")
+    if code == "unauthorized":
+        message = "The API key is missing or invalid; set AGI_API_KEY or run `agi login`."
+    cls = _BY_CODE.get(code, Error)
+    return cls(message, error=code, status=status, retry_after_s=float(retry) if retry is not None else None)

agi_diy-0.1.0/agi/session.py

@@ -0,0 +1,239 @@
+"""agi.Policy: one leased slot on api.agi.diy, spoken over zenoh with LeRobot's own client."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+from uuid import uuid4
+
+from . import _http
+from .errors import MissingDependency
+
+
+def _lerobot():
+    try:
+        from lerobot.inference import RemoteInferenceConfig  # noqa: F401
+        from lerobot.remote_inference import RemoteClient  # noqa: F401
+    except ImportError:
+        raise MissingDependency(
+            "Run `pip install 'agi-diy[lerobot]'`; connect() and predict() need lerobot[remote].",
+            error="missing_dependency",
+        ) from None
+
+
+class Policy:
+    """`agi.Policy("act/so101")` leases one slot and holds it until `close()`.
+
+    Attributes come straight from the lease: `id`, `model`, `endpoint` ("ws/zenoh.api.agi.diy:80"),
+    `deployment` ("d_…"), `semantics`, `action_horizon`, `fps`, `expires_at`, `zenoh_mode`.
+    """
+
+    def __init__(self, model: str, *, ttl_s: int | None = None, api_key: str | None = None):
+        body: dict[str, Any] = {"model": model}
+        if ttl_s is not None:
+            body["ttl_s"] = int(ttl_s)
+        self._key = api_key
+        self.lease = _http.request("POST", "/v1/sessions", body, key=api_key)
+        self._client: Any = None
+        self._closed = False
+
+    # --- lease fields -------------------------------------------------------
+    @property
+    def id(self) -> str:
+        return self.lease["id"]
+
+    @property
+    def model(self) -> str:
+        return self.lease["model"]
+
+    @property
+    def deployment(self) -> str:
+        return self.lease["deployment"]
+
+    @property
+    def endpoint(self) -> str:
+        z = self.lease.get("zenoh") or {}
+        return z.get("endpoint") or (z.get("endpoints") or [""])[0]
+
+    @property
+    def endpoints(self) -> list[str]:
+        z = self.lease.get("zenoh") or {}
+        return list(z.get("endpoints") or ([z["endpoint"]] if z.get("endpoint") else []))
+
+    @property
+    def zenoh_mode(self) -> str:
+        return (self.lease.get("zenoh") or {}).get("mode") or "client"
+
+    @property
+    def semantics(self) -> str:
+        return self.lease.get("semantics") or ""
+
+    @property
+    def action_horizon(self) -> int | None:
+        return self.lease.get("action_horizon")
+
+    @property
+    def fps(self) -> int | None:
+        return self.lease.get("fps")
+
+    @property
+    def expires_at(self) -> str | None:
+        return self.lease.get("expires_at")
+
+    @property
+    def url(self) -> str:
+        """`zenoh+<link>://host:port/<deployment>` — e.g. `zenoh+ws://zenoh.api.agi.diy:80/d_…`.
+
+        A tcp endpoint gives `zenoh://host:port/<deployment>`, which strands-robots `Policy(...)` parses today.
+        For ws use `session.policy()` (works now) or the one-line parser change in docs/UPSTREAM.md.
+        """
+        link, _, hostport = self.endpoint.partition("/")
+        scheme = "zenoh" if link == "tcp" else f"zenoh+{link}"
+        return f"{scheme}://{hostport}/{self.deployment}"
+
+    def rollout_args(self) -> list[str]:
+        """The `lerobot-rollout` flags for this lease."""
+        args = [
+            "--inference.type=remote",
+            f"--inference.endpoint={self.endpoint}",
+            f"--inference.deployment={self.deployment}",
+            f"--inference.zenoh_mode={self.zenoh_mode}",
+        ]
+        if self.semantics:
+            args.append(f"--inference.semantics={self.semantics}")
+        return args
+
+    # --- zenoh --------------------------------------------------------------
+    def config(self, **overrides: Any):
+        """A `lerobot.inference.RemoteInferenceConfig` built from the lease."""
+        _lerobot()
+        from lerobot.inference import RemoteInferenceConfig
+
+        kw: dict[str, Any] = dict(
+            endpoint=self.endpoint,
+            deployment=self.deployment,
+            semantics=self.semantics or "unknown",
+            zenoh_mode=self.zenoh_mode,
+        )
+        kw.update(overrides)
+        return RemoteInferenceConfig(**kw)
+
+    def connect(self, **overrides: Any):
+        """A connected, admitted `lerobot.remote_inference.RemoteClient` for this lease."""
+        _lerobot()
+        from lerobot.remote_inference import RemoteClient
+
+        config = self.config(**overrides)
+        client = RemoteClient.connect(config)
+        try:
+            caps = client.capabilities
+            semantics = client.descriptor.get("semantics") or config.semantics
+            client.admit(
+                features=caps.features,
+                action_feature=caps.action_feature,
+                semantics=semantics,
+                action_interval=caps.action_interval,
+                mode=config.mode,
+            )
+        except Exception:
+            client.close()
+            raise
+        self._client = client
+        return client
+
+    def policy(self, **settings: Any):
+        """A strands-robots policy for this lease: `arm.run(session.policy(), seconds=30)`."""
+        try:
+            from strands_robots.policy.lerobot import ZenohPolicy
+        except ImportError:
+            raise MissingDependency(
+                "Run `pip install strands-robots`; session.policy() returns a strands-robots ZenohPolicy.",
+                error="missing_dependency",
+            ) from None
+        settings.setdefault("zenoh_mode", self.zenoh_mode)
+        return ZenohPolicy(endpoint=self.endpoint, deployment=self.deployment, **settings)
+
+    def features(self) -> tuple:
+        """The deployment's observation features (name, shape, dtype, kind), from the server descriptor."""
+        client = self._client or self.connect(chunk_merge="append")
+        return client.capabilities.features
+
+    def synthetic_observation(self) -> dict:
+        """Zeros for every feature the deployment expects — what `agi run --probe` sends."""
+        import numpy as np
+
+        client = self._client or self.connect(chunk_merge="append")
+        obs = {}
+        for f in client.capabilities.features:
+            obs[f.name] = np.zeros(tuple(f.shape), dtype=f.dtype)
+        return obs
+
+    def predict(self, observation: dict, task: str = "", *, timeout_s: float | None = None):
+        """One observation in, one action chunk out: `np.ndarray [n_action_steps, dof]`.
+
+        `observation` is keyed by the deployment's feature names, e.g.
+        `{"observation.state": float32[6], "observation.images.front": uint8[H, W, 3]}`.
+        """
+        _lerobot()
+        import numpy as np
+        from lerobot.inference import ChunkRequest, ExecutionMode, ObservationSnapshot
+        from lerobot.policies.rtc.action_queue import QueueSnapshot
+
+        client = self._client or self.connect(chunk_merge="append")
+        caps = client.capabilities
+        features = {}
+        for spec in caps.features:
+            if spec.name not in observation:
+                raise KeyError(f"Observation is missing {spec.name!r}; the deployment expects {[f.name for f in caps.features]}.")
+            features[spec.name] = np.ascontiguousarray(np.asarray(observation[spec.name]), dtype=spec.dtype)
+        aligned = client.chunk_settings.get("chunk_merge") == "aligned"
+        snapshot = ObservationSnapshot(
+            features=features,
+            capture_time=time.monotonic(),
+            task=task,
+            observation_id=uuid4().hex,
+            action_cursor=0 if aligned else None,
+        )
+        continuation = QueueSnapshot(generation=client.generation, cursor=0, index=0, model_actions=None, canonical_actions=None, provenance=())
+        request = ChunkRequest(
+            observation=snapshot,
+            continuation=continuation,
+            request_id=uuid4().hex,
+            generation=client.generation,
+            mode=ExecutionMode.CHUNK,
+            delay=0,
+            submitted_at=time.monotonic(),
+        )
+        if timeout_s is not None:
+            client.config.action_timeout_s = float(timeout_s)
+        chunk = client.infer(request)
+        return chunk.canonical_actions.numpy()
+
+    # --- lifecycle ----------------------------------------------------------
+    def refresh(self) -> dict:
+        self.lease = _http.request("GET", f"/v1/sessions/{self.id}", key=self._key)
+        return self.lease
+
+    def close(self) -> dict | None:
+        """End the lease (DELETE /v1/sessions/:id) and the zenoh session, if any. Idempotent."""
+        if self._closed:
+            return None
+        self._closed = True
+        if self._client is not None:
+            try:
+                self._client.close()
+            finally:
+                self._client = None
+        try:
+            return _http.request("DELETE", f"/v1/sessions/{self.id}", key=self._key)
+        except Exception:
+            return None
+
+    def __enter__(self) -> "Policy":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"agi.Policy({self.model!r}, deployment={self.deployment!r}, endpoint={self.endpoint!r})"

agi_diy-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agi-diy"
+version = "0.1.0"
+description = "api.agi.diy client: lease a VLA policy, run it over the LeRobot remote-inference protocol."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "agi.diy" }]
+dependencies = []
+
+[project.optional-dependencies]
+lerobot = ["lerobot[remote]>=0.6", "numpy"]
+dev = ["pytest"]
+
+[project.scripts]
+agi = "agi.cli:main"
+
+[project.urls]
+Homepage = "https://api.agi.diy"
+Source = "https://github.com/cagataycali/api-agi-diy"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agi"]

agi_diy-0.1.0/tests/README.md

@@ -0,0 +1,10 @@
+# tests
+
+```
+uv venv .venv && source .venv/bin/activate
+uv pip install -e ".[dev]"                       # REST tests only (fake Worker on http.server)
+uv pip install -e "/path/to/lerobot[remote]"     # + zenoh loopback tests (real lerobot PolicyServer over ws/)
+PYTHONPATH=tests pytest -q
+```
+
+`test_zenoh_loopback.py` skips without `lerobot[remote]`.

agi_diy-0.1.0/tests/conftest.py

@@ -0,0 +1,16 @@
+import os
+import pytest
+
+from fake_worker import KEY, serve
+
+
+@pytest.fixture
+def worker(monkeypatch, tmp_path):
+    url, state, stop = serve()
+    monkeypatch.setenv("AGI_API_URL", url)
+    monkeypatch.setenv("AGI_API_KEY", KEY)
+    monkeypatch.setenv("AGI_CREDENTIALS", str(tmp_path / "credentials"))
+    import importlib, agi._http
+    importlib.reload(agi._http)
+    yield state
+    stop()

agi_diy-0.1.0/tests/fake_worker.py

@@ -0,0 +1,111 @@
+"""A tiny api.agi.diy stand-in (docs/CONTRACT.md v0) on http.server, for REST tests."""
+
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+KEY = "agi_sk_live_" + "a" * 32
+MODEL = {
+    "id": "act/so101", "family": "act", "robot": "so101", "semantics": "so101-degrees-gripper-percent-v1",
+    "action_horizon": 50, "fps": 30, "cameras": ["front"], "slots_free": 1, "slots_total": 1, "state": "ready",
+}
+
+
+class State:
+    def __init__(self):
+        self.sessions: dict[str, dict] = {}
+        self.free = 1
+        self.credits = 200_000
+        self.requests: list[tuple[str, str, dict | None]] = []
+
+
+def make_handler(state: State):
+    class H(BaseHTTPRequestHandler):
+        def log_message(self, *a):  # quiet
+            pass
+
+        def _json(self, code, body):
+            raw = json.dumps(body).encode()
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(raw)))
+            self.end_headers()
+            self.wfile.write(raw)
+
+        def _body(self):
+            n = int(self.headers.get("Content-Length") or 0)
+            return json.loads(self.rfile.read(n)) if n else None
+
+        def _auth(self):
+            return self.headers.get("Authorization") == f"Bearer {KEY}"
+
+        def do_GET(self):
+            path = self.path.split("?")[0]
+            state.requests.append(("GET", path, None))
+            if path == "/v1/health":
+                return self._json(200, {"ok": True, "runners": 1, "time": "2026-10-24T00:00:00Z"})
+            if not self._auth():
+                return self._json(401, {"error": "unauthorized", "message": "Missing or invalid API key."})
+            if path == "/v1/models":
+                return self._json(200, {"models": [MODEL]})
+            if path == "/v1/me":
+                return self._json(200, {"id": "u_1", "login": "tester", "credits_tokens": state.credits})
+            if path == "/v1/usage":
+                return self._json(200, {"credits_tokens": state.credits, "tokens_used": 0, "calls": 0, "by_model": [], "events": []})
+            if path.startswith("/v1/sessions/"):
+                s = state.sessions.get(path.rsplit("/", 1)[1])
+                return self._json(200, s) if s else self._json(404, {"error": "not_found", "message": "No such session."})
+            if path == "/v1/sessions":
+                return self._json(200, {"sessions": list(state.sessions.values())})
+            self._json(404, {"error": "not_found", "message": "No such route."})
+
+        def do_POST(self):
+            body = self._body()
+            state.requests.append(("POST", self.path, body))
+            if not self._auth():
+                return self._json(401, {"error": "unauthorized", "message": "Missing or invalid API key."})
+            if self.path == "/v1/sessions":
+                if body.get("model") != MODEL["id"]:
+                    return self._json(404, {"error": "unknown_model", "message": "Model not found; see GET /v1/models."})
+                if state.credits <= 0:
+                    return self._json(402, {"error": "insufficient_credits", "message": "Credits are at zero; top up at https://api.agi.diy/dashboard."})
+                if state.free <= 0:
+                    return self._json(409, {"error": "no_slots", "message": "All slots are busy; retry in 5 s.", "retry_after_s": 5})
+                state.free -= 1
+                sid = f"ses_{len(state.sessions)+1:022d}"
+                s = {
+                    "id": sid, "model": MODEL["id"], "state": "leased", "deployment": "d_test0000000000000000ab", "runner": "thor",
+                    "zenoh": {"endpoint": "ws/zenoh.api.agi.diy:80", "endpoints": ["ws/zenoh.api.agi.diy:80", "tcp/1.2.3.4:7447"], "mode": "client"},
+                    "semantics": MODEL["semantics"], "features": {}, "action_horizon": 50, "fps": 30,
+                    "created_at": "2026-10-24T00:00:00Z", "expires_at": "2026-10-24T00:10:00Z", "ended_at": None,
+                    "end_reason": None, "tokens_used": 0,
+                }
+                state.sessions[sid] = s
+                return self._json(201, s)
+            self._json(404, {"error": "not_found", "message": "No such route."})
+
+        def do_DELETE(self):
+            state.requests.append(("DELETE", self.path, None))
+            if not self._auth():
+                return self._json(401, {"error": "unauthorized", "message": "Missing or invalid API key."})
+            sid = self.path.rsplit("/", 1)[1]
+            s = state.sessions.get(sid)
+            if not s:
+                return self._json(404, {"error": "not_found", "message": "No such session."})
+            if s["state"] != "ended":
+                s["state"], s["end_reason"] = "ended", "client_done"
+                state.free += 1
+            self._json(200, s)
+
+    return H
+
+
+def serve():
+    """Start on a free port; returns (base_url, state, shutdown)."""
+    state = State()
+    srv = ThreadingHTTPServer(("127.0.0.1", 0), make_handler(state))
+    t = threading.Thread(target=srv.serve_forever, daemon=True)
+    t.start()
+    return f"http://127.0.0.1:{srv.server_port}", state, srv.shutdown

agi_diy-0.1.0/tests/loopback_server.py

@@ -0,0 +1,110 @@
+"""A real lerobot PolicyServer on a local zenoh ws listener, serving a tiny deterministic policy."""
+
+from __future__ import annotations
+
+import socket
+from collections import deque
+from threading import Event, Thread
+
+import torch
+from lerobot.configs.types import FeatureType, NormalizationMode, PolicyFeature
+from lerobot.inference import FeatureSpec, PolicyRunner
+from lerobot.policies.act.configuration_act import ACTConfig
+from lerobot.policies.act.processor_act import make_act_pre_post_processors
+from lerobot.policies.pretrained import PreTrainedPolicy
+from lerobot.remote_inference.server import PolicyServer, SessionWorker
+from lerobot.transport.zenoh import ZenohConfig, ZenohTransport
+from lerobot.utils.constants import ACTION, OBS_ENV_STATE, OBS_STATE
+
+SEMANTICS = "so101-degrees-gripper-percent-v1"
+NAMES = ("shoulder.pos", "elbow.pos", "gripper.pos")
+
+
+class TinyPolicy(PreTrainedPolicy):
+    config_class = ACTConfig
+    name = "tiny"
+
+    def __init__(self, config):
+        super().__init__(config)
+        self.reset()
+
+    def get_optim_params(self):
+        return {}
+
+    def reset(self):
+        self._action_queue = deque()
+
+    def forward(self, batch):
+        raise NotImplementedError
+
+    def select_action(self, batch, **kwargs):
+        raise AssertionError("the runner must not call select_action")
+
+    def predict_action_chunk(self, batch, **kwargs):
+        return torch.arange(24, dtype=torch.float32).reshape(1, 8, 3)
+
+
+def free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def serve(deployment: str = "d_loopback", link: str = "ws"):
+    """Start a server thread; returns (endpoint, stop)."""
+    config = ACTConfig(
+        input_features={
+            OBS_STATE: PolicyFeature(type=FeatureType.STATE, shape=(3,)),
+            OBS_ENV_STATE: PolicyFeature(type=FeatureType.ENV, shape=(3,)),
+        },
+        output_features={ACTION: PolicyFeature(type=FeatureType.ACTION, shape=(3,))},
+        normalization_mapping={
+            FeatureType.STATE: NormalizationMode.MEAN_STD,
+            FeatureType.ENV: NormalizationMode.IDENTITY,
+            FeatureType.ACTION: NormalizationMode.MEAN_STD,
+        },
+        chunk_size=8,
+        n_action_steps=8,
+        dim_model=16,
+        n_heads=2,
+        dim_feedforward=32,
+        n_encoder_layers=1,
+        n_decoder_layers=1,
+        vision_backbone="resnet18",
+        pretrained_backbone_weights=None,
+        device="cpu",
+    )
+    stats = {
+        OBS_STATE: {"mean": torch.zeros(3), "std": torch.ones(3)},
+        ACTION: {"mean": torch.tensor([1.0, 2.0, 3.0]), "std": torch.ones(3) * 2},
+    }
+    pre, post = make_act_pre_post_processors(config, stats)
+    runner = PolicyRunner(
+        TinyPolicy(config), pre, post, action_interval=1 / 30,
+        features=tuple(FeatureSpec(k, (3,), "float32", names=NAMES, semantics=SEMANTICS) for k in (OBS_STATE, OBS_ENV_STATE)),
+        action_feature=FeatureSpec(ACTION, (3,), "float32", names=NAMES, semantics=SEMANTICS),
+    )
+    worker = SessionWorker(runner, deployment=deployment, artifact_identity="tiny-loopback", semantics=SEMANTICS)
+    endpoint = f"{link}/127.0.0.1:{free_port()}"
+    transport = ZenohTransport(ZenohConfig(listen_endpoints=[endpoint]))
+    server = PolicyServer(worker, transport)
+    ready = Event()
+    original = transport.declare_token
+
+    def declare_token(key):
+        token = original(key)
+        ready.set()
+        return token
+
+    transport.declare_token = declare_token
+    thread = Thread(target=server.serve, daemon=True)
+    thread.start()
+    assert ready.wait(30), "loopback server did not advertise readiness"
+
+    def stop():
+        server.stop()
+        thread.join(10)
+        transport.close()
+        worker.close()
+
+    return endpoint, stop

agi_diy-0.1.0/tests/test_rest.py

@@ -0,0 +1,100 @@
+import os
+import subprocess
+import sys
+
+import pytest
+
+import agi
+from agi import _http
+from fake_worker import KEY
+
+
+def test_models_me_usage_health(worker):
+    assert agi.models()[0]["id"] == "act/so101"
+    assert agi.me()["login"] == "tester"
+    assert agi.usage()["credits_tokens"] == 200_000
+    assert agi.health()["ok"] is True
+    assert ("GET", "/v1/health", None) in worker.requests
+
+
+def test_policy_lease_and_close(worker):
+    with agi.Policy("act/so101", ttl_s=120) as s:
+        assert s.endpoint == "ws/zenoh.api.agi.diy:80"
+        assert s.endpoints[1] == "tcp/1.2.3.4:7447"
+        assert s.deployment.startswith("d_")
+        assert s.zenoh_mode == "client"
+        assert s.url == "zenoh+ws://zenoh.api.agi.diy:80/d_test0000000000000000ab"
+        assert "--inference.endpoint=ws/zenoh.api.agi.diy:80" in s.rollout_args()
+        assert f"--inference.deployment={s.deployment}" in s.rollout_args()
+        assert "--inference.semantics=so101-degrees-gripper-percent-v1" in s.rollout_args()
+        assert worker.requests[-1] == ("POST", "/v1/sessions", {"model": "act/so101", "ttl_s": 120})
+    assert worker.requests[-1] == ("DELETE", f"/v1/sessions/{s.id}", None)
+    assert worker.free == 1
+    assert s.close() is None  # idempotent
+
+
+def test_errors(worker, monkeypatch):
+    with pytest.raises(agi.UnknownModel) as e:
+        agi.Policy("nope/so101")
+    assert e.value.error == "unknown_model" and e.value.status == 404
+
+    worker.free = 0
+    with pytest.raises(agi.NoSlots) as e:
+        agi.Policy("act/so101")
+    assert e.value.retry_after_s == 5 and e.value.retryable
+
+    worker.free, worker.credits = 1, 0
+    with pytest.raises(agi.InsufficientCredits):
+        agi.Policy("act/so101")
+
+    monkeypatch.setenv("AGI_API_KEY", "agi_sk_live_wrong")
+    with pytest.raises(agi.AuthError) as e:
+        agi.models()
+    assert "agi login" in str(e.value)
+
+    monkeypatch.delenv("AGI_API_KEY")
+    with pytest.raises(agi.AuthError):
+        agi.models()
+
+
+def test_credentials_file(worker, monkeypatch, tmp_path):
+    monkeypatch.delenv("AGI_API_KEY")
+    path = _http.write_credentials(KEY, os.environ["AGI_API_URL"])
+    assert path == tmp_path / "credentials"
+    assert oct(path.stat().st_mode & 0o777) == "0o600"
+    assert path.read_text().splitlines()[0] == f"AGI_API_KEY={KEY}"
+    assert agi.me()["login"] == "tester"
+
+
+def test_missing_lerobot_names_fix(worker, monkeypatch):
+    import builtins
+    real = builtins.__import__
+
+    def fake(name, *a, **k):
+        if name.startswith("lerobot"):
+            raise ImportError(name)
+        return real(name, *a, **k)
+
+    monkeypatch.setattr(builtins, "__import__", fake)
+    s = agi.Policy("act/so101")
+    with pytest.raises(agi.MissingDependency) as e:
+        s.connect()
+    assert "agi-diy[lerobot]" in str(e.value)
+    s.close()
+
+
+def _cli(*args):
+    return subprocess.run([sys.executable, "-m", "agi.cli", *args], capture_output=True, text=True, env=os.environ)
+
+
+def test_cli(worker):
+    r = _cli("models")
+    assert r.returncode == 0 and "act/so101" in r.stdout and "ready" in r.stdout
+    r = _cli("session", "act/so101")
+    assert r.returncode == 0 and "ws/zenoh.api.agi.diy:80" in r.stdout and worker.free == 1
+    r = _cli("login", "--key", KEY, "--url", os.environ["AGI_API_URL"])
+    assert r.returncode == 0 and "tester" in r.stdout, r.stderr
+    r = _cli("login", "--key", "agi_sk_live_bad")
+    assert r.returncode == 1 and "agi login" in r.stderr
+    r = _cli("usage")
+    assert r.returncode == 0 and "credits 200000" in r.stdout

agi_diy-0.1.0/tests/test_zenoh_loopback.py

@@ -0,0 +1,66 @@
+"""End-to-end against fakes: fake Worker leases a slot whose endpoint is a REAL lerobot PolicyServer over zenoh ws."""
+
+import numpy as np
+import pytest
+
+pytest.importorskip("zenoh")
+pytest.importorskip("lerobot.remote_inference")
+
+import agi
+from loopback_server import SEMANTICS, serve
+
+
+@pytest.fixture(scope="module")
+def server():
+    endpoint, stop = serve(deployment="d_loopback", link="ws")
+    yield endpoint
+    stop()
+
+
+def test_predict_one_shot(worker, server, monkeypatch):
+    # Patch the fake's lease to point at the loopback server (ws link, zenoh client mode).
+    import fake_worker
+    monkeypatch.setitem(fake_worker.MODEL, "semantics", SEMANTICS)
+    session = agi.Policy("act/so101")
+    session.lease["zenoh"] = {"endpoint": server, "endpoints": [server], "mode": "client"}
+    session.lease["deployment"] = "d_loopback"
+    assert session.endpoint.startswith("ws/127.0.0.1:")
+    with session:
+        obs = session.synthetic_observation()
+        assert set(obs) == {"observation.state", "observation.environment_state"}
+        actions = session.predict(obs, task="probe")
+        assert isinstance(actions, np.ndarray)
+        assert actions.shape == (8, 3) and actions.dtype == np.float32
+        # tiny policy: arange(24) de-normalized with mean [1,2,3], std 2 -> [1,4,7], [7,10,13], ...
+        np.testing.assert_allclose(actions[0], [1.0, 4.0, 7.0])
+        np.testing.assert_allclose(actions[1], [7.0, 10.0, 13.0])
+        again = session.predict(obs, task="probe")
+        assert again.shape == (8, 3)
+    assert worker.free == 1
+
+
+def test_connect_returns_admitted_client(worker, server, monkeypatch):
+    import fake_worker
+    monkeypatch.setitem(fake_worker.MODEL, "semantics", SEMANTICS)
+    session = agi.Policy("act/so101")
+    session.lease["zenoh"] = {"endpoint": server, "endpoints": [server], "mode": "client"}
+    session.lease["deployment"] = "d_loopback"
+    client = session.connect()
+    try:
+        assert client.session_id  # admitted
+        assert client.descriptor["deployment"] == "d_loopback"
+        assert [f.name for f in client.capabilities.features] == ["observation.state", "observation.environment_state"]
+        assert session.config().zenoh_mode == "client"
+    finally:
+        session.close()
+
+
+def test_wrong_deployment_names_fix(worker, server, monkeypatch):
+    import fake_worker
+    monkeypatch.setitem(fake_worker.MODEL, "semantics", SEMANTICS)
+    session = agi.Policy("act/so101")
+    session.lease["zenoh"] = {"endpoint": server, "endpoints": [server], "mode": "client"}
+    session.lease["deployment"] = "d_nope"
+    with pytest.raises(TimeoutError, match="did not answer discovery"):
+        session.connect(handshake_timeout_s=1.5)
+    session.close()