guidinghand 0.1.0__py3-none-any.whl

guidinghand/__init__.py

@@ -0,0 +1,117 @@
+"""The official Python SDK for the GuidingHand API.
+
+```python
+from guidinghand import GuidingHand
+
+client = GuidingHand()  # reads GUIDINGHAND_API_KEY
+session = client.sessions.create()
+print("Send this link:", session["invite_url"])
+client.sessions.wait_for_connection(session["session_id"])
+task = client.tasks.run(
+    session["session_id"],
+    "Turn on Dark Mode",
+    on_question=lambda q: input(q["question"] + " > "),
+    on_approval=lambda a: input(f"Approve {a['action']}? [y/N] ") == "y",
+)
+print(task["status"], task["result"])
+```
+"""
+
+from ._async_client import AsyncGuidingHand
+from ._base import DEFAULT_BASE_URL
+from ._client import GuidingHand
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    GuidingHandError,
+    GuidingHandTimeout,
+    InvalidRequestError,
+    NeedsInput,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    SessionExpired,
+    WebhookVerificationError,
+)
+from ._types import (
+    Agent,
+    AgentPage,
+    ApprovalDecision,
+    ApprovalPending,
+    Deleted,
+    Device,
+    Effort,
+    Event,
+    EventPage,
+    EventType,
+    Metadata,
+    Page,
+    Pending,
+    QuestionPending,
+    Recording,
+    RecordingFrame,
+    Session,
+    SessionPage,
+    SessionStatus,
+    Task,
+    TaskPage,
+    TaskStatus,
+    Webhook,
+    WebhookEvent,
+    WebhookEventType,
+)
+from ._version import __version__
+from ._webhooks import SIGNATURE_HEADER, verify_webhook
+
+__all__ = [
+    "__version__",
+    "GuidingHand",
+    "AsyncGuidingHand",
+    "DEFAULT_BASE_URL",
+    "verify_webhook",
+    "SIGNATURE_HEADER",
+    # errors
+    "GuidingHandError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "APIError",
+    "APIConnectionError",
+    "GuidingHandTimeout",
+    "NeedsInput",
+    "SessionExpired",
+    "WebhookVerificationError",
+    # objects
+    "Agent",
+    "AgentPage",
+    "ApprovalDecision",
+    "ApprovalPending",
+    "Deleted",
+    "Device",
+    "Effort",
+    "Event",
+    "EventPage",
+    "EventType",
+    "Metadata",
+    "Page",
+    "Pending",
+    "QuestionPending",
+    "Recording",
+    "RecordingFrame",
+    "Session",
+    "SessionPage",
+    "SessionStatus",
+    "Task",
+    "TaskPage",
+    "TaskStatus",
+    "Webhook",
+    "WebhookEvent",
+    "WebhookEventType",
+]

guidinghand/_async_client.py

