kotharcomputing 0.76.0__py3-none-any.whl

kotharcomputing/__init__.py

@@ -0,0 +1,16 @@
+from .client import (
+    KotharClient,
+    KotharClientOptions,
+    RawResponse,
+)
+from .executions import ExecuteResult
+from .errors import KOTHAR_ERROR_TYPE_BASE_URL, KotharApiError
+
+__all__ = [
+    "KOTHAR_ERROR_TYPE_BASE_URL",
+    "KotharApiError",
+    "KotharClient",
+    "KotharClientOptions",
+    "RawResponse",
+    "ExecuteResult",
+]

kotharcomputing/agents.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypeAlias, TypedDict, cast
+
+from .fetch import ApiTransport
+from .users import WithUser
+
+
+class ActivityExecution(TypedDict):
+    type: Literal["execution"]
+    id: str
+
+
+class ActivityJob(TypedDict):
+    type: Literal["job"]
+    id: str
+
+
+Activity: TypeAlias = ActivityExecution | ActivityJob
+
+AgentKind: TypeAlias = Literal["personal", "cloud"]
+AgentStatus: TypeAlias = Literal["offline", "online"]
+AgentCapabilities: TypeAlias = Literal["direct-execution", "job"]
+
+
+class AgentSystemInfoCPU(TypedDict):
+    arch: str
+    parallelism: int
+    flags: list[str]
+    vendor: NotRequired[str]
+    model: NotRequired[str]
+
+
+class AgentSystemInfoMemory(TypedDict):
+    totalMB: int
+
+
+class AgentSystemInfo(TypedDict):
+    cpu: AgentSystemInfoCPU
+    memory: AgentSystemInfoMemory
+
+
+class AgentData(TypedDict):
+    systemInfo: AgentSystemInfo
+
+
+class AgentPersonal(WithUser):
+    id: str
+    name: str
+    status: AgentStatus
+    kind: Literal["personal"]
+    capabilities: list[AgentCapabilities]
+    activities: list[Activity]
+    ownerId: str
+    createdAt: str
+    ip: NotRequired[str]
+    version: NotRequired[str]
+    imageVersion: NotRequired[str]
+    lastSeen: NotRequired[str]
+    data: NotRequired[AgentData]
+
+
+class AgentCloudCPU(TypedDict):
+    parallelism: int
+
+
+class AgentCloudSystemInfo(TypedDict):
+    cpu: AgentCloudCPU
+    memory: AgentSystemInfoMemory
+
+
+class AgentCloudData(TypedDict):
+    systemInfo: AgentCloudSystemInfo
+
+
+class AgentCloud(WithUser):
+    id: str
+    name: str
+    status: AgentStatus
+    kind: Literal["cloud"]
+    capabilities: list[AgentCapabilities]
+    activities: list[Activity]
+    ownerId: str
+    tooltip: NotRequired[str]
+    timeout: NotRequired[str]
+    data: NotRequired[AgentCloudData]
+
+
+Agent: TypeAlias = AgentPersonal | AgentCloud
+
+
+class WithAgent(TypedDict):
+    agentId: str
+    agentName: NotRequired[str]
+
+
+class CreateAgentArgs(TypedDict):
+    name: str
+    kind: AgentKind
+    ownerId: str
+
+
+class CreateAgentResult(TypedDict):
+    agent: Agent
+    token: str
+    cmdLine: str
+
+
+class ResetAgentTokenResult(TypedDict):
+    agent: Agent
+    token: str
+    cmdLine: str
+
+
+class DeleteAgentResult(TypedDict, total=False):
+    cmdLine: str
+
+
+class AgentsPage(TypedDict):
+    items: list[Agent]
+    next: NotRequired[str]
+
+
+class AgentsClient:
+    def __init__(self, transport: ApiTransport) -> None:
+        self._transport = transport
+
+    def list(
+        self,
+        *,
+        for_user_id: str,
+        next: str | None = None,
+        with_usernames: bool | None = None,
+    ) -> AgentsPage:
+        return cast(
+            AgentsPage,
+            self._transport.get_json(
+                "v1/agents",
+                search_params={
+                    "forUserId": for_user_id,
+                    "next": next,
+                    "withUsernames": with_usernames,
+                },
+            ),
+        )
+
+    def create(self, args: CreateAgentArgs) -> CreateAgentResult:
+        return cast(
+            CreateAgentResult, self._transport.post_json("v1/agents", json_data=args)
+        )
+
+    def id(self, agent_id: str) -> "AgentByIdClient":
+        return AgentByIdClient(self._transport, agent_id)
+
+
+class AgentByIdClient:
+    def __init__(self, transport: ApiTransport, agent_id: str) -> None:
+        self._transport = transport
+        self._agent_id = agent_id
+
+    def get(self, *, with_usernames: bool | None = None) -> Agent:
+        return cast(
+            Agent,
+            self._transport.get_json(
+                "v1/agents/:agentId",
+                path_params={"agentId": self._agent_id},
+                search_params={"withUsernames": with_usernames},
+            ),
+        )
+
+    def reset_token(self) -> ResetAgentTokenResult:
+        return cast(
+            ResetAgentTokenResult,
+            self._transport.post_json(
+                "v1/agents/:agentId/$resetToken",
+                path_params={"agentId": self._agent_id},
+            ),
+        )
+
+    def delete(self) -> DeleteAgentResult:
+        return cast(
+            DeleteAgentResult,
+            self._transport.delete_json(
+                "v1/agents/:agentId", path_params={"agentId": self._agent_id}
+            ),
+        )

