agentstack-sdk 0.4.3rc3__py3-none-any.whl → 0.5.0__py3-none-any.whl

agentstack_sdk/a2a/extensions/base.py

@@ -111,7 +111,7 @@ class NoParamsBaseExtensionSpec(BaseExtensionSpec[NoneType]):
         return None
 
 
-ExtensionSpecT = typing.TypeVar("ExtensionSpecT", bound=BaseExtensionSpec)
+ExtensionSpecT = typing.TypeVar("ExtensionSpecT", bound=BaseExtensionSpec[typing.Any])
 
 
 class BaseExtensionServer(abc.ABC, typing.Generic[ExtensionSpecT, MetadataFromClientT]):

agentstack_sdk/a2a/extensions/services/form.py

@@ -4,9 +4,10 @@
 
 from __future__ import annotations
 
-from typing import Self, TypedDict, TypeVar, cast
+from typing import Self, TypeVar, cast
 
 from pydantic import BaseModel, TypeAdapter
+from typing_extensions import TypedDict
 
 from agentstack_sdk.a2a.extensions.base import BaseExtensionClient, BaseExtensionServer, BaseExtensionSpec
 from agentstack_sdk.a2a.extensions.common.form import FormRender, FormResponse

agentstack_sdk/a2a/extensions/services/mcp.py

@@ -39,7 +39,7 @@ class StdioTransport(pydantic.BaseModel):
 class StreamableHTTPTransport(pydantic.BaseModel):
     type: Literal["streamable_http"] = "streamable_http"
 
-    url: pydantic.AnyHttpUrl
+    url: str
     headers: dict[str, str] | None = None
 
 
