agentstack-sdk 0.4.3rc3__tar.gz → 0.5.0rc4__tar.gz

agentstack_sdk-0.5.0rc4/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.3
+Name: agentstack-sdk
+Version: 0.5.0rc4
+Summary: Agent Stack SDK
+Author: IBM Corp.
+Requires-Dist: a2a-sdk==0.3.21
+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 Server SDK
+
+Python SDK for packaging agents for deployment to Agent Stack infrastructure.
+
+[![PyPI version](https://img.shields.io/pypi/v/agentstack-sdk.svg?style=plastic)](https://pypi.org/project/agentstack-sdk/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=plastic)](https://opensource.org/licenses/Apache-2.0)
+[![LF AI & Data](https://img.shields.io/badge/LF%20AI%20%26%20Data-0072C6?style=plastic&logo=linuxfoundation&logoColor=white)](https://lfaidata.foundation/projects/)
+
+## Overview
+
+The `agentstack-sdk` provides Python utilities for wrapping agents built with any framework (LangChain, CrewAI, BeeAI Framework, etc.) for deployment on Agent Stack. It handles the A2A (Agent-to-Agent) protocol implementation, platform service integration, and runtime requirements so you can focus on agent logic.
+
+## Key Features
+
+- **Framework-Agnostic Deployment** - Wrap agents from any framework for Agent Stack deployment
+- **A2A Protocol Support** - Automatic handling of Agent-to-Agent communication
+- **Platform Service Integration** - Connect to Agent Stack's managed LLM, embedding, file storage, and vector store services
+- **Context Storage** - Manage data associated with conversation contexts
+
+## Installation
+
+```bash
+uv add agentstack-sdk
+```
+
+## Quickstart
+
+```python
+import os
+
+from a2a.types import (
+    Message,
+)
+from a2a.utils.message import get_message_text
+from agentstack_sdk.server import Server
+from agentstack_sdk.server.context import RunContext
+from agentstack_sdk.a2a.types import AgentMessage
+
+server = Server()
+
+@server.agent()
+async def example_agent(input: Message, context: RunContext):
+    """Polite agent that greets the user"""
+    hello_template: str = os.getenv("HELLO_TEMPLATE", "Ciao %s!")
+    yield AgentMessage(text=hello_template % get_message_text(input))
+
+def run():
+    try:
+        server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    run()
+```
+
+Run the agent:
+
+```bash
+uv run my_agent.py
+```
+
+## Available Extensions
+
+The SDK includes extension support for:
+
+- **Citations** - Source attribution (`CitationExtensionServer`, `CitationExtensionSpec`)
+- **Trajectory** - Agent decision logging (`TrajectoryExtensionServer`, `TrajectoryExtensionSpec`)
+- **Settings** - User-configurable agent parameters (`SettingsExtensionServer`, `SettingsExtensionSpec`)
+- **LLM Services** - Platform-managed language models (`LLMServiceExtensionServer`, `LLMServiceExtensionSpec`)
+- **Agent Details** - Metadata and UI enhancements (`AgentDetail`)
+- **And more** - See [Documentation](https://agentstack.beeai.dev/stable/agent-development/overview)
+
+Each extension provides both server-side handlers and A2A protocol specifications for seamless integration with Agent Stack's UI and infrastructure.
+
+## Resources
+
+- [Agent Stack Documentation](https://agentstack.beeai.dev)
+- [GitHub Repository](https://github.com/i-am-bee/agentstack)
+- [PyPI Package](https://pypi.org/project/agentstack-sdk/)
+
+## Contributing
+
+Contributions are welcome! Please see the [Contributing Guide](https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md) for details.
+
+## Support
+
+- [GitHub Issues](https://github.com/i-am-bee/agentstack/issues)
+- [GitHub Discussions](https://github.com/i-am-bee/agentstack/discussions)
+
+---
+
+Developed by contributors to the BeeAI project, this initiative is part of the [Linux Foundation AI & Data program](https://lfaidata.foundation/projects/). Its development follows open, collaborative, and community-driven practices.

agentstack_sdk-0.5.0rc4/README.md

@@ -0,0 +1,94 @@
+# Agent Stack Server SDK
+
+Python SDK for packaging agents for deployment to Agent Stack infrastructure.
+
+[![PyPI version](https://img.shields.io/pypi/v/agentstack-sdk.svg?style=plastic)](https://pypi.org/project/agentstack-sdk/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=plastic)](https://opensource.org/licenses/Apache-2.0)
+[![LF AI & Data](https://img.shields.io/badge/LF%20AI%20%26%20Data-0072C6?style=plastic&logo=linuxfoundation&logoColor=white)](https://lfaidata.foundation/projects/)
+
+## Overview
+
+The `agentstack-sdk` provides Python utilities for wrapping agents built with any framework (LangChain, CrewAI, BeeAI Framework, etc.) for deployment on Agent Stack. It handles the A2A (Agent-to-Agent) protocol implementation, platform service integration, and runtime requirements so you can focus on agent logic.
+
+## Key Features
+
+- **Framework-Agnostic Deployment** - Wrap agents from any framework for Agent Stack deployment
+- **A2A Protocol Support** - Automatic handling of Agent-to-Agent communication
+- **Platform Service Integration** - Connect to Agent Stack's managed LLM, embedding, file storage, and vector store services
+- **Context Storage** - Manage data associated with conversation contexts
+
+## Installation
+
+```bash
+uv add agentstack-sdk
+```
+
+## Quickstart
+
+```python
+import os
+
+from a2a.types import (
+    Message,
+)
+from a2a.utils.message import get_message_text
+from agentstack_sdk.server import Server
+from agentstack_sdk.server.context import RunContext
+from agentstack_sdk.a2a.types import AgentMessage
+
+server = Server()
+
+@server.agent()
+async def example_agent(input: Message, context: RunContext):
+    """Polite agent that greets the user"""
+    hello_template: str = os.getenv("HELLO_TEMPLATE", "Ciao %s!")
+    yield AgentMessage(text=hello_template % get_message_text(input))
+
+def run():
+    try:
+        server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    run()
+```
+
+Run the agent:
+
+```bash
+uv run my_agent.py
+```
+
+## Available Extensions
+
+The SDK includes extension support for:
+
+- **Citations** - Source attribution (`CitationExtensionServer`, `CitationExtensionSpec`)
+- **Trajectory** - Agent decision logging (`TrajectoryExtensionServer`, `TrajectoryExtensionSpec`)
+- **Settings** - User-configurable agent parameters (`SettingsExtensionServer`, `SettingsExtensionSpec`)
+- **LLM Services** - Platform-managed language models (`LLMServiceExtensionServer`, `LLMServiceExtensionSpec`)
+- **Agent Details** - Metadata and UI enhancements (`AgentDetail`)
+- **And more** - See [Documentation](https://agentstack.beeai.dev/stable/agent-development/overview)
+
+Each extension provides both server-side handlers and A2A protocol specifications for seamless integration with Agent Stack's UI and infrastructure.
+
+## Resources
+
+- [Agent Stack Documentation](https://agentstack.beeai.dev)
+- [GitHub Repository](https://github.com/i-am-bee/agentstack)
+- [PyPI Package](https://pypi.org/project/agentstack-sdk/)
+
+## Contributing
+
+Contributions are welcome! Please see the [Contributing Guide](https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md) for details.
+
+## Support
+
+- [GitHub Issues](https://github.com/i-am-bee/agentstack/issues)
+- [GitHub Discussions](https://github.com/i-am-bee/agentstack/discussions)
+
+---
+
+Developed by contributors to the BeeAI project, this initiative is part of the [Linux Foundation AI & Data program](https://lfaidata.foundation/projects/). Its development follows open, collaborative, and community-driven practices.

{agentstack_sdk-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "agentstack-sdk"
-version = "0.4.3-rc3"
+version = "0.5.0-rc4"
 description = "Agent Stack SDK"
 readme = "README.md"
 authors = [{ name = "IBM Corp." }]
 requires-python = ">=3.11,<3.14"
 dependencies = [
-    "a2a-sdk==0.3.9",
+    "a2a-sdk==0.3.21",
     "objprint>=0.3.0",
     "uvicorn>=0.35.0",
     "asyncclick>=8.1.8",

{agentstack_sdk-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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-0.4.3rc3 → agentstack_sdk-0.5.0rc4}/src/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()