kotharcomputing/ai.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from typing import Callable, Literal, NotRequired, TypeAlias, TypedDict, cast
+
+from .common import JSONValue
+from .errors import ProblemDetails
+from .fetch import ApiTransport
+from .users import WithUser
+
+
+class AIChatContentText(TypedDict):
+    type: Literal["text"]
+    text: str
+
+
+class AIChatFileLocation(TypedDict):
+    line: int
+    column: int
+
+
+class AIChatSelection(TypedDict):
+    start: AIChatFileLocation
+    end: AIChatFileLocation
+
+
+class AIChatContentEditorContextFile(TypedDict):
+    path: str
+    content: str
+    is_truncated: bool
+    language: NotRequired[str]
+    is_primary: NotRequired[bool]
+    cursor: NotRequired[AIChatFileLocation]
+    selection: NotRequired[AIChatSelection]
+
+
+class AIChatContentEditorContext(TypedDict):
+    type: Literal["editor_context"]
+    files: list[AIChatContentEditorContextFile]
+
+
+AIChatMessageAssistantContent: TypeAlias = AIChatContentText
+AIChatMessageUserContent: TypeAlias = AIChatContentText
+AIChatMessageUserContentEdition: TypeAlias = (
+    AIChatContentText | AIChatContentEditorContext
+)
+
+
+class AIChatToolDescriptionFunctionData(TypedDict):
+    name: str
+    description: NotRequired[str]
+    parameters: NotRequired[JSONValue]
+
+
+class AIChatToolDescriptionFunction(TypedDict):
+    type: Literal["function"]
+    function: AIChatToolDescriptionFunctionData
+
+
+AIChatToolDescription: TypeAlias = AIChatToolDescriptionFunction
+
+
+class AIChatToolCallFunctionData(TypedDict):
+    name: str
+    arguments: str
+
+
+class AIChatToolCallFunction(TypedDict):
+    id: str
+    type: Literal["function"]
+    function: AIChatToolCallFunctionData
+
+
+AIChatToolCall: TypeAlias = AIChatToolCallFunction
+
+
+class AbbreviatedAIChat(TypedDict):
+    id: str
+    createdAt: str
+    updatedAt: str
+    summary: NotRequired[str]
+
+
+class AIChatMessageApi(TypedDict):
+    role: Literal["api"]
+    aiChat: AbbreviatedAIChat
+
+
+class AIChatMessageUser(TypedDict):
+    role: Literal["user"]
+    content: list[AIChatMessageUserContent]
+
+
+class AIChatMessageAssistant(TypedDict):
+    role: Literal["assistant"]
+    content: NotRequired[list[AIChatMessageAssistantContent]]
+    toolCalls: NotRequired[list[AIChatToolCall]]
+    refusal: NotRequired[str]
+    reasoning: NotRequired[str]
+
+
+class AIChatMessageAssistantDelta(TypedDict):
+    role: Literal["assistant_delta"]
+    content: NotRequired[str]
+    refusal: NotRequired[str]
+    reasoning: NotRequired[str]
+
+
+class AIChatMessageError(TypedDict):
+    role: Literal["error"]
+    error: ProblemDetails
+
+
+class AIChatMessageTool(TypedDict):
+    role: Literal["tool"]
+    toolCallId: str
+    content: str
+
+
+AIChatMessage: TypeAlias = AIChatMessageApi | AIChatMessageUser | AIChatMessageAssistant
+AIChatMessageWithStreaming: TypeAlias = (
+    AIChatMessage | AIChatMessageAssistantDelta | AIChatMessageError
+)
+
+
+class AIChat(WithUser):
+    id: str
+    createdAt: str
+    updatedAt: str
+    messages: list[AIChatMessage]
+    summary: NotRequired[str]
+
+
+class AIChatsPage(TypedDict):
+    items: list[AbbreviatedAIChat]
+    next: NotRequired[str]
+
+
+class AIModelInfo(TypedDict):
+    id: str
+    name: str
+    default: NotRequired[bool]
+
+
+class AIChatMessageUserCreate(TypedDict):
+    role: Literal["user"]
+    content: list[AIChatMessageUserContentEdition]
+
+
+AIChatMessageUserAppend: TypeAlias = AIChatMessageUserCreate | AIChatMessageTool
+
+
+class AIChatByIdClient:
+    def __init__(
+        self, transport: ApiTransport, workspace_id: str, chat_id: str
+    ) -> None:
+        self._transport = transport
+        self._workspace_id = workspace_id
+        self._chat_id = chat_id
+
+    def get(self, *, with_usernames: bool | None = None) -> AIChat:
+        return cast(
+            AIChat,
+            self._transport.get_json(
+                "v1/workspaces/:workspaceId/ai/chats/:chatId",
+                path_params={
+                    "workspaceId": self._workspace_id,
+                    "chatId": self._chat_id,
+                },
+                search_params={"withUsernames": with_usernames},
+            ),
+        )
+
+    def append(
+        self,
+        *,
+        message: AIChatMessageUserAppend,
+        on: Callable[[AIChatMessage | AIChatMessageWithStreaming], None],
+        model: str | None = None,
+        tools: list[AIChatToolDescription] | None = None,
+        stream: bool | None = None,
+    ) -> None:
+        self._transport.sse(
+            "put",
+            "v1/workspaces/:workspaceId/ai/chats/:chatId",
+            path_params={"workspaceId": self._workspace_id, "chatId": self._chat_id},
+            json_data={
+                "message": message,
+                "model": model,
+                "tools": tools,
+                "stream": stream,
+            },
+            callback=on,
+        )
+
+    def delete(self) -> None:
+        self._transport.raw(
+            "delete",
+            "v1/workspaces/:workspaceId/ai/chats/:chatId",
+            path_params={"workspaceId": self._workspace_id, "chatId": self._chat_id},
+        )
+
+
+class AIChatsClient:
+    def __init__(self, transport: ApiTransport, workspace_id: str) -> None:
+        self._transport = transport
+        self._workspace_id = workspace_id
+
+    def list(self, *, next: str | None = None) -> AIChatsPage:
+        return cast(
+            AIChatsPage,
+            self._transport.get_json(
+                "v1/workspaces/:workspaceId/ai/chats",
+                path_params={"workspaceId": self._workspace_id},
+                search_params={"next": next},
+            ),
+        )
+
+    def create(
+        self,
+        *,
+        message: AIChatMessageUserCreate,
+        on: Callable[[AIChatMessage | AIChatMessageWithStreaming], None],
+        model: str | None = None,
+        tools: list[AIChatToolDescription] | None = None,
+        stream: bool | None = None,
+    ) -> None:
+        self._transport.sse(
+            "post",
+            "v1/workspaces/:workspaceId/ai/chats",
+            path_params={"workspaceId": self._workspace_id},
+            json_data={
+                "message": message,
+                "model": model,
+                "tools": tools,
+                "stream": stream,
+            },
+            callback=on,
+        )
+
+    def id(self, chat_id: str) -> AIChatByIdClient:
+        return AIChatByIdClient(self._transport, self._workspace_id, chat_id)
+
+
+class AIModelsClient:
+    def __init__(self, transport: ApiTransport, workspace_id: str) -> None:
+        self._transport = transport
+        self._workspace_id = workspace_id
+
+    def list(self) -> list[AIModelInfo]:
+        return cast(
+            list[AIModelInfo],
+            self._transport.get_json(
+                "v1/workspaces/:workspaceId/ai/models",
+                path_params={"workspaceId": self._workspace_id},
+            ),
+        )
+
+
+class WorkspaceAIClient:
+    def __init__(self, transport: ApiTransport, workspace_id: str) -> None:
+        self.chats = AIChatsClient(transport, workspace_id)
+        self.models = AIModelsClient(transport, workspace_id)

