agentstack-sdk 0.5.2rc4__py3-none-any.whl → 0.6.0rc2__py3-none-any.whl

agentstack_sdk/a2a/extensions/interactions/approval.py

@@ -38,8 +38,8 @@ class ToolCallServer(BaseModel):
 class ToolCallApprovalRequest(BaseModel):
     action: Literal["tool-call"] = "tool-call"
 
-    title: str | None = Field(None, description="A human-readable title for the tool call being approved.")
-    description: str | None = Field(None, description="A human-readable description of the tool call being approved.")
+    title: str | None = Field(None, description="A human-readable title of the tool.")
+    description: str | None = Field(None, description="A human-readable description of the tool.")
     name: str = Field(description="The programmatic name of the tool.")
     input: dict[str, Any] | None = Field(description="The input for the tool.")
     server: ToolCallServer | None = Field(None, description="The server executing the tool.")

agentstack_sdk/platform/__init__.py

@@ -3,6 +3,7 @@
 
 from .client import *
 from .configuration import *
+from .connector import *
 from .file import *
 from .model_provider import *
 from .provider import *

agentstack_sdk/platform/connector.py

@@ -0,0 +1,337 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import asyncio
+import webbrowser
+from collections.abc import AsyncIterator
+from enum import StrEnum
+from typing import Annotated, Literal
+from uuid import UUID
+
+import pydantic
+from pydantic import AnyUrl, BeforeValidator, Field
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+from agentstack_sdk.platform.common import PaginatedResult
+from agentstack_sdk.platform.types import Metadata
+
+
+def uuid_to_str(v: UUID | str) -> str:
+    """Convert UUID or str to str."""
+    if isinstance(v, UUID):
+        return str(v)
+    return v
+
+
+UuidStr = Annotated[UUID | str, BeforeValidator(uuid_to_str)]
+
+
+class AuthorizationCodeRequest(pydantic.BaseModel):
+    """Authorization request for code-based OAuth flow."""
+
+    type: Literal["code"] = "code"
+    authorization_endpoint: AnyUrl
+
+
+class ConnectorPreset(pydantic.BaseModel):
+    """Represents a preset connector configuration."""
+
+    url: AnyUrl
+    metadata: Metadata | None = None
+
+
+class ConnectorState(StrEnum):
+    """Enumeration of possible connector states."""
+
+    created = "created"
+    auth_required = "auth_required"
+    connected = "connected"
+    disconnected = "disconnected"
+
+
+class MCPProxyResponse(pydantic.BaseModel):
+    """Response from an MCP proxy request with headers and streaming content."""
+
+    headers: Annotated[dict[str, str], Field(description="HTTP headers from the proxy response")]
+    status_code: Annotated[int, Field(description="HTTP status code from the proxy response")]
+    chunk: Annotated[bytes, Field(description="Bytes chunk from streaming response content")]
+
+
+class Connector(pydantic.BaseModel):
+    """Represents a configured connector instance."""
+
+    id: UUID
+    url: AnyUrl
+    state: ConnectorState
+    auth_request: AuthorizationCodeRequest | None = None
+    disconnect_reason: str | None = None
+    metadata: Metadata | None = None
+    created_at: pydantic.AwareDatetime | None = None
+    updated_at: pydantic.AwareDatetime | None = None
+    created_by: UUID | None = None
+
+    @staticmethod
+    async def create(
+        url: AnyUrl | str,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        metadata: Metadata | None = None,
+        match_preset: bool = True,
+        client: PlatformClient | None = None,
+    ) -> Connector:
+        """
+        Create a new connector.
+
+        Args:
+            url: The URL of the connector/MCP server
+            client_id: OAuth client ID (optional)
+            client_secret: OAuth client secret (optional)
+            metadata: Additional metadata for the connector (optional)
+            match_preset: Whether to match against preset connectors
+            client: Optional PlatformClient instance
+
+        Returns:
+            The created Connector instance
+        """
+        async with client or get_platform_client() as client:
+            response = await client.post(
+                url="/api/v1/connectors",
+                json={
+                    "url": str(url),
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "metadata": metadata,
+                    "match_preset": match_preset,
+                },
+            )
+            response.raise_for_status()
+            return pydantic.TypeAdapter(Connector).validate_python(response.json())
+
+    @staticmethod
+    async def list(
+        *,
+        client: PlatformClient | None = None,
+    ) -> PaginatedResult[Connector]:
+        """
+        List all connectors for the current user.
+
+        Returns:
+            A paginated list of Connector instances
+        """
+        async with client or get_platform_client() as client:
+            response = await client.get(url="/api/v1/connectors")
+            response.raise_for_status()
+            return pydantic.TypeAdapter(PaginatedResult[Connector]).validate_python(response.json())
+
+    async def get(
+        self: Connector | UuidStr,
+        *,
+        client: PlatformClient | None = None,
+    ) -> Connector:
+        """
+        Read a specific connector by ID.
+        """
+        connector_id = str(self.id) if isinstance(self, Connector) else self
+        async with client or get_platform_client() as client:
+            response = await client.get(url=f"/api/v1/connectors/{connector_id}")
+            response.raise_for_status()
+            return pydantic.TypeAdapter(Connector).validate_python(response.json())
+
+    async def delete(
+        self: Connector | UuidStr,
+        *,
+        client: PlatformClient | None = None,
+    ) -> None:
+        """
+        Delete a connector.
+
+        Args:
+            client: Optional PlatformClient instance
+        """
+        connector_id = str(self.id) if isinstance(self, Connector) else self
+        async with client or get_platform_client() as client:
+            response = await client.delete(url=f"/api/v1/connectors/{connector_id}")
+            response.raise_for_status()
+
+    async def refresh(
+        self: Connector | UuidStr,
+        *,
+        client: PlatformClient | None = None,
+    ) -> Connector:
+        """
+        This is just a syntactic sugar for calling Connector.get().
+        """
+        async with client or get_platform_client() as client:
+            return await Connector.get(self, client=client)
+
+    async def wait_for_state(
+        self: Connector | UuidStr,
+        *,
+        state: ConnectorState = ConnectorState.connected,
+        poll_interval: int = 1,
+        client: PlatformClient | None = None,
+    ) -> Connector:
+        """
+        Wait for the connector to reach connected state.
+
+        This is useful after calling connect() and opening the browser for OAuth.
+        It will poll the server until the connector reaches 'connected' state or
+        timeout is exceeded.
+
+        Args:
+            poll_interval: Seconds between polls (default: 2)
+            client: Optional PlatformClient instance
+
+        Returns:
+            Updated Connector instance when connected
+
+        Raises:
+            TimeoutError: If connector doesn't reach connected state within timeout (300 seconds)
+        """
+        async with client or get_platform_client() as client:
+            connector = self if isinstance(self, Connector) else await Connector.get(self, client=client)
+
+            async with asyncio.timeout(300):
+                while connector.state != state:
+                    await asyncio.sleep(poll_interval)
+                    connector = await connector.refresh(client=client)
+            return connector
+
+    async def wait_for_deletion(
+        self: Connector | UuidStr,
+        *,
+        poll_interval: int = 1,
+        client: PlatformClient | None = None,
+    ) -> None:
+        connector_id = str(self.id) if isinstance(self, Connector) else self
+        async with client or get_platform_client() as client:
+            async with asyncio.timeout(30):
+                while True:
+                    connector_list = await Connector.list(client=client)
+                    if not any(str(conn.id) == connector_id for conn in connector_list.items):
+                        return
+                    await asyncio.sleep(poll_interval)
+
+    async def connect(
+        self: Connector | UuidStr,
+        *,
+        redirect_url: AnyUrl | str | None = None,
+        access_token: str | None = None,
+        client: PlatformClient | None = None,
+    ) -> Connector:
+        """
+        Connect a connector (establish authorization).
+
+        If the connector requires OAuth authorization, this will automatically
+        open the browser with the authorization endpoint.
+
+        Args:
+            redirect_url: OAuth redirect URL (optional)
+            access_token: OAuth access token (optional)
+            client: Optional PlatformClient instance
+
+        Returns:
+            The updated Connector instance
+        """
+        connector_id = str(self.id) if isinstance(self, Connector) else self
+        async with client or get_platform_client() as client:
+            response = await client.post(
+                url=f"/api/v1/connectors/{connector_id}/connect",
+                json={
+                    "redirect_url": str(redirect_url) if redirect_url else None,
+                    "access_token": access_token,
+                },
+            )
+            response.raise_for_status()
+            connector = pydantic.TypeAdapter(Connector).validate_python(response.json())
+        # If auth is required, open the browser automatically and returns the connector in
+        # `auth_required` state
+        if connector.state == ConnectorState.auth_required and connector.auth_request:
+            webbrowser.open(connector.auth_request.authorization_endpoint.unicode_string(), new=2)
+
+        return connector
+
+    async def disconnect(
+        self: Connector | UuidStr,
+        *,
+        client: PlatformClient | None = None,
+    ) -> Connector:
+        """
+        Disconnect a connector.
+
+        Args:
+            client: Optional PlatformClient instance
+
+        Returns:
+            The updated Connector instance
+        """
+        connector_id = str(self.id) if isinstance(self, Connector) else self
+        async with client or get_platform_client() as client:
+            response = await client.post(url=f"/api/v1/connectors/{connector_id}/disconnect")
+            response.raise_for_status()
+            return pydantic.TypeAdapter(Connector).validate_python(response.json())
+
+    async def mcp_proxy(
+        self: Connector | UuidStr,
+        *,
+        method: str,
+        headers: dict | None = None,
+        content: bytes | None = None,
+        client: PlatformClient | None = None,
+    ) -> AsyncIterator[MCPProxyResponse]:
+        """
+        Proxy a streaming request through to the connector's MCP endpoint.
+
+        This allows direct communication with the Model Context Protocol server
+        exposed by the connector. The response is streamed to avoid loading
+        large responses into memory.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            headers: Optional HTTP headers to include
+            content: Optional request body content
+            client: Optional PlatformClient instance
+
+        Yields:
+            Response content chunks as bytes
+        """
+        connector_id = str(self.id) if isinstance(self, Connector) else self
+        async with client or get_platform_client() as client:
+            url = f"/api/v1/connectors/{connector_id}/mcp"
+
+            # Merge headers - add Content-Type for JSON content if not already set
+            request_headers = dict(headers or {})
+            if content and "content-type" not in {k.lower() for k in request_headers}:
+                request_headers["Content-Type"] = "application/json"
+
+            # Use streaming to support large/long-lived connections
+            async with client.stream(
+                method=method.upper(),
+                url=url,
+                headers=request_headers,
+                content=content,
+            ) as response:
+                response.raise_for_status()
+                async for chunk in response.aiter_bytes():
+                    yield pydantic.TypeAdapter(MCPProxyResponse).validate_python(
+                        {"headers": dict(response.headers), "status_code": response.status_code, "chunk": chunk}
+                    )
+
+    @staticmethod
+    async def presets(
+        *,
+        client: PlatformClient | None = None,
+    ) -> PaginatedResult[ConnectorPreset]:
+        """
+        List all available connector presets.
+
+        Returns:
+            A paginated list of ConnectorPreset instances
+        """
+        async with client or get_platform_client() as client:
+            response = await client.get(url="/api/v1/connectors/presets")
+            response.raise_for_status()
+            return pydantic.TypeAdapter(PaginatedResult[ConnectorPreset]).validate_python(response.json())

