rayrun-sdk 0.8.0__py3-none-any.whl

rayrun/__init__.py

@@ -0,0 +1,3 @@
+from .client import AsyncRayrun, Rayrun, RayrunApiError
+
+__all__ = ["AsyncRayrun", "Rayrun", "RayrunApiError"]

rayrun/client.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+import httpx
+
+
+JsonObject = Mapping[str, Any]
+
+
+def _page_params(limit: int, cursor: Optional[str]) -> Dict[str, Any]:
+    return {"limit": limit, **({"cursor": cursor} if cursor is not None else {})}
+
+
+class RayrunApiError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        request_id: Optional[str],
+        status: int,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.request_id = request_id
+        self.status = status
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        body = response.json()
+    except ValueError:
+        body = {}
+    error = body.get("error", {}) if isinstance(body, dict) else {}
+    raise RayrunApiError(
+        error.get("message", f"Rayrun API request failed with HTTP {response.status_code}."),
+        code=error.get("code", "request_failed"),
+        request_id=error.get("requestId") or response.headers.get("rayrun-request-id"),
+        status=response.status_code,
+    )
+
+
+class ExternalPrincipals:
+    def __init__(self, client: httpx.Client) -> None:
+        self._client = client
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = self._client.request(method, path, **kwargs)
+        _raise_for_status(response)
+        return None if response.status_code == 204 else response.json()
+
+    def upsert(
+        self,
+        external_id: str,
+        *,
+        display_name: Optional[str] = None,
+        metadata: Optional[JsonObject] = None,
+    ) -> Dict[str, str]:
+        return self._request(
+            "POST",
+            "/external-principals",
+            json={
+                "displayName": display_name,
+                "externalId": external_id,
+                "metadata": dict(metadata or {}),
+            },
+        )
+
+    def list(self, *, limit: int = 50, cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._request(
+            "GET", "/external-principals", params=_page_params(limit, cursor)
+        )
+
+    def delete(self, principal_uid: str) -> None:
+        self._request("DELETE", f"/external-principals/{principal_uid}")
+
+    def create_session(
+        self,
+        principal_uid: str,
+        *,
+        expires_in_seconds: int = 3600,
+        runtime_context: Optional[JsonObject] = None,
+        tool_access_profile_uid: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/external-principals/{principal_uid}/sessions",
+            json={
+                "expiresInSeconds": expires_in_seconds,
+                "runtimeContext": dict(runtime_context or {}),
+                "toolAccessProfileUid": tool_access_profile_uid,
+            },
+        )
+
+    def list_sessions(
+        self,
+        principal_uid: str,
+        *,
+        limit: int = 50,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return self._request(
+            "GET",
+            f"/external-principals/{principal_uid}/sessions",
+            params=_page_params(limit, cursor),
+        )
+
+    def revoke_session(self, principal_uid: str, session_uid: str) -> None:
+        self._request("DELETE", f"/external-principals/{principal_uid}/sessions/{session_uid}")
+
+    def create_connect_link(self, principal_uid: str, connection_uid: str) -> Dict[str, str]:
+        return self._request(
+            "POST",
+            f"/external-principals/{principal_uid}/connect-links",
+            json={"connectionUid": connection_uid},
+        )
+
+
+class AsyncExternalPrincipals:
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = await self._client.request(method, path, **kwargs)
+        _raise_for_status(response)
+        return None if response.status_code == 204 else response.json()
+
+    async def upsert(
+        self,
+        external_id: str,
+        *,
+        display_name: Optional[str] = None,
+        metadata: Optional[JsonObject] = None,
+    ) -> Dict[str, str]:
+        return await self._request(
+            "POST",
+            "/external-principals",
+            json={
+                "displayName": display_name,
+                "externalId": external_id,
+                "metadata": dict(metadata or {}),
+            },
+        )
+
+    async def list(
+        self, *, limit: int = 50, cursor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        return await self._request(
+            "GET", "/external-principals", params=_page_params(limit, cursor)
+        )
+
+    async def delete(self, principal_uid: str) -> None:
+        await self._request("DELETE", f"/external-principals/{principal_uid}")
+
+    async def create_session(
+        self,
+        principal_uid: str,
+        *,
+        expires_in_seconds: int = 3600,
+        runtime_context: Optional[JsonObject] = None,
+        tool_access_profile_uid: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return await self._request(
+            "POST",
+            f"/external-principals/{principal_uid}/sessions",
+            json={
+                "expiresInSeconds": expires_in_seconds,
+                "runtimeContext": dict(runtime_context or {}),
+                "toolAccessProfileUid": tool_access_profile_uid,
+            },
+        )
+
+    async def list_sessions(
+        self,
+        principal_uid: str,
+        *,
+        limit: int = 50,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return await self._request(
+            "GET",
+            f"/external-principals/{principal_uid}/sessions",
+            params=_page_params(limit, cursor),
+        )
+
+    async def revoke_session(self, principal_uid: str, session_uid: str) -> None:
+        await self._request("DELETE", f"/external-principals/{principal_uid}/sessions/{session_uid}")
+
+    async def create_connect_link(
+        self, principal_uid: str, connection_uid: str
+    ) -> Dict[str, str]:
+        return await self._request(
+            "POST",
+            f"/external-principals/{principal_uid}/connect-links",
+            json={"connectionUid": connection_uid},
+        )
+
+
+class Rayrun:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://ray.run",
+        timeout: float = 30.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Rayrun requires an api_key.")
+        self._client = httpx.Client(
+            base_url=f"{base_url.rstrip('/')}/v1",
+            headers={"Authorization": f"Bearer {api_key}", "User-Agent": "rayrun-python/0.8.0"},
+            timeout=timeout,
+            transport=transport,
+        )
+        self.external_principals = ExternalPrincipals(self._client)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Rayrun":
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        self.close()
+
+
+class AsyncRayrun:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://ray.run",
+        timeout: float = 30.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Rayrun requires an api_key.")
+        self._client = httpx.AsyncClient(
+            base_url=f"{base_url.rstrip('/')}/v1",
+            headers={"Authorization": f"Bearer {api_key}", "User-Agent": "rayrun-python/0.8.0"},
+            timeout=timeout,
+            transport=transport,
+        )
+        self.external_principals = AsyncExternalPrincipals(self._client)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncRayrun":
+        return self
+
+    async def __aexit__(self, *_args: Any) -> None:
+        await self.close()

rayrun/py.typed

@@ -0,0 +1 @@
+

rayrun_sdk-0.8.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: rayrun-sdk
+Version: 0.8.0
+Summary: Python SDK for Rayrun embedded agents and MCP infrastructure
+Project-URL: Documentation, https://ray.run/docs/public-api
+Project-URL: Homepage, https://ray.run
+Project-URL: Repository, https://github.com/rayrundev/rayrun
+Author-email: Rayrun <support@ray.run>
+License-Expression: MIT
+Keywords: agents,mcp,model-context-protocol,rayrun
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Rayrun Python SDK
+
+```sh
+pip install rayrun-sdk
+```
+
+Create one short-lived MCP session for an application user:
+
+```python
+import os
+
+from rayrun import Rayrun
+
+with Rayrun(os.environ["RAYRUN_API_KEY"]) as rayrun:
+    principal = rayrun.external_principals.upsert(
+        "customer_123",
+        display_name="Ada",
+        metadata={"plan": "pro"},
+    )
+    session = rayrun.external_principals.create_session(
+        principal["uid"],
+        runtime_context={"accountId": "customer_123", "plan": "pro"},
+    )
+
+    page = rayrun.external_principals.list_sessions(principal["uid"], limit=50)
+    if page["page"]["nextCursor"]:
+        next_page = rayrun.external_principals.list_sessions(
+            principal["uid"], cursor=page["page"]["nextCursor"], limit=50
+        )
+
+print(session["endpoint"], session["sessionToken"])
+```
+
+`AsyncRayrun` exposes the same methods for async applications. Use a key with
+`principals:read`, `principals:write`, `sessions:read`, and `sessions:write`. Create a Connect Link
+with `create_connect_link(principal_uid, connection_uid)` when the user must authorize an upstream
+OAuth account. Correlate the returned `uid` with `connectLinkUid` in either terminal webhook:
+`external.authorization.completed` or `external.authorization.failed` (`provider_denied`,
+`incomplete_response`, `authorization_failed`, or `expired`). A session created without
+`tool_access_profile_uid` is read-only; pass an access profile to define an explicit tool ceiling that
+includes approved mutations.

rayrun_sdk-0.8.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+rayrun/__init__.py,sha256=_KixIpQE2Wxx33NPQ6ojNmmKMoDp5Q1Km7Sq1-Xbj8I,111
+rayrun/client.py,sha256=eEO6dI5YqFsgEWBtkn5c-LUwkKr6xfOsqFjZcIIEJRg,8010
+rayrun/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+rayrun_sdk-0.8.0.dist-info/METADATA,sha256=GcxPdHMEfAJsL67Wi1RniMaqF8fOJs0r2V3pcC5vRBo,2078
+rayrun_sdk-0.8.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+rayrun_sdk-0.8.0.dist-info/RECORD,,

rayrun_sdk-0.8.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any