agentstack-sdk 0.5.2rc2__py3-none-any.whl

agentstack_sdk/platform/configuration.py

@@ -0,0 +1,47 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import pydantic
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+
+
+class SystemConfiguration(pydantic.BaseModel):
+    id: str
+    default_llm_model: str | None = None
+    default_embedding_model: str | None = None
+    updated_at: pydantic.AwareDatetime
+    created_by: str
+
+    @staticmethod
+    async def get(*, client: PlatformClient | None = None) -> SystemConfiguration:
+        """Get the current system configuration."""
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(SystemConfiguration).validate_python(
+                (await client.get(url="/api/v1/configurations/system")).raise_for_status().json()
+            )
+
+    @staticmethod
+    async def update(
+        *,
+        default_llm_model: str | None = None,
+        default_embedding_model: str | None = None,
+        client: PlatformClient | None = None,
+    ) -> SystemConfiguration:
+        """Update the system configuration."""
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(SystemConfiguration).validate_python(
+                (
+                    await client.put(
+                        url="/api/v1/configurations/system",
+                        json={
+                            "default_llm_model": default_llm_model,
+                            "default_embedding_model": default_embedding_model,
+                        },
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )

agentstack_sdk/platform/context.py

@@ -0,0 +1,291 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Literal
+from uuid import UUID, uuid4
+
+import pydantic
+from a2a.types import Artifact, Message
+from pydantic import AwareDatetime, BaseModel, Field, SerializeAsAny, computed_field
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+from agentstack_sdk.platform.common import PaginatedResult
+from agentstack_sdk.platform.provider import Provider
+from agentstack_sdk.platform.types import Metadata, MetadataPatch
+from agentstack_sdk.util.utils import filter_dict, utc_now
+
+
+class ContextHistoryItem(BaseModel):
+    id: UUID = Field(default_factory=uuid4)
+    data: Artifact | Message
+    created_at: AwareDatetime = Field(default_factory=utc_now)
+    context_id: str
+
+    @computed_field
+    @property
+    def kind(self) -> Literal["message", "artifact"]:
+        return getattr(self.data, "kind", "artifact")
+
+
+class ContextToken(pydantic.BaseModel):
+    context_id: str
+    token: pydantic.Secret[str]
+    expires_at: pydantic.AwareDatetime | None = None
+
+
+class ContextPermissions(pydantic.BaseModel):
+    files: set[Literal["read", "write", "extract", "*"]] = set()
+    vector_stores: set[Literal["read", "write", "*"]] = set()
+    context_data: set[Literal["read", "write", "*"]] = set()
+
+
+class Permissions(ContextPermissions):
+    llm: set[Literal["*"] | str] = set()
+    embeddings: set[Literal["*"] | str] = set()
+    a2a_proxy: set[Literal["*"] | str] = set()
+    model_providers: set[Literal["read", "write", "*"]] = set()
+    variables: SerializeAsAny[set[Literal["read", "write", "*"]]] = set()
+
+    providers: set[Literal["read", "write", "*"]] = set()  # write includes "show logs" permission
+    provider_variables: set[Literal["read", "write", "*"]] = set()
+
+    contexts: set[Literal["read", "write", "*"]] = set()
+
+    connectors: set[Literal["read", "write", "proxy", "*"]] = set()
+
+
+class Context(pydantic.BaseModel):
+    id: str
+    created_at: pydantic.AwareDatetime
+    updated_at: pydantic.AwareDatetime
+    last_active_at: pydantic.AwareDatetime
+    created_by: str
+    provider_id: str | None = None
+    metadata: Metadata | None = None
+
+    @staticmethod
+    async def create(
+        *,
+        metadata: Metadata | None = None,
+        provider_id: str | None = None,
+        client: PlatformClient | None = None,
+    ) -> Context:
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(Context).validate_python(
+                (
+                    await client.post(
+                        url="/api/v1/contexts",
+                        json=filter_dict({"metadata": metadata, "provider_id": provider_id}),
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    @staticmethod
+    async def list(
+        *,
+        client: PlatformClient | None = None,
+        page_token: str | None = None,
+        limit: int | None = None,
+        order: Literal["asc"] | Literal["desc"] | None = None,
+        order_by: Literal["created_at"] | Literal["updated_at"] | None = None,
+        include_empty: bool = True,
+        provider_id: str | None = None,
+    ) -> PaginatedResult[Context]:
+        # `self` has a weird type so that you can call both `instance.get()` to update an instance, or `File.get("123")` to obtain a new instance
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(PaginatedResult[Context]).validate_python(
+                (
+                    await client.get(
+                        url="/api/v1/contexts",
+                        params=filter_dict(
+                            {
+                                "page_token": page_token,
+                                "limit": limit,
+                                "order": order,
+                                "order_by": order_by,
+                                "include_empty": include_empty,
+                                "provider_id": provider_id,
+                            }
+                        ),
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def get(
+        self: Context | str,
+        *,
+        client: PlatformClient | None = None,
+    ) -> Context:
+        # `self` has a weird type so that you can call both `instance.get()` to update an instance, or `File.get("123")` to obtain a new instance
+        context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(Context).validate_python(
+                (await client.get(url=f"/api/v1/contexts/{context_id}")).raise_for_status().json()
+            )
+
+    async def update(
+        self: Context | str,
+        *,
+        metadata: Metadata | None,
+        client: PlatformClient | None = None,
+    ) -> Context:
+        # `self` has a weird type so that you can call both `instance.get()` to update an instance, or `File.get("123")` to obtain a new instance
+        context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            result = pydantic.TypeAdapter(Context).validate_python(
+                (await client.put(url=f"/api/v1/contexts/{context_id}", json={"metadata": metadata}))
+                .raise_for_status()
+                .json()
+            )
+        if isinstance(self, Context):
+            self.__dict__.update(result.__dict__)
+            return self
+        return result
+
+    async def patch_metadata(
+        self: Context | str,
+        *,
+        metadata: MetadataPatch | None,
+        client: PlatformClient | None = None,
+    ) -> Context:
+        # `self` has a weird type so that you can call both `instance.get()` to update an instance, or `File.get("123")` to obtain a new instance
+        context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            result = pydantic.TypeAdapter(Context).validate_python(
+                (await client.patch(url=f"/api/v1/contexts/{context_id}/metadata", json={"metadata": metadata}))
+                .raise_for_status()
+                .json()
+            )
+        if isinstance(self, Context):
+            self.__dict__.update(result.__dict__)
+            return self
+        return result
+
+    async def delete(
+        self: Context | str,
+        *,
+        client: PlatformClient | None = None,
+    ) -> None:
+        # `self` has a weird type so that you can call both `instance.delete()` or `File.delete("123")`
+        context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            _ = (await client.delete(url=f"/api/v1/contexts/{context_id}")).raise_for_status()
+
+    async def generate_token(
+        self: Context | str,
+        *,
+        providers: list[str] | list[Provider] | None = None,
+        client: PlatformClient | None = None,
+        grant_global_permissions: Permissions | None = None,
+        grant_context_permissions: ContextPermissions | None = None,
+    ) -> ContextToken:
+        """
+        Generate token for agent authentication
+
+        @param grant_global_permissions: Global permissions granted by the token. Must be subset of the users permissions
+        @param grant_context_permissions: Context permissions granted by the token. Must be subset of the users permissions
+        """
+        # `self` has a weird type so that you can call both `instance.content()` to get content of an instance, or `File.content("123")`
+        context_id = self if isinstance(self, str) else self.id
+        grant_global_permissions = grant_global_permissions or Permissions()
+        grant_context_permissions = grant_context_permissions or Permissions()
+
+        if isinstance(self, Context) and self.metadata and (provider_id := self.metadata.get("provider_id", None)):
+            providers = providers or [provider_id]
+
+        if "*" not in grant_global_permissions.a2a_proxy and not grant_global_permissions.a2a_proxy:
+            if not providers:
+                raise ValueError(
+                    "Invalid audience: You must specify providers or use '*' in grant_global_permissions.a2a_proxy."
+                )
+
+            grant_global_permissions.a2a_proxy |= {p.id if isinstance(p, Provider) else p for p in providers}
+
+        async with client or get_platform_client() as client:
+            token_response = (
+                (
+                    await client.post(
+                        url=f"/api/v1/contexts/{context_id}/token",
+                        json={
+                            "grant_global_permissions": grant_global_permissions.model_dump(mode="json"),
+                            "grant_context_permissions": grant_context_permissions.model_dump(mode="json"),
+                        },
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+        return pydantic.TypeAdapter(ContextToken).validate_python({**token_response, "context_id": context_id})
+
+    async def add_history_item(
+        self: Context | str,
+        *,
+        data: Message | Artifact,
+        client: PlatformClient | None = None,
+    ) -> None:
+        """Add a Message or Artifact to the context history (append-only)"""
+        target_context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as platform_client:
+            _ = (
+                await platform_client.post(
+                    url=f"/api/v1/contexts/{target_context_id}/history", json=data.model_dump(mode="json")
+                )
+            ).raise_for_status()
+
+    async def delete_history_from_id(
+        self: Context | str,
+        *,
+        from_id: UUID | str,
+        client: PlatformClient | None = None,
+    ) -> None:
+        """Delete all history items from a specific item onwards (inclusive)"""
+        target_context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as platform_client:
+            _ = (
+                await platform_client.delete(
+                    url=f"/api/v1/contexts/{target_context_id}/history", params={"from_id": str(from_id)}
+                )
+            ).raise_for_status()
+
+    async def list_history(
+        self: Context | str,
+        *,
+        page_token: str | None = None,
+        limit: int | None = None,
+        order: Literal["asc"] | Literal["desc"] | None = "asc",
+        order_by: Literal["created_at"] | Literal["updated_at"] | None = None,
+        client: PlatformClient | None = None,
+    ) -> PaginatedResult[ContextHistoryItem]:
+        """List all history items for this context in chronological order"""
+        target_context_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as platform_client:
+            return pydantic.TypeAdapter(PaginatedResult[ContextHistoryItem]).validate_python(
+                (
+                    await platform_client.get(
+                        url=f"/api/v1/contexts/{target_context_id}/history",
+                        params=filter_dict(
+                            {"page_token": page_token, "limit": limit, "order": order, "order_by": order_by}
+                        ),
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def list_all_history(
+        self: Context | str, client: PlatformClient | None = None
+    ) -> AsyncIterator[ContextHistoryItem]:
+        result = await Context.list_history(self, client=client)
+        for item in result.items:
+            yield item
+        while result.has_more:
+            result = await Context.list_history(self, page_token=result.next_page_token, client=client)
+            for item in result.items:
+                yield item

agentstack_sdk/platform/file.py

@@ -0,0 +1,295 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Literal
+
+import pydantic
+from a2a.types import FilePart, FileWithUri
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+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_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
+    extraction_metadata: dict[str, typing.Any] | None = None
+    started_at: pydantic.AwareDatetime | None = None
+    finished_at: pydantic.AwareDatetime | None = None
+    created_at: pydantic.AwareDatetime
+
+
+class File(pydantic.BaseModel):
+    id: str
+    filename: str
+    content_type: str
+    file_size_bytes: int
+    created_at: pydantic.AwareDatetime
+    created_by: str
+    file_type: typing.Literal["user_upload", "extracted_text"]
+    parent_file_id: str | None = None
+
+    @property
+    def url(self) -> PlatformFileUrl:
+        return PlatformFileUrl(f"agentstack://{self.id}")
+
+    @staticmethod
+    async def create(
+        *,
+        filename: str,
+        content: typing.BinaryIO | bytes,
+        content_type: str = "application/octet-stream",
+        client: PlatformClient | None = None,
+        context_id: str | None | Literal["auto"] = "auto",
+    ) -> File:
+        async with client or get_platform_client() as platform_client:
+            context_id = platform_client.context_id if context_id == "auto" else context_id
+            return pydantic.TypeAdapter(File).validate_python(
+                (
+                    await platform_client.post(
+                        url="/api/v1/files",
+                        files={"file": (filename, content, content_type)},
+                        params=context_id and {"context_id": context_id},
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def get(
+        self: File | str,
+        *,
+        client: PlatformClient | None = None,
+        context_id: str | None | Literal["auto"] = "auto",
+    ) -> File:
+        # `self` has a weird type so that you can call both `instance.get()` to update an instance, or `File.get("123")` to obtain a new instance
+        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
+            return pydantic.TypeAdapter(File).validate_python(
+                (
+                    await platform_client.get(
+                        url=f"/api/v1/files/{file_id}",
+                        params=context_id and {"context_id": context_id},
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def delete(
+        self: File | str,
+        *,
+        client: PlatformClient | None = None,
+        context_id: str | None | Literal["auto"] = "auto",
+    ) -> None:
+        # `self` has a weird type so that you can call both `instance.delete()` or `File.delete("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
+            _ = (
+                await platform_client.delete(
+                    url=f"/api/v1/files/{file_id}", params=context_id and {"context_id": context_id}
+                )
+            ).raise_for_status()
+
+    @asynccontextmanager
+    async def load_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_content()` to create an extraction for an instance, or `File.load_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
+
+            async with platform_client.stream(
+                "GET", url=f"/api/v1/files/{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)
+
+    @asynccontextmanager
+    async def load_text_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_text_content()` to create an extraction for an instance, or `File.load_text_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
+
+            async with platform_client.stream(
+                "GET",
+                url=f"/api/v1/files/{file_id}/text_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)
+
+    @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:
+        # `self` has a weird type so that you can call both `instance.create_extraction()` to create an extraction for an instance, or `File.create_extraction("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
+            return pydantic.TypeAdapter(Extraction).validate_python(
+                (
+                    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()
+                .json()
+            )
+
+    async def get_extraction(
+        self: File | str,
+        *,
+        client: PlatformClient | None = None,
+        context_id: str | None | Literal["auto"] = "auto",
+    ) -> Extraction:
+        # `self` has a weird type so that you can call both `instance.get_extraction()` to get an extraction of an instance, or `File.get_extraction("123", "456")`
+        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
+            return pydantic.TypeAdapter(Extraction).validate_python(
+                (
+                    await platform_client.get(
+                        url=f"/api/v1/files/{file_id}/extraction",
+                        params=context_id and {"context_id": context_id},
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def delete_extraction(
+        self: File | str,
+        *,
+        client: PlatformClient | None = None,
+        context_id: str | None | Literal["auto"] = "auto",
+    ) -> None:
+        # `self` has a weird type so that you can call both `instance.delete_extraction()` or `File.delete_extraction("123", "456")`
+        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
+            _ = (
+                await platform_client.delete(
+                    url=f"/api/v1/files/{file_id}/extraction",
+                    params=context_id and {"context_id": context_id},
+                )
+            ).raise_for_status()
+
+    def to_file_part(self: File) -> FilePart:
+        return FilePart(file=FileWithUri(name=self.filename, uri=f"agentstack://{self.id}"))
+
+    @staticmethod
+    async def list(
+        *,
+        content_type: str | None = None,
+        filename_search: str | None = None,
+        page_token: str | None = None,
+        limit: int | None = None,
+        order: Literal["asc"] | Literal["desc"] | None = "asc",
+        order_by: Literal["created_at"] | Literal["filename"] | Literal["file_size_bytes"] | None = None,
+        client: PlatformClient | None = None,
+        context_id: str | None | Literal["auto"] = "auto",
+    ) -> PaginatedResult[File]:
+        # `self` has a weird type so that you can call both `instance.list_history()` or `ProviderBuild.list_history("123")`
+        async with client or get_platform_client() as platform_client:
+            context_id = platform_client.context_id if context_id == "auto" else context_id
+            return pydantic.TypeAdapter(PaginatedResult[File]).validate_python(
+                (
+                    await platform_client.get(
+                        url="/api/v1/files",
+                        params=filter_dict(
+                            {
+                                "context_id": context_id,
+                                "content_type": content_type,
+                                "filename_search": filename_search,
+                                "page_token": page_token,
+                                "limit": limit,
+                                "order": order,
+                                "order_by": order_by,
+                            }
+                        ),
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )