allternit-computer-driver 0.1.0__tar.gz

allternit_computer_driver-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: allternit-computer-driver
+Version: 0.1.0
+Summary: Drop-in drivers for Allternit hosted computers: a plain client plus Anthropic (computer/browser toolset), OpenAI computer-use and Gemini computer_use adapters.
+License: Apache-2.0
+Project-URL: Documentation, https://docs.allternit.com/api/platform/sdks/python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+
+# allternit-computer-driver
+
+Drive an Allternit hosted computer (`/v1/computers`) from Claude, OpenAI computer use, or Gemini computer use. Standard library only; `pip install allternit-computer-driver[anthropic]` adds the Anthropic SDK. Needs a project key with the `computers` scope and the hosted driver turned on for the project.
+
+```python
+from allternit_computer_driver import AllternitComputers
+client = AllternitComputers()  # reads ALLTERNIT_API_KEY
+computer = client.create(name="agent-1")
+```
+
+## Claude
+
+```python
+from allternit_computer_driver.anthropic import AllternitComputerToolset
+toolset = AllternitComputerToolset(client, computer["id"], on_approval=lambda approval: ask_a_person(approval))
+```
+
+Each member runs on the server through `POST /v1/computers/{id}/toolset`. A 409 `approval_required` calls `on_approval`: `True` approves it and resends with the grant, `False` returns the held result to the model as an error. When the installed `anthropic` package has `anthropic.tools.computer` / `anthropic.tools.browser`, these classes subclass its abstract toolsets. Older releases get a small stand-in with `to_dict()` and `tool_result(tool_use)` for a hand-written loop.
+
+## OpenAI computer use
+
+```python
+from allternit_computer_driver import run_openai_action
+step = run_openai_action(client, computer_id, call.call_id, call.action.model_dump(), display={"width": 1280, "height": 800})
+next_input.append(step["output"])
+```
+
+## Gemini computer use
+
+```python
+from allternit_computer_driver import run_gemini_call
+step = run_gemini_call(client, computer_id, fc.name, dict(fc.args))
+# step["function_response"] and step["inline_data"] (0-999 coords sent as normalized_1000)
+```
+
+The OpenAI and Gemini adapters raise `ApprovalRequiredError`; call `client.approve()` and resend. All other failures raise `AllternitApiError` with `status`, `code` and `type`.

allternit_computer_driver-0.1.0/README.md

@@ -0,0 +1,36 @@
+# allternit-computer-driver
+
+Drive an Allternit hosted computer (`/v1/computers`) from Claude, OpenAI computer use, or Gemini computer use. Standard library only; `pip install allternit-computer-driver[anthropic]` adds the Anthropic SDK. Needs a project key with the `computers` scope and the hosted driver turned on for the project.
+
+```python
+from allternit_computer_driver import AllternitComputers
+client = AllternitComputers()  # reads ALLTERNIT_API_KEY
+computer = client.create(name="agent-1")
+```
+
+## Claude
+
+```python
+from allternit_computer_driver.anthropic import AllternitComputerToolset
+toolset = AllternitComputerToolset(client, computer["id"], on_approval=lambda approval: ask_a_person(approval))
+```
+
+Each member runs on the server through `POST /v1/computers/{id}/toolset`. A 409 `approval_required` calls `on_approval`: `True` approves it and resends with the grant, `False` returns the held result to the model as an error. When the installed `anthropic` package has `anthropic.tools.computer` / `anthropic.tools.browser`, these classes subclass its abstract toolsets. Older releases get a small stand-in with `to_dict()` and `tool_result(tool_use)` for a hand-written loop.
+
+## OpenAI computer use
+
+```python
+from allternit_computer_driver import run_openai_action
+step = run_openai_action(client, computer_id, call.call_id, call.action.model_dump(), display={"width": 1280, "height": 800})
+next_input.append(step["output"])
+```
+
+## Gemini computer use
+
+```python
+from allternit_computer_driver import run_gemini_call
+step = run_gemini_call(client, computer_id, fc.name, dict(fc.args))
+# step["function_response"] and step["inline_data"] (0-999 coords sent as normalized_1000)
+```
+
+The OpenAI and Gemini adapters raise `ApprovalRequiredError`; call `client.approve()` and resend. All other failures raise `AllternitApiError` with `status`, `code` and `type`.

