agentstack-sdk 0.5.2rc2__py3-none-any.whl

agentstack_sdk/a2a/extensions/ui/error.py

@@ -0,0 +1,223 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+import logging
+import traceback
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from types import NoneType
+from typing import Any, Final
+
+import pydantic
+
+from agentstack_sdk.a2a.extensions.base import (
+    BaseExtensionClient,
+    BaseExtensionServer,
+    BaseExtensionSpec,
+)
+from agentstack_sdk.a2a.types import AgentMessage, Metadata
+from agentstack_sdk.types import JsonValue
+from agentstack_sdk.util import resource_context
+
+logger = logging.getLogger(__name__)
+
+
+class Error(pydantic.BaseModel):
+    """
+    Represents error information for displaying exceptions in the UI.
+
+    This extension helps display errors in a user-friendly way with:
+    - A clear error title (exception type)
+    - A descriptive error message
+
+    Visually, this may appear as an error card in the UI.
+
+    Properties:
+    - title: Title of the error (typically the exception class name).
+    - message: The error message describing what went wrong.
+    """
+
+    title: str
+    message: str
+
+
+class ErrorGroup(pydantic.BaseModel):
+    """
+    Represents a group of errors.
+
+    Properties:
+    - message: A message describing the group of errors.
+    - errors: A list of error objects.
+    """
+
+    message: str
+    errors: list[Error]
+
+
+class ErrorMetadata(pydantic.BaseModel):
+    """
+    Metadata containing an error (or group of errors) and an optional stack trace.
+
+    Properties:
+    - error: The error object or group of errors.
+    - stack_trace: Optional formatted stack trace for debugging.
+    - context: Optional context dictionary.
+    """
+
+    error: Error | ErrorGroup
+    stack_trace: str | None = None
+    context: JsonValue | None = None
+
+
+class ErrorExtensionParams(pydantic.BaseModel):
+    """
+    Configuration parameters for the error extension.
+
+    Properties:
+    - include_stacktrace: Whether to include stack traces in error messages (default: False).
+    """
+
+    include_stacktrace: bool = False
+
+
+class ErrorExtensionSpec(BaseExtensionSpec[ErrorExtensionParams]):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/ui/error/v1"
+
+
+def _format_stacktrace(exc: BaseException, include_cause: bool = True) -> str:
+    """Format exception with full traceback including nested causes."""
+    return "".join(traceback.format_exception(type(exc), exc, exc.__traceback__, chain=include_cause))
+
+
+def _extract_error(exc: BaseException) -> Error | ErrorGroup:
+    """
+    Extract error information from an exception, handling:
+    - BaseExceptionGroup (returns ErrorGroup)
+    - FrameworkError from beeai_framework (uses .explain() method)
+    """
+    # Handle BaseExceptionGroup by recursively extracting errors from each exception
+    if isinstance(exc, BaseExceptionGroup):
+        errors: list[Error] = []
+        for sub_exc in exc.exceptions:
+            extracted = _extract_error(sub_exc)
+            if isinstance(extracted, ErrorGroup):
+                errors.extend(extracted.errors)
+            else:
+                errors.append(extracted)
+        return ErrorGroup(message=str(exc), errors=errors)
+
+    # Try to handle FrameworkError if beeai_framework is available
+    try:
+        from beeai_framework.errors import FrameworkError
+
+        if isinstance(exc, FrameworkError):
+            # FrameworkError has special .explain() method
+            return Error(title=exc.name(), message=exc.explain())
+    except ImportError:
+        # beeai_framework not installed, continue with standard handling
+        pass
+
+    return Error(title=type(exc).__name__, message=str(exc))
+
+
+class ErrorExtensionServer(BaseExtensionServer[ErrorExtensionSpec, NoneType]):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Set up request-scoped error context using ContextVar."""
+        with use_error_extension_context(server=self, context={}):
+            yield
+
+    @property
+    def context(self) -> JsonValue:
+        """Get the current request's error context."""
+        try:
+            return get_error_extension_context().context
+        except LookupError:
+            # Fallback for when lifespan hasn't been entered yet
+            logger.warning(
+                "Attempted to use error context when the error extension is not initialized. Make sure to add the ErrorExtensionServer to the agent dependencies."
+            )
+            return {}
+
+    def error_metadata(self, error: BaseException) -> Metadata:
+        """
+        Create metadata for an error.
+
+        Args:
+            error: The exception to convert to metadata
+
+        Returns:
+            Metadata dictionary with error information
+        """
+        error_data = _extract_error(error)
+        stack_trace = _format_stacktrace(error) if self.spec.params.include_stacktrace else None
+        return Metadata(
+            {
+                self.spec.URI: ErrorMetadata(
+                    error=error_data,
+                    stack_trace=stack_trace,
+                    context=self.context or None,
+                ).model_dump(mode="json")
+            }
+        )
+
+    def message(
+        self,
+        error: BaseException,
+    ) -> AgentMessage:
+        """
+        Create an AgentMessage with error metadata and serialized text representation.
+
+        Args:
+            error: The exception to include in the message
+
+        Returns:
+            AgentMessage with error metadata and markdown-formatted text
+        """
+        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```")
+
+            if error_metadata.stack_trace:
+                text_lines.append(f"## Stack Trace\n```\n{error_metadata.stack_trace}\n```")
+
+            text = "\n\n".join(text_lines)
+
+            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: JsonValue = 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/form_request.py

@@ -0,0 +1,52 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar, cast
+
+from a2a.server.agent_execution.context import RequestContext
+from a2a.types import Message as A2AMessage
+from pydantic import TypeAdapter
+from typing_extensions import override
+
+from agentstack_sdk.a2a.extensions.base import (
+    BaseExtensionClient,
+    BaseExtensionServer,
+    NoParamsBaseExtensionSpec,
+)
+from agentstack_sdk.a2a.extensions.common.form import FormRender, FormResponse
+from agentstack_sdk.a2a.types import AgentMessage, InputRequired
+
+if TYPE_CHECKING:
+    from agentstack_sdk.server.context import RunContext
+
+T = TypeVar("T")
+
+
+class FormRequestExtensionSpec(NoParamsBaseExtensionSpec):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/ui/form_request/v1"
+
+
+class FormRequestExtensionServer(BaseExtensionServer[FormRequestExtensionSpec, FormResponse]):
+    @override
+    def handle_incoming_message(self, message: A2AMessage, run_context: RunContext, request_context: RequestContext):
+        super().handle_incoming_message(message, run_context, request_context)
+        self.context = run_context
+
+    async def request_form(self, *, form: FormRender, model: type[T] = FormResponse) -> T | None:
+        message = await self.context.yield_async(
+            InputRequired(message=AgentMessage(text=form.title, metadata={self.spec.URI: form}))
+        )
+        return self.parse_form_response(message=message, model=model) if message else None
+
+    def parse_form_response(self, *, message: A2AMessage, model: type[T] = FormResponse) -> T | None:
+        form_response = self.parse_client_metadata(message)
+        if form_response is None:
+            return None
+        if model is FormResponse:
+            return cast(T, form_response)
+        return TypeAdapter(model).validate_python(dict(form_response))
+
+
+class FormRequestExtensionClient(BaseExtensionClient[FormRequestExtensionSpec, FormRender]): ...

agentstack_sdk/a2a/extensions/ui/settings.py

@@ -0,0 +1,73 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+from agentstack_sdk.a2a.extensions.base import BaseExtensionClient, BaseExtensionServer, BaseExtensionSpec
+
+
+class CheckboxField(BaseModel):
+    id: str
+    label: str
+    default_value: bool = False
+
+
+class CheckboxGroupField(BaseModel):
+    id: str
+    type: Literal["checkbox_group"] = "checkbox_group"
+    fields: list[CheckboxField]
+
+
+class OptionItem(BaseModel):
+    label: str
+    value: str
+
+
+class SingleSelectField(BaseModel):
+    type: Literal["single_select"] = "single_select"
+    id: str
+    label: str
+    options: list[OptionItem]
+    default_value: str
+
+
+class SettingsRender(BaseModel):
+    fields: list[CheckboxGroupField | SingleSelectField]
+
+
+class CheckboxFieldValue(BaseModel):
+    value: bool | None = None
+
+
+class CheckboxGroupFieldValue(BaseModel):
+    type: Literal["checkbox_group"] = "checkbox_group"
+    values: dict[str, CheckboxFieldValue]
+
+
+class SingleSelectFieldValue(BaseModel):
+    type: Literal["single_select"] = "single_select"
+    value: str | None = None
+
+
+SettingsFieldValue = CheckboxGroupFieldValue | SingleSelectFieldValue
+
+
+class AgentRunSettings(BaseModel):
+    values: dict[str, SettingsFieldValue]
+
+
+class SettingsExtensionSpec(BaseExtensionSpec[SettingsRender | None]):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/ui/settings/v1"
+
+
+class SettingsExtensionServer(BaseExtensionServer[SettingsExtensionSpec, AgentRunSettings]):
+    def parse_settings_response(self) -> AgentRunSettings:
+        return AgentRunSettings.model_validate(self._metadata_from_client)
+
+
+class SettingsExtensionClient(BaseExtensionClient[SettingsExtensionSpec, SettingsRender]): ...

agentstack_sdk/a2a/extensions/ui/trajectory.py

@@ -0,0 +1,70 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from types import NoneType
+
+import pydantic
+from a2a.types import DataPart, FilePart, Part, TextPart
+
+from agentstack_sdk.a2a.extensions.base import (
+    BaseExtensionClient,
+    BaseExtensionServer,
+    NoParamsBaseExtensionSpec,
+)
+from agentstack_sdk.a2a.types import AgentMessage, Metadata
+
+
+class Trajectory(pydantic.BaseModel):
+    """
+    Represents trajectory information for an agent's reasoning or tool execution
+    steps. Helps track the agent's decision-making process and provides
+    transparency into how the agent arrived at its response.
+
+    Trajectory can capture intermediate steps like:
+    - A reasoning step with a message
+    - A tool execution with tool name, input, and output
+
+    This information can be used for debugging, audit trails, and providing
+    users with insight into the agent's thought process.
+
+    Visually, this may appear as an accordion component in the UI.
+
+    Properties:
+    - title: Title of the trajectory update.
+    - content: Markdown-formatted content of the trajectory update.
+    """
+
+    title: str | None = None
+    content: str | None = None
+    group_id: str | None = None
+
+
+class TrajectoryExtensionSpec(NoParamsBaseExtensionSpec):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/ui/trajectory/v1"
+
+
+class TrajectoryExtensionServer(BaseExtensionServer[TrajectoryExtensionSpec, NoneType]):
+    def trajectory_metadata(
+        self, *, title: str | None = None, content: str | None = None, group_id: str | None = None
+    ) -> Metadata:
+        return Metadata(
+            {self.spec.URI: Trajectory(title=title, content=content, group_id=group_id).model_dump(mode="json")}
+        )
+
+    def message(
+        self,
+        text: str | None = None,
+        parts: list[Part | TextPart | FilePart | DataPart] | None = None,
+        trajectory_title: str | None = None,
+        trajectory_content: str | None = None,
+    ) -> AgentMessage:
+        return AgentMessage(
+            text=text,
+            parts=parts or [],
+            metadata=self.trajectory_metadata(title=trajectory_title, content=trajectory_content),
+        )
+
+
+class TrajectoryExtensionClient(BaseExtensionClient[TrajectoryExtensionSpec, Trajectory]): ...

agentstack_sdk/a2a/types.py

@@ -0,0 +1,104 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+import uuid
+from typing import Literal, TypeAlias
+
+from a2a.types import (
+    Artifact,
+    DataPart,
+    FilePart,
+    FileWithBytes,
+    FileWithUri,
+    Message,
+    Part,
+    Role,
+    TaskArtifactUpdateEvent,
+    TaskState,
+    TaskStatus,
+    TaskStatusUpdateEvent,
+    TextPart,
+)
+from pydantic import Field, model_validator
+
+from agentstack_sdk.types import JsonDict, JsonValue
+
+
+class Metadata(dict[str, JsonValue]): ...
+
+
+RunYield: TypeAlias = (
+    Message  # includes AgentMessage (subclass)
+    | Part
+    | TaskStatus  # includes InputRequired and AuthRequired (subclasses)
+    | Artifact
+    | TextPart
+    | FilePart
+    | FileWithBytes
+    | FileWithUri
+    | Metadata
+    | DataPart
+    | TaskStatusUpdateEvent
+    | TaskArtifactUpdateEvent
+    | str
+    | JsonDict
+    | Exception
+)
+RunYieldResume: TypeAlias = Message | None
+
+
+class AgentArtifact(Artifact):
+    artifact_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    parts: list[Part | TextPart | FilePart | DataPart]
+
+    @model_validator(mode="after")
+    def text_message_validate(self):
+        self.parts = [part if isinstance(part, Part) else Part(root=part) for part in self.parts]  # pyright: ignore [reportIncompatibleVariableOverride]
+        return self
+
+
+class ArtifactChunk(Artifact):
+    last_chunk: bool = False
+    parts: list[Part | TextPart | FilePart | DataPart]
+
+    @model_validator(mode="after")
+    def text_message_validate(self):
+        self.parts = [part if isinstance(part, Part) else Part(root=part) for part in self.parts]  # pyright: ignore [reportIncompatibleVariableOverride]
+        return self
+
+
+class AgentMessage(Message):
+    message_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    role: Literal[Role.agent] = Role.agent  # pyright: ignore [reportIncompatibleVariableOverride]
+    text: str | None = Field(default=None, exclude=True)
+    parts: list[Part | TextPart | FilePart | DataPart] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def text_message_validate(self):
+        self.parts = [part if isinstance(part, Part) else Part(root=part) for part in self.parts]  # pyright: ignore [reportIncompatibleVariableOverride]
+        if self.parts and self.text is not None:
+            raise ValueError("Message cannot have both parts and text")
+        if self.text is not None:
+            self.parts.append(Part(root=TextPart(text=self.text)))
+        return self
+
+
+class InputRequired(TaskStatus):
+    message: Message | None = None
+    state: Literal[TaskState.input_required] = TaskState.input_required  # pyright: ignore [reportIncompatibleVariableOverride]
+    text: str | None = Field(default=None, exclude=True)
+    parts: list[Part | TextPart | DataPart | FilePart] = Field(exclude=True, default_factory=list)
+
+    @model_validator(mode="after")
+    def text_message_validate(self):
+        self.parts = [part if isinstance(part, Part) else Part(root=part) for part in self.parts]
+        if sum((self.message is not None, self.text is not None, bool(self.parts))) != 1:
+            raise ValueError("At most one of message, text, or parts must be provided.")
+        if self.text is not None:
+            self.message = AgentMessage(text=self.text)
+        elif self.parts:
+            self.message = AgentMessage(parts=self.parts)
+        return self
+
+
+class AuthRequired(InputRequired):
+    state: Literal[TaskState.auth_required] = TaskState.auth_required  # pyright: ignore [reportIncompatibleVariableOverride]

agentstack_sdk/platform/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from .client import *
+from .configuration import *
+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/client.py

@@ -0,0 +1,123 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+import asyncio
+import contextlib
+import os
+import ssl
+import typing
+from collections.abc import AsyncIterator, Mapping
+from types import TracebackType
+
+import httpx
+from httpx import URL, AsyncBaseTransport
+from httpx._client import EventHook
+from httpx._config import DEFAULT_LIMITS, DEFAULT_MAX_REDIRECTS, Limits
+from httpx._types import AuthTypes, CertTypes, CookieTypes, HeaderTypes, ProxyTypes, QueryParamTypes, TimeoutTypes
+from pydantic import Secret
+from typing_extensions import override
+
+from agentstack_sdk.util import resource_context
+
+DEFAULT_SDK_TIMEOUT: typing.Final = httpx.Timeout(timeout=30, read=None)
+
+
+class PlatformClient(httpx.AsyncClient):
+    context_id: str | None = None
+
+    def __init__(
+        self,
+        context_id: str | None = None,  # Enter context scope
+        auth_token: str | Secret[str] | None = None,
+        *,
+        auth: AuthTypes | None = None,
+        params: QueryParamTypes | None = None,
+        headers: HeaderTypes | None = None,
+        cookies: CookieTypes | None = None,
+        verify: ssl.SSLContext | str | bool = True,
+        cert: CertTypes | None = None,
+        http1: bool = True,
+        http2: bool = False,
+        proxy: ProxyTypes | None = None,
+        mounts: None | (Mapping[str, AsyncBaseTransport | None]) = None,
+        timeout: TimeoutTypes = DEFAULT_SDK_TIMEOUT,
+        follow_redirects: bool = False,
+        limits: Limits = DEFAULT_LIMITS,
+        max_redirects: int = DEFAULT_MAX_REDIRECTS,
+        event_hooks: None | (Mapping[str, list[EventHook]]) = None,
+        base_url: URL | str = "",
+        transport: AsyncBaseTransport | None = None,
+        trust_env: bool = True,
+        default_encoding: str | typing.Callable[[bytes], str] = "utf-8",
+    ) -> None:
+        if not base_url:
+            base_url = os.environ.get("PLATFORM_URL", "http://127.0.0.1:8333")
+        super().__init__(
+            auth=auth,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            verify=verify,
+            cert=cert,
+            http1=http1,
+            http2=http2,
+            proxy=proxy,
+            mounts=mounts,
+            timeout=timeout,
+            follow_redirects=follow_redirects,
+            limits=limits,
+            max_redirects=max_redirects,
+            event_hooks=event_hooks,
+            base_url=base_url,
+            transport=transport,
+            trust_env=trust_env,
+            default_encoding=default_encoding,
+        )
+        self.context_id = context_id
+        if auth_token:
+            self.headers["Authorization"] = f"Bearer {auth_token}"
+        self._ref_count: int = 0
+        self._context_manager_lock: asyncio.Lock = asyncio.Lock()
+
+    @override
+    async def __aenter__(self) -> typing.Self:
+        async with self._context_manager_lock:
+            self._ref_count += 1
+            if self._ref_count == 1:
+                _ = await super().__aenter__()
+            return self
+
+    @override
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: TracebackType | None = None,
+    ) -> None:
+        async with self._context_manager_lock:
+            self._ref_count -= 1
+            if self._ref_count == 0:
+                await super().__aexit__(exc_type, exc_value, traceback)
+
+
+get_platform_client, set_platform_client = resource_context(factory=PlatformClient, default_factory=PlatformClient)
+
+P = typing.ParamSpec("P")
+T = typing.TypeVar("T", bound=PlatformClient)
+
+
+def wrap_context(
+    context: typing.Callable[P, contextlib.AbstractContextManager[T]],
+) -> typing.Callable[P, contextlib.AbstractAsyncContextManager[T]]:
+    @contextlib.asynccontextmanager
+    async def use_async_resource(*args: P.args, **kwargs: P.kwargs) -> AsyncIterator[T]:
+        with context(*args, **kwargs) as resource:
+            async with resource:
+                yield resource
+
+    return use_async_resource
+
+
+use_platform_client = wrap_context(set_platform_client)
+
+
+__all__ = ["PlatformClient", "get_platform_client", "set_platform_client", "use_platform_client"]

agentstack_sdk/platform/common.py

@@ -0,0 +1,37 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+from enum import StrEnum
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PaginatedResult(BaseModel, Generic[T]):
+    items: list[T]
+    total_count: int
+    has_more: bool = False
+    next_page_token: str | None = None
+
+
+class GithubVersionType(StrEnum):
+    HEAD = "head"
+    TAG = "tag"
+
+
+class ResolvedGithubUrl(BaseModel):
+    host: str = "github.com"
+    org: str
+    repo: str
+    version: str
+    version_type: GithubVersionType
+    commit_hash: str
+    path: str | None = None
+
+
+class ResolvedDockerImageID(BaseModel):
+    registry: str
+    repository: str
+    tag: str
+    digest: str