@@ -0,0 +1,428 @@
+"""The asyncio client: ``AsyncGuidingHand``. Same surface as ``GuidingHand``, with ``await``."""
+
+import asyncio
+import inspect
+import time
+from typing import Any, AsyncIterator, Awaitable, Callable, Dict, List, Optional, Set, TypeVar, Union, cast
+
+import httpx
+
+from ._base import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    LONG_POLL_MS,
+    Include,
+    answer_of,
+    api_path,
+    approval_reply,
+    compact,
+    connection_error,
+    decision_of,
+    default_headers,
+    deleted_before,
+    events_timeout,
+    include_param,
+    is_retryable,
+    is_retryable_status,
+    may_have_happened,
+    parse_response,
+    pending_key,
+    resolve_api_key,
+    retry_delay,
+    run_wait_ms,
+    webhook_body,
+)
+from ._errors import ConflictError, GuidingHandError, GuidingHandTimeout, NeedsInput, SessionExpired
+from ._types import (
+    Agent,
+    AgentPage,
+    ApprovalDecision,
+    ApprovalPending,
+    Deleted,
+    Effort,
+    Event,
+    EventPage,
+    Metadata,
+    Pending,
+    QuestionPending,
+    Recording,
+    Session,
+    SessionPage,
+    Task,
+    TaskPage,
+    TaskStatus,
+    Webhook,
+)
+
+__all__ = ["AsyncGuidingHand"]
+
+T = TypeVar("T")
+MaybeAwaitable = Union[T, Awaitable[T]]
+
+
+async def _resolve(value: MaybeAwaitable[T]) -> T:
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+class AsyncGuidingHand:
+    """An asyncio client for the GuidingHand API, with the same resources and methods as ``GuidingHand``.
+
+    ```python
+    async with AsyncGuidingHand() as client:
+        session = await client.sessions.create()
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: Optional[float] = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self._http = httpx.AsyncClient(base_url=self.base_url, headers=default_headers(self.api_key), timeout=timeout)
+        self.agents = AsyncAgents(self)
+        self.sessions = AsyncSessions(self)
+        self.tasks = AsyncTasks(self)
+        self.webhook = AsyncWebhookEndpoint(self)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        timeout: Optional[float] = None,
+        raw: bool = False,
+        deleted_result: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """``deleted_result``: for a DELETE, what to return when a retry gets 404 because an earlier attempt
+        (whose response was lost) already deleted it."""
+        retryable = is_retryable(method, body)
+        attempt = 0
+        earlier_may_have_happened = False
+        while True:
+            try:
+                response = await self._http.request(
+                    method,
+                    path,
+                    params=compact(params) or None,
+                    json=body,
+                    timeout=timeout if timeout is not None else self.timeout,
+                )
+            except httpx.TransportError as e:
+                if retryable and attempt < self.max_retries:
+                    earlier_may_have_happened = True
+                    await asyncio.sleep(retry_delay(attempt))
+                    attempt += 1
+                    continue
+                raise connection_error(method, path, e) from e
+            if retryable and is_retryable_status(response.status_code) and attempt < self.max_retries:
+                earlier_may_have_happened = earlier_may_have_happened or may_have_happened(response)
+                delay = retry_delay(attempt, response)
+                await response.aclose()
+                await asyncio.sleep(delay)
+                attempt += 1
+                continue
+            if deleted_result is not None and deleted_before(method, response, earlier_may_have_happened):
+                return deleted_result
+            return parse_response(method, path, response, raw)
+
+    async def close(self) -> None:
+        """Closes the HTTP connections. The client can't be used afterwards."""
+        await self._http.aclose()
+
+    aclose = close
+
+    async def __aenter__(self) -> "AsyncGuidingHand":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncGuidingHand(base_url={self.base_url!r})"
+
+
+class AsyncAgents:
+    """``client.agents``: see ``guidinghand.GuidingHand.agents``."""
+
+    def __init__(self, client: AsyncGuidingHand) -> None:
+        self._client = client
+
+    async def list(self) -> AgentPage:
+        return cast(AgentPage, await self._client._request("GET", api_path("agents")))
+
+    async def create(
+        self,
+        name: str,
+        agent_id: Optional[str] = None,
+        instructions: Optional[str] = None,
+        effort: Optional[Effort] = None,
+        greeting: Optional[str] = None,
+    ) -> Agent:
+        body = compact(
+            {"name": name, "agent_id": agent_id, "instructions": instructions, "effort": effort, "greeting": greeting}
+        )
+        return cast(Agent, await self._client._request("POST", api_path("agents"), body=body))
+
+    async def retrieve(self, agent_id: str) -> Agent:
+        return cast(Agent, await self._client._request("GET", api_path("agents", agent_id)))
+
+    async def update(self, agent_id: str, **fields: Any) -> Agent:
+        return cast(Agent, await self._client._request("PATCH", api_path("agents", agent_id), body=fields))
+
+    async def delete(self, agent_id: str) -> Deleted:
+        gone = {"object": "agent", "agent_id": agent_id, "deleted": True}
+        return cast(Deleted, await self._client._request("DELETE", api_path("agents", agent_id), deleted_result=gone))
+
+
+class AsyncSessions:
+    """``client.sessions``: see ``guidinghand.GuidingHand.sessions``."""
+
+    def __init__(self, client: AsyncGuidingHand) -> None:
+        self._client = client
+
+    async def create(self, agent_id: Optional[str] = None, metadata: Optional[Metadata] = None) -> Session:
+        body = compact({"agent_id": agent_id, "metadata": metadata})
+        return cast(Session, await self._client._request("POST", api_path("sessions"), body=body))
+
+    async def list(
+        self, agent_id: Optional[str] = None, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> SessionPage:
+        params = {"agent_id": agent_id, "limit": limit, "cursor": cursor}
+        return cast(SessionPage, await self._client._request("GET", api_path("sessions"), params=params))
+
+    async def list_all(self, agent_id: Optional[str] = None, *, limit: Optional[int] = None) -> AsyncIterator[Session]:
+        cursor: Optional[str] = None
+        while True:
+            page = await self.list(agent_id=agent_id, limit=limit, cursor=cursor)
+            for session in page["data"]:
+                yield session
+            if not page["has_more"] or not page["next_cursor"]:
+                return
+            cursor = page["next_cursor"]
+
+    async def retrieve(self, session_id: str) -> Session:
+        return cast(Session, await self._client._request("GET", api_path("sessions", session_id)))
+
+    async def delete(self, session_id: str) -> Deleted:
+        gone = {"object": "session", "session_id": session_id, "deleted": True}
+        return cast(
+            Deleted, await self._client._request("DELETE", api_path("sessions", session_id), deleted_result=gone)
+        )
+
+    async def wait_for_connection(
+        self, session_id: str, timeout: Optional[float] = 600, poll_interval: float = 3
+    ) -> Session:
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            session = await self.retrieve(session_id)
+            if session["status"] == "connected":
+                return session
+            if session["status"] == "expired":
+                raise SessionExpired(session)
+            remaining = None if deadline is None else deadline - time.monotonic()
+            if remaining is not None and remaining <= 0:
+                raise GuidingHandTimeout(
+                    f"No computer connected to session {session_id} within {timeout:g} s.", session=session
+                )
+            await asyncio.sleep(poll_interval if remaining is None else max(0.0, min(poll_interval, remaining)))
+
+
+class AsyncTasks:
+    """``client.tasks``: see ``guidinghand.GuidingHand.tasks``."""
+
+    def __init__(self, client: AsyncGuidingHand) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        session_id: str,
+        prompt: str,
+        agent_id: Optional[str] = None,
+        request_id: Optional[str] = None,
+        metadata: Optional[Metadata] = None,
+    ) -> Task:
+        body = compact({"prompt": prompt, "agent_id": agent_id, "request_id": request_id, "metadata": metadata})
+        return cast(Task, await self._client._request("POST", api_path("sessions", session_id, "tasks"), body=body))
+
+    async def list(
+        self,
+        session_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        status: Optional[TaskStatus] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> TaskPage:
+        params = {"session_id": session_id, "agent_id": agent_id, "status": status, "limit": limit, "cursor": cursor}
+        return cast(TaskPage, await self._client._request("GET", api_path("tasks"), params=params))
+
+    async def list_all(
+        self,
+        session_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        status: Optional[TaskStatus] = None,
+        *,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[Task]:
+        cursor: Optional[str] = None
+        while True:
+            page = await self.list(session_id=session_id, agent_id=agent_id, status=status, limit=limit, cursor=cursor)
+            for task in page["data"]:
+                yield task
+            if not page["has_more"] or not page["next_cursor"]:
+                return
+            cursor = page["next_cursor"]
+
+    async def retrieve(self, task_id: str, include: Include = None) -> Task:
+        params = {"include": include_param(include)}
+        return cast(Task, await self._client._request("GET", api_path("tasks", task_id), params=params))
+
+    async def events(self, task_id: str, after: int = 0, wait_ms: int = 0) -> EventPage:
+        params = {"after": after, "wait_ms": wait_ms}
+        timeout = events_timeout(self._client.timeout, wait_ms)
+        return cast(
+            EventPage,
+            await self._client._request("GET", api_path("tasks", task_id, "events"), params=params, timeout=timeout),
+        )
+
+    async def respond(
+        self,
+        task_id: str,
+        question_id: Optional[str] = None,
+        answer: Optional[str] = None,
+        approval_id: Optional[str] = None,
+        decision: Optional[Union[str, bool]] = None,
+        note: Optional[str] = None,
+    ) -> Task:
+        body = compact(
+            {
+                "question_id": question_id,
+                "answer": answer,
+                "approval_id": approval_id,
+                "decision": decision_of(decision) if isinstance(decision, bool) else decision,
+                "note": note,
+            }
+        )
+        return cast(Task, await self._client._request("POST", api_path("tasks", task_id, "respond"), body=body))
+
+    async def stop(self, task_id: str) -> Task:
+        return cast(Task, await self._client._request("POST", api_path("tasks", task_id, "stop"), body={}))
+
+    async def recording(self, task_id: str) -> Recording:
+        return cast(Recording, await self._client._request("GET", api_path("tasks", task_id, "recording")))
+
+    async def recording_frame(self, task_id: str, seq: int) -> bytes:
+        return cast(bytes, await self._client._request("GET", api_path("tasks", task_id, "recording", seq), raw=True))
+
+    async def stream(self, task_id: str, after: int = 0) -> AsyncIterator[Event]:
+        """Yields the task's events as they happen, and ends when the task is done (``async for``)."""
+        while True:
+            page = await self.events(task_id, after=after, wait_ms=LONG_POLL_MS)
+            for event in page["data"]:
+                yield event
+            after = page["cursor"]
+            if page["task"]["done"]:
+                return
+
+    async def run(
+        self,
+        session_id: str,
+        prompt: str,
+        *,
+        agent_id: Optional[str] = None,
+        on_event: Optional[Callable[[Event], MaybeAwaitable[Any]]] = None,
+        on_question: Optional[Callable[[QuestionPending], MaybeAwaitable[str]]] = None,
+        on_approval: Optional[Callable[[ApprovalPending], MaybeAwaitable[Union[bool, str, ApprovalDecision]]]] = None,
+        metadata: Optional[Metadata] = None,
+        request_id: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> Task:
+        """Starts a task and drives it to the end: see ``GuidingHand.tasks.run``. Handlers may be async."""
+        deadline = None if timeout is None else time.monotonic() + timeout
+        task = await self.create(session_id, prompt, agent_id=agent_id, request_id=request_id, metadata=metadata)
+        task_id = task["task_id"]
+        after = 0
+        answered: Set[str] = set()
+        while True:
+            wait_ms = run_wait_ms(deadline)
+            if wait_ms is None:
+                try:
+                    task = await self.stop(task_id)
+                except GuidingHandError as e:
+                    raise GuidingHandTimeout(
+                        f"Task {task_id} wasn't done within {timeout:g} s, and stopping it failed: "
+                        "it may still be running.",
+                        task=task,
+                    ) from e
+                if task["done"] and not task.get("interrupted"):
+                    # It finished before the stop reached it: pass on the events not seen yet, and return it.
+                    if on_event is not None:
+                        for event in (await self.events(task_id, after=after))["data"]:
+                            await _resolve(on_event(event))
+                    return task
+                raise GuidingHandTimeout(f"Task {task_id} wasn't done within {timeout:g} s, so it was stopped.", task=task)
+            page = await self.events(task_id, after=after, wait_ms=wait_ms)
+            for event in page["data"]:
+                if on_event is not None:
+                    await _resolve(on_event(event))
+            after = page["cursor"]
+            task = page["task"]
+            if task["done"]:
+                return task
+            pending = task.get("pending")
+            if pending and pending_key(pending) not in answered:
+                await self._answer(task, pending, on_question, on_approval)
+                answered.add(pending_key(pending))
+
+    async def _answer(
+        self,
+        task: Task,
+        pending: Pending,
+        on_question: Optional[Callable[[QuestionPending], MaybeAwaitable[str]]],
+        on_approval: Optional[Callable[[ApprovalPending], MaybeAwaitable[Union[bool, str, ApprovalDecision]]]],
+    ) -> None:
+        reply: Dict[str, Any]
+        if pending["type"] == "question":
+            if on_question is None:
+                raise NeedsInput(task)
+            reply = {"question_id": pending["question_id"], "answer": answer_of(await _resolve(on_question(pending)))}
+        else:
+            if on_approval is None:
+                raise NeedsInput(task)
+            reply = {"approval_id": pending["approval_id"], **approval_reply(await _resolve(on_approval(pending)))}
+        try:
+            await self.respond(task["task_id"], **reply)
+        except ConflictError:
+            pass  # no longer pending (answered elsewhere, or the task ended): the next events call shows where it is
+
+
+class AsyncWebhookEndpoint:
+    """``client.webhook``: see ``guidinghand.GuidingHand.webhook``."""
+
+    def __init__(self, client: AsyncGuidingHand) -> None:
+        self._client = client
+
+    async def retrieve(self) -> Webhook:
+        return cast(Webhook, await self._client._request("GET", "/v1/webhook"))
+
+    async def update(
+        self, url: Optional[str] = None, events: Optional[List[str]] = None, rotate_secret: bool = False
+    ) -> Webhook:
+        """Changes only what you pass (leave ``url`` or ``events`` out to keep them): see
+        ``GuidingHand.webhook.update``. To remove the endpoint, use ``delete()``."""
+        body = webhook_body(url, events, rotate_secret)
+        return cast(Webhook, await self._client._request("PUT", "/v1/webhook", body=body))
+
+    async def delete(self) -> Webhook:
+        return cast(Webhook, await self._client._request("PUT", "/v1/webhook", body={"url": None}))