weavz-io-sdk 0.1.1__tar.gz

weavz_io_sdk-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,135 @@
+name: Release Python SDK
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build and validate without publishing
+        required: true
+        default: true
+        type: boolean
+      confirm_release:
+        description: Type release-sdk to publish
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+concurrency:
+  group: python-sdk-release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Release weavz-io-sdk
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    environment: pypi-release
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Validate release request
+        run: |
+          if [ "$GITHUB_REF_NAME" != "main" ]; then
+            echo "SDK releases must run from main. Current ref: ${GITHUB_REF_NAME}"
+            exit 1
+          fi
+
+          if [ "$DRY_RUN" = "false" ] && [ "$CONFIRM_RELEASE" != "release-sdk" ]; then
+            echo "Real SDK release requires confirm_release=release-sdk"
+            exit 1
+          fi
+        env:
+          CONFIRM_RELEASE: ${{ inputs.confirm_release }}
+          DRY_RUN: ${{ inputs.dry_run }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build pytest twine
+          python -m pip install -e .
+
+      - name: Run package checks
+        run: |
+          python -m pytest tests/test_generated_integrations.py
+          python -m build
+          python -m twine check dist/*
+
+      - name: Check package version
+        id: package
+        run: |
+          version="$(python - <<'PY'
+          import tomllib
+          with open("pyproject.toml", "rb") as f:
+              print(tomllib.load(f)["project"]["version"])
+          PY
+          )"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+
+          VERSION="$version" python - <<'PY'
+          import os
+          import sys
+          import urllib.error
+          import urllib.request
+
+          version = os.environ["VERSION"]
+          url = f"https://pypi.org/pypi/weavz-io-sdk/{version}/json"
+          try:
+              urllib.request.urlopen(url, timeout=10).close()
+          except urllib.error.HTTPError as exc:
+              if exc.code == 404:
+                  sys.exit(0)
+              raise
+
+          print(f"weavz-io-sdk {version} is already published")
+          sys.exit(1)
+          PY
+
+      - name: Publish to PyPI
+        if: inputs.dry_run == false
+        run: |
+          if [ -z "$TWINE_PASSWORD" ]; then
+            echo "PYPI_API_TOKEN is required for PyPI publishing"
+            exit 1
+          fi
+
+          python -m twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Tag release
+        if: inputs.dry_run == false
+        run: |
+          tag="v${VERSION}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "Git tag ${tag} already exists"
+            exit 1
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "$tag"
+          git push origin "$tag"
+        env:
+          VERSION: ${{ steps.package.outputs.version }}
+
+      - name: Create GitHub release
+        if: inputs.dry_run == false
+        run: |
+          gh release create "v${VERSION}" \
+            --title "weavz-io-sdk v${VERSION}" \
+            --notes "Published weavz-io-sdk ${VERSION} to PyPI."
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.package.outputs.version }}

weavz_io_sdk-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+generated/

weavz_io_sdk-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weavz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

weavz_io_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,480 @@
+Metadata-Version: 2.4
+Name: weavz-io-sdk
+Version: 0.1.1
+Summary: Python SDK for Weavz stateful agent runtime APIs
+Project-URL: Homepage, https://weavz.io
+Project-URL: Repository, https://github.com/weavz/weavz-python-sdk
+Project-URL: Documentation, https://weavz.io/docs/sdks/python
+Project-URL: Issues, https://github.com/weavz/weavz-python-sdk/issues
+Author-email: Weavz <support@weavz.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-runtime,agents,api,filesystem,integrations,mcp,sandbox,sdk,stateful-agents,weavz
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# Weavz Python SDK
+
+Official Python SDK for [Weavz](https://weavz.io), the stateful agent runtime for SaaS and AI products.
+
+Weavz gives your product one API for connection management, end-user identity, hosted connect flows, action execution, triggers, MCP servers, Human Gates, input partials, Filesystem, State KV, Sandbox execution, and 500+ integrations.
+
+## Links
+
+- [Weavz](https://weavz.io)
+- [Dashboard](https://dashboard.weavz.io)
+- [Documentation](https://weavz.io/docs)
+- [Python SDK docs](https://weavz.io/docs/sdks/python)
+- [API reference](https://weavz.io/docs/api-reference)
+- [Integration catalog](https://weavz.io/integrations)
+
+## Installation
+
+```bash
+pip install weavz-io-sdk
+```
+
+The SDK supports Python 3.10 and newer.
+
+```python
+from weavz_sdk import WeavzClient
+
+client = WeavzClient(api_key="wvz_your_api_key")
+```
+
+## What You Can Build
+
+- Hosted OAuth and credential connection flows for your customers
+- Multi-tenant workspaces with per-user, fixed, or fallback connection strategies
+- Validated action execution across integrations such as Slack, GitHub, Google Sheets, HubSpot, Notion, Stripe, and more
+- Remote MCP servers for Claude, ChatGPT, Codex, Cursor, and custom agents
+- Code Mode MCP servers where agents search, inspect, and call workspace integrations dynamically
+- Tool Mode MCP servers with a small explicit tool list
+- Filesystem and State KV for durable files, checkpoints, cursors, and lightweight agent state
+- Sandbox workflows that run JavaScript, Python, or Shell through the runtime
+- Human Gates for approvals before sensitive actions run
+- Input partials for defaults, locked fields, and reusable action configuration
+- Triggers and webhooks that forward integration events into your product
+
+## Quick Start
+
+This example creates a workspace, enables a built-in integration, and executes an action through the SDK.
+
+```python
+from weavz_sdk import WeavzClient
+
+client = WeavzClient(api_key="wvz_your_api_key")
+
+workspace = client.workspaces.create(
+    name="Production",
+    slug="production",
+)["workspace"]
+
+client.workspaces.add_integration(
+    workspace["id"],
+    integration_name="hash-encode",
+    integration_alias="hash",
+)
+
+result = client.actions.execute(
+    "hash-encode",
+    "hash",
+    workspace_id=workspace["id"],
+    integration_alias="hash",
+    input={
+        "text": "hello from weavz",
+        "algorithm": "sha256",
+        "encoding": "hex",
+    },
+)
+
+if result["success"]:
+    print(result["output"])
+
+client.close()
+```
+
+For a guided Slack setup, see the [Quick Start](https://weavz.io/docs/getting-started/quick-start).
+
+## Configuration
+
+```python
+client = WeavzClient(
+    api_key="wvz_your_api_key",
+    base_url="https://platform.weavz.io",
+    timeout=310.0,
+    max_retries=2,
+)
+```
+
+| Option | Required | Default | Description |
+| --- | --- | --- | --- |
+| `api_key` | Yes | - | Weavz API key with the `wvz_` prefix |
+| `base_url` | No | `https://platform.weavz.io` | API base URL |
+| `timeout` | No | `310.0` | Request timeout in seconds |
+| `max_retries` | No | `2` | Retry count for transient failures |
+
+Use the context manager to close the underlying HTTP client automatically:
+
+```python
+with WeavzClient(api_key="wvz_your_api_key") as client:
+    result = client.connections.list()
+    print(result["connections"])
+```
+
+## Core Product Flows
+
+### Workspaces And Integration Aliases
+
+Workspaces scope connections, integration configuration, MCP servers, partials, triggers, and end-user access. Add integrations to a workspace under purpose-readable aliases so agents and logs show stable names.
+
+```python
+workspace = client.workspaces.create(
+    name="Acme Customer",
+    slug="acme-customer",
+)["workspace"]
+
+client.workspaces.add_integration(
+    workspace["id"],
+    integration_name="slack",
+    integration_alias="customer_slack",
+    connection_strategy="per_user",
+    enabled_actions=["send_channel_message"],
+)
+```
+
+Read more:
+
+- [Organizations and workspaces](https://weavz.io/docs/concepts/organizations-and-workspaces)
+- [Workspace integrations](https://weavz.io/docs/concepts/integration-selectors)
+- [Integration aliases](https://weavz.io/docs/guides/integration-aliases)
+
+### Hosted Connect
+
+Create a hosted connect session when an end user needs to connect Slack, Google, GitHub, or another integration account.
+
+```python
+session = client.connect.create_token(
+    integration_name="slack",
+    connection_name="Acme Slack",
+    external_id="acme_slack",
+    workspace_id=workspace["id"],
+    end_user_id="user_123",
+)
+
+print(f"Send the user here: {session['connectUrl']}")
+
+completed = client.connect.wait(
+    session["token"],
+    timeout=120.0,
+    interval=1.0,
+)
+
+if completed["status"] == "COMPLETED":
+    print(completed["connectionId"])
+```
+
+Read more:
+
+- [Connections](https://weavz.io/docs/concepts/connections)
+- [Hosted connect API](https://weavz.io/docs/api-reference/oauth)
+- [Setting up connections](https://weavz.io/docs/guides/setting-up-connections)
+
+### Execute Actions
+
+Execute integration actions directly from your backend or product workflows.
+
+```python
+run = client.actions.execute(
+    "slack",
+    "send_channel_message",
+    workspace_id=workspace["id"],
+    integration_alias="customer_slack",
+    end_user_id="user_123",
+    input={
+        "channel": "#support",
+        "text": "New customer escalation received.",
+    },
+    idempotency_key="ticket_123_notify_slack",
+)
+
+if run.get("status") == "approval_required":
+    print("Approval required:", run["approval"]["id"])
+else:
+    print("Action output:", run["output"])
+```
+
+Read more:
+
+- [Actions](https://weavz.io/docs/concepts/actions)
+- [Executing actions](https://weavz.io/docs/guides/executing-actions)
+- [Actions API reference](https://weavz.io/docs/api-reference/actions)
+
+### MCP Servers For Agents
+
+Create remote MCP servers that expose workspace integrations to AI agents. Code Mode is the best default for broad agent workspaces; Tool Mode is useful for small explicit tool surfaces.
+
+```python
+result = client.mcp_servers.create(
+    name="Acme Agent Workspace",
+    mode="CODE",
+    workspace_id=workspace["id"],
+    auth_mode="oauth_and_bearer",
+    end_user_access="restricted",
+    settings={
+        "codeMode": {
+            "approvalWaitSeconds": 30,
+        },
+    },
+)
+
+server = result["server"]
+mcp_endpoint = result["mcpEndpoint"]
+
+token_result = client.mcp_servers.create_bearer_token(
+    server["id"],
+    end_user_id="user_123",
+    scopes=["mcp:tools", "mcp:code"],
+    expires_in=60 * 60 * 24 * 30,
+)
+
+print(mcp_endpoint, token_result["bearerToken"])
+```
+
+You can also run Code Mode directly through the SDK:
+
+```python
+code_run = client.mcp_servers.execute_code(
+    server["id"],
+    """
+const parsed = await weavz.datetime.parse_date({
+  dateString: "June 18, 2026 9am",
+  timezone: "America/New_York"
+})
+
+return { parsed }
+""",
+)
+```
+
+Code Mode responses include `structuredContent.timings` for total execution and per-action latency.
+For Agent Browser workflows, batch several browser actions inside one Code Mode script instead of
+calling `execute_code()` once per click or screenshot.
+
+Read more:
+
+- [MCP servers](https://weavz.io/docs/concepts/mcp-servers)
+- [MCP Code Mode](https://weavz.io/docs/guides/mcp-code-mode)
+- [MCP Tool Mode](https://weavz.io/docs/guides/mcp-tool-mode)
+- [Weavz MCP App](https://weavz.io/docs/guides/weavz-mcp-app)
+
+### Human Gates
+
+Human Gates let you require approval before sensitive actions execute.
+
+```python
+policy = client.approval_policies.create(
+    workspace_id=workspace["id"],
+    name="Approve external messages",
+    sources=["sdk", "mcp_code", "mcp_tools"],
+    decision="require_approval",
+    risk_mode="always",
+    approvers=[{"type": "org_role", "roles": ["owner", "admin"]}],
+    timeout_seconds=3600,
+    default_on_timeout="reject",
+    approval_access_mode="dashboard_and_hosted_link",
+)["policy"]
+
+guarded = client.actions.execute(
+    "slack",
+    "send_channel_message",
+    workspace_id=workspace["id"],
+    integration_alias="customer_slack",
+    end_user_id="user_123",
+    input={"channel": "#general", "text": "Launch update"},
+)
+
+if guarded.get("status") == "approval_required":
+    client.approvals.approve(
+        guarded["approval"]["id"],
+        reason="Message reviewed",
+    )
+```
+
+Read more:
+
+- [Human Gates guide](https://weavz.io/docs/guides/human-gates)
+- [Approvals API reference](https://weavz.io/docs/api-reference/approvals)
+
+### Input Partials
+
+Input partials let you reuse defaults and lock enforced fields so agents or callers only provide the fields they should control.
+
+```python
+partial = client.partials.create(
+    workspace["id"],
+    "slack",
+    "Support channel default",
+    action_name="send_channel_message",
+    values={"channel": "#support"},
+    enforced_keys=["channel"],
+)["partial"]
+
+client.actions.execute(
+    "slack",
+    "send_channel_message",
+    workspace_id=workspace["id"],
+    integration_alias="customer_slack",
+    partial_ids=[partial["id"]],
+    input={"text": "A new ticket needs attention."},
+)
+```
+
+Read more:
+
+- [Input partials](https://weavz.io/docs/concepts/input-partials)
+- [Using input partials](https://weavz.io/docs/guides/using-input-partials)
+
+### Triggers
+
+Enable triggers to receive integration events in your own webhook endpoint.
+
+```python
+trigger = client.triggers.enable(
+    integration_name="github",
+    trigger_name="new_push",
+    workspace_id=workspace["id"],
+    integration_alias="customer_github",
+    callback_url="https://yourapp.example.com/webhooks/weavz/github",
+    callback_metadata={"customerId": "acme"},
+)["triggerSource"]
+
+print(trigger["id"])
+```
+
+Read more:
+
+- [Triggers](https://weavz.io/docs/concepts/triggers)
+- [Setting up triggers](https://weavz.io/docs/guides/setting-up-triggers)
+
+## Generated Integration Input Models
+
+The SDK includes generated Pydantic models and lookup helpers for integration action inputs.
+
+```python
+from weavz_sdk.integrations import (
+    INTEGRATION_ACTIONS,
+    SlackSendChannelMessageInput,
+    get_action_names,
+    validate_action_input,
+)
+
+print(get_action_names("slack"))
+print(INTEGRATION_ACTIONS["slack"])
+
+input_data = SlackSendChannelMessageInput(
+    channel="#general",
+    text="Typed input from Python",
+)
+
+validated = validate_action_input(
+    "slack",
+    "send_channel_message",
+    input_data,
+)
+
+result = client.actions.execute_typed(
+    "slack",
+    "send_channel_message",
+    workspace_id=workspace["id"],
+    integration_alias="customer_slack",
+    input=validated,
+)
+```
+
+The model naming pattern is `{IntegrationName}{ActionName}Input` in PascalCase. Use `execute()` for dynamic or future integrations and `execute_typed()` when you want generated-model validation before the request is sent.
+
+## AI Framework Adapters
+
+MCP is the primary hosted agent surface. The SDK also includes small dependency-free adapters that convert configured workspace actions into common AI tool shapes.
+
+```python
+from weavz_sdk import (
+    create_mcp_server_action_tools,
+    to_anthropic_tool,
+    to_openai_responses_tool,
+)
+
+tools = create_mcp_server_action_tools(client, server["id"])
+
+openai_tools = [to_openai_responses_tool(tool) for tool in tools]
+anthropic_tools = [to_anthropic_tool(tool) for tool in tools]
+```
+
+Optional framework adapters are created lazily when the matching package is installed.
+
+## Resource Map
+
+| Resource | Purpose |
+| --- | --- |
+| `client.workspaces` | Workspace management and workspace integrations |
+| `client.connections` | Connection CRUD and resolution |
+| `client.connect` | Hosted connect session creation, polling, and waiting |
+| `client.actions` | Integration action execution and generated input validation |
+| `client.triggers` | Trigger enablement, listing, testing, and disabling |
+| `client.mcp_servers` | MCP servers, tools, tokens, Code Mode execution, declarations |
+| `client.integrations` | Integration metadata, property options, OAuth status |
+| `client.end_users` | End-user identity, connect tokens, invites |
+| `client.partials` | Input partial presets and enforced fields |
+| `client.approval_policies` | Human Gates policy management |
+| `client.approvals` | Approval inbox, decisions, and waiting |
+| `client.api_keys` | Customer-facing API key management |
+
+## Error Handling
+
+```python
+from weavz_sdk import WeavzError
+
+try:
+    client.actions.execute(
+        "slack",
+        "send_channel_message",
+        workspace_id=workspace["id"],
+        integration_alias="customer_slack",
+        input={"channel": "#general", "text": "Hello"},
+    )
+except WeavzError as error:
+    print(error.code)
+    print(error.status)
+    print(error.details)
+```
+
+## Publishing And Development
+
+This public repository is a release mirror. SDK development happens in the main Weavz monorepo under `sdks/python/`, then this repository is updated from that source directory for releases.
+
+For local checks in this repository:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e . pytest
+python -m pytest tests/test_generated_integrations.py
+```
+
+Live integration tests require a running Weavz API stack.
+
+## License
+
+[MIT](LICENSE)