r2flow-cloud-client 0.1.0__tar.gz

r2flow_cloud_client-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+*.egg-info/
+dist/
+node_modules/
+designer-web/dist/
+frontend/dist/
+.env
+flow.json
+flows/
+*.log
+.vscode/
+.idea/
+.DS_Store

r2flow_cloud_client-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.5
+Name: r2flow-cloud-client
+Version: 0.1.0
+Summary: Thin Python client for the r2flow-cloud orchestrator REST API
+Author: 2kurosss
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.18; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# r2flow-cloud-client
+
+Thin Python client for the [r2flow-cloud](../README.md) orchestrator REST API.
+
+```bash
+pip install r2flow-cloud-client
+```
+
+```python
+from r2flow_cloud_client import R2FlowCloud
+
+sc = R2FlowCloud("http://localhost:8000", token="r2f_...")
+
+process = sc.create_process("hello", files={"main.py": 'print("hi")'})
+agent = sc.list_agents()[0]
+sc.deploy_process(process["id"], agent["id"])
+run = sc.run_process(process["id"], agent["id"])
+result = sc.wait_run(process["id"], run["id"], timeout_s=120)
+print(result["status"])
+
+# REFramework-style queues
+sc.create_queue("invoices")
+sc.add_queue_items("invoices", [{"file": "a.pdf"}, {"file": "b.pdf"}])
+item = sc.claim_queue_item(agent["id"], "invoices", run["id"])
+sc.complete_queue_item(agent["id"], item["id"], run["id"], status="success")
+```
+
+Any HTTP client works too — the API is plain REST with Swagger at `/docs`.

r2flow_cloud_client-0.1.0/README.md

@@ -0,0 +1,28 @@
+# r2flow-cloud-client
+
+Thin Python client for the [r2flow-cloud](../README.md) orchestrator REST API.
+
+```bash
+pip install r2flow-cloud-client
+```
+
+```python
+from r2flow_cloud_client import R2FlowCloud
+
+sc = R2FlowCloud("http://localhost:8000", token="r2f_...")
+
+process = sc.create_process("hello", files={"main.py": 'print("hi")'})
+agent = sc.list_agents()[0]
+sc.deploy_process(process["id"], agent["id"])
+run = sc.run_process(process["id"], agent["id"])
+result = sc.wait_run(process["id"], run["id"], timeout_s=120)
+print(result["status"])
+
+# REFramework-style queues
+sc.create_queue("invoices")
+sc.add_queue_items("invoices", [{"file": "a.pdf"}, {"file": "b.pdf"}])
+item = sc.claim_queue_item(agent["id"], "invoices", run["id"])
+sc.complete_queue_item(agent["id"], item["id"], run["id"], status="success")
+```
+
+Any HTTP client works too — the API is plain REST with Swagger at `/docs`.

r2flow_cloud_client-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "r2flow-cloud-client"
+version = "0.1.0"
+description = "Thin Python client for the r2flow-cloud orchestrator REST API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "2kurosss" }]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=1.0", "ruff>=0.12", "mypy>=1.18"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/r2flow_cloud_client"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+# Thin JSON-over-HTTP wrapper: responses are Any by design.
+disable_error_code = ["no-any-return"]

r2flow_cloud_client-0.1.0/src/r2flow_cloud_client/__init__.py

@@ -0,0 +1,5 @@
+"""Thin Python client for the r2flow-cloud orchestrator REST API."""
+
+from r2flow_cloud_client.client import R2FlowCloud, R2FlowCloudError
+
+__all__ = ["R2FlowCloud", "R2FlowCloudError"]

r2flow_cloud_client-0.1.0/src/r2flow_cloud_client/client.py

