agentstack-sdk 0.5.2rc2__py3-none-any.whl

agentstack_sdk/platform/model_provider.py

@@ -0,0 +1,131 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+import pydantic
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+
+
+class ModelProviderType(StrEnum):
+    ANTHROPIC = "anthropic"
+    CEREBRAS = "cerebras"
+    CHUTES = "chutes"
+    COHERE = "cohere"
+    DEEPSEEK = "deepseek"
+    GEMINI = "gemini"
+    GITHUB = "github"
+    GROQ = "groq"
+    WATSONX = "watsonx"
+    JAN = "jan"
+    MISTRAL = "mistral"
+    MOONSHOT = "moonshot"
+    NVIDIA = "nvidia"
+    OLLAMA = "ollama"
+    OPENAI = "openai"
+    OPENROUTER = "openrouter"
+    PERPLEXITY = "perplexity"
+    TOGETHER = "together"
+    VOYAGE = "voyage"
+    RITS = "rits"
+    OTHER = "other"
+
+
+class ModelWithScore(pydantic.BaseModel):
+    model_id: str
+    score: float
+
+
+class ModelCapability(StrEnum):
+    LLM = "llm"
+    EMBEDDING = "embedding"
+
+
+class ModelProvider(pydantic.BaseModel):
+    id: str
+    name: str | None = None
+    description: str | None = None
+    type: ModelProviderType
+    base_url: pydantic.HttpUrl
+    watsonx_project_id: str | None = None
+    watsonx_space_id: str | None = None
+    created_at: pydantic.AwareDatetime
+    capabilities: set[ModelCapability]
+
+    @staticmethod
+    async def create(
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        type: ModelProviderType,
+        base_url: str | pydantic.HttpUrl,
+        watsonx_project_id: str | None = None,
+        watsonx_space_id: str | None = None,
+        api_key: str,
+        client: PlatformClient | None = None,
+    ) -> ModelProvider:
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(ModelProvider).validate_python(
+                (
+                    await client.post(
+                        url="/api/v1/model_providers",
+                        json={
+                            "name": name,
+                            "description": description,
+                            "type": type,
+                            "base_url": str(base_url),
+                            "watsonx_project_id": watsonx_project_id,
+                            "watsonx_space_id": watsonx_space_id,
+                            "api_key": api_key,
+                        },
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def get(self: ModelProvider | str, *, client: PlatformClient | None = None) -> ModelProvider:
+        model_provider_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            result = pydantic.TypeAdapter(ModelProvider).validate_python(
+                (await client.get(url=f"/api/v1/model_providers/{model_provider_id}")).raise_for_status().json()
+            )
+        if isinstance(self, ModelProvider):
+            self.__dict__.update(result.__dict__)
+            return self
+        return result
+
+    async def delete(self: ModelProvider | str, *, client: PlatformClient | None = None) -> None:
+        # `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
+        model_provider_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            _ = (await client.delete(f"/api/v1/model_providers/{model_provider_id}")).raise_for_status()
+
+    @staticmethod
+    async def match(
+        *,
+        capability: ModelCapability = ModelCapability.LLM,
+        suggested_models: tuple[str, ...] | None = None,
+        client: PlatformClient | None = None,
+    ) -> list[ModelWithScore]:
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(list[ModelWithScore]).validate_python(
+                (
+                    await client.post(
+                        "/api/v1/model_providers/match",
+                        json={"suggested_models": suggested_models, "capability": capability},
+                    )
+                )
+                .raise_for_status()
+                .json()["items"]
+            )
+
+    @staticmethod
+    async def list(*, client: PlatformClient | None = None) -> list[ModelProvider]:
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(list[ModelProvider]).validate_python(
+                (await client.get(url="/api/v1/model_providers")).raise_for_status().json()["items"]
+            )

agentstack_sdk/platform/provider.py

@@ -0,0 +1,219 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+
+import typing
+import urllib.parse
+from contextlib import asynccontextmanager
+from datetime import timedelta
+from uuid import UUID
+
+import pydantic
+from a2a.client import ClientConfig, ClientFactory
+from a2a.types import AgentCard
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+from agentstack_sdk.platform.common import ResolvedDockerImageID, ResolvedGithubUrl
+from agentstack_sdk.util.utils import filter_dict, parse_stream
+
+
+class ProviderErrorMessage(pydantic.BaseModel):
+    message: str
+
+
+class EnvVar(pydantic.BaseModel):
+    name: str
+    description: str | None = None
+    required: bool = False
+
+
+class VersionInfo(pydantic.BaseModel):
+    docker: ResolvedDockerImageID | None = None
+    github: ResolvedGithubUrl | None = None
+
+
+class Provider(pydantic.BaseModel):
+    id: str
+    auto_stop_timeout: timedelta
+    source: str
+    origin: str
+    version_info: VersionInfo = pydantic.Field(default_factory=VersionInfo)
+    registry: str | None = None
+    created_at: pydantic.AwareDatetime
+    updated_at: pydantic.AwareDatetime
+    last_active_at: pydantic.AwareDatetime
+    agent_card: AgentCard
+    state: typing.Literal["missing", "starting", "ready", "running", "error", "online", "offline"] = "missing"
+    managed: bool
+    last_error: ProviderErrorMessage | None = None
+    created_by: UUID
+    missing_configuration: list[EnvVar] = pydantic.Field(default_factory=list)
+
+    @staticmethod
+    async def create(
+        *,
+        location: str,
+        agent_card: AgentCard | None = None,
+        origin: str | None = None,
+        auto_stop_timeout: timedelta | None = None,
+        variables: dict[str, str] | None = None,
+        client: PlatformClient | None = None,
+    ) -> "Provider":
+        auto_stop_timeout_sec = auto_stop_timeout.total_seconds() if auto_stop_timeout is not None else None
+
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(Provider).validate_python(
+                (
+                    await client.post(
+                        url="/api/v1/providers",
+                        json=filter_dict(
+                            {
+                                "location": location,
+                                "agent_card": agent_card.model_dump(mode="json") if agent_card else None,
+                                "origin": origin,
+                                "variables": variables,
+                                "auto_stop_timeout_sec": auto_stop_timeout_sec,
+                            }
+                        ),
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def patch(
+        self: "Provider | str",
+        *,
+        location: str | None = None,
+        agent_card: AgentCard | None = None,
+        origin: str | None = None,
+        auto_stop_timeout: timedelta | None = None,
+        variables: dict[str, str] | None = None,
+        client: PlatformClient | None = None,
+    ) -> "Provider":
+        # `self` has a weird type so that you can call both `instance.patch()` to update an instance, or `Provider.patch("123", ...)` to update a provider
+
+        provider_id = self if isinstance(self, str) else self.id
+        payload = filter_dict(
+            {
+                "location": location,
+                "agent_card": agent_card.model_dump(mode="json") if agent_card else None,
+                "variables": variables,
+                "auto_stop_timeout_sec": None if auto_stop_timeout is None else auto_stop_timeout.total_seconds(),
+                "origin": origin,
+            }
+        )
+        if not payload:
+            return await Provider.get(self)
+
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(Provider).validate_python(
+                (await client.patch(url=f"/api/v1/providers/{provider_id}", json=payload)).raise_for_status().json()
+            )
+
+    @asynccontextmanager
+    async def a2a_client(self, client: PlatformClient | None = None):
+        async with client or get_platform_client() as client:
+            yield ClientFactory(ClientConfig(httpx_client=client)).create(card=self.agent_card)
+
+    @staticmethod
+    async def preview(
+        *,
+        location: str,
+        agent_card: AgentCard | None = None,
+        client: PlatformClient | None = None,
+    ) -> "Provider":
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(Provider).validate_python(
+                (
+                    await client.post(
+                        url="/api/v1/providers/preview",
+                        json={
+                            "location": location,
+                            "agent_card": agent_card.model_dump(mode="json") if agent_card else None,
+                        },
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def get(self: "Provider | str", *, client: PlatformClient | None = None) -> "Provider":
+        # `self` has a weird type so that you can call both `instance.get()` to update an instance, or `Provider.get("123")` to obtain a new instance
+        provider_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            result = pydantic.TypeAdapter(Provider).validate_json(
+                (await client.get(url=f"/api/v1/providers/{provider_id}")).raise_for_status().content
+            )
+        if isinstance(self, Provider):
+            self.__dict__.update(result.__dict__)
+            return self
+        return result
+
+    @staticmethod
+    async def get_by_location(*, location: str, client: PlatformClient | None = None) -> "Provider":
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(Provider).validate_json(
+                (await client.get(url=f"/api/v1/providers/by-location/{urllib.parse.quote(location, safe='')}"))
+                .raise_for_status()
+                .content
+            )
+
+    async def delete(self: "Provider | str", *, client: PlatformClient | None = None) -> None:
+        # `self` has a weird type so that you can call both `instance.delete()` or `Provider.delete("123")`
+        provider_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            _ = (await client.delete(f"/api/v1/providers/{provider_id}")).raise_for_status()
+
+    async def update_variables(
+        self: "Provider | str",
+        *,
+        variables: dict[str, str | None] | dict[str, str],
+        client: PlatformClient | None = None,
+    ) -> None:
+        # `self` has a weird type so that you can call both `instance.delete()` or `Provider.delete("123")`
+        provider_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            _ = (
+                await client.put(f"/api/v1/providers/{provider_id}/variables", json={"variables": variables})
+            ).raise_for_status()
+
+    async def stream_logs(
+        self: "Provider| str", *, client: PlatformClient | None = None
+    ) -> typing.AsyncIterator[dict[str, typing.Any]]:
+        # `self` has a weird type so that you can call both `instance.stream_logs()` or `ProviderBuild.stream_logs("123")`
+        provider_id = self if isinstance(self, str) else self.id
+        async with (
+            client or get_platform_client() as client,
+            client.stream(
+                "GET",
+                url=f"/api/v1/providers/{provider_id}/logs",
+                timeout=timedelta(hours=1).total_seconds(),
+            ) as response,
+        ):
+            async for line in parse_stream(response):
+                yield line
+
+    async def list_variables(self: "Provider | str", *, client: PlatformClient | None = None) -> dict[str, str]:
+        # `self` has a weird type so that you can call both `instance.delete()` or `Provider.delete("123")`
+        provider_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            result = await client.get(f"/api/v1/providers/{provider_id}/variables")
+            return result.raise_for_status().json()["variables"]
+
+    @staticmethod
+    async def list(
+        *, origin: str | None = None, user_owned: bool | None = None, client: PlatformClient | None = None
+    ) -> list["Provider"]:
+        async with client or get_platform_client() as client:
+            params = filter_dict({"origin": origin, "user_owned": user_owned})
+            return pydantic.TypeAdapter(list[Provider]).validate_python(
+                (
+                    await client.get(
+                        url="/api/v1/providers",
+                        params=params,
+                    )
+                )
+                .raise_for_status()
+                .json()["items"]
+            )

agentstack_sdk/platform/provider_build.py

@@ -0,0 +1,190 @@
+# 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 datetime import timedelta
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Literal, TypeAlias
+from uuid import UUID
+
+import pydantic
+from pydantic import Field
+
+from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+from agentstack_sdk.platform.common import PaginatedResult, ResolvedGithubUrl
+from agentstack_sdk.util.utils import filter_dict, parse_stream
+
+
+class BuildState(StrEnum):
+    MISSING = "missing"
+    IN_PROGRESS = "in_progress"
+    BUILD_COMPLETED = "build_completed"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class AddProvider(pydantic.BaseModel):
+    """
+    Will add a new provider or update an existing one with the same base docker image ID
+    (docker registry + repository, excluding tag)
+    """
+
+    type: Literal["add_provider"] = "add_provider"
+    auto_stop_timeout_sec: int | None = pydantic.Field(
+        default=None,
+        gt=0,
+        le=600,
+        description=(
+            "Timeout after which the agent provider will be automatically downscaled if unused."
+            "Contact administrator if you need to increase this value."
+        ),
+    )
+    variables: dict[str, str] | None = None
+
+
+class UpdateProvider(pydantic.BaseModel):
+    """Will update provider specified by ID"""
+
+    type: Literal["update_provider"] = "update_provider"
+    provider_id: UUID
+
+
+class NoAction(pydantic.BaseModel):
+    type: Literal["no_action"] = "no_action"
+
+
+class BuildConfiguration(pydantic.BaseModel):
+    dockerfile_path: Path | None = Field(
+        default=None,
+        description=(
+            "Path to Dockerfile relative to the repository path "
+            "(provider_build.source.path or repository root if not defined)"
+        ),
+    )
+
+
+OnCompleteAction: TypeAlias = AddProvider | UpdateProvider | NoAction
+
+
+class ProviderBuild(pydantic.BaseModel):
+    id: str
+    created_at: pydantic.AwareDatetime
+    status: BuildState
+    source: ResolvedGithubUrl
+    destination: str
+    provider_id: str | None = None
+    build_configuration: BuildConfiguration | None = None
+    created_by: str
+    error_message: str | None = None
+    provider_origin: str
+
+    @staticmethod
+    async def create(
+        *,
+        location: str,
+        client: PlatformClient | None = None,
+        on_complete: OnCompleteAction | None = None,
+        build_configuration: BuildConfiguration | None = None,
+    ) -> ProviderBuild:
+        on_complete = on_complete or NoAction()
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(ProviderBuild).validate_python(
+                (
+                    await client.post(
+                        url="/api/v1/provider_builds",
+                        json={
+                            "location": location,
+                            "on_complete": on_complete.model_dump(exclude_none=True, mode="json"),
+                            "build_configuration": build_configuration.model_dump(exclude_none=True, mode="json")
+                            if build_configuration
+                            else None,
+                        },
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    @staticmethod
+    async def preview(
+        *, location: str, client: PlatformClient | None = None, on_complete: OnCompleteAction | None = None
+    ) -> ProviderBuild:
+        on_complete = on_complete or NoAction()
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(ProviderBuild).validate_python(
+                (
+                    await client.post(
+                        url="/api/v1/provider_builds/preview",
+                        json={"location": location, "on_complete": on_complete.model_dump(exclude_none=True)},
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )
+
+    async def stream_logs(
+        self: ProviderBuild | str, *, client: PlatformClient | None = None
+    ) -> AsyncIterator[dict[str, Any]]:
+        # `self` has a weird type so that you can call both `instance.stream_logs()` or `ProviderBuild.stream_logs("123")`
+        provider_build_id = self if isinstance(self, str) else self.id
+        async with (
+            client or get_platform_client() as client,
+            client.stream(
+                "GET",
+                url=f"/api/v1/provider_builds/{provider_build_id}/logs",
+                timeout=timedelta(hours=1).total_seconds(),
+            ) as response,
+        ):
+            async for line in parse_stream(response):
+                yield line
+
+    async def get(self: ProviderBuild | str, *, client: PlatformClient | None = None) -> ProviderBuild:
+        # `self` has a weird type so that you can call both `instance.get()` to update an instance, or `ProviderBuild.get("123")` to obtain a new instance
+        provider_build_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            result = pydantic.TypeAdapter(ProviderBuild).validate_json(
+                (await client.get(url=f"/api/v1/provider_builds/{provider_build_id}")).raise_for_status().content
+            )
+        if isinstance(self, ProviderBuild):
+            self.__dict__.update(result.__dict__)
+            return self
+        return result
+
+    async def delete(self: ProviderBuild | str, *, client: PlatformClient | None = None) -> None:
+        # `self` has a weird type so that you can call both `instance.delete()` or `ProviderBuild.delete("123")`
+        provider_build_id = self if isinstance(self, str) else self.id
+        async with client or get_platform_client() as client:
+            _ = (await client.delete(f"/api/v1/provider_builds/{provider_build_id}")).raise_for_status()
+
+    @staticmethod
+    async def list(
+        *,
+        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,
+        user_owned: bool | None = None,
+        client: PlatformClient | None = None,
+    ) -> PaginatedResult[ProviderBuild]:
+        # `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:
+            return pydantic.TypeAdapter(PaginatedResult[ProviderBuild]).validate_python(
+                (
+                    await platform_client.get(
+                        url="/api/v1/provider_builds",
+                        params=filter_dict(
+                            {
+                                "page_token": page_token,
+                                "limit": limit,
+                                "order": order,
+                                "order_by": order_by,
+                                "user_owned": user_owned,
+                            }
+                        ),
+                    )
+                )
+                .raise_for_status()
+                .json()
+            )

agentstack_sdk/platform/types.py

@@ -0,0 +1,45 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import typing
+from textwrap import dedent
+
+import pydantic
+from pydantic import AfterValidator, Field
+
+
+def validate_metadata(metadata: dict[str, str | None]) -> dict[str, str | None]:
+    if len(metadata) > 16:
+        raise ValueError("Metadata must be less than 16 keys.")
+    if any(len(k) > 64 for k in metadata):
+        raise ValueError("Metadata keys must be less than 64 characters.")
+    if any(len(v) > 512 for v in metadata.values() if v is not None):
+        raise ValueError("Metadata values must be less than 512 characters.")
+    return metadata
+
+
+Metadata = typing.Annotated[
+    dict[str, str],
+    pydantic.Field(
+        description=dedent(
+            """
+            Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional
+            information about the object in a structured format, and querying for objects via API or the dashboard.
+
+            Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of
+            512 characters.
+            """,
+        )
+    ),
+    pydantic.AfterValidator(validate_metadata),
+]
+
+MetadataPatch = typing.Annotated[
+    dict[str, str | None],
+    Field(
+        description="Metadata update, will add or overwrite existing keys, None will delete the key from metadata.",
+    ),
+    AfterValidator(validate_metadata),
+]

agentstack_sdk/platform/user.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 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: UserRole
+    email: str
+    created_at: pydantic.AwareDatetime
+    role_updated_at: pydantic.AwareDatetime | None = None
+
+    @staticmethod
+    async def get(*, client: PlatformClient | None = None) -> User:
+        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()
+            )