kotharcomputing/api_tokens.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Literal, NotRequired, TypeAlias, TypedDict, cast
+
+from .fetch import ApiTransport, to_optional_iso
+from .users import WithUser
+
+
+class ApiToken(WithUser):
+    createdAt: str
+    id: str
+    name: str
+    permissions: "ApiTokenPermissions"
+    workspaceId: str
+    description: NotRequired[str]
+    expiresAt: NotRequired[str]
+
+
+ApiTokenPermissionSubject: TypeAlias = Literal["agent", "execution", "file", "job"]
+ApiTokenPermissionAction: TypeAlias = Literal[
+    "create", "read", "update", "delete", "manage"
+]
+ApiTokenPermissions: TypeAlias = list[
+    tuple[ApiTokenPermissionAction, ApiTokenPermissionSubject]
+]
+
+
+class CreateApiTokenArgs(TypedDict):
+    name: str
+    permissions: ApiTokenPermissions
+    description: NotRequired[str]
+    expiresAt: NotRequired[str | date | datetime]
+
+
+class CreateApiTokenResult(TypedDict):
+    apiToken: ApiToken
+    token: str
+
+
+class ApiTokensPage(TypedDict):
+    items: list[ApiToken]
+    next: NotRequired[str]
+
+
+class ApiTokensByIdClient:
+    def __init__(
+        self, transport: ApiTransport, workspace_id: str, api_token_id: str
+    ) -> None:
+        self._transport = transport
+        self._workspace_id = workspace_id
+        self._api_token_id = api_token_id
+
+    def get(self, *, with_usernames: bool | None = None) -> ApiToken:
+        return cast(
+            ApiToken,
+            self._transport.get_json(
+                "v1/workspaces/:workspaceId/api-tokens/:apiTokenId",
+                path_params={
+                    "workspaceId": self._workspace_id,
+                    "apiTokenId": self._api_token_id,
+                },
+                search_params={"withUsernames": with_usernames},
+            ),
+        )
+
+    def delete(self) -> None:
+        self._transport.raw(
+            "delete",
+            "v1/workspaces/:workspaceId/api-tokens/:apiTokenId",
+            path_params={
+                "workspaceId": self._workspace_id,
+                "apiTokenId": self._api_token_id,
+            },
+        )
+
+
+class ApiTokensClient:
+    def __init__(self, transport: ApiTransport, workspace_id: str) -> None:
+        self._transport = transport
+        self._workspace_id = workspace_id
+
+    def list(
+        self, *, next: str | None = None, with_usernames: bool | None = None
+    ) -> ApiTokensPage:
+        return cast(
+            ApiTokensPage,
+            self._transport.get_json(
+                "v1/workspaces/:workspaceId/api-tokens",
+                path_params={"workspaceId": self._workspace_id},
+                search_params={"next": next, "withUsernames": with_usernames},
+            ),
+        )
+
+    def create(self, args: CreateApiTokenArgs) -> CreateApiTokenResult:
+        payload = dict(args)
+        expires_at = payload.get("expiresAt")
+        if isinstance(expires_at, (date, datetime)):
+            payload["expiresAt"] = to_optional_iso(expires_at)
+
+        return cast(
+            CreateApiTokenResult,
+            self._transport.post_json(
+                "v1/workspaces/:workspaceId/api-tokens",
+                path_params={"workspaceId": self._workspace_id},
+                json_data=payload,
+            ),
+        )
+
+    def id(self, api_token_id: str) -> ApiTokensByIdClient:
+        return ApiTokensByIdClient(self._transport, self._workspace_id, api_token_id)

