agentstack-sdk 0.4.1rc1__tar.gz

agentstack_sdk-0.4.1rc1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.3
+Name: agentstack-sdk
+Version: 0.4.1rc1
+Summary: Agent Stack SDK
+Author: IBM Corp.
+Requires-Dist: a2a-sdk==0.3.9
+Requires-Dist: objprint>=0.3.0
+Requires-Dist: uvicorn>=0.35.0
+Requires-Dist: asyncclick>=8.1.8
+Requires-Dist: sse-starlette>=2.2.1
+Requires-Dist: starlette>=0.47.2
+Requires-Dist: anyio>=4.9.0
+Requires-Dist: opentelemetry-api>=1.35.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.35.0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.56b0
+Requires-Dist: opentelemetry-sdk>=1.35.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: janus>=2.0.0
+Requires-Dist: httpx
+Requires-Dist: mcp>=1.12.3
+Requires-Dist: fastapi>=0.116.1
+Requires-Python: >=3.11, <3.14
+Description-Content-Type: text/markdown
+
+# Agent Stack SDK
+
+## Examples
+
+The examples connect to the Agent Stack for LLM inteference.
+
+Run using:
+
+```bash
+uv run examples/agent.py
+```
+
+Connect to the agent using the CLI:
+
+```bash
+uv run examples/cli.py
+```
+
+## Plan
+
+- `agentstack_sdk`
+    - `a2a`:
+        - `extensions`: Shared definitions for A2A extensions
+            - `services`: Dependency injection extensions for external services
+                - `llm`
+                - `embedding`
+                - `docling`
+                - `file_store`
+                - `vector_store`
+            - `ui`: User interface extensions for Agent Stack UI
+                - `trajectory`
+                - `citations`
+            - `history`: store and allow requesting the full history of the context
+    - `server`
+        - `context_storage`: store data associated with context_id
+        - `wrapper`: conveniently build A2A agents -- opinionated on how tasks work, `yield`-semantics, autowired
+          services
+        - `services`: clients for external services
+            - `llm`: OpenAI-compatible chat LLM
+            - `embedding`: OpenAI-compatible embedding
+            - `text_extraction`: Docling-compatible text extraction
+            - `file_store`: S3-compatible file storage
+            - `vector_store`: some vector store?
+    - `client`
+        - ?

agentstack_sdk-0.4.1rc1/README.md

@@ -0,0 +1,45 @@
+# Agent Stack SDK
+
+## Examples
+
+The examples connect to the Agent Stack for LLM inteference.
+
+Run using:
+
+```bash
+uv run examples/agent.py
+```
+
+Connect to the agent using the CLI:
+
+```bash
+uv run examples/cli.py
+```
+
+## Plan
+
+- `agentstack_sdk`
+    - `a2a`:
+        - `extensions`: Shared definitions for A2A extensions
+            - `services`: Dependency injection extensions for external services
+                - `llm`
+                - `embedding`
+                - `docling`
+                - `file_store`
+                - `vector_store`
+            - `ui`: User interface extensions for Agent Stack UI
+                - `trajectory`
+                - `citations`
+            - `history`: store and allow requesting the full history of the context
+    - `server`
+        - `context_storage`: store data associated with context_id
+        - `wrapper`: conveniently build A2A agents -- opinionated on how tasks work, `yield`-semantics, autowired
+          services
+        - `services`: clients for external services
+            - `llm`: OpenAI-compatible chat LLM
+            - `embedding`: OpenAI-compatible embedding
+            - `text_extraction`: Docling-compatible text extraction
+            - `file_store`: S3-compatible file storage
+            - `vector_store`: some vector store?
+    - `client`
+        - ?

