stacklink-sdk 0.2.0__py3-none-any.whl

stacklink/tools.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .types import Json, ToolSchemasResponse, ToolSearchResponse
+
+
+class ToolsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def search(self, body: dict[str, Any]) -> ToolSearchResponse:
+        return self.client.request("POST", "/v1/tools/search", json_body=body)
+
+    def search_for_session(self, session_id: str, body: dict[str, Any], *, cache: str = "default") -> ToolSearchResponse:
+        search_body = {
+            "responseMode": "compact",
+            "includeSchemas": False,
+            "includeRelatedTools": False,
+            "includeExecutionPlan": False,
+            **body,
+        }
+        payload = _server_cache_body(search_body, cache)
+        return self.client.cached_request(
+            f"session:{session_id}:search:{_stable_json(_without_cache_control(search_body))}",
+            "POST",
+            f"/v1/sessions/{session_id}/tools/search",
+            json_body=payload,
+            bypass_cache=cache == "bypass",
+        )
+
+    def schemas(self, body: dict[str, Any]) -> ToolSchemasResponse:
+        return self.client.request("POST", "/v1/tools/schemas", json_body=body)
+
+    def schemas_for_session(self, session_id: str, body: dict[str, Any], *, cache: str = "default") -> ToolSchemasResponse:
+        payload = _server_cache_body(body, cache)
+        return self.client.cached_request(
+            f"session:{session_id}:schemas:{_stable_json(_without_cache_control(body))}",
+            "POST",
+            f"/v1/sessions/{session_id}/tools/schemas",
+            json_body=payload,
+            bypass_cache=cache == "bypass",
+        )
+
+    def runtime_contracts(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self.client.request("POST", "/v1/tools/runtime-contracts", json_body=body)
+
+    def runtime_contracts_for_session(self, session_id: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.client.request(
+            "POST",
+            f"/v1/sessions/{session_id}/tools/runtime-contracts",
+            json_body=body or {},
+        )
+
+    def prepare_runtime_for_session(
+        self,
+        session_id: str,
+        *,
+        toolkit_keys: list[str] | None = None,
+        tool_keys: list[str] | None = None,
+        include_planned: bool = False,
+    ) -> dict[str, Any]:
+        return self.runtime_contracts_for_session(session_id, {
+            **({"toolkitKeys": toolkit_keys} if toolkit_keys else {}),
+            **({"toolKeys": tool_keys} if tool_keys else {}),
+            "includePlanned": include_planned,
+        })
+
+    def prepare_for_session(
+        self,
+        session_id: str,
+        *,
+        intents: list[str],
+        include_schemas: bool = True,
+        limit_per_intent: int = 5,
+        include_planned: bool = False,
+        toolkit_key: str | None = None,
+        capability: str | None = None,
+        model: str | None = None,
+        cache: str = "default",
+    ) -> dict[str, Any]:
+        search = self.search_for_session(session_id, {
+            "responseMode": "compact",
+            "includeSchemas": False,
+            "includeRelatedTools": False,
+            "includeExecutionPlan": False,
+            "queries": [
+                {
+                    "query": intent,
+                    "limit": limit_per_intent,
+                    **({"toolkitKey": toolkit_key} if toolkit_key else {}),
+                    **({"capability": capability} if capability else {}),
+                }
+                for intent in intents
+            ],
+            "includePlanned": include_planned,
+            "limit": max(limit_per_intent, len(intents) * limit_per_intent),
+            **({"model": model} if model else {}),
+        }, cache=cache)
+        tools = search.get("tools", []) if isinstance(search, dict) else []
+        tool_keys = []
+        for tool in tools:
+            key = tool.get("key") if isinstance(tool, dict) else None
+            if isinstance(key, str) and key not in tool_keys:
+                tool_keys.append(key)
+        schemas = self.schemas_for_session(
+            session_id,
+            {"toolKeys": tool_keys, "includePlanned": include_planned},
+            cache=cache,
+        ) if include_schemas and tool_keys else {"tools": []}
+        return {
+            "tools": tools,
+            "schemas": schemas.get("tools", []) if isinstance(schemas, dict) else [],
+            "toolKeys": tool_keys,
+            "search": search,
+        }
+
+    def execute(self, body: dict[str, Any]) -> Json:
+        return self.client.request("POST", "/v1/tools/execute", json_body=body)
+
+    def execute_for_session(self, session_id: str, body: dict[str, Any]) -> Json:
+        return self.client.request("POST", f"/v1/sessions/{session_id}/tools/execute", json_body=body)
+
+    def execute_batch(self, body: dict[str, Any]) -> Json:
+        return self.client.request("POST", "/v1/tools/execute-batch", json_body=body)
+
+    def execute_batch_for_session(self, session_id: str, body: dict[str, Any]) -> Json:
+        return self.client.request("POST", f"/v1/sessions/{session_id}/tools/execute-batch", json_body=body)
+
+
+def _without_cache_control(body: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in body.items() if key != "cache"}
+
+
+def _server_cache_body(body: dict[str, Any], cache: str) -> dict[str, Any]:
+    payload = _without_cache_control(body)
+    if cache == "bypass":
+        payload["cache"] = "bypass"
+    return payload
+
+
+def _stable_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)

stacklink/triggers.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class TriggersResource:
+    def __init__(self, client):
+        self.client = client
+
+    def types(self, **query):
+        return self.client.request("GET", "/v1/triggers/types", query=query)
+
+    def list(self, **query):
+        return self.client.request("GET", "/v1/triggers/subscriptions", query=query)
+
+    def create(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/triggers/subscriptions", json_body=body)
+
+    def get(self, subscription_id: str):
+        return self.client.request("GET", f"/v1/triggers/subscriptions/{subscription_id}")
+
+    def update(self, subscription_id: str, body: dict[str, Any]):
+        return self.client.request("PATCH", f"/v1/triggers/subscriptions/{subscription_id}", json_body=body)
+
+    def delete(self, subscription_id: str):
+        return self.client.request("DELETE", f"/v1/triggers/subscriptions/{subscription_id}")
+

stacklink/types.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Literal, Mapping, MutableMapping, Optional, Tuple, TypedDict
+
+Json = Any
+JsonObject = dict[str, Any]
+Headers = Mapping[str, str]
+Transport = Callable[[str, str, Headers, Optional[Json], Mapping[str, Any], float], Tuple[int, MutableMapping[str, str], Json]]
+
+BillingClass = Literal["standard", "premium", "free"]
+BillingUnit = Literal["call", "runtime_10s", "token_block", "byte_block"]
+BillingQuantitySource = Literal["fixed", "duration_ms", "tokens", "bytes"]
+BillingVersion = Literal["stacklink-billing-v1"]
+PricingProductArea = Literal["provider", "knowledge", "model", "workbench", "platform"]
+PricingUnit = Literal[
+    "operation",
+    "call",
+    "1000_calls",
+    "1m_input_tokens",
+    "1m_output_tokens",
+    "1m_reasoning_tokens",
+    "runtime_10s",
+    "byte_block",
+]
+
+StacklinkBillingDescriptor = TypedDict(
+    "StacklinkBillingDescriptor",
+    {
+        "class": BillingClass,
+        "unit": BillingUnit,
+        "multiplier": Literal[1, 2, 3],
+        "quantitySource": BillingQuantitySource,
+        "version": BillingVersion,
+    },
+    total=False,
+)
+
+
+class StacklinkExecutionCapability(TypedDict, total=False):
+    cancellable: Literal["hard", "cooperative", "request_only", "none"]
+    streamingSupport: Literal["none", "progress", "output_delta", "both"]
+    backgroundSupport: Literal["none", "optional", "required"]
+    defaultTimeoutMs: int
+    maxTimeoutMs: int
+
+
+ProviderConnectorType = Literal["app", "platform", "sandbox", "api"]
+ProviderRuntimeKind = Literal["native_api", "native_sdk", "remote_mcp", "managed_mcp_gateway"]
+ProviderRuntimeOwner = Literal["stacklink", "provider", "third_party"]
+ProviderMcpTransport = Literal["streamable_http"]
+ProviderMcpAuthType = Literal["oauth_dcr", "oauth_static_client", "bearer", "none"]
+ProviderMcpImportPolicy = Literal["certified_allowlist", "discover_then_review"]
+ProviderMcpIdentityKind = Literal["user", "workspace", "organization", "project"]
+ProviderMcpResourceKind = Literal[
+    "user",
+    "workspace",
+    "organization",
+    "project",
+    "site",
+    "repository",
+    "channel",
+    "folder",
+    "database",
+]
+ConnectionRequestPhase = Literal[
+    "request_created",
+    "connect_page_opened",
+    "oauth_started",
+    "provider_authorizing",
+    "oauth_callback_received",
+    "token_exchange_started",
+    "account_storing",
+    "remote_mcp_tools_importing",
+    "remote_mcp_tools_imported",
+    "completed",
+    "failed",
+    "expired",
+]
+ConnectionRequestNextAction = Literal[
+    "open_connect_url",
+    "continue_to_provider",
+    "wait_for_user",
+    "wait_for_provider",
+    "wait_for_stacklink",
+    "refresh_toolkits",
+    "retry",
+    "none",
+]
+
+
+class ProviderProfileCapabilityItem(TypedDict):
+    key: str
+    label: str
+    description: str
+
+
+class ProviderProfileCapabilityGroup(TypedDict):
+    key: str
+    title: str
+    items: list[ProviderProfileCapabilityItem]
+
+
+class ProviderProfileDetails(TypedDict, total=False):
+    connectorType: ProviderConnectorType
+    author: Literal["Stacklink"]
+    providerKey: str
+    websiteUrl: str
+    docsUrl: str
+    privacyPolicyUrl: str
+    termsUrl: str
+
+
+class ProviderMarketplaceMetadata(TypedDict):
+    visible: bool
+    connectable: bool
+    recommended: bool
+    internal: bool
+
+
+class ProviderProfile(TypedDict):
+    headline: str
+    summary: str
+    examplePrompts: list[str]
+    capabilityGroups: list[ProviderProfileCapabilityGroup]
+    accessText: str
+    authText: str
+    safetyText: str
+    details: ProviderProfileDetails
+    marketplace: ProviderMarketplaceMetadata
+
+
+class ProviderMcpAuth(TypedDict):
+    type: ProviderMcpAuthType
+
+
+class ProviderMcpIdentity(TypedDict, total=False):
+    strategy: Literal["tool_call"]
+    identityKind: ProviderMcpIdentityKind
+    toolName: str
+    arguments: JsonObject
+    payloadRoot: JsonObject
+    externalAccountIdPath: list[str]
+    displayNamePath: list[str]
+    displayNameTemplate: str
+    metadataPaths: dict[str, list[str]]
+    fallbackDisplayName: str
+    timeoutMs: int
+    contractVersion: int
+
+
+class ProviderMcpResourceParent(TypedDict, total=False):
+    kind: ProviderMcpResourceKind
+    externalResourceIdPath: list[str]
+    labelPath: list[str]
+    labelTemplate: str
+
+
+class ProviderMcpResourceEnrichment(TypedDict, total=False):
+    toolName: str
+    argumentsTemplate: JsonObject
+    payloadRoot: JsonObject
+    metadataPaths: dict[str, list[str]]
+    urlPath: list[str]
+    timeoutMs: int
+
+
+class ProviderMcpResource(TypedDict, total=False):
+    key: str
+    strategy: Literal["tool_call"]
+    resourceKind: ProviderMcpResourceKind
+    toolName: str
+    arguments: JsonObject
+    payloadRoot: JsonObject
+    externalResourceIdPath: list[str]
+    labelPath: list[str]
+    labelTemplate: str
+    parent: ProviderMcpResourceParent
+    metadataPaths: dict[str, list[str]]
+    enrichments: list[ProviderMcpResourceEnrichment]
+    timeoutMs: int
+    maxItems: int
+    contractVersion: int
+
+
+class ProviderMcpRuntime(TypedDict, total=False):
+    endpointUrl: str
+    transport: ProviderMcpTransport
+    auth: ProviderMcpAuth
+    sourceUrl: str
+    importPolicy: ProviderMcpImportPolicy
+    allowlisted: bool
+    identity: ProviderMcpIdentity
+    resources: list[ProviderMcpResource]
+
+
+class ProviderRuntime(TypedDict, total=False):
+    kind: ProviderRuntimeKind
+    owner: ProviderRuntimeOwner
+    label: str
+    mcp: ProviderMcpRuntime
+
+
+class ConnectionRequest(TypedDict, total=False):
+    id: str
+    providerKey: str
+    providerName: str
+    authConfigId: str | None
+    authMode: str | None
+    status: str
+    phase: ConnectionRequestPhase
+    nextAction: ConnectionRequestNextAction
+    redirectUrl: str
+    callbackUrl: str | None
+    failureReason: str | None
+    failureCode: str | None
+    expiresAt: str
+    authModes: list[str]
+    authRequirements: list[JsonObject]
+    connectedAccount: JsonObject | None
+    metadata: Json
+
+
+class PublicPricingSummary(TypedDict, total=False):
+    billingModel: Literal["included", "free", "metered", "token_metered", "custom"]
+    productArea: PricingProductArea
+    unit: PricingUnit
+    unitLabel: str
+    priceMicros: str
+    priceText: str
+    currency: str
+    effectiveFrom: str
+    notes: list[str]
+
+
+class ProviderToolkit(TypedDict, total=False):
+    id: str
+    key: str
+    displayName: str
+    category: str
+    status: str
+    authModes: list[str]
+    capabilities: list[str]
+    metadata: Json
+    brand: Json
+    profile: ProviderProfile
+    runtime: ProviderRuntime
+    pricingSummary: PublicPricingSummary
+    createdAt: str
+    updatedAt: str
+
+
+class ProjectProvider(ProviderToolkit, total=False):
+    providerKey: str
+    name: str
+    projectStatus: str
+    toolCount: int
+    triggerCount: int
+    enabledAt: str | None
+    disabledAt: str | None
+    connection: Json
+    toolkit: ProviderToolkit
+
+
+class ProviderTool(TypedDict, total=False):
+    id: str
+    key: str
+    toolkitKey: str
+    displayName: str
+    description: str
+    capability: str
+    mutationLevel: str
+    status: str
+    inputSchema: Json
+    outputSchema: Json
+    searchDescriptor: Json
+    metadata: Json
+    aliases: list[Json]
+    providerProfile: ProviderProfile
+    execution: StacklinkExecutionCapability
+    billing: StacklinkBillingDescriptor
+
+
+class ToolSearchResponse(TypedDict, total=False):
+    tools: list[ProviderTool]
+    queries: list[Json]
+    meta: Json
+
+
+class ToolSchemasResponse(TypedDict):
+    tools: list[ProviderTool]

stacklink/webhooks.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class WebhooksResource:
+    def __init__(self, client):
+        self.client = client
+
+    def get(self):
+        return self.client.request("GET", "/v1/webhook")
+
+    def update(self, body: dict[str, Any]):
+        return self.client.request("PUT", "/v1/webhook", json_body=body)
+
+    def rotate_secret(self):
+        return self.client.request("POST", "/v1/webhook/rotate-secret")
+
+    def send_test(self, body: dict[str, Any] | None = None):
+        return self.client.request("POST", "/v1/webhook/test", json_body=body or {})
+
+    def retry_delivery(self, delivery_id: str, body: dict[str, Any] | None = None):
+        return self.client.request("POST", f"/v1/webhook-deliveries/{delivery_id}/retry", json_body=body or {})
+
+    def redrive_dead_letters(self, body: dict[str, Any] | None = None):
+        return self.client.request("POST", "/v1/webhook-deliveries/dead-letter/redrive", json_body=body or {})
+
+    def replay_event(self, event_id: str):
+        return self.client.request("POST", f"/v1/events/{event_id}/replay")