allternit_computer_driver-0.1.0/allternit_computer_driver/__init__.py

@@ -0,0 +1,15 @@
+"""Drive Allternit hosted computers from Claude, OpenAI computer use or Gemini computer use.
+
+The Anthropic toolsets are in ``allternit_computer_driver.anthropic`` so importing this package
+never needs the optional ``anthropic`` dependency."""
+
+from .client import DEFAULT_BASE_URL, AllternitApiError, AllternitComputers, ApprovalRequiredError, result_image, result_text
+from .gemini import gemini_keys, gemini_to_calls, run_gemini_call
+from .openai import openai_keys, openai_to_calls, run_openai_action
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AllternitComputers", "AllternitApiError", "ApprovalRequiredError", "DEFAULT_BASE_URL", "result_image", "result_text",
+    "gemini_keys", "gemini_to_calls", "run_gemini_call", "openai_keys", "openai_to_calls", "run_openai_action",
+]

allternit_computer_driver-0.1.0/allternit_computer_driver/anthropic.py

@@ -0,0 +1,179 @@
+"""Anthropic toolset drivers for computer_toolset_20260801 / browser_toolset_20260801.
+
+Each member call runs on an Allternit hosted computer via ``POST /v1/computers/{id}/toolset``.
+When the installed ``anthropic`` package ships the abstract toolsets (``anthropic.tools.computer``
+/ ``anthropic.tools.browser``), these classes subclass them and override ``execute``. Older
+releases (anthropic <= 0.125.0 has none) get a small stand-in base with the same ``execute``
+hook plus ``to_dict()`` and ``tool_result(tool_use)`` for a hand-written loop.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Callable, Dict, Optional
+
+from .client import AllternitComputers, ApprovalRequiredError, ToolsetResult, result_image, result_text
+
+
+def _sdk_base(module: str, names: tuple) -> Optional[type]:
+    try:
+        mod = __import__(module, fromlist=["_"])
+    except ImportError:
+        return None
+    for n in names:
+        if hasattr(mod, n):
+            return getattr(mod, n)
+    return None
+
+
+class _ToolError(Exception):
+    def __init__(self, content: Any) -> None:
+        super().__init__(content if isinstance(content, str) else "toolset error")
+        self.content = content
+
+
+try:  # The SDK's ToolError, so its runner reports is_error the same way.
+    from anthropic.lib.tools import ToolError as _SDKToolError  # type: ignore
+
+    ToolError: Any = _SDKToolError
+except ImportError:
+    ToolError = _ToolError
+
+
+class _StandIn:
+    type = ""
+    toolset_name = ""
+
+    def __init__(self, **_: Any) -> None:
+        pass
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type}
+
+    def tool_result(self, tool_use: Dict[str, Any]) -> Dict[str, Any]:
+        base = {"type": "tool_result", "tool_use_id": tool_use["id"], "toolset_name": self.toolset_name}
+        try:
+            out = self.execute(None, tool_use["name"], tool_use.get("input") or {})  # type: ignore[attr-defined]
+        except Exception as e:  # noqa: BLE001
+            content = getattr(e, "content", str(e))
+            return {**base, "content": content, "is_error": True}
+        if isinstance(out, dict) and "data" in out:
+            out = [{"type": "image", "source": {"type": "base64", "media_type": out.get("media_type", "image/png"), "data": out["data"]}}]
+        elif isinstance(out, (dict, list)):
+            out = json.dumps(out)
+        return {**base, "content": out or "Done."}
+
+
+_ComputerBase: Any = _sdk_base("anthropic.tools.computer", ("BetaAbstractComputerToolset20260801", "AbstractComputerToolset20260801")) or type("_ComputerBase", (_StandIn,), {"type": "computer_toolset_20260801", "toolset_name": "computer"})
+_BrowserBase: Any = _sdk_base("anthropic.tools.browser", ("BetaAbstractBrowserToolset20260801", "AbstractBrowserToolset20260801")) or type("_BrowserBase", (_StandIn,), {"type": "browser_toolset_20260801", "toolset_name": "browser"})
+
+
+def _server_decides(*_: Any) -> bool:
+    """Default ``confirm``: the Allternit server applies member policy and holds risky calls (409)."""
+    return True
+
+
+class _Driver:
+    def _setup(self, client: AllternitComputers, computer_id: str, on_approval: Optional[Callable[[Dict[str, Any]], bool]], call_ids: Optional[Callable[[Any, str], Dict[str, Any]]], browser_session_id: Optional[str]) -> None:
+        self._client, self._computer_id = client, computer_id
+        self._on_approval, self._call_ids, self._session = on_approval, call_ids, browser_session_id
+
+    def _call(self, toolset: str, ctx: Any, member: str, input: Any) -> ToolsetResult:
+        # The SDK only calls members its toolset config turned on: that is the
+        # opt-in the executor asks for on off-by-default members.
+        call: Dict[str, Any] = {"toolset": toolset, "member": member, "input": dict(input or {}), "enable": [member]}
+        if self._call_ids:
+            call.update(self._call_ids(ctx, member) or {})
+        if self._session:
+            call["browser_session_id"] = self._session
+        try:
+            res = self._client.toolset(self._computer_id, call)
+        except ApprovalRequiredError as e:
+            if self._on_approval and self._on_approval(e.approval):
+                self._client.approve(self._computer_id, e.approval["id"])
+                res = self._client.toolset(self._computer_id, {**call, "approval_grant": e.approval["id"]})
+            else:
+                res = e.result
+        if res.get("is_error"):
+            raise ToolError(_blocks(res))
+        return res
+
+
+def _blocks(r: ToolsetResult) -> Any:
+    out = [
+        {"type": "text", "text": b["text"]} if b.get("type") == "text" else {"type": "image", "source": {"type": "base64", "media_type": b["media_type"], "data": b["data"]}}
+        for b in r.get("content", [])
+    ]
+    return out or "The action failed."
+
+
+def _shot(r: ToolsetResult) -> Dict[str, str]:
+    img = result_image(r)
+    if not img:
+        raise ToolError("The computer returned no screenshot.")
+    return {"data": img["data"], "media_type": img["media_type"]}
+
+
+def _json(r: ToolsetResult) -> Any:
+    try:
+        return json.loads(result_text(r))
+    except ValueError:
+        return None
+
+
+class AllternitComputerToolset(_Driver, _ComputerBase):
+    def __init__(self, client: AllternitComputers, computer_id: str, on_approval: Optional[Callable[[Dict[str, Any]], bool]] = None, call_ids: Optional[Callable[[Any, str], Dict[str, Any]]] = None, **sdk_options: Any) -> None:
+        sdk_options.setdefault("confirm", _server_decides)
+        _ComputerBase.__init__(self, **sdk_options)
+        self._setup(client, computer_id, on_approval, call_ids, None)
+
+    def execute(self, ctx: Any, name: str, input: Any) -> Any:
+        r = self._call("computer", ctx, name, input)
+        if name in ("screenshot", "zoom"):
+            return _shot(r)
+        if name == "cursor_position":
+            j = _json(r)
+            if isinstance(j, dict) and "x" in j:
+                return {"x": j["x"], "y": j["y"]}
+            m = re.search(r"(-?\d+)\D+(-?\d+)", result_text(r))
+            if not m:
+                raise ToolError("The computer returned no cursor position.")
+            return {"x": int(m.group(1)), "y": int(m.group(2))}
+        return result_text(r) or None
+
+
+class AllternitBrowserToolset(_Driver, _BrowserBase):
+    def __init__(self, client: AllternitComputers, computer_id: str, on_approval: Optional[Callable[[Dict[str, Any]], bool]] = None, call_ids: Optional[Callable[[Any, str], Dict[str, Any]]] = None, browser_session_id: Optional[str] = None, **sdk_options: Any) -> None:
+        self._state: Optional[Dict[str, Any]] = None
+        sdk_options.setdefault("confirm", _server_decides)
+        sdk_options.setdefault("browser_state", self._current_state)
+        _BrowserBase.__init__(self, **sdk_options)
+        self._setup(client, computer_id, on_approval, call_ids, browser_session_id)
+
+    def _current_state(self, ctx: Any = None) -> Dict[str, Any]:
+        if self._state is None:
+            r = self._call("browser", ctx, "list_tabs", {})
+            self._state = r.get("browser_state") or {"tabs": _json(r) or []}
+        return self._state
+
+    def execute(self, ctx: Any, name: str, input: Any) -> Any:
+        r = self._call("browser", ctx, name, input)
+        if r.get("browser_state"):
+            self._state = r["browser_state"]
+        if name in ("screenshot", "zoom"):
+            return _shot(r)
+        j, tabs = _json(r), (self._state or {}).get("tabs", [])
+        if name == "navigate":
+            return j if isinstance(j, dict) and j.get("url") else {"url": tabs[0]["url"] if tabs else str((input or {}).get("url", ""))}
+        if name == "list_tabs":
+            return j if isinstance(j, list) else tabs
+        if name in ("new_tab", "switch_tab"):
+            if isinstance(j, dict) and j.get("tab_id"):
+                return j
+            if tabs:
+                return tabs[0]
+            raise ToolError("The browser returned no tab.")
+        if name == "close_tab":
+            return None
+        return result_text(r) or None

allternit_computer_driver-0.1.0/allternit_computer_driver/client.py

@@ -0,0 +1,123 @@
+"""Plain client for the Allternit hosted computer API (/v1/computers). Standard library only."""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from typing import Any, Dict, List, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+from urllib.request import Request, urlopen
+
+DEFAULT_BASE_URL = "https://api.allternit.com"
+DEFAULT_TIMEOUT = 60.0
+
+ToolsetResult = Dict[str, Any]
+"""``{is_error, content:[{type:"text",text}|{type:"image",media_type,data}], browser_state?, screen?, error?}``"""
+
+
+class AllternitApiError(Exception):
+    def __init__(self, status: int, error: Dict[str, Any], body: Any) -> None:
+        super().__init__(error.get("message") or f"Allternit API error {status}")
+        self.status = status
+        self.type = error.get("type", "api_error")
+        self.code = error.get("code", "unknown")
+        self.param = error.get("param")
+        self.body = body
+
+
+class ApprovalRequiredError(AllternitApiError):
+    """409 ``approval_required``: the call is held until someone approves it."""
+
+    def __init__(self, error: Dict[str, Any], approval: Dict[str, Any], result: ToolsetResult, body: Any) -> None:
+        super().__init__(409, error, body)
+        self.approval = approval
+        self.result = result
+
+
+class AllternitComputers:
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = DEFAULT_TIMEOUT) -> None:
+        key = api_key or os.environ.get("ALLTERNIT_API_KEY")
+        if not key:
+            raise ValueError("AllternitComputers: api_key is required (or set ALLTERNIT_API_KEY).")
+        self._api_key = key
+        self.base_url = (base_url or os.environ.get("ALLTERNIT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+
+    def create(self, name: Optional[str] = None, account_id: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        body = {k: v for k, v in {"name": name, "account_id": account_id, "metadata": metadata}.items() if v is not None}
+        return self._req("POST", "/v1/computers", body)
+
+    def list(self, limit: Optional[int] = None, after: Optional[str] = None) -> Dict[str, Any]:
+        return self._req("GET", "/v1/computers" + _qs(limit=limit, after=after))
+
+    def get(self, computer_id: str) -> Dict[str, Any]:
+        return self._req("GET", f"/v1/computers/{quote(computer_id)}")
+
+    def start(self, computer_id: str) -> Dict[str, Any]:
+        return self._req("POST", f"/v1/computers/{quote(computer_id)}/start", {})
+
+    def stop(self, computer_id: str) -> Dict[str, Any]:
+        return self._req("POST", f"/v1/computers/{quote(computer_id)}/stop", {})
+
+    def delete(self, computer_id: str) -> Dict[str, Any]:
+        return self._req("DELETE", f"/v1/computers/{quote(computer_id)}")
+
+    def toolset(self, computer_id: str, call: Dict[str, Any]) -> ToolsetResult:
+        """Run one member. Action failures return ``is_error: True``; a held call raises ApprovalRequiredError."""
+        return self._req("POST", f"/v1/computers/{quote(computer_id)}/toolset", call)
+
+    def schema(self, computer_id: str, toolset: str = "computer") -> Dict[str, Any]:
+        return self._req("GET", f"/v1/computers/{quote(computer_id)}/toolset/schema" + _qs(toolset=toolset))
+
+    def events(self, computer_id: str, after: Optional[str] = None, limit: Optional[int] = None) -> Dict[str, Any]:
+        return self._req("GET", f"/v1/computers/{quote(computer_id)}/events" + _qs(after=after, limit=limit))
+
+    def approve(self, computer_id: str, approval_id: str) -> Dict[str, Any]:
+        return self._req("POST", f"/v1/computers/{quote(computer_id)}/approvals/{quote(approval_id)}", {})
+
+    def _req(self, method: str, path: str, body: Any = None) -> Any:
+        headers = {"Authorization": f"Bearer {self._api_key}", "Accept": "application/json"}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+        if method == "POST":
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        req = Request(self.base_url + path, data=data, method=method, headers=headers)
+        try:
+            with urlopen(req, timeout=self.timeout) as res:
+                text = res.read().decode()
+                return json.loads(text) if text else None
+        except HTTPError as e:
+            text = e.read().decode(errors="replace")
+            try:
+                payload = json.loads(text) if text else {}
+            except ValueError:
+                payload = {"error": {"message": text}}
+            err = payload.get("error") or {}
+            if e.code == 409 and err.get("code") == "approval_required" and payload.get("approval"):
+                raise ApprovalRequiredError(err, payload["approval"], payload.get("result") or {"is_error": True, "content": []}, payload) from None
+            raise AllternitApiError(e.code, err, payload) from None
+        except URLError as e:
+            raise AllternitApiError(0, {"type": "connection_error", "code": "connection_error", "message": str(e.reason)}, None) from None
+
+
+def result_text(r: ToolsetResult) -> str:
+    return "\n".join(b["text"] for b in r.get("content", []) if b.get("type") == "text")
+
+
+def result_image(r: ToolsetResult) -> Optional[Dict[str, str]]:
+    for b in r.get("content", []):
+        if b.get("type") == "image":
+            return {"media_type": b["media_type"], "data": b["data"]}
+    return None
+
+
+def _qs(**q: Any) -> str:
+    p = [(k, str(v)) for k, v in q.items() if v not in (None, "")]
+    return "?" + urlencode(p) if p else ""
+
+
+__all__: List[str] = ["AllternitComputers", "AllternitApiError", "ApprovalRequiredError", "DEFAULT_BASE_URL", "result_text", "result_image"]

allternit_computer_driver-0.1.0/allternit_computer_driver/gemini.py

@@ -0,0 +1,91 @@
+"""Gemini computer_use adapter. Gemini coordinates are 0-999 normalized, so every call
+is sent with ``coordinate_space: "normalized_1000"`` and the server scales to the screen."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from .client import AllternitComputers, result_image, result_text
+
+Step = Dict[str, Any]
+_MAP = {"control": "ctrl", "meta": "super", "command": "super", "enter": "Return", "escape": "Escape", "backspace": "BackSpace", "tab": "Tab", "delete": "Delete"}
+
+
+def gemini_keys(keys: str) -> str:
+    """``"Control+Shift+T"`` -> ``"ctrl+shift+t"``."""
+    parts = [k.strip() for k in keys.split("+")]
+    return "+".join(_MAP.get(k.lower(), k.lower() if len(k) == 1 else k) for k in parts)
+
+
+def _pt(x: Any, y: Any) -> List[int]:
+    return [round(float(x)), round(float(y))]
+
+
+def _key(text: str) -> Step:
+    return {"member": "key", "input": {"text": text}}
+
+
+def _type(text: str) -> Step:
+    return {"member": "type", "input": {"text": text}}
+
+
+def _go(url: str) -> List[Step]:
+    return [_key("ctrl+l"), _type(url), _key("Return")]
+
+
+def gemini_to_calls(name: str, args: Dict[str, Any], search_url: str = "https://www.google.com") -> List[Step]:
+    a = args or {}
+    d = str(a.get("direction", "down"))
+    if name == "open_web_browser":
+        return []
+    if name == "wait_5_seconds":
+        return [{"member": "wait", "input": {"duration": 5}}]
+    if name == "go_back":
+        return [_key("alt+Left")]
+    if name == "go_forward":
+        return [_key("alt+Right")]
+    if name == "search":
+        return _go(search_url)
+    if name == "navigate":
+        return _go(str(a.get("url", "")))
+    if name == "click_at":
+        return [{"member": "left_click", "input": {"coordinate": _pt(a["x"], a["y"])}}]
+    if name == "hover_at":
+        return [{"member": "mouse_move", "input": {"coordinate": _pt(a["x"], a["y"])}}]
+    if name == "type_text_at":
+        steps: List[Step] = [{"member": "left_click", "input": {"coordinate": _pt(a["x"], a["y"])}}]
+        if a.get("clear_before_typing", True):
+            steps += [_key("ctrl+a"), _key("BackSpace")]
+        steps.append(_type(str(a.get("text", ""))))
+        if a.get("press_enter", True):
+            steps.append(_key("Return"))
+        return steps
+    if name == "key_combination":
+        return [_key(gemini_keys(str(a.get("keys", ""))))]
+    if name == "scroll_document":
+        return [{"member": "scroll", "input": {"coordinate": [500, 500], "scroll_direction": d, "scroll_amount": 5}}]
+    if name == "scroll_at":
+        amount = max(1, round(float(a.get("magnitude", 800)) / 160))
+        return [{"member": "scroll", "input": {"coordinate": _pt(a["x"], a["y"]), "scroll_direction": d, "scroll_amount": amount}}]
+    if name == "drag_and_drop":
+        return [{"member": "left_click_drag", "input": {"start_coordinate": _pt(a["x"], a["y"]), "coordinate": _pt(a["destination_x"], a["destination_y"])}}]
+    raise ValueError(f"Unsupported Gemini computer_use function: {name}")
+
+
+def run_gemini_call(client: AllternitComputers, computer_id: str, name: str, args: Dict[str, Any], search_url: str = "https://www.google.com") -> Dict[str, Any]:
+    """Returns ``{"function_response": {name, response}, "inline_data": {mime_type, data}, "error": ...}``."""
+    base = {"toolset": "computer", "coordinate_space": "normalized_1000"}
+    error = None
+    for step in gemini_to_calls(name, args, search_url):
+        r = client.toolset(computer_id, {**base, **step})
+        if r.get("is_error"):
+            error = r
+            break
+    s = client.toolset(computer_id, {**base, "member": "screenshot", "input": {}})
+    img = result_image(s)
+    if not img:
+        raise RuntimeError("Allternit computer returned no screenshot.")
+    response: Dict[str, Any] = {"url": ""}
+    if error:
+        response["error"] = result_text(error)
+    return {"function_response": {"name": name, "response": response}, "inline_data": {"mime_type": img["media_type"], "data": img["data"]}, "error": error}

