hitl-client 0.1.0__tar.gz

hitl_client-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+build/
+dist/

hitl_client-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: hitl-client
+Version: 0.1.0
+Summary: Zero-dependency Python SDK for HITL Broker: create/wait/consume human-in-the-loop checkpoints (approvals, OTP/short text, phone/app completion, image/QR display, live browser handoff).
+Project-URL: Homepage, https://github.com/aqiu9/HITL-Broker
+Project-URL: Repository, https://github.com/aqiu9/HITL-Broker
+License: MIT
+Keywords: approval,client,hitl,human-in-the-loop,otp,sdk
+Requires-Python: >=3.9
+Provides-Extra: browser
+Requires-Dist: hitl-cdp-browser-provider; extra == 'browser'
+Description-Content-Type: text/markdown
+
+# hitl-client
+
+Zero-dependency Python SDK for [HITL Broker](https://github.com/aqiu9/HITL-Broker) —
+create, wait for, and consume human-in-the-loop checkpoints from an agent or
+automation script: approvals (`decision`), OTP/short text (`text`),
+phone/app confirmations (`completion`), image or QR display (`image`/`qr`),
+and live browser handoff (`browser`).
+
+This is the packaged form of the HITL-Broker repo's own
+`client/hitl_client.py` — same file, published so callers don't need a full
+repo checkout to `import` it. Talks to the Broker over plain
+`urllib` (stdlib only, no runtime dependencies).
+
+## Install
+
+```bash
+pip install hitl-client
+```
+
+## Use
+
+```python
+import os
+from pathlib import Path
+from hitl_client import HitlClient
+
+base_url = os.environ["HITL_INTERNAL_URL"]        # e.g. http://192.168.1.10:8081
+api_key = Path(os.environ["HITL_API_KEY_FILE"]).read_text(encoding="utf-8").strip()
+client = HitlClient(base_url, api_key)
+
+result = client.wait_for_decision(
+    "Approve this deploy?",
+    description="Applies a schema migration if approved.",
+    external_id="run-42:approve-deploy",
+)
+if result.response["decision"] == "approve":
+    apply_deploy()
+else:
+    abort_deploy()
+client.consume(result.task_id)
+```
+
+`create_*`/`wait_for_*` cover all six task kinds; see the class docstrings
+in `hitl_client/client.py` for the full non-blocking + blocking API, and
+the main [HITL-Broker README](https://github.com/aqiu9/HITL-Broker) for
+task-kind semantics, the state machine, and realistic `expires_in` values
+(especially the OTP two-step timing pattern — trigger the SMS only after a
+human has confirmed they're ready, not before).
+
+## Do you also need browser support?
+
+Only if you're using the `browser` task kind (a human takes over a live
+browser session). Everything else — `decision`/`text`/`completion`/
+`image`/`qr` — works with just `pip install hitl-client`, nothing else.
+
+For `browser` tasks you need a small bridge process running on **whichever
+machine is actually hosting the browser session being handed off** — not
+necessarily the same machine that installed `hitl-client`. Pick one based on
+what that machine has, they're functionally identical:
+
+```bash
+# That machine runs Python:
+pip install hitl-cdp-browser-provider
+# — or, to also install it here as an extra when you already know you'll need it:
+pip install hitl-client[browser]
+
+# That machine runs Node instead:
+npm install -g hitl-cdp-browser-provider
+```
+
+You only need one of the two, not both. See
+[`hitl-cdp-browser-provider`](https://github.com/aqiu9/HITL-Broker/tree/main/packages)
+for setup and the `--token` security flag.

hitl_client-0.1.0/README.md

@@ -0,0 +1,73 @@
+# hitl-client
+
+Zero-dependency Python SDK for [HITL Broker](https://github.com/aqiu9/HITL-Broker) —
+create, wait for, and consume human-in-the-loop checkpoints from an agent or
+automation script: approvals (`decision`), OTP/short text (`text`),
+phone/app confirmations (`completion`), image or QR display (`image`/`qr`),
+and live browser handoff (`browser`).
+
+This is the packaged form of the HITL-Broker repo's own
+`client/hitl_client.py` — same file, published so callers don't need a full
+repo checkout to `import` it. Talks to the Broker over plain
+`urllib` (stdlib only, no runtime dependencies).
+
+## Install
+
+```bash
+pip install hitl-client
+```
+
+## Use
+
+```python
+import os
+from pathlib import Path
+from hitl_client import HitlClient
+
+base_url = os.environ["HITL_INTERNAL_URL"]        # e.g. http://192.168.1.10:8081
+api_key = Path(os.environ["HITL_API_KEY_FILE"]).read_text(encoding="utf-8").strip()
+client = HitlClient(base_url, api_key)
+
+result = client.wait_for_decision(
+    "Approve this deploy?",
+    description="Applies a schema migration if approved.",
+    external_id="run-42:approve-deploy",
+)
+if result.response["decision"] == "approve":
+    apply_deploy()
+else:
+    abort_deploy()
+client.consume(result.task_id)
+```
+
+`create_*`/`wait_for_*` cover all six task kinds; see the class docstrings
+in `hitl_client/client.py` for the full non-blocking + blocking API, and
+the main [HITL-Broker README](https://github.com/aqiu9/HITL-Broker) for
+task-kind semantics, the state machine, and realistic `expires_in` values
+(especially the OTP two-step timing pattern — trigger the SMS only after a
+human has confirmed they're ready, not before).
+
+## Do you also need browser support?
+
+Only if you're using the `browser` task kind (a human takes over a live
+browser session). Everything else — `decision`/`text`/`completion`/
+`image`/`qr` — works with just `pip install hitl-client`, nothing else.
+
+For `browser` tasks you need a small bridge process running on **whichever
+machine is actually hosting the browser session being handed off** — not
+necessarily the same machine that installed `hitl-client`. Pick one based on
+what that machine has, they're functionally identical:
+
+```bash
+# That machine runs Python:
+pip install hitl-cdp-browser-provider
+# — or, to also install it here as an extra when you already know you'll need it:
+pip install hitl-client[browser]
+
+# That machine runs Node instead:
+npm install -g hitl-cdp-browser-provider
+```
+
+You only need one of the two, not both. See
+[`hitl-cdp-browser-provider`](https://github.com/aqiu9/HITL-Broker/tree/main/packages)
+for setup and the `--token` security flag.

hitl_client-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hitl-client"
+version = "0.1.0"
+description = "Zero-dependency Python SDK for HITL Broker: create/wait/consume human-in-the-loop checkpoints (approvals, OTP/short text, phone/app completion, image/QR display, live browser handoff)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["hitl", "human-in-the-loop", "approval", "otp", "sdk", "client"]
+
+[project.optional-dependencies]
+browser = ["hitl-cdp-browser-provider"]
+
+[project.urls]
+Homepage = "https://github.com/aqiu9/HITL-Broker"
+Repository = "https://github.com/aqiu9/HITL-Broker"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hitl_client"]

hitl_client-0.1.0/src/hitl_client/__init__.py

@@ -0,0 +1,24 @@
+from .client import (
+    DEFAULT_POLL_POLICY,
+    HitlClient,
+    HitlError,
+    HitlHTTPError,
+    HitlTimeoutError,
+    HitlUnansweredError,
+    PollPolicy,
+    SubmittedResponse,
+    TaskHandle,
+)
+
+__all__ = [
+    "HitlClient",
+    "HitlError",
+    "HitlHTTPError",
+    "HitlTimeoutError",
+    "HitlUnansweredError",
+    "TaskHandle",
+    "SubmittedResponse",
+    "PollPolicy",
+    "DEFAULT_POLL_POLICY",
+]
+__version__ = "0.1.0"

hitl_client-0.1.0/src/hitl_client/client.py

@@ -0,0 +1,408 @@
+"""HITL Broker Python client SDK (design doc section 19, extended by the
+Image/QR/Browser increment doc section 23).
+
+Zero external dependencies (stdlib ``urllib`` only) so it can be dropped
+into any CT without adding a package footprint -- consistent with section
+25's minimal-stack philosophy. This is the packaged/published form (PyPI:
+``hitl-client``) of the HITL-Broker repo's own ``client/hitl_client.py``;
+either ``pip install hitl-client`` or copy that single file directly onto a
+client CT -- both are supported and stay in sync.
+
+Two layers, per section 19.1/19.2:
+
+* Non-blocking primitives -- ``create_decision`` / ``create_text`` /
+  ``create_completion`` / ``create_image`` / ``create_qr`` /
+  ``create_browser`` / ``put_artifact`` / ``get`` / ``consume`` /
+  ``resolve`` / ``cancel`` -- for a proper checkpoint/resume automation
+  that can shut down and come back.
+* Blocking convenience wrappers -- ``wait_for_decision`` /
+  ``wait_for_text`` / ``wait_for_completion`` -- for short-lived scripts
+  (typically the OTP flow, section 20) that are fine blocking in place.
+  They return a ``SubmittedResponse`` that the caller explicitly consumes
+  only after the downstream action accepts it. image/qr/browser tasks have
+  no analogous helper; the automation calls ``resolve()`` after confirming
+  the outcome by its own means.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+
+class HitlError(RuntimeError):
+    """Base class for all client-raised errors."""
+
+
+class HitlHTTPError(HitlError):
+    def __init__(self, status_code: int, code: str, message: str):
+        super().__init__(f"HTTP {status_code} [{code}]: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+
+class HitlTimeoutError(HitlError):
+    """The client's own poll budget was exhausted while the task was still
+    ``pending`` -- the task may still be answered later; it is NOT
+    automatically cancelled (see wait_for_* docstrings)."""
+
+
+class HitlUnansweredError(HitlError):
+    """The task left ``pending`` without a human response (expired or was
+    cancelled), as opposed to being genuinely approved/rejected/filled."""
+
+
+@dataclass
+class TaskHandle:
+    task_id: str
+    status: str
+    review_url: str | None
+    expires_at: str
+    poll_after: int
+
+
+@dataclass(frozen=True)
+class SubmittedResponse:
+    """A human response that remains readable until the caller confirms
+    successful downstream use with ``consume(task_id)``."""
+
+    task_id: str
+    kind: str
+    response: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class PollPolicy:
+    """Section 19.3 tiered polling: fast during the OTP-scale first 30s,
+    settling to a slower cadence, with jitter to avoid a thundering herd
+    against the broker when many tasks are in flight concurrently."""
+
+    fast_window_seconds: float = 30.0
+    fast_interval_seconds: float = 3.0
+    medium_window_seconds: float = 120.0
+    medium_interval_seconds: float = 10.0
+    slow_interval_seconds: float = 25.0
+    jitter_seconds: float = 3.0
+
+    def interval_at(self, elapsed_seconds: float) -> float:
+        if elapsed_seconds < self.fast_window_seconds:
+            base = self.fast_interval_seconds
+        elif elapsed_seconds < self.fast_window_seconds + self.medium_window_seconds:
+            base = self.medium_interval_seconds
+        else:
+            base = self.slow_interval_seconds
+        return max(0.5, base + random.uniform(0, self.jitter_seconds))
+
+
+DEFAULT_POLL_POLICY = PollPolicy()
+
+
+class HitlClient:
+    def __init__(self, base_url: str, api_key: str, *, timeout: float = 10.0):
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+
+    # -- low-level HTTP -----------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        data = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        request = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                raw = response.read()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            try:
+                body = json.loads(raw) if raw else {}
+            except json.JSONDecodeError:
+                body = {}
+            error = body.get("error", {}) if isinstance(body, dict) else {}
+            raise HitlHTTPError(
+                exc.code, error.get("code", "http_error"), error.get("message", str(exc.reason))
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise HitlError(f"request to {path} failed: {exc.reason}") from exc
+
+    def _request_bytes(self, method: str, path: str, *, data: bytes, content_type: str) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        headers = {"Authorization": f"Bearer {self._api_key}", "Content-Type": content_type}
+        request = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                raw = response.read()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            try:
+                body = json.loads(raw) if raw else {}
+            except json.JSONDecodeError:
+                body = {}
+            error = body.get("error", {}) if isinstance(body, dict) else {}
+            raise HitlHTTPError(
+                exc.code, error.get("code", "http_error"), error.get("message", str(exc.reason))
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise HitlError(f"request to {path} failed: {exc.reason}") from exc
+
+    # -- non-blocking primitives (section 19.1) -----------------------
+
+    def create_decision(
+        self,
+        title: str,
+        *,
+        description: str = "",
+        expires_in: int | None = None,
+        notify: bool = True,
+        external_id: str | None = None,
+    ) -> TaskHandle:
+        return self._create(
+            "decision", title=title, description=description, input_spec=None,
+            expires_in=expires_in, notify=notify, external_id=external_id,
+        )
+
+    def create_text(
+        self,
+        title: str,
+        *,
+        label: str = "",
+        secret: bool = True,
+        min_length: int | None = None,
+        max_length: int | None = None,
+        pattern: str | None = None,
+        description: str = "",
+        expires_in: int | None = None,
+        notify: bool = True,
+        external_id: str | None = None,
+    ) -> TaskHandle:
+        input_spec = {
+            "label": label, "secret": secret,
+            "min_length": min_length, "max_length": max_length, "pattern": pattern,
+        }
+        return self._create(
+            "text", title=title, description=description, input_spec=input_spec,
+            expires_in=expires_in, notify=notify, external_id=external_id,
+        )
+
+    def create_completion(
+        self,
+        title: str,
+        *,
+        description: str = "",
+        expires_in: int | None = None,
+        notify: bool = True,
+        external_id: str | None = None,
+    ) -> TaskHandle:
+        return self._create(
+            "completion", title=title, description=description, input_spec=None,
+            expires_in=expires_in, notify=notify, external_id=external_id,
+        )
+
+    # -- image/qr/browser (increment doc section 23) -----------------------
+
+    def create_image(
+        self,
+        title: str,
+        *,
+        description: str = "",
+        expires_in: int | None = None,
+        notify: bool = True,
+        external_id: str | None = None,
+    ) -> TaskHandle:
+        """Create the task, then call put_artifact() with the image bytes
+        (increment doc section 4.2's two-step flow: create, then upload)."""
+        return self._create(
+            "image", title=title, description=description, input_spec=None,
+            expires_in=expires_in, notify=notify, external_id=external_id,
+        )
+
+    def create_qr(
+        self,
+        title: str,
+        *,
+        description: str = "",
+        expires_in: int | None = None,
+        notify: bool = True,
+        external_id: str | None = None,
+    ) -> TaskHandle:
+        """Create the task, then call put_artifact() with the QR image.
+        Call put_artifact() again (same task_id) whenever the QR refreshes
+        -- section 8: no new task, just a new artifact version."""
+        return self._create(
+            "qr", title=title, description=description, input_spec=None,
+            expires_in=expires_in, notify=notify, external_id=external_id,
+        )
+
+    def create_browser(
+        self,
+        title: str,
+        *,
+        internal_url: str,
+        description: str = "",
+        expires_in: int | None = None,
+        notify: bool = True,
+        external_id: str | None = None,
+    ) -> TaskHandle:
+        """internal_url must match the calling source's configured
+        allowed_browser_host/port (increment doc section 19) or the
+        broker rejects the create with a 422."""
+        return self._create(
+            "browser", title=title, description=description, input_spec=None,
+            expires_in=expires_in, notify=notify, external_id=external_id, internal_url=internal_url,
+        )
+
+    def put_artifact(self, task_id: str, data: bytes, *, content_type: str) -> dict[str, Any]:
+        """Uploads or replaces a task's image artifact. Replacing
+        overwrites in place and bumps `version` -- no history is kept."""
+        return self._request_bytes("PUT", f"/v1/tasks/{task_id}/artifact", data=data, content_type=content_type)
+
+    def resolve(self, task_id: str, *, reason: str = "completed") -> dict[str, Any]:
+        """Ends an image/qr/browser task directly (pending -> consumed)
+        once the automation has independently confirmed the outcome --
+        e.g. the QR login succeeded (section 20). Not valid for
+        decision/text/completion tasks; use consume() for those after the
+        human has submitted a response."""
+        return self._request("POST", f"/v1/tasks/{task_id}/resolve", json_body={"reason": reason})
+
+    def _create(
+        self, kind: str, *, title: str, description: str, input_spec: dict[str, Any] | None,
+        expires_in: int | None, notify: bool, external_id: str | None, internal_url: str | None = None,
+    ) -> TaskHandle:
+        body: dict[str, Any] = {"kind": kind, "title": title, "description": description, "notify": notify}
+        if input_spec is not None:
+            body["input"] = {k: v for k, v in input_spec.items() if v is not None}
+        if internal_url is not None:
+            body["internal_url"] = internal_url
+        if expires_in is not None:
+            body["expires_in"] = expires_in
+        data = self._request("POST", "/v1/tasks", json_body=body, idempotency_key=external_id)
+        return TaskHandle(
+            task_id=data["task_id"],
+            status=data["status"],
+            review_url=data.get("review_url"),
+            expires_at=data["expires_at"],
+            poll_after=data.get("poll_after", 15),
+        )
+
+    def get(self, task_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/tasks/{task_id}")
+
+    def consume(self, task_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/v1/tasks/{task_id}/consume")
+
+    def cancel(self, task_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/v1/tasks/{task_id}/cancel")
+
+    # -- blocking convenience helpers (section 19.2/20) -----------------
+
+    def _poll_until_left_pending(self, task_id: str, *, timeout: float, policy: PollPolicy) -> dict[str, Any]:
+        start = time.monotonic()
+        while True:
+            status = self.get(task_id)
+            if status.get("status") != "pending":
+                return status
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout:
+                raise HitlTimeoutError(f"task {task_id} still pending after {timeout:.0f}s")
+            time.sleep(min(policy.interval_at(elapsed), max(0.0, timeout - elapsed)))
+
+    def wait_for_decision(
+        self,
+        title: str,
+        *,
+        description: str = "",
+        expires_in: int = 86400,
+        timeout: float | None = None,
+        poll_policy: PollPolicy = DEFAULT_POLL_POLICY,
+        external_id: str | None = None,
+    ) -> SubmittedResponse:
+        """Block until a decision is submitted, without consuming it.
+
+        Inspect ``result.response['decision']`` and call
+        ``consume(result.task_id)`` only after applying that decision.
+        """
+        handle = self.create_decision(title, description=description, expires_in=expires_in, external_id=external_id)
+        budget = timeout if timeout is not None else float(expires_in)
+        status = self._poll_until_left_pending(handle.task_id, timeout=budget, policy=poll_policy)
+        if status.get("status") != "submitted":
+            raise HitlUnansweredError(f"task {handle.task_id} ended with status={status.get('status')}")
+        return SubmittedResponse(
+            task_id=handle.task_id,
+            kind="decision",
+            response=status.get("response") or {},
+        )
+
+    def wait_for_text(
+        self,
+        title: str,
+        *,
+        label: str = "",
+        secret: bool = True,
+        min_length: int | None = None,
+        max_length: int | None = None,
+        pattern: str | None = None,
+        description: str = "",
+        expires_in: int = 300,
+        timeout: float | None = None,
+        poll_policy: PollPolicy = DEFAULT_POLL_POLICY,
+        external_id: str | None = None,
+    ) -> SubmittedResponse:
+        """Blocks until the human submits text (typically an OTP, section
+        20) or the task ends unanswered."""
+        handle = self.create_text(
+            title, label=label, secret=secret, min_length=min_length, max_length=max_length,
+            pattern=pattern, description=description, expires_in=expires_in, external_id=external_id,
+        )
+        budget = timeout if timeout is not None else float(expires_in)
+        status = self._poll_until_left_pending(handle.task_id, timeout=budget, policy=poll_policy)
+        if status.get("status") != "submitted":
+            raise HitlUnansweredError(f"task {handle.task_id} ended with status={status.get('status')}")
+        return SubmittedResponse(
+            task_id=handle.task_id,
+            kind="text",
+            response=status.get("response") or {},
+        )
+
+    def wait_for_completion(
+        self,
+        title: str,
+        *,
+        description: str = "",
+        expires_in: int = 86400,
+        timeout: float | None = None,
+        poll_policy: PollPolicy = DEFAULT_POLL_POLICY,
+        external_id: str | None = None,
+    ) -> SubmittedResponse:
+        """Block until completion is submitted, without consuming it."""
+        handle = self.create_completion(title, description=description, expires_in=expires_in, external_id=external_id)
+        budget = timeout if timeout is not None else float(expires_in)
+        status = self._poll_until_left_pending(handle.task_id, timeout=budget, policy=poll_policy)
+        if status.get("status") != "submitted":
+            raise HitlUnansweredError(f"task {handle.task_id} ended with status={status.get('status')}")
+        return SubmittedResponse(
+            task_id=handle.task_id,
+            kind="completion",
+            response=status.get("response") or {},
+        )