@@ -0,0 +1,267 @@
+"""Thin Python client for the r2flow-cloud orchestrator REST API.
+
+Works with any r2flow-cloud >= 0.1 install:
+
+    from r2flow_cloud_client import R2FlowCloud
+
+    sc = R2FlowCloud("http://localhost:8000", token="r2f_...")
+    process = sc.create_process("hello", files={"main.py": 'print("hi")'})
+    agent = sc.list_agents()[0]
+    sc.deploy_process(process["id"], agent["id"])
+    run = sc.run_process(process["id"], agent["id"])
+    sc.wait_run(process["id"], run["id"])  # blocks until terminal
+
+Any HTTP client works too — the API is plain REST; this wrapper only saves
+boilerplate. ``httpx`` (sync) is the only dependency.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+__all__ = ["R2FlowCloud", "R2FlowCloudError"]
+
+_TERMINAL_STATUSES = {"completed", "failed", "stopped", "system_failed"}
+
+
+class R2FlowCloudError(RuntimeError):
+    """Non-2xx response from the orchestrator."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"API error {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+class R2FlowCloud:
+    """Sync client for the r2flow-cloud REST API (v1, paths ``/api/...``)."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        token: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        self._client = httpx.Client(base_url=base_url.rstrip("/"), headers=headers, timeout=timeout)
+
+    # ------------------------------------------------------------- internals
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        res = self._client.request(method, path, **kwargs)
+        if res.status_code >= 400:
+            detail = res.text
+            try:
+                detail = res.json().get("detail", res.text)
+            except ValueError:
+                pass
+            raise R2FlowCloudError(res.status_code, detail)
+        if res.status_code == 204 or not res.content:
+            return None
+        return res.json()
+
+    def _get(self, path: str, **kwargs: Any) -> Any:
+        return self._request("GET", path, **kwargs)
+
+    def _post(self, path: str, **kwargs: Any) -> Any:
+        return self._request("POST", path, **kwargs)
+
+    def _put(self, path: str, **kwargs: Any) -> Any:
+        return self._request("PUT", path, **kwargs)
+
+    def _delete(self, path: str) -> None:
+        self._request("DELETE", path)
+
+    # ------------------------------------------------------------- processes
+
+    def list_processes(self) -> list[dict[str, Any]]:
+        return self._get("/api/processes")
+
+    def create_process(
+        self,
+        name: str,
+        files: dict[str, str],
+        entry_point: str = "main.py",
+        description: str | None = None,
+        requirements: list[str] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": name,
+            "entry_point": entry_point,
+            "files": files,
+            "requirements": requirements or [],
+        }
+        if description:
+            payload["description"] = description
+        return self._post("/api/processes", json=payload)
+
+    def get_process(self, process_id: str) -> dict[str, Any]:
+        return self._get(f"/api/processes/{process_id}")
+
+    def update_process(
+        self,
+        process_id: str,
+        files: dict[str, str] | None = None,
+        entry_point: str | None = None,
+        requirements: list[str] | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if files is not None:
+            payload["files"] = files
+        if entry_point is not None:
+            payload["entry_point"] = entry_point
+        if requirements is not None:
+            payload["requirements"] = requirements
+        if description is not None:
+            payload["description"] = description
+        return self._put(f"/api/processes/{process_id}", json=payload)
+
+    def delete_process(self, process_id: str) -> None:
+        self._delete(f"/api/processes/{process_id}")
+
+    def deploy_process(self, process_id: str, agent_id: str) -> dict[str, Any]:
+        return self._post(
+            f"/api/processes/{process_id}/deploy", json={"agent_id": agent_id}
+        )
+
+    def run_process(self, process_id: str, agent_id: str) -> dict[str, Any]:
+        return self._post(
+            f"/api/processes/{process_id}/run", json={"agent_id": agent_id}
+        )
+
+    def stop_run(self, process_id: str, run_id: str) -> dict[str, Any]:
+        return self._post(f"/api/processes/{process_id}/stop", json={"run_id": run_id})
+
+    def list_runs(self, process_id: str, limit: int = 50) -> list[dict[str, Any]]:
+        return self._get(f"/api/processes/{process_id}/runs", params={"limit": limit})
+
+    def get_logs(self, process_id: str, limit: int = 200) -> list[dict[str, Any]]:
+        return self._get(f"/api/processes/{process_id}/logs", params={"limit": limit})
+
+    def wait_run(
+        self, process_id: str, run_id: str, timeout_s: float = 300.0, poll_s: float = 1.0
+    ) -> dict[str, Any]:
+        """Poll the run until it reaches a terminal status (or timeout)."""
+        deadline = time.monotonic() + timeout_s
+        while time.monotonic() < deadline:
+            run = self._get(f"/api/processes/{process_id}/runs", params={"limit": 50})
+            for r in run:
+                if r["id"] == run_id:
+                    if str(r.get("status", "")).lower() in _TERMINAL_STATUSES:
+                        return r
+                    break
+            time.sleep(poll_s)
+        raise R2FlowCloudError(408, f"run {run_id} did not finish in {timeout_s}s")
+
+    # ---------------------------------------------------------------- agents
+
+    def list_agents(self) -> list[dict[str, Any]]:
+        return self._get("/api/agents")
+
+    def register_agent(
+        self, name: str, url: str, join_token: str | None = None
+    ) -> dict[str, Any]:
+        headers = {"Authorization": f"Bearer {join_token}"} if join_token else None
+        return self._post(
+            "/api/agents",
+            json={"name": name, "url": url},
+            headers=headers,
+        )
+
+    def delete_agent(self, agent_id: str) -> None:
+        self._delete(f"/api/agents/{agent_id}")
+
+    # ---------------------------------------------------------------- queues
+
+    def list_queues(self) -> list[dict[str, Any]]:
+        return self._get("/api/queues")
+
+    def create_queue(self, name: str, max_attempts: int = 3) -> dict[str, Any]:
+        return self._post("/api/queues", json={"name": name, "max_attempts": max_attempts})
+
+    def delete_queue(self, name: str) -> None:
+        self._delete(f"/api/queues/{name}")
+
+    def add_queue_items(
+        self, name: str, payloads: list[dict[str, Any]], idempotency_keys: list[str] | None = None
+    ) -> list[dict[str, Any]]:
+        items = [
+            {"payload": p, **({"idempotency_key": k} if k else {})}
+            for p, k in zip(payloads, idempotency_keys or [], strict=False)
+        ]
+        return self._post(f"/api/queues/{name}/items", json={"items": items})
+
+    def claim_queue_item(
+        self, agent_id: str, name: str, run_id: str, lease_seconds: int = 300
+    ) -> dict[str, Any] | None:
+        """Claim one item for a run; returns ``None`` when the queue is empty."""
+        res = self._post(
+            f"/api/agents/{agent_id}/queues/{name}/claim",
+            json={"run_id": run_id, "lease_seconds": lease_seconds},
+        )
+        return res.get("item")
+
+    def complete_queue_item(
+        self,
+        agent_id: str,
+        item_id: str,
+        run_id: str,
+        status: str = "success",
+        error: str | None = None,
+        result: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Complete an item; ``system_failed`` requeues it while attempts remain."""
+        payload: dict[str, Any] = {"run_id": run_id, "status": status}
+        if error:
+            payload["error"] = error
+        if result is not None:
+            payload["result"] = result
+        return self._request(
+            "PATCH",
+            f"/api/agents/{agent_id}/queue-items/{item_id}",
+            json=payload,
+        )
+
+    # -------------------------------------------------------------- triggers
+
+    def list_triggers(self) -> list[dict[str, Any]]:
+        return self._get("/api/triggers")
+
+    def create_trigger(
+        self,
+        name: str,
+        agent_id: str,
+        process_id: str,
+        run_at: str,
+        repeat: str = "once",
+        timezone: str = "Europe/Moscow",
+    ) -> dict[str, Any]:
+        return self._post(
+            "/api/triggers",
+            json={
+                "name": name,
+                "agent_id": agent_id,
+                "process_id": process_id,
+                "run_at": run_at,
+                "repeat": repeat,
+                "timezone": timezone,
+            },
+        )
+
+    def delete_trigger(self, trigger_id: str) -> None:
+        self._delete(f"/api/triggers/{trigger_id}")
+
+    # ---------------------------------------------------------------- tokens
+
+    def list_tokens(self) -> list[dict[str, Any]]:
+        return self._get("/api/tokens")
+
+    def create_token(self, name: str) -> dict[str, Any]:
+        return self._post("/api/tokens", json={"name": name})
+
+    def revoke_token(self, token_id: str) -> None:
+        self._delete(f"/api/tokens/{token_id}")

r2flow_cloud_client-0.1.0/tests/test_client.py

@@ -0,0 +1,80 @@
+"""Client tests against a mocked transport (no live server needed)."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from r2flow_cloud_client import R2FlowCloud, R2FlowCloudError
+
+
+def _mock_app() -> httpx.MockTransport:
+    state = {"runs": [], "calls": []}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        state["calls"].append((request.method, request.url.path))
+        path = request.url.path
+        auth = request.headers.get("authorization", "")
+        if not auth.startswith("Bearer r2f_"):
+            return httpx.Response(401, json={"detail": "Not authenticated"})
+        if path == "/api/processes" and request.method == "POST":
+            return httpx.Response(
+                201, json={"id": "p1", "name": "hello", "entry_point": "main.py"}
+            )
+        if path == "/api/agents" and request.method == "GET":
+            return httpx.Response(200, json=[{"id": "a1", "name": "ag", "url": "u"}])
+        if path.endswith("/deploy"):
+            return httpx.Response(201, json={"id": "d1"})
+        if path.endswith("/run"):
+            return httpx.Response(201, json={"id": "r1", "status": "pending"})
+        if path.endswith("/runs") and request.method == "GET":
+            return httpx.Response(
+                200,
+                json=[{"id": "r1", "status": state.get("status", "completed")}],
+            )
+        if path == "/api/queues/invoices/items" and request.method == "POST":
+            return httpx.Response(201, json=[{"id": "q1", "status": "new", "attempts": 0}])
+        if path.endswith("/claim") and request.method == "POST":
+            return httpx.Response(
+                200,
+                json={"item": {"id": "q1", "payload": {"file": "a.pdf"}, "attempts": 0}},
+            )
+        if request.method == "PATCH":
+            return httpx.Response(200, json={"id": "q1", "status": "success", "attempts": 1})
+        return httpx.Response(404, json={"detail": "Not Found"})
+
+    return httpx.MockTransport(handler)
+
+
+@pytest.fixture()
+def sc() -> R2FlowCloud:
+    client = R2FlowCloud("http://test", token="r2f_test")
+    client._client = httpx.Client(
+        transport=_mock_app(), base_url="http://test", headers={"Authorization": "Bearer r2f_test"}
+    )
+    return client
+
+
+def test_full_process_flow(sc: R2FlowCloud) -> None:
+    process = sc.create_process("hello", files={"main.py": "print(1)"})
+    assert process["id"] == "p1"
+    agent = sc.list_agents()[0]
+    sc.deploy_process(process["id"], agent["id"])
+    run = sc.run_process(process["id"], agent["id"])
+    assert run["id"] == "r1"
+    finished = sc.wait_run(process["id"], run["id"], timeout_s=2)
+    assert finished["status"] == "completed"
+
+
+def test_queue_flow(sc: R2FlowCloud) -> None:
+    items = sc.add_queue_items("invoices", [{"file": "a.pdf"}])
+    assert items[0]["id"] == "q1"
+    item = sc.claim_queue_item("a1", "invoices", "r1")
+    assert item is not None and item["payload"] == {"file": "a.pdf"}
+    state = sc.complete_queue_item("a1", item["id"], "r1", status="success")
+    assert state["status"] == "success"
+
+
+def test_error_raises(sc: R2FlowCloud) -> None:
+    with pytest.raises(R2FlowCloudError):
+        sc.get_process("missing")