stacklink-sdk 0.2.0__py3-none-any.whl

stacklink/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from .client import STACKLINK_PYTHON_SDK_VERSION, Stacklink
+from .claude_agent import create_stacklink_claude_agent_tool_config
+from .errors import RateLimitError, StacklinkError
+from .openai_agents import create_stacklink_openai_agents_tools
+from .openai_memory import StacklinkMemoryLifecycleError, with_stacklink_memory
+from .types import (
+    ProjectProvider,
+    ProviderMarketplaceMetadata,
+    ProviderProfile,
+    ProviderProfileCapabilityGroup,
+    ProviderProfileCapabilityItem,
+    ProviderProfileDetails,
+    ProviderTool,
+    ProviderToolkit,
+    StacklinkBillingDescriptor,
+    ToolSchemasResponse,
+    ToolSearchResponse,
+)
+
+__all__ = [
+    "Stacklink",
+    "STACKLINK_PYTHON_SDK_VERSION",
+    "StacklinkError",
+    "RateLimitError",
+    "StacklinkMemoryLifecycleError",
+    "with_stacklink_memory",
+    "create_stacklink_openai_agents_tools",
+    "create_stacklink_claude_agent_tool_config",
+    "ProjectProvider",
+    "ProviderMarketplaceMetadata",
+    "ProviderProfile",
+    "ProviderProfileCapabilityGroup",
+    "ProviderProfileCapabilityItem",
+    "ProviderProfileDetails",
+    "ProviderTool",
+    "ProviderToolkit",
+    "StacklinkBillingDescriptor",
+    "ToolSearchResponse",
+    "ToolSchemasResponse",
+]

stacklink/api_keys.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ApiKeysResource:
+    def __init__(self, client):
+        self.client = client
+
+    def list(self):
+        return self.client.request("GET", "/v1/api-keys")
+
+    def create(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/api-keys", json_body=body)
+
+    def revoke(self, api_key_id: str):
+        return self.client.request("DELETE", f"/v1/api-keys/{api_key_id}")
+

stacklink/artifacts.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class ArtifactsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def get(self, artifact_id: str):
+        return self.client.request("GET", f"/v1/artifacts/{artifact_id}")

stacklink/auth_configs.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class AuthConfigsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def list(self, **query):
+        return self.client.request("GET", "/v1/auth-configs", query=query)
+
+    def create(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/auth-configs", json_body=body)
+
+    def get(self, auth_config_id: str):
+        return self.client.request("GET", f"/v1/auth-configs/{auth_config_id}")
+
+    def update(self, auth_config_id: str, body: dict[str, Any]):
+        return self.client.request("PATCH", f"/v1/auth-configs/{auth_config_id}", json_body=body)
+
+    def enable(self, auth_config_id: str):
+        return self.client.request("POST", f"/v1/auth-configs/{auth_config_id}/enable")
+
+    def disable(self, auth_config_id: str):
+        return self.client.request("POST", f"/v1/auth-configs/{auth_config_id}/disable")
+
+    def delete(self, auth_config_id: str):
+        return self.client.request("DELETE", f"/v1/auth-configs/{auth_config_id}")

stacklink/billing.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class BillingResource:
+    def __init__(self, client):
+        self.client = client
+
+    def plans(self):
+        return self.client.request("GET", "/v1/billing/plans")
+
+    def rate_card(self, **query):
+        return self.client.request("GET", "/v1/billing/rate-card", query=query)
+
+    def subscription(self):
+        return self.client.request("GET", "/v1/subscription")
+
+    def usage(self, **query):
+        return self.client.request("GET", "/v1/usage", query=query)
+
+    def usage_events(self, **query):
+        return self.client.request("GET", "/v1/usage/events", query=query)
+
+    def create_checkout(self, plan_key: str, success_url: str | None = None, cancel_url: str | None = None):
+        body: dict[str, Any] = {"planKey": plan_key}
+        if success_url is not None:
+            body["successUrl"] = success_url
+        if cancel_url is not None:
+            body["cancelUrl"] = cancel_url
+        return self.client.request("POST", "/v1/billing/checkout", json_body=body)
+
+    def create_portal(self, return_url: str | None = None):
+        body: dict[str, Any] = {}
+        if return_url is not None:
+            body["returnUrl"] = return_url
+        return self.client.request("POST", "/v1/billing/portal", json_body=body)
+
+    def create_overage_invoice_line(self):
+        return self.client.request("POST", "/v1/billing/overage-invoice-line")
+
+    def set_workspace_plan_for_project(self, project_id: str, body: dict[str, Any]):
+        return self.client.request("POST", f"/v1/projects/{project_id}/subscription/plan", json_body=body)

stacklink/claude_agent.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypedDict
+
+if TYPE_CHECKING:
+    from .sessions import Session
+
+
+class StacklinkClaudeAgentToolConfig(TypedDict):
+    mcp_servers: dict[str, dict[str, Any]]
+    allowed_tools: list[str]
+
+
+def create_stacklink_claude_agent_tool_config(
+    session: "Session",
+) -> StacklinkClaudeAgentToolConfig:
+    connection = session.mcp_connection()
+    return {
+        "mcp_servers": {
+            "stacklink": {
+                "type": "http",
+                "url": connection["url"],
+                "headers": dict(connection["headers"]),
+            }
+        },
+        "allowed_tools": [
+            f"mcp__stacklink__{tool.name}" for tool in session.tools().values()
+        ],
+    }

stacklink/client.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Iterator, Mapping
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .api_keys import ApiKeysResource
+from .artifacts import ArtifactsResource
+from .auth_configs import AuthConfigsResource
+from .billing import BillingResource
+from .connected_accounts import ConnectedAccountsResource
+from .errors import RateLimitError, StacklinkError
+from .executions import ExecutionsResource
+from .knowledge import KnowledgeResource
+from .logs import LogsResource
+from .memory import MemoryResource
+from .mcp import McpResource
+from .projects import ProjectsResource
+from .sessions import SessionsResource
+from .tools import ToolsResource
+from .triggers import TriggersResource
+from .types import Json, Transport
+from .webhooks import WebhooksResource
+from .workbench import WorkbenchResource
+
+STACKLINK_PYTHON_SDK_VERSION = "0.2.0"
+STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
+
+
+class Stacklink:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        registration_key: str | None = None,
+        base_url: str | None = None,
+        timeout_ms: int | None = None,
+        transport: Transport | None = None,
+        cache_enabled: bool | None = None,
+        cache_ttl_seconds: int | None = None,
+    ):
+        self.api_key = api_key or os.getenv("STACKLINK_API_KEY")
+        if not self.api_key:
+            raise StacklinkError("STACKLINK_API_KEY is required.")
+        self.registration_key = registration_key or os.getenv("STACKLINK_REGISTRATION_KEY")
+        self.base_url = (base_url or os.getenv("STACKLINK_BASE_URL") or "http://localhost:3000").rstrip("/")
+        self.timeout = (timeout_ms or int(os.getenv("STACKLINK_TIMEOUT_MS", "30000"))) / 1000
+        self._transport = transport
+        self.cache_enabled = cache_enabled if cache_enabled is not None else True
+        self.cache_ttl_seconds = cache_ttl_seconds or int(os.getenv("STACKLINK_CACHE_TTL_SECONDS", "120"))
+        self._cache: dict[str, tuple[float, Json]] = {}
+        self.sessions = SessionsResource(self)
+        self.tools = ToolsResource(self)
+        self.mcp = McpResource(self)
+        self.executions = ExecutionsResource(self)
+        self.workbench = WorkbenchResource(self)
+        self.auth_configs = AuthConfigsResource(self)
+        self.connected_accounts = ConnectedAccountsResource(self)
+        self.triggers = TriggersResource(self)
+        self.webhooks = WebhooksResource(self)
+        self.logs = LogsResource(self)
+        self.memory = MemoryResource(self)
+        self.knowledge = KnowledgeResource(self)
+        self.billing = BillingResource(self)
+        self.api_keys = ApiKeysResource(self)
+        self.projects = ProjectsResource(self)
+        self.artifacts = ArtifactsResource(self)
+
+    def clear_cache(self, prefix: str | None = None) -> None:
+        if prefix is None:
+            self._cache.clear()
+            return
+        for key in list(self._cache.keys()):
+            if key.startswith(prefix):
+                del self._cache[key]
+
+    def cached_request(
+        self,
+        cache_key: str,
+        method: str,
+        path: str,
+        *,
+        json_body: Json | None = None,
+        query: Mapping[str, Any] | None = None,
+        ttl_seconds: int | None = None,
+        bypass_cache: bool = False,
+    ) -> Json:
+        if not self.cache_enabled or bypass_cache:
+            return self.request(method, path, json_body=json_body, query=query)
+        now = time.time()
+        cached = self._cache.get(cache_key)
+        if cached and cached[0] > now:
+            return cached[1]
+        value = self.request(method, path, json_body=json_body, query=query)
+        self._cache[cache_key] = (now + (ttl_seconds or self.cache_ttl_seconds), value)
+        return value
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Json | None = None,
+        query: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        registration: bool = False,
+    ) -> Json:
+        if registration:
+            if not self.registration_key:
+                raise StacklinkError("STACKLINK_REGISTRATION_KEY is required for registration/admin SDK methods.")
+            request_headers = {
+                "x-stacklink-registration-key": self.registration_key,
+                "content-type": "application/json",
+                **(headers or {}),
+                "user-agent": STACKLINK_PYTHON_USER_AGENT,
+                "x-stacklink-client-channel": "python_sdk",
+                "x-stacklink-client-name": "stacklink-python",
+                "x-stacklink-client-version": STACKLINK_PYTHON_SDK_VERSION,
+            }
+        else:
+            request_headers = {
+                "authorization": f"Bearer {self.api_key}",
+                "content-type": "application/json",
+                **(headers or {}),
+                "user-agent": STACKLINK_PYTHON_USER_AGENT,
+                "x-stacklink-client-channel": "python_sdk",
+                "x-stacklink-client-name": "stacklink-python",
+                "x-stacklink-client-version": STACKLINK_PYTHON_SDK_VERSION,
+            }
+        query_values = {key: value for key, value in (query or {}).items() if value is not None}
+        if self._transport:
+            status, response_headers, body = self._transport(method, path, request_headers, json_body, query_values, self.timeout)
+            return self._handle_response(status, response_headers, body)
+
+        url = f"{self.base_url}{path}"
+        if query_values:
+            url = f"{url}?{urlencode(query_values, doseq=True)}"
+        data = None if json_body is None else json.dumps(json_body).encode("utf-8")
+        request = Request(url, data=data, method=method, headers=request_headers)
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                raw = response.read().decode("utf-8")
+                body = json.loads(raw) if raw else None
+                return self._handle_response(response.status, dict(response.headers.items()), body)
+        except HTTPError as error:
+            raw = error.read().decode("utf-8")
+            try:
+                body = json.loads(raw) if raw else {}
+            except json.JSONDecodeError:
+                body = {"message": raw}
+            return self._handle_response(error.code, dict(error.headers.items()), body)
+
+    def request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> bytes:
+        request_headers = {
+            "authorization": f"Bearer {self.api_key}",
+            **(headers or {}),
+            "x-stacklink-client-channel": "python_sdk",
+            "x-stacklink-client-name": "stacklink-python",
+            "x-stacklink-client-version": STACKLINK_PYTHON_SDK_VERSION,
+        }
+        query_values = {key: value for key, value in (query or {}).items() if value is not None}
+        if self._transport:
+            status, response_headers, body = self._transport(method, path, request_headers, None, query_values, self.timeout)
+            if status >= 400:
+                self._handle_response(status, response_headers, body)
+            if isinstance(body, bytes):
+                return body
+            if isinstance(body, str):
+                return body.encode("utf-8")
+            return json.dumps(body).encode("utf-8")
+
+        url = f"{self.base_url}{path}"
+        if query_values:
+            url = f"{url}?{urlencode(query_values, doseq=True)}"
+        request = Request(url, method=method, headers=request_headers)
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                return response.read()
+        except HTTPError as error:
+            raw = error.read().decode("utf-8")
+            try:
+                body = json.loads(raw) if raw else {}
+            except json.JSONDecodeError:
+                body = {"message": raw}
+            self._handle_response(error.code, dict(error.headers.items()), body)
+            return b""
+
+    def request_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        request_headers = {
+            "authorization": f"Bearer {self.api_key}",
+            "accept": "text/event-stream",
+            **(headers or {}),
+        }
+        query_values = {key: value for key, value in (query or {}).items() if value is not None}
+        if self._transport:
+            status, response_headers, body = self._transport(method, path, request_headers, None, query_values, self.timeout)
+            if status >= 400:
+                self._handle_response(status, response_headers, body)
+            if isinstance(body, str):
+                yield from self._parse_sse_lines(body.splitlines())
+            elif isinstance(body, list):
+                for event in body:
+                    if isinstance(event, dict):
+                        yield event
+            return
+
+        url = f"{self.base_url}{path}"
+        if query_values:
+            url = f"{url}?{urlencode(query_values, doseq=True)}"
+        request = Request(url, method=method, headers=request_headers)
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                yield from self._parse_sse_lines(line.decode("utf-8") for line in response)
+        except HTTPError as error:
+            raw = error.read().decode("utf-8")
+            try:
+                body = json.loads(raw) if raw else {}
+            except json.JSONDecodeError:
+                body = {"message": raw}
+            self._handle_response(error.code, dict(error.headers.items()), body)
+
+    def _handle_response(self, status: int, headers: Mapping[str, str], body: Json) -> Json:
+        if status < 400:
+            return body
+        message = body.get("message") if isinstance(body, dict) else None
+        code = body.get("code") if isinstance(body, dict) else None
+        details = body.get("details") if isinstance(body, dict) else None
+        if status == 429:
+            raise RateLimitError(message or "Stacklink rate limit exceeded.", status_code=status, code=code, details=details, headers=headers)
+        raise StacklinkError(message or "Stacklink request failed.", status_code=status, code=code, details=details)
+
+    def _parse_sse_lines(self, lines) -> Iterator[dict[str, Any]]:
+        event_id = None
+        event_name = None
+        data_lines: list[str] = []
+
+        def emit_event():
+            if not data_lines:
+                return None
+            data_text = "\n".join(data_lines)
+            try:
+                data: Any = json.loads(data_text)
+            except json.JSONDecodeError:
+                data = data_text
+            return {
+                "id": event_id,
+                "event": event_name,
+                "data": data,
+            }
+
+        for raw_line in lines:
+            line = str(raw_line).rstrip("\r\n")
+            if line == "":
+                event = emit_event()
+                if event is not None:
+                    yield event
+                event_id = None
+                event_name = None
+                data_lines = []
+                continue
+            if line.startswith(":"):
+                continue
+            field, separator, value = line.partition(":")
+            if separator and value.startswith(" "):
+                value = value[1:]
+            if field == "id":
+                event_id = value
+            elif field == "event":
+                event_name = value
+            elif field == "data":
+                data_lines.append(value)
+
+        event = emit_event()
+        if event is not None:
+            yield event

stacklink/connected_accounts.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+class ConnectedAccountsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def list(self, **query):
+        return self.client.request("GET", "/v1/connections", query=query)
+
+    def get(self, account_id: str):
+        return self.client.request("GET", f"/v1/connections/{account_id}")
+
+    def list_tools(
+        self,
+        account_id: str,
+        *,
+        include_planned: bool | None = None,
+        tool_keys: list[str] | None = None,
+    ):
+        query: dict[str, Any] = {}
+        if include_planned is not None:
+            query["includePlanned"] = str(include_planned).lower()
+        if tool_keys:
+            query["toolKeys"] = tool_keys
+        return self.client.request("GET", f"/v1/connections/{account_id}/tools", query=query)
+
+    def list_resources(self, account_id: str):
+        return self.client.request("GET", f"/v1/connections/{account_id}/resources")
+
+    def refresh_resources(self, account_id: str):
+        return self.client.request("POST", f"/v1/connections/{account_id}/resources/refresh")
+
+    def resolve_resource(self, account_id: str, *, resource_key: str, external_resource_id: str):
+        return self.client.request(
+            "POST",
+            f"/v1/connections/{account_id}/resources/resolve",
+            json_body={
+                "resourceKey": resource_key,
+                "externalResourceId": external_resource_id,
+            },
+        )
+
+    def update(self, account_id: str, body: dict[str, Any]):
+        return self.client.request("PATCH", f"/v1/connections/{account_id}", json_body=body)
+
+    def enable(self, account_id: str):
+        return self.client.request("POST", f"/v1/connections/{account_id}/enable")
+
+    def disable(self, account_id: str):
+        return self.client.request("POST", f"/v1/connections/{account_id}/disable")
+
+    def refresh(self, account_id: str):
+        return self.client.request("POST", f"/v1/connections/{account_id}/refresh")
+
+    def delete(self, account_id: str):
+        return self.client.request("DELETE", f"/v1/connections/{account_id}")
+
+    def validate(self, account_id: str):
+        return self.client.request("POST", f"/v1/connections/{account_id}/validate")
+
+    def inspect_connect_token(self, public_token: str):
+        return self.client.request("GET", f"/v1/connect/{public_token}")
+
+    def complete_connect_token(self, public_token: str, body: dict[str, Any]):
+        return self.client.request("POST", f"/v1/connect/{public_token}/complete", json_body=body)
+
+    def get_connection_request(self, request_id: str):
+        return self.client.request("GET", f"/v1/connection-requests/{request_id}")
+
+    def wait_for_connections(self, request_ids: list[str], timeout_seconds: float = 120, interval_seconds: float = 2):
+        started_at = time.monotonic()
+        while time.monotonic() - started_at <= timeout_seconds:
+            connection_requests = [
+                self.get_connection_request(request_id).get("connectionRequest")
+                for request_id in request_ids
+            ]
+            statuses = [request.get("status") for request in connection_requests if isinstance(request, dict)]
+            if len(statuses) == len(request_ids) and all(status == "completed" for status in statuses):
+                return {"status": "completed", "connectionRequests": connection_requests}
+            terminal = next(
+                (
+                    request
+                    for request in connection_requests
+                    if isinstance(request, dict) and request.get("status") in {"failed", "expired", "cancelled"}
+                ),
+                None,
+            )
+            if isinstance(terminal, dict):
+                raise RuntimeError(f"Stacklink connection ended with status {terminal.get('status')}.")
+            time.sleep(interval_seconds)
+        raise TimeoutError("Timed out waiting for Stacklink connections.")

