assistant-runtime-sdk 1.7.0__tar.gz → 1.9.0__tar.gz

{assistant_runtime_sdk-1.7.0 → assistant_runtime_sdk-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assistant_runtime_sdk
-Version: 1.7.0
+Version: 1.9.0
 Summary: Python SDK for FAC Cloud - the Assistant Runtime AI assistant backend
 Keywords: frappe,ai,assistant,llm,mcp,anthropic,openai,streaming
 Author: Paul Clinton

{assistant_runtime_sdk-1.7.0 → assistant_runtime_sdk-1.9.0}/assistant_runtime_sdk/__init__.py

@@ -53,7 +53,7 @@ Standalone Functions:
 
 """
 
-__version__ = "1.7.0"
+__version__ = "1.9.0"
 __author__ = "Paul Clinton"
 __license__ = "AGPL-3.0"
 

{assistant_runtime_sdk-1.7.0 → assistant_runtime_sdk-1.9.0}/assistant_runtime_sdk/async_client.py

@@ -826,6 +826,14 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
             user_id, preference_id, status)
         return await self._request_post_json(endpoint, payload)
 
+    async def set_routing_preference_mode(
+        self, user_id: str, preference_id: str, rule_mode: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.set_routing_preference_mode."""
+        endpoint, payload = self._prepare_set_routing_preference_mode(
+            user_id, preference_id, rule_mode)
+        return await self._request_post_json(endpoint, payload)
+
     async def delete_routing_preference(
         self, user_id: str, preference_id: str,
     ) -> Optional[Dict[str, Any]]:
@@ -1333,7 +1341,7 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         user_id: str,
         server_name: str,
         endpoint_url: str,
-        transport_type: str = "SSE",
+        transport_type: str = "HTTP",
         auth_type: str = "OAuth",
         oauth_client_id: Optional[str] = None,
         oauth_client_secret: Optional[str] = None,
@@ -1344,12 +1352,14 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         api_key_header: str = "Authorization",
         allowed_tools: Optional[list] = None,
         blocked_tools: Optional[list] = None,
+        managed: bool = False,
     ) -> Dict[str, Any]:
         """Async version of AssistantRuntimeClient.add_user_mcp_server."""
         endpoint, params = self._prepare_add_user_mcp_server(
             user_id, server_name, endpoint_url, transport_type, auth_type,
             oauth_client_id, oauth_client_secret, access_token, refresh_token,
             token_expires_in, api_key, api_key_header, allowed_tools, blocked_tools,
+            managed,
         )
         return await self._request_post_form(endpoint, params)
 
@@ -1359,7 +1369,7 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         try:
             return await self._request_get(endpoint, params)
         except Exception as e:
-            return {"user_id": user_id, "mcp_servers": [], "error": str(e)}
+            return {"user_id": user_id, "mcp_servers": [], "error": str(e), "_ar_unreachable": True}
 
     async def update_mcp_server_tokens(
         self,
@@ -1378,6 +1388,64 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, params = self._prepare_remove_user_mcp_server(user_id, server_name)
         return await self._request_delete(endpoint, params)
 
+    async def enable_mcp_server(self, user_id: str, server_name: str, enabled: bool = True) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.enable_mcp_server."""
+        endpoint, params = self._prepare_enable_mcp_server(user_id, server_name, enabled)
+        return await self._request_post_form(endpoint, params)
+
+    async def test_mcp_server(self, user_id: str, server_name: str) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.test_mcp_server."""
+        endpoint, params = self._prepare_test_mcp_server(user_id, server_name)
+        return await self._request_post_form(endpoint, params)
+
+    async def set_mcp_server_tools(
+        self,
+        user_id: str,
+        server_name: str,
+        allowed_tools: Optional[list] = None,
+        blocked_tools: Optional[list] = None,
+    ) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.set_mcp_server_tools."""
+        endpoint, params = self._prepare_set_mcp_server_tools(
+            user_id, server_name, allowed_tools, blocked_tools
+        )
+        return await self._request_post_form(endpoint, params)
+
+    async def begin_mcp_connect(
+        self,
+        endpoint_url: str,
+        user_id: str,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.begin_mcp_connect."""
+        endpoint, params = self._prepare_begin_mcp_connect(
+            user_id, endpoint_url, client_id, client_secret
+        )
+        return await self._request_post_form(endpoint, params)
+
+    async def get_mcp_connect_session(self, handle: str, user_id: str) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.get_mcp_connect_session."""
+        endpoint, params = self._prepare_get_mcp_connect_session(user_id, handle)
+        return await self._request_get(endpoint, params)
+
+    async def commit_mcp_connect(
+        self, handle: str, server_name: str, user_id: str
+    ) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.commit_mcp_connect."""
+        endpoint, params = self._prepare_commit_mcp_connect(user_id, handle, server_name)
+        return await self._request_post_form(endpoint, params)
+
+    async def abandon_mcp_connect(self, handle: str, user_id: str) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.abandon_mcp_connect."""
+        endpoint, params = self._prepare_abandon_mcp_connect(user_id, handle)
+        return await self._request_post_form(endpoint, params)
+
+    async def begin_mcp_reauth(self, server_name: str, user_id: str) -> Dict[str, Any]:
+        """Async version of AssistantRuntimeClient.begin_mcp_reauth."""
+        endpoint, params = self._prepare_begin_mcp_reauth(user_id, server_name)
+        return await self._request_post_form(endpoint, params)
+
     async def list_users(
         self,
         status: Optional[str] = None,

{assistant_runtime_sdk-1.7.0 → assistant_runtime_sdk-1.9.0}/assistant_runtime_sdk/base.py

@@ -883,6 +883,16 @@ class BaseAssistantRuntimeClient:
             "status": status,
         }
 
+    def _prepare_set_routing_preference_mode(
+        self, user_id: str, preference_id: str, rule_mode: str,
+    ) -> tuple:
+        return "routing_preferences.set_routing_preference_mode", {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "preference_id": preference_id,
+            "rule_mode": rule_mode,
+        }
+
     def _prepare_delete_routing_preference(
         self, user_id: str, preference_id: str,
     ) -> tuple:
@@ -1427,7 +1437,7 @@ class BaseAssistantRuntimeClient:
 
     def _prepare_add_user_mcp_server(
         self, user_id: str, server_name: str, endpoint_url: str,
-        transport_type: str = "SSE", auth_type: str = "OAuth",
+        transport_type: str = "HTTP", auth_type: str = "OAuth",
         oauth_client_id: Optional[str] = None,
         oauth_client_secret: Optional[str] = None,
         access_token: Optional[str] = None,
@@ -1437,6 +1447,7 @@ class BaseAssistantRuntimeClient:
         api_key_header: str = "Authorization",
         allowed_tools: Optional[list] = None,
         blocked_tools: Optional[list] = None,
+        managed: bool = False,
     ) -> tuple:
         params: Dict[str, Any] = {
             "tenant_id": self.tenant_id,
@@ -1464,6 +1475,7 @@ class BaseAssistantRuntimeClient:
             params["allowed_tools"] = json.dumps(allowed_tools)
         if blocked_tools:
             params["blocked_tools"] = json.dumps(blocked_tools)
+        params["managed"] = "1" if managed else "0"
         return "users.add_user_mcp_server", params
 
     def _prepare_get_user_mcp_servers(self, user_id: str) -> tuple:
@@ -1494,6 +1506,94 @@ class BaseAssistantRuntimeClient:
             "server_name": server_name,
         }
 
+    def _prepare_enable_mcp_server(
+        self, user_id: str, server_name: str, enabled: bool = True
+    ) -> tuple:
+        return "users.enable_mcp_server", {
+            "tenant_id": self.tenant_id,
+            "user_id": str(user_id),
+            "server_name": str(server_name),
+            "enabled": "1" if enabled else "0",
+        }
+
+    def _prepare_test_mcp_server(self, user_id: str, server_name: str) -> tuple:
+        return "users.test_mcp_server", {
+            "tenant_id": self.tenant_id,
+            "user_id": str(user_id),
+            "server_name": str(server_name),
+        }
+
+    def _prepare_set_mcp_server_tools(
+        self, user_id: str, server_name: str,
+        allowed_tools: Optional[list] = None,
+        blocked_tools: Optional[list] = None,
+    ) -> tuple:
+        params: Dict[str, Any] = {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "server_name": server_name,
+        }
+        if allowed_tools is not None:
+            params["allowed_tools"] = json.dumps(allowed_tools)
+        if blocked_tools is not None:
+            params["blocked_tools"] = json.dumps(blocked_tools)
+        return "users.set_mcp_server_tools", params
+
+    # -------------------------------------------------------------------------
+    # MCP Connect wizard (assistant_runtime.api.mcp_oauth)
+    # -------------------------------------------------------------------------
+
+    def _prepare_begin_mcp_connect(
+        self, user_id: str, endpoint_url: str,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+    ) -> tuple:
+        params: Dict[str, Any] = {
+            "tenant_id": self.tenant_id,
+            "user_id": str(user_id),
+            "endpoint_url": str(endpoint_url),
+        }
+        # Omitted, not blank: a blank client_id on the wire makes AR record an
+        # empty manual registration instead of taking the DCR path.
+        if client_id:
+            params["client_id"] = str(client_id)
+        if client_secret:
+            params["client_secret"] = str(client_secret)
+        return "mcp_oauth.begin_mcp_connect", params
+
+    def _prepare_get_mcp_connect_session(self, user_id: str, handle: str) -> tuple:
+        return "mcp_oauth.get_mcp_connect_session", {
+            "tenant_id": self.tenant_id,
+            "user_id": str(user_id),
+            "handle": str(handle),
+        }
+
+    def _prepare_commit_mcp_connect(
+        self, user_id: str, handle: str, server_name: str
+    ) -> tuple:
+        return "mcp_oauth.commit_mcp_connect", {
+            "tenant_id": self.tenant_id,
+            "user_id": str(user_id),
+            "handle": str(handle),
+            "server_name": str(server_name),
+        }
+
+    def _prepare_abandon_mcp_connect(self, user_id: str, handle: str) -> tuple:
+        return "mcp_oauth.abandon_mcp_connect", {
+            "tenant_id": self.tenant_id,
+            "user_id": str(user_id),
+            "handle": str(handle),
+        }
+
+    def _prepare_begin_mcp_reauth(self, user_id: str, server_name: str) -> tuple:
+        # No endpoint_url: AR reads it from the row named here, and commit
+        # updates that row in place via the session's reauth_target.
+        return "mcp_oauth.begin_mcp_reauth", {
+            "tenant_id": self.tenant_id,
+            "user_id": str(user_id),
+            "server_name": str(server_name),
+        }
+
     def _prepare_list_users(
         self, status: Optional[str] = None, limit: int = 50,
         offset: int = 0, include_mcp_count: bool = True,

{assistant_runtime_sdk-1.7.0 → assistant_runtime_sdk-1.9.0}/assistant_runtime_sdk/client.py

@@ -1189,6 +1189,28 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
             user_id, preference_id, status)
         return self._request_post_json(endpoint, payload)
 
+    def set_routing_preference_mode(
+        self, user_id: str, preference_id: str, rule_mode: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Finish a rule's trial, or send it back to one.
+
+        Every rule carries its own mode, so this changes nothing about any
+        other rule. Platform defaults are not reachable here — they are
+        managed in AR Admin.
+
+        Args:
+            user_id: User identifier
+            preference_id: the rule
+            rule_mode: "shadow" (matched and recorded, never applied) or
+                "on" (applied)
+
+        Returns:
+            {"preference_id": ..., "rule_mode": ...}
+        """
+        endpoint, payload = self._prepare_set_routing_preference_mode(
+            user_id, preference_id, rule_mode)
+        return self._request_post_json(endpoint, payload)
+
     def delete_routing_preference(
         self, user_id: str, preference_id: str,
     ) -> Optional[Dict[str, Any]]:
@@ -1999,7 +2021,7 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         user_id: str,
         server_name: str,
         endpoint_url: str,
-        transport_type: str = "SSE",
+        transport_type: str = "HTTP",
         auth_type: str = "OAuth",
         oauth_client_id: Optional[str] = None,
         oauth_client_secret: Optional[str] = None,
@@ -2010,12 +2032,19 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         api_key_header: str = "Authorization",
         allowed_tools: Optional[list] = None,
         blocked_tools: Optional[list] = None,
+        managed: bool = False,
     ) -> Dict[str, Any]:
-        """Add or update an MCP server for a user."""
+        """Add or update an MCP server for a user.
+
+        ``managed`` is sent as a hint only — AR derives the authoritative
+        value server-side from whether server_name/endpoint_url match FAC's
+        real registration shape, regardless of what is passed here.
+        """
         endpoint, params = self._prepare_add_user_mcp_server(
             user_id, server_name, endpoint_url, transport_type, auth_type,
             oauth_client_id, oauth_client_secret, access_token, refresh_token,
             token_expires_in, api_key, api_key_header, allowed_tools, blocked_tools,
+            managed,
         )
         return self._request_post_form(endpoint, params)
 
@@ -2025,7 +2054,7 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         try:
             return self._request_get(endpoint, params)
         except Exception as e:
-            return {"user_id": user_id, "mcp_servers": [], "error": str(e)}
+            return {"user_id": user_id, "mcp_servers": [], "error": str(e), "_ar_unreachable": True}
 
     def update_mcp_server_tokens(
         self,
@@ -2044,6 +2073,113 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, params = self._prepare_remove_user_mcp_server(user_id, server_name)
         return self._request_delete(endpoint, params)
 
+    def enable_mcp_server(self, user_id: str, server_name: str, enabled: bool = True) -> Dict[str, Any]:
+        """Enable or disable an MCP server without deleting it."""
+        endpoint, params = self._prepare_enable_mcp_server(user_id, server_name, enabled)
+        return self._request_post_form(endpoint, params)
+
+    def test_mcp_server(self, user_id: str, server_name: str) -> Dict[str, Any]:
+        """Open a real authenticated MCP session and report what it exposes.
+
+        Unlike a reachability probe, this speaks MCP with the user's stored
+        credentials and lists tools. Returns a result dict rather than
+        raising: {"success": bool, "tool_count": int, "tools": [str], "error": str | None}.
+        """
+        endpoint, params = self._prepare_test_mcp_server(user_id, server_name)
+        return self._request_post_form(endpoint, params)
+
+    def set_mcp_server_tools(
+        self,
+        user_id: str,
+        server_name: str,
+        allowed_tools: Optional[list] = None,
+        blocked_tools: Optional[list] = None,
+    ) -> Dict[str, Any]:
+        """Replace the tool filters on one server, without touching enabled,
+        status, or credentials.
+
+        Unlike ``add_user_mcp_server``, this is a targeted write, not an
+        upsert — safe to call from a checkbox UI without risking a
+        disabled server being silently re-enabled or its stored API key
+        being dropped.
+        """
+        endpoint, params = self._prepare_set_mcp_server_tools(
+            user_id, server_name, allowed_tools, blocked_tools
+        )
+        return self._request_post_form(endpoint, params)
+
+    def begin_mcp_connect(
+        self,
+        endpoint_url: str,
+        user_id: str,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Start a server-side MCP connect attempt and run the preflight.
+
+        Returns AR's connect-session payload:
+        ``{"handle", "session", "preflight", "authorize_url", "redirect_uri"}``.
+        ``preflight`` is ``run_preflight``'s dict — ``steps`` (each
+        ``pass|fail|skipped``), ``server_info``, ``auth``. ``redirect_uri`` is
+        the URI a user must register by hand when the authorization server has
+        no Dynamic Client Registration.
+
+        ``client_id``/``client_secret`` are the no-DCR escape hatch: supply them
+        to re-begin with credentials the user registered themselves.
+        """
+        endpoint, params = self._prepare_begin_mcp_connect(
+            user_id, endpoint_url, client_id, client_secret
+        )
+        return self._request_post_form(endpoint, params)
+
+    def get_mcp_connect_session(self, handle: str, user_id: str) -> Dict[str, Any]:
+        """Read an in-flight connect session by its short-lived handle.
+
+        Returns ``{"status", "endpoint_url", "preflight", "capabilities",
+        "authorize_url", "error_message", "server_name",
+        "reauth_server_name"}``. ``status`` is one of ``Preflight``,
+        ``Awaiting Auth``, ``Authorized``, ``Committed``, ``Failed`` — Title
+        Case with spaces, matching ``AR User MCP Server``'s own status Select.
+        ``authorize_url`` is a real URL whenever one has been built, so a user
+        who reloaded mid-flow can still click Connect. ``capabilities`` is
+        populated only once the session reaches ``Authorized``; ``server_name``
+        only once it reaches ``Committed``. ``reauth_server_name`` is the name
+        of the row this session re-authorizes, or ``None`` on the ordinary add
+        path — it is what lets a caller tell the two apart without carrying any
+        state of its own across the authorization round trip.
+        """
+        endpoint, params = self._prepare_get_mcp_connect_session(user_id, handle)
+        return self._request_get(endpoint, params)
+
+    def commit_mcp_connect(
+        self, handle: str, server_name: str, user_id: str
+    ) -> Dict[str, Any]:
+        """Turn an authorized connect session into a real AR User MCP Server."""
+        endpoint, params = self._prepare_commit_mcp_connect(user_id, handle, server_name)
+        return self._request_post_form(endpoint, params)
+
+    def abandon_mcp_connect(self, handle: str, user_id: str) -> Dict[str, Any]:
+        """Drop an in-flight connect session and the credentials escrowed in it."""
+        endpoint, params = self._prepare_abandon_mcp_connect(user_id, handle)
+        return self._request_post_form(endpoint, params)
+
+    def begin_mcp_reauth(self, server_name: str, user_id: str) -> Dict[str, Any]:
+        """Re-authorize a connection that already exists.
+
+        Returns the same payload shape as :meth:`begin_mcp_connect`. AR opens
+        the session with ``reauth_target`` pointing at the named
+        ``AR User MCP Server`` row, so ``commit_mcp_connect`` updates that row's
+        credentials in place and restores it to ``Active`` instead of inserting
+        a second row — which is what made the duplicate-name guard fire on every
+        reconnect before this endpoint existed.
+
+        This is the only correct entry point for reconnecting. Calling
+        ``begin_mcp_connect`` and then committing under the existing name takes
+        the add path and fails.
+        """
+        endpoint, params = self._prepare_begin_mcp_reauth(user_id, server_name)
+        return self._request_post_form(endpoint, params)
+
     def list_users(
         self,
         status: Optional[str] = None,

{assistant_runtime_sdk-1.7.0 → assistant_runtime_sdk-1.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "assistant_runtime_sdk"
-version = "1.7.0"
+version = "1.9.0"
 description = "Python SDK for FAC Cloud - the Assistant Runtime AI assistant backend"
 readme = "README.md"
 license = {text = "AGPL-3.0"}