kotharcomputing/client.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .agents import AgentsClient
+from .fetch import AccessTokenProvider, ApiTransport, QueryParamValue, RawResponse
+from .runtimes import RuntimesClient
+from .service_prices import ServicePricesClient
+from .users import UsersClient
+from .workspaces import WorkspacesClient
+
+DEFAULT_BASE_URL = "https://api.kotharcomputing.com"
+
+
+@dataclass(slots=True)
+class KotharClientOptions:
+    base_url: str = DEFAULT_BASE_URL
+    access_token: AccessTokenProvider | None = None
+    timeout: float = 30.0
+
+
+class KotharClient:
+    def __init__(
+        self,
+        options: KotharClientOptions | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        access_token: AccessTokenProvider | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        if options is None:
+            options = KotharClientOptions(
+                base_url=base_url,
+                access_token=access_token,
+                timeout=timeout,
+            )
+
+        self._transport = ApiTransport(
+            base_url=options.base_url,
+            access_token=options.access_token,
+            timeout=options.timeout,
+        )
+
+        self.agents = AgentsClient(self._transport)
+        self.runtimes = RuntimesClient(self._transport)
+        self.service_prices = ServicePricesClient(self._transport)
+        self.users = UsersClient(self._transport)
+        self.workspaces = WorkspacesClient(self._transport)
+
+        # TS-compat aliases.
+        self.servicePrices = self.service_prices
+        self.apiVersion = self.api_version
+        self._raw = self.raw
+
+    def api_version(self) -> dict[str, str]:
+        return self._transport.get_json("version")
+
+    def raw(
+        self,
+        method: str,
+        templated_url: str,
+        *,
+        path_params: Mapping[str, str | int | bool] | None = None,
+        search_params: Mapping[str, QueryParamValue] | None = None,
+        headers: Mapping[str, str | None] | None = None,
+        body: bytes | str | None = None,
+        json_data: Any | None = None,
+    ) -> RawResponse:
+        return self._transport.raw(
+            method,
+            templated_url,
+            path_params=path_params,
+            search_params=search_params,
+            headers=headers,
+            body=body,
+            json_data=json_data,
+        )

kotharcomputing/common.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from typing import TypeAlias
+
+
+JSONPrimitive: TypeAlias = str | int | float | bool | None
+JSONValue: TypeAlias = JSONPrimitive | list["JSONValue"] | dict[str, "JSONValue"]