zamp-sdk 0.0.2__tar.gz

zamp_sdk-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Zamp
+
+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.

zamp_sdk-0.0.2/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: zamp-sdk
+Version: 0.0.2
+Summary: Customer-facing SDK for executing actions on the Zamp platform
+License: MIT
+License-File: LICENSE
+Keywords: zamp,sdk,actions,automation
+Author: Zamp Engineering
+Author-email: engineering@zamp.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: aiohttp
+Requires-Dist: pydantic
+Requires-Dist: structlog
+Project-URL: Changelog, https://github.com/Zampfi/zamp-sdk/releases
+Project-URL: Documentation, https://github.com/Zampfi/zamp-sdk#readme
+Project-URL: Homepage, https://github.com/Zampfi/zamp-sdk
+Project-URL: Issues, https://github.com/Zampfi/zamp-sdk/issues
+Project-URL: Repository, https://github.com/Zampfi/zamp-sdk
+Description-Content-Type: text/markdown
+
+# Zamp SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/zamp-sdk.svg)](https://pypi.org/project/zamp-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/zamp-sdk.svg)](https://pypi.org/project/zamp-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The official Python SDK for executing actions on the [Zamp](https://zamp.ai) platform.
+
+## Installation
+
+```bash
+pip install zamp-sdk
+```
+
+Or with [Poetry](https://python-poetry.org/):
+
+```bash
+poetry add zamp-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from zamp_sdk import ActionExecutor
+
+async def main():
+    result = await ActionExecutor.execute(
+        "send_invoice",
+        {"invoice_id": "inv_123"},
+        base_url="https://api.zamp.ai",
+        auth_token="your-api-token",
+    )
+    print(result)
+
+asyncio.run(main())
+```
+
+### Using environment variables
+
+Set `ZAMP_BASE_URL` and `ZAMP_AUTH_TOKEN` in your environment, then call without explicit config:
+
+```python
+result = await ActionExecutor.execute("send_invoice", {"invoice_id": "inv_123"})
+```
+
+## API Reference
+
+### `ActionExecutor.execute()`
+
+```python
+@staticmethod
+async def execute(
+    action_name: str,
+    params: Any,
+    *,
+    base_url: str | None = None,
+    auth_token: str | None = None,
+    summary: str | None = None,
+    return_type: type | None = None,
+    action_retry_policy: RetryPolicy | None = None,
+    action_start_to_close_timeout: timedelta | None = None,
+) -> Any
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action_name` | `str` | Yes | Name of the registered action to execute |
+| `params` | `Any` | Yes | Input parameters for the action |
+| `base_url` | `str \| None` | No | Zamp API base URL. Falls back to `ZAMP_BASE_URL` env var |
+| `auth_token` | `str \| None` | No | API authentication token. Falls back to `ZAMP_AUTH_TOKEN` env var |
+| `summary` | `str \| None` | No | Human-readable description of the execution |
+| `return_type` | `type \| None` | No | Pydantic model to validate the result against |
+| `action_retry_policy` | `RetryPolicy \| None` | No | Retry configuration for the action |
+| `action_start_to_close_timeout` | `timedelta \| None` | No | Maximum execution time for the action |
+
+### `RetryPolicy`
+
+```python
+from zamp_sdk import RetryPolicy
+
+policy = RetryPolicy(
+    initial_interval=timedelta(seconds=30),
+    maximum_attempts=11,
+    maximum_interval=timedelta(minutes=15),
+    backoff_coefficient=1.5,
+)
+
+# Or use the default configuration:
+policy = RetryPolicy.default()
+```
+
+| Field | Type | Default (via `.default()`) |
+|-------|------|---------------------------|
+| `initial_interval` | `timedelta` | 30 seconds |
+| `maximum_attempts` | `int` | 11 |
+| `maximum_interval` | `timedelta` | 15 minutes |
+| `backoff_coefficient` | `float` | 1.5 |
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `ZAMP_BASE_URL` | Base URL of the Zamp API (e.g. `https://api.zamp.ai`) |
+| `ZAMP_AUTH_TOKEN` | API authentication token |
+
+Explicit parameters passed to `ActionExecutor.execute()` take precedence over environment variables.
+
+## Error Handling
+
+| Exception | When |
+|-----------|------|
+| `HttpClientError` | HTTP request fails (non-2xx status, network error, timeout) |
+| `RuntimeError` | Action reaches a terminal failure state (FAILED, CANCELED, TERMINATED, TIMED_OUT) |
+| `TimeoutError` | Polling for action result exceeds the timeout limit |
+| `KeyError` | Required environment variable is missing and no explicit value was provided |
+
+```python
+from zamp_sdk.action_executor.utils import HttpClientError
+
+try:
+    result = await ActionExecutor.execute("my_action", params)
+except HttpClientError as e:
+    print(f"HTTP error {e.status_code}: {e.message}")
+except RuntimeError as e:
+    print(f"Action failed: {e}")
+except TimeoutError as e:
+    print(f"Timed out: {e}")
+```
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Zampfi/zamp-sdk.git
+cd zamp-sdk
+make install
+
+# Run all checks (lint + type-check + tests)
+make check
+
+# Individual targets
+make lint          # ruff check + format check
+make lint-fix      # auto-fix lint issues
+make format        # format code
+make type-check    # mypy
+make test          # pytest with coverage
+make clean         # remove build artifacts
+```
+
+## Contributing
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Run `make check` to verify lint, type-check, and tests pass
+4. Open a pull request
+
+Pre-commit hooks are configured -- install them with:
+
+```bash
+poetry run pre-commit install
+```
+
+## License
+
+[MIT](LICENSE)
+

zamp_sdk-0.0.2/README.md

@@ -0,0 +1,166 @@
+# Zamp SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/zamp-sdk.svg)](https://pypi.org/project/zamp-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/zamp-sdk.svg)](https://pypi.org/project/zamp-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The official Python SDK for executing actions on the [Zamp](https://zamp.ai) platform.
+
+## Installation
+
+```bash
+pip install zamp-sdk
+```
+
+Or with [Poetry](https://python-poetry.org/):
+
+```bash
+poetry add zamp-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from zamp_sdk import ActionExecutor
+
+async def main():
+    result = await ActionExecutor.execute(
+        "send_invoice",
+        {"invoice_id": "inv_123"},
+        base_url="https://api.zamp.ai",
+        auth_token="your-api-token",
+    )
+    print(result)
+
+asyncio.run(main())
+```
+
+### Using environment variables
+
+Set `ZAMP_BASE_URL` and `ZAMP_AUTH_TOKEN` in your environment, then call without explicit config:
+
+```python
+result = await ActionExecutor.execute("send_invoice", {"invoice_id": "inv_123"})
+```
+
+## API Reference
+
+### `ActionExecutor.execute()`
+
+```python
+@staticmethod
+async def execute(
+    action_name: str,
+    params: Any,
+    *,
+    base_url: str | None = None,
+    auth_token: str | None = None,
+    summary: str | None = None,
+    return_type: type | None = None,
+    action_retry_policy: RetryPolicy | None = None,
+    action_start_to_close_timeout: timedelta | None = None,
+) -> Any
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action_name` | `str` | Yes | Name of the registered action to execute |
+| `params` | `Any` | Yes | Input parameters for the action |
+| `base_url` | `str \| None` | No | Zamp API base URL. Falls back to `ZAMP_BASE_URL` env var |
+| `auth_token` | `str \| None` | No | API authentication token. Falls back to `ZAMP_AUTH_TOKEN` env var |
+| `summary` | `str \| None` | No | Human-readable description of the execution |
+| `return_type` | `type \| None` | No | Pydantic model to validate the result against |
+| `action_retry_policy` | `RetryPolicy \| None` | No | Retry configuration for the action |
+| `action_start_to_close_timeout` | `timedelta \| None` | No | Maximum execution time for the action |
+
+### `RetryPolicy`
+
+```python
+from zamp_sdk import RetryPolicy
+
+policy = RetryPolicy(
+    initial_interval=timedelta(seconds=30),
+    maximum_attempts=11,
+    maximum_interval=timedelta(minutes=15),
+    backoff_coefficient=1.5,
+)
+
+# Or use the default configuration:
+policy = RetryPolicy.default()
+```
+
+| Field | Type | Default (via `.default()`) |
+|-------|------|---------------------------|
+| `initial_interval` | `timedelta` | 30 seconds |
+| `maximum_attempts` | `int` | 11 |
+| `maximum_interval` | `timedelta` | 15 minutes |
+| `backoff_coefficient` | `float` | 1.5 |
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `ZAMP_BASE_URL` | Base URL of the Zamp API (e.g. `https://api.zamp.ai`) |
+| `ZAMP_AUTH_TOKEN` | API authentication token |
+
+Explicit parameters passed to `ActionExecutor.execute()` take precedence over environment variables.
+
+## Error Handling
+
+| Exception | When |
+|-----------|------|
+| `HttpClientError` | HTTP request fails (non-2xx status, network error, timeout) |
+| `RuntimeError` | Action reaches a terminal failure state (FAILED, CANCELED, TERMINATED, TIMED_OUT) |
+| `TimeoutError` | Polling for action result exceeds the timeout limit |
+| `KeyError` | Required environment variable is missing and no explicit value was provided |
+
+```python
+from zamp_sdk.action_executor.utils import HttpClientError
+
+try:
+    result = await ActionExecutor.execute("my_action", params)
+except HttpClientError as e:
+    print(f"HTTP error {e.status_code}: {e.message}")
+except RuntimeError as e:
+    print(f"Action failed: {e}")
+except TimeoutError as e:
+    print(f"Timed out: {e}")
+```
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Zampfi/zamp-sdk.git
+cd zamp-sdk
+make install
+
+# Run all checks (lint + type-check + tests)
+make check
+
+# Individual targets
+make lint          # ruff check + format check
+make lint-fix      # auto-fix lint issues
+make format        # format code
+make type-check    # mypy
+make test          # pytest with coverage
+make clean         # remove build artifacts
+```
+
+## Contributing
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Run `make check` to verify lint, type-check, and tests pass
+4. Open a pull request
+
+Pre-commit hooks are configured -- install them with:
+
+```bash
+poetry run pre-commit install
+```
+
+## License
+
+[MIT](LICENSE)

zamp_sdk-0.0.2/pyproject.toml

@@ -0,0 +1,74 @@
+[tool.poetry]
+name = "zamp-sdk"
+version = "0.0.2"
+description = "Customer-facing SDK for executing actions on the Zamp platform"
+authors = ["Zamp Engineering <engineering@zamp.com>"]
+readme = "README.md"
+packages = [{include = "zamp_sdk"}]
+license = "MIT"
+keywords = ["zamp", "sdk", "actions", "automation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+    "Framework :: AsyncIO",
+]
+
+[tool.poetry.urls]
+Homepage = "https://github.com/Zampfi/zamp-sdk"
+Documentation = "https://github.com/Zampfi/zamp-sdk#readme"
+Repository = "https://github.com/Zampfi/zamp-sdk"
+Issues = "https://github.com/Zampfi/zamp-sdk/issues"
+Changelog = "https://github.com/Zampfi/zamp-sdk/releases"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+aiohttp = "*"
+pydantic = "*"
+structlog = "*"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "*"
+pytest-asyncio = "*"
+pytest-cov = "*"
+ruff = "*"
+mypy = "*"
+pre-commit = "*"
+diff-cover = "*"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = false
+show_error_codes = true
+show_column_numbers = true
+show_error_context = true
+pretty = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["zamp_sdk", "tests"]
+addopts = "--cov=zamp_sdk --cov-report=xml --cov-report=term-missing --cov-fail-under=80"
+
+[tool.coverage.run]
+relative_files = true
+source = ["zamp_sdk"]
+omit = ["*/tests/*"]

zamp_sdk-0.0.2/zamp_sdk/__init__.py

@@ -0,0 +1,4 @@
+from zamp_sdk.action_executor import ActionExecutor
+from zamp_sdk.action_executor.models import RetryPolicy, SdkConfig
+
+__all__ = ["ActionExecutor", "RetryPolicy", "SdkConfig"]

zamp_sdk-0.0.2/zamp_sdk/action_executor/__init__.py

@@ -0,0 +1,3 @@
+from zamp_sdk.action_executor.action_executor import ActionExecutor
+
+__all__ = ["ActionExecutor"]

zamp_sdk-0.0.2/zamp_sdk/action_executor/action_executor.py

@@ -0,0 +1,119 @@
+import asyncio
+import os
+from datetime import timedelta
+from typing import Any
+
+from zamp_sdk.action_executor.constants import (
+    IN_PROGRESS_STATUSES,
+    POLL_INITIAL_INTERVAL_SECONDS,
+    POLL_MAX_INTERVAL_SECONDS,
+    POLL_TIMEOUT_SECONDS,
+    SUCCESS_STATUSES,
+    TERMINAL_FAILURE_STATUSES,
+)
+from zamp_sdk.action_executor.models import RetryPolicy, SdkConfig
+from zamp_sdk.action_executor.utils import HttpClient
+
+
+class ActionExecutor:
+    """Entry point for executing actions on the Zamp platform.
+
+    Configuration can be supplied explicitly via ``base_url`` / ``auth_token``
+    keyword arguments, or read automatically from the ``ZAMP_BASE_URL`` and
+    ``ZAMP_AUTH_TOKEN`` environment variables.
+    """
+
+    def _resolve_config(
+        self,
+        base_url: str | None,
+        auth_token: str | None,
+    ) -> SdkConfig:
+        """Build config from explicit values, falling back to environment variables."""
+        return SdkConfig(
+            base_url=base_url or os.environ["ZAMP_BASE_URL"],
+            auth_token=auth_token or os.environ["ZAMP_AUTH_TOKEN"],
+        )
+
+    async def execute(
+        self,
+        action_name: str,
+        params: dict[str, Any],
+        *,
+        base_url: str | None = None,
+        auth_token: str | None = None,
+        summary: str | None = None,
+        return_type: type | None = None,
+        action_retry_policy: RetryPolicy | None = None,
+        action_start_to_close_timeout: timedelta | None = None,
+    ) -> Any:
+        config = self._resolve_config(base_url, auth_token)
+
+        return await self._execute_action(
+            action_name=action_name,
+            params=params,
+            config=config,
+            return_type=return_type,
+            summary=summary,
+            action_retry_policy=action_retry_policy,
+            action_start_to_close_timeout=action_start_to_close_timeout,
+        )
+
+    async def _execute_action(
+        self,
+        action_name: str,
+        params: dict[str, Any],
+        *,
+        config: SdkConfig,
+        return_type: type | None = None,
+        summary: str | None = None,
+        action_retry_policy: RetryPolicy | None = None,
+        action_start_to_close_timeout: timedelta | None = None,
+    ) -> Any:
+        """Post to ``{config.base_url}/actions`` and poll until a terminal state."""
+        client = HttpClient(
+            base_url=config.base_url,
+            default_headers={"Authorization": f"Bearer {config.auth_token}"},
+        )
+
+        body: dict = {
+            "action_name": action_name,
+            "params": params,
+            "is_external_action": True,
+        }
+        if summary is not None:
+            body["summary"] = summary
+        if action_retry_policy is not None:
+            body["retry_policy"] = action_retry_policy.model_dump(mode="json")
+        if action_start_to_close_timeout is not None:
+            body["start_to_close_timeout_seconds"] = action_start_to_close_timeout.total_seconds()
+
+        response = await client.post("/actions", data=body)
+        action_id = response["id"]
+        result = await self._poll_action_result(client, action_id)
+
+        if return_type and hasattr(return_type, "model_validate"):
+            return return_type.model_validate(result)
+        return result
+
+    @staticmethod
+    async def _poll_action_result(client: HttpClient, action_id: str) -> Any:
+        """Poll ``GET /actions/{id}`` with exponential backoff until a terminal state."""
+        interval = POLL_INITIAL_INTERVAL_SECONDS
+        elapsed = 0.0
+
+        while elapsed < POLL_TIMEOUT_SECONDS:
+            await asyncio.sleep(interval)
+            elapsed += interval
+
+            data = await client.get(f"/actions/{action_id}")
+            action_status = data["status"]
+
+            if action_status in SUCCESS_STATUSES:
+                return data.get("result")
+            if action_status in TERMINAL_FAILURE_STATUSES:
+                raise RuntimeError(f"Action {action_id} {action_status}: {data.get('error', 'unknown error')}")
+            if action_status not in IN_PROGRESS_STATUSES:
+                raise RuntimeError(f"Action {action_id} unexpected status: {action_status}")
+            interval = min(interval * 2, POLL_MAX_INTERVAL_SECONDS)
+
+        raise TimeoutError(f"Action {action_id} did not complete within {POLL_TIMEOUT_SECONDS}s")

zamp_sdk-0.0.2/zamp_sdk/action_executor/constants/__init__.py

@@ -0,0 +1,21 @@
+from zamp_sdk.action_executor.constants.polling import (
+    POLL_INITIAL_INTERVAL_SECONDS,
+    POLL_MAX_INTERVAL_SECONDS,
+    POLL_TIMEOUT_SECONDS,
+)
+from zamp_sdk.action_executor.constants.statuses import (
+    IN_PROGRESS_STATUSES,
+    SUCCESS_STATUSES,
+    TERMINAL_FAILURE_STATUSES,
+    ActionStatus,
+)
+
+__all__ = [
+    "ActionStatus",
+    "IN_PROGRESS_STATUSES",
+    "POLL_INITIAL_INTERVAL_SECONDS",
+    "POLL_MAX_INTERVAL_SECONDS",
+    "POLL_TIMEOUT_SECONDS",
+    "SUCCESS_STATUSES",
+    "TERMINAL_FAILURE_STATUSES",
+]

zamp_sdk-0.0.2/zamp_sdk/action_executor/constants/polling.py

@@ -0,0 +1,3 @@
+POLL_INITIAL_INTERVAL_SECONDS = 1.0
+POLL_MAX_INTERVAL_SECONDS = 30.0
+POLL_TIMEOUT_SECONDS = 600.0

zamp_sdk-0.0.2/zamp_sdk/action_executor/constants/statuses.py

@@ -0,0 +1,22 @@
+from enum import StrEnum
+
+
+class ActionStatus(StrEnum):
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELED = "CANCELED"
+    TERMINATED = "TERMINATED"
+    TIMED_OUT = "TIMED_OUT"
+
+
+SUCCESS_STATUSES = frozenset({ActionStatus.COMPLETED})
+TERMINAL_FAILURE_STATUSES = frozenset(
+    {
+        ActionStatus.FAILED,
+        ActionStatus.CANCELED,
+        ActionStatus.TERMINATED,
+        ActionStatus.TIMED_OUT,
+    }
+)
+IN_PROGRESS_STATUSES = frozenset({ActionStatus.RUNNING})

zamp_sdk-0.0.2/zamp_sdk/action_executor/models/__init__.py

@@ -0,0 +1,17 @@
+from zamp_sdk.action_executor.models.retry_policy import (
+    DEFAULT_RETRY_BACKOFF_COEFFICIENT,
+    DEFAULT_RETRY_INITIAL_INTERVAL,
+    DEFAULT_RETRY_MAXIMUM_ATTEMPTS,
+    DEFAULT_RETRY_MAXIMUM_INTERVAL,
+    RetryPolicy,
+)
+from zamp_sdk.action_executor.models.sdk_config import SdkConfig
+
+__all__ = [
+    "DEFAULT_RETRY_BACKOFF_COEFFICIENT",
+    "DEFAULT_RETRY_INITIAL_INTERVAL",
+    "DEFAULT_RETRY_MAXIMUM_ATTEMPTS",
+    "DEFAULT_RETRY_MAXIMUM_INTERVAL",
+    "RetryPolicy",
+    "SdkConfig",
+]

zamp_sdk-0.0.2/zamp_sdk/action_executor/models/retry_policy.py

@@ -0,0 +1,24 @@
+from datetime import timedelta
+
+from pydantic import BaseModel
+
+DEFAULT_RETRY_INITIAL_INTERVAL = timedelta(seconds=30)
+DEFAULT_RETRY_MAXIMUM_ATTEMPTS = 11
+DEFAULT_RETRY_MAXIMUM_INTERVAL = timedelta(minutes=15)
+DEFAULT_RETRY_BACKOFF_COEFFICIENT = 1.5
+
+
+class RetryPolicy(BaseModel):
+    initial_interval: timedelta
+    maximum_attempts: int
+    maximum_interval: timedelta
+    backoff_coefficient: float
+
+    @staticmethod
+    def default() -> "RetryPolicy":
+        return RetryPolicy(
+            initial_interval=DEFAULT_RETRY_INITIAL_INTERVAL,
+            maximum_attempts=DEFAULT_RETRY_MAXIMUM_ATTEMPTS,
+            maximum_interval=DEFAULT_RETRY_MAXIMUM_INTERVAL,
+            backoff_coefficient=DEFAULT_RETRY_BACKOFF_COEFFICIENT,
+        )

zamp_sdk-0.0.2/zamp_sdk/action_executor/models/sdk_config.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class SdkConfig(BaseModel):
+    """Resolved configuration for the Zamp API."""
+
+    base_url: str
+    auth_token: str

zamp_sdk-0.0.2/zamp_sdk/action_executor/tests/conftest.py

@@ -0,0 +1,11 @@
+import pytest
+
+
+@pytest.fixture
+def base_url():
+    return "https://api.zamp.test"
+
+
+@pytest.fixture
+def auth_token():
+    return "test-token-abc123"

zamp_sdk-0.0.2/zamp_sdk/action_executor/tests/test_action_executor.py

@@ -0,0 +1,287 @@
+from datetime import timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from zamp_sdk.action_executor.action_executor import ActionExecutor
+from zamp_sdk.action_executor.models import RetryPolicy, SdkConfig
+
+_MODULE = "zamp_sdk.action_executor.action_executor"
+
+
+class TestExecute:
+    """Tests for the public ActionExecutor.execute() entry point."""
+
+    def _executor(self) -> ActionExecutor:
+        return ActionExecutor()
+
+    async def test_explicit_config_forwarded(self, base_url, auth_token):
+        executor = self._executor()
+        with patch.object(executor, "_execute_action", new_callable=AsyncMock) as mock:
+            mock.return_value = {"result": "ok"}
+
+            result = await executor.execute(
+                "send_invoice",
+                {"id": "inv_1"},
+                base_url=base_url,
+                auth_token=auth_token,
+            )
+
+            assert result == {"result": "ok"}
+            call_kwargs = mock.call_args.kwargs
+            config = call_kwargs["config"]
+            assert isinstance(config, SdkConfig)
+            assert config.base_url == base_url
+            assert config.auth_token == auth_token
+
+    async def test_falls_back_to_env_vars(self, base_url, auth_token):
+        executor = self._executor()
+        env = {"ZAMP_BASE_URL": base_url, "ZAMP_AUTH_TOKEN": auth_token}
+        with (
+            patch.object(executor, "_execute_action", new_callable=AsyncMock) as mock,
+            patch.dict("os.environ", env, clear=False),
+        ):
+            mock.return_value = "done"
+            result = await executor.execute("my_action", {"k": "v"})
+
+            assert result == "done"
+            mock.assert_awaited_once()
+            config = mock.call_args.kwargs["config"]
+            assert config.base_url == base_url
+            assert config.auth_token == auth_token
+
+    async def test_raises_when_env_vars_missing(self):
+        executor = self._executor()
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            pytest.raises(KeyError, match="ZAMP_BASE_URL"),
+        ):
+            await executor.execute("action", {})
+
+    async def test_forwards_all_params(self, base_url, auth_token):
+        executor = self._executor()
+        retry = RetryPolicy.default()
+        timeout = timedelta(minutes=5)
+
+        with patch.object(executor, "_execute_action", new_callable=AsyncMock) as mock:
+            mock.return_value = None
+
+            await executor.execute(
+                "action",
+                {"x": 1},
+                base_url=base_url,
+                auth_token=auth_token,
+                summary="test summary",
+                return_type=dict,
+                action_retry_policy=retry,
+                action_start_to_close_timeout=timeout,
+            )
+
+            call_kwargs = mock.call_args.kwargs
+            assert call_kwargs["summary"] == "test summary"
+            assert call_kwargs["return_type"] is dict
+            assert call_kwargs["action_retry_policy"] is retry
+            assert call_kwargs["action_start_to_close_timeout"] == timeout
+
+    async def test_returns_result(self, base_url, auth_token):
+        executor = self._executor()
+        with patch.object(executor, "_execute_action", new_callable=AsyncMock) as mock:
+            mock.return_value = {"amount": 42}
+
+            result = await executor.execute(
+                "calc",
+                {},
+                base_url=base_url,
+                auth_token=auth_token,
+            )
+
+            assert result == {"amount": 42}
+
+
+class TestExecuteAction:
+    """Tests for the private ActionExecutor._execute_action() method."""
+
+    def _executor(self) -> ActionExecutor:
+        return ActionExecutor()
+
+    def _make_config(
+        self,
+        base_url: str = "https://api.zamp.test",
+        auth_token: str = "tok",
+    ) -> SdkConfig:
+        return SdkConfig(base_url=base_url, auth_token=auth_token)
+
+    async def test_builds_correct_post_body(self):
+        mock_client = AsyncMock()
+        mock_client.post.return_value = {"id": "action-123"}
+        mock_client.get.return_value = {"status": "COMPLETED", "result": {"ok": True}}
+
+        with patch(f"{_MODULE}.HttpClient", return_value=mock_client):
+            await self._executor()._execute_action(
+                action_name="send_email",
+                params={"to": "a@b.com"},
+                config=self._make_config(),
+            )
+
+            body = mock_client.post.call_args.kwargs["data"]
+            assert body["action_name"] == "send_email"
+            assert body["params"] == {"to": "a@b.com"}
+            assert body["is_external_action"] is True
+
+    async def test_includes_optional_fields(self):
+        mock_client = AsyncMock()
+        mock_client.post.return_value = {"id": "action-456"}
+        mock_client.get.return_value = {"status": "COMPLETED", "result": None}
+
+        retry = RetryPolicy.default()
+
+        with patch(f"{_MODULE}.HttpClient", return_value=mock_client):
+            await self._executor()._execute_action(
+                action_name="process",
+                params={},
+                config=self._make_config(),
+                summary="Test summary",
+                action_retry_policy=retry,
+                action_start_to_close_timeout=timedelta(minutes=10),
+            )
+
+            body = mock_client.post.call_args.kwargs["data"]
+            assert body["summary"] == "Test summary"
+            assert "retry_policy" in body
+            assert body["start_to_close_timeout_seconds"] == 600.0
+
+    async def test_polls_after_post(self):
+        mock_client = AsyncMock()
+        mock_client.post.return_value = {"id": "action-789"}
+        mock_client.get.return_value = {"status": "COMPLETED", "result": {"val": 1}}
+
+        with patch(f"{_MODULE}.HttpClient", return_value=mock_client):
+            result = await self._executor()._execute_action(
+                action_name="calc",
+                params={},
+                config=self._make_config(),
+            )
+
+            mock_client.get.assert_awaited()
+            assert result == {"val": 1}
+
+    async def test_uses_return_type_model_validate(self):
+        mock_client = AsyncMock()
+        mock_client.post.return_value = {"id": "action-abc"}
+        mock_client.get.return_value = {"status": "COMPLETED", "result": {"x": 1}}
+
+        mock_model = MagicMock()
+        mock_model.model_validate.return_value = "validated"
+
+        with patch(f"{_MODULE}.HttpClient", return_value=mock_client):
+            result = await self._executor()._execute_action(
+                action_name="typed",
+                params={},
+                config=self._make_config(),
+                return_type=mock_model,
+            )
+
+            mock_model.model_validate.assert_called_once_with({"x": 1})
+            assert result == "validated"
+
+    async def test_constructs_client_with_auth_header(self):
+        mock_client = AsyncMock()
+        mock_client.post.return_value = {"id": "action-xyz"}
+        mock_client.get.return_value = {"status": "COMPLETED", "result": None}
+
+        with patch(f"{_MODULE}.HttpClient", return_value=mock_client) as mock_cls:
+            await self._executor()._execute_action(
+                action_name="test",
+                params={},
+                config=self._make_config(
+                    base_url="https://api.zamp.test",
+                    auth_token="my-token",
+                ),
+            )
+
+            mock_cls.assert_called_once_with(
+                base_url="https://api.zamp.test",
+                default_headers={"Authorization": "Bearer my-token"},
+            )
+
+
+class TestPollActionResult:
+    """Tests for the private ActionExecutor._poll_action_result() method."""
+
+    def _executor(self) -> ActionExecutor:
+        return ActionExecutor()
+
+    async def test_returns_result_on_completed(self):
+        client = AsyncMock()
+        client.get.return_value = {"status": "COMPLETED", "result": {"data": 42}}
+
+        with patch(f"{_MODULE}.asyncio.sleep", new_callable=AsyncMock):
+            result = await self._executor()._poll_action_result(client, "action-1")
+
+        assert result == {"data": 42}
+
+    async def test_raises_on_failed(self):
+        client = AsyncMock()
+        client.get.return_value = {"status": "FAILED", "error": "boom"}
+
+        with (
+            patch(f"{_MODULE}.asyncio.sleep", new_callable=AsyncMock),
+            pytest.raises(RuntimeError, match="FAILED.*boom"),
+        ):
+            await self._executor()._poll_action_result(client, "action-2")
+
+    async def test_raises_on_canceled(self):
+        client = AsyncMock()
+        client.get.return_value = {"status": "CANCELED", "error": "cancelled"}
+
+        with (
+            patch(f"{_MODULE}.asyncio.sleep", new_callable=AsyncMock),
+            pytest.raises(RuntimeError, match="CANCELED"),
+        ):
+            await self._executor()._poll_action_result(client, "action-3")
+
+    async def test_raises_on_timed_out(self):
+        client = AsyncMock()
+        client.get.return_value = {"status": "TIMED_OUT", "error": "timeout"}
+
+        with (
+            patch(f"{_MODULE}.asyncio.sleep", new_callable=AsyncMock),
+            pytest.raises(RuntimeError, match="TIMED_OUT"),
+        ):
+            await self._executor()._poll_action_result(client, "action-4")
+
+    async def test_raises_timeout_error_when_poll_exceeds_limit(self):
+        client = AsyncMock()
+        client.get.return_value = {"status": "RUNNING"}
+
+        with (
+            patch(f"{_MODULE}.asyncio.sleep", new_callable=AsyncMock),
+            patch(f"{_MODULE}.POLL_TIMEOUT_SECONDS", 2.0),
+            patch(f"{_MODULE}.POLL_INITIAL_INTERVAL_SECONDS", 1.0),
+            pytest.raises(TimeoutError, match="did not complete"),
+        ):
+            await self._executor()._poll_action_result(client, "action-5")
+
+    async def test_polls_until_completed(self):
+        client = AsyncMock()
+        client.get.side_effect = [
+            {"status": "RUNNING"},
+            {"status": "RUNNING"},
+            {"status": "COMPLETED", "result": {"done": True}},
+        ]
+
+        with patch(f"{_MODULE}.asyncio.sleep", new_callable=AsyncMock):
+            result = await self._executor()._poll_action_result(client, "action-6")
+
+        assert result == {"done": True}
+        assert client.get.await_count == 3
+
+    async def test_raises_on_unexpected_status(self):
+        client = AsyncMock()
+        client.get.return_value = {"status": "UNKNOWN_STATE"}
+
+        with (
+            patch(f"{_MODULE}.asyncio.sleep", new_callable=AsyncMock),
+            pytest.raises(RuntimeError, match="unexpected status"),
+        ):
+            await self._executor()._poll_action_result(client, "action-7")

zamp_sdk-0.0.2/zamp_sdk/action_executor/tests/test_http_client.py

@@ -0,0 +1,149 @@
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from zamp_sdk.action_executor.utils import HttpClient, HttpClientError
+
+
+class TestHttpClientUrlBuilding:
+    def test_builds_url_with_base(self):
+        client = HttpClient(base_url="https://api.zamp.test")
+        assert client._build_url("/actions") == "https://api.zamp.test/actions"
+
+    def test_builds_url_strips_trailing_slash(self):
+        client = HttpClient(base_url="https://api.zamp.test/")
+        assert client._build_url("/actions") == "https://api.zamp.test/actions"
+
+    # If the input URL is already absolute, it should be returned as-is regardless of the base URL.
+    def test_builds_url_without_base(self):
+        client = HttpClient()
+        assert client._build_url("https://full.url/path") == "https://full.url/path"
+
+
+class TestHttpClientPost:
+    async def test_post_with_json_body(self):
+        client = HttpClient(base_url="https://api.zamp.test")
+        mock_response = AsyncMock()
+        mock_response.ok = True
+        mock_response.status = 200
+        mock_response.text = AsyncMock(return_value=json.dumps({"id": "123"}))
+
+        mock_session = AsyncMock()
+        mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_session.__aexit__ = AsyncMock(return_value=False)
+
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_response)
+        mock_ctx.__aexit__ = AsyncMock(return_value=False)
+        mock_session.request = MagicMock(return_value=mock_ctx)
+
+        with patch("aiohttp.ClientSession", return_value=mock_session):
+            result = await client.post("/actions", data={"name": "test"})
+
+        assert result == {"id": "123"}
+
+    async def test_post_raises_on_http_error(self):
+        client = HttpClient(base_url="https://api.zamp.test")
+        mock_response = AsyncMock()
+        mock_response.ok = False
+        mock_response.status = 500
+        mock_response.text = AsyncMock(return_value="Internal Server Error")
+
+        mock_session = AsyncMock()
+        mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_session.__aexit__ = AsyncMock(return_value=False)
+
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_response)
+        mock_ctx.__aexit__ = AsyncMock(return_value=False)
+        mock_session.request = MagicMock(return_value=mock_ctx)
+
+        with (
+            patch("aiohttp.ClientSession", return_value=mock_session),
+            pytest.raises(HttpClientError, match="HTTP 500"),
+        ):
+            await client.post("/actions", data={"name": "test"})
+
+
+class TestHttpClientGet:
+    async def test_get_without_body(self):
+        client = HttpClient(base_url="https://api.zamp.test")
+        mock_response = AsyncMock()
+        mock_response.ok = True
+        mock_response.status = 200
+        mock_response.text = AsyncMock(return_value=json.dumps({"status": "COMPLETED"}))
+
+        mock_session = AsyncMock()
+        mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_session.__aexit__ = AsyncMock(return_value=False)
+
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_response)
+        mock_ctx.__aexit__ = AsyncMock(return_value=False)
+        mock_session.request = MagicMock(return_value=mock_ctx)
+
+        with patch("aiohttp.ClientSession", return_value=mock_session):
+            result = await client.get("/actions/123")
+
+        assert result == {"status": "COMPLETED"}
+        call_kwargs = mock_session.request.call_args.kwargs
+        assert call_kwargs["data"] is None
+
+
+class TestHttpClientEnvelopeUnwrapping:
+    async def test_unwraps_data_envelope(self):
+        client = HttpClient(base_url="https://api.zamp.test")
+        envelope = {"data": {"payload": "inner"}, "error": None}
+        mock_response = AsyncMock()
+        mock_response.ok = True
+        mock_response.status = 200
+        mock_response.text = AsyncMock(return_value=json.dumps(envelope))
+
+        mock_session = AsyncMock()
+        mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_session.__aexit__ = AsyncMock(return_value=False)
+
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_response)
+        mock_ctx.__aexit__ = AsyncMock(return_value=False)
+        mock_session.request = MagicMock(return_value=mock_ctx)
+
+        with patch("aiohttp.ClientSession", return_value=mock_session):
+            result = await client.get("/test")
+
+        assert result == {"payload": {"payload": "inner"}}
+
+    async def test_raises_on_error_envelope(self):
+        client = HttpClient(base_url="https://api.zamp.test")
+        envelope = {"data": None, "error": {"message": "Not found"}}
+        mock_response = AsyncMock()
+        mock_response.ok = True
+        mock_response.status = 200
+        mock_response.text = AsyncMock(return_value=json.dumps(envelope))
+
+        mock_session = AsyncMock()
+        mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_session.__aexit__ = AsyncMock(return_value=False)
+
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_response)
+        mock_ctx.__aexit__ = AsyncMock(return_value=False)
+        mock_session.request = MagicMock(return_value=mock_ctx)
+
+        with (
+            patch("aiohttp.ClientSession", return_value=mock_session),
+            pytest.raises(HttpClientError, match="Not found"),
+        ):
+            await client.get("/test")
+
+
+class TestHttpClientErrorHandling:
+    async def test_timeout_raises_http_client_error(self):
+        client = HttpClient(base_url="https://api.zamp.test", timeout=1)
+
+        with (
+            patch("aiohttp.ClientSession", side_effect=TimeoutError("timed out")),
+            pytest.raises(HttpClientError, match="Request timed out"),
+        ):
+            await client.get("/test")

zamp_sdk-0.0.2/zamp_sdk/action_executor/tests/test_models.py

@@ -0,0 +1,41 @@
+from datetime import timedelta
+
+from zamp_sdk.action_executor.models import (
+    DEFAULT_RETRY_BACKOFF_COEFFICIENT,
+    DEFAULT_RETRY_INITIAL_INTERVAL,
+    DEFAULT_RETRY_MAXIMUM_ATTEMPTS,
+    DEFAULT_RETRY_MAXIMUM_INTERVAL,
+    RetryPolicy,
+)
+
+
+class TestRetryPolicy:
+    def test_fields(self):
+        rp = RetryPolicy(
+            initial_interval=timedelta(seconds=10),
+            maximum_attempts=5,
+            maximum_interval=timedelta(minutes=1),
+            backoff_coefficient=2.0,
+        )
+        assert rp.initial_interval == timedelta(seconds=10)
+        assert rp.maximum_attempts == 5
+        assert rp.maximum_interval == timedelta(minutes=1)
+        assert rp.backoff_coefficient == 2.0
+
+    def test_default_values(self):
+        rp = RetryPolicy.default()
+        assert rp.initial_interval == DEFAULT_RETRY_INITIAL_INTERVAL
+        assert rp.maximum_attempts == DEFAULT_RETRY_MAXIMUM_ATTEMPTS
+        assert rp.maximum_interval == DEFAULT_RETRY_MAXIMUM_INTERVAL
+        assert rp.backoff_coefficient == DEFAULT_RETRY_BACKOFF_COEFFICIENT
+
+    def test_serialization(self):
+        rp = RetryPolicy.default()
+        data = rp.model_dump(mode="json")
+        assert isinstance(data, dict)
+        assert "initial_interval" in data
+        assert "maximum_attempts" in data
+        assert "maximum_interval" in data
+        assert "backoff_coefficient" in data
+        assert data["maximum_attempts"] == DEFAULT_RETRY_MAXIMUM_ATTEMPTS
+        assert data["backoff_coefficient"] == DEFAULT_RETRY_BACKOFF_COEFFICIENT

zamp_sdk-0.0.2/zamp_sdk/action_executor/utils/__init__.py

@@ -0,0 +1,6 @@
+from zamp_sdk.action_executor.utils.http_client import HttpClient, HttpClientError
+
+__all__ = [
+    "HttpClient",
+    "HttpClientError",
+]

zamp_sdk-0.0.2/zamp_sdk/action_executor/utils/http_client.py

@@ -0,0 +1,130 @@
+import asyncio
+import json
+from typing import Any, Dict, NoReturn, Optional, Union
+
+import aiohttp
+import structlog
+from pydantic import BaseModel
+
+logger = structlog.get_logger(__name__)
+
+
+class HttpClientError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[str] = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+        super().__init__(self.message)
+
+
+class HttpClient:
+    """Lightweight async HTTP client for JSON API calls."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        default_headers: Optional[Dict[str, str]] = None,
+        timeout: int = 30,
+    ):
+        self.base_url = base_url
+        self.default_headers = default_headers or {}
+        self.timeout = timeout
+
+    def _build_url(self, endpoint: str) -> str:
+        if self.base_url:
+            return f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}"
+        return endpoint
+
+    def _handle_request_error(self, exc: Exception) -> NoReturn:
+        if isinstance(exc, HttpClientError):
+            raise exc
+        elif isinstance(exc, asyncio.TimeoutError):
+            raise HttpClientError(f"Request timed out: {exc}")
+        elif isinstance(exc, aiohttp.ClientError):
+            raise HttpClientError(f"Network error: {exc}")
+        else:
+            raise HttpClientError(f"Unexpected error: {exc}")
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        data: Optional[Union[Dict[str, Any], BaseModel]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> dict:
+        try:
+            request_headers = {**self.default_headers}
+            if headers:
+                request_headers.update(headers)
+
+            url = self._build_url(endpoint)
+
+            request_data = None
+            if data is not None:
+                if isinstance(data, BaseModel):
+                    request_data = data.model_dump_json()
+                else:
+                    request_data = json.dumps(data)
+                request_headers.setdefault("Content-Type", "application/json")
+
+            client_timeout = aiohttp.ClientTimeout(total=timeout or self.timeout)
+
+            logger.info("API request", method=method, url=url)
+
+            async with aiohttp.ClientSession(timeout=client_timeout) as session:
+                async with session.request(
+                    method=method,
+                    url=url,
+                    headers=request_headers,
+                    data=request_data,
+                ) as response:
+                    response_text = await response.text()
+
+                    if not response.ok:
+                        raise HttpClientError(
+                            f"HTTP {response.status} from {url}",
+                            status_code=response.status,
+                            response_body=response_text,
+                        )
+
+                    parsed: dict = json.loads(response_text)
+                    if isinstance(parsed, dict) and parsed.get("error") is not None:
+                        err = parsed["error"]
+                        msg = err.get("message", str(err)) if isinstance(err, dict) else str(err)
+                        raise HttpClientError(
+                            msg,
+                            status_code=response.status,
+                            response_body=response_text,
+                        )
+                    if isinstance(parsed, dict) and "data" in parsed and parsed.get("error") is None:
+                        return {"payload": parsed["data"]}
+                    return parsed
+
+        except Exception as e:
+            self._handle_request_error(e)
+
+    async def post(
+        self,
+        endpoint: str,
+        *,
+        data: Optional[Union[Dict[str, Any], BaseModel]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> dict:
+        return await self._request("POST", endpoint, data=data, headers=headers, timeout=timeout)
+
+    async def get(
+        self,
+        endpoint: str,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> dict:
+        return await self._request("GET", endpoint, headers=headers, timeout=timeout)