stacklink/errors.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+class StacklinkError(Exception):
+    def __init__(self, message: str, *, status_code: int | None = None, code: str | None = None, details=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+
+
+class RateLimitError(StacklinkError):
+    def __init__(self, message: str, *, status_code: int = 429, code: str | None = "rate_limited", details=None, headers=None):
+        super().__init__(message, status_code=status_code, code=code, details=details)
+        self.headers = headers or {}
+

stacklink/executions.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict, cast
+
+
+class ExecutionListPage(TypedDict):
+    executions: list[dict[str, Any]]
+    limit: int
+    nextCursor: str | None
+    liveCount: int
+
+
+class ExecutionEventsPage(TypedDict):
+    events: list[dict[str, Any]]
+    limit: int
+    hasMore: bool
+    nextCursor: str | None
+
+
+class ExecutionsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def list(self, session_id: str, **query) -> ExecutionListPage:
+        return cast(ExecutionListPage, self.client.request(
+            "GET",
+            "/v1/executions",
+            query={"sessionId": session_id, **query},
+        ))
+
+    def get(self, session_id: str, execution_kind: str, execution_id: str, **query):
+        return self.client.request("GET", f"/v1/executions/{execution_kind}/{execution_id}", query={"sessionId": session_id, **query})
+
+    def events(self, session_id: str, execution_kind: str, execution_id: str, **query) -> ExecutionEventsPage:
+        return cast(ExecutionEventsPage, self.client.request(
+            "GET",
+            f"/v1/executions/{execution_kind}/{execution_id}/events",
+            query={"sessionId": session_id, **query},
+        ))
+
+    def wait(self, session_id: str, execution_kind: str, execution_id: str, body: dict[str, Any] | None = None):
+        return self.client.request("POST", f"/v1/executions/{execution_kind}/{execution_id}/wait", json_body={"sessionId": session_id, **(body or {})})
+
+    def cancel(self, session_id: str, execution_kind: str, execution_id: str, reason: str | None = None):
+        return self.client.request("POST", f"/v1/executions/{execution_kind}/{execution_id}/cancel", json_body={"sessionId": session_id, "reason": reason})

stacklink/knowledge.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class KnowledgeResource:
+    def __init__(self, client):
+        self.client = client
+
+    def packs(self, **query):
+        return self.client.request("GET", "/v1/knowledge/packs", query=query)
+
+    def capabilities(self, **query):
+        return self.client.request("GET", "/v1/knowledge/capabilities", query=query)
+
+    def search(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/knowledge/search", json_body=body)
+
+    def lookup_citation(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/knowledge/citations/lookup", json_body=body)
+
+    def verify_answer(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/knowledge/answers/verify", json_body=body)
+

stacklink/logs.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+class LogsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def query(self, **query):
+        return self.requests(**query)
+
+    def summary(self, **query):
+        return self.client.request("GET", "/v1/logs/summary", query=query)
+
+    def requests(self, **query):
+        return self.client.request("GET", "/v1/logs/requests", query=query)
+
+    def tools(self, **query):
+        return self.client.request("GET", "/v1/logs/tools", query=query)
+
+    def triggers(self, **query):
+        return self.client.request("GET", "/v1/logs/triggers", query=query)
+
+    def webhook_deliveries(self, **query):
+        return self.client.request("GET", "/v1/logs/webhook-deliveries", query=query)
+
+    def request_log(self, log_id: str):
+        return self.client.request("GET", f"/v1/logs/requests/{log_id}")
+
+    def tool_log(self, log_id: str):
+        return self.client.request("GET", f"/v1/logs/tools/{log_id}")