agentstack_sdk/platform/user.py

@@ -27,7 +27,6 @@ class User(pydantic.BaseModel):
     role: UserRole
     email: str
     created_at: pydantic.AwareDatetime
-    role_updated_at: pydantic.AwareDatetime | None = None
 
     @staticmethod
     async def get(*, client: PlatformClient | None = None) -> User:

{agentstack_sdk-0.5.2rc4.dist-info → agentstack_sdk-0.6.0rc2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentstack-sdk
-Version: 0.5.2rc4
+Version: 0.6.0rc2
 Summary: Agent Stack SDK
 Author: IBM Corp.
 Requires-Dist: a2a-sdk==0.3.21

{agentstack_sdk-0.5.2rc4.dist-info → agentstack_sdk-0.6.0rc2.dist-info}/RECORD

@@ -14,7 +14,7 @@ agentstack_sdk/a2a/extensions/common/__init__.py,sha256=3lg8P9ASBFHDipP1oZ3IcPqC
 agentstack_sdk/a2a/extensions/common/form.py,sha256=tbDD3V-ZW90TjXXkyf3SCQd3zJ3tvbJfJA5cbJuPdH0,3792
 agentstack_sdk/a2a/extensions/exceptions.py,sha256=k4_OFuglnm3XaAr9tl47dNXLLkIhjOQVLohIQ7ieC0M,369
 agentstack_sdk/a2a/extensions/interactions/__init__.py,sha256=GruhHZaI-iMrmzZhkgtb4KOzlVKgnKMYEylfNjIn6_4,118
-agentstack_sdk/a2a/extensions/interactions/approval.py,sha256=DMdiLFEkdgaYyZP-E5pq_tARAn2VNQIIyn_jiZL2RcI,4795
+agentstack_sdk/a2a/extensions/interactions/approval.py,sha256=AD4UhHh7fF-9LcbFL1QkzVYA7mhEPMktx-eI_z1yGVQ,4754
 agentstack_sdk/a2a/extensions/services/__init__.py,sha256=9njkm58sMs_sMQwKGTMkPU-I7c7T99BWy30fcw4nCoI,201
 agentstack_sdk/a2a/extensions/services/embedding.py,sha256=GuvbKaOlZSBn04a7SsIlJrQkehEKnZDxQmJCxpVbf_8,3892
 agentstack_sdk/a2a/extensions/services/form.py,sha256=BmZ-Cqwp4o-j1zgCneuZ_9-1vCOm1OkQMJZLc_Rp1qc,1707
@@ -33,17 +33,18 @@ agentstack_sdk/a2a/extensions/ui/form_request.py,sha256=YeRiovV3EgqeBD8fHtu_b5qr
 agentstack_sdk/a2a/extensions/ui/settings.py,sha256=uZu_8u29gAu1H85twFb_LCRBO0jeaEiLgfamaFNUPGM,1814
 agentstack_sdk/a2a/extensions/ui/trajectory.py,sha256=G66rIpr2VTe1UvbK82EgLXwFtUC3QfbyN_uLQGUU8jA,2334
 agentstack_sdk/a2a/types.py,sha256=z1-OxRLIJgYDHwaBJ66MZNIqSTpE1zQ04BPGBGw9IC0,3582
-agentstack_sdk/platform/__init__.py,sha256=jFlxr6P-6DJZVt1W8Xt1suISJpodD_EWX92GmcFLXwM,326
+agentstack_sdk/platform/__init__.py,sha256=2yu0t7mtMPv14MWk1PFiU5t6xaZf9n4VhY6moKjdNFw,351
 agentstack_sdk/platform/client.py,sha256=KDN3R1wyoo-ZUYl6ArjRJxre0yAqB0Y6NyKrQpdI268,4234
 agentstack_sdk/platform/common.py,sha256=p6w4l49NaFp7LsjEBDAwghX6FliNChOeO7IHP_-TnXA,750
 agentstack_sdk/platform/configuration.py,sha256=YfOasb6LxE9LN6sMZPEU07Q61F7uIhiU3DIQFRaqinU,1690
+agentstack_sdk/platform/connector.py,sha256=I3IgZCqbrZ0YXHFkFD-JSYihIahZHGBtQcXfN4cvEFc,12060
 agentstack_sdk/platform/context.py,sha256=vYAQOgZUEelvhP4Sldzt4Y1CP4WVtEE42DSuAMGnn-0,12099
 agentstack_sdk/platform/file.py,sha256=lOqMwMKHKGWFy5P1huQ6DLRTiHU0KexX-s2qF3FIRxw,13062
 agentstack_sdk/platform/model_provider.py,sha256=hv5UbFUFQ23IlalH5W-nCTvnUCrxBtZF4UrkeNWnwFE,4588
 agentstack_sdk/platform/provider.py,sha256=1juAfYc39sVwZ8ZbYz1ohVnzzRacJx6Junvo-7GgVmY,9071
 agentstack_sdk/platform/provider_build.py,sha256=Vn2XDdMGgQWvChWJmg9nxYFVecp42A1jXzURkFgSEQQ,7317
 agentstack_sdk/platform/types.py,sha256=3OHERUoli6t9rlCiaZ2YfN26GXqMQzDFQx_UluCZVYA,1502
-agentstack_sdk/platform/user.py,sha256=ZxTPJYPGxcRtRQJpxPPf2ylz3Erngu2vSMuia1oJ04Q,2148
+agentstack_sdk/platform/user.py,sha256=pqkac4JZqagOYVvdm8mk48xHvVn6SPq2tbe5tXx_W4M,2090
 agentstack_sdk/platform/user_feedback.py,sha256=IfMzZsaFKpWCPz5MjppDsFLLMM-iVQUBGugz0_FmrqY,1305
 agentstack_sdk/platform/variables.py,sha256=VW7eHO_V6B5I-vvqNgUangkcuUXDcjFIrxUSSfX5cHw,1637
 agentstack_sdk/platform/vector_store.py,sha256=h98RKGuN1SvmfL_bxf3WCLvY1IeQ00Wf7NTP6yr05qg,8695
@@ -71,6 +72,6 @@ agentstack_sdk/util/httpx.py,sha256=g6WKgkGCLc40wZA2CPYO_R2P-nav6QP1XmVlgkh9wYY,
 agentstack_sdk/util/logging.py,sha256=hGLkjw-P3GefiUQmDmcz7BZQxfT2Y44XlLyAMNxZXMo,2136
 agentstack_sdk/util/resource_context.py,sha256=OmjEXvrLQA6nBkVSBt0n24hNNxJkucd-N32haxJ4Mno,1093
 agentstack_sdk/util/utils.py,sha256=18qFqMRkX4g4eIpvIvLb4FZAs8Q8ojJrpm19oJleb-k,1593
-agentstack_sdk-0.5.2rc4.dist-info/WHEEL,sha256=M6du7VZflc4UPsGphmOXHANdgk8zessdJG0DBUuoA-U,78
-agentstack_sdk-0.5.2rc4.dist-info/METADATA,sha256=qJ5Qa_bZ2UC4A-EAY5NqtWk5-B-iuFTgOZv7X4dmRlA,4433
-agentstack_sdk-0.5.2rc4.dist-info/RECORD,,
+agentstack_sdk-0.6.0rc2.dist-info/WHEEL,sha256=M6du7VZflc4UPsGphmOXHANdgk8zessdJG0DBUuoA-U,78
+agentstack_sdk-0.6.0rc2.dist-info/METADATA,sha256=0-Tqa6hadZ7xiYobmfINCfIQK-xS22d-X4381G1Y9C4,4433
+agentstack_sdk-0.6.0rc2.dist-info/RECORD,,