@@ -111,13 +111,7 @@ class MCPServiceExtensionServer(BaseExtensionServer[MCPServiceExtensionSpec, MCP
         for fullfilment in self.data.mcp_fulfillments.values():
             if fullfilment.transport.type == "streamable_http":
                 try:
-                    fullfilment.transport.url = pydantic.AnyHttpUrl(
-                        re.sub(
-                            r"^http[s]?://{platform_url}",
-                            platform_url,
-                            str(fullfilment.transport.url),
-                        )
-                    )
+                    fullfilment.transport.url = re.sub("^{platform_url}", platform_url, str(fullfilment.transport.url))
                 except Exception:
                     logger.warning("Platform URL substitution failed", exc_info=True)
 
@@ -126,7 +120,7 @@ class MCPServiceExtensionServer(BaseExtensionServer[MCPServiceExtensionSpec, MCP
         if metadata:
             for name, demand in self.spec.params.mcp_demands.items():
                 if not (fulfillment := metadata.mcp_fulfillments.get(name)):
-                    raise ValueError(f'Fulfillment for demand "{name}" missing')
+                    continue
                 if fulfillment.transport.type not in demand.allowed_transports:
                     raise ValueError(f'Transport "{fulfillment.transport.type}" not allowed for demand "{name}"')
         return metadata
@@ -148,7 +142,8 @@ class MCPServiceExtensionServer(BaseExtensionServer[MCPServiceExtensionSpec, MCP
         fulfillment = self.data.mcp_fulfillments.get(demand) if self.data else None
 
         if not fulfillment:
-            raise ValueError(f'No fulfillment for demand "{demand}"')
+            yield None
+            return
 
         transport = fulfillment.transport
 
@@ -162,7 +157,7 @@ class MCPServiceExtensionServer(BaseExtensionServer[MCPServiceExtensionSpec, MCP
                 yield (read, write)
         elif isinstance(transport, StreamableHTTPTransport):
             async with streamablehttp_client(
-                url=str(transport.url),
+                url=transport.url,
                 headers=transport.headers,
                 auth=await self._create_auth(transport),
             ) as (
@@ -180,12 +175,12 @@ class MCPServiceExtensionServer(BaseExtensionServer[MCPServiceExtensionSpec, MCP
             platform
             and platform.data
             and platform.data.base_url
-            and str(transport.url).startswith(str(platform.data.base_url))
+            and transport.url.startswith(str(platform.data.base_url))
         ):
             return await platform.create_httpx_auth()
         oauth = self._get_oauth_server()
         if oauth:
-            return await oauth.create_httpx_auth(resource_url=transport.url)
+            return await oauth.create_httpx_auth(resource_url=pydantic.AnyUrl(transport.url))
         return None
 
 

agentstack_sdk/a2a/extensions/ui/canvas.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 import pydantic
-from a2a.types import Artifact
+from a2a.types import Artifact, TextPart
 from a2a.types import Message as A2AMessage
 
 if TYPE_CHECKING:
@@ -38,6 +38,9 @@ class CanvasExtensionSpec(NoParamsBaseExtensionSpec):
 
 class CanvasExtensionServer(BaseExtensionServer[CanvasExtensionSpec, CanvasEditRequestMetadata]):
     def handle_incoming_message(self, message: A2AMessage, context: RunContext):
+        if message.metadata and self.spec.URI in message.metadata and message.parts:
+            message.parts = [part for part in message.parts if not isinstance(part.root, TextPart)]
+
         super().handle_incoming_message(message, context)
         self.context = context
 

agentstack_sdk/a2a/extensions/ui/citation.py

@@ -4,7 +4,6 @@
 from __future__ import annotations
 
 from types import NoneType
-from typing import Any
 
 import pydantic
 from a2a.types import DataPart, FilePart, Part, TextPart
@@ -59,11 +58,7 @@ class CitationExtensionSpec(NoParamsBaseExtensionSpec):
 
 
 class CitationExtensionServer(BaseExtensionServer[CitationExtensionSpec, NoneType]):
-    def citation_metadata(
-        self,
-        *,
-        citations: list[Citation],
-    ) -> Metadata[str, Any]:
+    def citation_metadata(self, *, citations: list[Citation]) -> Metadata:
         return Metadata({self.spec.URI: CitationMetadata(citations=citations).model_dump(mode="json")})
 
     def message(

agentstack_sdk/a2a/extensions/ui/error.py

@@ -3,14 +3,13 @@
 
 from __future__ import annotations
 
-import contextvars
 import json
 import logging
 import traceback
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from types import NoneType
-from typing import Any
+from typing import Any, Final
 
 import pydantic
 
@@ -20,6 +19,7 @@ from agentstack_sdk.a2a.extensions.base import (
     BaseExtensionSpec,
 )
 from agentstack_sdk.a2a.types import AgentMessage, JsonDict, Metadata
+from agentstack_sdk.util import resource_context
 
 logger = logging.getLogger(__name__)
 
@@ -125,25 +125,18 @@ def _extract_error(exc: BaseException) -> Error | ErrorGroup:
 class ErrorExtensionServer(BaseExtensionServer[ErrorExtensionSpec, NoneType]):
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
-        # Server-scoped ContextVar for request-scoped error context
-        self._error_context_var: contextvars.ContextVar[JsonDict] = contextvars.ContextVar("error_context")
 
     @asynccontextmanager
     async def lifespan(self) -> AsyncIterator[None]:
         """Set up request-scoped error context using ContextVar."""
-        # Set an empty dict for this request's context
-        token = self._error_context_var.set({})
-
-        try:
+        with use_error_extension_context(server=self, context={}):
             yield
-        finally:
-            self._error_context_var.reset(token)
 
     @property
     def context(self) -> JsonDict:
         """Get the current request's error context."""
         try:
-            return self._error_context_var.get()
+            return get_error_extension_context().context
         except LookupError:
             # Fallback for when lifespan hasn't been entered yet
             logger.warning(
@@ -151,7 +144,7 @@ class ErrorExtensionServer(BaseExtensionServer[ErrorExtensionSpec, NoneType]):
             )
             return {}
 
-    def error_metadata(self, error: BaseException) -> Metadata[str, Any]:
+    def error_metadata(self, error: BaseException) -> Metadata:
         """
         Create metadata for an error.
 
@@ -186,28 +179,44 @@ class ErrorExtensionServer(BaseExtensionServer[ErrorExtensionSpec, NoneType]):
         Returns:
             AgentMessage with error metadata and markdown-formatted text
         """
-        metadata = self.error_metadata(error)
-        error_metadata = ErrorMetadata.model_validate(metadata[self.spec.URI])
-
-        # Serialize to markdown for display
-        text_lines: list[str] = []
-        if isinstance(error_metadata.error, ErrorGroup):
-            text_lines.append(f"## {error_metadata.error.message}\n")
-            for err in error_metadata.error.errors:
-                text_lines.append(f"### {err.title}\n{err.message}")
-        else:
-            text_lines.append(f"## {error_metadata.error.title}\n{error_metadata.error.message}")
+        try:
+            metadata = self.error_metadata(error)
+            error_metadata = ErrorMetadata.model_validate(metadata[self.spec.URI])
+
+            # Serialize to markdown for display
+            text_lines: list[str] = []
+            if isinstance(error_metadata.error, ErrorGroup):
+                text_lines.append(f"## {error_metadata.error.message}\n")
+                for err in error_metadata.error.errors:
+                    text_lines.append(f"### {err.title}\n{err.message}")
+            else:
+                text_lines.append(f"## {error_metadata.error.title}\n{error_metadata.error.message}")
 
-        # Add context if present
-        if error_metadata.context:
-            text_lines.append(f"## Context\n```json\n{json.dumps(error_metadata.context, indent=2)}\n```")
+            # Add context if present
+            if error_metadata.context:
+                text_lines.append(f"## Context\n```json\n{json.dumps(error_metadata.context, indent=2)}\n```")
 
-        if error_metadata.stack_trace:
-            text_lines.append(f"## Stack Trace\n```\n{error_metadata.stack_trace}\n```")
+            if error_metadata.stack_trace:
+                text_lines.append(f"## Stack Trace\n```\n{error_metadata.stack_trace}\n```")
 
-        text = "\n\n".join(text_lines)
+            text = "\n\n".join(text_lines)
 
-        return AgentMessage(text=text, metadata=metadata)
+            return AgentMessage(text=text, metadata=metadata)
+        except Exception as error_exc:
+            return AgentMessage(text=f"Failed to create error message: {error_exc!s}\noriginal exc: {error!s}")
 
 
 class ErrorExtensionClient(BaseExtensionClient[ErrorExtensionSpec, ErrorMetadata]): ...
+
+
+DEFAULT_ERROR_EXTENSION: Final = ErrorExtensionServer(ErrorExtensionSpec(ErrorExtensionParams()))
+
+
+class ErrorContext(pydantic.BaseModel, arbitrary_types_allowed=True):
+    server: ErrorExtensionServer = pydantic.Field(default=DEFAULT_ERROR_EXTENSION)
+    context: JsonDict = pydantic.Field(default_factory=dict)
+
+
+get_error_extension_context, use_error_extension_context = resource_context(
+    factory=ErrorContext, default_factory=ErrorContext
+)

agentstack_sdk/a2a/extensions/ui/trajectory.py

@@ -4,7 +4,6 @@
 from __future__ import annotations
 
 from types import NoneType
-from typing import Any
 
 import pydantic
 from a2a.types import DataPart, FilePart, Part, TextPart
@@ -49,7 +48,7 @@ class TrajectoryExtensionSpec(NoParamsBaseExtensionSpec):
 class TrajectoryExtensionServer(BaseExtensionServer[TrajectoryExtensionSpec, NoneType]):
     def trajectory_metadata(
         self, *, title: str | None = None, content: str | None = None, group_id: str | None = None
-    ) -> Metadata[str, Any]:
+    ) -> Metadata:
         return Metadata(
             {self.spec.URI: Trajectory(title=title, content=content, group_id=group_id).model_dump(mode="json")}
         )

agentstack_sdk/a2a/types.py

@@ -1,8 +1,7 @@
 # Copyright 2025 © BeeAI a Series of LF Projects, LLC
 # SPDX-License-Identifier: Apache-2.0
-import typing
 import uuid
-from typing import Generic, Literal, TypeAlias, TypeAliasType, Union
+from typing import TYPE_CHECKING, Literal, TypeAlias
 
 from a2a.types import (
     Artifact,
@@ -21,11 +20,19 @@ from a2a.types import (
 )
 from pydantic import Field, model_validator
 
-K = typing.TypeVar("K")
-V = typing.TypeVar("V")
+if TYPE_CHECKING:
+    JsonValue: TypeAlias = list["JsonValue"] | dict[str, "JsonValue"] | str | bool | int | float | None
+    JsonDict: TypeAlias = dict[str, JsonValue]
+else:
+    from typing import Union
 
+    from typing_extensions import TypeAliasType
 
-class Metadata(dict[K, V], Generic[K, V]): ...
+    JsonValue = TypeAliasType("JsonValue", "Union[dict[str, JsonValue], list[JsonValue], str, int, float, bool, None]")  # noqa: UP007
+    JsonDict = TypeAliasType("JsonDict", "dict[str, JsonValue]")
+
+
+class Metadata(dict[str, JsonValue]): ...
 
 
 RunYield: TypeAlias = (
@@ -42,7 +49,7 @@ RunYield: TypeAlias = (
     | TaskStatusUpdateEvent
     | TaskArtifactUpdateEvent
     | str
-    | dict
+    | JsonDict
     | Exception
 )
 RunYieldResume: TypeAlias = Message | None
@@ -50,7 +57,7 @@ RunYieldResume: TypeAlias = Message | None
 
 class AgentArtifact(Artifact):
     artifact_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
-    parts: list[Part | TextPart | FilePart | DataPart]  # pyright: ignore [reportIncompatibleVariableOverride]
+    parts: list[Part | TextPart | FilePart | DataPart]
 
     @model_validator(mode="after")
     def text_message_validate(self):
@@ -60,7 +67,7 @@ class AgentArtifact(Artifact):
 
 class ArtifactChunk(Artifact):
     last_chunk: bool = False
-    parts: list[Part | TextPart | FilePart | DataPart]  # pyright: ignore [reportIncompatibleVariableOverride]
+    parts: list[Part | TextPart | FilePart | DataPart]
 
     @model_validator(mode="after")
     def text_message_validate(self):
@@ -104,9 +111,3 @@ class InputRequired(TaskStatus):
 
 class AuthRequired(InputRequired):
     state: Literal[TaskState.auth_required] = TaskState.auth_required  # pyright: ignore [reportIncompatibleVariableOverride]
-
-
-JsonDict = TypeAliasType(
-    "JsonDict",
-    "Union[dict[str, JsonDict], list[JsonDict], str, int, float, bool, None]",  # pyright: ignore[reportDeprecated]  # noqa: UP007
-)

agentstack_sdk/platform/__init__.py

@@ -7,4 +7,6 @@ from .file import *
 from .model_provider import *
 from .provider import *
 from .provider_build import *
+from .user import *
+from .user_feedback import *
 from .vector_store import *

agentstack_sdk/platform/context.py

@@ -31,10 +31,6 @@ class ContextToken(pydantic.BaseModel):
     expires_at: pydantic.AwareDatetime | None = None
 
 
-class ResourceIdPermission(pydantic.BaseModel):
-    id: str
-
-
 class ContextPermissions(pydantic.BaseModel):
     files: set[Literal["read", "write", "extract", "*"]] = set()
     vector_stores: set[Literal["read", "write", "*"]] = set()
@@ -42,8 +38,8 @@ class ContextPermissions(pydantic.BaseModel):
 
 
 class Permissions(ContextPermissions):
-    llm: set[Literal["*"] | ResourceIdPermission] = set()
-    embeddings: set[Literal["*"] | ResourceIdPermission] = set()
+    llm: set[Literal["*"] | str] = set()
+    embeddings: set[Literal["*"] | str] = set()
     a2a_proxy: set[Literal["*"]] = set()
     model_providers: set[Literal["read", "write", "*"]] = set()
     variables: SerializeAsAny[set[Literal["read", "write", "*"]]] = set()

agentstack_sdk/platform/file.py

@@ -16,11 +16,20 @@ from agentstack_sdk.platform.common import PaginatedResult
 from agentstack_sdk.util.file import LoadedFile, LoadedFileWithUri, PlatformFileUrl
 from agentstack_sdk.util.utils import filter_dict
 
+ExtractionFormatLiteral = typing.Literal["markdown", "vendor_specific_json"]
+
+
+class ExtractedFileInfo(pydantic.BaseModel):
+    """Information about an extracted file."""
+
+    file_id: str
+    format: ExtractionFormatLiteral | None
+
 
 class Extraction(pydantic.BaseModel):
     id: str
     file_id: str
-    extracted_file_id: str | None = None
+    extracted_files: list[ExtractedFileInfo] = pydantic.Field(default_factory=list)
     status: typing.Literal["pending", "in_progress", "completed", "failed", "cancelled"] = "pending"
     job_id: str | None = None
     error_message: str | None = None
@@ -152,9 +161,43 @@ class File(pydantic.BaseModel):
                     await response.aread()
                 yield LoadedFileWithUri(response=response, content_type=file.content_type, filename=file.filename)
 
+    @asynccontextmanager
+    async def load_json_content(
+        self: File | str,
+        *,
+        stream: bool = False,
+        client: PlatformClient | None = None,
+        context_id: str | None | Literal["auto"] = "auto",
+    ) -> AsyncIterator[LoadedFile]:
+        # `self` has a weird type so that you can call both `instance.load_json_content()` to create an extraction for an instance, or `File.load_json_content("123")`
+        file_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as platform_client:
+            context_id = platform_client.context_id if context_id == "auto" else context_id
+
+            file = await File.get(file_id, client=client, context_id=context_id) if isinstance(self, str) else self
+            extraction = await file.get_extraction(client=client, context_id=context_id)
+
+            for extracted_file_info in extraction.extracted_files:
+                if extracted_file_info.format != "vendor_specific_json":
+                    continue
+                extracted_json_file_id = extracted_file_info.file_id
+                async with platform_client.stream(
+                    "GET",
+                    url=f"/api/v1/files/{extracted_json_file_id}/content",
+                    params=context_id and {"context_id": context_id},
+                ) as response:
+                    response.raise_for_status()
+                    if not stream:
+                        await response.aread()
+                    yield LoadedFileWithUri(response=response, content_type=file.content_type, filename=file.filename)
+                return
+
+            raise ValueError("No extracted JSON content available for this file.")
+
     async def create_extraction(
         self: File | str,
         *,
+        formats: list[ExtractionFormatLiteral] | None = None,
         client: PlatformClient | None = None,
         context_id: str | None | Literal["auto"] = "auto",
     ) -> Extraction:
@@ -167,6 +210,7 @@ class File(pydantic.BaseModel):
                     await platform_client.post(
                         url=f"/api/v1/files/{file_id}/extraction",
                         params=context_id and {"context_id": context_id},
+                        json={"settings": {"formats": formats}} if formats else None,
                     )
                 )
                 .raise_for_status()

agentstack_sdk/platform/user.py

@@ -3,23 +3,68 @@
 
 from __future__ import annotations
 
-from typing import Literal
+from enum import StrEnum
 
 import pydantic
 
 from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+from agentstack_sdk.platform.common import PaginatedResult
+
+
+class UserRole(StrEnum):
+    ADMIN = "admin"
+    DEVELOPER = "developer"
+    USER = "user"
+
+
+class ChangeRoleResponse(pydantic.BaseModel):
+    user_id: str
+    new_role: UserRole
 
 
 class User(pydantic.BaseModel):
     id: str
-    role: Literal["admin", "developer", "user"]
-    email: pydantic.EmailStr
+    role: UserRole
+    email: str
     created_at: pydantic.AwareDatetime
+    role_updated_at: pydantic.AwareDatetime | None = None
 
     @staticmethod
     async def get(*, client: PlatformClient | None = None) -> User:
-        """Get the current user information."""
         async with client or get_platform_client() as client:
             return pydantic.TypeAdapter(User).validate_python(
                 (await client.get(url="/api/v1/user")).raise_for_status().json()
             )
+
+    @staticmethod
+    async def list(
+        *,
+        email: str | None = None,
+        limit: int = 40,
+        page_token: str | None = None,
+        client: PlatformClient | None = None,
+    ) -> PaginatedResult[User]:
+        async with client or get_platform_client() as client:
+            params: dict[str, int | str] = {"limit": limit}
+            if email:
+                params["email"] = email
+            if page_token:
+                params["page_token"] = page_token
+
+            return pydantic.TypeAdapter(PaginatedResult[User]).validate_python(
+                (await client.get(url="/api/v1/users", params=params)).raise_for_status().json()
+            )
+
+    @staticmethod
+    async def set_role(
+        user_id: str,
+        new_role: UserRole,
+        *,
+        client: PlatformClient | None = None,
+    ) -> ChangeRoleResponse:
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(ChangeRoleResponse).validate_python(
+                (await client.put(url=f"/api/v1/users/{user_id}/role", json={"new_role": new_role}))
+                .raise_for_status()
+                .json()
+            )

agentstack_sdk/platform/user_feedback.py

@@ -0,0 +1,42 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from datetime import datetime
+from uuid import UUID
+
+import pydantic
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+from agentstack_sdk.platform.common import PaginatedResult
+from agentstack_sdk.util.utils import filter_dict
+
+
+class UserFeedback(pydantic.BaseModel):
+    id: UUID
+    provider_id: UUID
+    task_id: UUID
+    context_id: UUID
+    rating: int
+    message: str
+    comment: str | None = None
+    comment_tags: list[str] | None = None
+    created_at: datetime
+    agent_name: str
+
+    @staticmethod
+    async def list(
+        *,
+        provider_id: str | None = None,
+        limit: int = 50,
+        after_cursor: str | None = None,
+        client: PlatformClient | None = None,
+    ) -> "ListUserFeedbackResponse":
+        async with client or get_platform_client() as client:
+            params = filter_dict({"provider_id": provider_id, "limit": limit, "after_cursor": after_cursor})
+            return pydantic.TypeAdapter(ListUserFeedbackResponse).validate_python(
+                (await client.get(url="/api/v1/user_feedback", params=params)).raise_for_status().json()
+            )
+
+
+class ListUserFeedbackResponse(PaginatedResult[UserFeedback]):
+    pass