stacklink-sdk 0.2.0__tar.gz

stacklink_sdk-0.2.0/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2026 Stacklink. All rights reserved.
+
+This software is proprietary. You may install and use it only to access
+Stacklink services under an agreement with Stacklink. You may not copy,
+modify, redistribute, sublicense, sell, or otherwise make this software
+available to another party except where your agreement with Stacklink
+expressly permits it.
+
+This notice must remain with every permitted copy.

stacklink_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: stacklink-sdk
+Version: 0.2.0
+Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
+Author: Stacklink
+License-Expression: LicenseRef-Proprietary
+Project-URL: Documentation, https://docs.stacklink.in/docs/quickstart
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2.0; extra == "openai"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents<0.19,>=0.18; extra == "openai-agents"
+Provides-Extra: claude-agent
+Requires-Dist: claude-agent-sdk<0.3,>=0.2; extra == "claude-agent"
+Dynamic: license-file
+
+# Stacklink Python SDK
+
+Stacklink supplies executable, governed tools to an agent harness. The selected harness owns the model call, tool loop, and final answer.
+
+Install the public package with the harness extra you use:
+
+```bash
+uv add 'stacklink-sdk[openai-agents]'
+```
+
+or:
+
+```bash
+uv add 'stacklink-sdk[claude-agent]'
+```
+
+The complete guides and certified recipes live at [docs.stacklink.in](https://docs.stacklink.in/docs/quickstart). PyPI is the package delivery system, not the primary documentation surface. Stacklink does not display registry download badges in its product or documentation.
+
+## Certified agent harnesses
+
+| Harness | Stacklink adapter |
+|---|---|
+| OpenAI Agents SDK | `create_stacklink_openai_agents_tools(session)` |
+| Claude Agent SDK | `create_stacklink_claude_agent_tool_config(session)` |
+
+Both start with one explicit Stacklink session:
+
+```python
+import os
+from stacklink import Stacklink
+
+stacklink = Stacklink(
+    api_key=os.environ['STACKLINK_API_KEY'],
+    base_url=os.getenv('STACKLINK_BASE_URL', 'https://api.stacklink.in'),
+)
+session = stacklink.sessions.create_bound({
+    'externalTenantId': 'acme',
+    'externalUserId': 'user_123',
+    'metaTools': {'surface': 'connector'},
+})
+
+try:
+    # Pass the selected Stacklink adapter output to your agent harness.
+    pass
+finally:
+    session.close()
+```
+
+The complete OpenAI Agents and Claude Agent examples shown by the Stacklink Overview are generated from the executable files under `examples/sdk/`. The dashboard, documentation, and certification tests all read those same files.
+
+The raw OpenAI `with_stacklink_memory` helper remains a separate Memory integration. It is not the agent-tool integration and is not part of basic Overview onboarding.
+
+Environment variables are `STACKLINK_API_KEY`, optional `STACKLINK_BASE_URL`, and the model-provider credentials required by the selected harness. The SDK is proprietary and is provided under the applicable Stacklink agreement.

stacklink_sdk-0.2.0/README.md

@@ -0,0 +1,53 @@
+# Stacklink Python SDK
+
+Stacklink supplies executable, governed tools to an agent harness. The selected harness owns the model call, tool loop, and final answer.
+
+Install the public package with the harness extra you use:
+
+```bash
+uv add 'stacklink-sdk[openai-agents]'
+```
+
+or:
+
+```bash
+uv add 'stacklink-sdk[claude-agent]'
+```
+
+The complete guides and certified recipes live at [docs.stacklink.in](https://docs.stacklink.in/docs/quickstart). PyPI is the package delivery system, not the primary documentation surface. Stacklink does not display registry download badges in its product or documentation.
+
+## Certified agent harnesses
+
+| Harness | Stacklink adapter |
+|---|---|
+| OpenAI Agents SDK | `create_stacklink_openai_agents_tools(session)` |
+| Claude Agent SDK | `create_stacklink_claude_agent_tool_config(session)` |
+
+Both start with one explicit Stacklink session:
+
+```python
+import os
+from stacklink import Stacklink
+
+stacklink = Stacklink(
+    api_key=os.environ['STACKLINK_API_KEY'],
+    base_url=os.getenv('STACKLINK_BASE_URL', 'https://api.stacklink.in'),
+)
+session = stacklink.sessions.create_bound({
+    'externalTenantId': 'acme',
+    'externalUserId': 'user_123',
+    'metaTools': {'surface': 'connector'},
+})
+
+try:
+    # Pass the selected Stacklink adapter output to your agent harness.
+    pass
+finally:
+    session.close()
+```
+
+The complete OpenAI Agents and Claude Agent examples shown by the Stacklink Overview are generated from the executable files under `examples/sdk/`. The dashboard, documentation, and certification tests all read those same files.
+
+The raw OpenAI `with_stacklink_memory` helper remains a separate Memory integration. It is not the agent-tool integration and is not part of basic Overview onboarding.
+
+Environment variables are `STACKLINK_API_KEY`, optional `STACKLINK_BASE_URL`, and the model-provider credentials required by the selected harness. The SDK is proprietary and is provided under the applicable Stacklink agreement.

stacklink_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stacklink-sdk"
+version = "0.2.0"
+description = "Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing."
+readme = "README.md"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Stacklink" }]
+dependencies = []
+
+[project.urls]
+Documentation = "https://docs.stacklink.in/docs/quickstart"
+
+[project.optional-dependencies]
+openai = ["openai>=2.0,<3"]
+openai-agents = ["openai-agents>=0.18,<0.19"]
+claude-agent = ["claude-agent-sdk>=0.2,<0.3"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stacklink*"]

stacklink_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stacklink_sdk-0.2.0/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_sdk-0.2.0/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_sdk-0.2.0/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_sdk-0.2.0/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_sdk-0.2.0/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_sdk-0.2.0/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_sdk-0.2.0/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