agentstack_sdk-0.4.1rc1/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "agentstack-sdk"
+version = "0.4.1-rc1"
+description = "Agent Stack SDK"
+readme = "README.md"
+authors = [{ name = "IBM Corp." }]
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "a2a-sdk==0.3.9",
+    "objprint>=0.3.0",
+    "uvicorn>=0.35.0",
+    "asyncclick>=8.1.8",
+    "sse-starlette>=2.2.1",
+    "starlette>=0.47.2",
+    "anyio>=4.9.0",
+    "opentelemetry-api>=1.35.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.35.0",
+    "opentelemetry-instrumentation-fastapi>=0.56b0",
+    "opentelemetry-sdk>=1.35.0",
+    "tenacity>=9.1.2",
+    "janus>=2.0.0",
+    "httpx",                                          # version determined by a2a-sdk
+    "mcp>=1.12.3",
+    "fastapi>=0.116.1",
+]
+
+[dependency-groups]
+dev = [
+    "beeai-framework[duckduckgo,wikipedia]>=0.1.58",
+    "pyright>=1.1.403",
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.1.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.12.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+lint.select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "UP",    # pyupgrade
+    "I",     # isort
+    "B",     # bugbear
+    "N",     # pep8-naming
+    "C4",    # Comprehensions
+    "Q",     # Quotes
+    "SIM",   # Simplify
+    "RUF",   # Ruff
+    "TID",   # tidy-imports
+    "ASYNC", # async
+    # TODO: add "DTZ",   # DatetimeZ
+    # TODO: add "ANN",   # annotations
+]
+lint.ignore = [
+    "E501", # line lenght (annyoing)
+    "N999", # invalid module name agentstack-server (yeah, we use a dash, deal with it)
+    "F403", # redundant with Pyright
+]
+force-exclude = true
+
+[tool.pytest.ini_options]
+markers = ["e2e", "unit"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "-v"
+
+[tool.pyright]
+ignore = ["tests/**", "examples/cli.py"]
+venvPath = "."
+venv = ".venv"

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from importlib.metadata import version
+
+__version__ = version("agentstack-sdk")

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from .auth import *
+from .services import *
+from .ui import *

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from .oauth import *
+from .secrets import *

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/oauth/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from .oauth import *

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/oauth/oauth.py

@@ -0,0 +1,144 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import uuid
+from types import NoneType
+from typing import TYPE_CHECKING, Any, Self
+from urllib.parse import parse_qs
+
+import a2a.types
+import pydantic
+from mcp.client.auth import OAuthClientProvider
+from mcp.shared.auth import OAuthClientMetadata
+
+from agentstack_sdk.a2a.extensions.auth.oauth.storage import MemoryTokenStorageFactory, TokenStorageFactory
+from agentstack_sdk.a2a.extensions.base import BaseExtensionClient, BaseExtensionServer, BaseExtensionSpec
+from agentstack_sdk.a2a.types import AgentMessage, AuthRequired, RunYieldResume
+
+if TYPE_CHECKING:
+    from agentstack_sdk.server.context import RunContext
+
+_DEFAULT_DEMAND_NAME = "default"
+
+
+class AuthRequest(pydantic.BaseModel):
+    authorization_endpoint_url: pydantic.AnyUrl
+
+
+class AuthResponse(pydantic.BaseModel):
+    redirect_uri: pydantic.AnyUrl
+
+
+class OAuthFulfillment(pydantic.BaseModel):
+    redirect_uri: pydantic.AnyUrl
+
+
+class OAuthDemand(pydantic.BaseModel):
+    redirect_uri: bool = True
+
+
+class OAuthExtensionParams(pydantic.BaseModel):
+    oauth_demands: dict[str, OAuthDemand]
+    """Server requests that the agent requires to be provided by the client."""
+
+
+class OAuthExtensionSpec(BaseExtensionSpec[OAuthExtensionParams]):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/auth/oauth/v1"
+
+    @classmethod
+    def single_demand(cls, name: str = _DEFAULT_DEMAND_NAME) -> Self:
+        return cls(params=OAuthExtensionParams(oauth_demands={name: OAuthDemand()}))
+
+
+class OAuthExtensionMetadata(pydantic.BaseModel):
+    oauth_fulfillments: dict[str, OAuthFulfillment] = {}
+    """Provided servers corresponding to the server requests."""
+
+
+class OAuthExtensionServer(BaseExtensionServer[OAuthExtensionSpec, OAuthExtensionMetadata]):
+    def __init__(self, spec: OAuthExtensionSpec, token_storage_factory: TokenStorageFactory | None = None) -> None:
+        super().__init__(spec)
+        self.token_storage_factory = token_storage_factory or MemoryTokenStorageFactory()
+
+    def handle_incoming_message(self, message: a2a.types.Message, context: RunContext):
+        super().handle_incoming_message(message, context)
+        self.context = context
+
+    def _get_fulfillment_for_resource(self, resource_url: pydantic.AnyUrl):
+        if not self.data:
+            raise RuntimeError("No fulfillments found")
+
+        fulfillment = self.data.oauth_fulfillments.get(str(resource_url)) or self.data.oauth_fulfillments.get(
+            _DEFAULT_DEMAND_NAME
+        )
+        if fulfillment:
+            return fulfillment
+
+        raise RuntimeError("Fulfillment not found")
+
+    async def create_httpx_auth(self, *, resource_url: pydantic.AnyUrl):
+        fulfillment = self._get_fulfillment_for_resource(resource_url=resource_url)
+
+        resume: RunYieldResume = None
+
+        async def handle_redirect(auth_url: str) -> None:
+            nonlocal resume
+            if resume:
+                raise RuntimeError("Another redirect is already pending")
+            message = self.create_auth_request(authorization_endpoint_url=pydantic.AnyUrl(auth_url))
+            resume = await self.context.yield_async(AuthRequired(message=message))
+
+        async def handle_callback() -> tuple[str, str | None]:
+            nonlocal resume
+            try:
+                if not resume:
+                    raise ValueError("Missing resume data")
+                response = self.parse_auth_response(message=resume)
+                params = parse_qs(response.redirect_uri.query)
+                return params["code"][0], params.get("state", [None])[0]
+            finally:
+                resume = None
+
+        # A2A Client is responsible for catching the redirect and forwarding it over the A2A connection
+        oauth_auth = OAuthClientProvider(
+            server_url=str(resource_url),
+            client_metadata=OAuthClientMetadata(
+                redirect_uris=[fulfillment.redirect_uri],
+            ),
+            storage=await self.token_storage_factory.create_storage(),
+            redirect_handler=handle_redirect,
+            callback_handler=handle_callback,
+        )
+        return oauth_auth
+
+    def create_auth_request(self, *, authorization_endpoint_url: pydantic.AnyUrl):
+        data = AuthRequest(authorization_endpoint_url=authorization_endpoint_url)
+        return AgentMessage(text="Authorization required", metadata={self.spec.URI: data.model_dump(mode="json")})
+
+    def parse_auth_response(self, *, message: a2a.types.Message):
+        if not message or not message.metadata or not (data := message.metadata.get(self.spec.URI)):
+            raise RuntimeError("Invalid auth response")
+        return AuthResponse.model_validate(data)
+
+
+class OAuthExtensionClient(BaseExtensionClient[OAuthExtensionSpec, NoneType]):
+    def fulfillment_metadata(self, *, oauth_fulfillments: dict[str, Any]) -> dict[str, Any]:
+        return {self.spec.URI: OAuthExtensionMetadata(oauth_fulfillments=oauth_fulfillments).model_dump(mode="json")}
+
+    def parse_auth_request(self, *, message: a2a.types.Message):
+        if not message or not message.metadata or not (data := message.metadata.get(self.spec.URI)):
+            raise ValueError("Invalid auth request")
+        return AuthRequest.model_validate(data)
+
+    def create_auth_response(self, *, task_id: str, redirect_uri: pydantic.AnyUrl):
+        data = AuthResponse(redirect_uri=redirect_uri)
+
+        return a2a.types.Message(
+            message_id=str(uuid.uuid4()),
+            role=a2a.types.Role.user,
+            parts=[a2a.types.TextPart(text="Authorization completed")],  # type: ignore
+            task_id=task_id,
+            metadata={self.spec.URI: data.model_dump(mode="json")},
+        )

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/oauth/storage/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from .base import *
+from .memory import *

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/oauth/storage/base.py

@@ -0,0 +1,11 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+import abc
+
+from mcp.client.auth import TokenStorage
+
+
+class TokenStorageFactory(abc.ABC):
+    @abc.abstractmethod
+    async def create_storage(self) -> TokenStorage: ...

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/oauth/storage/memory.py

@@ -0,0 +1,38 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+
+from mcp.client.auth import TokenStorage
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+
+from .base import TokenStorageFactory
+
+
+class MemoryTokenStorage(TokenStorage):
+    def __init__(self):
+        self.tokens: OAuthToken | None = None
+        self.client_info: OAuthClientInformationFull | None = None
+
+    async def get_tokens(self) -> OAuthToken | None:
+        return self.tokens
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        self.tokens = tokens
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        return self.client_info
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        self.client_info = client_info
+
+
+class MemoryTokenStorageFactory(TokenStorageFactory):
+    def __init__(self, *, client_info: OAuthClientInformationFull | None = None):
+        super().__init__()
+        self._client_info = client_info
+
+    async def create_storage(self) -> TokenStorage:
+        storage = MemoryTokenStorage()
+        if self._client_info:
+            await storage.set_client_info(self._client_info)
+        return storage

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/secrets/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from .secrets import *

agentstack_sdk-0.4.1rc1/src/agentstack_sdk/a2a/extensions/auth/secrets/secrets.py

@@ -0,0 +1,71 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+import typing
+from typing import TYPE_CHECKING
+
+import pydantic
+from a2a.types import Message as A2AMessage
+
+from agentstack_sdk.a2a.extensions.base import BaseExtensionClient, BaseExtensionServer, BaseExtensionSpec
+from agentstack_sdk.a2a.types import AgentMessage, AuthRequired
+
+if TYPE_CHECKING:
+    from agentstack_sdk.server.context import RunContext
+
+
+class SecretDemand(pydantic.BaseModel):
+    name: str
+    description: str | None = None
+
+
+class SecretFulfillment(pydantic.BaseModel):
+    secret: str
+
+
+class SecretsServiceExtensionParams(pydantic.BaseModel):
+    secret_demands: dict[str, SecretDemand]
+
+
+class SecretsServiceExtensionMetadata(pydantic.BaseModel):
+    secret_fulfillments: dict[str, SecretFulfillment] = {}
+
+
+class SecretsExtensionSpec(BaseExtensionSpec[SecretsServiceExtensionParams | None]):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/auth/secrets/v1"
+
+    @classmethod
+    def single_demand(cls, name: str, key: str | None = None, description: str | None = None) -> typing.Self:
+        return cls(
+            params=SecretsServiceExtensionParams(
+                secret_demands={key or "default": SecretDemand(description=description, name=name)}
+            )
+        )
+
+
+class SecretsExtensionServer(BaseExtensionServer[SecretsExtensionSpec, SecretsServiceExtensionMetadata]):
+    def handle_incoming_message(self, message: A2AMessage, context: "RunContext"):
+        super().handle_incoming_message(message, context)
+        self.context = context
+
+    def parse_secret_response(self, message: A2AMessage) -> SecretsServiceExtensionMetadata:
+        if not message or not message.metadata or not (data := message.metadata.get(self.spec.URI)):
+            raise ValueError("Secrets has not been provided in response.")
+
+        return SecretsServiceExtensionMetadata.model_validate(data)
+
+    async def request_secrets(self, params: SecretsServiceExtensionParams) -> SecretsServiceExtensionMetadata:
+        resume = await self.context.yield_async(
+            AuthRequired(
+                message=AgentMessage(
+                    metadata={self.spec.URI: params.model_dump(mode="json")},
+                )
+            )
+        )
+        if isinstance(resume, A2AMessage):
+            return self.parse_secret_response(message=resume)
+        else:
+            raise ValueError("Secrets has not been provided in response.")
+
+
+class SecretsExtensionClient(BaseExtensionClient[SecretsExtensionSpec, SecretsServiceExtensionParams]): ...