stacklink-sdk 0.2.0__tar.gz → 0.2.2__tar.gz

{stacklink_sdk-0.2.0/stacklink_sdk.egg-info → stacklink_sdk-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -8,6 +8,7 @@ Project-URL: Documentation, https://docs.stacklink.in/docs/quickstart
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: httpx[http2]<1,>=0.27
 Provides-Extra: openai
 Requires-Dist: openai<3,>=2.0; extra == "openai"
 Provides-Extra: openai-agents
@@ -54,7 +55,7 @@ stacklink = Stacklink(
 session = stacklink.sessions.create_bound({
     'externalTenantId': 'acme',
     'externalUserId': 'user_123',
-    'metaTools': {'surface': 'connector'},
+    'modelSurface': {'mode': 'router'},
 })
 
 try:
@@ -69,3 +70,15 @@ The complete OpenAI Agents and Claude Agent examples shown by the Stacklink Over
 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.
+
+## Accepted operations, approvals and retries
+
+An execution response can be pending. Keep its `executionKind`, `executionId`, session ID and retry key in your application. Read or wait for that operation using the existing execution APIs. A lost connection does not submit a second action, and closing the application session can remove the authority required to execute pending work.
+
+Retry keys are case-sensitive and accept up to 240 characters. Tool and batch requests have separate key namespaces. Reuse a key only for the exact same request in the same SDK session. Changed inputs return `409 idempotency_key_reused`; an expired stored result returns `410 execution_result_expired`. Neither response authorizes submitting the write again.
+
+For `waiting_for_approval`, your backend can use the session approval read, approve and deny APIs with `platform_approvals:read` / `platform_approvals:manage` scopes. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
+
+Use execution cancellation for an explicit Stop request. Losing a stream only stops observation. Vercel and LangChain adapters forward their supported abort signal; other adapters keep the structured operation identity available for explicit cancellation. MCP progress reports actual stages, not invented percentages.
+
+Streaming has a total observation deadline and a separate inactivity timeout. A timeout raises `sdk_stream_timeout` without repeating the action; use its original operation ID to resume observation. Stream responses are limited to 8 MiB, including JSON responses to streaming requests. The synchronous client keeps blocking reads in a bounded reader and releases the response when that read finishes or reaches its inactivity timeout. Custom transports must honor the timeout passed to them. MCP calls return once all matching responses arrive, even if the server keeps the stream open.

stacklink_sdk-0.2.2/README.md

@@ -0,0 +1,65 @@
+# 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',
+    'modelSurface': {'mode': 'router'},
+})
+
+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.
+
+## Accepted operations, approvals and retries
+
+An execution response can be pending. Keep its `executionKind`, `executionId`, session ID and retry key in your application. Read or wait for that operation using the existing execution APIs. A lost connection does not submit a second action, and closing the application session can remove the authority required to execute pending work.
+
+Retry keys are case-sensitive and accept up to 240 characters. Tool and batch requests have separate key namespaces. Reuse a key only for the exact same request in the same SDK session. Changed inputs return `409 idempotency_key_reused`; an expired stored result returns `410 execution_result_expired`. Neither response authorizes submitting the write again.
+
+For `waiting_for_approval`, your backend can use the session approval read, approve and deny APIs with `platform_approvals:read` / `platform_approvals:manage` scopes. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
+
+Use execution cancellation for an explicit Stop request. Losing a stream only stops observation. Vercel and LangChain adapters forward their supported abort signal; other adapters keep the structured operation identity available for explicit cancellation. MCP progress reports actual stages, not invented percentages.
+
+Streaming has a total observation deadline and a separate inactivity timeout. A timeout raises `sdk_stream_timeout` without repeating the action; use its original operation ID to resume observation. Stream responses are limited to 8 MiB, including JSON responses to streaming requests. The synchronous client keeps blocking reads in a bounded reader and releases the response when that read finishes or reaches its inactivity timeout. Custom transports must honor the timeout passed to them. MCP calls return once all matching responses arrive, even if the server keeps the stream open.

{stacklink_sdk-0.2.0 → stacklink_sdk-0.2.2}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.2.0"
+version = "0.2.2"
 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 = []
+dependencies = ["httpx[http2]>=0.27,<1"]
 
 [project.urls]
 Documentation = "https://docs.stacklink.in/docs/quickstart"

{stacklink_sdk-0.2.0 → stacklink_sdk-0.2.2}/stacklink/__init__.py

@@ -1,12 +1,16 @@
 from __future__ import annotations
 
-from .client import STACKLINK_PYTHON_SDK_VERSION, Stacklink
+from .client import AsyncStacklink, 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,
+    ProviderCatalogItem,
+    ProviderCatalogPage,
+    ProviderToolCatalogItem,
+    ProviderToolCatalogPage,
     ProviderMarketplaceMetadata,
     ProviderProfile,
     ProviderProfileCapabilityGroup,
@@ -21,6 +25,7 @@ from .types import (
 
 __all__ = [
     "Stacklink",
+    "AsyncStacklink",
     "STACKLINK_PYTHON_SDK_VERSION",
     "StacklinkError",
     "RateLimitError",
@@ -29,6 +34,10 @@ __all__ = [
     "create_stacklink_openai_agents_tools",
     "create_stacklink_claude_agent_tool_config",
     "ProjectProvider",
+    "ProviderCatalogItem",
+    "ProviderCatalogPage",
+    "ProviderToolCatalogItem",
+    "ProviderToolCatalogPage",
     "ProviderMarketplaceMetadata",
     "ProviderProfile",
     "ProviderProfileCapabilityGroup",