hypercli-sdk 0.9.0__tar.gz → 1.0.0__tar.gz

{hypercli_sdk-0.9.0 → hypercli_sdk-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypercli-sdk
-Version: 0.9.0
+Version: 1.0.0
 Summary: Python SDK for HyperCLI - GPU orchestration and LLM API
 Project-URL: Homepage, https://hypercli.com
 Project-URL: Documentation, https://docs.hypercli.com

{hypercli_sdk-0.9.0 → hypercli_sdk-1.0.0}/hypercli/__init__.py

@@ -9,10 +9,10 @@ from .x402 import X402Client, X402JobLaunch, X402FlowCreate, X402RenderCreate, F
 from .files import File, AsyncFiles
 from .job import BaseJob, ComfyUIJob, GradioJob, apply_params, apply_graph_modes, find_node, find_nodes, load_template, graph_to_api, expand_subgraphs, DEFAULT_OBJECT_INFO
 from .logs import LogStream, stream_logs, fetch_logs
-from .agents import Agents, ReefPod, ExecResult
+from .shell import ShellSession, shell_connect
 from .claw import Claw, ClawKey, ClawPlan, ClawModel
 
-__version__ = "0.8.9"
+__version__ = "1.0.0"
 __all__ = [
     "HyperCLI",
     "configure",
@@ -65,10 +65,9 @@ __all__ = [
     "LogStream",
     "stream_logs",
     "fetch_logs",
-    # Agents (Reef Pods)
-    "Agents",
-    "ReefPod",
-    "ExecResult",
+    # Shell
+    "ShellSession",
+    "shell_connect",
     # HyperClaw
     "Claw",
     "ClawKey",

{hypercli_sdk-0.9.0 → hypercli_sdk-1.0.0}/hypercli/client.py

@@ -7,7 +7,6 @@ from .user import UserAPI
 from .instances import Instances
 from .renders import Renders
 from .files import Files
-from .agents import Agents
 from .claw import Claw
 from .keys import KeysAPI
 
@@ -51,7 +50,6 @@ class HyperCLI:
         self._http = HTTPClient(self._api_url, self._api_key)
 
         # API namespaces
-        self.agents = Agents(self._http, claw_api_key=claw_api_key)
         self.billing = Billing(self._http)
         self.jobs = Jobs(self._http)
         self.user = UserAPI(self._http)

{hypercli_sdk-0.9.0 → hypercli_sdk-1.0.0}/hypercli/jobs.py

@@ -134,7 +134,6 @@ class Jobs:
         ports: dict[str, int] = None,
         auth: bool = False,
         registry_auth: dict[str, str] = None,
-        dockerfile: str = None,
     ) -> Job:
         """Create a new job.
 
@@ -150,7 +149,6 @@ class Jobs:
             ports: Ports to expose. Use {"lb": port} for HTTPS load balancer
             auth: Enable Bearer token auth on load balancer (use with ports={"lb": port})
             registry_auth: Private registry credentials {"username": "...", "password": "..."}
-            dockerfile: Base64-encoded Dockerfile (overrides docker_image if provided)
         """
         payload = {
             "docker_image": image,
@@ -171,8 +169,6 @@ class Jobs:
             payload["auth"] = auth
         if registry_auth:
             payload["registry_auth"] = registry_auth
-        if dockerfile:
-            payload["dockerfile"] = dockerfile
 
         data = self._http.post("/api/jobs", json=payload)
         return Job.from_dict(data)

hypercli_sdk-1.0.0/hypercli/shell.py

@@ -0,0 +1,124 @@
+"""Interactive shell over WebSocket for running job containers.
+
+SDK-level: async WebSocket client that connects to the director's
+/orchestra/ws/shell/{job_id}?token={job_key} endpoint.
+
+Protocol (text frames):
+  Client → Server:  raw stdin text, or xterm resize "\x1b[8;{rows};{cols}t"
+  Server → Client:  raw stdout/stderr text
+"""
+import asyncio
+from typing import TYPE_CHECKING, Callable, Optional
+
+import websockets
+
+from .config import get_ws_url
+
+if TYPE_CHECKING:
+    from .client import HyperCLI
+
+WS_SHELL_PATH = "/orchestra/ws/shell"
+
+
+async def shell_connect(
+    client: "HyperCLI",
+    job_id: str,
+    job_key: str = None,
+    shell: str = "/bin/bash",
+    on_output: Callable[[str], None] = None,
+    on_close: Callable[[str], None] = None,
+) -> "ShellSession":
+    """Connect to a running job's shell via WebSocket.
+
+    Args:
+        client: HyperCLI client instance
+        job_id: Job ID
+        job_key: Job key for auth (fetched if None)
+        shell: Shell executable (default: /bin/bash)
+        on_output: Callback for output data
+        on_close: Callback when shell closes (receives reason string)
+
+    Returns:
+        ShellSession object for sending input and managing the connection.
+    """
+    if not job_key:
+        job = client.jobs.get(job_id)
+        job_key = job.job_key
+
+    ws_url = get_ws_url()
+    url = f"{ws_url}{WS_SHELL_PATH}/{job_id}?token={job_key}&shell={shell}"
+
+    ws = await websockets.connect(
+        url,
+        ping_interval=30,
+        ping_timeout=20,
+        close_timeout=5,
+        max_size=2**20,
+        compression=None,
+    )
+
+    session = ShellSession(ws, on_output=on_output, on_close=on_close)
+    session._reader_task = asyncio.create_task(session._read_loop())
+    return session
+
+
+class ShellSession:
+    """Async WebSocket shell session."""
+
+    def __init__(
+        self,
+        ws,
+        on_output: Callable[[str], None] = None,
+        on_close: Callable[[str], None] = None,
+    ):
+        self._ws = ws
+        self._on_output = on_output
+        self._on_close = on_close
+        self._reader_task: Optional[asyncio.Task] = None
+        self._closed = False
+
+    async def send(self, data: str):
+        """Send stdin data to the shell."""
+        if not self._closed:
+            await self._ws.send(data)
+
+    async def resize(self, cols: int, rows: int):
+        """Send terminal resize."""
+        if not self._closed:
+            await self._ws.send(f"\x1b[8;{rows};{cols}t")
+
+    async def close(self):
+        """Close the shell session."""
+        self._closed = True
+        if self._reader_task:
+            self._reader_task.cancel()
+        try:
+            await self._ws.close()
+        except Exception:
+            pass
+
+    async def _read_loop(self):
+        """Read output from WebSocket and dispatch to callback."""
+        try:
+            async for message in self._ws:
+                if self._closed:
+                    break
+                if isinstance(message, bytes):
+                    message = message.decode(errors="replace")
+                if self._on_output:
+                    self._on_output(message)
+        except websockets.ConnectionClosed as e:
+            reason = e.reason or f"code {e.code}"
+            if self._on_close and not self._closed:
+                self._on_close(reason)
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            if self._on_close and not self._closed:
+                self._on_close(str(e))
+        finally:
+            self._closed = True
+
+    @property
+    def closed(self) -> bool:
+        return self._closed

{hypercli_sdk-0.9.0 → hypercli_sdk-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypercli-sdk"
-version = "0.9.0"
+version = "1.0.0"
 description = "Python SDK for HyperCLI - GPU orchestration and LLM API"
 readme = "README.md"
 requires-python = ">=3.10"

hypercli_sdk-0.9.0/hypercli/agents.py

@@ -1,417 +0,0 @@
-"""
-HyperClaw Agents API — Reef Pod Management
-
-Client for HyperClaw backend agent endpoints. Manages OpenClaw desktop containers
-(reef pods) via the authenticated backend API at api.hyperclaw.app/api/agents.
-
-The backend proxies to Lagoon internally, handles auth, plan enforcement,
-runtime key generation, and DB persistence.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import datetime
-from typing import Optional, Any
-
-import httpx
-
-from .http import HTTPClient, APIError
-
-
-CLAW_API_BASE = "https://api.hyperclaw.app"
-
-
-@dataclass
-class ReefPod:
-    """A reef pod (OpenClaw desktop container)."""
-    id: str  # Agent UUID from backend
-    user_id: str
-    pod_id: str
-    pod_name: str
-    state: str
-    hostname: Optional[str] = None
-    jwt_token: Optional[str] = None
-    jwt_expires_at: Optional[datetime] = None
-    started_at: Optional[datetime] = None
-    stopped_at: Optional[datetime] = None
-    last_error: Optional[str] = None
-    created_at: Optional[datetime] = None
-    updated_at: Optional[datetime] = None
-
-    @classmethod
-    def from_dict(cls, data: dict) -> ReefPod:
-        def _parse_dt(val):
-            if isinstance(val, str) and val:
-                return datetime.fromisoformat(val.replace("Z", "+00:00"))
-            return None
-
-        return cls(
-            id=data.get("id", ""),
-            user_id=data.get("user_id", ""),
-            pod_id=data.get("pod_id", ""),
-            pod_name=data.get("pod_name", ""),
-            state=data.get("state", "unknown"),
-            hostname=data.get("hostname"),
-            jwt_token=data.get("jwt_token"),
-            jwt_expires_at=_parse_dt(data.get("jwt_expires_at")),
-            started_at=_parse_dt(data.get("started_at")),
-            stopped_at=_parse_dt(data.get("stopped_at")),
-            last_error=data.get("last_error"),
-            created_at=_parse_dt(data.get("created_at")),
-            updated_at=_parse_dt(data.get("updated_at")),
-        )
-
-    @property
-    def vnc_url(self) -> Optional[str]:
-        if self.hostname:
-            return f"https://{self.hostname}"
-        return None
-
-    @property
-    def shell_url(self) -> Optional[str]:
-        if self.hostname:
-            return f"https://shell-{self.hostname}"
-        return None
-
-    @property
-    def executor_url(self) -> Optional[str]:
-        return self.shell_url
-
-    @property
-    def is_running(self) -> bool:
-        return self.state == "running"
-
-
-@dataclass
-class ExecResult:
-    """Result of a one-shot command execution."""
-    exit_code: int
-    stdout: str
-    stderr: str
-
-    @classmethod
-    def from_dict(cls, data: dict) -> ExecResult:
-        return cls(
-            exit_code=data.get("exit_code", -1),
-            stdout=data.get("stdout", ""),
-            stderr=data.get("stderr", ""),
-        )
-
-
-class Agents:
-    """
-    HyperClaw Agents API — manage reef pods (OpenClaw desktop containers).
-
-    Uses the authenticated backend API (api.hyperclaw.app/api/agents).
-    Auth: pass your HyperClaw API key (sk-...) as the claw_api_key.
-
-    Usage:
-        from hypercli import HyperCLI
-        client = HyperCLI(api_key="...", claw_api_key="sk-...")
-
-        # Launch
-        pod = client.agents.create()
-        print(f"Desktop: {pod.vnc_url}")
-
-        # Execute a command
-        result = client.agents.exec(pod, "echo hello")
-
-        # List
-        pods = client.agents.list()
-
-        # Stop
-        client.agents.stop(pod.id)
-    """
-
-    def __init__(self, http: HTTPClient, claw_api_key: str = None, claw_api_base: str = None):
-        self._http = http
-        self._api_key = claw_api_key or http.api_key
-        self._api_base = (claw_api_base or CLAW_API_BASE).rstrip("/")
-
-    @property
-    def _headers(self) -> dict:
-        return {
-            "Authorization": f"Bearer {self._api_key}",
-            "Content-Type": "application/json",
-        }
-
-    def _get(self, path: str, params: dict = None) -> Any:
-        with httpx.Client(timeout=30) as client:
-            resp = client.get(f"{self._api_base}{path}", headers=self._headers, params=params)
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json().get("detail", resp.text)
-            except Exception:
-                detail = resp.text
-            raise APIError(resp.status_code, detail)
-        return resp.json()
-
-    def _post(self, path: str, json: dict = None) -> Any:
-        with httpx.Client(timeout=30) as client:
-            resp = client.post(f"{self._api_base}{path}", headers=self._headers, json=json)
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json().get("detail", resp.text)
-            except Exception:
-                detail = resp.text
-            raise APIError(resp.status_code, detail)
-        return resp.json()
-
-    def _delete(self, path: str) -> Any:
-        with httpx.Client(timeout=30) as client:
-            resp = client.delete(f"{self._api_base}{path}", headers=self._headers)
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json().get("detail", resp.text)
-            except Exception:
-                detail = resp.text
-            raise APIError(resp.status_code, detail)
-        return resp.json()
-
-    # -----------------------------------------------------------------------
-    # Agent lifecycle (HyperClaw backend → Lagoon)
-    # -----------------------------------------------------------------------
-
-    def create(self, config: dict = None) -> ReefPod:
-        """Create a new agent (provisions a reef pod via the backend).
-
-        The backend handles: auth, plan enforcement, runtime key generation,
-        Lagoon pod creation, and DB persistence.
-
-        Args:
-            config: Optional config overrides.
-
-        Returns:
-            ReefPod with connection details.
-        """
-        data = self._post("/api/agents", json={"config": config or {}})
-        return ReefPod.from_dict(data)
-
-    def list(self) -> list[ReefPod]:
-        """List all agents for the authenticated user.
-
-        Returns:
-            List of ReefPod objects.
-        """
-        data = self._get("/api/agents")
-        items = data.get("items", data) if isinstance(data, dict) else data
-        return [ReefPod.from_dict(p) for p in items]
-
-    def get(self, agent_id: str) -> ReefPod:
-        """Get agent details by ID (refreshes status from Lagoon).
-
-        Args:
-            agent_id: Agent UUID.
-
-        Returns:
-            ReefPod with current status.
-        """
-        data = self._get(f"/api/agents/{agent_id}")
-        return ReefPod.from_dict(data)
-
-    def start(self, agent_id: str) -> ReefPod:
-        """Start a previously stopped agent.
-
-        Args:
-            agent_id: Agent UUID.
-
-        Returns:
-            ReefPod with new pod details.
-        """
-        data = self._post(f"/api/agents/{agent_id}/start")
-        return ReefPod.from_dict(data)
-
-    def stop(self, agent_id: str) -> ReefPod:
-        """Stop an agent (tears down pod, keeps DB record).
-
-        Args:
-            agent_id: Agent UUID.
-
-        Returns:
-            ReefPod in stopped state.
-        """
-        data = self._post(f"/api/agents/{agent_id}/stop")
-        return ReefPod.from_dict(data)
-
-    def delete(self, agent_id: str) -> dict:
-        """Delete an agent entirely (pod + DB record).
-
-        Args:
-            agent_id: Agent UUID.
-
-        Returns:
-            Deletion status dict.
-        """
-        return self._delete(f"/api/agents/{agent_id}")
-
-    def refresh_token(self, agent_id: str) -> dict:
-        """Refresh the JWT token for an agent.
-
-        Args:
-            agent_id: Agent UUID.
-
-        Returns:
-            Dict with agent_id, pod_id, token, expires_at.
-        """
-        return self._get(f"/api/agents/{agent_id}/token")
-
-    # -----------------------------------------------------------------------
-    # Executor API (direct to reef pod via shell-{hostname})
-    # -----------------------------------------------------------------------
-
-    def _executor_headers(self, pod: ReefPod) -> dict:
-        h = {}
-        if pod.jwt_token:
-            h["Authorization"] = f"Bearer {pod.jwt_token}"
-            h["Cookie"] = f"{pod.pod_name}-token={pod.jwt_token}"
-        return h
-
-    def exec(self, pod: ReefPod, command: str, timeout: int = 30) -> ExecResult:
-        """Execute a one-shot command on a reef pod via the executor API.
-
-        Args:
-            pod: ReefPod to execute on (needs jwt_token).
-            command: Shell command to run.
-            timeout: Command timeout in seconds.
-
-        Returns:
-            ExecResult with exit_code, stdout, stderr.
-        """
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL (missing hostname)")
-        with httpx.Client(timeout=max(timeout + 5, 35)) as client:
-            resp = client.post(
-                f"{pod.executor_url}/exec",
-                headers=self._executor_headers(pod),
-                json={"command": command, "timeout": timeout},
-            )
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json().get("detail", resp.text)
-            except Exception:
-                detail = resp.text
-            raise APIError(resp.status_code, detail)
-        return ExecResult.from_dict(resp.json())
-
-    def health(self, pod: ReefPod) -> dict:
-        """Check executor health on a pod."""
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL")
-        with httpx.Client(timeout=10) as client:
-            resp = client.get(
-                f"{pod.executor_url}/health",
-                headers=self._executor_headers(pod),
-            )
-        if resp.status_code >= 400:
-            raise APIError(resp.status_code, resp.text)
-        return resp.json()
-
-    def files_list(self, pod: ReefPod, path: str = ".") -> list[dict]:
-        """List files on a pod."""
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL")
-        with httpx.Client(timeout=10) as client:
-            resp = client.get(
-                f"{pod.executor_url}/files",
-                headers=self._executor_headers(pod),
-                params={"path": path},
-            )
-        if resp.status_code >= 400:
-            raise APIError(resp.status_code, resp.text)
-        return resp.json().get("entries", [])
-
-    def file_read(self, pod: ReefPod, path: str) -> str:
-        """Read a file from a pod."""
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL")
-        with httpx.Client(timeout=10) as client:
-            resp = client.get(
-                f"{pod.executor_url}/files/read",
-                headers=self._executor_headers(pod),
-                params={"path": path},
-            )
-        if resp.status_code >= 400:
-            raise APIError(resp.status_code, resp.text)
-        return resp.text
-
-    def file_write(self, pod: ReefPod, path: str, content: str) -> dict:
-        """Write a file to a pod."""
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL")
-        with httpx.Client(timeout=10) as client:
-            resp = client.put(
-                f"{pod.executor_url}/files/write",
-                headers=self._executor_headers(pod),
-                params={"path": path},
-                content=content.encode(),
-            )
-        if resp.status_code >= 400:
-            raise APIError(resp.status_code, resp.text)
-        return resp.json()
-
-    def chat_stream(self, pod: ReefPod, messages: list[dict], model: str = "hyperclaw/kimi-k2.5"):
-        """Stream chat completions from the pod's OpenClaw gateway via executor proxy.
-
-        Yields content delta strings as they arrive.
-        """
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL")
-
-        body = {
-            "model": model,
-            "messages": messages,
-            "stream": True,
-        }
-
-        with httpx.Client(timeout=300) as client:
-            with client.stream(
-                "POST",
-                f"{pod.executor_url}/chat",
-                headers=self._executor_headers(pod),
-                json=body,
-            ) as resp:
-                if resp.status_code >= 400:
-                    raise APIError(resp.status_code, resp.read().decode())
-                for line in resp.iter_lines():
-                    line = line.strip()
-                    if not line or not line.startswith("data: "):
-                        continue
-                    data = line[6:]
-                    if data == "[DONE]":
-                        break
-                    try:
-                        import json
-                        chunk = json.loads(data)
-                        delta = chunk.get("choices", [{}])[0].get("delta", {})
-                        content = delta.get("content")
-                        if content:
-                            yield content
-                    except (json.JSONDecodeError, IndexError, KeyError):
-                        continue
-
-    def logs_stream(self, pod: ReefPod, lines: int = 100, follow: bool = True):
-        """Stream logs from the pod via executor SSE.
-
-        Yields log lines as they arrive.
-        """
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL")
-
-        params = {"lines": lines, "follow": "true" if follow else "false"}
-
-        with httpx.Client(timeout=None) as client:
-            with client.stream(
-                "GET",
-                f"{pod.executor_url}/logs",
-                headers=self._executor_headers(pod),
-                params=params,
-            ) as resp:
-                if resp.status_code >= 400:
-                    raise APIError(resp.status_code, resp.read().decode())
-                for line in resp.iter_lines():
-                    line = line.strip()
-                    if line.startswith("data: "):
-                        data = line[6:]
-                        if data == "[keepalive]":
-                            continue
-                        yield data