asiflow-hyper 1.0.0__tar.gz

asiflow_hyper-1.0.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: asiflow-hyper
+Version: 1.0.0
+Summary: Python client for the Hyper Agent API (OAuth 2.1, REST v1): delegate objectives, run and verify work, read evidence.
+Author: ASIFlow
+License: MIT
+Project-URL: Homepage, https://hyper.asiflow.ai
+Project-URL: Documentation, https://hyper.asiflow.ai/docs/platform/agent-api
+Project-URL: OpenAPI, https://api.hyper.asiflow.ai/openapi.json
+Keywords: hyper,agent,ai software engineer,oauth,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25
+
+# asiflow-hyper
+
+Python client for the [Hyper Agent API](https://hyper.asiflow.ai/docs/platform/agent-api): delegate a software objective to Hyper, run and verify the work, read the evidence. Thin and honest: every method is one documented REST call (`https://api.hyper.asiflow.ai/openapi.json`); errors are the API's RFC 9457 problems.
+
+```python
+from asiflow_hyper import HyperClient, device_login
+
+token = device_login(client_name="my-agent", scope="objectives:read objectives:write runs:write evidence:read deploy:verify offline_access")
+hyper = HyperClient(token=token.access_token)
+
+job = hyper.create_objective(name="Bakery site", objective="A one-page site for Nour's bakery with a contact form.")
+job = hyper.wait_job(job["id"])
+run = hyper.start_run(job["result"]["project_id"], policy={"budget_cap_usd": 10})
+run = hyper.wait_run(run["result"]["run_id"], on_needs_you=lambda card: "approved")
+for attempt in run["attempts"]:
+    if attempt["status"] == "verified":
+        print(hyper.attempt_evidence(attempt["id"]))
+```
+
+The `agent-interop-e2e` lane runs this client against production on every Hyper deploy.

asiflow_hyper-1.0.0/README.md

@@ -0,0 +1,20 @@
+# asiflow-hyper
+
+Python client for the [Hyper Agent API](https://hyper.asiflow.ai/docs/platform/agent-api): delegate a software objective to Hyper, run and verify the work, read the evidence. Thin and honest: every method is one documented REST call (`https://api.hyper.asiflow.ai/openapi.json`); errors are the API's RFC 9457 problems.
+
+```python
+from asiflow_hyper import HyperClient, device_login
+
+token = device_login(client_name="my-agent", scope="objectives:read objectives:write runs:write evidence:read deploy:verify offline_access")
+hyper = HyperClient(token=token.access_token)
+
+job = hyper.create_objective(name="Bakery site", objective="A one-page site for Nour's bakery with a contact form.")
+job = hyper.wait_job(job["id"])
+run = hyper.start_run(job["result"]["project_id"], policy={"budget_cap_usd": 10})
+run = hyper.wait_run(run["result"]["run_id"], on_needs_you=lambda card: "approved")
+for attempt in run["attempts"]:
+    if attempt["status"] == "verified":
+        print(hyper.attempt_evidence(attempt["id"]))
+```
+
+The `agent-interop-e2e` lane runs this client against production on every Hyper deploy.

asiflow_hyper-1.0.0/asiflow_hyper/__init__.py

@@ -0,0 +1,6 @@
+"""asiflow-hyper — Python client for the Hyper Agent API."""
+from .auth import DeviceToken, TokenSet, device_login, jwt_bearer_login, refresh, register_client
+from .client import HyperClient, HyperError
+
+__all__ = ["HyperClient", "HyperError", "DeviceToken", "TokenSet", "device_login", "jwt_bearer_login", "refresh", "register_client"]
+__version__ = "1.0.0"

asiflow_hyper-1.0.0/asiflow_hyper/auth.py

@@ -0,0 +1,91 @@
+"""OAuth 2.1 helpers for the Hyper authorization server (RFC 7591 registration,
+RFC 8628 device grant, RFC 7523 jwt-bearer, rotating refresh). Human-facing:
+``device_login`` prints the code the person types at hyper.asiflow.ai."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional
+
+import httpx
+
+DEFAULT_BASE = "https://api.hyper.asiflow.ai"
+DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+
+
+@dataclass
+class TokenSet:
+    access_token: str
+    refresh_token: Optional[str]
+    expires_in: int
+    scope: str
+    token_type: str = "Bearer"
+
+
+@dataclass
+class DeviceToken(TokenSet):
+    client_id: str = ""
+
+
+class AuthError(Exception):
+    pass
+
+
+def _post_form(base: str, path: str, data: Dict[str, str], transport: Optional[httpx.BaseTransport] = None) -> Dict:
+    with httpx.Client(base_url=base.rstrip("/"), timeout=30.0, transport=transport) as c:
+        r = c.post(path, data=data, headers={"Accept": "application/json"})
+        body = r.json() if r.content else {}
+        if r.status_code >= 400:
+            raise AuthError(f"{r.status_code} {body.get('error')}: {body.get('error_description') or body}")
+        return body
+
+
+def register_client(*, client_name: str, scope: str, grant_types: Optional[List[str]] = None,
+                    redirect_uris: Optional[List[str]] = None, base: str = DEFAULT_BASE, transport: Optional[httpx.BaseTransport] = None) -> Dict:
+    """RFC 7591 dynamic registration. Unverified clients receive read-only scopes until reviewed."""
+    body = {"client_name": client_name, "scope": scope, "grant_types": grant_types or [DEVICE_GRANT, "refresh_token"],
+            "redirect_uris": redirect_uris or ["https://hyper.asiflow.ai/oauth/callback"]}
+    with httpx.Client(base_url=base.rstrip("/"), timeout=30.0, transport=transport) as c:
+        r = c.post("/oauth/register", json=body, headers={"Accept": "application/json"})
+        out = r.json() if r.content else {}
+        if r.status_code != 201:
+            raise AuthError(f"register → {r.status_code} {out}")
+        return out
+
+
+def device_login(*, client_name: str, scope: str, client_id: Optional[str] = None, base: str = DEFAULT_BASE,
+                 prompt: Callable[[str, str], None] = None, transport: Optional[httpx.BaseTransport] = None, timeout_s: float = 600) -> DeviceToken:
+    """Register (unless client_id is given), start the device grant, show the person the
+    code, poll until they approve. ``prompt(verification_uri, user_code)`` defaults to print."""
+    cid = client_id or register_client(client_name=client_name, scope=scope, base=base, transport=transport)["client_id"]
+    dev = _post_form(base, "/oauth/device", {"client_id": cid, "scope": scope}, transport)
+    (prompt or (lambda uri, code: print(f"Open {uri} and enter the code {code}")))(dev.get("verification_uri_complete") or dev["verification_uri"], dev["user_code"])
+    interval, deadline = float(dev.get("interval") or 5), time.time() + timeout_s
+    while time.time() < deadline:
+        time.sleep(interval)
+        try:
+            tok = _post_form(base, "/oauth/token", {"grant_type": DEVICE_GRANT, "client_id": cid, "device_code": dev["device_code"]}, transport)
+        except AuthError as exc:
+            msg = str(exc)
+            if "authorization_pending" in msg:
+                continue
+            if "slow_down" in msg:
+                interval += 5
+                continue
+            raise
+        return DeviceToken(access_token=tok["access_token"], refresh_token=tok.get("refresh_token"), expires_in=int(tok.get("expires_in") or 900),
+                           scope=str(tok.get("scope") or scope), client_id=cid)
+    raise AuthError("the person did not approve the device code in time")
+
+
+def jwt_bearer_login(*, client_id: str, assertion: str, scope: str, base: str = DEFAULT_BASE, transport: Optional[httpx.BaseTransport] = None) -> TokenSet:
+    """RFC 7523: exchange a signed assertion (a key Hyper trusts for this client) for an access token."""
+    tok = _post_form(base, "/oauth/token", {"grant_type": JWT_BEARER_GRANT, "client_id": client_id, "assertion": assertion, "scope": scope}, transport)
+    return TokenSet(access_token=tok["access_token"], refresh_token=tok.get("refresh_token"), expires_in=int(tok.get("expires_in") or 900), scope=str(tok.get("scope") or scope))
+
+
+def refresh(*, client_id: str, refresh_token: str, base: str = DEFAULT_BASE, transport: Optional[httpx.BaseTransport] = None) -> TokenSet:
+    """Rotating refresh: the old token is invalid after this call; reuse revokes the family."""
+    tok = _post_form(base, "/oauth/token", {"grant_type": "refresh_token", "client_id": client_id, "refresh_token": refresh_token}, transport)
+    return TokenSet(access_token=tok["access_token"], refresh_token=tok.get("refresh_token"), expires_in=int(tok.get("expires_in") or 900), scope=str(tok.get("scope") or ""))

asiflow_hyper-1.0.0/asiflow_hyper/client.py

@@ -0,0 +1,125 @@
+"""The REST v1 client. One method per documented call; nothing invented."""
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Callable, Dict, List, Optional
+
+import httpx
+
+DEFAULT_BASE = "https://api.hyper.asiflow.ai"
+TERMINAL_JOB = ("succeeded", "failed", "cancelled")
+TERMINAL_RUN = ("completed", "failed", "stopped")
+
+
+class HyperError(Exception):
+    """An RFC 9457 problem from the API: ``status``, ``type``, ``title``, ``detail``."""
+
+    def __init__(self, status: int, problem: Dict[str, Any]):
+        self.status, self.problem = status, problem
+        super().__init__(f"{status} {problem.get('title') or ''}: {problem.get('detail') or problem}")
+
+
+class HyperClient:
+    def __init__(self, token: str, *, base_url: str = DEFAULT_BASE, timeout: float = 30.0, transport: Optional[httpx.BaseTransport] = None,
+                 user_agent: str = "asiflow-hyper-python/1.0.0"):
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout, transport=transport,
+                                  headers={"Authorization": f"Bearer {token}", "User-Agent": user_agent, "Accept": "application/json"})
+
+    # ── transport ──────────────────────────────────────────────────────────
+    def _call(self, method: str, path: str, *, json: Any = None, idempotent: bool = False) -> Any:
+        headers = {"Idempotency-Key": str(uuid.uuid4())} if idempotent else {}
+        r = self._http.request(method, path, json=json, headers=headers)
+        if r.status_code >= 400:
+            try:
+                problem = r.json()
+            except ValueError:
+                problem = {"title": r.reason_phrase, "detail": r.text[:300]}
+            raise HyperError(r.status_code, problem)
+        return r.json() if r.content else None
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ── identity ───────────────────────────────────────────────────────────
+    def me(self) -> Dict[str, Any]:
+        return self._call("GET", "/v1/me")
+
+    # ── objectives and jobs ────────────────────────────────────────────────
+    def create_objective(self, *, name: str, objective: str, tasks: Optional[List[Dict[str, Any]]] = None,
+                         autonomy: str = "balanced", repo: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name, "objective": objective, "autonomy": autonomy}
+        if tasks is not None:
+            body["tasks"] = tasks
+        if repo:
+            body["repo"] = repo
+        return self._call("POST", "/v1/objectives", json=body, idempotent=True)
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        return self._call("GET", f"/v1/jobs/{job_id}")
+
+    def cancel_job(self, job_id: str) -> Dict[str, Any]:
+        return self._call("POST", f"/v1/jobs/{job_id}/cancel")
+
+    def wait_job(self, job_id: str, *, timeout_s: float = 900, interval_s: float = 5.0) -> Dict[str, Any]:
+        deadline = time.time() + timeout_s
+        while True:
+            job = self.get_job(job_id)
+            if job.get("terminal") or job.get("status") in TERMINAL_JOB + ("waiting_for_acceptance",):
+                return job
+            if time.time() > deadline:
+                raise TimeoutError(f"job {job_id} still {job.get('status')} after {timeout_s}s")
+            time.sleep(interval_s)
+
+    # ── projects, repos, runs ──────────────────────────────────────────────
+    def list_projects(self) -> Dict[str, Any]:
+        return self._call("GET", "/v1/projects")
+
+    def get_project(self, project_id: str) -> Dict[str, Any]:
+        return self._call("GET", f"/v1/projects/{project_id}")
+
+    def connect_repo(self, project_id: str, repo: str) -> Dict[str, Any]:
+        return self._call("POST", f"/v1/projects/{project_id}/repo", json={"repo": repo})
+
+    def start_run(self, project_id: str, *, scope: Optional[Dict[str, Any]] = None, policy: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._call("POST", f"/v1/projects/{project_id}/runs", json={"scope": scope or {"kind": "project"}, "policy": policy or {}}, idempotent=True)
+
+    def get_run(self, run_id: str) -> Dict[str, Any]:
+        return self._call("GET", f"/v1/runs/{run_id}")
+
+    def control_run(self, run_id: str, action: str) -> Dict[str, Any]:
+        if action not in ("pause", "resume", "stop"):
+            raise ValueError("action must be pause, resume or stop")
+        return self._call("POST", f"/v1/runs/{run_id}/{action}")
+
+    def wait_run(self, run_id: str, *, timeout_s: float = 1800, interval_s: float = 10.0,
+                 on_needs_you: Optional[Callable[[Dict[str, Any]], Any]] = None) -> Dict[str, Any]:
+        """Poll until the run ends. When it blocks on a card and ``on_needs_you`` is given,
+        the callback returns "approved" | "rejected" | "changes_requested" or (status, note)."""
+        deadline = time.time() + timeout_s
+        while True:
+            run = self.get_run(run_id)
+            if run.get("status") in TERMINAL_RUN:
+                return run
+            if run.get("status") == "blocked" and run.get("needs_you") and on_needs_you is not None:
+                for card in run["needs_you"]:
+                    answer = on_needs_you(card)
+                    status, note = (answer, None) if isinstance(answer, str) else (answer[0], answer[1])
+                    self.decide(card["id"], status=status, note=note)
+            if time.time() > deadline:
+                raise TimeoutError(f"run {run_id} still {run.get('status')} after {timeout_s}s")
+            time.sleep(interval_s)
+
+    # ── approvals and evidence ─────────────────────────────────────────────
+    def list_approvals(self, project_id: str) -> Dict[str, Any]:
+        return self._call("GET", f"/v1/projects/{project_id}/approvals")
+
+    def decide(self, approval_id: str, *, status: str, note: Optional[str] = None) -> Dict[str, Any]:
+        return self._call("POST", f"/v1/approvals/{approval_id}/decide", json={"status": status, "note": note})
+
+    def attempt_evidence(self, attempt_id: str) -> Dict[str, Any]:
+        return self._call("GET", f"/v1/attempts/{attempt_id}/evidence")
+
+    def verify_deployment(self, url: str, *, expect_text: Optional[str] = None) -> Dict[str, Any]:
+        return self._call("POST", "/v1/verify/deployment", json={"url": url, "expect_text": expect_text})

asiflow_hyper-1.0.0/asiflow_hyper.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: asiflow-hyper
+Version: 1.0.0
+Summary: Python client for the Hyper Agent API (OAuth 2.1, REST v1): delegate objectives, run and verify work, read evidence.
+Author: ASIFlow
+License: MIT
+Project-URL: Homepage, https://hyper.asiflow.ai
+Project-URL: Documentation, https://hyper.asiflow.ai/docs/platform/agent-api
+Project-URL: OpenAPI, https://api.hyper.asiflow.ai/openapi.json
+Keywords: hyper,agent,ai software engineer,oauth,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25
+
+# asiflow-hyper
+
+Python client for the [Hyper Agent API](https://hyper.asiflow.ai/docs/platform/agent-api): delegate a software objective to Hyper, run and verify the work, read the evidence. Thin and honest: every method is one documented REST call (`https://api.hyper.asiflow.ai/openapi.json`); errors are the API's RFC 9457 problems.
+
+```python
+from asiflow_hyper import HyperClient, device_login
+
+token = device_login(client_name="my-agent", scope="objectives:read objectives:write runs:write evidence:read deploy:verify offline_access")
+hyper = HyperClient(token=token.access_token)
+
+job = hyper.create_objective(name="Bakery site", objective="A one-page site for Nour's bakery with a contact form.")
+job = hyper.wait_job(job["id"])
+run = hyper.start_run(job["result"]["project_id"], policy={"budget_cap_usd": 10})
+run = hyper.wait_run(run["result"]["run_id"], on_needs_you=lambda card: "approved")
+for attempt in run["attempts"]:
+    if attempt["status"] == "verified":
+        print(hyper.attempt_evidence(attempt["id"]))
+```
+
+The `agent-interop-e2e` lane runs this client against production on every Hyper deploy.

asiflow_hyper-1.0.0/asiflow_hyper.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+asiflow_hyper/__init__.py
+asiflow_hyper/auth.py
+asiflow_hyper/client.py
+asiflow_hyper.egg-info/PKG-INFO
+asiflow_hyper.egg-info/SOURCES.txt
+asiflow_hyper.egg-info/dependency_links.txt
+asiflow_hyper.egg-info/requires.txt
+asiflow_hyper.egg-info/top_level.txt

asiflow_hyper-1.0.0/asiflow_hyper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

asiflow_hyper-1.0.0/asiflow_hyper.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.25

asiflow_hyper-1.0.0/asiflow_hyper.egg-info/top_level.txt

@@ -0,0 +1 @@
+asiflow_hyper

asiflow_hyper-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "asiflow-hyper"
+version = "1.0.0"
+description = "Python client for the Hyper Agent API (OAuth 2.1, REST v1): delegate objectives, run and verify work, read evidence."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "ASIFlow" }]
+dependencies = ["httpx>=0.25"]
+keywords = ["hyper", "agent", "ai software engineer", "oauth", "mcp"]
+classifiers = ["Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent"]
+
+[project.urls]
+Homepage = "https://hyper.asiflow.ai"
+Documentation = "https://hyper.asiflow.ai/docs/platform/agent-api"
+OpenAPI = "https://api.hyper.asiflow.ai/openapi.json"
+
+[tool.setuptools.packages.find]
+include = ["asiflow_hyper*"]

asiflow_hyper-1.0.0/setup.cfg

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