allternit_computer_driver-0.1.0/allternit_computer_driver/openai.py

@@ -0,0 +1,102 @@
+"""OpenAI computer-use adapter: run one ``computer_call`` action on an Allternit hosted
+computer and return a ``computer_call_output`` item carrying the next screenshot."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .client import AllternitComputers, result_image
+
+_KEYS = {
+    "CTRL": "ctrl", "CONTROL": "ctrl", "ALT": "alt", "OPTION": "alt", "SHIFT": "shift", "CMD": "super", "META": "super",
+    "SUPER": "super", "WIN": "super", "ENTER": "Return", "RETURN": "Return", "ESC": "Escape", "ESCAPE": "Escape",
+    "TAB": "Tab", "SPACE": "space", "BACKSPACE": "BackSpace", "DELETE": "Delete", "UP": "Up", "DOWN": "Down",
+    "LEFT": "Left", "RIGHT": "Right", "ARROWUP": "Up", "ARROWDOWN": "Down", "ARROWLEFT": "Left", "ARROWRIGHT": "Right",
+    "HOME": "Home", "END": "End", "PAGEUP": "Page_Up", "PAGEDOWN": "Page_Down",
+}
+
+Step = Dict[str, Any]
+
+
+def openai_keys(keys: List[str]) -> str:
+    """``["CTRL","C"]`` -> ``"ctrl+c"``."""
+    return "+".join(_KEYS.get(k.upper(), k.lower() if len(k) == 1 else k) for k in keys)
+
+
+def _c(x: Any, y: Any) -> List[int]:
+    return [round(float(x)), round(float(y))]
+
+
+def openai_to_calls(a: Dict[str, Any], per_click: int = 100) -> List[Step]:
+    t = a.get("type")
+    if t == "click":
+        b = a.get("button", "left")
+        if b == "back":
+            return [{"member": "key", "input": {"text": "alt+Left"}}]
+        if b == "forward":
+            return [{"member": "key", "input": {"text": "alt+Right"}}]
+        member = {"right": "right_click", "wheel": "middle_click"}.get(b, "left_click")
+        return [{"member": member, "input": {"coordinate": _c(a["x"], a["y"])}}]
+    if t == "double_click":
+        return [{"member": "double_click", "input": {"coordinate": _c(a["x"], a["y"])}}]
+    if t == "drag":
+        p = a.get("path") or []
+        if len(p) < 2:
+            return []
+        if len(p) == 2:
+            return [{"member": "left_click_drag", "input": {"start_coordinate": _c(p[0]["x"], p[0]["y"]), "coordinate": _c(p[1]["x"], p[1]["y"])}}]
+        return (
+            [{"member": "mouse_move", "input": {"coordinate": _c(p[0]["x"], p[0]["y"])}}, {"member": "left_mouse_down", "input": {}}]
+            + [{"member": "mouse_move", "input": {"coordinate": _c(q["x"], q["y"])}} for q in p[1:]]
+            + [{"member": "left_mouse_up", "input": {}}]
+        )
+    if t == "keypress":
+        return [{"member": "key", "input": {"text": openai_keys(a.get("keys") or [])}}]
+    if t == "move":
+        return [{"member": "mouse_move", "input": {"coordinate": _c(a["x"], a["y"])}}]
+    if t == "scroll":
+        out: List[Step] = []
+        amt = lambda v: max(1, round(abs(v) / per_click))  # noqa: E731
+        sx, sy = a.get("scroll_x", 0) or 0, a.get("scroll_y", 0) or 0
+        if sy:
+            out.append({"member": "scroll", "input": {"coordinate": _c(a["x"], a["y"]), "scroll_direction": "down" if sy > 0 else "up", "scroll_amount": amt(sy)}})
+        if sx:
+            out.append({"member": "scroll", "input": {"coordinate": _c(a["x"], a["y"]), "scroll_direction": "right" if sx > 0 else "left", "scroll_amount": amt(sx)}})
+        return out
+    if t == "type":
+        return [{"member": "type", "input": {"text": a.get("text", "")}}]
+    if t == "wait":
+        return [{"member": "wait", "input": {"duration": max(1, round((a.get("ms") or 2000) / 1000))}}]
+    if t == "screenshot":
+        return []
+    raise ValueError(f"Unsupported OpenAI computer action: {t}")
+
+
+def run_openai_action(
+    client: AllternitComputers,
+    computer_id: str,
+    call_id: str,
+    action: Dict[str, Any],
+    display: Optional[Dict[str, int]] = None,
+    pixels_per_scroll_click: int = 100,
+) -> Dict[str, Any]:
+    """Returns ``{"output": <computer_call_output item>, "error": <failed result or None>}``."""
+    frame = {"model_frame": display, "coordinate_space": "pixels"} if display else {}
+    error = None
+    for step in openai_to_calls(action, pixels_per_scroll_click):
+        r = client.toolset(computer_id, {"toolset": "computer", **step, **frame})
+        if r.get("is_error"):
+            error = r
+            break
+    s = client.toolset(computer_id, {"toolset": "computer", "member": "screenshot", "input": {}, **frame})
+    img = result_image(s)
+    if not img:
+        raise RuntimeError("Allternit computer returned no screenshot.")
+    return {
+        "output": {
+            "type": "computer_call_output",
+            "call_id": call_id,
+            "output": {"type": "computer_screenshot", "image_url": f"data:{img['media_type']};base64,{img['data']}"},
+        },
+        "error": error,
+    }

allternit_computer_driver-0.1.0/allternit_computer_driver.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: allternit-computer-driver
+Version: 0.1.0
+Summary: Drop-in drivers for Allternit hosted computers: a plain client plus Anthropic (computer/browser toolset), OpenAI computer-use and Gemini computer_use adapters.
+License: Apache-2.0
+Project-URL: Documentation, https://docs.allternit.com/api/platform/sdks/python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+
+# allternit-computer-driver
+
+Drive an Allternit hosted computer (`/v1/computers`) from Claude, OpenAI computer use, or Gemini computer use. Standard library only; `pip install allternit-computer-driver[anthropic]` adds the Anthropic SDK. Needs a project key with the `computers` scope and the hosted driver turned on for the project.
+
+```python
+from allternit_computer_driver import AllternitComputers
+client = AllternitComputers()  # reads ALLTERNIT_API_KEY
+computer = client.create(name="agent-1")
+```
+
+## Claude
+
+```python
+from allternit_computer_driver.anthropic import AllternitComputerToolset
+toolset = AllternitComputerToolset(client, computer["id"], on_approval=lambda approval: ask_a_person(approval))
+```
+
+Each member runs on the server through `POST /v1/computers/{id}/toolset`. A 409 `approval_required` calls `on_approval`: `True` approves it and resends with the grant, `False` returns the held result to the model as an error. When the installed `anthropic` package has `anthropic.tools.computer` / `anthropic.tools.browser`, these classes subclass its abstract toolsets. Older releases get a small stand-in with `to_dict()` and `tool_result(tool_use)` for a hand-written loop.
+
+## OpenAI computer use
+
+```python
+from allternit_computer_driver import run_openai_action
+step = run_openai_action(client, computer_id, call.call_id, call.action.model_dump(), display={"width": 1280, "height": 800})
+next_input.append(step["output"])
+```
+
+## Gemini computer use
+
+```python
+from allternit_computer_driver import run_gemini_call
+step = run_gemini_call(client, computer_id, fc.name, dict(fc.args))
+# step["function_response"] and step["inline_data"] (0-999 coords sent as normalized_1000)
+```
+
+The OpenAI and Gemini adapters raise `ApprovalRequiredError`; call `client.approve()` and resend. All other failures raise `AllternitApiError` with `status`, `code` and `type`.

allternit_computer_driver-0.1.0/allternit_computer_driver.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+allternit_computer_driver/__init__.py
+allternit_computer_driver/anthropic.py
+allternit_computer_driver/client.py
+allternit_computer_driver/gemini.py
+allternit_computer_driver/openai.py
+allternit_computer_driver/py.typed
+allternit_computer_driver.egg-info/PKG-INFO
+allternit_computer_driver.egg-info/SOURCES.txt
+allternit_computer_driver.egg-info/dependency_links.txt
+allternit_computer_driver.egg-info/requires.txt
+allternit_computer_driver.egg-info/top_level.txt

allternit_computer_driver-0.1.0/allternit_computer_driver.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

allternit_computer_driver-0.1.0/allternit_computer_driver.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[anthropic]
+anthropic

allternit_computer_driver-0.1.0/allternit_computer_driver.egg-info/top_level.txt

@@ -0,0 +1 @@
+allternit_computer_driver

allternit_computer_driver-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "allternit-computer-driver"
+version = "0.1.0"
+description = "Drop-in drivers for Allternit hosted computers: a plain client plus Anthropic (computer/browser toolset), OpenAI computer-use and Gemini computer_use adapters."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+dependencies = []
+
+[project.optional-dependencies]
+anthropic = ["anthropic"]
+
+[project.urls]
+Documentation = "https://docs.allternit.com/api/platform/sdks/python"
+
+[tool.setuptools]
+packages = ["allternit_computer_driver"]
+
+[tool.setuptools.package-data]
+allternit_computer_driver = ["py.typed"]

allternit_computer_driver-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+